Nhà cung cấp AI

Trang này đề cập đến việc thiết lập nhà cung cấp suy luận cho Đại lý Hermes — từ các API đám mây như OpenRouter và Anthropic, đến các điểm cuối tự lưu trữ như Ollama và vLLM, cho đến các cấu hình dự phòng và định tuyến nâng cao. Bạn cần ít nhất một nhà cung cấp được định cấu hình để sử dụng Hermes.

Nhà cung cấp suy luận

Bạn cần ít nhất một cách để kết nối với LLM. Sử dụng mô hình hermes để chuyển đổi nhà cung cấp và mô hình một cách tương tác hoặc định cấu hình trực tiếp:

Nhà cung cấp	Thiết lập
Cổng thông tin Nous	`mô hình hermes` (OAuth, dựa trên đăng ký)
OpenAI Codex	`mô hình hermes` (ChatGPT OAuth, sử dụng mô hình Codex)
Phi công phụ GitHub	`mô hình hermes` (Luồng mã thiết bị OAuth, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN` hoặc `gh auth token`)
GitHub Copilot ACP	`hermes model` (sinh ra local `copilot --acp --stdio`)
Nhân loại	`mô hình hermes` (Claude Pro/Max thông qua xác thực Claude Code, khóa API Anthropic hoặc mã thông báo thiết lập thủ công)
OpenRouter	`OPENROUTER_API_KEY` trong `~/.hermes/.env`
Cổng AI	`AI_GATEWAY_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `ai-gateway`)
z.ai / GLM	`GLM_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `zai`)
Kimi / Ánh trăng	`KIMI_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `kimi-coding`)
MiniMax	`MINIMAX_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `minimax`)
MiniMax Trung Quốc	`MINIMAX_CN_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `minimax-cn`)
Đám mây Alibaba	`DASHSCOPE_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `alibaba`, bí danh: `dashscope`, `qwen`)
Mã Kilo	`KILOCODE_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `kilocode`)
Mã mở Zen	`OPENCODE_ZEN_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `opencode-zen`)
Mã mở đi	`OPENCODE_GO_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `opencode-go`)
DeepSeek	`DEEPSEEK_API_KEY` trong `~/.hermes/.env` (nhà cung cấp: `deepseek`)
Ôm mặt	`HF_TOKEN` trong `~/.hermes/.env` (nhà cung cấp: `huggingface`, bí danh: `hf`)
Google / Song Tử	`GOOGLE_API_KEY` (hoặc `GEMINI_API_KEY`) trong `~/.hermes/.env` (nhà cung cấp: `gemini`)
Điểm cuối tùy chỉnh	`mô hình hermes` → chọn "Điểm cuối tùy chỉnh" (được lưu trong `config.yaml`)

Model key alias

Trong phần cấu hình model:, bạn có thể sử dụng default: hoặc model: làm tên khóa cho ID mẫu của mình. Cả model: { default: my-model } và model: { model: my-model } đều hoạt động giống hệt nhau.

Codex Note

Nhà cung cấp OpenAI Codex xác thực thông qua mã thiết bị (mở URL, nhập mã). Hermes lưu trữ thông tin xác thực thu được trong cửa hàng xác thực của riêng mình dưới ~/.hermes/auth.json và có thể nhập thông tin xác thực Codex CLI hiện có từ ~/.codex/auth.json khi có. Không cần cài đặt Codex CLI.

cảnh báo

Ngay cả khi sử dụng Nous Portal, Codex hoặc điểm cuối tùy chỉnh, một số công cụ (tầm nhìn, tóm tắt web, MoA) vẫn sử dụng mô hình "phụ trợ" riêng biệt — theo mặc định là Gemini Flash thông qua OpenRouter. OPENROUTER_API_KEY tự động kích hoạt các công cụ này. Bạn cũng có thể định cấu hình mô hình và nhà cung cấp mà các công cụ này sử dụng — xem Mô hình phụ trợ.

Nhân chủng học (Bản địa)

Sử dụng trực tiếp các mô hình Claude thông qua API Anthropic - không cần proxy OpenRouter. Hỗ trợ ba phương thức xác thực:

# With an API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Preferred: authenticate through `hermes model`
# Hermes will use Claude Code's credential store directly when available
hermes model

# Manual override with a setup-token (fallback / legacy)
export ANTHROPIC_TOKEN=***  # setup-token or manual OAuth token
hermes chat --provider anthropic

# Auto-detect Claude Code credentials (if you already use Claude Code)
hermes chat --provider anthropic  # reads Claude Code credential files automatically

Khi bạn chọn Anthropic OAuth thông qua mô hình hermes, Hermes thích kho thông tin xác thực của chính Claude Code hơn là sao chép mã thông báo vào ~/.hermes/.env. Điều đó giúp thông tin đăng nhập Claude có thể làm mới được luôn được làm mới.

Hoặc đặt nó vĩnh viễn:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

Aliases

--provider claude và --provider claude-code cũng hoạt động như cách viết tắt của --provider anthropic.

Phi công phụ GitHub

Hermes hỗ trợ GitHub Copilot với tư cách là nhà cung cấp hạng nhất với hai chế độ:

Copilot — API Copilot trực tiếp (được khuyến nghị). Sử dụng đăng ký GitHub Copilot của bạn để truy cập GPT-5.x, Claude, Gemini và các mô hình khác thông qua API Copilot.

hermes chat --provider copilot --model gpt-5.4

Tùy chọn xác thực (được chọn theo thứ tự này):

Biến môi trường COPILOT_GITHUB_TOKEN
Biến môi trường GH_TOKEN
Biến môi trường GITHUB_TOKEN
Dự phòng CLI gh auth token

