huggingface_hub v1.0: 오픈 머신러닝의 기반 구축 5 년간의 여정

TL;DR: 5 년간의 개발 끝에

huggingface_hub

은 v1.0 에 도달했습니다. 이 마일스톤은 20 만 개의 의존 라이브러리를 구동하고, 200 만 개 이상의 공개 모델, 50 만 개 이상의 공개 데이터셋, 100 만 개 이상의 공개 Spaces 를 액세스하는 데 핵심 기능을 제공하는 Python 패키지의 성숙함을 표시합니다. 이 릴리스는 거의 300 명의 기여자와 수백만 명의 사용자가 주도하는 오픈 머신러닝의 다음 10 년을 지원하기 위해 설계된 breaking changes 를 포함합니다.

🚀 v1.0 으로 업그레이드를 강력히 권장하며, 주요 성능 개선과 새로운 기능을 누릴 수 있습니다.

pip install --upgrade huggingface_hub

이번 릴리스의 주요 변경 사항에는 httpx

로 백엔드 라이브러리로 마이그레이션, (구버전인 huggingface-cli 를 대체하는) Typer 기반 인터페이스와 크게 확장된 기능 세트를 갖춘 완전히 재설계된 hf CLI 가 포함되어 있습니다. 파일 전송을 위해 hf_xet 을 완전하게 채택하여 구버전인 hf_transfer 를 대체했습니다. 완전한 릴리스 노트는 여기에서 찾을 수 있습니다.

우리는 huggingface_hub
v1.0.0 이 후방 호환성을 유지하도록 노력했습니다. 실제로 대부분의 ML 라이브러리는 v0.x 와 v1.x 버전 모두와 원활하게 작동해야 합니다. 주요 예외는 transformers 로, 이는 v4 릴리스에서 명시적으로 huggingface_hub v0.x 를 요구하며, 다가오는 v5 릴리스에서 v1.x 를 요구합니다. 라이브러리별 상세한 호환성 개요를 확인하려면 이 이슈의 표를 참조하세요.

각 주요 라이브러리는 자신의 이야기를 가지고 있습니다. huggingface_hub 에서는 다음과 같은 간단한 아이디어로 시작했습니다: GitHub 에서 코드를 공유하는 것처럼 머신러닝 모델을 공유할 수 있다면 어떨까요?

Hugging Face Hub 의 초기에는 연구원과 실무자가 공통된 좌절에 직면했습니다. 최첨단 모델의 훈련은 상당한 컴퓨트 리소스와 전문성을 필요로 했습니다. 훈련된 후에는 이러한 모델들은 종종 고립되어 있으며, 로컬 머신에 저장되고 (파괴된) Google Drive 링크를 통해 공유되었습니다. AI 커뮤니티는 중복 작업을 하고, 자원을 낭비하며, 협력 기회를 놓치고 있었습니다.

Hugging Face Hub 는 이 문제에 대한 해답으로 등장했습니다. 초기에는 transformers 라이브러리와 호환되는 체크포인트를 공유하는 데 주로 사용되었습니다. Hub 와 상호 작용하기 위한 모든 Python 코드는 이 라이브러리 내에 존재하여 다른 라이브러리가 재사용할 수 없었습니다.

2020 년 말에 우리는 간단한 미션으로 huggingface_hub v0.0.1 을 출시했습니다: transformers 의 내부 논리를 추출하고 Hugging Face Hub 에서 머신러닝 모델과 데이터셋을 액세스 및 공유하는 방법을 통합할 전용 라이브러리를 생성합니다. 초기에는 이 라이브러리는 파일 다운로드와 저장소를 관리하기 위한 Git 래퍼만큼 단순했습니다. 5 년과 35 개 이상의 릴리스 이후, huggingface_hub 는 그 기원에 훨씬 더 발전했습니다.

그 여정을 추적해 보겠습니다.

초기 릴리스는 기본 기능을 확립했습니다. 버전 0.0.8 은 저장소와 상호 작용하기 위해 Git 명령어를 래핑하는 첫 번째 API 를 소개했습니다. 버전 0.0.17 은 개인 저장소 및 업로드에 대한 안전한 액세스를 가능하게 하는 토큰 기반 인증을 가져왔습니다. 이는 겸손한 시작이었지만, 이후 모든 것을 위한 기초를 마련했습니다.

2022 년 6 월, 버전 0.8.1 은 중요한 순간을 표시했습니다: 우리는 HTTP Commit API 를 소개했습니다. Git 및 Git LFS 설치 없이도 사용자는 이제 HTTP 요청을 통해 파일을 직접 업로드할 수 있습니다. 새로운 create_commit()

