Chuyển tới nội dung chính

Nguyên bảo

Kết nối Hermes với Yuanbao, nền tảng nhắn tin doanh nghiệp của Tencent. Bộ điều hợp sử dụng cổng WebSocket để gửi tin nhắn theo thời gian thực và hỗ trợ cả hội thoại trực tiếp (C2C) và nhóm.

thông tin

Yuanbao là một nền tảng nhắn tin doanh nghiệp chủ yếu được sử dụng trong môi trường Tencent và doanh nghiệp. Nó sử dụng WebSocket để liên lạc theo thời gian thực, xác thực dựa trên HMAC và hỗ trợ đa phương tiện bao gồm hình ảnh, tệp và tin nhắn thoại.

Điều kiện tiên quyết​

  • Tài khoản Yuanbao có quyền tạo bot

  • Yuanbao APP_ID và APP_SECRET (từ quản trị viên nền tảng)

  • Gói Python: websockets và `httpx

  • Hỗ trợ truyền thông: `aiofiles ``Cài đặt các phụ thuộc cần thiết:

pip install websockets httpx aiofiles

`

## Thiết lập

### 1. Tạo Bot trong Yuanbao
1. Tải xuống ứng dụng Yuanbao từ [https://yuanbao.tencent.com/](https://yuanbao.tencent.com/)

2. Trong ứng dụng, hãy truy cập **PAI → My Bot** và tạo bot mới
3. Sau khi bot được tạo, hãy sao chép **APP_ID** và **APP_SECRET**

### 2. Chạy Trình hướng dẫn cài đặt

Cách dễ nhất để định cấu hình Yuanbao là thông qua thiết lập tương tác:

``` bash
Hermes gateway setup

`
``Chọn **Yuanbao** khi được nhắc. Trình hướng dẫn sẽ:
1. Yêu cầu APP_ID của bạn

2. Yêu cầu APP_SECRET của bạn
3. Tự động lưu cấu hình

:::tip
URL WebSocket và Miền API được tích hợp sẵn các giá trị mặc định hợp lý. Bạn chỉ cần cung cấp APP_ID và APP_SECRET để bắt đầu.
:::

### 3. Cấu hình biến môi trường

Sau khi thiết lập lần đầu, hãy xác minh các biến này trong 

~/.Hermes/.env

:

``` bash

# Required
YUANBAO_APP_ID=your-app-id
YUANBAO_APP_SECRET=your-app-secret
YUANBAO_WS_URL=wss://API.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://API.yuanbao.example.com

# Optional: bot account ID (normally obtained automatically from sign-token)
# YUANBAO_BOT_ID=your-bot-id

# Optional: internal routing environment (e.g. test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Optional: home channel for cron/notifications (format: direct:<account> or group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# Optional: restrict access (legacy, see Access Control below for fine-grained policies)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

`

### 4. Khởi động Gateway

``` bash
Hermes gateway

`
``Bộ điều hợp sẽ kết nối với cổng Yuanbao WebSocket, xác thực bằng chữ ký HMAC và bắt đầu xử lý tin nhắn.

## Tính năng
- **Cổng WebSocket** — giao tiếp hai chiều theo thời gian thực

- **Xác thực HMAC** — ký yêu cầu an toàn bằng APP_ID/APP_SECRET
- **Nhắn tin C2C** — cuộc trò chuyện trực tiếp giữa người dùng với bot
- **Nhắn tin nhóm** — cuộc trò chuyện trong cuộc trò chuyện nhóm
- **Hỗ trợ phương tiện** — hình ảnh, tệp và tin nhắn thoại qua COS (Lưu trữ đối tượng đám mây)
- **Định dạng đánh dấu** — tin nhắn được tự động chia nhỏ theo giới hạn kích thước của Yuanbao
- **Loại bỏ tin nhắn** — ngăn chặn việc xử lý trùng lặp cùng một tin nhắn
- **Heartbeat/keep-alive** — duy trì sự ổn định của kết nối WebSocket
- **Chỉ báo đang gõ** — hiển thị trạng thái "đang gõ..." trong khi tác nhân xử lý
- **Tự động kết nối lại** — xử lý việc ngắt kết nối WebSocket với độ trễ theo cấp số nhân
- **Truy vấn thông tin nhóm** — truy xuất thông tin chi tiết về nhóm và danh sách thành viên
- **Hỗ trợ Nhãn dán/Biểu tượng cảm xúc** — gửi nhãn dán và biểu tượng cảm xúc TIMFaceElem trong cuộc trò chuyện
- **Auto-sethome** — người dùng đầu tiên nhắn tin cho bot sẽ tự động được đặt làm chủ sở hữu kênh chính
- **Thông báo phản hồi chậm** — gửi tin nhắn chờ khi tổng đài viên mất nhiều thời gian hơn dự kiến

## Tùy chọn cấu hình

### Định dạng ID trò chuyện

Yuanbao sử dụng số nhận dạng tiền tố tùy thuộc vào loại cuộc hội thoại:

| Loại trò chuyện | Định dạng | Ví dụ |
|----------|----------|---------|
| Tin nhắn trực tiếp (C2C) |

direct:<account
` | 
`direct:user123
` |
| Tin nhắn nhóm |

