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 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:

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

3. 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.
• Nhân loại sử dụng 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ộ điều hợp 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

1. hermes_cli/auth.py
2. hermes_cli/models.py
3. hermes_cli/runtime_provider.py
4. hermes_cli/main.py
5. agent/auxiliary_client.py
6. agent/model_metadata.py
7. kiểm tra
8. 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/kiểu máy 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

10. agent/<provider>_adapter.py
11. run_agent.py
12. pyproject.toml nếu cần có SDK 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
• 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 trong 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 thì nhà cung cấp có thể xác thực chính xác nhưng vẫn thất bại trong quá trình 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, 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ông tin này trong hermes_cli/main.py:

• lệnh provider_labels
• 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 sẽ 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ộ 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.

Hãy luôn run_agent.py tập trung vào việc phối hợp. 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ả đị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 gốc

Đố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 đã thêm vào hermes_cli/auth.py
• bí danh được thêm vào trong 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 trong 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
• 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 xác thực được giải quyết 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. Nhánh 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

• Độ phân giải thời gian chạy của nhà cung cấp
• Kiến trúc
• Đóng góp