레포지토리 생성 및 관리
Hugging Face Hub는 git 저장소의 모음입니다. Git은 협업으로 프로젝트를 작업할 때 버전을 쉽게 관리할 수 있도록 소프트웨어 개발에서 널리 사용되는 도구입니다. 이 가이드에서는 Hub의 저장소와 상호 작용하는 방법을 보여 드리며, 특히 다음을 다룹니다:
- 리포지토리를 생성하고 삭제합니다.
- 브랜치와 태그 관리
- 리포지토리를 이름 변경합니다.
- 리포지토리 가시성을 업데이트하세요.
- 리포지토리의 로컬 복사본을 관리합니다.
GitLab/GitHub/Bitbucket과 같은 플랫폼을 사용해 보셨다면,
gitCLI를 사용하여 저장소를 클론(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
TrueSpaces 검색
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" 저장소 유형을 지원합니다. 이는 완전히 호환되는 저장소 유형이 아닙니다. 테스트되고 공식적으로 지원되는 메서드는 제한적입니다:
- kernel_info()
- hf_hub_download()
- snapshot_download()
- list_repo_refs()
- list_repo_files()
- list_repo_tree()
create_repo()와 delete_repo()도 호환되지만, Hub에서 허용된 소수의 사용자 및 조직으로 제한됩니다.
커널 저장소를 빌드, 게시 및 사용하려면 대신 전용 kernels 패키지를 사용하세요. 자세한 내용은 Kernels 문서를 참조하세요.