Hugging Face 的 LOGO

Hub 文档

Webhooks

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

Webhooks

Webhooks 现已公开！

Webhooks 是 MLOps 相关功能的基础。它们允许您监听特定仓库或属于特定用户/组织集的所有仓库（不仅仅是您的仓库，而是任何仓库）的新更改。

您可以使用它们自动转换模型、构建社区机器人，或为您的模型、数据集和 Spaces 构建 CI/CD（以及更多！）。

Webhooks 的文档在下方 – 您也可以浏览我们的 指南，其中展示了 Webhooks 的一些可能用例。

创建您的 Webhook

您可以在 Webhooks 设置中创建新的 Webhooks 并编辑现有的 Webhooks。

Settings of an individual webhook

Webhooks 可以监视仓库更新、Pull Requests、讨论和新评论。甚至可以创建一个 Space 来响应您的 Webhooks！

Webhook 有效载荷

注册 Webhook 后，您将通过指定目标 URL 上的 HTTP POST 调用收到新事件通知。有效载荷以 JSON 格式编码。

您可以在 webhook 设置页面的活动选项卡中查看发送的有效载荷历史记录，也可以重播过去的 webhooks 以便更轻松地调试。

image.png

例如，这是一个 Pull Request 打开时的完整有效载荷：

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

事件

顶层属性 event 始终指定并用于确定事件的性质。

它有两个子属性：event.action 和 event.scope。

event.scope 将是以下值之一：

  • "repo" - 仓库上的全局事件。关联 action 的可能值："create", "delete", "update", "move"。
  • "repo.content" - 仓库内容上的事件，例如新的提交或标签。由于新创建的引用/提交，它也会触发新的 Pull Requests。关联 action 始终为 "update"。
  • "repo.config" - 配置上的事件：更新 Space 密钥，更新设置，更新 DOI，启用或禁用等。关联 action 始终为 "update"。
  • "discussion" - 创建讨论或 Pull Request，更新标题或状态，以及合并。关联 action 的可能值："create", "delete", "update"。
  • "discussion.comment" - 创建、更新和隐藏评论。关联 action 的可能值："create", "update"。

未来可能会添加更多范围。为了处理未知事件，您的 webhook 处理程序可以将缩小范围内的任何操作视为扩大范围内的 "update" 操作。

例如，如果未来添加了 "repo.config.dois" 范围，则您的 webhook 处理程序可以将具有该范围的任何事件视为 "repo.config" 范围上的 "update" 操作。

仓库

在当前版本的 webhooks 中，顶级属性 repo 始终被指定，因为事件始终可以与仓库关联。例如，考虑以下值：

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"tags": [
		"license:other",
		"has_space"
	],
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha 是仓库 main 分支上最新提交的 sha。它仅在 event.scope 以 "repo" 开头时发送，而不发送给讨论和评论等社区事件。

代码变更

在代码变更时，顶层属性 updatedRefs 在仓库事件中指定。它是一个包含已更新引用的数组。以下是示例值：

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

新创建的引用将把 oldSha 设置为 null。已删除的引用将把 newSha 设置为 null。

您可以对特定 pull request 中的新提交、新标签或新分支作出反应。

配置更改

当顶级属性 event.scope 为 "repo.config" 时，会指定 updatedConfig 属性。它是一个包含更新配置的对象。以下是示例值：

"updatedConfig": {
  "private": false
}

或者

"updatedConfig": {
  "xetEnabled": true,
}

或者，当更新的配置键不受 webhook 支持时：

"updatedConfig": {}

目前只支持 private 和 xetEnabled。如果您需要更多配置键，请通过 website@huggingface.co 告知我们。

讨论和 Pull Requests

顶级属性 discussion 在社区事件（讨论和 Pull Requests）中指定。discussion.isPullRequest 属性是一个布尔值，指示讨论是否也是 Pull Request（在 Hub 上，PR 是一种特殊类型的讨论）。以下是示例值：

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

评论

当评论被创建（包括在讨论创建时）或更新时，顶级属性 comment 会被指定。以下是示例值：

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

Webhook 密钥

设置 Webhook 密钥有助于确保发送到您的 Webhook 处理程序 URL 的有效负载确实来自 Hugging Face。

如果您为 Webhook 设置了密钥，它将作为 X-Webhook-Secret HTTP 标头随每个请求发送。仅支持 ASCII 字符。

也可以将密钥直接添加到处理程序 URL 中。例如，将其设置为查询参数：https://example.com/webhook?secret=XXX。

如果您的 Webhook 处理程序访问请求的 HTTP 标头很复杂，这会很有帮助。

速率限制

每个 Webhook 每天（24 小时）限制 1,000 次触发。您可以在 Webhook 设置页面的“活动”选项卡中查看您的使用情况。

如果您需要增加 Webhook 的触发次数，请通过 website@huggingface.co 联系我们。

开发您的 Webhooks

如果您没有 HTTPS 端点/URL，可以尝试使用公共工具进行 webhook 测试。这些工具充当捕获所有发送给它们的请求的万能（捕获所有请求）工具，并返回 200 OK 状态码。Beeceptor 是一个可以用来创建临时 HTTP 端点并查看传入有效载荷的工具。另一个类似的工具是 Webhook.site。

此外，您可以在开发过程中将真实的 Webhook 有效负载路由到您本地机器上运行的代码。这是测试和调试以实现更快集成的好方法。您可以通过将本地主机端口暴露到 Internet 来实现此目的。为此，您可以使用 ngrok 或 localtunnel。

调试 Webhooks

您可以轻松找到最近为您的 webhook 生成的事件。打开 webhook 的活动选项卡。在那里您将看到最近事件的列表。

image.png

您可以在此处查看生成的事件的 HTTP 状态代码和有效负载。此外，您可以通过单击 Replay 按钮来重播这些事件！

注意：当更改 Webhook 的目标 URL 或密钥时，重播事件会将有效负载发送到更新后的 URL。

常见问题

我可以在我的组织而非我的用户帐户上定义 webhook 吗？

不，目前不支持。

我如何订阅 HF 上的所有事件（或整个仓库类型，例如所有模型）？

此功能目前不向最终用户开放，但如果您发送电子邮件至 website@huggingface.co，我们可以为您开启。

< > 在 GitHub 上更新

←集合 操作方法：使用 Auto-Train 进行自动微调→