Hugging Face 모델 카드 작성 가이드

[choincnp]

HuggingFace 모델 카드

Hugging Face 모델 카드(Model Card) 는 머신러닝 모델과 함께 제공되는 문서로, 해당 모델에 대한 다양한 정보를 담은 README 파일이자, 모델에 대한 설명서이자 사용 가이드입니다.

전체적인 내용

Markdown(.md) 형식으로 구성되어 있으며, 다음과 같은 작성 요소를 가집니다.

• 모델 설명
• 모델 사용 목적 및 잠재적 한계(편향성 및 윤리적 고려 사항 포함)
• 훈련 매개변수 및 실험 정보(링크 있으면 좋다)
• 모델 훈련에 사용된 데이터셋
• 모델 평가 결과

예시

https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct

모델 카드는 왜 작성해야 할까?

5가지 이유로 알아보는 작성 이유

• 투명성: 모델의 의도, 구성, 성능, 한계 등을 공개하여 신뢰를 높임 .
• 재현성: 실험 설정과 데이터를 명시하여 다른 이들이 재현 가능하도록 도움.
• 책임성: 모델의 위험성과 편향을 인정하고 명시하여 책임 있는 사용을 유도.
• 지식 공유: 모델 사용법과 상세 정보를 공유하여 연구 및 개발 커뮤니티에 기여.
• 표준화: 모델 정보를 체계적으로 정리해, 업계 표준에 따른 문서화 실천.

모델 카드 작성의 장점 (사용자 입장 vs 배포자 입장)

사용자 입장

사용자는 모델 카드 덕분에 해당 모델이 어떤 작업에 적합한지, 어떻게 사용할 수 있는지 바로 알 수 있습니다. 예를 들어 모델 카드에 사용 가능한 언어, 지원되는 라이브러리, 라이선스 등의 메타데이터가 포함되어 있으면, Hugging Face Hub의 모델 검색 페이지에서 필터링을 통해 손쉽게 원하는 모델을 찾을 수 있습니다 .

또한 모델 카드에는 간단한 사용 예제 코드가 제공되는 경우가 많아, 사용자가 빠르게 모델을 실행해볼 수 있습니다. 무엇보다 모델의 한계나 편향 정보가 있다면, 사용자가 부적절한 용도로 모델을 쓰지 않도록 경각심을 갖게 해줍니다.

배포자 입장

잘 정리된 모델 카드는 다른 사람들이 모델을 올바로 이해하고 활용하게 해 주어 모델 영향력 확대로 이어집니다. 또한 모델 카드에 연구 논문이나 참고 문헌 (예: arXiv 논문 링크, BibTeX) 정보를 포함하면, 사용자들이 모델의 배경 연구를 찾아보고 **인용(citation)**할 수 있어 연구자의 공로를 인정받는 통로가 됩니다.

Hugging Face Hub는 모델 카드와 연계하여 Digital Object Identifier (DOI) 발급 기능도 제공하므로, 모델 자체를 학술적으로 인용할 수도 있습니다.

모델 카드 작성하기

모델 카드의 구조

• 메타데이터
• 텍스트 설명

메타데이터

메타데이터는 2가지 방식을 이용해서 기록할 수 있습니다.

• Readme.md파일에 yaml형식으로 작성
• Hub의 UI 이용해서 작성
  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
metrics:
- metric1
- metric2
base_model: "base model Hub identifier"
---

Hub의 UI

Hugging Face 모델 카드의 구조와 작성 방법

Hugging Face는 모델 카드 작성에 대해 권장되는 템플릿 구조를 제공하고 있습니다 . 2022년 Hugging Face Science 팀은 Model Card Guidebook을 발표하며 기존 연구와 업계 관행을 반영한 업데이트된 모델 카드 템플릿과 Annotated Model Card 예시, 그리고 모델 카드 생성 도구를 소개했습니다 . 아래에서는 Hugging Face 권장 포맷을 중심으로 모델 카드의 주요 섹션과 각 섹션에 포함할 내용을 설명합니다. (물론 모든 모델에 모든 항목이 적용되는 것은 아니며, 필요에 따라 Optional로 표시된 섹션은 생략 가능함을 유의하세요.)

모델 카드 주요 섹션

