HuggingFace Hub의 루트 로거에 대한 현재 레벨을 반환합니다.

HuggingFace Hub에는 다음과 같은 로깅 레벨이 있습니다:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

HuggingFace Hub의 루트 로거 수준을 설정합니다.

로그 수준을 logging.INFO(으)로 설정합니다.

logging.DEBUG로 로그 수준을 설정합니다.

logging.WARNING로 심각도를 설정합니다.

logging.ERROR로 로그 수준을 설정합니다.

라이브러리 로그 출력의 전파를 비활성화합니다. 참고로 로그 전파는 기본적으로 비활성화되어 있습니다.

라이브러리 로그 출력의 전파를 활성화합니다. 루트 로거가 설정된 경우 중복 로그를 방지하려면 HuggingFace Hub의 기본 핸들러를 비활성화하세요.

지정된 이름을 가진 로거를 반환합니다. 이 함수는 라이브러리 사용자가 직접 접근하도록 의도된 것이 아닙니다.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

진행 표시줄이 전역적으로 또는 특정 그룹에 대해 비활성화되어 있는지 확인합니다.

이 함수는 주어진 그룹 또는 전역적으로 진행 표시줄이 비활성화되어 있는지 여부를 반환합니다. HF_HUB_DISABLE_PROGRESS_BARS 환경 변수를 먼저 확인한 후, 프로그래밍 설정을 확인합니다.

전역적으로 또는 지정된 그룹에 대해 진행 표시줄을 비활성화합니다.

이 함수는 그룹 이름에 따라 진행 막대의 상태를 업데이트합니다. 그룹 이름이 제공되지 않으면 모든 진행 막대가 비활성화됩니다. 이 작업은 HF_HUB_DISABLE_PROGRESS_BARS 환경 변수의 설정을 따릅니다.

일반 호출과 컨텍스트 매니저로 모두 작동합니다: disable_progress_bars() # enable_progress_bars()까지 비활성화 with disable_progress_bars(): # 블록 내에서 비활성화, 종료 시 재활성화 …

전역적으로 또는 지정된 그룹에 대해 진행 표시줄을 활성화합니다.

이 함수는 지정된 그룹에 대해 진행 표시줄을 활성화 상태로 설정하며, 그룹이 지정되지 않으면 전역적으로 활성화합니다. 이 작업은 HF_HUB_DISABLE_PROGRESS_BARS 환경 설정에 따라 달라집니다.

huggingface_hub에서 사용할 HTTP 클라이언트 팩토리를 설정합니다.

client factory는 httpx2.Client 객체를 반환하는 메서드입니다. get_session()이 처음 호출되면 client factory가 사용되어 huggingface_hub에 의해 수행되는 모든 호출 간에 공유되는 새로운 httpx2.Client 객체가 생성됩니다.

특정 환경에서 스크립트를 실행하고 있으며, 해당 환경에 커스텀 구성(예: 커스텀 프록시 또는 인증서)이 필요한 경우 유용할 수 있습니다.

httpx2.Client을 올바르게 구성하려면 get_session()를 사용하세요.

사용자의 transport factory를 사용하여 httpx2.Client 객체를 가져옵니다.

이 클라이언트는 huggingface_hub이 수행하는 모든 호출 사이에 공유됩니다. 따라서 수동으로 닫지 않아야 합니다.

httpx2.Client를 사용자 정의하려면 set_client_factory()를 사용하세요.

huggingface_hub에서 사용하는 전역 httpx2.Client를 닫습니다.

Client가 닫힌 경우, 다음 get_session() 호출 시 다시 생성됩니다.

SSL 인증서가 업데이트된 경우와 같이 유용할 수 있습니다.

huggingface_hub에서 사용할 HTTP 비동기 클라이언트 팩토리를 설정합니다.

async client factory는 httpx2.AsyncClient 객체를 반환하는 메서드입니다. 스크립트를 커스텀 구성(예: 커스텀 프록시 또는 인증서)이 필요한 특정 환경에서 실행하는 경우 유용할 수 있습니다. 올바르게 구성된 httpx2.AsyncClient를 가져오려면 get_async_session()을 사용하세요.

huggingface_hub가 수행하는 모든 호출에서 공유되는 httpx2.Client와 달리, httpx2.AsyncClient는 공유되지 않습니다. 컨텍스트가 종료될 때 클라이언트가 올바르게 닫히도록 보장하기 위해 async 컨텍스트 매니저를 사용하는 것이 권장됩니다.

