huggingface_hub v1.0: 오픈 머신러닝의 기반을 다진 5년

TL;DR: 5년간의 개발 끝에, huggingface_hub은 v1.0에 도달했으며, 이는 200,000개의 의존 라이브러리를 구동하는 파이썬 패키지로서 라이브러리의 성숙도를 나타내는 이정표입니다. 2백만 개 이상의 공개 모델, 50만 개의 공개 데이터셋, 1백만 개의 공개 Spaces에 대한 핵심 기능에 접근할 수 있도록 제공합니다. 이 릴리스는 거의 300명의 글로벌 기여자와 수백만 명의 사용자에 의해 이끌리는 다음 10년의 오픈 머신러닝을 지원하기 위해 설계된 중단 변경을 도입합니다.

🚀 주요 성능 향상과 새로운 기능을 누리기 위해 v1.0으로 업그레이드하는 것을 강력히 권장합니다.

라이브러리의 이야기

이 라이브러리는 2020년 간단한 Git 래퍼에서 시작하여 5년 동안 허깅페이스 허브를 구동하는 성숙한 기반으로 발전했습니다.

기초 연도 (2020-2021)

초기 릴리스에서는 기본 사항이 확립되었습니다: 버전 0.0.8은 Git 명령을 래핑한 첫 번째 API를 도입했으며, 버전 0.0.17은 비공개 리포지토리와 업로드를 위한 토큰 기반 인증을 추가했습니다.

큰 변화: Git에서 HTTP로 (2022)

2022년 6월, 버전 0.8.1은 HTTP Commit API를 도입하여 Git LFS 없이 HTTP를 통한 파일 업로드를 가능하게 했으며, 라이브러리 간에 공유되는 git 인식 캐시 레이아웃을 추가했습니다.

확장되는 API 표면 (2022–2024)

허브가 성장함에 따라, 라이브러리는 리포지토리 메타데이터, 웹훅, Spaces 관리, Inference Endpoints, Jobs API, 풀 요청 및 댓글과 같은 커뮤니티 기능, 그리고 요청당 과금형 추론을 위한 Inference Providers용 프리미티브를 추가했습니다.

준비. Xet. Go! (2024-2025)

버전 0.30.0은 청크 수준 저장 프로토콜인 Xet을 도입했으며, 마이그레이션은 6,000,000개 이상의 리포지토리에 걸쳐 77PB+을 투명하게 이동시켜 더 빠른 업로드와 다운로드를 가능하게 했습니다.

성장과 영향 측정

이제 라이브러리는 대규모 채택을 보이며, 수백만 개의 모델을 구동하고 수만 명의 사용자와 기업에 의해 사용됩니다.

  • 월간 다운로드 1억 1350만 회, 총 16억 회 (2025년 10월).
  • 2백만+ 공개 모델, 500k+ 공개 데이터셋, 1백만+ 공개 Spaces에 대한 접근을 제공합니다 (개인 복사본 포함).
  • 일일 사용자 60k+, 월간 사용자 550k+에 의해 사용됩니다.
  • 스타트업부터 포춘 500까지 200k+ 기업에서 신뢰받고 있습니다.
  • 200,000개 이상의 GitHub 리포지토리와 3,000개의 PyPI 패키지에 의존성이 있으며, Keras, LangChain, PaddleOCR, ChatTTS, YOLO, Google Generative AI, Moshi, NVIDIA NeMo, Open Sora와 같은 주요 프레임워크를 포함합니다.
  • 거의 300명의 기여자에 의해 구축되었습니다.

다음 10년을 위한 구축

버전 1.0은 다음 10년을 위해 라이브러리를 확장하기 위한 전략적인 중단 변경을 도입합니다.

httpx와 hf_xet을 사용한 현대적인 HTTP 인프라

