Hub Python Library documentation
huggingface_hub v1.0으로 마이그레이션
huggingface_hub v1.0으로 마이그레이션
v1.0 릴리스는 huggingface_hub 라이브러리의 주요 이정표입니다. 이는 API 안정성에 대한 우리의 약속과 라이브러리의 성숙도를 나타냅니다. 라이브러리를 더 견고하고 사용하기 쉽게 만들기 위해 여러 가지 개선 사항과 호환성이 깨지는 변경 사항을 적용했습니다.
이 가이드는 기존 코드를 새 버전으로 마이그레이션하는 데 도움을 주기 위해 작성되었습니다. 질문이나 피드백이 있으시면 GitHub에서 이슈를 열어 알려 주시기 바랍니다.
Python 3.9 이상
huggingface_hub는 이제 Python 3.9 이상이 필요합니다. Python 3.8은 더 이상 지원되지 않습니다.
HTTPX 마이그레이션
huggingface_hub 라이브러리는 이제 HTTP 요청에 requests 대신 httpx를 사용합니다. 이 변경은 성능을 개선하고 동기 및 비동기 요청을 동일한 방식으로 지원하기 위해 이루어졌습니다. 따라서 requests와 aiohttp 의존성을 모두 제거했습니다.
호환성 깨짐
이것은 라이브러리 전체에 영향을 미치는 주요 변경 사항입니다. 이 변경 사항을 최대한 투명하게 처리하려 노력했지만, 일부 경우 코드를 업데이트해야 할 수 있습니다. 이 과정에서 도입된 호환성 깨짐(breaking changes) 목록은 다음과 같습니다:
- 프록시 구성: “메서드별” 프록시는 더 이상 지원되지 않습니다. 프록시는
HTTP_PROXY및HTTPS_PROXY환경 변수를 사용하여 전역으로 구성해야 합니다. - 사용자 지정 HTTP 백엔드:
configure_http_backend함수가 제거되었습니다. 이제 set_client_factory()와 set_async_client_factory()를 사용하여 HTTP 클라이언트를 구성해야 합니다. - 오류 처리: HTTP 오류는 더 이상
requests.HTTPError에서 상속되지 않고httpx.HTTPError에서 상속됩니다.from huggingface_hub.utils import HfHubHTTPError로 가져오는 HfHubHTTPError를 catch하는 것을 권장합니다. 이 클래스는 v0.x에서는requests.HTTPError의 하위 클래스이고, v1.x에서는httpx.HTTPError의 하위 클래스입니다.huggingface_hub의 오류를 catch하면 라이브러리의 구버전과 신버전 모두와 호환되는 코드를 작성할 수 있습니다. - SSLError:
httpx에는SSLError라는 개념이 없습니다. 이제 일반적인httpx.ConnectError입니다. LocalEntryNotFoundError: 이 에러는 더 이상HTTPError를 상속하지 않습니다. 이제EntryNotFoundError(신규)를 정의했으며,LocalEntryNotFoundError(로컬 캐시에서 파일을 찾을 수 없는 경우)와RemoteEntryNotFoundError(Hub의 저장소에서 파일을 찾을 수 없는 경우)가 모두 이를 상속합니다. 원격 에러만HTTPError를 상속합니다.InferenceClient: 이제InferenceClient를 컨텍스트 매니저로 사용할 수 있습니다. 이는 언어 모델에서 토큰을 스트리밍할 때 연결이 올바르게 닫히도록 보장하는 데 특히 유용합니다.AsyncInferenceClient:AsyncInferenceClient생성자에서trust_env매개변수가 제거되었습니다.httpx는 기본적으로 환경 변수를 신뢰합니다. 환경을 명시적으로 신뢰하지 않으려면 set_async_client_factory()로 구성해야 합니다.
자세한 내용은 httpx를 도입한 PR #3328를 확인하세요.
왜 httpx 인가요?
requests에서 httpx로의 마이그레이션은 라이브러리의 성능, 신뢰성 및 유지보수성을 향상시키는 여러 가지 주요 개선 사항을 가져옵니다:
스레드 안전성 및 연결 재사용: httpx는 설계상 스레드 안전성을 제공하여 여러 스레드에서 동일한 클라이언트를 안전하게 재사용할 수 있습니다. 이러한 연결 재사용은 각 HTTP 요청마다 새 연결을 설정하는 오버헤드를 줄여, 특히 Hub에 대한 빈번한 요청 시 성능을 향상시킵니다.
HTTP/2 지원: httpx는 네이티브 HTTP/2 지원을 제공하며, 이는 동일한 서버에 여러 요청을 보내는 경우(우리의 사용 사례) 더 나은 효율성을 제공합니다. 이는 HTTP/1.1에 비해 지연 시간이 줄고 리소스 소비가 감소하는 것을 의미합니다.
통합 동기/비동기 API: 이전에는 동기용 requests와 비동기용 aiohttp라는 별개의 의존성을 사용했지만, httpx는 동일한 동작을 하는 동기 및 비동기 클라이언트를 모두 제공합니다. 이를 통해 InferenceClient와 AsyncInferenceClient의 기능이 일관되게 유지되며, 두 구현체 사이에 존재하던 미묘한 동작 차이를 제거합니다.
SSL 오류 처리 개선: httpx가 SSL 오류를 더 유연하게 처리하여 연결 문제를 디버깅하는 것이 더 쉽고 안정적으로 되었습니다.
미래 지향적인 아키텍처: httpx는 현대적인 Python 애플리케이션을 위해 설계되어 있으며 적극적으로 유지 관리되고 있습니다. 반면, requests는 유지 관리 모드에 있으며 스레드 안전성 개선이나 HTTP/2 지원과 같은 주요 업데이트를 받지 않습니다.
환경 변수 처리 개선: httpx는 동기 및 비동기 컨텍스트 모두에서 환경 변수를 더 일관되게 처리하여, requests는 기본적으로 로컬 환경 변수를 읽는 반면 aiohttp는 읽지 않던 기존 불일치를 제거합니다.
httpx로의 전환은 huggingface_hub에 현대적이고 효율적이며 유지보수가 용이한 HTTP 백엔드를 제공합니다. 대부분의 사용자는 매끄러운 작동을 경험할 수 있지만, 이러한 근본적인 개선 사항은 모든 Hub 상호작용에서 더 나은 성능과 안정성을 보장합니다.
hf_transfer
현재 Hub의 모든 저장소가 Xet을 지원하며 hf_xet가 파일을 다운로드/업로드하는 기본 방식이므로, hf_transfer 선택 패키지에 대한 지원이 제거되었습니다. 따라서 HF_HUB_ENABLE_HF_TRANSFER 환경 변수는 무시됩니다. 대신 HF_XET_HIGH_PERFORMANCE를 사용하세요.
Repository 클래스
Repository 클래스는 v1.0에서 제거되었습니다. 이 클래스는 저장소를 관리하기 위한 git CLI의 얇은 래퍼였습니다. 터미널에서 git를 직접 사용할 수는 있지만, 특히 대용량 파일을 다룰 때 더 원활한 경험을 위해 huggingface_hub 라이브러리의 HTTP 기반 API를 사용하는 것이 권장됩니다.
레거시 Repository 클래스에서 새로운 HfApi 클래스로의 매핑은 다음과 같습니다:
Repository 메서드 | HfApi 메서드 |
|---|---|
repo.clone_from | snapshot_download |
repo.git_add + git_commit + git_push | upload_file(), upload_folder(), create_commit() |
repo.git_tag | create_tag |
repo.git_branch | create_branch |
HfFolder 클래스
HfFolder는 사용자 액세스 토큰을 관리하는 데 사용되었습니다. login()을 사용하여 새 토큰을 저장하고, logout()을 사용하여 삭제하며, whoami()을 사용하여 현재 토큰에 연결된 사용자를 확인합니다. 마지막으로, 스크립트에서 사용자 토큰을 가져오려면 get_token()을 사용하세요.
InferenceApi 클래스
InferenceApi는 Inference API와 상호작용하기 위한 클래스였습니다. 이제 InferenceClient 클래스를 사용하는 것이 권장됩니다.
기타 비추천 기능
v1.0에서 일부 메서드와 파라미터가 제거되었습니다. 아래에 나열된 항목들은 v0.x에서 이미 경고 메시지와 함께 비권장(deprecated) 처리되었습니다.
constants.hf_cache_home는 제거되었습니다. 대신HF_HOME을 사용하세요.use_auth_token매개변수가 모든 메서드에서 제거되었습니다. 대신token을 사용하세요.get_token_permission메서드가 제거되었습니다.update_repo_visibility메서드는 제거되었습니다. 대신update_repo_settings를 사용하세요.is_write_action매개변수가build_hf_headers에서,write_permission가login에서 제거되었습니다. 세밀한 권한을 가진 토큰이 권장되는 방식으로 변경되었으므로, “쓰기 권한”이라는 개념은 더 이상 관련이 없습니다.login의new_session매개변수는 명확성을 높이기 위해skip_if_logged_in으로 이름이 변경되었습니다.resume_download,force_filename,local_dir_use_symlinks매개변수가hf_hub_download와snapshot_download에서 제거되었습니다.library,language,tags,task매개변수가list_models에서 제거되었습니다.
CLI 캐시 명령
CLI를 통한 캐시 관리가 Docker에서 영감을 받은 워크플로우를 따르도록 재설계되었습니다. 비권장된 huggingface-cli는 제거되었으며, hf(v0.34에서 도입됨)가 더 명확한 리소스-액션 CLI로 이를 대체합니다.
레거시 hf cache scan 및 hf cache delete 명령도 v1.0에서 제거되었으며, 아래에 있는 새로운 세 가지 명령으로 대체됩니다:
hf cache ls는 캐시 항목을 간결한 테이블, JSON 또는 CSV 형식으로 나열합니다. 개별 리비전을 확인하려면--revisions를 사용하고,size>1GB또는accessed>30d와 같은--filter표현식을 추가할 수 있습니다. 식별자만 필요한 경우--quiet와 함께 조합하여 사용하세요.hf cache rm은 선택된 캐시 항목을 삭제합니다. 하나 이상의 리포지토리 ID(예:model/bert-base-uncased) 또는 리비전 해시를 전달하고, 미리 보기를 위해--dry-run를 추가하거나 확인 프롬프트를 건너뛰기 위해--yes를 추가할 수 있습니다. 이는 이전 명령어의 인터랙티브 TUI 및--disable-tui워크플로를 모두 대체합니다.hf cache prune는 참조되지 않는 리비전을 한 번에 삭제하는 일반적인 정리 작업을 수행합니다.hf cache rm과 동일한 방식으로--dry-run또는--yes를 추가할 수 있습니다.
마지막으로, [cli] extra가 제거되었습니다. CLI는 이제 핵심 huggingface_hub 패키지에 포함되어 제공됩니다.
TensorFlow 및 Keras 2.x 지원
v1.0에서 TensorFlow 관련 코드 및 의존성이 모두 제거되었습니다. 이는 다음과 같은 호환성 깨짐(breaking changes)을 포함합니다:
huggingface_hub[tensorflow]는 더 이상 지원되는 추가 의존성이 아닙니다split_tf_state_dict_into_shards및get_tf_storage_size유틸리티 함수가 제거되었습니다.tensorflow,fastai,fastcore버전은 더 이상 내장 헤더에 포함되지 않습니다.
Keras 2.x 통합도 제거되었습니다. 여기에는 KerasModelHubMixin 클래스와 save_pretrained_keras, from_pretrained_keras, push_to_hub_keras 유틸리티가 포함됩니다. Keras 2.x는 더 이상 유지 관리되지 않는 레거시 라이브러리입니다. Hub와 긴밀하게 통합된 Keras 3.x를 사용하는 것이 권장됩니다(즉, Hub에 로드/푸시하는 내장 메서드를 포함합니다). 여전히 Keras 2.x를 사용해야 한다면 huggingface_hub를 v0.x 버전으로 다운그레이드해야 합니다.
upload_file 및 upload_folder 반환 값
upload_file() 및 upload_folder() 함수는 이제 Hub에서 생성된 커밋의 URL을 반환합니다. 이전에는 파일 또는 폴더의 URL을 반환했습니다. 이는 create_commit(), delete_file() 및 delete_folder()의 반환 값과 일치시키기 위한 것입니다.
Update on GitHub