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-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 来填写模板文件。
请注意,您必须安装 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 身份验证(通过使用 huggingface-cli 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。
更新元数据
在本节中,我们将了解 repo 卡片中的元数据是什么以及如何更新它们。
metadata
指的是一个哈希映射(或键值)上下文,它提供有关模型、数据集或 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