Hub Python Library documentation
빠른 시작
빠른 시작
Hugging Face Hub은 머신러닝 모델, 데모, 데이터셋, 메트릭을 공유하는 데 가장 많이 사용되는 플랫폼입니다. huggingface_hub 라이브러리를 사용하면 개발 환경을 벗어나지 않고도 Hub와 상호작용할 수 있습니다. 리포지토리를 쉽게 생성하고 관리하고, 파일을 다운로드 및 업로드하며, Hub에서 유용한 모델 및 데이터셋 메타데이터를 가져올 수 있습니다.
설치
시작하려면 huggingface_hub 라이브러리를 설치하세요:
pip install --upgrade huggingface_hub
자세한 내용은 설치 가이드를 확인하세요.
huggingface_hub에는 터미널에서 Hub와 직접 상호작용할 수 있는hfCLI도 함께 제공됩니다. AI 에이전트(Claude Code, Codex, Cursor, …)를 사용 중이라면, 에이전트가 CLI를 사용할 수 있도록 Skill을 설치하세요:# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills add자세한 내용은 AI 에이전트를 위한 Hugging Face CLI 가이드를 참고하세요.
파일 다운로드
Hub의 저장소는 git 버전 관리되며, 사용자는 단일 파일 또는 전체 저장소를 다운로드할 수 있습니다. hf_hub_download() 함수를 사용하여 파일을 다운로드할 수 있습니다. 이 함수는 파일을 로컬 디스크에 다운로드하고 캐시합니다. 해당 파일이 다시 필요할 때 캐시에서 로드되므로 다시 다운로드할 필요가 없습니다.
다운로드하려는 파일의 저장소 ID와 파일명이 필요합니다. 예를 들어, Pegasus 모델의 구성 파일을 다운로드하려면:
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")특정 버전의 파일을 다운로드하려면 revision 매개변수를 사용하여 브랜치 이름, 태그 또는 커밋 해시를 지정하세요. 커밋 해시를 사용하는 경우, 짧은 7자 커밋 해시가 아닌 전체 길이의 해시를 사용해야 합니다:
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
... repo_id="google/pegasus-xsum",
... filename="config.json",
... revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )자세한 내용과 옵션은 hf_hub_download()의 API 참조를 확인하세요.
인증
많은 경우, Hub에서 작업하려면 Hugging Face 계정으로 인증해야 합니다. 예를 들어, 비공개 저장소를 다운로드하거나 파일을 업로드하거나 PR을 생성하는 등의 작업이 해당됩니다. 아직 계정이 없다면 계정을 생성하세요.
로그인 명령
가장 쉬운 인증 방법은 login() 명령을 사용하는 것입니다:
hf auth login
이미 로그인되어 있으면 해당 명령은 즉시 반환됩니다. 재로그인을 강제하려면 hf auth login --force를 사용하세요. 로그인되어 있지 않으면 브라우저로 로그인하도록 프롬프트가 표시됩니다: 출력된 URL을 열고, 짧은 코드를 입력하고, 요청을 승인하면 액세스 토큰이 검색되어 HF_HOME 디렉터리(기본값은 ~/.cache/huggingface/token)에 저장됩니다. 토큰은 일정 시간 후 만료되지만 계속 사용하는 동안 자동으로 갱신됩니다. Hub와 상호작용하는 모든 스크립트 또는 라이브러리는 요청을 보낼 때 이 토큰을 사용합니다. 또는 Settings page에서 생성한 User Access Token을 붙여넣을 수도 있습니다.
User Access Tokens에는
read또는write권한이 있습니다. 저장소를 생성하거나 편집하려면write액세스 토큰을 보유해야 합니다. 그렇지 않은 경우, 토큰이 실수로 유출되었을 때 위험을 줄이기 위해read토큰을 생성하는 것이 좋습니다.
대신, 노트북이나 스크립트에서 login()을 사용하여 프로그래밍 방식으로 로그인할 수 있습니다:
>>> from huggingface_hub import login
>>> login()한 번에 하나의 계정으로만 로그인할 수 있습니다. 새 계정으로 로그인하면 이전 계정은 자동으로 로그아웃됩니다. 현재 활성 계정을 확인하려면 hf auth whoami 명령을 실행하면 됩니다.
로그인 후, Hub에 대한 모든 요청 - 인증이 반드시 필요하지 않은 메서드 포함 - 은 기본적으로 액세스 토큰을 사용합니다. 토큰의 암시적 사용을 비활성화하려면
HF_HUB_DISABLE_IMPLICIT_TOKEN=1을 환경 변수로 설정해야 합니다(참고 참조).
로컬에서 여러 토큰 관리
각 토큰으로 login() 명령을 실행하여 로컬 머신에 여러 토큰을 저장할 수 있습니다. 로컬에서 이 토큰들 사이를 전환해야 하는 경우 auth switch 명령을 사용할 수 있습니다:
hf auth switch
이 명령은 저장된 토큰 목록에서 이름을 기준으로 토큰을 선택하도록 프롬프트를 표시합니다. 선택이 완료되면 해당 토큰이 활성 토큰이 되며, Hub와의 모든 상호작용에 사용됩니다.
hf auth list를 사용하여 머신에서 사용 가능한 모든 액세스 토큰을 나열할 수 있습니다.
환경 변수
환경 변수 HF_TOKEN도 인증에 사용할 수 있습니다. 이는 HF_TOKEN을 Space secret으로 설정할 수 있는 Space에서 특히 유용합니다.
신규: Google Colaboratory에서 노트북에 개인 키를 정의할 수 있습니다.
HF_TOKEN시크릿을 정의하면 자동으로 인증됩니다!
환경 변수 또는 시크릿을 통한 인증은 머신에 저장된 토큰보다 우선합니다.
메서드 매개변수
마지막으로, token을 매개변수로 받는 모든 메서드에 토큰을 전달하여 인증하는 것도 가능합니다.
from huggingface_hub import whoami
user = whoami(token=...)토큰을 영구적으로 저장하지 않거나 여러 토큰을 동시에 처리해야 하는 환경이 아닌 한, 이 방법은 일반적으로 권장되지 않습니다.
토큰을 매개변수로 전달할 때는 주의가 필요합니다. 토큰은 코드베이스나 노트북에 하드코딩하는 대신 항상 보안 저장소에서 로드하는 것이 최선의 관행입니다. 코드를 실수로 공유할 경우, 하드코딩된 토큰은 심각한 유출 위험을 초래할 수 있습니다.
리포지토리 생성
등록 및 로그인 후 create_repo() 함수를 사용하여 저장소를 생성합니다:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")리포지토리를 비공개로 설정하려면:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)Private repositories는 본인만 볼 수 있습니다.
Hub에 저장소를 생성하거나 콘텐츠를 push하려면
write권한이 있는 User Access Token을 제공해야 합니다. Settings page에서 토큰을 생성할 때 권한을 선택할 수 있습니다.
파일 업로드
새로 생성한 저장소에 파일을 추가하려면 upload_file() 함수를 사용하세요. 다음을 지정해야 합니다:
- 업로드할 파일의 경로입니다.
- 저장소 내 파일의 경로입니다.
- 파일을 추가하려는 저장소 ID
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
... path_or_fileobj="/home/lysandre/dummy-test/README.md",
... path_in_repo="README.md",
... repo_id="lysandre/test-model",
... )한 번에 여러 파일을 업로드하려면, git를 사용하거나 사용하지 않고 파일을 업로드하는 여러 방법을 소개하는 Upload 가이드를 참고하세요.
다음 단계
huggingface_hub 라이브러리를 사용하면 Python으로 Hub와 쉽게 상호작용할 수 있습니다. Hub에서 파일과 저장소를 관리하는 방법에 대해 자세히 알아보려면 다음을 위한 가이드를 읽어보시는 것을 권장합니다:
- 리포지토리 관리.
- Hub에서 다운로드 파일을 가져옵니다.
- Upload 파일을 Hub에 업로드합니다.
- Hub 검색에서 원하는 모델 또는 데이터셋을 검색하세요.
- Hugging Face Hub에 호스팅된 모델에 대해 여러 서비스에서 추론 실행