Add archived/oneapi-custom-endpoint-setup

2026-07-10 16:10:55 +08:00
parent 40ccc9a036
commit 718326a371
1 changed files with 157 additions and 0 deletions
@@ -0,0 +1,157 @@
+---
+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 生效