Hub Python 庫文件
建立和分享模型卡片
並獲得增強的文件體驗
開始使用
建立和分享模型卡片
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 例項，其中包含模型卡片的元資料。在此例項上呼叫.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-字串的另一種方法。在以下示例中，我們
- 使用 ModelCardData.to_yaml() 將我們定義的元資料轉換為 YAML，以便我們可以將其用於在模型卡片中插入 YAML 塊。
- 展示瞭如何透過 Python f-字串使用模板變數。
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來填充模板檔案。
請注意，您必須安裝 Jinja2 才能使用 from_template。您可以使用 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)
您可以在此處檢視生成的卡片。
如果您想以拉取請求的形式推送卡片，只需在呼叫 push_to_hub 時將 create_pr=True 即可。
card.push_to_hub(repo_id, create_pr=True)由此命令建立的 PR 可以在此處檢視。
更新元資料
本節我們將瞭解倉庫卡片中的元資料是什麼以及如何更新它們。
metadata 指的是一個雜湊對映（或鍵值）上下文，它提供有關模型、資料集或空間的一些高階資訊。這些資訊可以包括模型型別、模型 ID 或模型描述等詳細資訊。有關更多詳細資訊，您可以檢視這些指南：模型卡片、資料集卡片和空間設定。現在我們來看一些如何更新這些元資料的示例。
我們從第一個示例開始
>>> 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)您經常會遇到想要建議對沒有寫入許可權的倉庫進行一些更改的情況。您可以透過在該倉庫上建立拉取請求來實現，這將允許所有者審查和合並您的建議。
>>> 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