Webhooks

Webhooks là nền tảng cho các tính năng liên quan đến MLOps. Chúng cho phép bạn lắng nghe các thay đổi mới trên các repo cụ thể hoặc trên tất cả các repo thuộc các người dùng/tổ chức nhất định mà bạn quan tâm. Hướng dẫn này trước tiên sẽ giải thích cách quản lý webhooks bằng lập trình. Sau đó, chúng ta sẽ xem cách tận dụng huggingface_hub để tạo một server lắng nghe webhooks và triển khai nó lên một Space.

Hướng dẫn này giả định rằng bạn đã quen thuộc với khái niệm webhook trên Huggingface Hub. Để tìm hiểu thêm về chính các webhook, bạn nên đọc hướng dẫn này trước.

Quản lý Webhooks

huggingface_hub cho phép bạn quản lý webhook của mình theo cách lập trình. Bạn có thể liệt kê các webhook hiện có, tạo webhook mới, cũng như cập nhật, bật, tắt hoặc xóa chúng. Phần này hướng dẫn bạn các thao tác sử dụng các hàm API của Hugging Face Hub.

Tạo một Webhook

Để tạo một webhook mới, hãy sử dụng create_webhook() và chỉ định URL mà các payload sẽ được gửi đến, các sự kiện cần theo dõi, và tùy chọn đặt một domain cùng một secret để tăng cường bảo mật.

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 cũng có thể kích hoạt một Job chạy trên hạ tầng của Hugging Face thay vì gửi payload đến một URL. Trong trường hợp này, bạn cần truyền ID của một Job nguồn.

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook kích hoạt Job với webhook payload trong biến môi trường WEBHOOK_PAYLOAD. Các secrets của Job nguồn không được sao chép sang webhook. Nếu Job được kích hoạt cần secrets (ví dụ HF_TOKEN), hãy truyền chúng bằng secrets={"HF_TOKEN": "hf_***"}. Khi dùng update_webhook(), bạn phải truyền job_id cùng với secrets. Các secrets được liệt kê sẽ thay thế các giá trị đã lưu, chuỗi rỗng sẽ xóa một secret, và tất cả các secrets khác được giữ nguyên. Để biết thêm thông tin về Hugging Face Jobs, phần cứng khả dụng (CPU, GPU) và các script UV, hãy xem tài liệu về Jobs.

Danh sách Webhooks

Để xem tất cả các webhook bạn đã cấu hình, bạn có thể liệt kê chúng bằng list_webhooks(). Điều này hữu ích để xem lại ID, URL và trạng thái của chúng.

from huggingface_hub import list_webhooks

# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
    print(webhook)

Cập nhật Webhook

Nếu bạn cần thay đổi cấu hình của một webhook hiện có, chẳng hạn như URL hoặc các sự kiện mà nó theo dõi, bạn có thể cập nhật nó bằng 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"]
)

Bật và Tắt Webhooks

Bạn có thể muốn tạm thời vô hiệu hóa một webhook mà không xóa nó. Thao tác này có thể thực hiện bằng disable_webhook(), và webhook có thể được kích hoạt lại sau đó bằng enable_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)

Xóa Webhook

Khi một webhook không còn cần thiết nữa, nó có thể bị xóa vĩnh viễn bằng cách sử dụng delete_webhook().

from huggingface_hub import delete_webhook

# Example: Deleting a webhook
delete_webhook("your-webhook-id")

Quản lý Webhooks từ CLI

Tất cả các thao tác nêu trên cũng có sẵn từ giao diện dòng lệnh hf. Điều này đặc biệt hữu ích cho việc viết script và các luồng làm việc dạng agent.

# List all webhooks
>>> hf webhooks ls

# Get details about a specific webhook
>>> hf webhooks info <webhook_id>

# Create a webhook that pings a URL
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased --domain repo

# Create a webhook that triggers a Job
>>> hf webhooks create --job-id <job_id> --watch user:julien-c

# Create a webhook that triggers a Job with your HF token as a secret
>>> hf webhooks create --job-id <job_id> --watch bucket:my-org/my-bucket --secrets HF_TOKEN

# Update an existing webhook
>>> hf webhooks update <webhook_id> --url https://new-url.com/hook

# Enable / disable a webhook
>>> hf webhooks enable <webhook_id>
>>> hf webhooks disable <webhook_id>

# Delete a webhook (with confirmation prompt)
>>> hf webhooks delete <webhook_id>

