Hugging Face's logo

Hub Python 函式庫文件

建立並分享模型卡

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

建立並分享模型卡

huggingface_hub 程式庫提供了 Python 介面，讓您可以建立、分享及更新模型卡。請造訪專屬說明頁面，深入了解 Hub 上的模型卡是什麼，以及它們在底層是如何運作的。

從 Hub 載入模型卡

若要從 Hub 載入現有的模型卡，您可以使用 ModelCard.load() 函式。在此範例中，我們將載入 nateraw/vit-base-beans 的模型卡。

from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')

此模型卡具有一些您可能需要存取或利用的實用屬性：

  • card.data：回傳一個 ModelCardData 實例，包含模型卡的中繼資料 (metadata)。在此實例上呼叫 .to_dict() 即可將其轉換為字典格式。
  • card.text：回傳模型卡的文字內容，不包含中繼資料標頭。
  • card.content：回傳模型卡的文字內容，包含中繼資料標頭。

建立模型卡

從文字建立

若要從文字初始化模型卡，只需將卡片的文字內容傳遞給 ModelCard 進行初始化即可。

content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True

另一種做法是使用 f-strings。在以下範例中，我們

  • 使用 ModelCardData.to_yaml() 將我們定義的中繼資料轉換為 YAML，以便將 YAML 區塊插入模型卡中。
  • 展示如何透過 Python f-strings 使用模板變數。
card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)

上述範例將會產生一個如下所示的模型卡：

---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)

從 Jinja 模板建立

如果您安裝了 Jinja2，可以從 jinja 模板檔案建立模型卡。讓我們來看一個基本範例：

from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://huggingface.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)

產生的模型卡 Markdown 看起來像這樣：

---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://huggingface.co/nateraw).

如果您更新任何 card.data，它將會反映在卡片本身。

card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)

現在，您可以看到中繼資料標頭已經更新了。

---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://huggingface.co/nateraw).

在更新卡片資料時，您可以呼叫 ModelCard.validate() 來驗證卡片對於 Hub 而言是否仍然有效。這可確保卡片符合 Hugging Face Hub 上設定的任何驗證規則。

從預設模板建立

除了使用您自己的模板外，您也可以使用預設模板，這是一個功能齊全的模型卡，其中包含許多您可能需要填寫的章節。在底層，它使用 Jinja2 來填寫模板檔案。

請注意，若要使用 from_template，您必須安裝 Jinja2。您可以執行 pip install Jinja2 來安裝。

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)

分享模型卡

如果您已通過 Hugging Face Hub 驗證（使用 hf auth login 或 login()），則只需呼叫 ModelCard.push_to_hub() 即可將模型卡推送到 Hub。讓我們來看看如何操作……

首先，我們將在已驗證使用者的命名空間下建立一個名為 ‘hf-hub-modelcards-pr-test’ 的新儲存庫。

from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)

然後，我們將從預設模板建立一個模型卡（與上述章節中定義的相同）。

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)

最後，我們將其推送到 Hub。

card.push_to_hub(repo_id)

您可以在此處查看產生的模型卡。

如果您想將模型卡以提取請求 (Pull Request) 的方式推送，則在呼叫 push_to_hub 時只需設定 create_pr=True。

card.push_to_hub(repo_id, create_pr=True)

由此命令建立的 PR 可以在此處查看。

更新中繼資料

在本節中，我們將了解儲存庫卡片中有哪些中繼資料以及如何更新它們。

中繼資料 指的是雜湊映射（鍵值對）內容，它提供了有關模型、資料集或 Space 的一些高階資訊。這些資訊可以包括諸如模型的 pipeline type、model_id 或 model_description 等細節。有關更多詳細資訊，您可以參考以下指南：模型卡、資料集卡以及 Spaces 設定。現在讓我們來看一些如何更新這些中繼資料的範例。

讓我們從第一個範例開始。

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})

透過這兩行程式碼，您將更新中繼資料以設定新的 pipeline_tag。

預設情況下，您無法更新卡片上已存在的金鑰。如果您想這麼做，必須明確傳遞 overwrite=True。

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)

您經常會想要對沒有寫入權限的儲存庫提出更改建議。您可以透過在該儲存庫上建立 PR 來做到這一點，這將允許擁有者審核並合併您的建議。

>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

納入評估結果

若要將評估結果納入 model-index 中繼資料，您可以傳遞一個 EvalResult 或包含相關評估結果的 EvalResult 列表。在底層，當您呼叫 card.data.to_dict() 時，它將會建立 model-index。有關其運作方式的更多資訊，您可以查看 Hub 文件中的此章節。

請注意，使用此函式需要在 ModelCardData 中包含 model_name 屬性。

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)

產生的 card.data 應該看起來像這樣：

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7

如果您有多個想要分享的評估結果，只需傳遞一個 EvalResult 列表即可：

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data

這將會產生以下的 card.data：

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65
在 GitHub 上更新

←快取 (Cache) 管理您的 Space→
© . This site is unofficial and not affiliated with Hugging Face, Inc.