주석이 달린 모델 카드 템플릿

주석이 달린 모델 카드 템플릿 (Annotated Model Card Template)

모델 카드를 완성할 때 각 섹션의 역할(개발자, 사회기술 전문가, 프로젝트 조직자)을 안내하는 주석 템플릿이에요. 각 섹션에 무엇을 적어야 하는지 이탤릭체 설명으로 함께 제공됩니다.

출처: 문서

본문

[!TIP] 게시할 준비가 되셨나요? 간결하고 유익하며 사용자 친화적인 모델 릴리스의 필수 단계는 Model Release Checklist를 참고하세요.

템플릿 (Template)

modelcard_template.md 파일

작성 지침 (Directions)

모델 카드를 완전히 채우려면 몇 가지 다른 역할의 입력이 필요합니다. (한 사람이 여러 역할을 맡을 수도 있어요.) 이 역할들을 코드 작성과 학습 실행을 담당하는 개발자(developer), 기술과 사회의 장기적 상호작용 분석에 능숙한 사회기술 전문가(sociotechnic)(변호사, 윤리학자, 사회학자, 권리 옹호자 포함), 그리고 모델의 전체적인 범위와 영향력을 이해하고 카드의 각 부분을 대략적으로 채울 수 있으며 모델 카드 업데이트의 연락 담당 역할을 하는 **프로젝트 조직자(project organizer)**라고 부를게요.

지침은 아래에 이탤릭체로 제공됩니다.

템플릿 변수 이름은 monospace로 표시됩니다.

Model Name

섹션 개요 (Section Overview): 모델 이름과 모델이 무엇인지에 대한 1-2문장 요약을 제공하세요.

model_id

model_summary

Table of Contents

섹션 개요 (Section Overview): 각 섹션으로의 링크와 함께 제공해, 사람들이 파일을 쉽게 이동하거나 TOC를 보존한 채 다른 위치에서 사용/인쇄할 수 있게 합니다.

Model Details

섹션 개요 (Section Overview): 이 섹션은 모델이 무엇인지, 현재 상태, 어디서 왔는지에 대한 기본 정보를 제공합니다. 모델을 참조하려는 누구에게나 유용해야 합니다.

Model Description

model_description

모델에 대한 기본 세부 정보를 제공하세요. 여기에는 아키텍처, 버전, 논문에 소개되었는지, 원본 구현이 가능한지, 창작자가 포함됩니다. 저작권은 여기에 명시해야 합니다. 학습 절차, 파라미터, 중요한 면책 조항에 대한 일반 정보도 이 섹션에서 언급할 수 있습니다.

  • Developed by (개발자): developers

모델을 만든 사람을 나열하세요(가능하면 링크).

  • Funded by (자금 제공자): funded_by

이 모델을 재정적, 컴퓨팅 또는 기타 방식으로 지원·가능하게 한 자금 출처를 나열하세요(가능하면 링크).

  • Shared by [선택]: shared_by

모델을 온라인으로 제공하는 사람/조직을 나열하세요(가능하면 링크).

  • Model type (모델 유형): model_type

"유형"은 다음과 같이 이름 붙일 수 있습니다: 1. 지도/학습 방법 (Supervision/Learning Method) 2. 머신러닝 유형 (Machine Learning Type) 3. 모달리티 (Modality)

  • Language(s) [NLP]: language

시스템이 자연(인간) 언어를 사용하거나 처리할 때 이 필드를 사용하세요.

  • License (라이선스): license

사용 중인 라이선스를 명명하고 링크하세요.

  • Finetuned From Model [선택]: base_model

이 모델이 다른 모델을 기반으로 한다면, 여기에서 그 모델로 링크하세요.

Model Sources [선택]

  • Repository: repo
  • Paper [선택]: paper
  • Demo [선택]: demo

사용자가 모델과 그 세부 정보를 직접 볼 수 있는 소스를 제공하세요. 학습 로그, 교훈 등 추가적인 종류의 리소스는 More Information 섹션에 속합니다. 이 섹션에 하나만 포함한다면 저장소로 링크하세요.

Uses

섹션 개요 (Section Overview): 이 섹션은 모델이 다양한 적용 컨텍스트에서 어떻게 사용되도록 의도되었는지에 대한 질문을 다루고, 모델의 예측 가능한 사용자(모델의 영향을 받는 사람 포함)를 논의하며, 범위 밖으로 간주되거나 모델 오용으로 간주되는 사용을 설명합니다. 이 섹션은 라이선스 사용 세부 정보를 포함하기 위한 것이 아님을 유의하세요. 그것은 라이선스로 직접 링크하세요.

Direct Use

direct_use

