Thêm nhà cung cấp
Hermes đã có thể giao tiếp với bất kỳ điểm cuối tương thích OpenAI nào thông qua đường dẫn nhà cung cấp tùy chỉnh. Không thêm nhà cung cấp tích hợp trừ khi bạn muốn UX hạng nhất cho dịch vụ đó:
-
làm mới mã thông báo hoặc xác thực dành riêng cho nhà cung cấp
-
một danh mục mô hình giám tuyển
-
mục menu thiết lập / `Hermes model
-
bí danh nhà cung cấp cho cú pháp `provider:model
-
hình dạng API không phải OpenAI cần bộ chuyển đổi
Nếu nhà cung cấp chỉ là "một URL cơ sở và khóa API tương thích với OpenAI khác", thì một nhà cung cấp tùy chỉnh được đặt tên có thể là đủ.
Mô hình tinh thần
Một nhà cung cấp tích hợp phải xếp hàng qua một vài lớp:
1.
Hermes_CLI/auth.py quyết định cách tìm thông tin xác thực.
2.
Hermes_CLI/runtime_provider.py biến dữ liệu đó thành dữ liệu thời gian chạy:
`provider
`API_mode
`base_url
`API_key
`source
run_agent.py sử dụng
API_mode để quyết định cách tạo và gửi yêu cầu.
4.
Hermes_CLI/models.py và
Hermes_CLI/main.py làm cho nhà cung cấp hiển thị trong CLI. (
Hermes_CLI/setup.py tự động ủy quyền cho
main.py — không cần thay đổi gì ở đó.)
5.
agent/auxiliary_CLIent.py và
agent/model_metadata.py duy trì hoạt động của các nhiệm vụ phụ và lập ngân sách mã thông báo.
Sự trừu tượng hóa quan trọng là `API_mode
.
- Hầu hết các nhà cung cấp đều sử dụng `chat_completions
.
- Codex sử dụng `Codex_responses
.
- Anthropic sử dụng `Anthropic_messages
.
- Giao thức không phải OpenAI mới thường có nghĩa là thêm bộ điều hợp mới và nhánh
API_modemới.
Chọn đường dẫn thực hiện trước
Đường dẫn A — Nhà cung cấp tương thích với OpenAI
Sử dụng tùy chọn này khi nhà cung cấp chấp nhận các yêu cầu kiểu hoàn thành trò chuyện tiêu chuẩn.
Công việc điển hình:
- thêm siêu dữ liệu xác thực
- thêm danh mục / bí danh mô hình
- thêm độ phân giải thời gian chạy
- thêm hệ thống dây menu CLI
- thêm mặc định của mô hình phụ trợ
- thêm bài kiểm tra và tài liệu người dùng
Bạn thường không cần bộ chuyển đổi mới hoặc
API_mode mới.
Đường dẫn B — Nhà cung cấp gốc
Sử dụng tính năng này khi nhà cung cấp không hoạt động giống như hoàn thành trò chuyện OpenAI.
Ví dụ trong cây ngày hôm nay:
`Codex_responses
`Anthropic_messages ``Đường dẫn này bao gồm mọi thứ từ Đường dẫn A cộng thêm:
-
bộ điều hợp nhà cung cấp trong `agent/
-
Các nhánh
run_agent.pyđể xây dựng yêu cầu, gửi đi, trích xuất sử dụng, xử lý gián đoạn và chuẩn hóa phản hồi -
kiểm tra bộ chuyển đổi
Danh sách kiểm tra tệp
Bắt buộc đối với mọi nhà cung cấp tích hợp
`Hermes_CLI/auth.py
`Hermes_CLI/models.py
`Hermes_CLI/runtime_provider.py
`Hermes_CLI/main.py
`agent/auxiliary_CLIent.py
`agent/model_metadata.py
- kiểm tra
- tài liệu hướng tới người dùng trong `website/docs/
Hermes_CLI/setup.py không cần thay đổi. Trình hướng dẫn thiết lập ủy quyền lựa chọn nhà cung cấp/mô hình cho
select_provider_and_model() trong
main.py — mọi nhà cung cấp được thêm vào đó sẽ tự động có sẵn trong
`Hermes setup
.
Bổ sung cho các nhà cung cấp gốc/không phải OpenAI
`agent/<provider>_adapter.py
`run_agent.py
pyproject.TOML nếu cần có SDK nhà cung cấp
Đường dẫn nhanh: Nhà cung cấp khóa API đơn giản
Nếu nhà cung cấp của bạn chỉ là điểm cuối tương thích với OpenAI xác thực bằng một khóa API duy nhất thì bạn không cần phải chạm vào `auth.py
, `runtime_provider.py
,
main.py hoặc bất kỳ tệp nào khác trong danh sách kiểm tra đầy đủ bên dưới.
Tất cả những gì bạn cần là:
-
Thư mục plugin trong
plugins/model-providers/<your-provider>/chứa:
`init.py
-
gọi
register_provider(profile)ở cấp mô-đun
`plugin.YAML
- bảng kê khai (tên, loại: nhà cung cấp mô hình, phiên bản, mô tả)
- Thế thôi. Các plugin của nhà cung cấp tự động tải vào lần đầu tiên bất kỳ thứ gì gọi
get_provider_profile()hoặclist_providers()— các plugin đi kèm (repo này) và các plugin người dùng tại
$Hermes_HOME/plugins/model-providers/ ` đều được chọn.
Khi bạn thêm một plugin và nó gọi `register_provider()
, hệ thống sau sẽ tự động kết nối:1. Mục nhập
PROVIDER_REGISTRY trong
auth.py (độ phân giải thông tin xác thực, tra cứu env-var)
2.
API_mode được đặt thành
`chat_completions
base_url có nguồn gốc từ config hoặc var env đã khai báo
4.
env_vars được kiểm tra theo thứ tự ưu tiên cho khóa API
5. Danh sách
fallback_models đã đăng ký cho nhà cung cấp
6. Cờ
--provider
CLI chấp nhận id nhà cung cấp 7. Menu Hermes model
bao gồm nhà cung cấp 8. Trình hướng dẫn Hermes setup
tự động ủy quyền cho main.py
- Cú pháp bí danh
provider:modelhoạt động - Trình phân giải thời gian chạy trả về
base_urlvàAPI_keychính xác - Cờ
--provider <name> ` CLI chấp nhận id nhà cung cấp 12. Kích hoạt mô hình dự phòng có thể chuyển sang nhà cung cấp một cách dễ dàng
Các plugin của người dùng tại
$Hermes_HOME/plugins/model-providers/<name/
ghi đè các plugin đi kèm cùng tên (người viết cuối cùng sẽ thắng trong register_provider()
) — vì vậy các bên thứ ba có thể vá lỗi hoặc thay thế bất kỳ cấu hình tích hợp nào mà không cần chỉnh sửa repo.
Xem
plugins/model-providers/nvidia/ hoặc
plugins/model-providers/gmi/ làm mẫu và Model Provider Plugin guide đầy đủ để tham khảo trường, thành ngữ hook và ví dụ từ đầu đến cuối.
Đường dẫn đầy đủ: OAuth và nhà cung cấp phức tạp
Sử dụng danh sách kiểm tra đầy đủ bên dưới khi nhà cung cấp của bạn cần bất kỳ điều nào sau đây:
- Làm mới OAuth hoặc mã thông báo (Nous Portal, Codex, Google Gemini, Cổng thông tin Qwen, Copilot)
- Hình dạng API không phải OpenAI yêu cầu bộ điều hợp mới (Thông điệp nhân loại, Phản hồi Codex)
- Phát hiện điểm cuối tùy chỉnh hoặc thăm dò đa vùng (Z.AI, Kimi)
- Danh mục mô hình tĩnh được quản lý hoặc tìm nạp
/models ` trực tiếp
- Các mục menu
Hermes modeldành riêng cho nhà cung cấp với các luồng xác thực riêng
Bước 1: Chọn một id nhà cung cấp chuẩn
Chọn một id nhà cung cấp duy nhất và sử dụng nó ở mọi nơi.
Ví dụ từ repo:
`OpenAI-Codex
`Kimi-coding
`MiniMax-cn ``Id tương tự sẽ xuất hiện trong:
PROVIDER_REGISTRY trong
`Hermes_CLI/auth.py
_PROVIDER_LABELS trong
`Hermes_CLI/models.py
_PROVIDER_ALIASES trong cả
Hermes_CLI/auth.py và
`Hermes_CLI/models.py
- Các lựa chọn CLI
--provider
trong Hermes_CLI/main.py
- nhánh thiết lập / lựa chọn mô hình
- mặc định mô hình phụ trợ
- kiểm tra
Nếu id khác nhau giữa các tệp đó, nhà cung cấp sẽ cảm thấy nửa vời: auth có thể hoạt động trong khi
/model
, thiết lập hoặc độ phân giải thời gian chạy âm thầm bỏ lỡ nó.
Bước 2: Thêm siêu dữ liệu xác thực vào
Hermes_CLI/auth.py ``Đối với nhà cung cấp khóa API, hãy thêm mục nhập ProviderConfig
vào PROVIDER_REGISTRY
` với:
`id
`name
`auth_type="API_key"
`inference_base_url
`API_key_env_vars
base_url_env_var tùy chọn
Đồng thời thêm bí danh vào `_PROVIDER_ALIASES
.
Sử dụng các nhà cung cấp hiện có làm mẫu:
- đường dẫn khóa API đơn giản: Z.AI, MiniMax
- Đường dẫn khóa API có tính năng phát hiện điểm cuối: Kimi, Z.AI
- độ phân giải mã thông báo gốc: Anthropic
- Đường dẫn OAuth/auth-store: Nous, OpenAI Codex
Câu hỏi cần trả lời tại đây:
- Hermes nên kiểm tra những loại env nào và theo thứ tự ưu tiên nào?
- Nhà cung cấp có cần ghi đè URL cơ sở không?
- Nó có cần thăm dò điểm cuối hoặc làm mới mã thông báo không?
- Lỗi xác thực sẽ báo như thế nào khi thiếu thông tin xác thực?
Nếu nhà cung cấp cần thứ gì đó hơn là "tra cứu khóa API", hãy thêm trình phân giải thông tin xác thực chuyên dụng thay vì đẩy logic vào các nhánh không liên quan.
Bước 3: Thêm danh mục model và bí danh trong
Hermes_CLI/models.py ``Cập nhật danh mục nhà cung cấp để nhà cung cấp hoạt động trong menu và theo cú pháp provider:model
.
Chỉnh sửa điển hình:
`_PROVIDER_MODELS
`_PROVIDER_LABELS
`_PROVIDER_ALIASES
-
thứ tự hiển thị của nhà cung cấp bên trong `list_available_providers()
provider_model_ids() nếu nhà cung cấp hỗ trợ tìm nạp
/models ` trực tiếp
Nếu nhà cung cấp hiển thị danh sách mô hình trực tiếp, hãy ưu tiên danh sách đó trước và giữ
_PROVIDER_MODELS làm dự phòng tĩnh.
Tệp này cũng là thứ giúp các đầu vào như thế này hoạt động:
Anthropic:Claude-sonnet-4-6
Kimi:model-name
`
``Nếu thiếu bí danh ở đây, nhà cung cấp có thể xác thực chính xác nhưng vẫn không thành công khi phân tích cú pháp
/model
.
## Bước 4: Giải quyết dữ liệu thời gian chạy trong
`Hermes_CLI/runtime_provider.py
```resolve_runtime_provider()
` là đường dẫn chung được sử dụng bởi các máy khách CLI, cổng, cron, ACP và trình trợ giúp.
Thêm một nhánh trả về một lệnh có ít nhất:
`Python
{
"provider": "your-provider",
"API_mode": "chat_completions", # or your native mode
"base_url": "https://...",
"API_key": "...",
"source": "env|portal|auth-store|explicit",
"requested_provider": requested_provider,
}
`
``Nếu nhà cung cấp tương thích với OpenAI,
`API_mode
` thường sẽ giữ nguyên
`chat_completions
.Hãy cẩn thận với quyền ưu tiên của khóa API. Hermes đã chứa logic để tránh rò rỉ khóa OpenRouter tới các điểm cuối không liên quan. Nhà cung cấp mới phải rõ ràng như nhau về khóa nào đi tới URL cơ sở nào.
## Bước 5: Đấu dây CLI vào
`Hermes_CLI/main.py
``Không thể tìm thấy nhà cung cấp cho đến khi nhà cung cấp đó xuất hiện trong luồng
`Hermes model
` tương tác.
Cập nhật những điều này trong
`Hermes_CLI/main.py
:
- Lệnh
`provider_labels
`
- Danh sách
`providers
` trong
`select_provider_and_model()
- công văn nhà cung cấp (
`if selected_provider == ...
)
- Lựa chọn đối số
--provider
- lựa chọn đăng nhập/đăng xuất nếu nhà cung cấp hỗ trợ các luồng đó
- chức năng
`_model_flow_<provider()
` hoặc sử dụng lại
`_model_flow_API_key_provider()
` nếu phù hợp
:::tip
`Hermes_CLI/setup.py
` không cần thay đổi — nó gọi
`select_provider_and_model()
` từ
`main.py
, do đó nhà cung cấp mới của bạn tự động xuất hiện trong cả
`Hermes model
` và
`Hermes setup
.
:::
## Bước 6: Duy trì hoạt động của các cuộc gọi phụ
Hai tập tin quan trọng ở đây:
###
`agent/auxiliary_CLIent.py
``Thêm mô hình phụ trợ mặc định rẻ/nhanh vào
`_API_KEY_PROVIDER_AUX_MODELS
` nếu đây là nhà cung cấp khóa API trực tiếp.
Các nhiệm vụ phụ trợ bao gồm những việc như:
- tóm tắt tầm nhìn
- tóm tắt trích xuất web
- tóm tắt nén ngữ cảnh
- tóm tắt tìm kiếm phiên
- tuôn ra bộ nhớ
Nếu nhà cung cấp không có mặc định phụ trợ hợp lý, các tác vụ phụ có thể hoạt động kém hoặc sử dụng mô hình chính đắt tiền một cách bất ngờ.
###
`agent/model_metadata.py
``Thêm độ dài ngữ cảnh cho mô hình của nhà cung cấp để lập ngân sách mã thông báo, ngưỡng nén và giới hạn luôn hợp lý.
## Bước 7: Nếu nhà cung cấp là bản địa, hãy thêm bộ chuyển đổi và hỗ trợ
`run_agent.py
``Nếu nhà cung cấp không hoàn thành cuộc trò chuyện đơn giản, hãy tách biệt logic dành riêng cho nhà cung cấp trong
`agent/<provider_adapter.py
.
Giữ
`run_agent.py
` tập trung vào việc điều phối. Nó nên gọi những người trợ giúp bộ điều hợp chứ không phải tải trọng của nhà cung cấp dịch vụ xây dựng thủ công nội tuyến trên toàn bộ tệp.
Một nhà cung cấp bản địa thường cần làm việc ở những nơi sau:
### Tệp bộ điều hợp mới
Trách nhiệm điển hình:
- xây dựng ứng dụng khách SDK / HTTP
- giải quyết mã thông báo
- chuyển đổi tin nhắn hội thoại kiểu OpenAI sang định dạng yêu cầu của nhà cung cấp
- chuyển đổi lược đồ công cụ nếu cần
- bình thường hóa phản hồi của nhà cung cấp theo những gì
`run_agent.py
` mong đợi
- trích xuất dữ liệu sử dụng và lý do kết thúc
###
`run_agent.py
``Tìm kiếm
`API_mode
` và kiểm tra mọi điểm chuyển đổi. Tối thiểu, hãy xác minh:
-
`__init__
` chọn
`API_mode
` mới
- công trình xây dựng của khách hàng cho nhà cung cấp
-
`_build_API_kwargs()
` biết cách định dạng yêu cầu
-
`_interruptible_API_call()
` gửi đến đúng cuộc gọi của khách hàng
- đường dẫn xây dựng lại ngắt / máy khách hoạt động
- xác thực phản hồi chấp nhận hình dạng của nhà cung cấp
- kết thúc trích xuất lý do là chính xác
- trích xuất sử dụng mã thông báo là chính xác
- kích hoạt mô hình dự phòng có thể chuyển sang nhà cung cấp mới một cách rõ ràng
- đường dẫn tạo tóm tắt và xóa bộ nhớ vẫn hoạt động
Đồng thời tìm kiếm
`run_agent.py
` cho
`self.CLIent.
. Bất kỳ đường dẫn mã nào giả định ứng dụng khách OpenAI tiêu chuẩn tồn tại đều có thể bị hỏng khi nhà cung cấp gốc sử dụng một đối tượng ứng dụng khách khác hoặc
`self.CLIent = None
.
### Bộ nhớ đệm nhắc nhở và các trường yêu cầu dành riêng cho nhà cung cấp
Bộ nhớ đệm nhanh chóng và các nút bấm dành riêng cho nhà cung cấp rất dễ bị thoái lui.
Ví dụ đã có trong cây:
- Anthropic có đường dẫn bộ nhớ đệm gốc
- OpenRouter nhận các trường định tuyến của nhà cung cấp
- không phải mọi nhà cung cấp đều nhận được mọi tùy chọn phía yêu cầu
Khi bạn thêm nhà cung cấp gốc, hãy kiểm tra kỹ xem Hermes chỉ gửi các trường mà nhà cung cấp thực sự hiểu hay không.
## Bước 8: Kiểm tra
Ít nhất, hãy chạm vào các bài kiểm tra bảo vệ hệ thống dây điện của nhà cung cấp.
Những nơi thường gặp:
-
`tests/test_runtime_provider_resolution.py
-
`tests/test_CLI_provider_resolution.py
-
`tests/test_CLI_model_command.py
-
`tests/test_setup_model_selection.py
-
`tests/test_provider_parity.py
-
`tests/test_run_agent.py
-
`tests/test_<provider_adapter.py
` dành cho nhà cung cấp bản địa
Đối với các ví dụ chỉ dành cho tài liệu, tập hợp tệp chính xác có thể khác nhau. Vấn đề là để bao gồm:
- độ phân giải xác thực
- Menu CLI / lựa chọn nhà cung cấp
- độ phân giải của nhà cung cấp thời gian chạy
- đường dẫn thực thi tác nhân
- nhà cung cấp: phân tích mô hình
- mọi chuyển đổi tin nhắn dành riêng cho bộ điều hợp
Chạy thử nghiệm với xdist bị vô hiệu hóa:
``` bash
source venv/bin/activate
Python -m pytest tests/test_runtime_provider_resolution.py tests/test_CLI_provider_resolution.py tests/test_CLI_model_command.py tests/test_setup_model_selection.py -n0 -q
`
``Để có những thay đổi sâu hơn, hãy chạy bộ đầy đủ trước khi đẩy:
`bash
source venv/bin/activate
Python -m pytest tests/ -n0 -q
`
## Bước 9: Xác minh trực tiếp
Sau khi kiểm tra, hãy chạy thử nghiệm khói thực sự.
`bash
source venv/bin/activate
Python -m Hermes_CLI.main chat -q "Say hello" --provider your-provider --model your-model
`
``Đồng thời kiểm tra các luồng tương tác nếu bạn thay đổi menu:
`bash
source venv/bin/activate
Python -m Hermes_CLI.main model
Python -m Hermes_CLI.main setup
`
``Đối với các nhà cung cấp gốc, hãy xác minh ít nhất một lệnh gọi công cụ chứ không chỉ là phản hồi bằng văn bản đơn giản.## Bước 10: Cập nhật tài liệu hướng tới người dùng
Nếu nhà cung cấp dự định cung cấp dưới dạng tùy chọn hạng nhất, hãy cập nhật tài liệu người dùng:
-
`website/docs/getting-started/quickstart.md
`
-
`website/docs/user-guide/configuration.md
-
`website/docs/reference/environment-variables.md
``Nhà phát triển có thể kết nối nhà cung cấp một cách hoàn hảo nhưng vẫn khiến người dùng không thể khám phá các biến env hoặc quy trình thiết lập cần thiết.
## Danh sách kiểm tra nhà cung cấp tương thích với OpenAI
Sử dụng điều này nếu nhà cung cấp hoàn thành trò chuyện tiêu chuẩn.
- [ ]
`ProviderConfig
` được thêm vào
`Hermes_CLI/auth.py
- [ ] bí danh được thêm vào
`Hermes_CLI/auth.py
` và
`Hermes_CLI/models.py
- [ ] Danh mục mẫu được thêm vào
`Hermes_CLI/models.py
- [ ] nhánh thời gian chạy được thêm vào
`Hermes_CLI/runtime_provider.py
- [ ] Hệ thống dây CLI được thêm vào
`Hermes_CLI/main.py
` (setup.py kế thừa tự động)
- [ ] mô hình aux được thêm vào
`agent/auxiliary_CLIent.py
- [ ] độ dài ngữ cảnh được thêm vào trong
`agent/model_metadata.py
- [] đã cập nhật các bài kiểm tra thời gian chạy / CLI
- [] tài liệu người dùng được cập nhật
## Danh sách kiểm tra của nhà cung cấp bản địa
Sử dụng điều này khi nhà cung cấp cần một đường dẫn giao thức mới.
- [ ] mọi thứ trong danh sách kiểm tra tương thích với OpenAI
- [ ] bộ chuyển đổi được thêm vào
`agent/<provider_adapter.py
- []
`API_mode
` mới được hỗ trợ trong
`run_agent.py
- [] ngắt/xây dựng lại đường dẫn hoạt động
- [] công việc trích xuất lý do sử dụng và kết thúc
- [] đường dẫn dự phòng hoạt động
- [] đã thêm các bài kiểm tra bộ điều hợp
- [ ] vượt qua bài kiểm tra khói trực tiếp
## Những cạm bẫy thường gặp
### 1. Thêm nhà cung cấp vào xác thực nhưng không thêm vào phân tích mô hình
Điều đó giúp thông tin xác thực được phân giải chính xác trong khi đầu vào
/model
` và
`provider:model
` không thành công.
### 2. Quên rằng
`config["model"]
` có thể là một chuỗi hoặc một lệnh
Rất nhiều mã lựa chọn nhà cung cấp phải bình thường hóa cả hai biểu mẫu.
### 3. Giả sử cần có nhà cung cấp tích hợp
Nếu dịch vụ chỉ tương thích với OpenAI thì nhà cung cấp tùy chỉnh có thể đã giải quyết được vấn đề của người dùng mà không cần phải bảo trì nhiều.
### 4. Quên đường dẫn phụ
Đường dẫn trò chuyện chính có thể hoạt động trong khi quá trình tóm tắt, xóa bộ nhớ hoặc trợ giúp trực quan không thành công do định tuyến phụ trợ chưa bao giờ được cập nhật.
### 5. Các nhánh của nhà cung cấp bản địa ẩn trong
`run_agent.py
``Tìm kiếm
`API_mode
` và
`self.CLIent.
. Đừng cho rằng đường dẫn yêu cầu rõ ràng là đường dẫn duy nhất.
### 6. Gửi các nút bấm chỉ dành cho OpenRouter cho các nhà cung cấp khác
Các trường như định tuyến nhà cung cấp chỉ thuộc về các nhà cung cấp hỗ trợ họ.
### 7. Đang cập nhật
`Hermes model
` nhưng không phải
`Hermes setup
``Cả hai luồng đều cần biết về nhà cung cấp.
## Mục tiêu tìm kiếm tốt khi triển khai
Nếu bạn đang tìm kiếm tất cả những nơi mà nhà cung cấp chạm tới, hãy tìm kiếm những biểu tượng sau:
-
`PROVIDER_REGISTRY
-
`_PROVIDER_ALIASES
-
`_PROVIDER_MODELS
-
`resolve_runtime_provider
-
`_model_flow_
-
`select_provider_and_model
-
`API_mode
-
`_API_KEY_PROVIDER_AUX_MODELS
-
`self.CLIent.
## Tài liệu liên quan
- [Provider Runtime Resolution](./provider-runtime.md)
- [Architecture](./architecture.md)
- [Contributing](./contributing.md)