섹션	주요 내용 및 작성 요령
Model Details (모델 세부정보)	모델의 기본 정보: 모델 설명(모델 아키텍처, 목적, 배경 논문 여부, 개발자 및 지원 기관, 버전 등), 개발자(만든 이들), 지원 기관(펀딩 출처), 공유자(온라인에 공개한 주체), 모델 유형(예: 지도학습/비지도, 모델 계열 등), 언어(NLP의 경우), 라이선스(모델 사용 허가 범위 명시), 출처 모델(파인튜닝한 베이스 모델이 있다면 명시) 등을 포함합니다 . 필요하다면 저작권 표기나 중요한 사용상의 주의도 함께 언급합니다.
Model Sources (optional)	모델 관련 추가 자료 소스: Repository(모델 코드 저장소나 구현체), Paper(논문이 있다면 링크), Demo(데모 웹페이지나 앱) 등을 링크로 제공합니다 .
Uses (사용 방법과 범위)	모델의 의도된 활용 분야와 사용 방법을 설명합니다. 구체적으로 Direct Use(즉시 활용 방법: 예시 입력/출력과 간단한 코드 스니펫 포함 권장 ), Downstream Use(파인튜닝이나 응용 예 ), 그리고 Out-of-Scope Use(모델의 비의도적 사용 혹은 오용 사례 명시 )로 구성됩니다. 이 섹션에서는 이 모델이 잘 작동하도록 설계되지 않은 분야나 잘못된 사용법을 분명히 적시하여 사용자를 교육시키는 것이 중요합니다. 예를 들어 “이 모델은 의학적 조언을 제공하도록 만들어지지 않았으므로 의료 분야에 단독으로 사용해서는 안 됩니다”와 같은 경고를 포함할 수 있습니다.
Bias, Risks, and Limitations(편향, 위험 및 한계)	모델의 잠재적 편향(특정 하위집합에 대한 성능 편차), 사회적 위험(유해 출력, 잘못 사용시 영향) 및 기술적 한계를 정리합니다 . 이 섹션은 모델이 어떤 상황에서 부정확하거나 문제가 발생할 수 있는지 알려주며, 이를 완화하기 위한 **권고사항(Recommendations)**도 함께 기술합니다 . 예를 들어 “이 모델은 어린이에게 부적절한 내용을 생성할 수 있으므로 미성년자 사용에 주의가 필요함” 또는 “특정 언어권 데이터가 부족해 해당 언어에 성능이 낮을 수 있음”과 같은 내용을 작성합니다.
How to Get Started (Usage)	모델 사용법을 간략히 안내하는 섹션으로, 일반적으로 예제 코드를 포함합니다. Hugging Face Transformers 나 Pipelines를 활용하여 inference하는 방법을 코드 블록으로 제공하고, 필요시 모델 허깅페이스 토크나이저 사용 예 등을 보여줍니다. (예: from transformers import AutoModel, AutoTokenizer … 등의 코드 스니펫) 이를 통해 사용자가 빠르게 시작할 수 있도록 돕습니다.
Training Details (훈련 세부정보)	모델의 훈련과정에 대한 정보입니다. Training Data(사용한 데이터셋 설명 및 링크 ), Training Procedure(훈련 절차 설명)로 구성되며, 세부 항목으로 전처리(Preprocessing) 방법 , 훈련 하이퍼파라미터 및 환경(예: epoch 수, 배치 크기, 최적화기 등), 훈련 소요 시간 및 자원(Speeds, Sizes, Times: GPU종류, 수행 시간, 체크포인트 크기 등 ) 등을 기술합니다. 연구용 모델이라면 이 부분에 충분한 상세 정보를 포함해 다른 연구자가 참고할 수 있게 해야 합니다.
Evaluation (평가)	모델의 평가 방법과 결과를 나타냅니다. 사용한 테스트 데이터(및 해당 데이터셋 카드 링크)와 평가지표를 명시하고 , 다양한 조건에서의 성능(요인 Factors: 예를 들어 입력 길이별 성능, 언어별 성능 등)도 가능하면 분류하여 보고합니다 . 그런 다음 **결과(Results)**를 기술하며, 중요한 내용은 표나 그래프로 요약할 수도 있습니다. 마지막으로 **요약(Summary)**을 통해 일반 독자를 위한 핵심 해설을 덧붙이면 좋습니다 . 특히 연구용 모델이라면, 벤치마크 결과를 경쟁 모델과 비교하거나 논문에서 주장하는 바를 뒷받침하는 데이터를 포함하면 모범적입니다. 또한 **Societal Impact (사회적 영향 평가)**를 별도 섹션으로 추가해, 모델이 유발할 수 있는 사회적 위험 요소 (예: 증오발언 생성 여부, 프라이버시 침해 가능성 등)에 대한 테스트 결과나 분석을 담으면 더욱 책임감 있는 카드가 됩니다.
Environmental Impact (환경 영향)	모델 훈련에 따른 탄소 배출량 등 환경적 영향을 요약합니다 . 예를 들어 사용한 하드웨어 종류, 훈련 시간(hours), 클라우드 리전, 추정 탄소 배출량 (CO2) 등을 기재합니다 . 탄소 배출량은  에서 소개된 Machine Learning Impact 계산기를 활용하여 추산할 수 있습니다. 이 섹션은 모델 훈련/배포와 환경의 상관관계에 관심 있는 독자들에게 유용한 정보입니다.
Technical Specifications (optional)	모델의 기술적 상세를 기술합니다. 모델의 **아키텍처 및 목표(Objective)**를 설명하고, **컴퓨팅 인프라(Compute Infrastructure)**를 상세히 기록합니다 . 하위 항목으로 Hardware 요구사항(추론 또는 재훈련 시 필요한 최소 사양)과 Software 요구사항(필요한 라이브러리, 드라이버 버전 등) 등을 포함하여 모델을 활용하거나 재훈련하려는 사람들이 사전에 알아야 할 기술 정보를 제공합니다 .
Citation (인용) (optional)	해당 모델과 관련된 논문이나 리포트의 인용 정보를 제공합니다. 일반적으로 BibTeX 형식과 APA 형식 두 가지로 인용문을 제시하여, 사용자가 편리하게 참고 문헌으로 활용할 수 있게 합니다 .
Glossary (용어 설명) (optional)	모델 카드에서 사용된 용어나 지표의 정의를 제공합니다. 예를 들어 “BLEU 점수”에 대해 설명하거나, “스퓨리어스 커릴레이션”과 같은 용어가 등장했다면 간단히 풀이를 쓰는 식입니다 . 용어 설명은 다양한 배경의 독자가 모델 카드를 이해하는 데 도움을 줍니다.
More Information (추가 정보) (optional)	모델과 관련된 추가 자료나 글을 링크합니다. 예를 들어 데이터셋 카드, 모델 구조 상세 블로그 글, 문제 해결 노트, 모델 데모 영상 또는 모델의 초기 결과분석 보고 등을 연결할 수 있습니다 .
Model Card Authors (optional)	모델 카드를 작성하는 데 기여한 사람들의 목록을 적습니다. 작성자에게 크레딧을 주고, 동시에 책임 소재를 분명히 하는 효과가 있습니다 .
Model Card Contact	모델 카드에 대한 문의나 수정 제안을 보낼 연락처를 명시합니다. 일반적으로 이메일 주소나 Hugging Face 사용자의 프로필 링크 등을 적습니다 . 이를 통해 사용자가 카드 내용에 질문이나 개선 요청을 할 수 있습니다.