미세 조정, 후처리 또는 파이프라인 연결 없이 모델을 어떻게 사용할 수 있는지 설명하세요. 예시 코드 스니펫을 권장합니다.

Downstream Use [선택]

downstream_use

이 모델이 태스크에 대해 미세 조정되거나 더 큰 생태계·앱에 연결될 때 어떻게 사용될 수 있는지 설명하세요. 예시 코드 스니펫을 권장합니다.

Out-of-Scope Use

out_of_scope_use

모델이 예측 가능하게 오용될 수 있는 방법(동작하지 않을 방식으로 사용되는 경우)을 나열하고 사용자가 모델로 해서는 안 되는 일을 다루세요.

Bias, Risks, and Limitations

섹션 개요 (Section Overview): 이 섹션은 예측 가능한 해악, 오해, 기술·사회기술적 한계를 식별합니다. 또한 경고와 잠재적 완화에 대한 정보를 제공합니다. Bias, risk, limitation은 때로 분리할 수 없거나 같은 문제를 가리킬 수 있습니다. 일반적으로 bias와 risk는 사회기술적이고, limitation은 기술적입니다:

  • **Bias(편향)**는 일부 하위 집단에 대한 고정관념 또는 비례하지 않는 성능(편중)입니다.
  • **Risk(위험)**은 모델이 유발할 수 있는 사회적으로 관련 있는 문제입니다.
  • **Limitation(한계)**은 나열된 권장 사항을 따라 해결할 수 있는 예측 가능한 실패 모드입니다.

bias_risks_limitations

이 모델에서 비롯된 알려졌거나 예측 가능한 문제는 무엇인가요?

Recommendations

bias_recommendations

예측 가능한 문제와 관련한 권장 사항은 무엇인가요? 이것은 "이미지를 다운샘플링하세요"부터 명시적 콘텐츠 필터링까지 모든 것을 포함할 수 있습니다.

Training Details

섹션 개요 (Section Overview): 이 섹션은 학습 데이터, 학습 요소의 속도·크기, 학습의 환경 영향 등 학습을 설명하고 복제하는 데 필요한 정보를 제공합니다. Technical Specifications과도 밀접하게 관련되어 있으며, 여기의 콘텐츠는 학습 절차와 관련될 때 그 섹션으로 링크해야 합니다. 모델 입력과 학습 발자취에 대해 더 알고 싶은 사람들에게 유용합니다. 모델이 무엇을 학습하는지의 기초를 알고 싶은 누구에게나 관련이 있어요.

Training Data

training_data

학습 데이터가 무엇인지 1-2문장으로 쓰세요. 이상적으로는 추가 정보를 위해 Dataset Card로 링크합니다. 데이터 전처리나 추가 필터링과 관련된 문서 링크는 여기뿐 아니라 More Information에도 넣을 수 있습니다.

Training Procedure [선택]

Preprocessing

preprocessing

토큰화, 크기 조정/재작성(모달리티에 따라) 등을 자세히 설명하세요.

Speeds, Sizes, Times

speeds_sizes_times

처리량, 시작/종료 시간, 체크포인트 크기 등을 자세히 설명하세요.

Evaluation

섹션 개요 (Section Overview): 이 섹션은 평가 프로토콜, 평가에서 측정되는 것, 결과를 설명합니다. 평가는 이상적으로 최소 두 부분으로, 하나는 일반 성능의 정량적 측정(Testing Data, Factors & Metrics, 벤치마킹으로 할 수 있음)을, 다른 하나는 특정 사회 안전 문제에 대한 성능(Societal Impact Assessment, red-teaming으로 할 수 있음)을 봅니다. 모델 카드 메타데이터에서 모델의 평가 결과를 구조화된 방식으로 지정할 수도 있어요. 결과는 Hub가 파싱해 모델 페이지의 위젯에 표시됩니다. https://huggingface.co/docs/hub/model-cards#evaluation-results 를 참고하세요.

Testing Data, Factors & Metrics

평가는 이상적으로 태스크, 도메인, 인구 하위 그룹 같은 다른 요인에 대해 **분리(disaggregated)**되어야 하며, 예측 가능한 사용 컨텍스트에 가장 의미 있는 메트릭으로 계산되어야 합니다. 다른 하위 그룹에서의 동일한 평가 성능은 그 하위 그룹에 대해 "공정"하다고 합니다. 목표 공정성 메트릭은 모델 사용을 고려할 때 어떤 오류가 더 문제가 될 가능성이 있는지에 따라 결정해야 합니다. 그러나 이 섹션은 가장 흔히 다양한 태스크 벤치마크에 대한 종합적인 평가 성능을 보고하는 데 사용됩니다.

Testing Data

testing_data

