리포지토리는 스냅샷이 아니라 트리다
모델 허브는 저장 모델을 git에게서 빌려 왔고, 그 상속은 겉치레 이상이야. 네가 북마크한 URL(owner/model)은 리포지토리를 가리키고, 기본적으로 그것을 읽을 때마다 main ref가 현재 가리키는 것 무엇이든로 해석돼. 저자는 정정을 push할 수 있고, 파일 포맷을 바꿀 수 있고, 네이티브 릴리스를 양자화판으로 교체할 수 있고, 리포를 통째로 비울 수도 있어. 오늘의 다운로드와 내년의 재다운로드 사이에, 그 주소는 두 개의 다른 객체를 서빙했을 수 있는 거야.
해결책은 git이 프로그래머들에게 주는 것과 같아: 커밋을 이름 붙이는 것. 리포지토리의 모든 상태는 revision sha(API가 sha로 보고하는 커밋 해시)로 주소 지정 가능해. URL + 고정된 revision은 얼어붙은 재현 가능한 객체를 가리키고, URL 혼자는 정책("현재 무엇이든")을 가리켜.
만나게 될 브랜치와 ref
main— 기본값. 움직이고, 편집 가능하고, 조용한 치환의 대상이야.- 이름 붙은 브랜치 — 변환 브랜치(FP32와 BF16 변형을 ref로 유지하는 리포), 유산 스냅샷, 스테이징 ref. 유용한 대안들이지. 항상 어느 ref를 읽었는지 기록해.
- PR ref — 아직 병합 안 된 커뮤니티 제안. 검사용으론 괜찮고 수집용으론 위험해: 리베이스로 사라질 수 있거든.
- 태그/릴리스 — 존재할 때는, 저자의 "이건 한 버전이다" 선언에 가장 가까운 것. 둘 다 있으면 맨 브랜치보다 태그를 택해.
샤딩은 이것과 얽혀 있어: 한 파일에 담기엔 너무 큰 모델은 model-00001-of-00003.safetensors 와 그 형제들, 그리고 텐서 이름을 샤드에 매핑하는 인덱스로 배포돼. 샤드 수는 스냅샷 정체성의 일부야 — 모든 텐서가 살아남더라도 3개 파일에서 2개로 재샤딩한 리포는 객체를 바꾼 거야. 수집 기록에는 revision뿐 아니라 파일 목록도 담아야 해.
핀을 습관으로 만들기
실용적인 의례는 수집 시점의 한 줄이야: 메타데이터 엔드포인트를 쿼리하고, sha를 사본 옆에 기록하고, 그때부터 네가 핀한 사본을 기준으로 다뤘 — URL을 다시 해석하는 건 "현재 것"을 의도적으로 원할 때만. 나중 쿼리가 다른 sha를 돌려주면, 그건 발밑에서 조용한 치환이 아니라 판단할 수 있는 사실이 되는 거야(저자가 뭘 개선했나? 포맷을 바꿨나? 라이선스를 고쳤나?).