Webhook 指南：为模型和数据集设置自动元数据质量审查

本指南将引导您创建一个系统，该系统可以响应 Hub 上用户或组织的模型或数据集的更改，并为更改后的仓库创建“元数据审查”。

我们正在构建什么以及为什么？

在我们深入探讨此特定工作流程中涉及的技术细节之前，我们将快速概述我们正在创建的内容以及原因。

模型卡片和数据集卡片是记录机器学习模型和数据集的重要工具。 Hugging Face Hub 使用包含 YAML 标头块的 README.md 文件来生成模型和数据集卡片。此 YAML 部分定义了与模型或数据集相关的元数据。例如

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
---

此元数据包含有关您的模型或数据集对潜在用户的重要信息。例如，许可证定义了可以使用模型或数据集的条款。 Hub 用户还可以使用 YAML 元数据中定义的字段作为过滤器，以识别符合特定标准的模型或数据集。

由于在此块中定义的元数据对于我们模型和数据集的潜在用户至关重要，因此完成此部分非常重要。在团队或组织环境中，将模型和数据集推送到 Hub 的用户可能对 YAML 元数据块的重要性有不同的熟悉程度。虽然团队中的某人可以承担审查此元数据的责任，但我们可以进行一些自动化来帮助我们解决此问题。结果将是在 Hub 上的仓库更改时自动发布或更新的元数据审查报告。对于我们的元数据质量，此系统的工作方式类似于 CI/CD。

您还可以在此处找到示例审查。

使用 Hub 客户端库创建模型审查卡片

huggingface_hub 是一个 Python 库，允许您与 Hub 交互。我们可以使用这个库从 Hub 下载模型和数据集卡片，使用 DatasetCard.load 或 ModelCard.load 方法。特别是，我们将使用这些方法加载一个 Python 字典，其中包含在我们的模型或数据集卡片的 YAML 中定义的元数据。我们将创建一个小的 Python 函数来包装这些方法并进行一些异常处理。

from huggingface_hub import DatasetCard, ModelCard
from huggingface_hub.utils import EntryNotFoundError 

def load_repo_card_metadata(repo_type, repo_name):
    if repo_type == "dataset":
        try:
            return DatasetCard.load(repo_name).data.to_dict()
        except EntryNotFoundError:
            return {}
    if repo_type == "model":
        try:
            return ModelCard.load(repo_name).data.to_dict()
        except EntryNotFoundError:
            return {}

此函数将返回一个 Python 字典，其中包含与仓库关联的元数据（如果没有元数据，则返回一个空字典）。

{'license': 'afl-3.0'}

创建我们的元数据审查报告

一旦我们有了一个包含与仓库关联的元数据的 Python 字典，我们将为我们的元数据审查创建一个“报告卡”。在这个特定的例子中，我们将通过定义一些我们想要值的元数据字段来审查我们的元数据。例如，我们可能想要确保 license 字段始终已完成。为了评估我们的元数据，我们将计算在我们期望的字段中存在哪些元数据字段，并根据我们想要看到值的所需元数据字段的覆盖率返回一个百分比分数。

由于我们有一个包含元数据的 Python 字典，我们可以循环遍历这个字典来检查我们期望的键是否在那里。如果缺少期望的元数据字段（字典中的键），我们将值赋值为 None。

def create_metadata_key_dict(card_data, repo_type: str):
    shared_keys = ["tags", "license"]
    if repo_type == "model":
        model_keys = ["library_name", "datasets", "metrics", "co2", "pipeline_tag"]
        shared_keys.extend(model_keys)
        keys = shared_keys
        return {key: card_data.get(key) for key in keys}
    if repo_type == "dataset":
        # [...]

此函数将返回一个字典，其中包含表示我们模型或数据集所需的元数据字段的键。字典值将包含为该字段输入的元数据，如果 YAML 中缺少该元数据字段，则包含 None。

{'tags': None,
 'license': 'afl-3.0',
 'library_name': None,
 'datasets': None,
 'metrics': None,
 'co2': None,
 'pipeline_tag': None}

一旦我们有了这个字典，我们就可以创建我们的元数据报告。为了简洁起见，我们不会在此处包含完整的代码，但此 Webhook 的 Hugging Face Spaces 仓库 包含完整的代码。

我们创建一个函数，该函数创建一个 markdown 表格，生成我们在元数据覆盖率字典中拥有的数据的更漂亮版本。

def create_metadata_breakdown_table(desired_metadata_dictionary):
    # [...]
    return tabulate(
        table_data, tablefmt="github", headers=("Metadata Field", "Provided Value")
    )

