Hub documentation

모델 카드

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

모델 카드

모델 카드란 무엇인가요?

Model card는 모델과 함께 제공되며 유용한 정보를 담고 있는 파일입니다. 내부적으로 Model card는 추가 메타데이터가 포함된 단순한 Markdown 파일입니다. Model card는 검색 가능성, 재현성, 공유에 필수적입니다! 어떤 모델 저장소에서든 README.md 파일로 Model card를 찾을 수 있습니다.

모델 카드는 다음을 설명해야 합니다:

모델
Mitchell, 2018에 자세히 설명된 편향 및 윤리적 고려 사항과 같은 의도된 용도 및 잠재적 한계
학습 매개변수 및 실험 정보(참고로 실험 추적 플랫폼에 임베드하거나 링크할 수 있습니다)
모델을 학습하는 데 어떤 데이터셋이 사용되었나요
모델의 평가 결과

모델 카드 템플릿은 여기에서 사용할 수 있습니다.

모델 카드의 각 섹션을 작성하는 방법은 the Annotated Model Card에 설명되어 있습니다.

Hub의 Model Cards에는 중복되는 정보가 있는 두 가지 주요 부분이 있습니다:

메타데이터
텍스트 설명

모델 카드 메타데이터

모델 저장소는 README.md를 모델 카드로 렌더링합니다. 모델 카드는 Markdown 파일이며, 상단에 모델에 대한 메타데이터를 포함하는 YAML 섹션이 있습니다.

모델 카드에 추가하는 메타데이터는 모델의 검색 및 사용 편의성을 높이는 데 도움이 됩니다. 예를 들어:

https://huggingface.co/models에서 사용자가 모델을 필터링할 수 있도록 허용합니다.
모델의 라이선스를 표시합니다.
메타데이터에 데이터셋을 추가하면 모델 페이지에 Datasets used to train:라는 메시지가 표시되고, Hub에 해당 데이터셋이 있는 경우 관련 데이터셋으로 링크됩니다.

Dataset 및 language 식별자는 Datasets 및 Languages 페이지에 나열된 것입니다.

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

모델 카드에 메타데이터를 추가하는 방법은 다음과 같이 여러 가지가 있습니다:

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

Hub 통합이 포함된 많은 라이브러리는 모델을 업로드할 때 모델 카드에 메타데이터를 자동으로 추가합니다.

메타데이터 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

지정되지 않은 경우 Hub는 라이브러리 유형을 자동으로 감지하려고 시도합니다. 그러나 이러한 방식은 권장되지 않으며, 저장소 생성자는 가능한 한 명시적인 library_name을 사용해야 합니다.

*.nemo 또는 *.mlmodel와 같은 파일의 존재를 확인하여 Hub는 해당 모델이 NeMo 또는 CoreML에서 온 것인지 판별할 수 있습니다.
과거에는 감지된 항목이 없고 config.json 파일이 있는 경우, 라이브러리가 transformers인 것으로 간주되었습니다. 2024년 8월 이후 생성된 모델 저장소의 경우 더 이상 그렇지 않으므로, library_name: transformers를 명시적으로 설정해야 합니다.

기본 모델 지정

모델이 기본 모델의 fine-tune, adapter 또는 양자화 버전인 경우, 모델 카드의 메타데이터 섹션에서 기본 모델을 지정할 수 있습니다. 이 정보는 또한 모델이 여러 기존 모델의 merge임을 나타내는 데에도 사용할 수 있습니다. 따라서 base_model 필드는 단일 모델 ID이거나, 하나 이상의 base_models(각각의 Hub 식별자로 지정) 목록일 수 있습니다.

base_model: HuggingFaceH4/zephyr-7b-beta

이 메타데이터는 모델 페이지에서 베이스 모델을 표시하는 데 사용됩니다. 사용자는 이 정보를 사용하여 베이스 모델별로 모델을 필터링하거나 특정 베이스 모델에서 파생된 모델을 찾을 수도 있습니다:

For a fine-tuned model:

For an adapter (LoRA, PEFT, etc):

For a quantized version of another model:

For a merge of two or more models:

병합(Merge)의 경우, 두 개 이상의 base_models 목록을 지정합니다:

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

Hub는 현재 모델에서 기본 모델로의 관계 유형("adapter", "merge", "quantized", "finetune")을 추론하지만, 필요에 따라 명시적으로 설정할 수도 있습니다. 예를 들어 base_model_relation: quantized처럼요.

새 버전 지정

Hub에서 모델의 새 버전이 사용 가능한 경우, new_version 필드에 이를 지정할 수 있습니다.

예를 들어, l3utterfly/mistral-7b-v0.1-layla-v3에서:

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

이 메타데이터는 모델 페이지에서 해당 모델의 최신 버전으로 연결되는 링크를 표시하는 데 사용됩니다. new_version에 연결된 모델에도 new_version 필드가 있는 경우, 항상 가장 최신 버전이 표시됩니다.

데이터셋 지정

모델 카드의 메타데이터 섹션에서 모델을 학습하는 데 사용한 데이터셋을 지정할 수 있습니다. 데이터셋은 모델 페이지에 표시되며, 사용자는 데이터셋별로 모델을 필터링할 수 있습니다. 데이터셋의 저장소 이름과 동일한 Hub 데이터셋 식별자를 사용해야 합니다:

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

버킷 지정

모델 카드의 메타데이터 섹션에서 모델에 연결된 storage buckets를 지정할 수 있습니다. 해당 버킷은 모델 페이지에 태그로 표시되며, 연결된 버킷 페이지에는 해당 모델이 표시됩니다. Hub 버킷 식별자는 버킷의 저장소 이름과 동일하므로 이를 사용해야 합니다:

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

작업 지정(pipeline_tag)

pipeline_tag은 모델 카드 메타데이터에서 지정할 수 있습니다. pipeline_tag는 해당 모델이 의도된 작업의 유형을 나타냅니다. 이 태그는 모델 페이지에 표시되며, 사용자는 Hub에서 작업을 기준으로 모델을 필터링할 수 있습니다. 이 태그는 또한 모델에 사용할 widget과 내부적으로 사용할 API를 결정하는 데에도 사용됩니다.

transformers 모델의 경우 파이프라인 태그는 모델의 config.json 파일에서 자동으로 추론되지만, 필요 시 모델 카드 메타데이터에서 이를 재정의할 수 있습니다. 메타데이터 UI에서 이 필드를 편집하면 파이프라인 태그가 유효한지 확인할 수 있습니다. Hub 통합이 있는 다른 라이브러리들도 모델 카드 메타데이터에 파이프라인 태그를 자동으로 추가합니다.

라이선스 지정

모델 카드의 메타데이터 섹션에서 라이선스를 지정할 수 있습니다. 라이선스는 모델 페이지에 표시되며, 사용자는 라이선스별로 모델을 필터링할 수 있습니다. 메타데이터 UI를 사용하면 가장 일반적인 라이선스 목록이 드롭다운으로 표시됩니다.

필요한 경우, license 값으로 other를 지정하고 메타데이터에 license 이름과 링크를 지정하여 custom license를 지정할 수도 있습니다.

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

라이선스가 URL을 통해 제공되지 않는 경우, 모델 저장소에 저장된 LICENSE에 링크를 걸 수 있습니다.

평가 결과

모델 카드 메타데이터에 모델의 평가 결과를 구조화된 방식으로 지정할 수 있습니다. Hub에서 결과를 파싱하여 모델 페이지의 위젯에 표시합니다. bigcode/starcoder 모델의 경우 다음과 같이 표시됩니다:

The initial metadata spec was based on Papers with code’s model-index specification. This allowed us to directly index the results into Papers with code’s leaderboards when appropriate. You could also link the source from where the eval results has been computed.

NEW: 평가 결과를 위한 더 간단하고 새로운 메타데이터 형식을 제공합니다. 전용 문서 페이지에서 확인해 보세요.

아래는 01-ai/Yi-34B의 ARC 벤치마크 점수를 설명하는 모델 인덱스의 일부 예시입니다. 해당 결과는 source로 정의된 Open LLM Leaderboard에서 가져온 것입니다:

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

