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
thiết lập / mục menu hermes model
bí danh của 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ê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:

hermes_cli/auth.py quyết định cách tìm thông tin xác thực.
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.
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ì ở đó.)
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 .
Công dụng nhân loại anthropic_messages .
Giao thức mới không phải OpenAI thường có nghĩa là thêm bộ chuyển đổi mới và nhánh api_mode mớ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ý ngắt 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/

mẹo

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 của nhà cung cấp

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 ở cả hermes_cli/auth.py và hermes_cli/models.py
CLI --provider lựa chọn 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 bằng:

id
name
auth_type="api_key"
inference_base_url
api_key_env_vars
tùy chọn base_url_env_var

Đồ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ì chuyển logic vào các nhánh không liên quan.

Bước 3: Thêm danh mục mẫu 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 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:

{
    "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 thì api_mode thường nên 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 thứ này trong hermes_cli/main.py :

provider_labels mệnh lệnh
Danh sách providers trong select_provider_and_model()
công văn của nhà cung cấp ( if selected_provider == ... )
--provider lựa chọn đối số
lựa chọn đăng nhập/đăng xuất nếu nhà cung cấp hỗ trợ các luồng đó
hàm _model_flow_<provider>() hoặc sử dụng lại _model_flow_api_key_provider() nếu phù hợp

mẹo

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 khai thác 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ộ điều hợp 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 .

Hãy 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
_api_call_with_interrupt() 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ả sử ứ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:

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:

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ự.

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:

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 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
mới api_mode đượ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 đăng nhập được phân giải chính xác trong khi dữ liệu nhập /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.

Mô hình tinh thần

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​

Đường dẫn B — Nhà cung cấp gốc​

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​

Bổ sung cho các nhà cung cấp gốc/không phải OpenAI​

Bước 1: Chọn một id nhà cung cấp chuẩn

Bước 2: Thêm siêu dữ liệu xác thực vào hermes_cli/auth.py

Bước 3: Thêm danh mục mẫu và bí danh trong hermes_cli/models.py

Bước 4: Giải quyết dữ liệu thời gian chạy trong hermes_cli/runtime_provider.py

Bước 5: Đấu dây CLI vào hermes_cli/main.py

Bước 6: Duy trì hoạt động của các cuộc gọi phụ

agent/auxiliary_client.py​

agent/model_metadata.py​

Bước 7: Nếu nhà cung cấp là bản địa, hãy thêm bộ điều hợp và hỗ trợ run_agent.py

Tệp bộ điều hợp mới​

run_agent.py​

Bộ nhớ đệm nhắc nhở và các trường yêu cầu dành riêng cho nhà cung cấp​