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

Máy chủ API

Máy chủ API hiển thị Hermes-agent dưới dạng điểm cuối HTTP tương thích với OpenAI. Bất kỳ giao diện người dùng nào sử dụng định dạng OpenAI — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, v.v. — đều có thể kết nối với Hermes-agent và sử dụng nó làm phụ trợ.

Tác nhân của bạn xử lý các yêu cầu bằng bộ công cụ đầy đủ (terminal, 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. Khi phát trực tuyến, các chỉ báo tiến trình của công cụ xuất hiện nội tuyến để giao diện người dùng có thể hiển thị những gì tổng đài viên đang làm.

One backend covers models + tools

Bản thân Hermes cần một nhà cung cấp được định cấu hình và các công cụ phụ trợ để máy chủ API hoạt động hữu ích. Đăng ký Nous Portal xử lý cả hai - hơn 300 kiểu máy cộng với web/hình ảnh/TTS/trình duyệt thông qua Cổng công cụ. Chạy Hermes setup --portal một lần trước khi khởi động máy chủ API và các giao diện người dùng như Open WebUI hoặc LobeChat có được phần phụ trợ được trang bị đầy đủ công cụ.

Bắt đầu nhanh​

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

Thêm vào

~/.Hermes/.env

:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev

# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

`

### 2. Khởi động cổng

``` bash
Hermes gateway

`
``Bạn sẽ thấy:

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

`

### 3. Kết nối giao diện người dùng

Trỏ bất kỳ ứng dụng khách nào tương thích với OpenAI vào 
`http://localhost:8642/v1

:

`bash

# Test with curl
curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/JSON" \
  -d '\{"model": "Hermes-agent", "messages": [\{"role": "user", "content": "Hello!"}]}'

`
``Hoặc kết nối Open WebUI, LobeChat hoặc bất kỳ giao diện người dùng nào khác — xem [Open WebUI integration guide](/docs/user-guide/messaging/open-webui) để biết hướng dẫn từng bước.

## Điểm cuối

### BÀI ĐĂNG /v1/chat/hoàn thành

Định dạng hoàn thành trò chuyện OpenAI tiêu chuẩn. Không trạng thái - cuộc trò chuyện đầy đủ được bao gồm trong mỗi yêu cầu thông qua mảng 
`messages

.

**Yêu cầu:**

`
``` json
{
  "model": "Hermes-agent",
  "messages": [
    \{"role": "system", "content": "You are a Python expert."},
    \{"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

`
``**Trả lời:**

`
`JSON
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "Hermes-agent",
  "choices": [{
    "index": 0,
    "message": \{"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": \{"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

`
``**Đầu vào hình ảnh nội tuyến:** tin nhắn người dùng có thể gửi 
`content
` dưới dạng một mảng gồm các bộ phận 
`text
` và 
`image_url

. Cả URL 
`http(s)
` từ xa và URL 
`data:image/...
` đều được hỗ trợ:

`JSON
{
  "model": "Hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        \{"type": "text", "text": "What is in this image?"},
        \{"type": "image_url", "image_url": \{"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

`
``Các tệp đã tải lên (
`file
` / 
`input_file
` / 
`file_id

) và các URL 
`data:
` không phải hình ảnh trả về 
`400 unsupported_content_type

.

**Truyền phát** (

"stream": true

): Trả về Sự kiện do máy chủ gửi (SSE) với các đoạn phản hồi theo từng mã thông báo. Đối với **Hoàn thành cuộc trò chuyện**, luồng sử dụng các sự kiện 
`chat.completion.chunk
` tiêu chuẩn cộng với sự kiện 
`Hermes.tool.progress
` tùy chỉnh của Hermes cho UX khởi động công cụ. Đối với **Phản hồi**, luồng sử dụng các loại sự kiện Phản hồi OpenAI như 
`response.created

, 
`response.output_text.delta

, 
`response.output_item.added

, 
`response.output_item.done
` và 
`response.completed

.

**Tiến trình công cụ trong luồng**:

- **Hoàn thành cuộc trò chuyện**: Hermes phát ra 
`event: Hermes.tool.progress
` để hiển thị khi bắt đầu công cụ mà không làm ảnh hưởng đến văn bản trợ lý liên tục.
- **Phản hồi**: Hermes phát ra các mục đầu ra 
`function_call
` và 
`function_call_output
` đặc tả trong luồng SSE, vì vậy khách hàng có thể hiển thị giao diện người dùng công cụ có cấu trúc trong thời gian thực.

### POST /v1/phản hồi

Định dạng API phản hồi OpenAI. Hỗ trợ trạng thái hội thoại phía máy chủ thông qua 
`previous_response_id

 - máy chủ lưu trữ toàn bộ lịch sử hội thoại (bao gồm các cuộc gọi công cụ và kết quả) để bối cảnh nhiều lượt được giữ nguyên mà không cần khách hàng quản lý.

**Yêu cầu:**

`
``` json
{
  "model": "Hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

`
``**Trả lời:**

`
`JSON
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "Hermes-agent",
  "output": [
    \{"type": "function_call", "name": "terminal", "arguments": "\{\"command\": \"ls\"}", "call_id": "call_1"},
    \{"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
    \{"type": "message", "role": "assistant", "content": [\{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": \{"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

`
``**Đầu vào hình ảnh nội tuyến:** 
`input[].content
` có thể chứa các bộ phận 
`input_text
` và 
`input_image

. Cả URL từ xa và URL 
`data:image/...
` đều được hỗ trợ:

`JSON
{
  "model": "Hermes-agent",
  "input": [
    {
      "role": "user",
      "content": [
        \{"type": "input_text", "text": "Describe this screenshot."},
        \{"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
      ]
    }
  ]
}

`
``Các tệp đã tải lên (
`input_file
` / 
`file_id

) và các URL 
`data:
` không phải hình ảnh trả về 
`400 unsupported_content_type

.

#### Nhiều lượt với previous_response_id

Chuỗi phản hồi để duy trì bối cảnh đầy đủ (bao gồm cả các lệnh gọi công cụ) qua các lượt:

`JSON
{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

`
``Máy chủ xây dựng lại toàn bộ cuộc hội thoại từ chuỗi phản hồi được lưu trữ — tất cả các lệnh gọi và kết quả công cụ trước đó đều được giữ nguyên. Các yêu cầu theo chuỗi cũng chia sẻ cùng một phiên, do đó, các cuộc trò chuyện nhiều lượt sẽ xuất hiện dưới dạng một mục duy nhất trong trang tổng quan và lịch sử phiên.

#### Cuộc trò chuyện được đặt tên

Sử dụng tham số 
`conversation
` thay vì theo dõi ID phản hồi:

`JSON
\{"input": "Hello", "conversation": "my-project"}
\{"input": "What's in src/?", "conversation": "my-project"}
\{"input": "Run the tests", "conversation": "my-project"}

`
``Máy chủ tự động liên kết với phản hồi mới nhất trong cuộc trò chuyện đó. Giống như lệnh 

/title
` cho các phiên cổng.

### NHẬN /v1/responses/\\{id\}

Truy xuất phản hồi được lưu trữ trước đó bằng ID.

### XÓA /v1/responses/\\{id\}

Xóa phản hồi đã lưu.

### NHẬN /v1/model

Liệt kê đại lý như một mô hình có sẵn. Tên mẫu được quảng cáo mặc định là tên [profile](/docs/user-guide/profiles) (hoặc 
`Hermes-agent
` cho cấu hình mặc định). Được yêu cầu bởi hầu hết các giao diện người dùng để khám phá mô hình.

### NHẬN /v1/khả năngTrả về mô tả mà máy có thể đọc được về bề mặt ổn định của máy chủ API dành cho giao diện người dùng bên ngoài, bộ điều phối và cầu nối plugin.

`JSON
{
  "object": "Hermes.API_server.capabilities",
  "platform": "Hermes-agent",
  "model": "Hermes-agent",
  "auth": \{"type": "bearer", "required": true},
  "features": {
    "chat_completions": true,
    "responses_API": true,
    "run_submission": true,
    "run_status": true,
    "run_events_sse": true,
    "run_stop": true
  }
}

`
``Sử dụng điểm cuối này khi tích hợp bảng thông tin, giao diện người dùng trình duyệt hoặc mặt phẳng điều khiển để họ có thể khám phá xem phiên bản Hermes đang chạy có hỗ trợ chạy, phát trực tuyến, hủy và tính liên tục của phiên mà không phụ thuộc vào nội bộ Python riêng tư hay không.

### NHẬN /sức khỏe

Kiểm tra sức khỏe. Trả về 

\{"status": "ok"}

. Cũng có sẵn tại **GET /v1/health** dành cho các máy khách tương thích với OpenAI yêu cầu tiền tố 

/v1/

.

### NHẬN /sức khỏe/chi tiết

Kiểm tra tình trạng mở rộng cũng báo cáo các phiên hoạt động, tác nhân đang chạy và mức sử dụng tài nguyên. Hữu ích cho công cụ giám sát/quan sát.

## Chạy API (giải pháp thay thế thân thiện với phát trực tuyến)

Ngoài 

/v1/chat/completions
` và 

/v1/responses

, máy chủ còn hiển thị API **chạy** cho các phiên dài mà khách hàng muốn đăng ký các sự kiện tiến trình thay vì tự quản lý việc phát trực tuyến.

### POST /v1/run

Tạo một hoạt động đại lý mới. Trả về 
`run_id
` có thể được sử dụng để đăng ký các sự kiện tiến trình.

`JSON
{
  "run_id": "run_abc123",
  "status": "started"
}

`
``Các lần chạy chấp nhận chuỗi 
`input
` đơn giản và 
`session_id

, 
`instructions

, 
`conversation_history
` hoặc 
`previous_response_id
` tùy chọn. Khi 
`session_id
` được cung cấp, Hermes sẽ hiển thị nó ở trạng thái chạy để giao diện người dùng bên ngoài có thể tương quan với các lần chạy với ID hội thoại của riêng họ.

### NHẬN /v1/runs/\\{run_id\}

Thăm dò trạng thái chạy hiện tại. Điều này hữu ích cho các bảng thông tin cần trạng thái mà không cần giữ kết nối SSE mở hoặc cho các giao diện người dùng kết nối lại sau khi điều hướng.

`JSON
{
  "object": "Hermes.run",
  "run_id": "run_abc123",
  "status": "completed",
  "session_id": "space-session",
  "model": "Hermes-agent",
  "output": "Done.",
  "usage": \{"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

`
``Các trạng thái được giữ lại trong thời gian ngắn sau các trạng thái đầu cuối (
`completed

, 
`failed
` hoặc 
`cancelled

) để thăm dò ý kiến và đối chiếu giao diện người dùng.

### NHẬN /v1/runs/\\{run_id\}/events

Luồng Sự kiện do máy chủ gửi về tiến trình lệnh gọi công cụ, vùng đồng bằng mã thông báo và các sự kiện trong vòng đời của quá trình chạy. Được thiết kế cho bảng thông tin và máy khách dày muốn gắn/tháo mà không làm mất trạng thái.

### POST /v1/runs/\\{run_id\}/stop

Làm gián đoạn một lượt tác nhân đang chạy. Điểm cuối quay lại ngay lập tức với 

\{"status": "stopping"}
` trong khi Hermes yêu cầu tác nhân đang hoạt động dừng lại ở điểm gián đoạn an toàn tiếp theo.

## API công việc (công việc được lên lịch ở chế độ nền)

Máy chủ hiển thị bề mặt CRUD công việc nhẹ để quản lý các hoạt động tác nhân nền/theo lịch trình từ máy khách từ xa. Tất cả các điểm cuối đều được kiểm soát phía sau cùng một xác thực mang.

### NHẬN /API/công việc

Liệt kê tất cả các công việc theo lịch trình.

### POST /API/jobs

Tạo một công việc theo lịch trình mới. Cơ thể chấp nhận hình dạng tương tự như 
`Hermes cron

 - nhanh chóng, lịch trình, kỹ năng, ghi đè của nhà cung cấp, mục tiêu phân phối.

### NHẬN /API/jobs/\\{job_id\}

Tìm nạp định nghĩa và trạng thái chạy cuối cùng của một công việc.

### VÁ /API/jobs/\\{job_id\}

Cập nhật các trường về công việc hiện có (lời nhắc, lịch trình, v.v.). Cập nhật một phần được hợp nhất.

### XÓA /API/jobs/\\{job_id\}

Loại bỏ một công việc. Đồng thời hủy bỏ mọi hoạt động trên chuyến bay.

### ĐĂNG /API/jobs/\\{job_id\}/pause

Tạm dừng công việc mà không xóa nó. Dấu thời gian chạy theo lịch trình tiếp theo sẽ bị tạm dừng cho đến khi được tiếp tục.

### BÀI ĐĂNG /API/jobs/\\{job_id\}/sơ yếu lý lịch

Tiếp tục công việc đã tạm dừng trước đó.

### POST /API/jobs/\\{job_id\}/run

Kích hoạt công việc phải chạy ngay, ngoài lịch trình.

## Xử lý dấu nhắc hệ thống

Khi một giao diện người dùng gửi tin nhắn 
`system
` (Hoàn thành trò chuyện) hoặc trường 
`instructions
` (API phản hồi), Hermes-agent **đặt nó lên trên cùng** lời nhắc hệ thống cốt lõi của nó. Tác nhân của bạn giữ lại tất cả các công cụ, bộ nhớ và kỹ năng của nó — lời nhắc hệ thống của giao diện người dùng sẽ bổ sung thêm các hướng dẫn bổ sung.

Điều này có nghĩa là bạn có thể tùy chỉnh hành vi trên mỗi giao diện người dùng mà không mất khả năng:

- Mở lời nhắc hệ thống WebUI: "Bạn là chuyên gia Python. Luôn bao gồm các gợi ý về loại."
- Agent vẫn có terminal, công cụ tập tin, tìm kiếm trên web, bộ nhớ, v.v.

## Xác thực

Xác thực mã thông báo mang thông qua tiêu đề 
`Authorization

:

`
Authorization: Bearer ***

`
``Định cấu hình khóa thông qua 
`API_SERVER_KEY
` env var. Nếu bạn cần một trình duyệt để gọi trực tiếp cho Hermes, hãy đặt 
`API_SERVER_CORS_ORIGINS
` vào danh sách cho phép rõ ràng.

:::warning[Security]
Máy chủ API cấp quyền truy cập đầy đủ vào bộ công cụ của Hermes-agent, **bao gồm các lệnh đầu cuối**. Khi liên kết với một địa chỉ không vòng lặp như 
`0.0.0.0

, 
`API_SERVER_KEY
` là **bắt buộc**. Đồng thời giữ 
`API_SERVER_CORS_ORIGINS
` ở mức thu hẹp để kiểm soát quyền truy cập của trình duyệt.Địa chỉ liên kết mặc định (
`127.0.0.1

) chỉ dành cho sử dụng cục bộ. Quyền truy cập trình duyệt bị tắt theo mặc định; chỉ kích hoạt nó cho các nguồn gốc đáng tin cậy rõ ràng.
:::

## Cấu hình

### Biến môi trường

| Biến | Mặc định | Mô tả |
|----------|----------|-------------|
| 
`API_SERVER_ENABLED
` | 
`false
` | Kích hoạt máy chủ API |
| 
`API_SERVER_PORT
` | 
`8642
` | Cổng máy chủ HTTP |
| 
`API_SERVER_HOST
` | 
`127.0.0.1
` | Địa chỉ liên kết (chỉ localhost theo mặc định) |
| 
`API_SERVER_KEY
` | _(không có)_ | Mã thông báo mang cho xác thực |
| 
`API_SERVER_CORS_ORIGINS
` | _(không có)_ | Nguồn gốc trình duyệt được phép phân tách bằng dấu phẩy |
| 
`API_SERVER_MODEL_NAME
` | _(tên hồ sơ)_ | Tên model trên 

/v1/models

. Mặc định là tên hồ sơ hoặc 
`Hermes-agent
` cho hồ sơ mặc định. |

### config.yaml

``` yaml

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

`

## Tiêu đề bảo mật

Tất cả các phản hồi bao gồm các tiêu đề bảo mật:
- 
`X-Content-Type-Options: nosniff

 - ngăn chặn việc đánh hơi kiểu MIME
- 
`Referrer-Policy: no-referrer

 - ngăn chặn rò rỉ liên kết giới thiệu

## CORS

Máy chủ API **không** bật CORS của trình duyệt theo mặc định.

Để truy cập trực tiếp vào trình duyệt, hãy đặt danh sách cho phép rõ ràng:

``` bash
API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

`
``Khi CORS được bật:

- **Phản hồi trước** bao gồm 
`Access-Control-Max-Age: 600
` (bộ nhớ đệm 10 phút)
- **Phản hồi phát trực tuyến SSE** bao gồm tiêu đề CORS để ứng dụng khách EventSource của trình duyệt hoạt động chính xác
- **
`Idempotency-Key

** là tiêu đề yêu cầu được phép — khách hàng có thể gửi nó để chống trùng lặp (các phản hồi được lưu vào bộ nhớ đệm theo khóa trong 5 phút)

Hầu hết các giao diện người dùng được ghi lại như Open WebUI đều kết nối máy chủ với máy chủ và hoàn toàn không cần CORS.

## Giao diện người dùng tương thích

Bất kỳ giao diện người dùng nào hỗ trợ định dạng API OpenAI đều hoạt động. Tích hợp đã được kiểm tra/ghi lại:

| Giao diện người dùng | Sao | Kết nối |
|----------|-------|-------------|
| [Open WebUI](/docs/user-guide/messaging/open-webui) | 126k | Hướng dẫn đầy đủ có sẵn |
| ThùyChat | 73k | Điểm cuối của nhà cung cấp tùy chỉnh |
| LibreChat | 34k | Custom Endpoint trong librechat.YAML |
| Bất cứ điều gìLLM | 56k | Nhà cung cấp OpenAI chung |
| Trò chuyện tiếp theo | 87k | BASE_URL env var |
| Hộp trò chuyện | 39k | Cài đặt máy chủ API |
| tháng Giêng | 26k | Cấu hình mô hình từ xa |
| Giao diện người dùng trò chuyện HF | 8k | OpenAI_BASE_URL |
| AGI lớn | 7k | Custom Endpoint |
| SDK Python OpenAI | — |

OpenAI(base_url="http://localhost:8642/v1")
` |
| cuộn tròn | — | Yêu cầu HTTP trực tiếp |

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

Để cung cấp cho nhiều người dùng phiên bản Hermes biệt lập của riêng họ (cấu hình, bộ nhớ, kỹ năng riêng), hãy sử dụng [profiles](/docs/user-guide/profiles):

``` bash

# Create a profile per user
Hermes profile create alice
Hermes profile create bob

# Configure each profile's API server on a different port. API_SERVER_* are env
# vars (not config.yaml keys), so write them to each profile's .env:
cat >> ~/.Hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=alice-secret
EOF`cat > ~/.Hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=bob-secret
EOF

# Start each profile's gateway
Hermes -p alice gateway &
Hermes -p bob gateway &

`
``Máy chủ API của mỗi hồ sơ tự động quảng cáo tên hồ sơ dưới dạng ID mẫu:
- 
`http://localhost:8643/v1/models
` → mẫu 
`alice

- 
`http://localhost:8644/v1/models
` → model 
`bob
``Trong Open WebUI, hãy thêm từng cái dưới dạng một kết nối riêng biệt. Danh sách mô hình thả xuống hiển thị 
`alice
` và 
`bob
` dưới dạng các mô hình riêng biệt, mỗi mô hình được hỗ trợ bởi một phiên bản Hermes biệt lập hoàn toàn. Xem [Open WebUI guide](/docs/user-guide/messaging/open-webui#multi-user-setup-with-profiles) để biết chi tiết.

## Hạn chế
- **Lưu trữ phản hồi** — các phản hồi được lưu trữ (dành cho 
`previous_response_id

) được lưu giữ trong SQLite và vẫn tồn tại khi khởi động lại cổng. Tối đa 100 phản hồi được lưu trữ (trục xuất LRU).
- **Không tải lên tệp** — hình ảnh nội tuyến được hỗ trợ trên cả 

/v1/chat/completions
` và 

/v1/responses

, nhưng các tệp đã tải lên (
`file

, 
`input_file

, 
`file_id

) và đầu vào tài liệu không phải hình ảnh không được hỗ trợ thông qua API.
- **Trường mô hình chỉ mang tính thẩm mỹ** — trường 
`model
` trong yêu cầu được chấp nhận nhưng mô hình LLM thực tế được sử dụng được định cấu hình phía máy chủ trong config.yaml.

## Chế độ ủy quyền

Máy chủ API cũng đóng vai trò phụ trợ cho **chế độ proxy cổng**. Khi một phiên bản cổng Hermes khác được định cấu hình với 
`GATEWAY_PROXY_URL
` trỏ vào máy chủ API này, nó sẽ chuyển tiếp tất cả các tin nhắn ở đây thay vì chạy tác nhân của chính nó. Điều này cho phép triển khai phân chia — ví dụ: bộ chứa Docker xử lý Matrix E2EE chuyển tiếp đến tác nhân phía máy chủ.

Xem [Matrix Proxy Mode](/docs/user-guide/messaging/Matrix#proxy-mode-e2ee-on-macOS) để biết hướng dẫn thiết lập đầy đủ.