Hub documentation

Hub에 라이브러리를 통합하세요

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Hub에 라이브러리를 통합하세요

Hugging Face Hub은 기계 학습 모델, 체크포인트, 아티팩트의 공유를 촉진하는 것을 목표로 합니다. 이 노력에는 커뮤니티의 수많은 훌륭한 서드파티 라이브러리에 Hub를 통합하는 것이 포함됩니다. 이미 통합된 라이브러리 중 일부로는 spaCy, Sentence Transformers, OpenCLIP, timm 등이 있습니다. 통합이란 사용자가 라이브러리에서 직접 Hub로 파일을 다운로드하고 업로드할 수 있음을 의미합니다. 여러분의 라이브러리도 통합하여 모두를 위한 인공지능의 민주화에 함께해 주시기를 바랍니다.

Hub을 라이브러리에 통합하면 다음과 같은 많은 이점을 제공합니다:

사용자와 사용자들을 위한 무료 모델 호스팅.
Git-Xet 덕분에 거대한 파일도 포함된 내장 파일 버전 관리가 가능합니다.
커뮤니티 기능(토론, pull request, 좋아요).
library로 실행된 모든 모델의 사용량 지표입니다.

이 튜토리얼은 Hub를 라이브러리에 통합하여 사용자가 Hub에서 제공하는 모든 기능을 활용할 수 있도록 도와줍니다.

시작하기 전에, 저장소와 파일을 관리할 수 있는 Hugging Face 계정을 만드는 것을 권장합니다.

통합에 도움이 필요하시면 issue를 열어 주세요. 기꺼이 도와드리겠습니다.

구현

Hub에 라이브러리를 통합하는 것은 일반적으로 Hub에서 모델을 로드하고 사용자가 새 모델을 Hub에 푸시할 수 있도록 내장 메서드를 제공하는 것을 의미합니다. 이 섹션에서는 huggingface_hub 라이브러리를 사용하여 이를 수행하는 기본 사항을 다룹니다. 더 자세한 가이드는 이 가이드를 참고하세요.

설치

Hub에 라이브러리를 통합하려면 huggingface_hub 라이브러리를 의존성으로 추가해야 합니다:

pip install huggingface_hub

huggingface_hub 설치에 대한 자세한 내용은 이 가이드를 확인하세요.

이 가이드에서는 Python 라이브러리에 초점을 맞춥니다. JavaScript로 라이브러리를 구현했다면 @huggingface/hub를 대신 사용할 수 있습니다. 나머지 로직(즉, 파일 호스팅, 코드 샘플 등)은 코드 언어에 의존하지 않습니다.
npm add @huggingface/hub

huggingface_hub 라이브러리를 성공적으로 설치한 후 사용자는 인증을 수행해야 합니다. 가장 쉬운 인증 방법은 토큰을 머신에 저장하는 것입니다. 사용자는 터미널에서 login() 명령을 사용하여 이를 수행할 수 있습니다:

hf auth login

이 명령은 사용자가 이미 로그인되어 있는지 확인하고 토큰을 입력하도록 요청합니다. 토큰은 검증된 후 HF_HOME 디렉터리(기본값은 ~/.cache/huggingface/token)에 저장됩니다. Hub와 상호작용하는 모든 스크립트 또는 라이브러리는 요청을 전송할 때 이 토큰을 사용합니다.

대신, 사용자는 노트북이나 스크립트에서 login()을 사용하여 프로그래밍 방식으로 로그인할 수 있습니다:

from huggingface_hub import login
login()

Hub의 공개 저장소에서 파일을 다운로드할 때 인증은 선택 사항입니다.

Hub에서 파일 다운로드

Integrations를 사용하면 사용자가 Hub에서 모델을 다운로드하여 라이브러리로 바로 인스턴스를 생성할 수 있습니다. 이는 일반적으로 라이브러리에 특화된 메서드(보통 from_pretrained 또는 load_from_hf라고 불림)를 제공함으로써 가능해집니다. Hub에서 모델을 인스턴스화하려면 라이브러리는 다음을 수행해야 합니다:

Hub에서 파일을 다운로드합니다. 이제 이 부분을 다룰 것입니다.
이 파일들에서 Python 모델을 인스턴스화합니다.

hf_hub_download 메서드를 사용하여 Hub의 저장소에서 파일을 다운로드합니다. 다운로드된 파일은 ~/.cache/huggingface/hub 캐시에 저장됩니다. 사용자는 다음에 파일을 사용할 때 다시 다운로드할 필요가 없으므로, 특히 큰 파일의 경우 시간을 크게 절약할 수 있습니다. 또한 저장소가 파일의 새 버전으로 업데이트되면 huggingface_hub가 최신 버전을 자동으로 다운로드하여 캐시에 저장합니다. 사용자는 파일을 수동으로 업데이트할 필요가 없습니다.

예를 들어, lysandre/arxiv-nlp 저장소에서 config.json 파일을 다운로드합니다:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path에는 이제 다운로드된 파일의 경로가 포함되어 있습니다. 해당 파일이 존재하며 최신 상태임을 보장합니다.

라이브러리가 저장소 전체를 다운로드해야 하는 경우 snapshot_download를 사용하세요. 이 함수는 모든 파일을 병렬로 다운로드하는 작업을 처리합니다. 반환 값은 다운로드된 파일이 포함된 디렉토리의 경로입니다.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

특정 revision에서 파일을 다운로드하거나, 다운로드할 파일을 필터링하거나, 사용자 지정 캐시 디렉터리를 제공하거나, 로컬 디렉터리에 다운로드하는 등 다양한 옵션이 있습니다. 자세한 내용은 다운로드 가이드를 확인하세요.

Hub에 파일 업로드

사용자가 자체 모델을 Hub에 업로드할 수 있도록 메서드를 제공하는 것도 좋습니다. 이를 통해 커뮤니티가 라이브러리와 호환되는 모델 생태계를 구축할 수 있습니다. huggingface_hub 라이브러리는 저장소를 생성하고 파일을 업로드하는 메서드를 제공합니다:

create_repo는 Hub에 저장소를 생성합니다.
upload_file와 upload_folder는 Hub의 저장소에 파일을 업로드합니다.

create_repo 메서드는 Hub에 저장소를 생성합니다. repo_id 매개변수를 사용하여 저장소 이름을 지정합니다:

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

Hugging Face 계정을 확인하면 이제 네임스페이스 아래에 test-model 저장소가 표시되어야 합니다.

upload_file 메서드는 파일을 Hub에 업로드합니다. 이 메서드는 다음이 필요합니다:

업로드할 파일의 경로입니다.
저장소의 최종 경로입니다.
파일을 푸시하려는 저장소입니다.

예를 들어:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Hugging Face 계정을 확인하면 저장소 안에 해당 파일이 표시되어야 합니다.

보통 라이브러리는 모델을 로컬 디렉터리에 직렬화한 후, 해당 폴더 전체를 한 번에 Hub에 업로드합니다. upload_folder를 사용하면 됩니다:

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

파일 업로드 방법에 대한 자세한 내용은 업로드 가이드를 확인하세요.

모델 카드

Model cards는 모델과 함께 제공되는 파일로, 유용한 정보를 제공합니다. 내부적으로 model cards는 추가 메타데이터가 포함된 단순한 Markdown 파일입니다. Model cards는 검색 가능성, 재현성, 공유에 필수적입니다! 어떤 모델 저장소에서든 README.md 파일로 model card를 찾을 수 있습니다. 좋은 model card를 만드는 방법에 대한 자세한 내용은 model cards 가이드를 참고하세요.

라이브러리가 Hub에 모델을 푸시하는 것을 허용하는 경우, 미리 채워진 메타데이터(일반적으로 library_name, pipeline_tag 또는 tags)와 모델 학습 방식에 대한 정보가 포함된 최소한의 모델 카드를 생성하는 것이 권장됩니다. 이를 통해 라이브러리로 구축된 모든 모델에 대해 표준화된 설명을 제공할 수 있습니다.

라이브러리 등록