작성 시 유의사항 및 팁

• 명확하고 간결한 서술: 각 섹션의 내용을 명확히 전달하되 과도한 마케팅 용어는 지양합니다. 특히 성능 관련 섹션에서는 숫자와 사실에 기반해 서술하고, 한계 및 편향 섹션에서는 솔직하게 문제점을 밝히는 것이 좋습니다.
• 일관성 유지: 모델 카드 내에서 사용되는 용어 정의(예: “정확도(accuracy)“의 의미 등)를 일관되게 사용하세요. 필요한 경우 용어집(Glossary)를 활용해 용어를 정의합니다.
• 메타데이터 활용: 모델 카드 최상단의 YAML 메타데이터 필드에 언어, 태스크, 라이선스, 데이터셋, 라이브러리 등을 정확히 기입하세요. 이 메타데이터는 Hugging Face Hub에서 모델 검색 필터로 사용되며, 모델 페이지 상단에 자동으로 라이선스 표시나 “Datasets used to train” 같이 데이터셋 링크를 보여주는 등 다양한 용도로 활용됩니다 . 메타데이터는 UI 편집기를 통해 추가할 수도 있고, 수동으로 YAML 헤더를 편집해 넣을 수도 있습니다 .
• 예제 코드 제공: 가능하다면 간단한 예제 코드를 포함하여 사용자가 금방 모델을 써볼 수 있도록 합니다. 예를 들어 텍스트 생성 모델이라면 pipeline을 이용한 생성 예제, 분류 모델이면 AutoModelForSequenceClassification으로 문장 분류하는 예제 등을 넣습니다. 코드 블록을 사용할 때에는 Markdown 문법을 지켜 가독성을 높이세요.
• 라이선스 및 법적 주의사항: 모델의 라이선스 조항을 명확히 하고, 만약 별도 사용 제한이 있다면(예: 비상업적 사용만 가능 등) 모델 카드 서두나 Model Details 부분에 눈에 띄게 명시합니다. 또한 데이터 저작권이나 프라이버시 이슈 등 법적 고려사항이 있다면 언급하는 것이 좋습니다.
• 업데이트 및 유지보수: 모델이 개선되거나 새로운 평가 결과가 나오면 모델 카드를 갱신(update)해야 합니다. Hugging Face Hub에서는 모델 카드 수정을 Pull Request로 관리할 수도 있고, 모델 카드 작성자(Model Card Authors)를 통해 여러 명이 함께 관리할 수 있습니다. 최신 정보로 유지되는 모델 카드가 신뢰도가 높습니다.

