# モデルカード

## モデルカードとは何ですか？

モデルカードは、モデルに付随するファイルで、便利な情報を提供します。内部構造としては、追加のメタデータを持つシンプルなMarkdownファイルです。モデルカードは、発見可能性、再現性、共有のために不可欠です。モデルカードは、どのモデルリポジトリでも`README.md`ファイルとして確認できます。

モデルカードには、以下を記載する必要があります:
- モデル
- [Mitchell, 2018](https://arxiv.org/abs/1810.03993) に詳述されているように、意図された用途と潜在的な制限（バイアスや倫理的な考慮事項を含む）
- 学習パラメータと実験情報（実験追跡プラットフォームに埋め込みまたはリンクして参照できます）
- モデルの学習に使用されたデータセット
- モデルの評価結果

モデルカードのテンプレートは[こちら](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)で入手できます。

モデルカードの各セクションの記入方法については、[注釈付きモデルカード](https://huggingface.co/docs/hub/model-card-annotated)に説明があります。

Hub上のモデルカードには、情報が重複する2つの主要な部分があります:
- [メタデータ](#model-card-metadata)
- [テキストの説明](#model-card-text)

## モデルカードのメタデータ

モデルリポジトリは、`README.md`をモデルカードとしてレンダリングします。モデルカードは[Markdown](https://en.wikipedia.org/wiki/Markdown)ファイルであり、上部にはモデルに関するメタデータを含む[YAML](https://en.wikipedia.org/wiki/YAML)セクションがあります。

モデルカードに追加するメタデータは、モデルの発見と利用の容易さをサポートします。例えば:

* https://huggingface.co/models でモデルをフィルタリングできるようにします。
* モデルのライセンスを表示します。
* メタデータにデータセットを追加すると、モデルページに`Datasets used to train:`というメッセージが表示され、Hubで利用可能な場合は関連するデータセットへのリンクが追加されます。

Datasetとlanguageの識別子は、[Datasets](https://huggingface.co/datasets)ページと[Languages](https://huggingface.co/languages)ページにリストされているものです。

### モデルカードにメタデータを追加する

モデルカードにメタデータを追加する方法はいくつかあります。以下に示します。
- メタデータUIの使用
- `README.md`ファイルのYAMLセクションを直接編集する
- Pythonライブラリ[`huggingface_hub`](https://huggingface.co/docs/huggingface_hub)については、詳細は[ドキュメント](https://huggingface.co/docs/huggingface_hub/guides/model-cards#update-metadata)を参照してください。

[Hub連携](./models-libraries)を備えた多くのライブラリでは、モデルをアップロードすると、モデルカードにメタデータが自動的に追加されます。

#### メタデータUIの使用

メタデータUIを使用して、モデルカードにメタデータを追加できます。メタデータUIにアクセスするには、モデルページに移動し、モデルカードの右上隅にある`Edit model card`ボタンをクリックします。これにより、モデルカードの`README.md`ファイルを表示するエディターと、メタデータ編集用のUIが開きます。

このUIを使用すると、モデルカードに重要なメタデータを追加でき、提供した情報に基づいて多くのフィールドが自動補完されます。UIを使うことはモデルカードにメタデータを追加する最も簡単な方法ですが、すべてのメタデータフィールドをサポートしているわけではありません。UIでサポートされていないメタデータを追加したい場合は、`README.md`ファイルのYAMLセクションを直接編集できます。

#### `README.md`ファイルのYAMLセクションの編集

`README.md`ファイルのYAMLセクションを直接編集することもできます。モデルカードにYAMLセクションがまだない場合は、ファイルの先頭に`---`を3つ追加してセクションを作成し、関連するメタデータをすべて含め、以下の例のように別の`---`のグループでセクションを閉じます。

```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"
---
```

詳細なモデルカードのメタデータ仕様は、こちらで確認できます。

### ライブラリの指定

モデルカードのメタデータセクションで、サポートされているライブラリを指定できます。サポートされているライブラリについて詳しくは、[こちら](./models-libraries)をご覧ください。ライブラリは、以下の優先順位で指定されます。

1. モデルカードに`library_name`を指定します（モデルが`transformers`モデルでない場合は推奨されます）。この情報は、メタデータUI経由で追加するか、モデルカードのYAMLセクションに直接記述できます。

```yaml
library_name: flair
```

2. サポートされているライブラリの名前のタグがあること

```yaml
tags:
- flair
```

指定されていない場合、Hub はライブラリタイプを自動的に検出しようとします。ただし、このアプローチは推奨されておらず、リポジトリの作成者はできるだけ明示的な`library_name`を使用すべきです。

1. `*.nemo` や `*.mlmodel` のようなファイルの有無を確認することで、Hub はモデルが NeMo 由来か CoreML 由来かを判定できます。
2. 過去には、何も検出されず`config.json`ファイルが存在する場合、ライブラリは`transformers`であると仮定されていました。2024年8月以降に作成されたモデルリポジトリでは、この挙動は変更されたため、`library_name: transformers`を明示的に設定する必要があります。

### ベースモデルの指定

モデルがファインチューニング済み、アダプター、またはベースモデルの量子化バージョンである場合、モデルカードのメタデータセクションでベースモデルを指定できます。この情報は、モデルが複数の既存モデルのマージであることを示すのにも使用できます。したがって、`base_model`フィールドには、単一のモデルID、または1つ以上のベースモデル（Hub識別子で指定）のリストを指定できます。

```yaml
base_model: HuggingFaceH4/zephyr-7b-beta
```

このメタデータは、モデルページ上でベースモデルを表示するために使用されます。ユーザーは、この情報を使用してベースモデルでモデルをフィルタリングしたり、特定のベースモデルから派生したモデルを検索したりすることもできます:

   
      ファインチューニングされたモデルの場合:
      
         
         
      
   
   
      アダプター（LoRA、PEFT など）の場合：
      
         
         
      
   

   
      別のモデルの量子化バージョンについては:
      
        
        
      
   
   
      2つ以上のモデルのマージの場合:
      
        
        
      
   

マージの場合、2つ以上のbase_modelsのリストを指定します:

```yaml
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`では:

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

このメタデータは、モデルページでモデルの最新バージョンへのリンクを表示するために使用されます。`new_version`にリンクされているモデルにも`new_version`フィールドがある場合、常に最新のバージョンが表示されます。

   
   

### データセットの指定

モデルカードのメタデータセクションで、モデルの学習に使用したデータセットを指定できます。データセットはモデルページに表示され、ユーザーはデータセットでモデルをフィルタリングできるようになります。識別子として、データセットのリポジトリ名と同じである Hub のデータセット識別子を使用してください:

```yaml
datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb
```

### バケットの指定

モデルカードのメタデータセクションで、モデルに関連付けられた[ストレージバケット](./storage-buckets)を指定できます。バケットはモデルページにタグとして表示され、関連付けられたバケットページにはそのモデルが表示されます。バケットのHub識別子、つまりバケットのリポジトリ名と同じものを使用してください:

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

### タスク(`pipeline_tag`)の指定

モデルカードのメタデータで`pipeline_tag`を指定できます。`pipeline_tag`は、モデルが対象とするタスクの種類を示します。このタグはモデルページに表示され、ユーザーはHub上でタスク別にモデルをフィルタリングできます。また、このタグは、モデルにどの[widget](./models-widgets#enabling-a-widget)を使用するか、および内部でどのAPIを使用するかを決定するためにも使用されます。

`transformers`のモデルでは、モデルの`config.json`ファイルからパイプラインタグが自動的に推測されますが、必要に応じてモデルカードのメタデータで上書きできます。メタデータUIでこのフィールドを編集すると、パイプラインタグが有効であることが保証されます。Hub統合を備えた他のライブラリも、モデルカードのメタデータにパイプラインタグを自動的に追加します。

### ライセンスの指定

モデルカードのメタデータセクションでライセンスを指定できます。ライセンスはモデルページに表示され、ユーザーはライセンスでモデルをフィルタリングできるようになります。メタデータUIを使用すると、一般的なライセンスのドロップダウンリストが表示されます。

必要に応じて、ライセンスの値に`other`を追加し、メタデータにライセンス名とそのリンクを指定することで、カスタムライセンスを指定することもできます。

```yaml
# 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](https://huggingface.co/bigcode/starcoder)モデルの場合の表示例を以下に示します。

The initial metadata spec was based on Papers with code's [model-index specification](https://github.com/paperswithcode/model-index). 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.

> [!TIP]
> NEW: 評価結果用の新しい、よりシンプルなメタデータ形式が利用可能になりました。[専用のドキュメントページ](./eval-results)で確認してください。

以下は、[01-ai/Yi-34B](https://huggingface.co/01-ai/Yi-34B)のARCベンチマークでのスコアを説明していたモデルインデックスの部分的な例です。この結果は、`source`として定義されている[Open LLM Leaderboard](https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard)から得られたものです。

```yaml
---
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 の仕様](https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1)を参照してください。

### CO2排出量

モデルカードは、モデルのCO2排出量に関する情報を示すのにも最適な場所です。詳しくは、[CO2排出量の追跡と報告に関するガイド](./model-cards-co2)をご覧ください。

### 論文のリンク

モデルカードにPaperページのリンク（HF上またはArxivの要約/PDF）が含まれている場合、Hugging Face HubはarXiv IDを抽出し、`arxiv:<PAPER ID>`という形式でモデルタグに含めます。このタグをクリックすると、以下を行うことができます：

* Paperページをご覧ください
* 同じ論文を引用しているHub上の他のモデルをフィルタリングします。

Paperページの詳細については、[こちら](./paper-pages)をご覧ください。

## モデルカードのテキスト

モデルカードの人間が読める部分（印刷して切り貼りできるようにするため）の記入方法の詳細は、[Annotated Model Card](./model-card-annotated)で確認できます。

## よくある質問

### モデルタグはどのように決定されますか？

各モデルページでは、モデル名の下のページヘッダーに、そのモデルのすべてのタグがリストされています。これらのタグは主にモデルカードのメタデータから計算されますが、[ウィジェットの有効化](./models-widgets#enabling-a-widget)で説明されているように、自動的に追加されるものもあります。

### モデルにカスタムタグを追加できますか？

はい、モデルカードのメタデータ内の`tags`フィールドにタグを追加することで、モデルにカスタムタグを追加できます。メタデータのUIでは人気のあるタグが提案されますが、任意のタグを追加できます。例えば、モデルが金融に特化していることを示すために`finance`タグを追加できます。

### すべてのユーザーに適していないモデルであることをどのように示せばよいですか？

モデルカードのメタデータに`not-for-all-audiences`タグを追加できます。このタグが存在する場合、モデルページには、そのモデルがすべてのユーザー向けではないことを示すメッセージが表示されます。ユーザーはこのメッセージをクリックすることで、モデルカードを表示できます。

### ダークモードとライトモードで異なる画像を表示するにはどうすればよいですか?

各テーマに最適化された画像の異なるバージョンを表示できます。これは、ライトモードとダークモードの両方で可視性と美観を維持するために異なるカラーリングが必要なロゴ、図表、スクリーンショットに特に役立ちます。この機能を使用するには、画像の両方のバージョンを提供する必要があります。

**Markdownエディターでアップロードされた画像について**

Markdown エディターから画像を直接アップロードする（ドラッグ＆ドロップを使用する）場合、画像 URL の末尾に URI フラグメント `#hf-light-mode-only` または `#hf-dark-mode-only` を追加して、表示するテーマを指定します：

```markdown
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)
```

**すでにホストされている画像**

再アップロードせずに、すでにホストされている画像を参照したい場合は、HTMLの`<img>`タグに以下のTailwind CSSクラスを指定して、表示するテーマを指定してください。

```html
// 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](https://katex.org/)という数式組版ライブラリを使用しています。

以下のデリミタを使用する必要があります:
- `$$ ... $$` は表示モード用
- インラインモードには`&#92;&#92;(...\\)`を使用します（スラッシュと括弧の間にスペースを入れないでください）。

その後、次のように記述できるようになります。

$$ \LaTeX $$

$$ \mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2} $$

$$ E=mc^2 $$