diff --git a/skills/archived/oneapi-custom-endpoint-setup/SKILL.md b/skills/archived/oneapi-custom-endpoint-setup/SKILL.md new file mode 100644 index 0000000..175d3bb --- /dev/null +++ b/skills/archived/oneapi-custom-endpoint-setup/SKILL.md @@ -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 生效