Hub Python 库文档
Webhooks
并获得增强的文档体验
开始使用
Webhooks
Webhooks 是 MLOps 相关功能的基础。它们允许您监听特定仓库或您感兴趣的所有用户/组织所属的所有仓库的新更改。本指南将首先解释如何以编程方式管理 Webhooks。然后我们将看到如何利用 huggingface_hub
创建一个监听 Webhooks 的服务器并将其部署到 Space。
本指南假设您熟悉 Huggingface Hub 上 Webhooks 的概念。要了解有关 Webhooks 本身的更多信息,您应该首先阅读这篇指南。
管理 Webhooks
huggingface_hub
允许您以编程方式管理您的 Webhooks。您可以列出现有的 Webhooks,创建新的,以及更新、启用、禁用或删除它们。本节将指导您使用 Hugging Face Hub 的 API 函数完成这些操作。
创建 Webhook
要创建新的 Webhook,请使用 create_webhook() 并指定应发送有效负载的 URL、应监视的事件,以及可选地设置域和密钥以确保安全。
from huggingface_hub import create_webhook
# Example: Creating a webhook
webhook = create_webhook(
url="https://webhook.site/your-custom-url",
watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
domains=["repo", "discussion"],
secret="your-secret"
)
列出 Webhook
要查看您配置的所有 Webhook,可以使用 list_webhooks() 列出它们。这对于查看它们的 ID、URL 和状态非常有用。
from huggingface_hub import list_webhooks
# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
print(webhook)
更新 Webhook
如果您需要更改现有 Webhook 的配置,例如 URL 或其监视的事件,您可以使用 update_webhook() 进行更新。
from huggingface_hub import update_webhook
# Example: Updating a webhook
updated_webhook = update_webhook(
webhook_id="your-webhook-id",
url="https://new.webhook.site/url",
watched=[{"type": "user", "name": "new-username"}],
domains=["repo"]
)
启用和禁用 Webhook
您可能希望暂时禁用 Webhook 而不删除它。这可以使用 disable_webhook() 完成,并且之后可以使用 enable_webhook() 重新启用 Webhook。
from huggingface_hub import enable_webhook, disable_webhook
# Example: Enabling a webhook
enabled_webhook = enable_webhook("your-webhook-id")
print("Enabled:", enabled_webhook)
# Example: Disabling a webhook
disabled_webhook = disable_webhook("your-webhook-id")
print("Disabled:", disabled_webhook)
删除 Webhook
当不再需要 Webhook 时,可以使用 delete_webhook() 永久删除它。
from huggingface_hub import delete_webhook
# Example: Deleting a webhook
delete_webhook("your-webhook-id")
Webhooks 服务器
本指南部分将使用的基类是 WebhooksServer()。它是一个用于轻松配置能够从 Huggingface Hub 接收 Webhooks 的服务器的类。该服务器基于 Gradio 应用程序。它有一个 UI 来显示您或您的用户的说明,以及一个 API 来监听 Webhooks。
要查看 Webhook 服务器的运行示例,请查看 Spaces CI Bot。它是一个在 Space 上打开 PR 时启动临时环境的 Space。
这是一个实验性功能。这意味着我们仍在努力改进 API。未来可能会在未经事先通知的情况下引入重大更改。请确保在您的需求中锁定 huggingface_hub
的版本。
创建端点
实现 Webhook 端点就像装饰函数一样简单。让我们看一个解释主要概念的第一个例子
# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload
@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
if payload.repo.type == "dataset" and payload.event.action == "update":
# Trigger a training job if a dataset is updated
...
将此代码片段保存到名为 'app.py'
的文件中,并使用 'python app.py'
运行它。您应该会看到类似以下消息
Webhook secret is not defined. This means your webhook endpoints will be open to everyone. To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: `app = WebhooksServer(webhook_secret='my_secret', ...)` For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. Running on local URL: http://127.0.0.1:7860 Running on public URL: https://1fadb0f52d8bf825fc.gradio.live This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training Go to https://huggingface.co/settings/webhooks to setup your webhooks.
干得好!您刚刚启动了一个 Webhook 服务器!让我们详细分解一下发生了什么
- 通过使用 webhook_endpoint() 装饰函数,已在后台创建了一个 WebhooksServer() 对象。如您所见,此服务器是一个在 http://127.0.0.1:7860 运行的 Gradio 应用程序。如果您在浏览器中打开此 URL,您将看到一个包含已注册 Webhook 说明的登陆页面。
- Gradio 应用程序底层是一个 FastAPI 服务器。它已添加了一个新的 POST 路由
/webhooks/trigger_training
。这是将监听 Webhook 并在触发时运行trigger_training
函数的路由。FastAPI 将自动解析有效负载并将其作为 WebhookPayload 对象传递给函数。这是一个包含触发 Webhook 的事件所有信息的pydantic
对象。 - Gradio 应用程序还打开了一个隧道来接收来自互联网的请求。这是有趣的部分:您可以在 https://huggingface.co/settings/webhooks 配置一个指向您本地机器的 Webhook。这对于调试您的 Webhook 服务器和在部署到 Space 之前快速迭代非常有用。
- 最后,日志还告诉您您的服务器当前未受密钥保护。这对于本地调试不是问题,但以后需要牢记。
默认情况下,服务器在脚本末尾启动。如果您在 notebook 中运行它,可以通过调用 decorated_function.run()
手动启动服务器。由于使用唯一的服务器,即使您有多个端点,也只需启动服务器一次。
配置 Webhook
现在您已经运行了一个 Webhook 服务器,您需要配置一个 Webhook 以开始接收消息。转到 https://huggingface.co/settings/webhooks,点击“添加新 Webhook”并配置您的 Webhook。设置您要监视的目标存储库和 Webhook URL,这里是 https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
。

