Hub documentation
モデルカード
モデルカード
モデルカードとは何ですか？
モデルカードは、モデルに付随するファイルで、便利な情報を提供します。内部構造としては、追加のメタデータを持つシンプルなMarkdownファイルです。モデルカードは、発見可能性、再現性、共有のために不可欠です。モデルカードは、どのモデルリポジトリでもREADME.mdファイルとして確認できます。
モデルカードには、以下を記載する必要があります:
- モデル
- Mitchell, 2018 に詳述されているように、意図された用途と潜在的な制限（バイアスや倫理的な考慮事項を含む）
- 学習パラメータと実験情報（実験追跡プラットフォームに埋め込みまたはリンクして参照できます）
- モデルの学習に使用されたデータセット
- モデルの評価結果
モデルカードのテンプレートはこちらで入手できます。
モデルカードの各セクションの記入方法については、注釈付きモデルカードに説明があります。
Hub上のモデルカードには、情報が重複する2つの主要な部分があります:
モデルカードのメタデータ
モデルリポジトリは、README.mdをモデルカードとしてレンダリングします。モデルカードはMarkdownファイルであり、上部にはモデルに関するメタデータを含むYAMLセクションがあります。
モデルカードに追加するメタデータは、モデルの発見と利用の容易さをサポートします。例えば:
- https://huggingface.co/models でユーザーがモデルをフィルタリングできるようにします。
- モデルのライセンスを表示します。
- メタデータにデータセットを追加すると、モデルページに
Datasets used to train:というメッセージが表示され、Hubで利用可能な場合は関連するデータセットへのリンクが追加されます。
Datasetとlanguageの識別子は、DatasetsページとLanguagesページにリストされているものです。
モデルカードにメタデータを追加する
モデルカードにメタデータを追加する方法はいくつかあります。以下に示します。
- メタデータUIの使用
README.mdファイルのYAMLセクションを直接編集する- Pythonライブラリ
huggingface_hubについては、詳細はドキュメントを参照してください。
Hub連携を備えた多くのライブラリでは、モデルをアップロードすると、モデルカードにメタデータが自動的に追加されます。
メタデータUIの使用
メタデータUIを使用して、モデルカードにメタデータを追加できます。メタデータUIにアクセスするには、モデルページに移動し、モデルカードの右上隅にあるEdit model cardボタンをクリックします。これにより、モデルカードのREADME.mdファイルを表示するエディターと、メタデータ編集用のUIが開きます。
このUIを使用すると、モデルカードに重要なメタデータを追加でき、提供した情報に基づいて多くのフィールドが自動補完されます。UIを使うことはモデルカードにメタデータを追加する最も簡単な方法ですが、すべてのメタデータフィールドをサポートしているわけではありません。UIでサポートされていないメタデータを追加したい場合は、README.mdファイルのYAMLセクションを直接編集できます。
README.mdファイルのYAMLセクションの編集
README.mdファイルのYAMLセクションを直接編集することもできます。モデルカードにYAMLセクションがまだない場合は、ファイルの先頭に---を3つ追加してセクションを作成し、関連するメタデータをすべて含め、以下の例のように別の---のグループでセクションを閉じます。
---
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を明示的に設定する必要があります。
ベースモデルの指定
モデルがファインチューニング済み、アダプター、またはベースモデルの量子化バージョンである場合、モデルカードのメタデータセクションでベースモデルを指定できます。この情報は、モデルが複数の既存モデルのマージであることを示すのにも使用できます。したがって、base_modelフィールドには、単一のモデルID、または1つ以上のベースモデル（Hub識別子で指定）のリストを指定できます。
base_model: HuggingFaceH4/zephyr-7b-betaこのメタデータは、モデルページ上でベースモデルを表示するために使用されます。ユーザーは、この情報を使用してベースモデルでモデルをフィルタリングしたり、特定のベースモデルから派生したモデルを検索したりすることもできます:
マージの場合、2つ以上のbase_modelsのリストを指定します:
base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4Hub は、現在のモデルからベースモデルへの関係のタイプ（"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バケットの指定
モデルカードのメタデータセクションで、モデルに関連付けられたストレージバケットを指定できます。バケットはモデルページにタグとして表示され、関連付けられたバケットページにはそのモデルが表示されます。バケットのリポジトリ名と同じである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を使用すると、一般的なライセンスのドロップダウンリストが表示されます。
必要に応じて、ライセンスの値に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へのリンクを設定できます。
評価結果
モデルの評価結果を、モデルカードのメタデータに構造化された形式で指定できます。結果は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ベンチマークでのスコアを説明していたmodel-indexの部分的な例です。この結果は、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 の仕様を参照してください。
CO2排出量
モデルカードは、モデルのCO2への影響に関する情報を示すのにも最適な場所です。詳しくは、CO2排出量の追跡と報告に関するガイドをご覧ください。
論文のリンク
モデルカードにPaperページのリンク（HF上またはArxivの要約/PDF）が含まれている場合、Hugging Face HubはarXiv IDを抽出し、arxiv:<PAPER ID>という形式でモデルタグに含めます。このタグをクリックすると、以下を行うことができます：
- Paperページをご覧ください
- 同じ論文を引用しているHub上の他のモデルをフィルタリングします。
Paperページの詳細については、こちらをご覧ください。
モデルカードのテキスト
モデルカードの人間が読める部分（印刷して切り貼りできるようにするため）の記入方法の詳細は、Annotated Model Cardで確認できます。
よくある質問
モデルタグはどのように決定されますか？
各モデルページでは、モデル名の下のページヘッダーに、そのモデルのすべてのタグがリストされています。これらのタグは主にモデルカードのメタデータから計算されますが、ウィジェットの有効化で説明されているように、自動的に追加されるものもあります。
モデルにカスタムタグを追加できますか？
はい、モデルカードのメタデータ内のtagsフィールドにタグを追加することで、モデルにカスタムタグを追加できます。メタデータのUIでは人気のあるタグが提案されますが、任意のタグを追加できます。例えば、モデルが金融に特化していることを示すためにfinanceタグを追加できます。
すべてのユーザーに適していないモデルであることをどのように示せばよいですか？
モデルカードのメタデータにnot-for-all-audiencesタグを追加できます。このタグが存在する場合、モデルページには、そのモデルがすべてのユーザー向けではないことを示すメッセージが表示されます。ユーザーはこのメッセージをクリックすることで、モデルカードを表示できます。
ダークモードとライトモードで異なる画像を表示するにはどうすればよいですか?
各テーマに最適化された画像の異なるバージョンを表示できます。これは、ライトモードとダークモードの両方で可視性と美観を維持するために異なるカラーリングが必要なロゴ、図表、スクリーンショットに特に役立ちます。この機能を使用するには、画像の両方のバージョンを提供する必要があります。
Markdownエディターでアップロードされた画像について
Markdown エディターから画像を直接アップロードする（ドラッグ＆ドロップを使用する）場合、画像 URL の末尾に URI フラグメント #hf-light-mode-only または #hf-dark-mode-only を追加して、表示するテーマを指定します：
Image only displays when viewing in light mode
Image only displays when viewing in dark mode
すでにホストされている画像
再アップロードせずに、すでにホストされている画像を参照したい場合は、HTMLの<img>タグに以下のTailwind CSSクラスを指定して、表示するテーマを指定してください。
// 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という数式組版ライブラリを使用しています。
以下のデリミタを使用する必要があります:
$$ ... $$は表示モード用- インラインモードには
\\(...\\)を使用します（スラッシュと括弧の間にスペースを入れないでください）。
次に、次のように記述できるようになります。
Update on GitHub