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

Độ phân giải thời gian chạy của nhà cung cấp

Hermes có trình phân giải thời gian chạy của nhà cung cấp dùng chung được sử dụng trên:

  • CLI
  • cổng
  • công việc định kỳ
  • ACP
  • cuộc gọi mô hình phụ trợ

Thực hiện chính:

  • hermes_cli/runtime_provider.py — độ phân giải thông tin xác thực, _resolve_custom_runtime()
  • hermes_cli/auth.py — sổ đăng ký nhà cung cấp, resolve_provider()
  • hermes_cli/model_switch.py — đường dẫn chuyển đổi /model được chia sẻ (CLI + cổng)
  • agent/auxiliary_client.py — định tuyến mô hình phụ trợ

Nếu bạn đang cố gắng thêm nhà cung cấp suy luận hạng nhất mới, hãy đọc Thêm nhà cung cấp dọc theo trang này.

Ưu tiên độ phân giải​

Ở mức độ cao, độ phân giải của nhà cung cấp sử dụng:

  1. yêu cầu CLI/thời gian chạy rõ ràng
  2. Cấu hình nhà cung cấp/mô hình config.yaml
  3. biến môi trường
  4. mặc định của nhà cung cấp cụ thể hoặc độ phân giải tự động

Việc đặt hàng đó quan trọng vì Hermes coi lựa chọn mẫu/nhà cung cấp đã lưu là nguồn thông tin chính xác cho các hoạt động bình thường. Điều này ngăn quá trình xuất shell cũ âm thầm ghi đè điểm cuối mà người dùng đã chọn lần cuối trong mô hình hermes.

Nhà cung cấp​

Các nhóm nhà cung cấp hiện tại bao gồm:

  • Cổng AI (Vercel)
  • Bộ định tuyến mở
  • Cổng thông tin chúng tôi
  • Codex OpenAI
  • Phi công phụ / ACP phụ
  • Nhân chủng học (bản địa)
  • Google / Song Tử
  • Alibaba / DashScope
  • Tìm kiếm sâu
  • Z.AI
  • Kimi / Ánh trăng
  • MiniMax
  • MiniMax Trung Quốc
  • Mã Kilo
  • Ôm Mặt
  • OpenCode Zen / OpenCode Go
  • Tùy chỉnh (nhà cung cấp: tùy chỉnh) — nhà cung cấp hạng nhất cho mọi điểm cuối tương thích với OpenAI
  • Nhà cung cấp tùy chỉnh được đặt tên (danh sách custom_providers trong config.yaml)

Đầu ra của độ phân giải thời gian chạy​

Trình phân giải thời gian chạy trả về dữ liệu như:

  • nhà cung cấp
  • api_mode
  • base_url
  • api_key
  • nguồn
  • siêu dữ liệu dành riêng cho nhà cung cấp như thông tin hết hạn/làm mới

Tại sao điều này lại quan trọng​

Trình phân giải này là lý do chính khiến Hermes có thể chia sẻ logic xác thực/thời gian chạy giữa:

  • Trò chuyện Hermes
  • xử lý tin nhắn cổng
  • công việc định kỳ chạy trong phiên mới
  • Phiên biên tập ACP
  • nhiệm vụ mô hình phụ trợ

Cổng AI​

Đặt AI_GATEWAY_API_KEY trong ~/.hermes/.env và chạy với --provider ai-gateway. Hermes tìm nạp các mô hình có sẵn từ điểm cuối /models của cổng, lọc theo các mô hình ngôn ngữ có hỗ trợ sử dụng công cụ.

OpenRouter, AI Gateway và các URL cơ sở tương thích với OpenAI tùy chỉnh​

Hermes chứa logic để tránh rò rỉ khóa API sai đến điểm cuối tùy chỉnh khi tồn tại nhiều khóa nhà cung cấp (ví dụ: OPENROUTER_API_KEY, AI_GATEWAY_API_KEY và OPENAI_API_KEY).

Khóa API của mỗi nhà cung cấp nằm trong phạm vi URL cơ sở của chính nhà cung cấp đó:

  • OPENROUTER_API_KEY chỉ được gửi đến điểm cuối openrouter.ai
  • AI_GATEWAY_API_KEY chỉ được gửi đến điểm cuối ai-gateway.vercel.sh
  • OPENAI_API_KEY được sử dụng cho các điểm cuối tùy chỉnh và làm dự phòng

Hermes cũng phân biệt giữa:

  • một điểm cuối tùy chỉnh thực sự được người dùng lựa chọn
  • đường dẫn dự phòng OpenRouter được sử dụng khi không có điểm cuối tùy chỉnh nào được định cấu hình

Sự khác biệt đó đặc biệt quan trọng đối với:

  • máy chủ mô hình địa phương
  • API tương thích với OpenAI không phải OpenRouter/không phải AI Gateway
  • chuyển đổi nhà cung cấp mà không cần chạy lại thiết lập
  • các điểm cuối tùy chỉnh được lưu cấu hình sẽ tiếp tục hoạt động ngay cả khi OPENAI_BASE_URL không được xuất trong shell hiện tại

Con đường nhân chủng bản địa​

Anthropic không chỉ là "thông qua OpenRouter" nữa.

