Hub 에서 Git LFS 를 Xet 으로 마이그레이션하기

오늘 Hub 는 100 만 명 이상의 사용자가 Xet 을 사용하고 있습니다. 5 월에 Hub 의 새 사용자 및 조직을 위한 기본 설정으로 지정되었습니다. GitHub 이슈, 포럼 게시글, Discord 메시지가 몇 dozen 개뿐인 것으로, 이는 아마도 가장 조용한 대규모 마이그레이션 중 하나일 것입니다.

어떻게? 첫째로, 팀은 시스템의 기반을 제공하는 내용 저장소 (CAS) 와 Rust 클라이언트를 구축하고 지원하는 데 수년의 경험을 가지고 준비했습니다. 이 부분들을 없애면 Git LFS 는 여전히 Hub 의 미래가 될 수 있습니다. 그러나 이 마이그레이션의 숨겨진 영웅들은 다음과 같습니다:

• 내부적으로 Git LFS Bridge 로 알려진 필수 인프라 구성 요소
• 일주일에 24 시간 작동하는 배경 내용 마이그레이션

이러한 구성 요소는 Hub 나 커뮤니티에 영향을 주지 않고 PB 단위를 수일 만에 공격적으로 마이그레이션할 수 있게 했습니다. 향후 몇 주와 달 (끝으로 넘어가기 👇) 에 더 빠르게 이동할 수 있는 마음의 평화를 줍니다.

Xet 로의 마이그레이션을 계획하는 초기 단계에서 우리는 몇 가지 핵심 설계 결정을 내렸습니다:

• Git LFS 에서 Xet 으로 "강력한 컷오프"가 없어야 합니다
• Xet 을 지원하는 저장소는 Xet 과 LFS 파일을 모두 포함할 수 있어야 합니다
• LFS 에서 Xet 로의 저장소 마이그레이션은 "잠금"이 필요하지 않습니다; 즉, 다운로드 또는 업로드를 방해하지 않고 배경에서 실행될 수 있습니다

우리의 커뮤니티에 대한 헌신으로 인해 이러한 명백한 단순한 결정은 상당한 영향을 미쳤습니다. 가장 중요한 것은 사용자와 팀이 Xet 을 지원하는 저장소와 상호 작용하기 위해 즉시 워크플로우를 변경하거나 새 클라이언트를 다운로드해야 한다는 믿음이 없었습니다.

Xet 의식이 있는 클라이언트 (예: hf-xet 및 huggingface_hub 의 Xet 통합) 를 사용한다면, 업로드와 다운로드가 전체 Xet 스택을 통과합니다. 클라이언트는 업로드 시 콘텐츠 정의 쉐이크를 사용하여 파일을 조각으로 나누거나, 다운로드 시 파일 재구성 정보를 요청합니다. 업로드 시에는 조각이 CAS 로 전달되어 S3 에 저장됩니다. 다운로드 중에는 CAS 가 클라이언트가 S3 에서 파일을 재구성하기 위해 필요한 조각 범위를 제공합니다.

huggingface_hub 또는 huggingface.js 의 이전 버전은 쉐이크 기반 파일 전송을 지원하지 않지만, Xet 저장소에 여전히 업로드하고 다운로드할 수 있습니다. 이 바이트는 다른 경로를 취합니다. Hub 의 resolve 엔드포인트를 따라 Xet 백업 파일을 요청하면 Git LFS Bridge 가 단일 presigned URL 을 구성하여 반환하며 LFS 프로토콜을 모방합니다. Bridge 는 S3 에서 보관된 콘텐츠를 사용하여 파일을 재구성하고 요청자에게 반환합니다.

이를 확인하려면 위의 이미지를 마우스 오른쪽 버튼으로 클릭하여 새 탭에서 열 수 있습니다. URL 은 https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/migrating-the-hub-to-xet/bridge.png 에서 시작하며 https://cas-bridge.xethub.hf.co/xet-bridge-us/... 로 시작합니다. 또한 같은 URL 에 curl -vL 을 사용하여 터미널에서 리디렉션 사항을 볼 수 있습니다.

