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

Mở tích hợp WebUI

Open WebUI (126k★) là giao diện trò chuyện tự lưu trữ phổ biến nhất dành cho AI. Với máy chủ API tích hợp của Hermes Agent, bạn có thể sử dụng Open WebUI làm giao diện người dùng web bóng bẩy cho Agent của mình — hoàn thiện với tính năng quản lý cuộc trò chuyện, tài khoản người dùng và giao diện trò chuyện hiện đại.

Kiến trúc​

Open WebUI kết nối với máy chủ API của Hermes Agent giống như kết nối với OpenAI. Tác nhân của bạn xử lý các yêu cầu bằng bộ công cụ đầy đủ — thiết bị đầu cuối, thao tác tệp, tìm kiếm trên web, bộ nhớ, kỹ năng — và trả về phản hồi cuối cùng.

Open WebUI giao tiếp với máy chủ Hermes đến máy chủ, vì vậy bạn không cần API_SERVER_CORS_ORIGINS cho việc tích hợp này.

Thiết lập nhanh​

1. Kích hoạt máy chủ API​

Thêm vào ~/.Hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. Khởi động cổng Hermes Agent​

Hermes gateway

Bạn nên xem:

[API Server] API server listening on http://127.0.0.1:8642

3. Bắt đầu Open WebUI​

Docker run -d -p 3000:8080 \
  -e OpenAI_API_BASE_URL=http://host.Docker.internal:8642/v1 \
  -e OpenAI_API_KEY=your-secret-key \
  --add-host=host.Docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

4. Mở giao diện người dùng​

Đi tới http://localhost:3000. Tạo tài khoản quản trị viên của bạn (người dùng đầu tiên trở thành quản trị viên). Bạn sẽ thấy nhân viên hỗ trợ của mình trong danh sách mô hình thả xuống (được đặt tên theo hồ sơ của bạn hoặc Hermes-agent cho hồ sơ mặc định). Bắt đầu trò chuyện!

Thiết lập soạn thảo Docker​

Để thiết lập lâu dài hơn, hãy tạo Docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OpenAI_API_BASE_URL=http://host.Docker.internal:8642/v1
      - OpenAI_API_KEY=your-secret-key
    extra_hosts:
      - "host.Docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Sau đó:

Docker compose up -d

Định cấu hình qua Giao diện người dùng quản trị​

Nếu bạn muốn định cấu hình kết nối thông qua giao diện người dùng thay vì các biến môi trường:

  1. Đăng nhập để Open WebUI tại http://localhost:3000
  2. Nhấp vào hình đại diện hồ sơ của bạn → Cài đặt quản trị
  3. Vào Kết nối
  4. Trong OpenAI API, hãy nhấp vào biểu tượng cờ lê (Quản lý)
  5. Nhấp vào *** Thêm kết nối mới**
  6. Nhập:
    • URL: http://host.Docker.internal:8642/v1
    • Khóa API: khóa của bạn hoặc bất kỳ giá trị nào không trống (ví dụ: not-needed)
  7. Nhấp vào dấu kiểm để xác minh kết nối
  8. Lưu

Mô hình nhân viên hỗ trợ của bạn bây giờ sẽ xuất hiện trong danh sách mô hình thả xuống (được đặt tên theo hồ sơ của bạn hoặc Hermes-agent cho hồ sơ mặc định).

cảnh báo

Các biến môi trường chỉ có hiệu lực trong lần khởi chạy đầu tiên của Open WebUI. Sau đó, cài đặt kết nối được lưu trữ trong cơ sở dữ liệu nội bộ của nó. Để thay đổi chúng sau này, hãy sử dụng Giao diện người dùng quản trị viên hoặc xóa ổ đĩa Docker và bắt đầu làm mới.

Loại API: Hoàn thành trò chuyện và Phản hồi​

Open WebUI hỗ trợ hai chế độ API khi kết nối với chương trình phụ trợ:

Chế độĐịnh dạngKhi nào nên sử dụng
Hoàn thành cuộc trò chuyện (mặc định)/v1/chat/completionsKhuyến khích. Hoạt động tốt.
Phản hồi (thử nghiệm)/v1/responsesĐối với trạng thái hội thoại phía máy chủ thông qua previous_response_id.

Sử dụng tính năng hoàn thành cuộc trò chuyện (được khuyến nghị)​

Đây là mặc định và không yêu cầu cấu hình bổ sung. Open WebUI gửi các yêu cầu định dạng OpenAI tiêu chuẩn và Hermes Agent sẽ phản hồi tương ứng. Mỗi yêu cầu bao gồm toàn bộ lịch sử hội thoại.

Sử dụng API phản hồi​

Để sử dụng chế độ API phản hồi:

  1. Đi tới Cài đặt quản trị → Kết nối → OpenAI → Quản lý
  2. Chỉnh sửa kết nối Hermes-agent của bạn
  3. Thay đổi Loại API từ "Hoàn thành trò chuyện" thành "Phản hồi (Thử nghiệm)"
  4. Lưu

Với API phản hồi, Open WebUI gửi yêu cầu ở định dạng Phản hồi (mảng input + instructions) và Hermes Agent có thể lưu giữ toàn bộ lịch sử cuộc gọi công cụ qua các lượt thông qua previous_response_id.

ghi chú

Open WebUI hiện quản lý phía máy khách lịch sử hội thoại ngay cả trong chế độ Phản hồi — nó gửi toàn bộ lịch sử tin nhắn trong mỗi yêu cầu thay vì sử dụng previous_response_id. Chế độ API phản hồi chủ yếu hữu ích cho khả năng tương thích trong tương lai khi giao diện người dùng phát triển.

Nó hoạt động như thế nào​

Khi bạn gửi tin nhắn trong Open WebUI:

  1. WebUI mở sẽ gửi yêu cầu POST /v1/chat/completions kèm theo lịch sử tin nhắn và cuộc trò chuyện của bạn
  2. Hermes Agent tạo một phiên bản AIAgent với bộ công cụ đầy đủ
  3. Tác nhân xử lý yêu cầu của bạn — nó có thể gọi các công cụ (thiết bị đầu cuối, thao tác tệp, tìm kiếm trên web, v.v.)
  4. Khi các công cụ thực thi, thông báo tiến trình nội tuyến sẽ truyền đến giao diện người dùng để bạn có thể biết tác nhân đang làm gì (ví dụ: `💻 ls -la`, `🔍 Python 3.12 Release`)
  5. Phản hồi văn bản cuối cùng của tổng đài viên sẽ quay trở lại Open WebUI
  6. Open WebUI hiển thị phản hồi trong giao diện trò chuyện của nó

Nhân viên hỗ trợ của bạn có quyền truy cập vào tất cả các công cụ và khả năng giống như khi sử dụng CLI hoặc Telegram — điểm khác biệt duy nhất là giao diện người dùng.:::tip Tool Progress Khi bật tính năng phát trực tuyến (mặc định), bạn sẽ thấy các chỉ báo nội tuyến ngắn gọn khi các công cụ chạy — biểu tượng cảm xúc của công cụ và đối số chính của nó. Những thông tin này xuất hiện trong luồng phản hồi trước câu trả lời cuối cùng của tổng đài viên, giúp bạn hiểu rõ những gì đang diễn ra ở hậu trường. :::

Tham khảo cấu hình​

Hermes Agent (máy chủ API)​

BiếnMặc địnhMô tả
API_SERVER_ENABLEDfalseKích hoạt máy chủ API
API_SERVER_PORT8642Cổng máy chủ HTTP
API_SERVER_HOST127.0.0.1Địa chỉ ràng buộc
API_SERVER_KEY(bắt buộc)Mã thông báo mang cho auth. Phù hợp với OpenAI_API_KEY.

Open WebUI​

