158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
---
|
||
name: oneapi-custom-endpoint-setup
|
||
description: "Use when connecting Hermes Agent to a OneAPI-compatible proxy endpoint — set base_url, api_key, default model, auxiliary models, and delegation models."
|
||
version: 1.0.0
|
||
author: Hermes Agent
|
||
license: MIT
|
||
metadata:
|
||
hermes:
|
||
tags: [oneapi, custom-endpoint, proxy, model-config, deployment]
|
||
related_skills: [hermes-agent]
|
||
---
|
||
|
||
# OneAPI / Custom Endpoint Setup
|
||
|
||
## Overview
|
||
|
||
OneAPI 提供了 OpenAI 兼容的 API 接口，可以作为 Hermes Agent 的模型后端。通过它可以用一个统一入口接入多个模型（如通义千问系列、嵌入模型等）。
|
||
|
||
配置项涉及三个层级：
|
||
|
||
1. **主模型** — 对话默认使用的模型
|
||
2. **辅助模型** — 压缩等后台任务使用的轻量模型
|
||
3. **子 Agent 模型** — `delegate_task` 子任务使用的模型
|
||
|
||
## When to Use
|
||
|
||
- 你有一个 OpenAI 兼容的 API 代理端点（如 OneAPI、NewAPI、LiteLLM 等）
|
||
- 需要接入私有部署的模型服务
|
||
- 想为不同任务分配不同规格的模型（大模型做主对话，小模型做压缩）
|
||
|
||
## 前置检查
|
||
|
||
确认端点可用：
|
||
|
||
```bash
|
||
# 查看可用模型列表
|
||
curl -s https://your-oneapi-domain/v1/models \
|
||
-H "Authorization: Bearer your-api-key" \
|
||
| python3 -m json.tool
|
||
|
||
# 测试对话
|
||
curl -s https://your-oneapi-domain/v1/chat/completions \
|
||
-H "Authorization: Bearer your-api-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"model":"model-name","messages":[{"role":"user","content":"Say hi"}]}'
|
||
```
|
||
|
||
> ⚠️ **HTTPS 必须**：如果服务同时支持 HTTP 和 HTTPS，一定要用 HTTPS。HTTP 返回 301 重定向，会导致 POST 请求变成 GET 从而返回 404。
|
||
|
||
## 配置步骤
|
||
|
||
### 1. 主模型
|
||
|
||
```bash
|
||
hermes config set model.base_url https://your-oneapi-domain/v1
|
||
hermes config set model.api_key your-api-key
|
||
hermes config set model.default your-chat-model-name
|
||
hermes config set model.key_env '' # 清除旧的 key_env 引用
|
||
```
|
||
|
||
`provider` 字段保持原值（如 `deepseek`）即可 — 实际请求由 `base_url` 决定。
|
||
|
||
### 2. 辅助压缩模型（后台任务用轻量模型）
|
||
|
||
```bash
|
||
hermes config set auxiliary.compression.model lightweight-model-name
|
||
hermes config set auxiliary.compression.base_url https://your-oneapi-domain/v1
|
||
hermes config set auxiliary.compression.api_key your-api-key
|
||
```
|
||
|
||
参考模型中对应 `auxiliary.{vision|web_extract|compression|...}` 等各个子任务，每个都支持独立配置 `model` / `base_url` / `api_key`。
|
||
|
||
推荐用轻量模型做压缩和标题生成等高频低强度任务。
|
||
|
||
### 3. 子 Agent 模型（delegation）
|
||
|
||
```bash
|
||
hermes config set delegation.model powerful-model-name
|
||
hermes config set delegation.base_url https://your-oneapi-domain/v1
|
||
hermes config set delegation.api_key your-api-key
|
||
```
|
||
|
||
子 Agent 处理高复杂度任务时可以用更大的模型。
|
||
|
||
### 4. 其他辅助任务设置
|
||
|
||
如果希望所有辅助任务也用同一个端点（而不走 `auto` 回退到 OpenRouter）：
|
||
|
||
```bash
|
||
hermes config set auxiliary.vision.base_url https://your-oneapi-domain/v1
|
||
hermes config set auxiliary.vision.api_key your-api-key
|
||
# 其他 auxiliary 子项类似：web_extract, title_generation, session_search 等
|
||
```
|
||
|
||
## 验证配置
|
||
|
||
```bash
|
||
hermes config show | grep -A5 -E "(Model|Delegat)"
|
||
```
|
||
|
||
查看输出确认 `base_url` 和 `api_key` 正确。
|
||
|
||
然后 `/reset` 新开 session 生效，输入 `Say hello` 测试。
|
||
|
||
## 典型配置示例
|
||
|
||
### 生产群场景
|
||
|
||
```yaml
|
||
model:
|
||
default: qwen3.6-35b-64k-cuda # 主对话用最强模型
|
||
base_url: https://your-oneapi-domain/v1
|
||
api_key: your-api-key
|
||
|
||
auxiliary:
|
||
compression:
|
||
model: qwen2.5:7b-128k # 后台压缩用轻量模型
|
||
base_url: https://your-oneapi-domain/v1
|
||
api_key: your-api-key
|
||
|
||
delegation:
|
||
model: qwen3.6-35b-64k-cuda # 子Agent用同一大模型
|
||
base_url: https://your-oneapi-domain/v1
|
||
api_key: your-api-key
|
||
```
|
||
|
||
### 多模型分层场景
|
||
|
||
```yaml
|
||
model:
|
||
default: Qwen3.6-27B-Q4_K_M # 中等模型做日常对话
|
||
base_url: https://oneapi-domain/v1
|
||
api_key: your-api-key
|
||
|
||
auxiliary:
|
||
compression:
|
||
model: qwen2.5:7b-128k # 轻量模型做压缩
|
||
|
||
delegation:
|
||
model: qwen3.6-35b-64k-cuda # 大模型做复杂子任务
|
||
base_url: https://oneapi-domain/v1
|
||
api_key: your-api-key
|
||
```
|
||
|
||
## 切换模型
|
||
|
||
配置完成后，在对话中用 `/model` 随时切换：
|
||
- `/model model-name` — 切换到指定模型（仅当前 session 有效）
|
||
- `/model` — 显示已支持的模型
|
||
|
||
## 注意事项
|
||
|
||
1. **必须用 HTTPS** — HTTP 请求会出现 301 重定向导致 POST→GET 引发 404
|
||
2. **OneAPI 的模型名区分大小写** — 需与 `/v1/models` 返回的 `id` 完全一致
|
||
3. **嵌入模型**（如 `bge-m3`）不能用于对话，如果作为主模型会报 500
|
||
4. **子任务的 model 字段仅一个字符串** — delegation 不支持配置多个模型
|
||
5. **配置后需 `/reset`** — tool/skill 变更需新 session 生效
|