모델 카드 (Model Cards)

모델 카드란 무엇인가요?

모델 카드는 모델과 함께 제공되어 유용한 정보를 담는 파일이에요. 내부적으로 모델 카드는 추가 메타데이터가 붙은 단순한 Markdown 파일이에요. 모델 카드는 발견성, 재현성, 공유에 필수적이에요. 어떤 모델 저장소에서든 README.md 파일로 모델 카드를 찾을 수 있어요.

모델 카드는 다음을 설명해야 해요.

모델
의도된 용도와 잠재적 한계. Mitchell, 2018에 상세히 나와 있는 편향과 윤리적 고려사항 포함
훈련 파라미터와 실험 정보(참고를 위해 실험 추적 플랫폼을 임베드하거나 링크할 수 있어요)
모델 훈련에 쓰인 데이터셋
모델의 평가 결과

모델 카드 템플릿은 여기에서 볼 수 있어요. 각 섹션을 어떻게 채우는지는 Annotated Model Card에 설명되어 있어요.

허브의 모델 카드는 두 가지 핵심 부분을 가지며, 두 부분은 정보가 겹쳐요.

메타데이터
텍스트 설명

모델 카드 메타데이터

모델 저장소는 README.md를 모델 카드로 렌더링해요. 모델 카드는 Markdown 파일이며, 맨 위에 모델에 대한 메타데이터를 담고 있는 YAML 섹션이 있어요.

모델 카드에 넣는 메타데이터는 모델의 발견성과 사용 용이성을 지원해요. 예를 들어:

사용자가 https://huggingface.co/models에서 모델을 필터링할 수 있게 해줘요.
모델의 라이선스를 표시해요.
데이터셋을 메타데이터에 추가하면 모델 페이지에 Datasets used to train: 메시지가 추가되고, 허브에 있다면 관련 데이터셋을 연결해 줘요.

데이터셋과 언어 식별자는 Datasets 및 Languages 페이지에 나열된 것들입니다.

모델 카드에 메타데이터 추가하기

모델 카드에 메타데이터를 추가하는 방법은 몇 가지가 있어요.

메타데이터 UI 사용
README.md 파일의 YAML 섹션 직접 편집
huggingface_hub Python 라이브러리로. 자세한 내용은 문서 참고

허브 통합이 있는 많은 라이브러리는 모델을 업로드할 때 모델 카드에 메타데이터를 자동으로 추가해요.

메타데이터 UI 사용

메타데이터 UI로 모델 카드에 메타데이터를 추가할 수 있어요. 메타데이터 UI에 접근하려면 모델 페이지로 가서 모델 카드 오른쪽 위의 Edit model card 버튼을 클릭하세요. 그러면 모델 카드 README.md 파일과 메타데이터 편집용 UI를 보여주는 편집기가 열려요.

이 UI는 모델 카드에 핵심 메타데이터를 추가할 수 있게 해주고, 많은 필드는 제공하는 정보에 따라 자동 완성돼요. UI를 쓰는 것이 메타데이터를 추가하는 가장 쉬운 방법이지만, 모든 메타데이터 필드를 지원하지는 않아요. UI가 지원하지 않는 메타데이터를 추가하고 싶다면 README.md의 YAML 섹션을 직접 편집하면 돼요.

README.md의 YAML 섹션 편집

README.md 파일의 YAML 섹션을 직접 편집할 수도 있어요. 모델 카드에 아직 YAML 섹션이 없다면 파일 맨 위에 --- 세 개를 추가하고 관련 메타데이터를 모두 넣은 뒤 또 다른 ---로 섹션을 닫으면 돼요.

---
language:
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

상세한 모델 카드 메타데이터 사양은 여기에서 볼 수 있어요.

라이브러리 지정

모델 카드 메타데이터 섹션에서 지원 라이브러리를 지정할 수 있어요. 지원 라이브러리에 대한 자세한 내용은 여기에서 확인하세요. 라이브러리는 다음 우선순위 순서로 지정돼요.

모델 카드에서 library_name을 지정하기(transformers 모델이 아니라면 권장). 이 정보는 메타데이터 UI나 모델 카드 YAML 섹션에서 추가할 수 있어요.

library_name: flair

지원되는 라이브러리 이름을 가진 태그