group:<group_code
` | 
`group:grp456
` |

### Tải lên phương tiện

Bộ điều hợp Yuanbao tự động xử lý việc tải lên phương tiện thông qua COS (Bộ lưu trữ đối tượng đám mây của Tencent):
- **Hình ảnh**: Hỗ trợ JPEG, PNG, GIF, WebP
- **Tệp**: Hỗ trợ tất cả các loại tài liệu phổ biến
- **Giọng nói**: Hỗ trợ WAV, MP3, OGG

URL phương tiện được tự động xác thực và tải xuống trước khi tải lên để ngăn chặn các cuộc tấn công SSRF.

## Kênh chủ

Sử dụng lệnh 

/sethome
` trong bất kỳ cuộc trò chuyện Yuanbao (DM hoặc nhóm) nào để chỉ định kênh đó làm **kênh chính**. Các tác vụ đã lên lịch (cron jobs) phân phối kết quả của chúng tới kênh này.

:::tip[Auto-sethome]
Nếu không có kênh chính nào được định cấu hình, người dùng đầu tiên nhắn tin cho bot sẽ tự động được đặt làm chủ sở hữu kênh chính. Nếu kênh trang chủ hiện tại là kênh trò chuyện nhóm thì DM đầu tiên sẽ nâng cấp kênh đó lên kênh trực tiếp.
:::

Bạn cũng có thể đặt thủ công trong 

~/.Hermes/.env

:

``` bash
YUANBAO_HOME_CHANNEL=direct:user_account_id

# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

`

### Ví dụ: Đặt kênh Home
1. Bắt đầu cuộc trò chuyện với bot trong Yuanbao
2. Gửi lệnh: 

/sethome

3. Bot trả lời: "Kênh chủ được đặt thành [chat_name] với ID [chat_id]. Công việc định kỳ sẽ được gửi đến vị trí này."
4. Các công việc định kỳ và thông báo trong tương lai sẽ được gửi đến kênh này

### Ví dụ: Phân phối công việc định kỳ

Tạo một công việc định kỳ:

``` bash
/cron "0 9 * * *" Check server status

`
`Đầu ra theo lịch trình sẽ được gửi đến kênh nhà Yuanbao của bạn vào lúc 9 giờ sáng hàng ngày.

## Mẹo sử dụng

### Bắt đầu cuộc trò chuyện

Gửi bất kỳ tin nhắn nào tới bot trong Yuanbao:

`
hello

`
``Bot phản hồi trong cùng một chuỗi hội thoại.

### Các lệnh có sẵn

Tất cả các lệnh Hermes tiêu chuẩn đều hoạt động trên Yuanbao:

| Lệnh | Mô tả |
|----------|-------------|
| 

/new
` | Bắt đầu một cuộc trò chuyện mới |
| 

/model [provider:model]
` | Hiển thị hoặc thay đổi mô hình |
| 

/sethome
` | Đặt cuộc trò chuyện này làm kênh chính |
| 

/status
` | Hiển thị thông tin phiên |
| 

/help
` | Hiển thị các lệnh có sẵn |

### Gửi tập tin

Để gửi tệp tới bot, chỉ cần đính kèm tệp trực tiếp vào cuộc trò chuyện Yuanbao. Bot sẽ tự động tải xuống và xử lý tệp đính kèm.

Bạn cũng có thể bao gồm một tin nhắn với tệp đính kèm:

`
Please analyze this document

`

### Đang nhận tập tin

Khi bạn yêu cầu bot tạo hoặc xuất tệp, nó sẽ gửi tệp trực tiếp đến cuộc trò chuyện Yuanbao của bạn.

## Khắc phục sự cố

### Bot đang online nhưng không trả lời tin nhắn`**Lý do**: Xác thực không thành công trong quá trình bắt tay WebSocket.

**Khắc phục**:

1. Xác minh APP_ID và APP_SECRET là chính xác
2. Kiểm tra xem URL WebSocket có thể truy cập được không
3. Đảm bảo tài khoản bot có quyền thích hợp
4. Xem lại nhật ký cổng: 
`tail -f ~/.Hermes/logs/gateway.log

### Lỗi "Kết nối bị từ chối"`**Lý do**: URL WebSocket không thể truy cập được hoặc không chính xác.