사용자의 transport factory를 사용하여 httpx2.AsyncClient 객체를 반환합니다.

httpx2.AsyncClient를 사용자 정의하려면 set_async_client_factory()를 사용하세요.

huggingface_hub가 수행하는 모든 호출에서 공유되는 httpx2.Client와 달리, httpx2.AsyncClient는 공유되지 않습니다. 컨텍스트가 종료될 때 클라이언트가 올바르게 닫히도록 보장하기 위해 async 컨텍스트 매니저를 사용하는 것이 권장됩니다.

잠재적 HTTPError를 정제하는 response.raise_for_status()의 내부 버전입니다. raise되는 예외는 HfHubHTTPError의 인스턴스입니다.

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

요청이 실패하면 발생:

• RepositoryNotFoundError 다운로드할 저장소를 찾을 수 없는 경우 발생합니다. 이는 해당 저장소가 존재하지 않거나, repo_type이 올바르게 설정되지 않았거나, 저장소가 private이고 액세스 권한이 없는 경우일 수 있습니다.
• GatedRepoError 저장소가 존재하지만 게이트가 설정되어 있고 사용자가 승인된 목록에 없는 경우.
• RevisionNotFoundError 저장소는 존재하지만 리비전을 찾을 수 없는 경우.
• EntryNotFoundError 저장소는 존재하지만 항목(예: 요청된 파일)을 찾을 수 없는 경우.
• 요청이 HTTP 400 BadRequest 오류로 실패한 경우 BadRequestError
• HfHubHTTPError 위에서 나열되지 않은 이유로 요청이 실패한 경우.

Hub의 오프라인 모드인지 여부를 반환합니다.

오프라인 모드가 활성화되면 get_session으로发出的 모든 HTTP 요청은 OfflineModeIsEnabled 예외를 발생시킵니다.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HF Hub에서 발생하는 모든 사용자 정의 HTTP 오류를 상속하기 위한 HTTPError.

모든 HTTPError는 최소한 HfHubHTTPError로 변환됩니다. 서버가 일부 정보를 반환하는 경우, 해당 정보가 오류 메시지에 추가됩니다.

추가된 세부 정보:

• 요청 ID는 우선순위 순서대로 헤더에서 가져옵니다: “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• 헤더 “X-Error-Message”의 서버 오류 메시지.
• 응답 본문에서 서버 오류 메시지를 찾을 수 있는 경우 해당 메시지를 반환합니다.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

잘못된 저장소 이름으로 hf.co URL에 액세스하려고 하거나, 사용자가 액세스 권한이 없는 비공개 저장소 이름으로 액세스하려고 할 때 발생됩니다.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

사용자가 승인 목록에 없는 게이트드 리포지토리에 액세스하려고 할 때 발생됩니다.

참고: RepositoryNotFoundError에서 파생되어 하위 호환성을 보장합니다.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

유효한 저장소이지만 잘못된 revision으로 hf.co URL에 액세스하려고 할 때 발생됩니다.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

HfApi.resolve_revision()에서 리비전이 커밋 해시로 해석되지 못할 때 발생: Hub에 접근할 수 없는 경우(오프라인 모드, 연결 오류, 타임아웃, Hub 장애 등)이고 로컬 캐시에서 일치하는 항목을 찾지 못한 경우입니다.

서버가 HTTP 400 오류를 반환할 때 hf_raise_for_status에 의해 발생됩니다.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

로컬 또는 리모트에서 항목을 찾을 수 없을 때 발생됩니다.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

유효한 저장소와 리비전이 있는 hf.co URL에 접근하려고 할 때, 파일명이 유효하지 않은 경우 발생합니다.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

네트워크가 비활성화되었거나 사용할 수 없는 경우(연결 문제) 디스크에 없는 파일 또는 스냅샷에 액세스하려고 할 때 발생하며, 해당 항목은 Hub에 존재할 수 있습니다.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Hub에 연결할 수 없는 경우(오프라인, 연결 문제 또는 local_files_only=True)에 snapshot_download()가 발생시키며, 캐시된 스냅샷이 불완전한 것으로 알려진 상황에서 발생합니다: 저장소의 캐시된 트리 목록에 나열된 일부 파일이 로컬 스냅샷에서 누락되어 있습니다.

이것은 하위 호환성을 위해 LocalEntryNotFoundError의 하위 클래스입니다.