Git LFS 와 함께 사용하기에 번거로운 대형 모델 파일의 경우 특히 워크플로우를 크게 단순화했습니다. 또한 Git 감지 캐치 파일 레이아웃이 도입되었습니다. 모든 라이브러리 (transformers 만이 아니라, 세 번째 파티 라이브러리도 포함) 는 이제 명시적 버전 관리와 파일 중복 제거를 통해 동일한 캐치를 공유합니다.

이는 단순한 기술 개선이 아니었습니다. 철학적 전환이었습니다. 우리는 transformers 를 위한 Git 래퍼를 구축하는 것이 아니라, ML 생태계의 모든 라이브러리를 구동할 수 있는 머신 러닝 아티팩트를 위한 전용 인프라를 구축하고 있었습니다.

Hub 가 모델 저장소에서 완전한 플랫폼으로 성장함에 따라, huggingface_hub는 확장되는 API 표면과 함께 진행했습니다. 핵심 저장소 원형이 성숙되었습니다: 트리를 열거, 참조와 커밋을 브라우징, 파일 읽기 또는 폴더 동기화, 태그, 브랜치 및 릴리스 사이클 관리. 저장소 메타데이터와 웹훅은 팀이 실시간으로 변경 사항을 반응할 수 있도록 제공을 완성했습니다.

동시에, Hub 에서 직접 호스팅하고 공유하는 인터랙티브 ML 데모를 위한 단순하지만 강력한 방법인 Spaces 가 등장했습니다. 시간이 지남에 따라 huggingface_hub는 하드웨어 요청, 시크릿, 환경 구성, 업로드를 배포하고 관리할 수 있는 완전한 프로그램 제어력을 얻었습니다. 프로덕션 규모의 인프라에서 모델을 배포하기 위해 Inference Endpoints 를 통합했습니다. 마지막으로 Jobs API 는 컴퓨팅 제공을 완성하기 위해 나중에 (Q3 2025) 등장했습니다.

사회적 및 커뮤니티 레이어도 일류 시민이 되었습니다: 풀 리퀘스트와 코멘트 API 에서부터 사용자 및 조직 정보, 저장소 좋아요, 팔로우 및 팔로워를 거쳐 컬렉션에 이르기까지 관련 자원을 큐레이션하고 공유합니다. 일상적인 에르고닉스도 개선되었습니다: Colab 에서 원활한 인증, 재개할 수 있는 다운로드, 대규모 폴더의 신뢰성 있는 업로드 등.

그 다음에는 버전 0.28.0 과 Inference Providers 생태계가 등장했습니다. 단일 인퍼런스 백엔드 대신, 우리는 Together AI, SambaNova, Replicate, Cerebras, Groq 및 기타와 같은 여러 서버리스 제공업체와 파트너십을 맺어 하나의 API 를 투명한 라우팅으로 서비스합니다. 우리는 사람들이 실제로 어떻게 원하는지 맞춘 페이 퍼 리퀘스트 인퍼런스 아키텍처를 채택했습니다.

버전 0.30.0 은 Git 저장소에 대형 객체를 저장하는 획기적인 새로운 프로토콜인 Xet 을 소개했습니다. 파일 수준에서 중복 제거하는 Git LFS 와 달리, Xet 은 청크 수준 (64KB 청크) 에서 작동합니다. 데이터셋 또는 모델에서 대형 파일을 업데이트할 때, 전체 파일이 아닌 변경된 청크만 업로드되거나 다운로드됩니다.

이전에는 50 만 개 이상의 저장소에서 20 petabytes 를 시작하는 대규모 마이그레이션이었습니다. 그러나 이는 투명한 방식으로, 완전한 후방 호환성을 유지하며 발생했습니다. 한 년 후, 모든 **77PB+**의 6,000,000 저장소가 Xet 백엔드로 마이그레이션되어 훨씬 더 빠른 (그리고 더 똑똑한!) 업로드 및 다운로드를 허용합니다. 이는 사용자 개입 없이, 기존 워크플로우에 간섭 없이 발생했습니다 🔥

오픈 소스 라이브러리의 성장과 영향을 측정하는 것은 까다로운 과제입니다. 숫자는 그들의 이야기를 말합니다:

1 개월당 1 억 1 천 3 백 5 만 다운로드, 총 16 억 (2025 년 10 월).- 접근을 제공합니다.
**2M+**공공 모델, **500k+**공공 데이터셋, **1M+**공공 Spaces 및 약 두 배의 양은 사설 저장소를 계산할 때 -
사용자 **60k+**일마다 사용, **550k+**월간 -
트러스트를 받습니다.
200k+ 회사스타트업부터 Fortune 500 까지

하지만 실제 규모는 생태계를 볼 때 명확해집니다. huggingface_hub

GitHub 에서 20 만 개 이상의 저장소 와 PyPI 의 3,000 개의 패키지 를 위한 의존성 (dependency) 으로, Keras, LangChain, PaddleOCR, ChatTTS, YOLO, Google Generative AI, Moshi, NVIDIA NeMo, Open Sora 와 같은 주요 제 3 자 프레임워크부터 ML 경계 전반에 걸친 수많은 작은 라이브러리 및 도구에 이르기까지 모든 것을 구동합니다. 우리 자체 생태계 (transformers, diffusers, datasets, sentence-transformers, lighteval, gradio, peft, trl, smolagents, timm, lerobot 등) 도 이 기반을 통해 혜택을 받습니다.

놀라운 점은? 대부분의 제 3 자 통합은 우리가 어떤 역할을 하지 않은 채 자연적으로 이루어졌습니다. Hugging Face Hub 는 ML 커뮤니티를 다양한 방식으로 지원하지만, 그것이 얼마나 멀리 가고 널리 사용되고 있는지 보면 우리는 항상 겸손합니다.

버전 1.0 은 단지 마일스톤을 달성하는 것만이 아닙니다. 이는 다음 10 년의 오픈 소스 머신러닝을 위한 기반을 구축하는 것입니다. 우리가 만든 변경 사항 (breaking changes) 은 임의적인 것이 아니라, 수백만 명의 개발자가 의존하는 신뢰성을 유지하면서 AI 의 폭발적 성장을 확장할 수 있도록 위치시키는 전략적 결정입니다.

v1.0 의 가장 중요한 구조적 변화는 requests 에서 httpx 로의 마이그레이션입니다. 이는 단순한 의존성 교체 (dependency churn) 만이 아닙니다. HTTP 의 현대 시대로 라이브러리를 업그레이드하는 근본적인 개선입니다.

왜 httpx? 이점들은 상당합니다: 더 나은 연결 효율성을 위한 네이티브 HTTP/2 지원과 여러 스레드 사이에서 안전한 연결 재사용을 가능하게 하는 진정한 스레드 안전성 (thread safety). 가장 중요한 것은, httpx 가 동기 및 비동기 작업에 대한 통합 API 를 제공하여 기존 동기 및 비동기 추론 클라이언트 사이의 미묘한 동작 차이 (behavioral differences) 를 제거한다는 것입니다.

마이그레이션은 최대한 투명하게 설계되었습니다. 대부분의 사용자는 아무것도 변경할 필요가 없습니다. 커스텀 HTTP 백엔드를 가진 사용자들에게는 configure_http_backend() 에서 set_client_factory() 와 set_async_client_factory() 로 명확한 마이그레이션 경로를 제공했습니다.

또한, hf_xet 은 이제 Hub 로 파일 업로드 및 다운로드를 위한 기본 패키지가 되었고, 이전에 선택적 (optional) 이었던 hf_transfer 를 완전히 제거했습니다.

버전 0.32.0 은 모델 컨텍스트 프로토콜 (Model Context Protocol - MCP) 통합과 tiny-agents를 도입하여 개발자가 AI 에이전트를 구축하는 방식을 근본적으로 변화시켰습니다. 이제 복잡한 프레임워크 통합이 필요했던 것은 약 70 줄의 Python 코드만으로도 가능합니다.

MCPClient 는 AI 에이전트가 도구와 상호작용할 수 있는 표준화된 방법을 제공하며, tiny-agents CLI 는 Hub 에서 직접 에이전트를 실행할 수 있게 합니다. 로컬 또는 원격 MCP 서버에 연결하고, Gradio Space 를 도구로 사용하며, 자연스럽고 반응적인 대화형 에이전트를 구축할 수 있습니다.

이 모든 것은 기존 InferenceClient 와 그 수개의 추론 제공자 (Inference Providers) 위에 구축되었습니다. 우리는 에이전트가 미래라고 믿습니다. huggingface_hub 는 AI 빌더가 이를 실험할 수 있도록 구성 요소 (building blocks) 를 제공하는 데 있습니다.