동시에, Xet 의식이 없는 클라이언트가 파일을 업로드하면 먼저 LFS 저장소에 전송된 후 Xet 으로 마이그레이션됩니다. 이 "배경 마이그레이션 프로세스"는 문서에서 간략히 언급되었지만, Xet 로의 마이그레이션과 업로드 백워드 호환성을 모두 구동합니다. 잘 넘는 수십 PB 의 모델 및 데이터셋 마이그레이션 뒤에 있으며, 50 만 개의 저장소를 Xet 저장소와 동기화하고 있습니다.

LFS 에서 Xet 로 파일을 이관할 때마다 웹훅 (webhook) 이 트리거되어 이벤트가 분산 큐로 푸시되며, 오케스트레이터 (orchestrator) 가 이를 처리합니다. 오케스트레이터는 다음과 같은 작업을 수행합니다:

• 이벤트에 따라 해당 레포지토리에 Xet 을 활성화합니다.
• 레포지토리의 모든 LFS 파일의 LFS 수정 목록을 가져옵니다.
• 파일 크거나 파일 수를 기준으로 파일을 작업으로 배치하며, 1000 개 파일 또는 500MB 가 먼저 도달하는 것을 기준으로 배치합니다.
• 작업을 이관 작업 포드 (migration worker pods) 를 위한 다른 큐에 배치합니다.

이러한 이관 작업 포드는 다음 작업을 수행하고 각 포드는:

• 배치에서 나열된 LFS 파일을 다운로드합니다.
• xet-core 를 사용하여 LFS 파일을 Xet 콘텐츠 주소형 저장소로 업로드합니다.

4 월에 우리는 Bartowski 와 연락하여 Xet 을 테스트해 보기를 원하지 않는지 물으며 이 시스템의 한계를 테스트했습니다. 2,000 개의 레포지토리에 걸쳐 거의 500TB 를 가진 Bartowski 의 이관은 몇 가지 약점을 드러냈습니다:

• 전역 중복 제거용 임시 샤드 파일은 먼저 /tmp 에 작성된 후 샤드 캐시 (shard cache) 로 이동되었습니다. 그러나 우리 작업 포드에서 /tmp 와 Xet 캐시는 다른 마운트 포인트에 위치했습니다. 이동이 실패하여 샤드 파일은 결코 삭제되지 않았습니다. 결국 디스크가 가득 차 No space left on device 오류를 유발하는 오류 파동을 일으켰습니다.
• Llama 4 출시를 지원하기 위해 CAS 를 버스트 다운로드에 확장했지만, 수백 개의 다중 GB 업로드가 CAS 의 자원을 초과하여 이관 작업 포드가 상황을 뒤집었습니다.
• 이론적으로 이관 작업 포드는 보고된 성능보다 훨씬 높은 트래픽 처리 능력을 가졌으나, 포드 프로파일링은 네트워크 및 EBS I/O 병목 현상을 드러냈습니다.

이 세 가지 머리를 가진 괴물을 고치는 것은 모든 레이어를 만져야 함을 의미합니다: xet-core 를 패치하고 CAS 를 리사이징하며 작업 노드 사양을 강화해야 합니다. 행운에, 모든 레포지토리가 Xet 으로 이동하는 동안 Bartowski 는 우리와 함께 일할 준비가 되어 있었습니다. 이러한 교훈은 Hub 의 가장 큰 저장 사용자들 (Richard Erkhov: 1.7PB 와 25,000 개 레포지토리, mradermacher: 6.1PB 와 42,000 개 레포지토리 🤯) 의 이동에도 적용되었습니다.

CAS 트래픽은 첫 번째 대규모 이관부터 최신 대규모 이관에 걸쳐 10 배 증가했습니다:

Bartowski 이관: CAS 는 ~35 Gb/s 의 지속 트래픽을 유지하며, 약 5 Gb/s 는 일반적인 Hub 트래픽에서 비롯되었습니다.
mradermacher 와 Richard Erkhov 이관: CAS 는 약 300 Gb/s 까지 도달했으며, 여전히 약 40 Gb/s 의 일상 트래픽을 서비스했습니다.

LFS 를 교체할 때 우리는 두 가지 목표를 가지고 있었습니다:

• 해를 입히지 않기 (Do no harm)
• 가능한 한 빠르게 가장 큰 영향을 미치기 (Drive the most impact as fast as possible)

초기 제약 조건과 이러한 목표에 기반하여 설계함으로써 우리는 다음을 달성했습니다:

• hf-xet 를 도입하고 강화한 후, 이를 huggingface_hub 에 필수 의존성으로 포함하기 전에 커뮤니티가 Xet 활성화된 레포지토리에 업로드하고 다운로드할 수 있도록 지원 - 현재 사용하는 모든 방법으로 Xet 활성화된 레포지토리에 업로드하고 다운로드하며 인프라가 나머지를 처리합니다.
• 규모부터 분산 파일 시스템에서 클라이언트가 어떻게 작동하는지에 이르기까지 귀중한 교훈을 배웠습니다 - Hub 를 Xet 으로 점진적으로 이관함으로써

모든 업로드 경로가 Xet 을 인식할 때까지 기다리기보다, 하드 컷오버 (hard cut-over) 를 강제하거나 커뮤니티를 특정 워크플로우를 채택하도록 강요하는 대신, 최소 사용자 영향을 받으며 Hub 를 즉시 Xet 으로 이관할 수 있었습니다. 간단히 말해, 팀이 워크플로우를 유지하고 인프라가 장기적인 통합 저장 시스템 목표에 지원하며 유기적으로 Xet 으로 전환되도록 합니다.

1 월과 2 월에 우리는 피드백 제공 및 인프라 압력 테스트를 위해 파워 사용자를 온보딩했습니다. 커뮤니티 피드백을 얻기 위해 Xet 활성화된 레포지토리를 미리보기하기 위한 웨이트리스트 (waitlist) 를 출시했습니다. 곧 Xet 은 Hub 의 새로운 사용자들을 위한 기본값이 되었습니다.

현재 우리는 Hub 에서 가장 큰 크리에이터들 중 일부 (Meta Llama, Google, OpenAI, Qwen) 를 지원하면서 커뮤니티는 중단 없이 계속 작업하고 있습니다.

다음으로?

이번 달부터 Xet 을 모두에게 제공하기 시작합니다. Xet 에 대한 액세스를 제공하는 이메일을 기다리시고, 이를 받으시면 최신 huggingface_hub (
pip install -U huggingface_hub
) 를 업데이트하여 즉시 더 빠른 전송을 해제하세요. 이는 또한 다음과 같은 것을 의미합니다:

• 모든 기존 레포지토리는 LFS 에서 Xet 로 마이그레이션됩니다.
• 새로 생성된 모든 레포지토리는 기본적으로 Xet 을 지원합니다.

브라우저를 사용하여 Hub 에서 업로드하거나 다운로드하거나 Git 을 사용하는 경우, 괜찮습니다. 두 가지 모두에 대한 Chunk-based 지원이 곧 제공됩니다. meantime 에는 이미 가지고 있는 워크플로우 중 하나를 사용하세요; 제한은 없습니다.

다음으로: Xet 프로토콜과 전체 인프라 스택을 오픈소스로 공개합니다. AI 워크로드까지 확장되는 바이트 저장 및 이동의 미래는 Hub 에서 있으며, 우리는 이를 모두에게 가져오려는 목표입니다.

질문이 있으시면 댓글에 드려주세요 👇, Xet team 페이지에서 discussion를 열기세요.