Nếu không tìm thấy mã thông báo nào, mô hình hermes sẽ cung cấp đăng nhập mã thiết bị OAuth — cùng một quy trình được sử dụng bởi Copilot CLI và mã mở.

Token types

API Copilot không hỗ trợ Mã thông báo truy cập cá nhân cổ điển (ghp_*). Các loại mã thông báo được hỗ trợ:

Loại	Tiền tố	Làm thế nào để có được
Mã thông báo OAuth	`gho_`	`mô hình Hermes` → GitHub Copilot → Đăng nhập bằng GitHub
PAT hạt mịn	`github_pat_`	Cài đặt GitHub → Cài đặt dành cho nhà phát triển → Mã thông báo chi tiết (cần quyền Yêu cầu phi công phụ)
Mã thông báo ứng dụng GitHub	`ghu_`	Thông qua cài đặt ứng dụng GitHub

Nếu gh auth token của bạn trả về mã thông báo ghp_*, thay vào đó hãy sử dụng hermes model để xác thực qua OAuth.

Định tuyến API: Các mẫu GPT-5+ (ngoại trừ gpt-5-mini) tự động sử dụng API phản hồi. Tất cả các kiểu máy khác (GPT-4o, Claude, Gemini, v.v.) đều sử dụng tính năng Hoàn thành trò chuyện. Các mô hình được tự động phát hiện từ danh mục Copilot trực tiếp.

copilot-acp — Phần phụ trợ của tác nhân Copilot ACP. Sinh ra CLI Copilot cục bộ dưới dạng một quy trình con:

hermes chat --provider copilot-acp --model copilot-acp
# Requires the GitHub Copilot CLI in PATH and an existing `copilot login` session

Cấu hình cố định:

model:
  provider: "copilot"
  default: "gpt-5.4"

Biến môi trường	Mô tả
`COPILOT_GITHUB_TOKEN`	Mã thông báo GitHub cho API Copilot (ưu tiên hàng đầu)
`HERMES_COPILOT_ACP_COMMAND`	Ghi đè đường dẫn nhị phân Copilot CLI (mặc định: `copilot`)
`HERMES_COPILOT_ACP_ARGS`	Ghi đè các đối số ACP (mặc định: `--acp --stdio`)

Nhà cung cấp AI Trung Quốc hạng nhất

Các nhà cung cấp này có hỗ trợ tích hợp với ID nhà cung cấp chuyên dụng. Đặt khóa API và sử dụng --provider để chọn:

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# Requires: GLM_API_KEY in ~/.hermes/.env

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding
# Requires: KIMI_API_KEY in ~/.hermes/.env

# MiniMax (global endpoint)
hermes chat --provider minimax --model MiniMax-M2.7
# Requires: MINIMAX_API_KEY in ~/.hermes/.env

# MiniMax (China endpoint)
hermes chat --provider minimax-cn --model MiniMax-M2.7
# Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env

# Alibaba Cloud / DashScope (Qwen models)
hermes chat --provider alibaba --model qwen3.5-plus
# Requires: DASHSCOPE_API_KEY in ~/.hermes/.env

Hoặc đặt nhà cung cấp vĩnh viễn trong config.yaml:

model:
  provider: "zai"       # or: kimi-coding, minimax, minimax-cn, alibaba
  default: "glm-5"

URL cơ sở có thể được ghi đè bằng các biến môi trường GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL hoặc DASHSCOPE_BASE_URL.

Z.AI Endpoint Auto-Detection

Khi sử dụng nhà cung cấp Z.AI / GLM, Hermes tự động thăm dò nhiều điểm cuối (toàn cầu, Trung Quốc, các biến thể mã hóa) để tìm ra điểm cuối chấp nhận khóa API của bạn. Bạn không cần đặt GLM_BASE_URL theo cách thủ công — điểm cuối hoạt động được phát hiện và lưu vào bộ nhớ đệm tự động.

xAI (Grok) Bộ nhớ đệm nhắc nhở

Khi sử dụng xAI làm nhà cung cấp (bất kỳ URL cơ sở nào chứa x.ai), Hermes sẽ tự động kích hoạt bộ nhớ đệm nhanh chóng bằng cách gửi tiêu đề x-grok-conv-id với mọi yêu cầu API. Điều này định tuyến các yêu cầu đến cùng một máy chủ trong phiên hội thoại, cho phép cơ sở hạ tầng của xAI sử dụng lại lời nhắc hệ thống và lịch sử hội thoại đã lưu trong bộ nhớ đệm.

Không cần cấu hình — bộ nhớ đệm sẽ tự động kích hoạt khi phát hiện điểm cuối xAI và có ID phiên. Điều này giúp giảm độ trễ và chi phí cho các cuộc hội thoại nhiều lượt.

Nhà cung cấp suy luận ôm mặt

Nhà cung cấp suy luận Hugging Face định tuyến tới hơn 20 mô hình mở thông qua điểm cuối thống nhất tương thích với OpenAI (router.huggingface.co/v1). Các yêu cầu được tự động chuyển đến chương trình phụ trợ có sẵn nhanh nhất (Groq, Together, SambaNova, v.v.) với tính năng chuyển đổi dự phòng tự động.

# Use any available model
hermes chat --provider huggingface --model Qwen/Qwen3-235B-A22B-Thinking-2507
# Requires: HF_TOKEN in ~/.hermes/.env

# Short alias
hermes chat --provider hf --model deepseek-ai/DeepSeek-V3.2

Hoặc đặt nó vĩnh viễn trong config.yaml:

model:
  provider: "huggingface"
  default: "Qwen/Qwen3-235B-A22B-Thinking-2507"

Nhận mã thông báo của bạn tại huggingface.co/settings/tokens — đảm bảo bật quyền "Thực hiện cuộc gọi tới Nhà cung cấp suy luận". Đã bao gồm bậc miễn phí (tín dụng ($0,10/tháng, không tăng giá theo giá của nhà cung cấp).

Bạn có thể nối thêm hậu tố định tuyến vào tên mô hình: :fastest (mặc định), :cheapest hoặc :provider_name để buộc một chương trình phụ trợ cụ thể.

URL cơ sở có thể được ghi đè bằng HF_BASE_URL.

Nhà cung cấp LLM tùy chỉnh và tự lưu trữ

Hermes Agent hoạt động với mọi điểm cuối API tương thích với OpenAI. Nếu máy chủ triển khai /v1/chat/completions, bạn có thể trỏ Hermes vào máy chủ đó. Điều này có nghĩa là bạn có thể sử dụng các mô hình cục bộ, máy chủ suy luận GPU, bộ định tuyến của nhiều nhà cung cấp hoặc bất kỳ API nào của bên thứ ba.

Cài đặt chung

Ba cách để định cấu hình điểm cuối tùy chỉnh:

Thiết lập tương tác (được khuyến nghị):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

Cấu hình thủ công (config.yaml):

# In ~/.hermes/config.yaml
model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Legacy env vars

OPENAI_BASE_URL và LLM_MODEL trong .env không được dùng nữa. OPENAI_BASE_URL không còn được tư vấn để giải quyết điểm cuối nữa — config.yaml là nguồn thông tin chính xác duy nhất. CLI bỏ qua hoàn toàn LLM_MODEL (chỉ cổng mới đọc nó dưới dạng dự phòng). Sử dụng hermes model hoặc chỉnh sửa trực tiếp config.yaml — cả hai đều tồn tại chính xác trên các lần khởi động lại và vùng chứa Docker.

Cả hai cách tiếp cận đều sử dụng config.yaml, đây là nguồn thông tin chính xác cho mô hình, nhà cung cấp và URL cơ sở.

Chuyển đổi mô hình bằng `/model`

Sau khi định cấu hình điểm cuối tùy chỉnh, bạn có thể chuyển đổi mô hình giữa phiên:

/model custom:qwen-2.5          # Switch to a model on your custom endpoint
/model custom                    # Auto-detect the model from the endpoint
/model openrouter:claude-sonnet-4 # Switch back to a cloud provider

Nếu bạn đã định cấu hình nhà cung cấp tùy chỉnh được đặt tên (xem bên dưới), hãy sử dụng cú pháp ba:

/model custom:local:qwen-2.5    # Use the "local" custom provider with model qwen-2.5
/model custom:work:llama3       # Use the "work" custom provider with llama3

Khi chuyển đổi nhà cung cấp, Hermes vẫn giữ nguyên URL cơ sở và nhà cung cấp để định cấu hình để thay đổi vẫn tiếp tục khởi động lại. Khi chuyển từ điểm cuối tùy chỉnh sang nhà cung cấp tích hợp sẵn, URL cơ sở cũ sẽ tự động bị xóa.

mẹo

/model custom (trống, không có tên mô hình) truy vấn API /models của điểm cuối của bạn và tự động chọn mô hình nếu chính xác một mô hình được tải. Hữu ích cho các máy chủ cục bộ chạy một mô hình duy nhất.

Mọi thứ bên dưới đều tuân theo cùng một mẫu — chỉ cần thay đổi URL, khóa và tên mẫu.

Ollama — Mô hình cục bộ, không cần cấu hình

Ollama chạy cục bộ các mô hình có trọng lượng mở chỉ bằng một lệnh. Tốt nhất cho: thử nghiệm cục bộ nhanh chóng, công việc nhạy cảm với quyền riêng tư, sử dụng ngoại tuyến. Hỗ trợ gọi công cụ thông qua API tương thích với OpenAI.

# Install and run a model
ollama pull qwen2.5-coder:32b
ollama serve   # Starts on port 11434

Sau đó cấu hình Hermes:

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:11434/v1
# Skip API key (Ollama doesn't need one)
# Enter model name (e.g. qwen2.5-coder:32b)

Hoặc định cấu hình trực tiếp config.yaml:

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768   # See warning below

Ollama defaults to very low context lengths

Theo mặc định, Ollama không sử dụng cửa sổ ngữ cảnh đầy đủ của mô hình của bạn. Tùy thuộc vào VRAM của bạn, mặc định là:

VRAM có sẵn	Bối cảnh mặc định
Dưới 24 GB	4.096 token
24–48 GB	32.768 token
48+GB	256.000 token

Để sử dụng tác nhân bằng các công cụ, bạn cần ít nhất 16k–32k bối cảnh. Ở mức 4k, chỉ riêng lời nhắc hệ thống + lược đồ công cụ có thể lấp đầy cửa sổ, không còn chỗ cho cuộc trò chuyện.

Cách tăng (chọn một):

# Option 1: Set server-wide via environment variable (recommended)
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

# Option 2: For systemd-managed Ollama
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_CONTEXT_LENGTH=32768"
# Then: sudo systemctl daemon-reload && sudo systemctl restart ollama

# Option 3: Bake it into a custom model (persistent per-model)
echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 32768" > Modelfile
ollama create qwen2.5-coder-32k -f Modelfile

Bạn không thể đặt độ dài ngữ cảnh thông qua API tương thích với OpenAI (/v1/chat/completions). Nó phải được cấu hình phía máy chủ hoặc thông qua Modelfile. Đây là nguyên nhân gây nhầm lẫn số 1 khi tích hợp Ollama với các công cụ như Hermes.

Xác minh bối cảnh của bạn được đặt chính xác:

ollama ps
# Look at the CONTEXT column — it should show your configured value

mẹo

Liệt kê các mẫu có sẵn bằng danh sách ollama. Kéo bất kỳ mô hình nào từ thư viện Ollama bằng ollama pull <model>. Ollama tự động xử lý việc giảm tải GPU — không cần cấu hình cho hầu hết các thiết lập.

vLLM — Suy luận GPU hiệu suất cao

vLLM là tiêu chuẩn để phân phát LLM sản xuất. Tốt nhất cho: thông lượng tối đa trên phần cứng GPU, phục vụ các mô hình lớn, phân khối liên tục.

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Sau đó cấu hình Hermes:

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8000/v1
# Skip API key (or enter one if you configured vLLM with --api-key)
# Enter model name: meta-llama/Llama-3.1-70B-Instruct

Độ dài ngữ cảnh: vLLM đọc max_position_embeddings của mô hình theo mặc định. Nếu vượt quá bộ nhớ GPU của bạn, nó sẽ báo lỗi và yêu cầu bạn đặt --max-model-len thấp hơn. Bạn cũng có thể sử dụng --max-model-len auto để tự động tìm mức tối đa phù hợp. Đặt --gpu-memory-utilization 0,95 (mặc định 0,9) để thu thập thêm ngữ cảnh vào VRAM.

Việc gọi công cụ yêu cầu có cờ rõ ràng:

Cờ	Mục đích
`--enable-auto-tool-lựa chọn`	Bắt buộc đối với `tool_choice: "auto"` (mặc định trong Hermes)
`--tool-call-parser <name>`	Trình phân tích cú pháp cho định dạng lệnh gọi công cụ của mô hình

Các trình phân tích cú pháp được hỗ trợ: hermes (Qwen 2.5, Hermes 2/3), llama3_json (Llama 3.x), mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Nếu không có những cờ này, lệnh gọi công cụ sẽ không hoạt động — mô hình sẽ xuất lệnh gọi công cụ dưới dạng văn bản.

mẹo

vLLM hỗ trợ các kích thước mà con người có thể đọc được: --max-model-len 64k (chữ thường k = 1000, chữ hoa K = 1024).

SGLang — Phục vụ nhanh chóng với RadixAttention

SGLang là một giải pháp thay thế cho vLLM với RadixAttention để tái sử dụng bộ đệm KV. Tốt nhất cho: cuộc hội thoại nhiều lượt (bộ nhớ đệm tiền tố), giải mã có giới hạn, đầu ra có cấu trúc.

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

Sau đó cấu hình Hermes:

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:30000/v1
# Enter model name: meta-llama/Llama-3.1-70B-Instruct

Độ dài ngữ cảnh: SGLang đọc từ cấu hình của mô hình theo mặc định. Sử dụng --context-length để ghi đè. Nếu bạn cần vượt quá mức tối đa đã khai báo của mô hình, hãy đặt SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1.

Gọi công cụ: Sử dụng --tool-call-parser với trình phân tích cú pháp thích hợp cho dòng mô hình của bạn: qwen (Qwen 2.5), llama3, llama4, deepseekv3, mistral, glm. Nếu không có cờ này, lệnh gọi công cụ sẽ trở lại dưới dạng văn bản thuần túy.

SGLang defaults to 128 max output tokens

Nếu phản hồi có vẻ bị cắt ngắn, hãy thêm max_tokens vào yêu cầu của bạn hoặc đặt --default-max-tokens trên máy chủ. Mặc định của SGLang chỉ là 128 mã thông báo cho mỗi phản hồi nếu không được chỉ định trong yêu cầu.

llama.cpp / llama-server — Suy luận CPU & kim loại

llama.cpp chạy các mô hình lượng tử hóa trên CPU, Apple Silicon (Metal) và GPU tiêu dùng. Tốt nhất cho: chạy các mô hình không có GPU trung tâm dữ liệu, người dùng Mac, triển khai biên.

# Build and start llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

Độ dài ngữ cảnh (-c): Các bản dựng gần đây mặc định là 0 đọc ngữ cảnh đào tạo của mô hình từ siêu dữ liệu GGUF. Đối với các mô hình có bối cảnh đào tạo hơn 128k, điều này có thể xảy ra khi cố gắng phân bổ toàn bộ bộ nhớ đệm KV. Đặt -c một cách rõ ràng theo những gì bạn cần (32k–64k là một phạm vi phù hợp để sử dụng cho tác nhân). Nếu sử dụng các vị trí song song (-np), tổng bối cảnh được chia cho các vị trí — với -c 32768 -np 4, mỗi vị trí chỉ nhận được 8k.

Sau đó cấu hình Hermes để trỏ vào nó:

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8080/v1
# Skip API key (local servers don't need one)
# Enter model name — or leave blank to auto-detect if only one model is loaded

Thao tác này sẽ lưu điểm cuối vào config.yaml để điểm cuối này tồn tại qua các phiên.

--jinja is required for tool calling

Không có --jinja, llama-server hoàn toàn bỏ qua tham số tools. Mô hình sẽ cố gắng gọi các công cụ bằng cách viết JSON trong văn bản phản hồi của nó, nhưng Hermes sẽ không nhận ra đó là lệnh gọi công cụ — bạn sẽ thấy JSON thô như {"name": "web_search", ...} được in dưới dạng tin nhắn thay vì tìm kiếm thực tế.

Hỗ trợ gọi công cụ gốc (hiệu suất tốt nhất): Llama 3.x, Qwen 2.5 (bao gồm Coder), Hermes 2/3, Mistral, DeepSeek, Functionary. Tất cả các mô hình khác đều sử dụng trình xử lý chung hoạt động nhưng có thể kém hiệu quả hơn. Xem tài liệu gọi hàm llama.cpp để biết danh sách đầy đủ.

Bạn có thể xác minh hỗ trợ công cụ đang hoạt động bằng cách kiểm tra http://localhost:8080/props — phải có trường chat_template.

mẹo

Tải xuống các mô hình GGUF từ Ôm mặt. Lượng tử hóa Q4_K_M mang lại sự cân bằng tốt nhất giữa chất lượng và mức sử dụng bộ nhớ.

LM Studio — Ứng dụng máy tính để bàn với các mô hình cục bộ

LM Studio là một ứng dụng dành cho máy tính để bàn để chạy các mô hình cục bộ bằng GUI. Tốt nhất cho: người dùng thích giao diện trực quan, thử nghiệm mô hình nhanh, nhà phát triển trên macOS/Windows/Linux.

Khởi động máy chủ từ ứng dụng LM Studio (tab Nhà phát triển → Máy chủ khởi động) hoặc sử dụng CLI:

lms server start                        # Starts on port 1234
lms load qwen2.5-coder --context-length 32768

Sau đó cấu hình Hermes:

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:1234/v1
# Skip API key (LM Studio doesn't require one)
# Enter model name

Context length often defaults to 2048

LM Studio đọc độ dài ngữ cảnh từ siêu dữ liệu của mô hình, nhưng nhiều mô hình GGUF báo cáo giá trị mặc định thấp (2048 hoặc 4096). Luôn đặt rõ ràng độ dài ngữ cảnh trong cài đặt mô hình LM Studio:

Nhấp vào biểu tượng bánh răng bên cạnh bộ chọn mô hình
Đặt "Độ dài bối cảnh" ít nhất là 16384 (tốt nhất là 32768)
Tải lại mô hình để thay đổi có hiệu lực

Ngoài ra, hãy sử dụng CLI: lms load model-name --context-length 32768

Để đặt các giá trị mặc định cố định cho mỗi mô hình: tab Mô hình của tôi → biểu tượng bánh răng trên mô hình → đặt kích thước ngữ cảnh.

Gọi công cụ: Được hỗ trợ kể từ LM Studio 0.3.6. Các mô hình được đào tạo gọi công cụ gốc (Qwen 2.5, Llama 3.x, Mistral, Hermes) được tự động phát hiện và hiển thị cùng với huy hiệu công cụ. Các mô hình khác sử dụng một dự phòng chung có thể kém tin cậy hơn.

Mạng WSL2 (Người dùng Windows)

Vì Hermes Agent yêu cầu môi trường Unix nên người dùng Windows sẽ chạy nó bên trong WSL2. Nếu máy chủ mô hình của bạn (Ollama, LM Studio, v.v.) chạy trên máy chủ Windows, thì bạn cần thu hẹp khoảng cách mạng — WSL2 sử dụng bộ điều hợp mạng ảo với mạng con riêng của nó, vì vậy localhost bên trong WSL2 đề cập đến máy ảo Linux, không máy chủ Windows.

Both in WSL2? No problem.

Nếu máy chủ mô hình của bạn cũng chạy bên trong WSL2 (phổ biến cho vLLM, SGLang và llama-server), localhost hoạt động như mong đợi — chúng chia sẻ cùng một không gian tên mạng. Bỏ qua phần này.

Tùy chọn 1: Chế độ kết nối mạng được nhân đôi (Được khuyến nghị)

Có sẵn trên Windows 11 22H2+, chế độ phản chiếu giúp localhost hoạt động hai chiều giữa Windows và WSL2 — cách khắc phục đơn giản nhất.

Tạo hoặc chỉnh sửa %USERPROFILE%\.wslconfig (ví dụ: C:\Users\YourName\.wslconfig):
```
[wsl2]
networkingMode=mirrored
```
Khởi động lại WSL từ PowerShell:
```
wsl --shutdown
```
Mở lại thiết bị đầu cuối WSL2 của bạn. localhost hiện có sẵn trên các dịch vụ Windows:
```
curl http://localhost:11434/v1/models   # Ollama on Windows — works
```

Hyper-V Firewall

Trên một số bản dựng Windows 11, tường lửa Hyper-V chặn các kết nối được nhân đôi theo mặc định. Nếu localhost vẫn không hoạt động sau khi bật chế độ phản chiếu, hãy chạy chế độ này trong PowerShell quản trị:

Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow

Tùy chọn 2: Sử dụng IP máy chủ Windows (Windows 10 / bản dựng cũ hơn)

If you can't use mirrored mode, find the Windows host IP from inside WSL2 and use that instead of localhost:

# Get the Windows host IP (the default gateway of WSL2's virtual network)
ip route show | grep -i default | awk '{ print $3 }'
# Example output: 172.29.192.1

Use that IP in your Hermes config:

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows host IP, not localhost

Dynamic helper

The host IP can change on WSL2 restart. You can grab it dynamically in your shell:

export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }')
echo "Windows host at: $WSL_HOST"
curl http://$WSL_HOST:11434/v1/models   # Test Ollama

