Hub Python Library documentation

레포지토리 생성 및 관리

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

레포지토리 생성 및 관리

Hugging Face Hub는 git 저장소의 모음입니다. Git은 협업으로 프로젝트를 작업할 때 버전을 쉽게 관리할 수 있도록 소프트웨어 개발에서 널리 사용되는 도구입니다. 이 가이드에서는 Hub의 저장소와 상호 작용하는 방법을 보여 드리며, 특히 다음을 다룹니다:

  • 리포지토리를 생성하고 삭제합니다.
  • 브랜치와 태그 관리
  • 리포지토리를 이름 변경합니다.
  • 리포지토리 가시성을 업데이트하세요.
  • 리포지토리의 로컬 복사본을 관리합니다.

GitLab/GitHub/Bitbucket과 같은 플랫폼을 사용해 보셨다면, git CLI를 사용하여 저장소를 클론(git clone)하고, 변경 사항을 커밋(git add, git commit)한 후 푸시(git push)하는 것이 첫 번째 직관일 수 있습니다. Hugging Face Hub를 사용할 때 이는 유효한 방법입니다. 그러나 소프트웨어 엔지니어링과 머신러닝은 동일한 요구 사항과 워크플로를 공유하지 않습니다. 모델 저장소는 다양한 프레임워크와 도구를 위한 대규모 모델 가중치 파일을 유지할 수 있으므로, 저장소를 클론하면 방대한 크기의 로컬 폴더를 유지 관리하게 될 수 있습니다. 그 결과, 자체 HTTP 메서드를 사용하는 것이 더 효율적일 수 있습니다. 자세한 내용은 Git vs HTTP paradigm 설명 페이지를 참고하세요.

Hub에서 저장소를 생성하고 관리하려면 머신에 로그인되어 있어야 합니다. 로그인되어 있지 않다면 이 섹션을 참조하세요. 이 가이드의 나머지 부분에서는 머신이 로그인되어 있다고 가정합니다.

리포지토리 목록 보기

list_user_repos()를 사용하여 계정 또는 조직의 모든 저장소(모델, 데이터셋, 스페이스, 버킷)를 나열할 수 있습니다. 결과에는 저장소 정보가 포함되며, 저장소 사용량 기준으로 정렬됩니다.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

또는 CLI를 통해 (기본적으로 30개 저장소를 표시하며, --limit 0을 사용하여 전체 목록을 표시할 수 있습니다):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

레포지토리 생성 및 삭제

첫 단계는 저장소를 생성하고 삭제하는 방법을 아는 것입니다. 사용자 이름 네임스페이스에 있는 저장소나 쓰기 권한이 있는 조직의 저장소만 관리할 수 있습니다.

리포지토리 생성

create_repo()를 사용하여 빈 저장소를 생성하고 repo_id 매개변수로 이름을 지정합니다. repo_id는 네임스페이스 뒤에 저장소 이름을 붙인 형태입니다: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

또는 CLI를 통해:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

기본적으로 create_repo()는 모델 저장소를 생성합니다. 하지만 repo_type 매개변수를 사용하여 다른 저장소 유형을 지정할 수 있습니다. 예를 들어, 데이터셋 저장소를 생성하려면:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

또는 CLI를 통해:

>>> hf repos create lysandre/test-dataset --repo-type dataset

리포지토리를 생성할 때 visibility 파라미터를 사용하여 리포지토리 가시성을 설정할 수 있습니다:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

또는 CLI를 통해:

>>> hf repos create lysandre/test-private --private

나중에 저장소 가시성을 변경하려면 update_repo_settings() 함수를 사용할 수 있습니다.