tags:
- flair

지정하지 않으면 허브가 라이브러리 유형을 자동 감지하려고 해요. 하지만 이 방식은 권장되지 않으며, 저장소 작성자는 가능한 한 명시적 library_name을 써야 해요.
*.nemo나 *.mlmodel 같은 파일의 존재를 보고 허브가 NeMo 또는 CoreML 모델인지 판단할 수 있어요.
과거에는 아무것도 감지되지 않고 config.json 파일이 있으면 라이브러리가 transformers라고 가정했어요. 2024년 8월 이후에 만들어진 모델 저장소는 더 이상 그렇지 않으므로, library_name: transformers를 명시적으로 설정해야 해요.

기본 모델(base model) 지정

모델이 파인튜닝, 어댑터, 혹은 기본 모델의 양자화(quantized) 버전이라면 모델 카드 메타데이터 섹션에서 기본 모델을 지정할 수 있어요. 이 정보는 모델이 여러 기존 모델의 머지인지 나타내는 데도 쓰일 수 있어요. 따라서 base_model 필드는 단일 모델 ID일 수도, 하나 이상의 base_model(허브 식별자로 지정) 목록일 수도 있어요.

base_model: HuggingFaceH4/zephyr-7b-beta

이 메타데이터는 모델 페이지에 기본 모델을 표시하는 데 사용돼요. 사용자는 이 정보로 기본 모델별로 모델을 필터링하거나 특정 기본 모델에서 파생된 모델을 찾을 수 있어요.

머지(merge)의 경우 두 개 이상의 base_model 목록을 지정해요.

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

허브는 현재 모델과 기본 모델 사이의 관계 유형("adapter", "merge", "quantized", "finetune")을 유추해요. 필요하면 base_model_relation: quantized처럼 명시적으로 설정할 수도 있어요.

새 버전 지정

모델의 새 버전이 허브에 있다면 new_version 필드로 지정할 수 있어요.

예: l3utterfly/mistral-7b-v0.1-layla-v3에서

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

이 메타데이터로 모델 페이지에 모델의 최신 버전 링크가 표시돼요. new_version이 가리키는 모델도 new_version 필드를 가지면 가장 최신 버전이 항상 표시돼요.

데이터셋 지정

모델 훈련에 사용한 데이터셋을 모델 카드 메타데이터 섹션에서 지정할 수 있어요. 데이터셋은 모델 페이지에 표시되고, 사용자는 데이터셋으로 모델을 필터링할 수 있어요. 허브 데이터셋 식별자, 즉 데이터셋 저장소 이름과 같은 식별자를 사용해야 해요.

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

버킷(bucket) 지정

모델과 연결된 storage buckets을 모델 카드 메타데이터 섹션에서 지정할 수 있어요. 버킷은 모델 페이지에 태그로 표시되고, 연결된 버킷 페이지에는 반대로 모델이 표시돼요. 허브 버킷 식별자, 즉 버킷 저장소 이름과 같은 식별자를 사용해야 해요.

buckets:
- my-org/my-bucket
- my-org/another-bucket

작업(pipeline_tag) 지정

모델 카드 메타데이터에서 pipeline_tag를 지정할 수 있어요. pipeline_tag는 모델이 의도된 작업 유형을 나타내요. 이 태그는 모델 페이지에 표시되고, 사용자는 허브에서 작업별로 모델을 필터링할 수 있어요. 이 태그는 어떤 위젯을 쓸지, 내부적으로 어떤 API를 쓸지를 정하는 데도 사용돼요.

transformers 모델의 경우 파이프라인 태그는 모델의 config.json 파일에서 자동 유추되지만, 필요하면 모델 카드 메타데이터에서 덮어쓸 수 있어요. 메타데이터 UI에서 이 필드를 편집하면 파이프라인 태그가 유효함을 보장해요. 허브 통합이 있는 일부 다른 라이브러리도 모델 카드 메타데이터에 파이프라인 태그를 자동 추가해요.

라이선스 지정

모델 카드 메타데이터 섹션에서 라이선스를 지정할 수 있어요. 라이선스는 모델 페이지에 표시되고, 사용자는 라이선스로 모델을 필터링할 수 있어요. 메타데이터 UI를 쓰면 가장 흔한 라이선스의 드롭다운이 보여요.

