LFS 포인터와 허브 다이제스트

clone하는 리포와 download하는 리포가 다른 이유

git은 텍스트를 추적하도록 지어졌어. 기가바이트 단위 텐서는 모든 clone과 모든 diff를 재앙으로 만들으니, 모델 허브는 Git LFS를 덧붙여: 리포지토리 본체는 각 큰 아티팩트에 대한 조그만 포인터 파일을 저장하고, 진짜 바이트는 허브 뒤의 콘텐츠 주소 저장소에 살아. clone하면 포인터를 받고, 허브의 파일 엔드포인트로 내려받으면 진짜 파일을 받아.

그 아키텍처가 다이제스트를 정확히 기록관이 필요한 곳에 놓아. 포인터 파일은 서너 줄이야:

version https://git-lfs.github.com/spec/v1
oid sha256:<16진 64 문자> — 진짜 바이트의 SHA-256
size <바이트> — 진짜 파일의 실제 크기

oid 줄이 네 다이제스트 계약의 참조 쪽이야, 파일이 업로드된 순간 플랫폼이 공개한. 다운로드 뒤의 shasum -a 256이 비교해야 할 대상이지 — README를 믿는 게 아니라.

clone 없이 참조 얻기

다이제스트를 알려고 14 GB 리포를 clone할 필요는 없어. 허브의 raw 파일 엔드포인트가 포인터 파일 자체를 서빙하고(그게 작으니까 — 그게 요점이지), API의 파일 트리 목록이 파일마다 LFS 다이제스트와 크기를 실어 와. 어느 경로든 검증 목표를 몇 초 안에 줘 — 어떤 전송에든 저지르기 전에. size 필드도 주목해: 그게 첫 번째이자 가장 싼 점검이야 — 잘못된 크기에서 끝난 다운로드는 이미 실패한 거야, 해싱도 필요 없이.

체화할 만한 섬세함 하나: 다이제스트는 blob에 대해 계산되고, 파일명이나 경로와 무관해. 파일명을 바꾸거나 디렉토리 사이를 옮기는 건 다이제스트를 안 바꿔. 한 바이트를 고치면 바꾸지. 이래서 다른 이름, 다른 레이아웃의 사본을 검증할 수 있는 거야 — 정체성은 경로가 아니라 바이트에 살아.

포인터 파일은 공짜 증명서다. LFS 기반 리포의 모든 큰 파일은 플랫폼이 공개한 SHA-256과 실제 크기를 달고 나와. 받기 전에 모으고, 받은 뒤에 그것들과 검증해.

조립된 워크플로

정찰이 포인터를 읽고, 수집이 바이트를 옮기고, 검증이 고리를 닫아: 포인터(또는 API 기록)를 가져오고, 진짜 파일을 내려받고, 로컬에서 SHA-256을 재계산하고, 비교하고, 두 다이제스트를 수집 노트에 기록해. 그 단계들 중 셋은 이 트랙에서 이미 아는 명령들이고, 이 레슨의 기여는 참조가 어디서 오는지 아는 것뿐 — 그게 검증을 의례에서 점검으로 바꿔.

Code

참조 다이제스트 당긴 뒤 그것으로 검증·bash

REPO=<org>/<model>
F=model-00001-of-00003.safetensors

# 1) 포인터 파일 자체 — 작고, 즉시
curl -s "https://huggingface.co/$REPO/raw/main/$F"
# version https://git-lfs.github.com/spec/v1
# oid sha256:3f2a9b...        <- 참조 다이제스트
# size 4920320256             <- 실제 바이트 크기

# 2) 또는 API로 LFS 다이제스트 포함 전체 트리:
curl -s "https://huggingface.co/api/models/$REPO/tree/main?recursive=true" \
  | python3 -c "
import json, sys
for f in json.load(sys.stdin):
    lfs = f.get('lfs') or {}
    if lfs: print(f['path'], lfs['oid'], lfs['size'])"

# 3) 다운로드 뒤 — 계약이 약속한 비교:
shasum -a 256 $F   # 1단계의 oid와 같아야 해
stat -f%z $F       # 1단계의 size와 같아야 해 (macOS; Linux는 %s)

Exercise

수집할 예정인 리포 하나에 대해: 큰 파일 전부의 포인터 파일(또는 API LFS 기록)을 references 파일로 당겨 와 — 경로, oid, size, 한 줄에 하나. 그 리포에서 무엇이든 내려받은 뒤 비교를 돌려. 로컬 다이제스트나 크기가 참조와 어긋나는 파일이 있으면 보고하고, 그걸 어떻게 할지 적어.

Hint

references 파일을 수집 옆에 두워 — 동시에 검증 목표이자 출처 기록이야. 불일치는 재다운로드가 먼저야(일시적 손상이 상류 변조보다 흔해), 반복되면 조사해.

clone하는 리포와 download하는 리포가 다른 이유

clone 없이 참조 얻기

조립된 워크플로

Code

External links

Exercise

Progress

댓글 0