Enterprise 플랜을 사용하는 조직의 구성원이라면 create_repo()에 resource_group_id를 매개변수로 전달하여 특정 리소스 그룹에 리포지토리를 생성할 수 있습니다. 리소스 그룹은 조직의 어떤 멤버가 특정 리소스에 접근할 수 있는지를 제어하는 보안 기능입니다. Hub의 조직 설정 페이지 URL에서 리소스 그룹 ID를 복사하여 확인할 수 있습니다(예: "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). 리소스 그룹에 대한 자세한 내용은 이 가이드를 참고하세요.

region을 매개변수로 전달하여 특정 클라우드 리전에 저장소를 만들 수도 있습니다:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

리포지토리 삭제

delete_repo()를 사용하여 저장소를 삭제합니다. 이 작업은 되돌릴 수 없으므로 저장소를 삭제할지 신중하게 확인하세요!

삭제하려는 저장소의 repo_id를 지정하세요:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

리포지토리가 존재하지 않는 경우 호출을 조용히 무시하려면 missing_ok=True를 전달하세요:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

또는 CLI를 통해:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

리포지토리 복제

일부 경우에는 다른 사람의 저장소를 복사하여 자신의 사용 사례에 맞게 수정하고 싶을 수 있습니다. 이것은 duplicate_repo() 메서드를 사용하여 가능합니다. 이 메서드는 전체 저장소를 복제하며, 전체 git 히스토리를 보존합니다. 이 기능은 모델, 데이터셋, Spaces에 모두 적용됩니다. Spaces의 경우에도 하드웨어, sleep-time, 저장소, 변수 및 시크릿 등 자신의 설정을 구성해야 합니다. 자세한 내용은 Manage your Space 가이드를 참고하세요.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

create_repo()와 마찬가지로, duplicate_repo()는 resource_group_id를 받아 Enterprise 조직의 리소스 그룹 안에 복본을 직접 생성할 수 있습니다(hf repos duplicate에 --resource-group-id 사용).

git 히스토리는 즉시 복사되지만, duplicate_repo()가 반환된 후에도 LFS/Xet 파일은 백그라운드에서 복사될 수 있습니다. 복사가 완료될 때까지 새 저장소에서 이러한 파일을 다운로드하면 실패할 수 있습니다. 복사가 아직 진행 중인지 확인하려면 반환 값의 files_copy_pending를 확인하세요:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Spaces 검색

Hub은 Spaces를 발견하기 위한 의미론적 검색 API를 제공합니다. search_spaces()를 사용하여 자연어 쿼리로 검색할 수 있습니다:

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

자세한 내용과 필터링 옵션에 대해서는 Spaces 관리 가이드를 참조하세요.

파일 업로드 및 다운로드

…리포지토리를 생성했으므로 이제 변경 사항을 푸시하고 파일을 다운로드하는 데 관심이 있을 것입니다.

이 두 주제는 각각 별도의 가이드가 필요합니다. 저장소를 사용하는 방법을 배우려면 업로드 및 다운로드 가이드를 참고하세요.

파일 복사

Hub에 이미 호스팅된 파일을 다운로드 및 재업로드하지 않고 한 저장소에서 다른 저장소(또는 동일한 저장소 내)로 복사하려면 copy_files()를 사용하세요. 개별 파일과 전체 폴더 모두 지원되며, Xet 또는 LFS로 추적되는 파일은 해시를 기반으로 서버 측에서 복사됩니다.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

또는 통합 hf cp 명령어(또는 hf repos cp로도 사용 가능)를 통해 CLI로:

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files(그리고 hf cp)는 저장소에서 Bucket로 파일을 복사하는 데에도 사용할 수 있습니다. Bucket에서 저장소로 복사하는 것은 지원되지 않습니다. 자세한 내용은 Buckets 가이드를 참조하세요.

서버 측 복사본은 동일한 스토리지 리전 내에서만 작동합니다.

Branches and tags

Git 저장소는 동일한 저장소의 다른 버전을 저장하기 위해 브랜치를 사용하는 경우가 많습니다. 태그는 저장소의 특정 상태를 표시하는 데 사용할 수 있으며, 예를 들어 버전을 릴리스할 때 사용할 수 있습니다. 더 일반적으로, 브랜치와 태그는 git references라고 불립니다.

브랜치와 태그 만들기

create_branch()와 create_tag()를 사용하여 새 브랜치와 태그를 만들 수 있습니다:

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

또는 CLI를 통해:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

delete_branch() 및 delete_tag() 함수를 동일한 방식으로 사용하여 브랜치 또는 태그를 삭제할 수 있으며, CLI에서는 각각 hf repos branch delete 및 hf repos tag delete를 사용할 수 있습니다.

모든 branch와 tag를 나열합니다

list_repo_refs()를 사용하여 저장소의 기존 git refs를 나열할 수도 있습니다:

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

저장소 설정 변경

리포지토리에는 설정할 수 있는 몇 가지 설정이 있습니다. 대부분의 경우, 브라우저의 리포지토리 설정 페이지에서 수동으로 설정하는 것이 좋습니다. 리포지토리를 설정하려면 쓰기 권한이 있어야 합니다(리포지토리의 소유자이거나 조직의 일원이어야 합니다). 이 섹션에서는 huggingface_hub을 사용하여 프로그래밍 방식으로 설정할 수 있는 설정을 살펴보겠습니다.

일부 설정은 Spaces(하드웨어, 환경 변수 등)에 특화되어 있습니다. 이러한 설정을 구성하려면 Manage your Spaces 가이드를 참고하세요.

가시성 업데이트

리포지토리는 공개 또는 비공개일 수 있습니다. 비공개 리포지토리는 해당 리포지토리가 속해 있는 조직의 멤버나 본인에게만 표시됩니다. 다음과 같이 리포지토리를 비공개로 변경할 수 있습니다.

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

또는 CLI를 통해:

>>> hf repos settings lysandre/test-private --private true

게이트된 액세스 설정

리포지토리의 사용 방식을 더 세밀하게 제어할 수 있도록, Hub는 리포지토리 작성자가 자신의 리포지토리에 대해 액세스 요청을 활성화할 수 있도록 지원합니다. 활성화된 경우, 사용자는 파일에 액세스하려면 리포지토리 작성자와 연락처 정보(사용자 이름 및 이메일 주소)를 공유하는 데 동의해야 합니다. 액세스 요청이 활성화된 리포지토리를 게이트드 리포지토리라고 합니다.

update_repo_settings()를 사용하여 저장소를 게이트드(gated)로 설정할 수 있습니다:

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

또는 CLI를 통해:

>>> hf repos settings lysandre/test-private --gated auto

리포지토리 이름 변경

Hub에서 move_repo()를 사용하여 저장소 이름을 변경할 수 있습니다. 이 메서드를 사용하면 사용자 계정을 조직으로 저장소를 이동하는 것도 가능합니다. 이 경우 알아야 할 몇 가지 제한 사항이 있습니다. 예를 들어, 다른 사용자에게 저장소를 이전할 수 없습니다.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

또는 CLI를 통해:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

커널 저장소

Hub는 컴퓨트 커널을 호스팅하기 위한 "kernel" 저장소 유형을 지원합니다. 이는 완전히 호환되는 저장소 유형이 아닙니다. 테스트되고 공식적으로 지원되는 메서드는 제한적입니다:

create_repo()와 delete_repo()도 호환되지만, Hub에서 허용된 소수의 사용자 및 조직으로 제한됩니다.

커널 저장소를 빌드, 게시 및 사용하려면 대신 전용 kernels 패키지를 사용하세요. 자세한 내용은 Kernels 문서를 참조하세요.

Update on GitHub