httpx로의 마이그레이션과 기본 hf_xet 사용은 성능, 스레드 안전성, 비동기 지원을 향상시킵니다.

  • httpx가 requests를 대체하여 네이티브 HTTP/2, 진정한 스레드 안전성, 그리고 통합된 동기/비동기 API를 제공합니다.
  • hf_xet은 이제 파일 전송의 기본 패키지가 되었으며, 선택 사항이었던 hf_transfer를 대체합니다.
  • 커스텀 HTTP 백엔드는 configure_http_backend()에서 set_client_factory()와 set_async_client_factory()로 마이그레이션할 수 있습니다.

MCP와 Tiny-Agents로 간소화된 에이전트

MCP 통합과 tiny-agents를 통해 개발자는 약 70줄의 파이썬 코드로 AI 에이전트를 구축할 수 있습니다.

  • MCPClient는 에이전트가 도구와 상호작용할 수 있는 표준화된 방법을 제공합니다.
  • tiny-agents CLI는 허브에서 직접 에이전트를 실행하며, 로컬 또는 원격 MCP 서버에 연결하고 어떤 Gradio Space든 도구로 사용합니다.
  • 기존 InferenceClient 및 수십 개의 Inference Providers 지원을 기반으로 구축되었습니다.

현대적인 워크플로를 위한 풀-피처드 CLI

재설계된 hf CLI는 Typer 기반 인터페이스로 huggingface-cli를 대체하며, 인증, 전송, 리포지토리 관리, 캐시, 작업을 포괄합니다.

  • hf auth login은 인증을 위해 사용됩니다.
  • hf download 및 hf upload는 파일 전송을 위해 사용됩니다.
  • hf repo는 리포지토리 관리를 위해 사용됩니다.
  • hf cache ls 및 hf cache rm은 캐시 관리를 위해 사용됩니다.
  • hf jobs run은 클라우드 컴퓨팅을 위해 사용됩니다.
  • Platform‑agnostic installer:
    # macOS or Linux
curl -LsSf https://hf.co/cli/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

미래를 위한 정리

코드베이스를 간소화하고 미래 지향적인 기능에 집중하기 위해 레거시 클래스와 패턴이 제거되었습니다.

  • Git 기반 Repository 클래스가 제거되었으며, upload_file()과 create_commit() 같은 HTTP 기반 메서드가 이제 표준입니다.
  • 토큰 관리가 HfFolder에서 명시적인 login(), logout(), get_token() 함수로 이동했습니다.
  • 이전 InferenceApi 클래스는 더 기능이 완전한 InferenceClient로 대체되었습니다.
  • hf_transfer은 hf_xet 바이너리 패키지로 완전히 대체되었습니다.
  • 대부분의 사용 중단 사전 공고는 수개월 전에 경고와 마이그레이션 가이드와 함께 발표되었습니다.

마이그레이션 가이드

포괄적인 마이그레이션 가이드가 업그레이드를 용이하게 하며, transformers v5를 제외한 대부분의 라이브러리에 대해 하위 호환성이 유지됩니다.

  • 이 가이드는 각 변경에 대한 단계별 지침을 제공하고 왜 각 변경이 필요한지 설명합니다.
  • 가능한 경우 하위 호환성이 유지됩니다; 예를 들어, HfHubHttpError는 이전 requests와 새로운 httpx 기본 HTTPError 클래스 둘 다를 상속합니다.
  • 이전 v0.* 버전은 취약점 업데이트를 위해서만 PyPI에 남아 있으며, 개발은 v1.0 및 이후에 집중됩니다.
  • 주요 예외는 transformers이며, 이는 v4 릴리스에 huggingface_hub v0.x가 필요하고 upcoming v5 릴리스에 v1.x가 필요합니다 (issue #3340의 호환성 표 참조).

인정

기여자, 커뮤니티, 사용자에게 감사드립니다.

  • 280명 이상의 기여자가 코드, 문서, 번역, 커뮤니티 지원을 통해 라이브러리를 구축했습니다.
  • 더 넓은 허깅페이스 커뮤니티가 피드백, 버그 보고, 제안을 제공했습니다.
  • 개별 개발자부터 대기업까지의 사용자는 huggingface_hub이 그들의 워크플로를 구동한다고 신뢰합니다.

Sources