就这样!现在您可以通过更新目标存储库(例如,推送提交)来触发该 Webhook。检查 Webhook 的“活动”选项卡以查看已触发的事件。现在您已经设置了一个可用的环境,您可以测试并快速迭代。如果您修改代码并重新启动服务器,您的公共 URL 可能会更改。如果需要,请务必更新 Hub 上的 Webhook 配置。
部署到 Space
现在您已经有了一个可用的 Webhook 服务器,目标是将其部署到 Space。转到 https://huggingface.co/new-space 创建一个 Space。给它一个名称,选择 Gradio SDK,然后点击“创建 Space”。将您的代码上传到 Space 中的 app.py
文件。您的 Space 将自动启动!有关 Spaces 的更多详细信息,请参阅此指南。
您的 Webhook 服务器现在正在公共 Space 上运行。在大多数情况下,您会希望使用密钥对其进行保护。转到您的 Space 设置 > “存储库密钥”部分 > “添加密钥”。将 WEBHOOK_SECRET
环境变量设置为您选择的值。返回Webhooks 设置并在 Webhook 配置中设置密钥。现在,只有具有正确密钥的请求才会被您的服务器接受。
就这样!您的 Space 现在已准备好接收来自 Hub 的 Webhooks。请记住,如果您在免费的“cpu-basic”硬件上运行 Space,它将在不活动 48 小时后关闭。如果您需要永久 Space,您应该考虑将其设置为升级的硬件。
高级用法
上面的指南解释了设置 WebhooksServer() 的最快方法。在本节中,我们将看到如何进一步自定义它。
多个端点
您可以在同一服务器上注册多个端点。例如,您可能希望一个端点触发训练作业,另一个端点触发模型评估。您可以通过添加多个 @webhook_endpoint
装饰器来实现这一点
# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload
@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
if payload.repo.type == "dataset" and payload.event.action == "update":
# Trigger a training job if a dataset is updated
...
@webhook_endpoint
async def trigger_evaluation(payload: WebhookPayload) -> None:
if payload.repo.type == "model" and payload.event.action == "update":
# Trigger an evaluation job if a model is updated
...
这将创建两个端点
(...) Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation
自定义服务器
为了获得更大的灵活性,您还可以直接创建 WebhooksServer() 对象。如果您想自定义服务器的登陆页面,这将非常有用。您可以通过传递将覆盖默认页面的 Gradio UI 来实现此目的。例如,您可以为用户添加说明或添加表单以手动触发 Webhook。创建 WebhooksServer() 时,您可以使用 add_webhook()
装饰器注册新的 Webhook。
这是一个完整的例子
import gradio as gr
from fastapi import Request
from huggingface_hub import WebhooksServer, WebhookPayload
# 1. Define UI
with gr.Blocks() as ui:
...
# 2. Create WebhooksServer with custom UI and secret
app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")
# 3. Register webhook with explicit name
@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
return {"message": "hello"}
# 4. Register webhook with implicit name
@app.add_webhook
async def goodbye(payload: WebhookPayload):
return {"message": "goodbye"}
# 5. Start server (optional)
app.run()
- 我们使用 Gradio 块定义了一个自定义 UI。此 UI 将显示在服务器的登陆页面上。
- 我们创建了一个带有自定义 UI 和密钥的 WebhooksServer() 对象。密钥是可选的,可以使用
WEBHOOK_SECRET
环境变量进行设置。 - 我们注册了一个具有显式名称的 Webhook。这将创建一个位于
/webhooks/say_hello
的端点。 - 我们注册了一个具有隐式名称的 Webhook。这将创建一个位于
/webhooks/goodbye
的端点。 - 我们启动服务器。这是可选的,因为您的服务器将在脚本结束时自动启动。