라이브러리를 Hub에 통합하기

라이브러리를 Hub에 통합하기

Hugging Face Hub는 머신러닝 모델, 체크포인트, 아티팩트 공유를 돕는 것을 목표로 해요. 이를 위해 Hub를 커뮤니티의 훌륭한 서드파티 라이브러리 여러 개에 통합하고 있어요. 이미 통합된 것에는 spaCy, Sentence Transformers, OpenCLIP, timm 등이 있어요. 통합하면 사용자가 여러분 라이브러리에서 직접 Hub에 파일을 다운로드하고 업로드할 수 있어요.

출처: 문서

본문

Hub를 라이브러리와 통합하면 많은 이점이 있어요:

• 여러분과 사용자에게 무료 모델 호스팅.
• Git-Xet 덕분에 거대한 파일도 가능한 내장 파일 버전 관리.
• 커뮤니티 기능(토론, 풀 리퀘스트, 좋아요).
• 라이브러리로 실행한 모든 모델의 사용량 지표.

시작 전에 저장소와 파일을 관리할 Hugging Face 계정을 만드는 걸 권장해요. 통합에 문제가 있으면 이슈를 열어 도움을 받을 수 있어요.

구현

라이브러리와 Hub를 통합한다는 건 보통 Hub에서 모델을 불러오고 사용자가 새 모델을 Hub로 푸시하는 내장 메서드를 제공하는 걸 의미해요. 이 섹션은 huggingface_hub 라이브러리로 그 방법의 기초를 다룰 거예요.

설치

huggingface_hub 라이브러리를 의존성으로 추가해야 해요:

pip install huggingface_hub

[!TIP] 이 가이드는 파이썬 라이브러리에 초점을 맞춰요. 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에서 파일 다운로드

통합은 사용자가 Hub에서 모델을 다운로드해 라이브러리에서 바로 인스턴스화하게 해줘요. 보통 라이브러리에 특화된 메서드(주로 from_pretrained 또는 load_from_hf)를 제공해 가능해요. Hub에서 모델을 인스턴스화하려면 라이브러리는:

• Hub에서 파일을 다운로드해야 해요. (지금 다룰 내용)
• 이 파일들로 파이썬 모델을 인스턴스화해야 해요.

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'

특정 리비전 다운로드, 다운로드 파일 필터링, 커스텀 캐시 디렉터리, 로컬 디렉터리로 다운로드 등 다양한 옵션이 있어요. 자세한 내용은 다운로드 가이드를 참고하세요.

Hub에 파일 업로드

사용자가 자신의 모델을 Hub에 푸시하는 메서드를 제공할 수도 있어요. 이렇게 하면 커뮤니티가 라이브러리와 호환되는 모델 생태계를 만드는 걸 돕게 돼요. huggingface_hub는 저장소 생성·파일 업로드 메서드를 제공해요:

• create_repo - Hub에 저장소를 만들어요.
• upload_file과 upload_folder - Hub 저장소에 파일을 업로드해요.

create_repo는 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은 다음을 요구해요:

• 업로드할 파일 경로.
• 저장소에서의 최종 경로.
• 파일을 푸시할 저장소.

예를 들어:

>>> 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'

보통 라이브러리는 모델을 로컬 디렉터리에 직렬화한 뒤, 전체 폴더를 한 번에 Hub에 업로드해요. upload_folder로 할 수 있어요:

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

업로드 방법에 대한 자세한 내용은 업로드 가이드를 참고하세요.

모델 카드

모델 카드는 모델과 함께 제공되는 파일로 유용한 정보를 담아요. 본질적으로 추가 메타데이터가 있는 단순한 Markdown 파일이에요. 모델 카드는 발견 가능성, 재현성, 공유에 필수적이에요! 어떤 모델 저장소에서든 README.md 파일로 모델 카드를 찾을 수 있어요. 좋은 모델 카드를 만드는 방법은 모델 카드 가이드를 참고하세요.

라이브러리가 Hub에 모델을 푸시하게 한다면, 미리 채워진 메타데이터(보통 library_name, pipeline_tag, tags)와 학습 방법 정보가 든 최소 모델 카드를 생성하는 걸 권장해요.

라이브러리 등록하기

이제 Hub에서 모델을 불러오고 새 모델을 푸시할 수 있는 라이브러리가 준비됐어요. 다음 단계는 Hub의 모델이 잘 문서화되고 플랫폼과 통합되게 하는 거예요. 라이브러리를 Hub에 등록하면 사용자에게 여러 이점이 있어요:

• 모델 페이지에 보기 좋은 라벨을 보여줄 수 있어요(예: keras-nlp 대신 KerasNLP).
• 각 모델 페이지에 라이브러리 저장소와 문서 링크가 추가돼요.
• 커스텀 다운로드 카운트 규칙을 정의할 수 있어요.
• 라이브러리로 모델을 불러오는 방법을 보여주는 코드 스니펫을 생성할 수 있어요.

새 라이브러리를 등록하려면 다음 지침을 따라 여기에 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으로 업데이트해야 해요(예제). Hub 모델의 소유자가 아니라면 PR을 열어 주세요(예제).

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을 참고하세요.

더 알아보기 (Learn more)

• huggingface_hub 통합 가이드로 심화 내용을 익혀 보세요.
• 모델 카드 가이드로 좋은 모델 카드 작성법을 배워 보세요.