테스트 데이터를 설명하거나 그 Dataset Card로 링크하세요.

Factors

testing_factors

모델 동작에 영향을 미칠 예측 가능한 특성은 무엇인가요? 성능 격차를 발견하기 위해 평가는 이상적으로 이러한 요인들에 걸쳐 분리되어야 합니다.

Metrics

testing_metrics

평가에 어떤 메트릭이 사용될 것인가요?

Results

results

결과는 위에서 정의한 Factors와 Metrics에 기반해야 합니다.

Summary

results_summary

결과가 무엇을 말하나요? 일반 청중을 위한 일종의 tl;dr 역할을 할 수 있습니다.

Societal Impact Assessment [선택]

이 자유 텍스트 섹션을 사용해 이 모델이 아동 안전, NCII, 프라이버시, 폭력 같은 사회적 해악 위험에 대해 어떻게 평가되었는지 설명하세요. 다음 질문에 대한 답변 형태일 수 있습니다:

  • 이 모델은 어린이가 사용하기에 안전한가요? 그 이유는?
  • 이 모델은 비자발적 친밀 이미지(CSEM 포함)와 관련된 위험을 평가하도록 테스트되었나요?
  • 이 모델은 폭력 활동 또는 폭력 묘사와 관련된 위험을 평가하도록 테스트되었나요? 결과는? 각 문제에 대한 정량적 수치도 제공할 수 있습니다.

Model Examination [선택]

섹션 개요 (Section Overview): 일부 개발자들이 추가하기 시작한 실험적 섹션으로, 설명 가능성/해석 가능성에 대한 작업이 들어갈 수 있습니다.

model_examination

Environmental Impact

섹션 개요 (Section Overview): 전기 사용량과 탄소 배출 같은 환경 영향 계산에 필요한 정보를 요약합니다.

  • Hardware Type: hardware_type
  • Hours used: hours_used
  • Cloud Provider: cloud_provider
  • Compute Region: cloud_region
  • Carbon Emitted: co2_emitted

탄소 배출은 Lacoste et al. (2019)에 제시된 Machine Learning Impact 계산기로 추정할 수 있습니다.

Technical Specifications [선택]

섹션 개요 (Section Overview): 이 섹션은 모델 목적과 아키텍처, 컴퓨트 인프라에 대한 세부 정보를 포함합니다. 모델 개발에 관심 있는 사람들에게 유용해요. 이 섹션을 작성하려면 보통 모델 개발자가 직접 참여해야 합니다.

Model Architecture and Objective

model_specs

Compute Infrastructure

compute_infrastructure

Hardware

hardware_requirements

최소 하드웨어 요구 사항(예: 처리, 저장, 메모리 요구 사항)은 무엇인가요?

Software

software

Citation [선택]

섹션 개요 (Section Overview): 개발자가 선호하는 이 모델에 대한 인용 방식입니다. 종종 논문입니다.

BibTeX

citation_bibtex

APA

citation_apa

Glossary [선택]

섹션 개요 (Section Overview): 이 섹션은 공통 용어와 메트릭 계산 방식을 정의합니다.

glossary

다양한 청중이 접근 가능하도록 용어를 명확히 정의하세요.

More Information [선택]

섹션 개요 (Section Overview): 이 섹션은 데이터셋 생성, 기술 사양, 교훈, 초기 결과에 대한 글 링크를 제공합니다.

more_information

Model Card Authors [선택]

섹션 개요 (Section Overview): 이 섹션은 모델 카드를 만든 사람들을 나열해, 그 구성에 들어간 상세한 작업에 대한 인정과 책임을 제공합니다.

model_card_authors

Model Card Contact

섹션 개요 (Section Overview): Model Card에 대한 업데이트, 제안 또는 질문이 있는 사람들이 Model Card 작성자에게 연락할 수 있는 방법을 제공합니다.

model_card_contact

How to Get Started with the Model

섹션 개요 (Section Overview): 모델을 사용하는 방법을 보여주는 코드 스니펫을 제공합니다.

get_started_code

다음과 같이 인용하세요: Ozoani, Ezi and Gerchick, Marissa and Mitchell, Margaret. Model Card Guidebook. Hugging Face, 2022. https://huggingface.co/docs/hub/en/model-card-guidebook

더 알아보기 (Learn more)

Annotated Model Card는 개발자·사회기술 전문가·프로젝트 조직자의 역할별로 각 섹션 작성 지침을 이탤릭체 주석으로 제공하는 템플릿이에요. template 변수(model_description, bias_risks_limitations 등)를 실제 값으로 채우고, huggingface_hub의 modelcard_template.md 파일을 템플릿으로 사용하세요. 게시 전에는 Model Release Checklist를 확인하는 것이 좋아요.