Or use your machine's mDNS name (requires libnss-mdns in WSL2):

sudo apt install libnss-mdns
curl http://$(hostname).local:11434/v1/models

Server Bind Address (Required for NAT Mode)

If you're using Option 2 (NAT mode with the host IP), the model server on Windows must accept connections from outside 127.0.0.1. By default, most servers only listen on localhost — WSL2 connections in NAT mode come from a different virtual subnet and will be refused. In mirrored mode, localhost maps directly so the default 127.0.0.1 binding works fine.

Server	Default bind	How to fix
Ollama	`127.0.0.1`	Set `OLLAMA_HOST=0.0.0.0` environment variable before starting Ollama (System Settings → Environment Variables on Windows, or edit the Ollama service)
LM Studio	`127.0.0.1`	Enable "Serve on Network" in the Developer tab → Server settings
llama-server	`127.0.0.1`	Add `--host 0.0.0.0` to the startup command
vLLM	`0.0.0.0`	Already binds to all interfaces by default
SGLang	`127.0.0.1`	Add `--host 0.0.0.0` to the startup command

Ollama on Windows (detailed): Ollama runs as a Windows service. To set OLLAMA_HOST:

Open System Properties → Environment Variables
Add a new System variable: OLLAMA_HOST = 0.0.0.0
Restart the Ollama service (or reboot)