Tùy chọn --watch sử dụng định dạng type:name trong đó type là một trong model, dataset, space, org hoặc user. Tùy chọn này có thể được lặp lại để theo dõi nhiều mục. Để xem danh sách đầy đủ các tùy chọn, hãy chạy hf webhooks <command> --help. Để biết thêm chi tiết, hãy xem hướng dẫn CLI.

Máy chủ Webhooks

Lớp cơ sở mà chúng ta sẽ sử dụng trong phần hướng dẫn này là WebhooksServer(). Đây là một lớp để cấu hình dễ dàng một máy chủ có thể nhận webhook từ Huggingface Hub. Máy chủ này dựa trên ứng dụng Gradio. Nó có giao diện người dùng để hiển thị các hướng dẫn cho bạn hoặc người dùng của bạn và một API để lắng nghe webhook.

Để xem một ví dụ về máy chủ webhook đang chạy, hãy xem Spaces CI Bot. Đây là một Space khởi động các môi trường tạm thời khi một PR được mở trên một Space.

Đây là một chức năng thử nghiệm. Điều này có nghĩa là chúng tôi vẫn đang tiếp tục cải thiện API. Các thay đổi gây lỗi có thể được đưa ra trong tương lai mà không có thông báo trước. Hãy đảm bảo cố định phiên bản của huggingface_hub trong các yêu cầu của bạn.

Tạo một endpoint

Việc triển khai một điểm cuối webhook đơn giản như việc trang trí một hàm. Hãy xem một ví dụ đầu tiên để giải thích các khái niệm chính:

# 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
        ...

Lưu đoạn mã này vào một tệp có tên 'app.py' và chạy bằng 'python app.py'. Bạn sẽ thấy một thông báo như sau:

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.

Làm tốt lắm! Bạn vừa khởi động một máy chủ webhook! Hãy cùng phân tích chi tiết những gì đã xảy ra:

Khi trang trí một hàm bằng webhook_endpoint(), một đối tượng WebhooksServer() đã được tạo ra ở nền. Như bạn có thể thấy, máy chủ này là một ứng dụng Gradio chạy trên http://127.0.0.1:7860. Nếu bạn mở URL này trong trình duyệt, bạn sẽ thấy một trang đích với các hướng dẫn về các webhook đã đăng ký.
Ứng dụng Gradio là một máy chủ FastAPI bên trong. Một tuyến POST mới /webhooks/trigger_training đã được thêm vào. Đây là tuyến sẽ lắng nghe các webhook và chạy hàm trigger_training khi được kích hoạt. FastAPI sẽ tự động phân tích payload và truyền nó vào hàm dưới dạng một đối tượng WebhookPayload. Đây là một đối tượng pydantic chứa tất cả thông tin về sự kiện đã kích hoạt webhook.
Ứng dụng Gradio cũng mở một đường hầm để nhận các yêu cầu từ internet. Đây là phần thú vị: bạn có thể cấu hình một Webhook tại https://huggingface.co/settings/webhooks trỏ đến máy cục bộ của bạn. Điều này hữu ích để gỡ lỗi cho máy chủ webhook của bạn và lặp lại nhanh chóng trước khi triển khai lên một Space.
Cuối cùng, nhật ký cũng cho bạn biết rằng máy chủ của bạn hiện tại chưa được bảo mật bằng một khóa bí mật. Điều này không gây vấn đề cho việc gỡ lỗi cục bộ nhưng cần lưu ý cho các bước sau.

Mặc định, máy chủ được khởi động ở cuối script của bạn. Nếu bạn đang chạy trong notebook, bạn có thể khởi động máy chủ thủ công bằng cách gọi decorated_function.launch(). Vì một máy chủ duy nhất được sử dụng, bạn chỉ cần khởi động máy chủ một lần ngay cả khi có nhiều endpoint.

Cấu hình Webhook

Bây giờ bạn đã có một máy chủ webhook đang chạy, bạn muốn cấu hình một Webhook để bắt đầu nhận các tin nhắn. Truy cập https://huggingface.co/settings/webhooks, nhấp vào “Add a new webhook” và cấu hình Webhook của bạn. Đặt các kho lưu trữ đích mà bạn muốn theo dõi và URL của Webhook, ở đây là https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

