# Máy chủ 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 theo dõi 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. Để tìm hiểu thêm về webhooks trên Huggingface Hub, bạn có thể đọc [hướng dẫn](https://huggingface.co/docs/hub/webhooks) về Webhooks.

> [!TIP]
> Xem [hướng dẫn](../guides/webhooks_server) này để có hướng dẫn từng bước về cách thiết lập máy chủ webhooks của bạn và triển khai nó dưới dạng một Space.

> [!WARNING]
> Đây là một tính 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. Một cảnh báo sẽ được kích hoạt khi bạn sử dụng một tính năng thử nghiệm. Bạn có thể tắt nó bằng cách đặt `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` như một biến môi trường.

## Máy chủ

Máy chủ là một ứng dụng [Gradio](https://gradio.app/). 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, cùng với một API để lắng nghe các webhook. Việc triển khai một điểm cuối webhook đơn giản như việc trang trí một hàm. Sau đó, bạn có thể gỡ lỗi bằng cách chuyển hướng các Webhooks đến máy của mình (sử dụng đường hầm Gradio) trước khi triển khai lên một Space.

### WebhooksServer[[huggingface_hub.WebhooksServer]]

#### huggingface_hub.WebhooksServer[[huggingface_hub.WebhooksServer]]

```python
huggingface_hub.WebhooksServer(*args, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L37)

**Tham số:**

ui (`gradio.Blocks`, tùy chọn) : Một instance Gradio UI được sử dụng làm trang đích của Space. Nếu `None`, một UI hiển thị các hướng dẫn về các webhook đã cấu hình sẽ được tạo ra.

webhook_secret (`str`, optional) : Một khóa bí mật để xác thực các yêu cầu webhook đến. Bạn có thể đặt giá trị này thành bất kỳ bí mật nào bạn muốn, miễn là bạn cũng cấu hình nó trong [bảng cài đặt webhook](https://huggingface.co/settings/webhooks) của bạn. Bạn cũng có thể đặt giá trị này dưới dạng biến môi trường `WEBHOOK_SECRET`. Nếu không cung cấp bí mật, các điểm cuối webhook sẽ được mở mà không có bất kỳ bảo mật nào.

Lớp [WebhooksServer()](/docs/huggingface_hub/v2.4.0/vi/package_reference/webhooks_server#huggingface_hub.WebhooksServer) cho phép bạn tạo một instance của ứng dụng Gradio có thể nhận các webhook từ Huggingface. Các webhook này có thể được đăng ký bằng decorator `add_webhook()`. Các endpoint webhook được thêm vào ứng dụng dưới dạng endpoint POST cho FastAPI router. Sau khi tất cả các webhook được đăng ký, bạn phải gọi phương thức `launch` để khởi động ứng dụng.

Khuyến nghị nhận [WebhookPayload](/docs/huggingface_hub/v2.4.0/vi/package_reference/webhooks_server#huggingface_hub.WebhookPayload) làm đối số đầu tiên của hàm webhook. Đây là một mô hình Pydantic chứa tất cả thông tin về sự kiện webhook. Dữ liệu sẽ được tự động phân tích cho bạn.

Xem [hướng dẫn webhooks](../guides/webhooks_server) để có hướng dẫn từng bước về cách thiết lập WebhooksServer của bạn và triển khai nó trên một Space.

> [!WARNING]
> `WebhooksServer` là thử nghiệm. API của nó có thể thay đổi trong tương lai.

> [!WARNING]
> Bạn phải cài đặt `gradio` để sử dụng `WebhooksServer` (`pip install --upgrade gradio`).

Ví dụ:

```python
import gradio as gr
from huggingface_hub import WebhooksServer, WebhookPayload

with gr.Blocks() as ui:
    ...

app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

app.launch()
```

### @webhook_endpoint[[huggingface_hub.webhook_endpoint]]

#### huggingface_hub.webhook_endpoint[[huggingface_hub.webhook_endpoint]]

```python
huggingface_hub.webhook_endpoint(path: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L221)

**Tham số:**

path (`str`, tùy chọn) : Đường dẫn URL để đăng ký hàm webhook. Nếu không được cung cấp, tên hàm sẽ được sử dụng làm đường dẫn. Trong mọi trường hợp, tất cả các webhook đều được đăng ký dưới `/webhooks`.

Decorator để khởi động [WebhooksServer()](/docs/huggingface_hub/v2.4.0/vi/package_reference/webhooks_server#huggingface_hub.WebhooksServer) và đăng ký hàm được trang trí như một điểm cuối webhook.

Đây là công cụ hỗ trợ để bắt đầu nhanh chóng. Nếu bạn cần nhiều linh hoạt hơn (trang đích tùy chỉnh hoặc webhook secret), bạn có thể sử dụng trực tiếp [WebhooksServer()](/docs/huggingface_hub/v2.4.0/vi/package_reference/webhooks_server#huggingface_hub.WebhooksServer). Bạn có thể đăng ký nhiều webhook endpoints (về cùng một server) bằng cách sử dụng decorator này nhiều lần.

Xem [hướng dẫn webhooks](../guides/webhooks_server) để có hướng dẫn từng bước về cách thiết lập máy chủ của bạn và triển khai nó trên một Space.

> [!WARNING]
> `webhook_endpoint` là thử nghiệm. API của nó có thể thay đổi trong tương lai.

> [!WARNING]
> Bạn phải cài đặt `gradio` để sử dụng `webhook_endpoint` (`pip install --upgrade gradio`).

Ví dụ: Cách sử dụng mặc định là đăng ký một hàm làm điểm cuối webhook. Tên hàm sẽ được dùng làm đường dẫn. Máy chủ sẽ tự động khởi động khi thoát (tức là ở cuối script).

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

# Server is automatically started at the end of the script.
```

Cách sử dụng nâng cao: đăng ký một hàm làm điểm cuối webhook và khởi động máy chủ thủ công. Cách này hữu ích nếu bạn đang chạy trong notebook.

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

# Start the server manually
trigger_training.launch()
```

## Payload[[huggingface_hub.WebhookPayload]]

[WebhookPayload](/docs/huggingface_hub/v2.4.0/vi/package_reference/webhooks_server#huggingface_hub.WebhookPayload) là cấu trúc dữ liệu chính chứa payload từ Webhooks. Đây là một class `pydantic`, giúp việc sử dụng với FastAPI trở nên rất dễ dàng. Nếu bạn truyền nó làm tham số cho một webhook endpoint, nó sẽ được xác thực và phân tích tự động thành một đối tượng Python.

Để biết thêm thông tin về payload của webhooks, bạn có thể tham khảo [hướng dẫn](https://huggingface.co/docs/hub/webhooks#webhook-payloads) về Webhooks Payload.

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayload[[huggingface_hub.WebhookPayload]]

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

#### huggingface_hub.WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

```python
huggingface_hub.WebhookPayloadComment(id: str, author: ObjectId, hidden: bool, content: str | None = None, url: WebhookPayloadUrl)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L94)

### WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

#### huggingface_hub.WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

```python
huggingface_hub.WebhookPayloadDiscussion(id: str, num: int, author: ObjectId, url: WebhookPayloadUrl, title: str, isPullRequest: bool, status: typing.Literal['closed', 'draft', 'open', 'merged'], changes: huggingface_hub._webhooks_payload.WebhookPayloadDiscussionChanges | None = None, pinned: bool | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L101)

### WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

#### huggingface_hub.WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

```python
huggingface_hub.WebhookPayloadDiscussionChanges(base: str, mergeCommitId: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L89)

### WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

#### huggingface_hub.WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

```python
huggingface_hub.WebhookPayloadEvent(action: typing.Literal['create', 'delete', 'move', 'update'], scope: str)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L84)

### WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

#### huggingface_hub.WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

```python
huggingface_hub.WebhookPayloadMovedTo(name: str, owner: ObjectId)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L75)

### WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

#### huggingface_hub.WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

```python
huggingface_hub.WebhookPayloadRepo(id: str, owner: ObjectId, head_sha: str | None = None, name: str, private: bool, subdomain: str | None = None, tags: list[str] | None = None, type: typing.Literal['dataset', 'model', 'space'], url: WebhookPayloadUrl)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L112)

### WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

#### huggingface_hub.WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

```python
huggingface_hub.WebhookPayloadUrl(web: str, api: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L70)

### WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

#### huggingface_hub.WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

```python
huggingface_hub.WebhookPayloadWebhook(id: str, version: typing.Literal[3])
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L80)