필요하면 커스텀 라이선스를 지정할 수도 있어요. 라이선스 값에 other를 추가하고 메타데이터에 라이선스 이름과 링크를 지정하면 돼요.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

라이선스를 URL로 사용할 수 없다면 모델 저장소에 저장된 LICENSE를 연결할 수 있어요.

평가 결과

모델 카드 메타데이터에서 모델의 평가 결과를 구조화된 방식으로 지정할 수 있어요. 결과는 허브가 파싱해 모델 페이지의 위젯에 표시해요. bigcode/starcoder 모델에서 어떻게 보이는지가 예시예요.

논문 연결

모델 카드에 Paper 페이지(HF 또는 Arxiv 초록/PDF) 링크가 포함되어 있으면, Hugging Face Hub가 arXiv ID를 추출해 arxiv:<PAPER ID> 형식의 모델 태그에 넣어줘요. 태그를 클릭하면:

Paper 페이지 방문
같은 논문을 인용하는 허브의 다른 모델 필터링

Paper 페이지에 대한 자세한 내용은 여기에서 확인하세요.

모델 카드 텍스트

모델 카드의 사람이 읽는 부분(출력·복사·붙여넣기용)을 어떻게 채우는지의 자세한 내용은 Annotated Model Card에서 볼 수 있어요.

FAQ

모델 태그는 어떻게 결정되나요?

각 모델 페이지는 페이지 헤더, 모델 이름 아래에 모든 모델 태그를 나열해요. 이 태그들은 주로 모델 카드 메타데이터에서 계산되지만, 위젯 활성화에 설명된 대로 자동으로 추가되는 것도 있어요.

모델에 커스텀 태그를 추가할 수 있나요?

네, 모델 카드 메타데이터의 tags 필드에 추가하면 커스텀 태그를 넣을 수 있어요. 메타데이터 UI가 인기 태그를 제안하지만 원하는 태그를 아무거나 추가할 수 있어요. 예를 들어 모델이 금융에 특화됐다는 뜻의 finance 태그를 추가할 수 있어요.

모델이 모든 사용자에게 적합하지 않다고 표시하려면 어떻게 하나요?

모델 카드 메타데이터에 not-for-all-audiences 태그를 추가하면 돼요. 이 태그가 있으면 모델이 모든 사용자용이 아니라는 메시지가 모델 페이지에 표시되고, 사용자는 이 메시지를 클릭해 모델 카드를 볼 수 있어요.

라이트 모드와 다크 모드에 다른 이미지를 표시하려면 어떻게 하나요?

각 테마에 최적화된 다른 이미지 버전을 표시할 수 있어요. 로고·다이어그램·스크린샷처럼 라이트/다크 모드에서 가시성과 미관을 유지하기 위해 다른 색 구성이 필요한 이미지에 특히 유용해요. 이 기능을 쓰려면 이미지의 두 버전을 모두 제공해야 해요.

마크다운 편집기로 업로드한 이미지

마크다운 편집기에서 이미지를 직접 업로드(드래그 앤 드롭)할 때, 이미지 URL 끝에 URI 프래그먼트 #hf-light-mode-only 또는 #hf-dark-mode-only를 추가해 어떤 테마에서 표시할지 지정하면 돼요.

Image only displays when viewing in light mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-light.png#hf-light-mode-only)

Image only displays when viewing in dark mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-dark.png#hf-dark-mode-only)

이미 호스팅된 이미지

다시 업로드하지 않고 이미 호스팅된 이미지를 참조하려면, 다음 Tailwind CSS 클래스가 있는 HTML <img> 태그를 사용해 어떤 테마에 표시할지 지정하세요.

<!-- Image only displays when viewing in dark mode -->
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

<!-- Image only displays when viewing in light mode -->
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />

모델 카드에 LaTeX를 쓸 수 있나요?

네! 허브는 KaTeX 수학 타입세팅 라이브러리를 사용해 Markdown을 파싱하기 전에 수학 공식을 서버 측에서 렌더링해요.

다음 구분자를 사용해야 해요.

표시 모드: $$ ... $$
인라인 모드: \$...\$ (슬래시와 괄호 사이에 공백 없음)