Và như vậy là xong! Bạn giờ có thể kích hoạt webhook đó bằng cách cập nhật kho lưu trữ đích (ví dụ: đẩy một commit). Kiểm tra tab Activity của Webhook để xem các sự kiện đã được kích hoạt. Khi đã có một cấu hình hoạt động, bạn có thể kiểm thử và lặp lại nhanh chóng. Nếu bạn sửa đổi mã và khởi động lại máy chủ, URL công khai của bạn có thể thay đổi. Hãy đảm bảo cập nhật cấu hình webhook trên Hub nếu cần.

Triển khai lên một Space

Giờ đây, khi bạn đã có một máy chủ webhook hoạt động, mục tiêu là triển khai nó lên một Space. Truy cập https://huggingface.co/new-space để tạo một Space. Đặt tên cho nó, chọn Gradio SDK và nhấp vào “Create Space”. Tải mã của bạn lên Space trong một tệp có tên app.py. Space của bạn sẽ tự động khởi động! Để biết thêm chi tiết về Spaces, hãy tham khảo hướng dẫn này.

Máy chủ webhook của bạn hiện đang chạy trên một Space công khai. Trong hầu hết các trường hợp, bạn sẽ muốn bảo mật nó bằng một secret. Hãy vào cài đặt Space của bạn > Mục “Repository secrets” > “Add a secret”. Đặt biến môi trường WEBHOOK_SECRET thành giá trị bạn chọn. Quay lại cài đặt Webhooks và đặt secret trong cấu hình webhook. Bây giờ, chỉ các yêu cầu có secret đúng sẽ được máy chủ của bạn chấp nhận.

Và đây là tất cả! Space của bạn giờ đã sẵn sàng để nhận webhook từ Hub. Vui lòng lưu ý rằng nếu bạn chạy Space trên phần cứng ‘cpu-basic’ miễn phí, nó sẽ bị tắt sau 48 giờ không hoạt động. Nếu bạn cần một Space hoạt động liên tục, bạn nên cân nhắc chuyển sang phần cứng nâng cấp.

Cách sử dụng nâng cao

Hướng dẫn ở trên đã giải thích cách nhanh nhất để thiết lập WebhooksServer(). Trong phần này, chúng ta sẽ xem cách tùy chỉnh nó thêm.

Nhiều điểm cuối

Bạn có thể đăng ký nhiều endpoint trên cùng một server. Ví dụ, bạn có thể muốn có một endpoint để kích hoạt một tác vụ huấn luyện và một endpoint khác để kích hoạt đánh giá mô hình. Bạn có thể thực hiện điều này bằng cách thêm nhiều decorator @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
        ...

Điều này sẽ tạo ra hai điểm cuối:

(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation

Máy chủ tùy chỉnh

Để có thêm sự linh hoạt, bạn cũng có thể tạo trực tiếp một đối tượng WebhooksServer(). Điều này hữu ích nếu bạn muốn tùy chỉnh trang đích của máy chủ. Bạn có thể làm điều này bằng cách truyền một Gradio UI sẽ ghi đè lên giao diện mặc định. Ví dụ, bạn có thể thêm hướng dẫn cho người dùng hoặc thêm một biểu mẫu để kích hoạt thủ công các webhook. Khi tạo một WebhooksServer(), bạn có thể đăng ký các webhook mới bằng trình trang trí add_webhook().

Dưới đây là một ví dụ hoàn chỉnh:

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.launch()

Chúng ta định nghĩa một UI tùy chỉnh bằng cách sử dụng Gradio blocks. Giao diện này sẽ được hiển thị trên trang đích của server.
Chúng ta tạo một đối tượng WebhooksServer() với giao diện người dùng tùy chỉnh và một secret. Secret là tùy chọn và có thể được đặt bằng biến môi trường WEBHOOK_SECRET.
Chúng ta đăng ký một webhook với tên rõ ràng. Thao tác này sẽ tạo ra một endpoint tại /webhooks/say_hello.
Chúng ta đăng ký một webhook với tên ngầm định. Thao tác này sẽ tạo ra một endpoint tại /webhooks/goodbye.
Chúng ta khởi động máy chủ. Đây là bước tùy chọn vì máy chủ của bạn sẽ tự động được khởi động ở cuối script.

Update on GitHub

Hub Python Library

Webhooks

Quản lý Webhooks

Tạo một Webhook

Danh sách Webhooks

Cập nhật Webhook

Bật và Tắt Webhooks

Xóa Webhook

Quản lý Webhooks từ CLI

Máy chủ Webhooks

Tạo một endpoint

Cấu hình Webhook

Triển khai lên một Space

Cách sử dụng nâng cao

Nhiều điểm cuối

Máy chủ tùy chỉnh