잘하셨습니다! 이제 Hub에서 모델을 로드하고, 필요 시 새 모델을 push할 수 있는 라이브러리를 갖추셨습니다. 다음 단계는 Hub에 있는 모델이 잘 문서화되고 플랫폼과 통합되었는지 확인하는 것입니다. 이를 위해 라이브러리를 Hub에 등록할 수 있으며, 이렇게 하면 사용자에게 다음과 같은 이점이 있습니다:

모델 페이지에 더 보기 좋은 라벨이 표시될 수 있습니다(예: keras-nlp 대신 KerasNLP)
각 모델 페이지에는 라이브러리 저장소 및 문서에 대한 링크가 추가됩니다
custom download count rule을 정의할 수 있습니다
code snippets를 생성하여 라이브러리를 사용하여 모델을 로드하는 방법을 보여줄 수 있습니다

새 라이브러리를 등록하려면 아래 지침에 따라 여기에서 Pull Request를 열어 주세요:

라이브러리 id는 소문자 및 하이픈으로 구분해야 합니다(예: "adapter-transformers"). PR을 열 때 알파벳 순서를 유지하는지 확인하세요.
repoName과 prettyLabel을 사용자 친화적인 대소문자 표기로 설정합니다(예: DeepForest).
repoUrl에 라이브러리 소스 코드 링크(보통 GitHub 저장소)를 설정합니다.
(선택 사항) 라이브러리 문서 링크를 docsUrl에 설정합니다. 문서가 위에서 언급한 GitHub 저장소에 이미 포함되어 있다면 두 번 설정할 필요가 없습니다.
filter를 false(으)로 설정합니다.
(선택 사항) countDownload를 설정하여 다운로드가 어떻게 집계되어야 하는지 정의합니다. 다운로드는 파일 확장명 또는 파일명을 기준으로 추적할 수 있습니다. 중복 집계되지 않도록 주의하세요. 예를 들어, 모델 로딩에 3개의 파일이 필요한 경우, 다운로드 집계 규칙은 3개 파일 중 1개 파일에 대해서만 다운로드를 집계해야 합니다. 그렇지 않으면 다운로드 수가 과대 집계됩니다. 참고: 라이브러리가 기본 설정 파일(config.json, config.yaml, hyperparams.yaml, params.json, meta.yaml, 여기 참조) 중 하나를 사용하는 경우, 다운로드 집계 규칙을 수동으로 정의할 필요가 없습니다.
(선택 사항) snippets를 정의하여 사용자가 모델을 빠르게 인스턴스화하는 방법을 안내합니다. 자세한 내용은 아래를 참조하세요.

PR을 열기 전에 https://huggingface.co/models?other=my-library-name에 최소 하나의 모델이 참조되는지 확인하세요. 그렇지 않은 경우, 해당 모델의 모델 카드 메타데이터를 library_name: my-library-name으로 업데이트해야 합니다(예: example). Hub에서 해당 모델의 소유자가 아니라면 PR을 열어주세요(예: example).

VFIMamba 통합을 추가하는 최소한의 예시입니다.

코드 스니펫

다운스트림 라이브러리에서 모델을 사용하는 방법을 설명하는 코드 스니펫을 추가하는 것을 권장합니다.

코드 스니펫을 추가하려면 model-libraries-snippets.ts 파일을 모델에 대한 설명으로 업데이트해야 합니다. 예를 들어, Asteroid 통합에는 Asteroid 모델을 로드하고 사용하는 방법에 대한 간단한 코드 스니펫이 포함되어 있습니다:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

이렇게 하면 모델에 태그가 추가되어 사용자가 라이브러리의 모델을 빠르게 식별할 수 있습니다.

model-libraries-snippets.ts에 스니펫이 추가되면, 위에서 설명한 대로 model-libraries.ts에서 이를 참조할 수 있습니다.

라이브러리 문서화

마지막으로, 라이브러리를 Hub의 문서에 추가할 수 있습니다. 예를 들어, SetFit을 문서에 추가한 Setfit PR를 확인해 보세요.

Update on GitHub

←고급 주제 작업→