이 데이터의 포맷팅 방법에 대한 자세한 내용은 Model Card specifications를 확인하세요.

CO2 배출량

모델 카드에는 모델의 CO₂ 영향에 대한 정보를 보여주는 데에도 적합합니다. 자세한 내용은 CO₂ 배출량 추적 및 보고 가이드를 참고하세요.

종이 연결하기

모델 카드에 Paper 페이지 링크(HF 또는 Arxiv abstract/PDF)가 포함된 경우, Hugging Face Hub는 arXiv ID를 추출하여 arxiv:<PAPER ID> 형식으로 모델 태그에 포함합니다. 해당 태그를 클릭하면 다음을 수행할 수 있습니다:

Paper 페이지를 방문하세요
같은 논문을 인용하는 Hub의 다른 모델로 필터링합니다.

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

모델 카드 텍스트

모델 카드의 사람이 읽을 수 있는 부분을 작성하는 방법에 대한 자세한 내용은 Annotated Model Card에서 확인할 수 있습니다.

자주 묻는 질문

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

각 모델 페이지의 헤더, 모델 이름 아래에 해당 모델의 모든 태그가 나열됩니다. 이러한 태그는 주로 모델 카드 메타데이터에서 계산되며, 일부는 위젯 활성화에 설명된 대로 자동으로 추가됩니다.

모델에 사용자 지정 태그를 추가할 수 있나요?

네, 모델 카드 메타데이터의 tags 필드에 태그를 추가하여 모델에 사용자 정의 태그를 붙일 수 있습니다. 메타데이터 UI에서 인기 있는 태그를 제안하지만, 원하는 태그를 자유롭게 추가할 수 있습니다. 예를 들어, 모델이 금융 분야에 초점을 맞추고 있음을 나타내려면 finance 태그를 추가할 수 있습니다.

모든 사용자에게 적합하지 않은 모델임을 어떻게 표시할 수 있나요

모델 카드 메타데이터에 not-for-all-audiences 태그를 추가할 수 있습니다. 이 태그가 존재하면 모델 페이지에 해당 모델이 모든 사용자에게 적합하지 않다는 메시지가 표시됩니다. 사용자는 이 메시지를 클릭하여 모델 카드를 볼 수 있습니다.

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

각 테마에 최적화된 이미지의 서로 다른 버전을 표시할 수 있습니다. 이는 라이트 모드와 다크 모드에서 가독성과 미적 요소를 유지하기 위해 다른 색상 스킴이 필요한 로고, 다이어그램 또는 스크린샷에 특히 유용합니다. 이 기능을 사용하려면 이미지의 두 버전 모두를 제공해야 합니다.

마크다운 편집기를 통해 업로드된 이미지에 대해

Markdown 편집기에서 이미지를 직접 업로드할 때(드래그 앤 드롭 사용) 이미지 URL 끝에 #hf-light-mode-only 또는 #hf-dark-mode-only URI 단편을 추가하여 해당 이미지가 표시될 테마를 지정합니다:

Image only displays when viewing in light mode
![Logo](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2Flogo-light.png%23hf-light-mode-only%3C%2Fspan%3E)

Image only displays when viewing in dark mode
![Logo](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2Flogo-dark.png%23hf-dark-mode-only%3C%2Fspan%3E)%3C!----%3E%3C%2Fpre%3E%3C%2Fdiv%3E%3C!----%3E 이미지가 이미 호스팅된 경우
 이미지를 다시 업로드하지 않고 이미 호스팅된 이미지를 참조하려면, 다음 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를 작성할 수 있나요?
 네! Hub는 Markdown을 파싱하기 전에 수식 렌더링을 서버 측에서 수행하기 위해 KaTeX 수식 typesetting 라이브러리를 사용합니다.
 다음 구분자를 사용해야 합니다:
 $$ ... $$ 은 디스플레이 모드에 사용됩니다
 \\(...\\)은 인라인 모드에 사용됩니다(슬래시와 괄호 사이에 공백이 없습니다).
 이렇게 작성할 수 있습니다:  $\LaTeX$   $\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$   $E=mc^2$ 
  Update on GitHub

←모델 허브 탄소 배출량→