Hugging Face's logo

Hub Python Library documentation

创建并共享模型卡片

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

创建并共享模型卡片

huggingface_hub 库提供了一个 Python 接口，用于创建、共享和更新 Model Cards。 请访问专用文档页面，深入了解 Hub 上的 Model Cards 是什么，以及其底层工作原理。

从 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-string。在下面的示例中，我们：

  • 使用 ModelCardData.to_yaml() 将我们定义的元数据转换为 YAML，以便将其插入到模型卡中的 YAML 代码块。
  • 展示如何通过 Python f-string 使用模板变量。
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 模板文件创建 Model Cards。下面是一个基本示例：

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://hf.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://hf.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://hf.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)

您可以在此处查看生成的卡片 here。

如果您希望以拉取请求的形式推送卡片，只需在调用 push_to_hub 时指定 create_pr=True 即可：

card.push_to_hub(repo_id, create_pr=True)

由此命令生成的 PR 可以在此处查看。

更新元数据

在本节中，我们将了解仓库卡片中包含哪些元数据，以及如何更新它们。

metadata 指的是一个哈希映射（或键值对）上下文，用于提供有关模型、数据集或 Space 的一些高层信息。这些信息可以包括模型的 pipeline type、model_id 或 model_description 等详细信息。如需了解更多，请参阅以下指南：Model Card、Dataset Card 和 Spaces Settings。 下面让我们看一些更新这些元数据的示例。

让我们从一个示例开始：

>>> 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
Update on GitHub

←缓存 管理您的 Space→