모델 카드 작성 예시 소개

• BLOOM 모델 카드 (bigscience/bloom)
  • 악용하지 않도록 방법 예시
• Whisper 모델 카드 (openai/whisper):
  • 음성 인식 모델
  • 언어별 성능 차이 상세 기술 / 한계 또는 bias 명시
• Stable Diffusion 모델 카드 (CompVis/stable-diffusion)

각기 다른 도메인의 모델 카드를 살펴보면, 도메인별로 강조해야 할 섹션이 다를 수 있음을 알 수 있습니다. 자연어 모델은 사회언어학적 편향과 사용 용도를, 음성 모델은 정확도 한계와 오디오 품질 이슈를, 생성 모델은 윤리적 사용 지침을 특히 강조하는 식입니다. 자신의 모델 특성에 맞춰 중요한 내용을 빠짐없이 담는 것이 좋은 모델 카드의 핵심입니다.

모델 카드 템플릿과 작성 자동화 도구 활용

모델 카드를 처음부터 모든 내용을 손으로 작성하는 것은 벅찰 수 있습니다.
Hugging Face와 커뮤니티에서는 모델 카드 생성을 돕는 템플릿과 도구들을 제공합니다.

HF Hub Template

• Hugging Face Hub 템플릿: Hugging Face Hub의 huggingface_hub 파이썬 라이브러리에는 공식 모델 카드 템플릿과 유틸리티가 내장되어 있습니다 . 예를 들어 huggingface_hub 라이브러리의 ModelCard 및 ModelCardData 클래스를 사용하면 파이썬 코드로 모델 카드를 조작할 수 있습니다. Hugging Face에 따르면 이 라이브러리를 통해 모델 카드를 생성, 공유, 수정하는 인터페이스를 쓸 수 있습니다 . 아래는 간단한 사용 예시입니다:

from huggingface_hub import ModelCard, ModelCardData

# 1. 메타데이터 정의 (언어, 라이선스, 태그 등)
card_data = ModelCardData(language='en', license='mit', tags=['text-classification'])

# 2. 카드 콘텐츠 작성 (YAML 메타데이터 + Markdown 본문)
content = f"""
---
{card_data.to_yaml()}
---

# My Model Name

이 모델은 [@username](https://huggingface.co/username)이 생성한 것입니다. 
"""
card = ModelCard(content)

# 3. Hugging Face Hub에 모델 카드 업로드 (새 모델 리포지토리를 생성하고 PR로 카드 제출)
card.push_to_hub("username/my-model-repo", create_pr=True)