我们还有一个 Python 函数，用于生成一个分数（表示存在的期望元数据字段的百分比）

def calculate_grade(desired_metadata_dictionary):
    # [...]
    return round(score, 2)

以及一个 Python 函数，用于为我们的元数据审查创建 markdown 报告。此报告包含分数和元数据表，以及对报告内容的解释。

def create_markdown_report(
    desired_metadata_dictionary, repo_name, repo_type, score, update: bool = False
):
    # [...]
    return report

如何自动发布审查？

我们现在有了一个 markdown 格式的元数据审查报告。我们将使用 huggingface_hub 库来发布此审查。我们定义一个函数，该函数接收从 Hub 收到的 Webhook 数据，解析数据，并创建元数据报告。根据之前是否创建过报告，该函数会创建一个新报告或将新问题发布到现有的元数据审查线程。

def create_or_update_report(data):
    if parsed_post := parse_webhook_post(data):
        repo_type, repo_name = parsed_post
    else:
        return Response("Unable to parse webhook data", status_code=400)
    # [...]
    return True

创建 Webhook 以响应 Hub 上的更改

我们现在有了为模型或数据集创建元数据审查报告的核心功能。下一步是使用 Webhooks 自动响应更改。

在您的用户个人资料中创建 Webhook

首先，通过访问 https://huggingface.co/settings/webhooks 创建您的 Webhook。

• 输入您的 Webhook 将监听的一些目标仓库（您可能希望将此限制为您自己的仓库或您所属组织的仓库）。
• 输入一个密钥以使您的 Webhook 更安全（如果您不知道为此选择什么，您可能需要使用密码生成器来为您的密钥生成足够长的随机字符串）。
• 现在我们可以为 Webhook URL 参数传递一个虚拟 URL。

您的 Webhook 将如下所示

创建一个新的机器人用户个人资料

本指南创建一个单独的用户帐户，用于发布元数据审查。

创建 Webhook 监听器

我们现在需要一些方法来监听 Webhook 事件。您可以使用许多可能的工具来监听 Webhook 事件。许多现有服务，例如 Zapier 和 IFTTT，可以使用 Webhooks 来触发操作（例如，他们可以在每次模型更新时发布推文）。在本例中，我们将使用 FastAPI 实现我们的 Webhook 监听器。

FastAPI 是一个 Python Web 框架。我们将使用 FastAPI 创建一个 Webhook 监听器。特别是，我们需要实现一个接受 /webhook 上的 POST 请求的路由。为了进行身份验证，我们将 X-Webhook-Secret 标头与可以传递到我们的 Docker 容器的 WEBHOOK_SECRET 密钥在运行时进行比较。

from fastapi import FastAPI, Request, Response
import os

KEY = os.environ.get("WEBHOOK_SECRET")

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    if request.method == "POST":
        if request.headers.get("X-Webhook-Secret") != KEY:
            return Response("Invalid secret", status_code=401)
        data = await request.json()
        result = create_or_update_report(data)
        return "Webhook received!" if result else result

上述函数将接收 Webhook 事件，并为更改后的仓库创建或更新元数据审查报告。

使用 Spaces 部署我们的 Webhook 应用程序

我们的 main.py 文件包含我们的 Webhook 应用程序所需的所有代码。为了部署它，我们将使用一个 Space。

对于我们的 Space，我们将使用 Docker 来运行我们的应用程序。Dockerfile 复制我们的应用程序文件，安装所需的依赖项，并运行应用程序。为了填充 KEY 变量，我们还将为我们的 Space 设置一个 WEBHOOK_SECRET 密钥，其中包含我们之前生成的密钥。您可以在此处阅读有关 Docker Spaces 的更多信息。

最后，我们需要将 Webhook 设置中的 URL 更新为我们 Space 的 URL。我们可以从上下文菜单中获取 Space 的“直接 URL”。点击“Embed this Space”（嵌入此 Space）并复制“Direct URL”（直接 URL）。

获得此 URL 后，我们可以将其传递到 Webhook 设置中的 Webhook URL 参数。现在，当受监控的存储库发生更改时，我们的机器人应该开始发布评论了！

结论和后续步骤

现在我们有了一个自动元数据审查机器人！以下是一些关于如何在此指南基础上进行构建的想法

• 我们的机器人执行的元数据审查相对粗糙；您可以添加更复杂的规则来审查元数据。
• 您可以使用完整的 README.md 文件进行审查。
• 您可能希望定义对您的组织特别重要的“规则”，并使用 webhook 来检查这些规则是否被遵守。

如果您使用 Webhooks 构建了元数据质量应用程序，请标记我 @davanstrien；我很乐意了解它！