huggingface_hub 패키지는 패키지 로그 레벨을 제어하기 위한 logging 유틸리티를 제공합니다.
다음과 같이 가져올 수 있습니다:
from huggingface_hub import logging그런 다음, 로그의 출력 수를 업데이트하기 위해 로그 레벨을 정의할 수 있습니다:
from huggingface_hub import logging
logging.set_verbosity_error()
logging.set_verbosity_warning()
logging.set_verbosity_info()
logging.set_verbosity_debug()
logging.set_verbosity(...)로그 레벨은 다음과 같이 이해하면 됩니다:
error: 오류 또는 예기치 않은 동작으로 이어질 수 있는 결정적인 로그만 표시합니다.warning: 결정적이진 않지만 의도치 않은 동작을 초래할 수 있는 로그를 표시합니다. 또한 중요한 정보를 포함한 로그도 표시될 수 있습니다.info: 하부에서 무슨 일이 일어나고 있는지에 대한 자세한 로그를 포함하여 대부분의 로그를 표시합니다. 무언가 예상치 못한 방식으로 동작하는 경우, 더 많은 정보를 얻기 위해 verbosity 단계로 전환하는 것이 좋습니다.debug: 하부에서 정확히 무슨 일이 일어나고 있는지를 추적하는 데 사용될 수 있는 일부 내부 로그를 포함하여 모든 로그를 표시합니다.
[[autodoc]] logging.get_verbosity [[autodoc]] logging.set_verbosity [[autodoc]] logging.set_verbosity_info [[autodoc]] logging.set_verbosity_debug [[autodoc]] logging.set_verbosity_warning [[autodoc]] logging.set_verbosity_error [[autodoc]] logging.disable_propagation [[autodoc]] logging.enable_propagation
아래 제공된 메소드들은 huggingface_hub 라이브러리 모듈을 수정할 때 관련이 있습니다. huggingface_hub를 사용하고 해당 모듈을 수정하지 않는 경우에는 사용할 필요가 없습니다.
[[autodoc]] logging.get_logger
프로그레스 바는 긴 시간이 걸리는 작업을 실행하는 동안 정보를 표시하는 유용한 도구입니다(예시로 파일을 다운로드하거나 업로드하는 등). huggingface_hub는 라이브러리 전체에서 일관된 방식으로 프로그레스 바를 표시하기 위한 [~utils.tqdm] 래퍼를 제공합니다.
기본적으로 프로그레스 바가 활성화되어 있습니다. HF_HUB_DISABLE_PROGRESS_BARS 환경 변수를 설정하여 전역적으로 비활성화할 수 있습니다. 또한 [~utils.enable_progress_bars]와 [~utils.disable_progress_bars]를 사용하여 프로그레스 바를 개별적으로 활성화 또는 비활성화할 수도 있습니다. 만약 환경 변수가 설정되어 있다면, 환경 변수가 도우미에서 우선 순위를 가집니다.
>>> from huggingface_hub import snapshot_download
>>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars
>>> # 전역적으로 프로그레스 바를 비활성화합니다.
>>> disable_progress_bars()
>>> # 프로그레스 바가 표시되지 않습니다!
>>> snapshot_download("gpt2")
>>> are_progress_bars_disabled()
True
>>> # 다시 프로그레스 바가 활성화됩니다
>>> enable_progress_bars()[[autodoc]] huggingface_hub.utils.are_progress_bars_disabled
[[autodoc]] huggingface_hub.utils.disable_progress_bars
[[autodoc]] huggingface_hub.utils.enable_progress_bars
일부 환경에서는 HTTP 호출이 이루어지는 방식을 구성할 수 있습니다. 예를 들어, 프록시를 사용하는 경우가 그렇습니다. huggingface_hub는 [configure_http_backend]를 사용하여 전역적으로 이를 구성할 수 있게 합니다. 그러면 Hub로의 모든 요청이 사용자가 설정한 설정을 사용합니다. 내부적으로 huggingface_hub는 requests.Session을 사용하므로 사용 가능한 매개변수에 대해 자세히 알아보려면 requests 문서를 참조하는 것이 좋습니다.
requests.Session이 스레드 안전을 보장하지 않기 때문에 huggingface_hub는 스레드당 하나의 세션 인스턴스를 생성합니다. 세션을 사용하면 HTTP 호출 사이에 연결을 유지하고 최종적으로 시간을 절약할 수 있습니다. huggingface_hub를 서드 파티 라이브러리에 통합하고 사용자 지정 호출을 Hub로 만들려는 경우, [get_session]을 사용하여 사용자가 구성한 세션을 가져옵니다 (즉, 모든 requests.get(...) 호출을 get_session().get(...)으로 대체합니다).
[[autodoc]] configure_http_backend
[[autodoc]] get_session
huggingface_hub는 서버에서 반환된 추가 정보로 requests에서 발생한 HTTPError를 세분화하기 위해 자체 HTTP 오류를 정의합니다.
[~utils.hf_raise_for_status]는 Hub에 대한 모든 요청에서 "상태를 확인하고 예외를 발생시키는" 중앙 메소드로 사용됩니다. 이 메서드는 기본 requests.raise_for_status를 감싸서 추가 정보를 제공합니다. 발생된 모든 HTTPError는 HfHubHTTPError로 변환됩니다.
import requests
from huggingface_hub.utils import hf_raise_for_status, HfHubHTTPError
response = requests.post(...)
try:
hf_raise_for_status(response)
except HfHubHTTPError as e:
print(str(e)) # 형식화된 메시지
e.request_id, e.server_message # 서버에서 반환된 세부 정보
# 오류 메시지를 발생시킬 때 추가 정보를 포함하여 완성합니다
e.append_to_message("\n`create_commit` expects the repository to exist.")
raise[[autodoc]] huggingface_hub.utils.hf_raise_for_status
여기에는 huggingface_hub에서 발생하는 HTTP 오류 목록이 있습니다.
HfHubHTTPError는 HF Hub HTTP 오류에 대한 부모 클래스입니다. 이 클래스는 서버 응답을 구문 분석하고 오류 메시지를 형식화하여 사용자에게 가능한 많은 정보를 제공합니다.
[[autodoc]] huggingface_hub.utils.HfHubHTTPError
[[autodoc]] huggingface_hub.utils.RepositoryNotFoundError
[[autodoc]] huggingface_hub.utils.GatedRepoError
[[autodoc]] huggingface_hub.utils.RevisionNotFoundError
[[autodoc]] huggingface_hub.utils.EntryNotFoundError
[[autodoc]] huggingface_hub.utils.BadRequestError
[[autodoc]] huggingface_hub.utils.LocalEntryNotFoundError
[[autodoc]] huggingface_hub.utils.OfflineModeIsEnabled
huggingface_hub는 원격 측정 데이터를 보내는 도우미가 포함되어 있습니다. 이 정보는 문제를 디버깅하고 새로운 기능을 우선적으로 처리하는 데 도움이 됩니다. 사용자는 HF_HUB_DISABLE_TELEMETRY=1 환경 변수를 설정하여 언제든지 원격 측정 수집을 비활성화할 수 있습니다. 또한 오프라인 모드에서도 (즉, HF_HUB_OFFLINE=1로 설정된 경우) 원격 측정이 비활성화됩니다.
서드 파티 라이브러리의 유지 관리자인 경우, 원격 측정 데이터를 보내는 것은 [send_telemetry]를 호출하는 것만큼 간단합니다. 사용자에게 가능한 영향을 최소화하기 위해 데이터는 별도의 스레드에서 전송됩니다.
[[autodoc]] utils.send_telemetry
huggingface_hub에는 메소드 인수를 자동으로 유효성 검사하는 사용자 정의 검증기가 포함되어 있습니다. 이 유효성 검사는 타입 힌트를 검증하는 데 Pydantic의 작업을 참고하여 구현되었지만, 기능은 더 제한적입니다.
[~utils.validate_hf_hub_args]는 huggingface_hub의 네이밍을 따르는 인수를 갖는 메소드를 캡슐화하는 일반적인 데코레이터입니다. 기본적으로 구현된 검증기가 있는 모든 인수가 유효성 검사됩니다.
입력이 유효하지 않은 경우 [~utils.HFValidationError]이 발생합니다. 첫 번째 유효하지 않은 값만 오류를 발생시키고 유효성 검사 프로세스를 중지합니다.
사용법:
>>> 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'.
>>> @validate_hf_hub_args
... def my_cool_auth_method(token: str):
... print(token)
>>> my_cool_auth_method(token="a token")
"a token"
>>> my_cool_auth_method(use_auth_token="a use_auth_token")
"a use_auth_token"
>>> my_cool_auth_method(token="a token", use_auth_token="a use_auth_token")
UserWarning: Both `token` and `use_auth_token` are passed (...). `use_auth_token` value will be ignored.
"a token"[[autodoc]] utils.validate_hf_hub_args
[[autodoc]] utils.HFValidationError
검증기는 개별적으로도 사용할 수 있습니다. 다음은 검증할 수 있는 모든 인수 목록입니다.
[[autodoc]] utils.validate_repo_id
정확히 검증기는 아니지만, 잘 실행됩니다.
[[autodoc]] utils.smoothly_deprecate_use_auth_token