BiếnMô tả
OpenAI_API_BASE_URLURL API của Hermes Agent (bao gồm /v1)
OpenAI_API_KEYPhải không trống. Phù hợp với API_SERVER_KEY của bạn.

Khắc phục sự cố​

Không có mô hình nào xuất hiện trong danh sách thả xuống​

  • Kiểm tra URL có hậu tố /v1: http://host.Docker.internal:8642/v1 (không chỉ :8642)
  • Xác minh cổng đang chạy: curl http://localhost:8642/health sẽ trả về {"status": "ok"}
  • Kiểm tra danh sách mô hình: curl http://localhost:8642/v1/models sẽ trả về danh sách có Hermes-agent
  • Mạng Docker: Từ bên trong Docker, localhost có nghĩa là vùng chứa chứ không phải máy chủ của bạn. Sử dụng host.Docker.internal hoặc --network=host.

Kiểm tra kết nối thành công nhưng không tải mô hình​

Đây hầu như luôn là hậu tố /v1 bị thiếu. Kiểm tra kết nối của Open WebUI là kiểm tra kết nối cơ bản — nó không xác minh hoạt động của danh sách mô hình.

Phản hồi mất nhiều thời gian​

Hermes Agent có thể đang thực hiện nhiều lệnh gọi công cụ (đọc tệp, chạy lệnh, tìm kiếm trên web) trước khi đưa ra phản hồi cuối cùng. Điều này là bình thường đối với các truy vấn phức tạp. Phản hồi xuất hiện cùng một lúc khi tác nhân kết thúc.

Lỗi "Khóa API không hợp lệ"​

Đảm bảo OpenAI_API_KEY của bạn trong Open WebUI khớp với API_SERVER_KEY trong Hermes Agent.

Thiết lập nhiều người dùng với hồ sơ​

Để chạy các phiên bản Hermes riêng biệt cho mỗi người dùng — mỗi phiên bản có cấu hình, bộ nhớ và kỹ năng riêng — hãy sử dụng profiles. Mỗi cấu hình chạy máy chủ API riêng trên một cổng khác nhau và tự động quảng cáo tên cấu hình làm mô hình trong Open WebUI.

1. Tạo hồ sơ và cấu hình máy chủ API​

Hermes profile create alice
Hermes -p alice config set API_SERVER_ENABLED true
Hermes -p alice config set API_SERVER_PORT 8643
Hermes -p alice config set API_SERVER_KEY alice-secret

Hermes profile create bob
Hermes -p bob config set API_SERVER_ENABLED true
Hermes -p bob config set API_SERVER_PORT 8644
Hermes -p bob config set API_SERVER_KEY bob-secret

2. Khởi động từng cổng​

Hermes -p alice gateway &
Hermes -p bob gateway &

3. Thêm kết nối trong Open WebUI​

Trong Cài đặt quản trị → Kết nối → OpenAI API → Quản lý, thêm một kết nối cho mỗi hồ sơ:

| Kết nối | URL | Khóa API | |----------||------|----------| | Alice | http://host.Docker.internal:8643/v1 | alice-secret | | Bob | http://host.Docker.internal:8644/v1 | bob-secret |

Danh sách mô hình thả xuống sẽ hiển thị alice và bob dưới dạng các mô hình riêng biệt. Bạn có thể chỉ định mô hình cho người dùng Open WebUI thông qua bảng quản trị, cung cấp cho mỗi người dùng tác nhân Hermes riêng biệt của họ.

Custom Model Names

Tên model mặc định là tên hồ sơ. Để ghi đè nó, hãy đặt API_SERVER_MODEL_NAME trong .env của cấu hình:

Hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

Linux Docker (không có Docker Desktop)​

Trên Linux không có Docker Desktop, host.Docker.internal không giải quyết theo mặc định. Tùy chọn:

# Option 1: Add host mapping
Docker run --add-host=host.Docker.internal:host-gateway ...

# Option 2: Use host networking
Docker run --network=host -e OpenAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
Docker run -e OpenAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...