snapshot_path 속성은 불완전한 로컬 스냅샷의 경로를 저장하므로, 해당 파일들이 불완전하다는 것이 알려져 있더라도 하위 라이브러리가 최신 캐시된 파일을 찾을 수 있습니다.

요청된 리비전의 트리 목록이 캐시에 없을 때 get_cached_repo_tree()에서 발생됩니다.

트리 목록은 snapshot_download()의 부수 효과로 생성됩니다.

요청이 이루어졌지만 환경 변수로 HF_HUB_OFFLINE=1이 설정된 경우 발생합니다.

각종 HF 라이브러리의 사용량을 추적하는 데 도움이 되는 텔레메트리를 전송합니다.

이 사용 데이터는 문제를 디버깅하고 새로운 기능을 우선순위에 두는 데 도움이 됩니다. 그러나 모든 사용자가 추가 정보를 공유하기를 원하지는 않는다는 점을 이해하며, 여러분의 프라이버시를 존중합니다. HF_HUB_DISABLE_TELEMETRY=1을 환경 변수로 설정하여 텔레메트리 수집을 비활성화할 수 있습니다. 오프라인 모드(즉, HF_HUB_OFFLINE=1을 설정한 경우)에서도 텔레메트리가 비활성화됩니다.

Telemetry collection은 사용자에 대한 영향을 최소화하기 위해 별도의 스레드에서 실행됩니다.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

huggingface_hub의 모든 공개 메서드에 인수로 전달되는 값을 검증합니다.

이 데코레이터의 목표는 모든 곳에서 재사용되는 인수의 검증을 조화시키는 것입니다. 기본적으로 정의된 모든 검증기가 테스트됩니다.

검증기:

• validate_repo_id(): repo_id은 "repo_name" 또는 "namespace/repo_name"여야 합니다. Namespace는 사용자 이름 또는 조직입니다.
• ~utils.smoothly_deprecate_legacy_arguments: 파일 다운로드 시 proxies 무시 (전역으로 설정해야 함).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

huggingface_hub 검증기가 throw하는 일반적인 예외입니다.

ValueError에서 상속됩니다.

repo_id이 유효한지 확인합니다.

이것은 Hub에서 수행되는 적절한 검증을 대체하기 위한 것이 아니라, 가능한 한 로컬의 불일치를 방지하기 위한 것입니다(예: repo_id에 repo_type를 전달하는 것은 금지됨).

규칙:

• 1자에서 96자 사이.
• “repo_name” 또는 “namespace/repo_name”
• [a-zA-Z0-9] 또는 ”-”, ”_”, ”.”
• “—”과 “..”는 사용이 금지됩니다

유효: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

유효하지 않은 예시: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

https://github.com/huggingface/huggingface_hub/issues/1008에서 논의되었습니다. moon-landing(내부 저장소)에서:

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

huggingface_hub 코드베이스에서 레거시 인수를 부드럽게 비활성화합니다.

이 함수는 kwargs에서 일부 비추천(deprecated)된 인수를 무시하고, 해당 인수가 무시됨을 사용자에게 경고합니다. 기존 코드의 동작을 깨뜨리지 않으면서도 사용자에게 새로운 사용법을 안내하는 것이 목표입니다.

비추천 인자 목록:

• proxies: 프록시를 설정하려면 사용자는 HTTP_PROXY 환경 변수를 사용하거나 set_client_factory() 함수를 사용하여 httpx2.Client를 수동으로 구성해야 합니다.

  huggingface_hub 0.x에서는 proxies가 requests.request에 직접 전달되는 사전(dictionary)이었습니다. huggingface_hub 1.x부터 요청별 proxies는 더 이상 지원되지 않습니다. 특히, 요청별로 프록시를 구성할 수 없습니다. set_client_factory() 함수를 사용하거나 HTTP_PROXY 환경 변수를 사용하여 전역으로 구성하는 것이 해결책입니다.

  자세한 내용은 다음을 참조하세요:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: 대체 항목 없이 비추천으로 변경되었습니다. huggingface_hub는 항상 가능한 경우 다운로드를 재개합니다.

• force_filename: 대체 항목 없이 비활성화되었습니다. 파일 이름은 항상 Hub와 동일합니다.

• local_dir_use_symlinks: 대체 수단 없이 비활성화되었습니다. 로컬 디렉터리로 다운로드할 때 더 이상 심볼릭 링크를 사용하지 않습니다.