Windows Firewall

Windows Firewall treats WSL2 as a separate network (in both NAT and mirrored mode). If connections still fail after the steps above, add a firewall rule for your model server's port:

# Run in Admin PowerShell — replace PORT with your server's port
New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434

Common ports: Ollama 11434, vLLM 8000, SGLang 30000, llama-server 8080, LM Studio 1234.

Quick Verification

From inside WSL2, test that you can reach your model server:

# Replace URL with your server's address and port
curl http://localhost:11434/v1/models          # Mirrored mode
curl http://172.29.192.1:11434/v1/models       # NAT mode (use your actual host IP)

If you get a JSON response listing your models, you're good. Use that same URL as the base_url in your Hermes config.

Troubleshooting Local Models

These issues affect all local inference servers when used with Hermes.

"Connection refused" from WSL2 to a Windows-hosted model server

If you're running Hermes inside WSL2 and your model server on the Windows host, http://localhost:<port> won't work in WSL2's default NAT networking mode. See WSL2 Networking above for the fix.

Tool calls appear as text instead of executing

The model outputs something like {"name": "web_search", "arguments": {...}} as a message instead of actually calling the tool.

Cause: Your server doesn't have tool calling enabled, or the model doesn't support it through the server's tool calling implementation.

Server	Fix
llama.cpp	Add `--jinja` to the startup command
vLLM	Add `--enable-auto-tool-choice --tool-call-parser hermes`
SGLang	Add `--tool-call-parser qwen` (or appropriate parser)
Ollama	Tool calling is enabled by default — make sure your model supports it (check with `ollama show model-name`)
LM Studio	Update to 0.3.6+ and use a model with native tool support