Khi độ phân giải của nhà cung cấp chọn anthropic, Hermes sử dụng:

  • api_mode = tin nhắn nhân loại
  • API thông điệp nhân loại gốc
  • agent/anthropic_adapter.py để dịch

Độ phân giải thông tin xác thực cho Anthropic gốc hiện ưu tiên thông tin xác thực Mã Claude có thể làm mới hơn so với mã thông báo env được sao chép khi cả hai đều có mặt. Trong thực tế điều đó có nghĩa là:

  • Các tệp thông tin xác thực của Mã Claude được coi là nguồn ưu tiên khi chúng bao gồm xác thực có thể làm mới
  • các giá trị ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN thủ công vẫn hoạt động dưới dạng ghi đè rõ ràng
  • Hermes làm mới thông tin xác thực Anthropic trước các lệnh gọi API Tin nhắn gốc
  • Hermes vẫn thử lại một lần trên 401 sau khi xây dựng lại ứng dụng khách Anthropic, như một đường dẫn dự phòng

Đường dẫn OpenAI Codex​

Codex sử dụng đường dẫn API phản hồi riêng:

  • api_mode = codex_responses
  • giải quyết thông tin xác thực chuyên dụng và hỗ trợ cửa hàng xác thực

Định tuyến mô hình phụ trợ​

Các công việc phụ trợ như:

  • 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
  • hoạt động của trung tâm kỹ năng
  • Hoạt động trợ giúp MCP
  • tuôn ra bộ nhớ

có thể sử dụng định tuyến nhà cung cấp/mô hình của riêng họ thay vì mô hình đàm thoại chính.

Khi một tác vụ phụ được định cấu hình với nhà cung cấp main, Hermes sẽ giải quyết vấn đề đó thông qua cùng một đường dẫn thời gian chạy chung như cuộc trò chuyện thông thường. Trong thực tế điều đó có nghĩa là:

  • điểm cuối tùy chỉnh theo hướng env vẫn hoạt động
  • các điểm cuối tùy chỉnh được lưu qua hermes model / config.yaml cũng hoạt động
  • định tuyến phụ trợ có thể cho biết sự khác biệt giữa điểm cuối tùy chỉnh đã lưu thực và dự phòng OpenRouter

Mô hình dự phòng​

Hermes hỗ trợ cặp nhà cung cấp/mô hình dự phòng đã được định cấu hình, cho phép chuyển đổi dự phòng trong thời gian chạy khi mô hình chính gặp lỗi.

Cách thức hoạt động nội bộ​

  1. Bộ nhớ: AIAgent.__init__ lưu trữ lệnh fallback_model và đặt _fallback_activated = False.

  2. Điểm kích hoạt: _try_activate_fallback() được gọi từ ba vị trí trong vòng lặp thử lại chính trong run_agent.py:

  • Sau khi thử lại tối đa các phản hồi API không hợp lệ (Không có lựa chọn nào, thiếu nội dung)
  • Về lỗi máy khách không thể thử lại (HTTP 401, 403, 404)
  • Sau khi thử lại tối đa các lỗi tạm thời (HTTP 429, 500, 502, 503)
  1. Luồng kích hoạt (_try_activate_fallback):
  • Trả về False ngay lập tức nếu đã được kích hoạt hoặc chưa được định cấu hình
  • Gọi resolve_provider_client() từ auxiliary_client.py để xây dựng một ứng dụng khách mới với quyền xác thực phù hợp
  • Xác định api_mode: codex_responses cho openai-codex, anthropic_messages cho anthropic, chat_completions cho mọi thứ khác
  • Hoán đổi tại chỗ: self.model, self.provider, self.base_url, self.api_mode, self.client, self._client_kwargs
  • Đối với dự phòng nhân loại: xây dựng ứng dụng khách Anthropic gốc thay vì tương thích với OpenAI
  • Đánh giá lại bộ nhớ đệm nhanh chóng (được bật cho các mô hình Claude trên OpenRouter)
  • Đặt _fallback_activated = True — ngăn kích hoạt lại
  • Đặt lại số lần thử về 0 và tiếp tục vòng lặp
  1. Luồng cấu hình:
  • CLI: cli.py đọc CLI_CONFIG["fallback_model"] → chuyển tới AIAgent(fallback_model=...)
  • Gateway: gateway/run.py._load_fallback_model() đọc config.yaml → chuyển tới AIAgent
  • Xác thực: cả hai khóa nhà cung cấp và model phải không trống hoặc khóa dự phòng bị tắt

Điều gì KHÔNG hỗ trợ dự phòng​

  • Ủy quyền đại lý phụ (tools/delegate_tool.py): đại lý phụ kế thừa nhà cung cấp của nhà cung cấp chính nhưng không kế thừa cấu hình dự phòng
  • Cron jobs (cron/): chạy với nhà cung cấp cố định, không có cơ chế dự phòng
  • Nhiệm vụ phụ trợ: sử dụng chuỗi tự động phát hiện nhà cung cấp độc lập của riêng họ (xem Định tuyến mô hình phụ trợ ở trên)

Phạm vi kiểm tra​

Xem tests/test_fallback_model.py để biết các bài kiểm tra toàn diện bao gồm tất cả các nhà cung cấp được hỗ trợ, ngữ nghĩa một lần và các trường hợp khó khăn.

Tài liệu liên quan​