**Khắc phục**:
1. Xác minh định dạng URL WebSocket (nên bắt đầu bằng 
`wss://

)
2. Kiểm tra kết nối mạng với miền API Yuanbao
3. Xác nhận tường lửa cho phép kết nối WebSocket
4. URL kiểm tra với: 
`curl -I https://[YUANBAO_API_DOMAIN]

### Tải lên phương tiện không thành công`**Lý do**: Thông tin xác thực COS không hợp lệ hoặc máy chủ phương tiện không thể truy cập được.

**Khắc phục**:
1. Xác minh API_DOMAIN là chính xác
2. Kiểm tra xem quyền tải lên phương tiện đã được bật cho bot của bạn chưa
3. Đảm bảo tệp phương tiện có thể truy cập được và không bị hỏng
4. Kiểm tra cấu hình nhóm COS với quản trị viên nền tảng

### Tin nhắn chưa được gửi tới kênh chủ`**Nguyên nhân**: Định dạng ID kênh chính không chính xác hoặc công việc định kỳ chưa được kích hoạt.

**Khắc phục**:
1. Xác minh YUANBAO_HOME_CHANNEL có đúng định dạng
2. Kiểm tra bằng lệnh 

/sethome
` để tự động phát hiện định dạng đúng
3. Kiểm tra lịch công việc định kỳ với 

/status

4. Xác minh bot có quyền gửi trong cuộc trò chuyện mục tiêu

### Ngắt kết nối thường xuyên`**Lý do**: Kết nối WebSocket không ổn định hoặc mạng không đáng tin cậy.

**Khắc phục**:
1. Kiểm tra nhật ký cổng để tìm các mẫu lỗi
2. Tăng thời gian chờ của nhịp tim trong cài đặt kết nối
3. Đảm bảo kết nối mạng ổn định với API Yuanbao
4. Cân nhắc việc bật ghi nhật ký chi tiết: 
`Hermes_LOG_LEVEL=debug

## Kiểm soát truy cập

Yuanbao hỗ trợ kiểm soát truy cập chi tiết cho cả cuộc trò chuyện trực tiếp và nhóm:

``` bash

# DM policy: open (default) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Group policy: open (default) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

`
``Những thứ này cũng có thể được đặt trong 
`config.yaml

:

``` yaml
platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

`

## Cấu hình nâng cao

### Phân đoạn tin nhắn

Yuanbao có kích thước tin nhắn tối đa. Hermes tự động phân chia các phản hồi lớn bằng tính năng phân tách nhận biết Markdown (tôn trọng hàng rào mã, bảng và ranh giới đoạn văn).

### Thông số kết nối

Các tham số kết nối sau được tích hợp vào bộ chuyển đổi với các giá trị mặc định hợp lý:

| Tham số | Giá trị mặc định | Mô tả |
|----------|-----------------|-------------|
| Hết thời gian kết nối WebSocket | 15 giây | Đã đến lúc chờ bắt tay WS |
| Khoảng nhịp tim | 30 giây | Tần số Ping để duy trì kết nối |
| Số lần kết nối lại tối đa | 100 | Số lần thử kết nối lại tối đa |
| Kết nối lại backoff | 1s → 60s (theo cấp số nhân) | Thời gian chờ giữa các lần thử kết nối lại |
| Trả lời nhịp tim | 2 giây | Tần số gửi trạng thái CHẠY |
| Gửi thời gian chờ | 30 giây | Hết thời gian chờ cho các tin nhắn WS gửi đi |

:::note
Các giá trị này hiện không thể cấu hình được thông qua các biến môi trường. Chúng được tối ưu hóa cho việc triển khai Yuanbao điển hình.

:::

### Ghi nhật ký dài dòng

Bật tính năng ghi nhật ký gỡ lỗi để khắc phục sự cố kết nối:

``` bash
Hermes_LOG_LEVEL=debug Hermes gateway

`

## Tích hợp với các tính năng khác

### Công việc định kỳ

Lên lịch các tác vụ chạy trên Yuanbao:

`
/cron "0 */4 * * *" Report system health

`
``Kết quả được gửi đến kênh chủ của bạn.

### Tác vụ nền

Chạy các thao tác dài mà không chặn cuộc trò chuyện:

`
/background Analyze all files in the archive

`

### Tin nhắn đa nền tảng

Gửi tin nhắn từ CLI tới Yuanbao:

`bash
Hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

`

## Tài liệu liên quan
- [Messaging Gateway Overview](./index.md)

- [Slash Commands Reference](/docs/reference/slash-commands.md)
- [Cron Jobs](/docs/user-guide/features/cron.md)
- [Background Sessions](/docs/user-guide/CLI#background-sessions)