Hub Python Library documentation

레포지토리 생성 및 관리

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