Model seems to forget context or give incoherent responses

Cause: Context window is too small. When the conversation exceeds the context limit, most servers silently drop older messages. Hermes's system prompt + tool schemas alone can use 4k–8k tokens.

Diagnosis:

# Check what Hermes thinks the context is
# Look at startup line: "Context limit: X tokens"

# Check your server's actual context
# Ollama: ollama ps (CONTEXT column)
# llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM: check --max-model-len in startup args

Fix: Set context to at least 32,768 tokens for agent use. See each server's section above for the specific flag.

"Context limit: 2048 tokens" at startup

Hermes auto-detects context length from your server's /v1/models endpoint. If the server reports a low value (or doesn't report one at all), Hermes uses the model's declared limit which may be wrong.

Fix: Set it explicitly in config.yaml:

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Responses get cut off mid-sentence

Possible causes:

Low max_tokens on the server — SGLang defaults to 128 tokens per response. Set --default-max-tokens on the server or configure Hermes with model.max_tokens in config.yaml.
Context exhaustion — The model filled its context window. Increase context length or enable context compression in Hermes.

LiteLLM Proxy — Multi-Provider Gateway

LiteLLM is an OpenAI-compatible proxy that unifies 100+ LLM providers behind a single API. Best for: switching between providers without config changes, load balancing, fallback chains, budget controls.

# Install and start
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000

# Or with a config file for multiple models:
litellm --config litellm_config.yaml --port 4000

Then configure Hermes with hermes model → Custom endpoint → http://localhost:4000/v1.

Example litellm_config.yaml with fallback:

model_list:
  - model_name: "best"
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
  - model_name: "best"
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...
router_settings:
  routing_strategy: "latency-based-routing"

ClawRouter — Cost-Optimized Routing

ClawRouter by BlockRunAI is a local routing proxy that auto-selects models based on query complexity. It classifies requests across 14 dimensions and routes to the cheapest model that can handle the task. Payment is via USDC cryptocurrency (no API keys).

# Install and start
npx @blockrun/clawrouter    # Starts on port 8402

Then configure Hermes with hermes model → Custom endpoint → http://localhost:8402/v1 → model name blockrun/auto.

Routing profiles:

Profile	Strategy	Savings
`blockrun/auto`	Balanced quality/cost	74-100%
`blockrun/eco`	Cheapest possible	95-100%
`blockrun/premium`	Best quality models	0%
`blockrun/free`	Free models only	100%
`blockrun/agentic`	Optimized for tool use	varies

ghi chú

ClawRouter requires a USDC-funded wallet on Base or Solana for payment. All requests route through BlockRun's backend API. Run npx @blockrun/clawrouter doctor to check wallet status.

Other Compatible Providers

Any service with an OpenAI-compatible API works. Some popular options:

Provider	Base URL	Notes
Together AI	`https://api.together.xyz/v1`	Cloud-hosted open models
Groq	`https://api.groq.com/openai/v1`	Ultra-fast inference
DeepSeek	`https://api.deepseek.com/v1`	DeepSeek models
Fireworks AI	`https://api.fireworks.ai/inference/v1`	Fast open model hosting
Cerebras	`https://api.cerebras.ai/v1`	Wafer-scale chip inference
Mistral AI	`https://api.mistral.ai/v1`	Mistral models
OpenAI	`https://api.openai.com/v1`	Direct OpenAI access
Azure OpenAI	`https://YOUR.openai.azure.com/`	Enterprise OpenAI
LocalAI	`http://localhost:8080/v1`	Self-hosted, multi-model
Jan	`http://localhost:1337/v1`	Desktop app with local models

Configure any of these with hermes model → Custom endpoint, or in config.yaml:

model:
  default: meta-llama/Llama-3.1-70B-Instruct-Turbo
  provider: custom
  base_url: https://api.together.xyz/v1
  api_key: your-together-key

Context Length Detection

Hermes uses a multi-source resolution chain to detect the correct context window for your model and provider:

Config override — model.context_length in config.yaml (highest priority)
Custom provider per-model — custom_providers[].models.<id>.context_length
Persistent cache — previously discovered values (survives restarts)
Endpoint /models — queries your server's API (local/custom endpoints)
Anthropic /v1/models — queries Anthropic's API for max_input_tokens (API-key users only)
OpenRouter API — live model metadata from OpenRouter
Nous Portal — suffix-matches Nous model IDs against OpenRouter metadata
models.dev — community-maintained registry with provider-specific context lengths for 3800+ models across 100+ providers
Fallback defaults — broad model family patterns (128K default)

For most setups this works out of the box. The system is provider-aware — the same model can have different context limits depending on who serves it (e.g., claude-opus-4.6 is 1M on Anthropic direct but 128K on GitHub Copilot).

To set the context length explicitly, add context_length to your model config:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072  # tokens

For custom endpoints, you can also set context length per model:

custom_providers:
  - name: "My Local LLM"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768
      deepseek-r1:70b:
        context_length: 65536

hermes model will prompt for context length when configuring a custom endpoint. Leave it blank for auto-detection.

When to set this manually

You're using Ollama with a custom num_ctx that's lower than the model's maximum
You want to limit context below the model's maximum (e.g., 8k on a 128k model to save VRAM)
You're running behind a proxy that doesn't expose /v1/models

Named Custom Providers

If you work with multiple custom endpoints (e.g., a local dev server and a remote GPU server), you can define them as named custom providers in config.yaml:

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions   # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages  # for Anthropic-compatible proxies

Switch between them mid-session with the triple syntax:

/model custom:local:qwen-2.5       # Use the "local" endpoint with qwen-2.5
/model custom:work:llama3-70b      # Use the "work" endpoint with llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4  # Use the proxy

You can also select named custom providers from the interactive hermes model menu.

Choosing the Right Setup

Use Case	Recommended
Just want it to work	OpenRouter (default) or Nous Portal
Local models, easy setup	Ollama
Production GPU serving	vLLM or SGLang
Mac / no GPU	Ollama or llama.cpp
Multi-provider routing	LiteLLM Proxy or OpenRouter
Cost optimization	ClawRouter or OpenRouter with `sort: "price"`
Maximum privacy	Ollama, vLLM, or llama.cpp (fully local)
Enterprise / Azure	Azure OpenAI with custom endpoint
Chinese AI models	z.ai (GLM), Kimi/Moonshot, or MiniMax (first-class providers)

mẹo

You can switch between providers at any time with hermes model — no restart required. Your conversation history, memory, and skills carry over regardless of which provider you use.

Optional API Keys

Feature	Provider	Env Variable
Web scraping	Firecrawl	`FIRECRAWL_API_KEY`, `FIRECRAWL_API_URL`
Browser automation	Browserbase	`BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`
Image generation	FAL	`FAL_KEY`
Premium TTS voices	ElevenLabs	`ELEVENLABS_API_KEY`
OpenAI TTS + voice transcription	OpenAI	`VOICE_TOOLS_OPENAI_KEY`
RL Training	Tinker + WandB	`TINKER_API_KEY`, `WANDB_API_KEY`
Cross-session user modeling	Honcho	`HONCHO_API_KEY`
Semantic long-term memory	Supermemory	`SUPERMEMORY_API_KEY`

Self-Hosting Firecrawl

By default, Hermes uses the Firecrawl cloud API for web search and scraping. If you prefer to run Firecrawl locally, you can point Hermes at a self-hosted instance instead. See Firecrawl's SELF_HOST.md for complete setup instructions.

What you get: No API key required, no rate limits, no per-page costs, full data sovereignty.

What you lose: The cloud version uses Firecrawl's proprietary "Fire-engine" for advanced anti-bot bypassing (Cloudflare, CAPTCHAs, IP rotation). Self-hosted uses basic fetch + Playwright, so some protected sites may fail. Search uses DuckDuckGo instead of Google.

Setup:

Clone and start the Firecrawl Docker stack (5 containers: API, Playwright, Redis, RabbitMQ, PostgreSQL — requires ~4-8 GB RAM):

git clone https://github.com/firecrawl/firecrawl
cd firecrawl
# In .env, set: USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002
docker compose up -d

Point Hermes at your instance (no API key needed):

hermes config set FIRECRAWL_API_URL http://localhost:3002

You can also set both FIRECRAWL_API_KEY and FIRECRAWL_API_URL if your self-hosted instance has authentication enabled.

OpenRouter Provider Routing

When using OpenRouter, you can control how requests are routed across providers. Add a provider_routing section to ~/.hermes/config.yaml:

provider_routing:
  sort: "throughput"          # "price" (default), "throughput", or "latency"
  # only: ["anthropic"]      # Only use these providers
  # ignore: ["deepinfra"]    # Skip these providers
  # order: ["anthropic", "google"]  # Try providers in this order
  # require_parameters: true  # Only use providers that support all request params
  # data_collection: "deny"   # Exclude providers that may store/train on data

Shortcuts: Append :nitro to any model name for throughput sorting (e.g., anthropic/claude-sonnet-4:nitro), or :floor for price sorting.

Fallback Model

Configure a backup provider:model that Hermes switches to automatically when your primary model fails (rate limits, server errors, auth failures):

fallback_model:
  provider: openrouter                    # required
  model: anthropic/claude-sonnet-4        # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name for custom endpoint API key

When activated, the fallback swaps the model and provider mid-session without losing your conversation. It fires at most once per session.

Supported providers: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.

mẹo

Fallback is configured exclusively through config.yaml — there are no environment variables for it. For full details on when it triggers, supported providers, and how it interacts with auxiliary tasks and delegation, see Fallback Providers.

Smart Model Routing

Optional cheap-vs-strong routing lets Hermes keep your main model for complex work while sending very short/simple turns to a cheaper model.

smart_model_routing:
  enabled: true
  max_simple_chars: 160
  max_simple_words: 28
  cheap_model:
    provider: openrouter
    model: google/gemini-2.5-flash
    # base_url: http://localhost:8000/v1  # optional custom endpoint
    # api_key_env: MY_CUSTOM_KEY          # optional env var name for that endpoint's API key

How it works:

If a turn is short, single-line, and does not look code/tool/debug heavy, Hermes may route it to cheap_model
If the turn looks complex, Hermes stays on your primary model/provider
If the cheap route cannot be resolved cleanly, Hermes falls back to the primary model automatically

This is intentionally conservative. It is meant for quick, low-stakes turns like:

short factual questions
quick rewrites
lightweight summaries

It will avoid routing prompts that look like:

coding/debugging work
tool-heavy requests
long or multi-line analysis asks

Use this when you want lower latency or cost without fully changing your default model.

Nhà cung cấp suy luận​

Nhân chủng học (Bản địa)​

Phi công phụ GitHub​

Nhà cung cấp AI Trung Quốc hạng nhất​

xAI (Grok) Bộ nhớ đệm nhắc nhở​

Nhà cung cấp suy luận ôm mặt​

Nhà cung cấp LLM tùy chỉnh và tự lưu trữ​

Cài đặt chung​

Chuyển đổi mô hình bằng /model​

Ollama — Mô hình cục bộ, không cần cấu hình​

vLLM — Suy luận GPU hiệu suất cao​

SGLang — Phục vụ nhanh chóng với RadixAttention​

llama.cpp / llama-server — Suy luận CPU & kim loại​

LM Studio — Ứng dụng máy tính để bàn với các mô hình cục bộ​

Mạng WSL2 (Người dùng Windows)​

Tùy chọn 1: Chế độ kết nối mạng được nhân đôi (Được khuyến nghị)​

Tùy chọn 2: Sử dụng IP máy chủ Windows (Windows 10 / bản dựng cũ hơn)​

Server Bind Address (Required for NAT Mode)​

Windows Firewall​

Quick Verification​

Troubleshooting Local Models​

"Connection refused" from WSL2 to a Windows-hosted model server​

Tool calls appear as text instead of executing​

Model seems to forget context or give incoherent responses​

"Context limit: 2048 tokens" at startup​

Responses get cut off mid-sentence​

LiteLLM Proxy — Multi-Provider Gateway​

ClawRouter — Cost-Optimized Routing​

Other Compatible Providers​

Context Length Detection​

Named Custom Providers​

Choosing the Right Setup​

Optional API Keys​

Self-Hosting Firecrawl​

OpenRouter Provider Routing​

Fallback Model​

Smart Model Routing​

See Also​

Nhà cung cấp suy luận

Nhân chủng học (Bản địa)

Phi công phụ GitHub

Nhà cung cấp AI Trung Quốc hạng nhất

xAI (Grok) Bộ nhớ đệm nhắc nhở

Nhà cung cấp suy luận ôm mặt

Nhà cung cấp LLM tùy chỉnh và tự lưu trữ

Cài đặt chung

Chuyển đổi mô hình bằng `/model`

Ollama — Mô hình cục bộ, không cần cấu hình

vLLM — Suy luận GPU hiệu suất cao

SGLang — Phục vụ nhanh chóng với RadixAttention

llama.cpp / llama-server — Suy luận CPU & kim loại

LM Studio — Ứng dụng máy tính để bàn với các mô hình cục bộ

Mạng WSL2 (Người dùng Windows)

Tùy chọn 1: Chế độ kết nối mạng được nhân đôi (Được khuyến nghị)

Tùy chọn 2: Sử dụng IP máy chủ Windows (Windows 10 / bản dựng cũ hơn)

Server Bind Address (Required for NAT Mode)

Windows Firewall

Quick Verification

Troubleshooting Local Models

"Connection refused" from WSL2 to a Windows-hosted model server

Tool calls appear as text instead of executing

Model seems to forget context or give incoherent responses

"Context limit: 2048 tokens" at startup

Responses get cut off mid-sentence

LiteLLM Proxy — Multi-Provider Gateway

ClawRouter — Cost-Optimized Routing

Other Compatible Providers

Context Length Detection

Named Custom Providers

Choosing the Right Setup

Optional API Keys

Self-Hosting Firecrawl

OpenRouter Provider Routing

Fallback Model

Smart Model Routing

See Also