위 코드는 ModelCardData로 메타데이터 YAML을 쉽게 생성한 뒤, f-string으로 템플릿에 끼워 넣어 ModelCard 객체를 만들고 있습니다. push_to_hub 메소드를 통해 해당 내용을 Hugging Face Hub에 바로 올릴 수도 있으며, create_pr=True 옵션을 주면 곧바로 모델 카드 변경 사항이 Pull Request로 제출되어 공동 작업자들과 검토할 수도 있습니다 . huggingface_hub은 또한 Jinja2 템플릿을 이용한 카드 생성 기능도 제공하여, 반복되는 양식을 보다 간편히 채워 넣을 수 있습니다 . Hugging Face 공식 깃허브에는 모델 카드의 raw 템플릿 (modelcard_template.md)이 공개되어 있으므로 이를 기반으로 커스텀 템플릿을 만들어 활용해도 됩니다 .

Jinja 템플릿

from pathlib import Path
from huggingface_hub import ModelCard, ModelCardData

# 템플릿 정의 및 파일로 저장
template_text = """
---
{{ card_data }}
---
# {{ model_name }} 모델 카드

이 모델은 {{ purpose }}를 위해 개발되었습니다.
개발자: {{ developer }}
""".strip()
Path('template.md').write_text(template_text)

# 카드 생성
card_data = ModelCardData(language='ko', license='mit', library_name='transformers')
card = ModelCard.from_template(
    card_data, 
    template_path='template.md',
    model_name='KoBERT',
    purpose='한국어 감성 분석',
    developer='HuggingFace Korea'
)

다른 자동화 도구

• Hugging Face Model Card 작성 UI: Hugging Face는 모델 카드 작성을 쉽게 하기 위해 웹 기반 UI 도구도 제공하고 있습니다. Hugging Face Spaces 중 Model_Cards_Writing_Tool이라는 Space가 그것으로, 사용자가 양식에 따라 모델 정보를 입력하면 Markdown 카드 초안을 생성해줍니다. UI 상에서 메타데이터 필드 입력, 각 섹션별 마크다운 작성, 미리보기 등이 가능하여 매우 편리합니다.
• Model Card Generator (Intel의 model_card_gen): Intel에서 개발한 오픈소스 도구인 Model Card Generator는 스트림릿(Streamlit) 기반의 대화형 UI로 모델 카드를 작성하도록 도와줍니다. Intel의 설명에 따르면 이 도구는 복잡한 모델 정보를 시각적이고 상호작용적인 형식으로 정리하여, 개발자, 비즈니스 이해관계자 등 누구든 모델의 능력과 한계를 쉽게 파악할 수 있게 해줍니다 . intel-xai-tools 저장소의 model_card_gen 패키지로 제공되며, 로컬에서 실행하거나 Docker로 구동할 수 있습니다 . 모델 카드를 일종의 대시보드 형태로 만들어주는 개념으로, 특히 모델 성능 분석(예: 임계값별 지표, 그룹별 성능) 섹션을 시각화하여 담아낼 수 있는 점이 특징입니다. 이 도구를 사용하면 연구자가 자신의 모델 카드에 시각적 요소와 대화형 콘텐츠(예: 그래프 상의 슬라이더로 임계값 조정 등)를 포함하는 것도 가능해집니다. 작성이 완료된 후에는 결과를 Markdown 혹은 HTML 보고서로 저장할 수 있어, Hugging Face 모델 카드에 포함시키거나 별도 문서로 배포할 수 있습니다.

결론

Hugging Face Model Card는 오늘날 머신러닝 모델 공개의 필수 요소로 자리잡고 있으며, 투명하고 책임있는 AI를 구현하는 데 핵심적인 역할을 합니다. 연구 목적으로 모델을 공유할 때도 모델 카드를 충실히 작성하면 다른 연구자들에게 큰 도움이 되고, 자신의 연구 가치를 극대화할 수 있습니다. 모델 카드에는 모델의 이력과 설명, 사용법, 성능, 한계 등이 망라되어야 하며, Hugging Face의 권장 템플릿을 따르면 이러한 내용을 체계적으로 담을 수 있습니다. 또한 공식 도구와 커뮤니티 툴을 활용하면 모델 카드 작성 과정을 효율화하면서도 높은 품질을 유지할 수 있습니다. 투명성, 재현성, 책임성을 고려한 모델 카드를 작성하여, 더 나은 AI 생태계를 만드는 데 동참해 봅시다 :)