CLI 는 단순한 명령줄 도구에서 ML 작업의 종합적인 인터페이스로 진화했습니다. 간소화된 hf 명령어는 레거시 huggingface-cli 를 현대적 리소스-액션 패턴으로 대체합니다:
hf auth login 을 인증에 사용
hf download 와 hf upload 를 파일 전송에 사용
hf repo 를 저장소 관리에 사용
hf cache ls 와 hf cache rm 을 캐시 관리에 사용
hf jobs run 을 클라우드 컴퓨팅에 사용

CLI 는 샌드박싱 설치기를 내장하여 기존 개발 환경을 깨뜨리지 않고 쉽게 업그레이드할 수 있습니다:

# macOS 또는 Linux
curl -LsSf https://hf.co/cli/install.sh | sh
# 또는 Windows
...

자동 완성 지원과 크로스 플랫폼으로 작동하는 설치기로 인해 CLI 는 이제 현대적인 개발 도구만큼 다듬어진 느낌을 줍니다.

버전 1.0 은 우리를 방해했던 레거시 패턴을 제거했습니다. Git 기반의 Repository 클래스는 사라졌습니다. HTTP 기반 방법인 upload_file()와 create_commit()은 더 단순하고, 신뢰성 있으며 현대적인 워크플로우에 더 적합해졌습니다. HfFolder 토큰 관리는 명시적인 login(), logout(), 및 get_token() 함수로 대체되었습니다. 오래된 InferenceApi 클래스는 기능 완결도가 더 높은 InferenceClient 로 대체되었습니다. hf_transfer 는 완전히 hf_xet 바이너리 패키지로 대체되었습니다.

이러한 변경은 경솔하게 이루어지지 않았습니다. 대부분의 폐기물은 명확한 경고와 마이그레이션 가이드를 함께 수 개월 전에 발표되었습니다. 그 결과, 폐기된 패턴을 지원하기보다 미래 지향적인 기능에 집중할 수 있는 더 깔끔하고 유지 가능한 코드베이스가 만들어졌습니다.

우리는 변경 사항이 파괴적임을 이해합니다. 이것이 바로 마이그레이션을 최대한 부드럽게 만들기 위해 많은 투자를 한 이유입니다. 우리의 종합 마이그레이션 가이드는 각 변경 사항에 대한 단계별 지침과 왜 각 변경 사항이 필요한지에 대한 설명을 제공합니다.

가장 중요한 것은 가능한 한 후방 호환성을 유지한 것입니다. 예를 들어, HfHubHttpError는 오래된 requests와 새로운 httpx 기본 HTTPError 클래스를 모두 상속하여 오류 처리가 버전 간에 계속 작동하도록 보장합니다.

이 릴리스로 우리는 미래를 완전히 약속하며 v1.0 및 그 이후에만 집중할 것이며, 커뮤니티가 Hugging Face Hub 와 상호작용하기 위해 필요한 성능과 기능 및 도구를 제공할 수 있도록 보장합니다. 이전 v0.* 버전을 PyPI 에서 사용할 수 있지만, 취약성 업데이트만 받을 것입니다.

우리는 huggingface_hub v1.0.0 이 후방 호환성을 유지하도록 최선을 다했습니다. 실제로 대부분의 ML 라이브러리는 v0.x 와 v1.x 버전과 원활하게 작동해야 합니다. 주요 예외는 transformers로, 이는 v4 릴리스에서 명시적으로 huggingface_hub v0.x 를 필요로 하며 v5 릴리스에서 v1.x 를 필요로 합니다. 라이브러리 간에 대한 상세 호환성 개요를 위해 이 이슈의 표를 참조하세요.

280+ 기여자 여러분에게 감사드립니다. 코드, 문서, 번역 및 커뮤니티 지원을 통해 이 라이브러리를 구축해 주셨습니다!

우리는 또한 이 라이브러리를 형성한 피드백, 버그 보고 및 제안에 대해 Hugging Face 커뮤니티 전체에게 깊은 감사를 표합니다.

마지막으로, huggingface_hub 를 워크플로우를 구동하는 데 신뢰해 주셔서 개인 개발자부터 대기업까지 사용자에게 큰 감사의 인사를 전합니다. 여러분의 지원은 우리가 계속 개선하고 혁신하도록 동기를 부여합니다.

GitHub 에서 별을 찍어주세요 ⭐. 여러분의 지원을 보여주고 오픈 머신 러닝의 기반을 계속 구축하는 데 도움을 주세요. 5 년이 지났지만 아직 시작일 뿐입니다!