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 实例,其中包含模型卡片的元数据。在此实例上调用.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://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 来填充模板文件。

请注意,你必须安装 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 loginlogin()),你可以通过简单地调用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 指的是一个哈希映射(或键值)上下文,它提供有关模型、数据集或空间的一些高级信息。这些信息可以包括模型的pipeline typemodel_idmodel_description 等详细信息。有关更多详细信息,你可以查看以下指南:模型卡片数据集卡片空间设置。现在让我们看一些有关如何更新这些元数据的示例。

让我们从第一个示例开始

>>> 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 上更新