XiuChengWu
4745ce1f1c
Some checks failed
- Introduced `ai_endpoint_mgr` plugin to manage multiple AI provider endpoints. - Added configuration reference documentation for `config.toml`. - Implemented endpoint loading, active endpoint switching, and model mutation. - Included error handling for missing endpoints and configuration failures. - Developed unit tests covering various scenarios including error paths and concurrency.
157 lines
5.0 KiB
Markdown
157 lines
5.0 KiB
Markdown
# 配置参考 / Configuration Reference
|
||
|
||
`config.toml` 是 dstalk 的唯一配置文件，放在项目根目录。本文档列出所有支持字段、类型、默认值与使用说明。
|
||
|
||
---
|
||
|
||
## 配置概览
|
||
|
||
配置分为两种模式：
|
||
|
||
| 模式 | 适用场景 | 核心 key |
|
||
|------|----------|----------|
|
||
| **单 Provider** | 只需一个 AI 后端 | `ai.provider`, `api.*` |
|
||
| **多 Endpoint** | 同时配置多个 AI 后端，运行时切换 | `endpoints.names`, `endpoint.<name>.*` |
|
||
|
||
两种模式可以同时配置，但 `ai_endpoint_mgr` 的 `chat` / `chat_stream` 调用优先走 `endpoints.*`。
|
||
|
||
---
|
||
|
||
## 一、单 Provider 模式 (Legacy)
|
||
|
||
直接在 `[global]` 下声明。这些 key 无默认值——不配置则无法启动 AI 对话。
|
||
|
||
### ai.provider
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **值**: `"ai_openai"` 或 `"ai_anthropic"`
|
||
- **说明**: 指定要加载的 AI provider 插件。该名称对应插件 DLL 注册的服务名。
|
||
|
||
### api.base_url
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **说明**: AI API 的基础 URL。例如:
|
||
- OpenAI: `https://api.openai.com/v1`
|
||
- Anthropic: `https://api.anthropic.com`
|
||
- DeepSeek (OpenAI 兼容): `https://api.deepseek.com/v1`
|
||
|
||
### api.api_key
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **说明**: API 密钥。注意保管，不要提交到版本控制。
|
||
|
||
### api.model
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **说明**: 要使用的模型名称。例如 `gpt-4o`、`claude-sonnet-4-20250514`、`deepseek-chat`。
|
||
|
||
---
|
||
|
||
## 二、多 Endpoint 模式 (推荐)
|
||
|
||
由 `ai_endpoint_mgr` 插件管理。每个 endpoint 是一个命名的 AI 后端配置，运行时可通过 `/endpoint` 命令切换。
|
||
|
||
### endpoints.names
|
||
|
||
- **类型**: string (逗号分隔)
|
||
- **默认**: 无
|
||
- **说明**: 所有要启用的 endpoint 名称列表。例如 `"openai_main, anthropic_alt"`。重复名称会被跳过并输出警告。
|
||
|
||
### endpoints.active
|
||
|
||
- **类型**: string
|
||
- **默认**: 取 `endpoints.names` 中第一个成功加载的 endpoint
|
||
- **说明**: 启动时默认使用的 endpoint 名称。如果指定的名称不在 `endpoints.names` 中或对应配置无效，则回退到第一个成功加载的 endpoint。
|
||
|
||
---
|
||
|
||
### endpoint.\<name\>.provider
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **值**: `"ai_openai"` 或 `"ai_anthropic"`
|
||
- **说明**: 该 endpoint 使用的 AI provider 服务名称。
|
||
|
||
### endpoint.\<name\>.base_url
|
||
|
||
- **类型**: string
|
||
- **默认**: 按 provider 自动推导
|
||
- **说明**:
|
||
- 未配置时，已知 provider 自动使用默认 base_url:
|
||
- `ai_anthropic` → `https://api.anthropic.com`
|
||
- `ai_openai` → `https://api.openai.com/v1`
|
||
- 如果 provider 不在已知列表中，**必须**显式配置 `base_url`，否则该 endpoint 加载失败。
|
||
- 显式配置的值优先于默认值，可用于自定义端点（如代理、DeepSeek 兼容 API 等）。
|
||
|
||
### endpoint.\<name\>.api_key
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **说明**: 该 endpoint 的 API 密钥。
|
||
|
||
> **安全提示**: `api_key` **不会**出现在 `list_json()` 的输出中，也不进入日志。这是有意为之的安全策略。
|
||
|
||
### endpoint.\<name\>.model
|
||
|
||
- **类型**: string
|
||
- **默认**: 无（必填）
|
||
- **说明**: 该 endpoint 默认使用的模型名称。运行时可通过 `set_model()` 修改并同步回 `config.toml`。
|
||
|
||
### endpoint.\<name\>.max_tokens
|
||
|
||
- **类型**: integer
|
||
- **默认**: `4096`
|
||
- **范围**: `1` ~ `1000000`（超出范围的值视为无效，回退到默认值）
|
||
- **说明**: 每次请求的最大输出 token 数。
|
||
|
||
### endpoint.\<name\>.temperature
|
||
|
||
- **类型**: double
|
||
- **默认**: `0.7`
|
||
- **范围**: `0.0` ~ `2.0`（超出范围的值视为无效，回退到默认值）
|
||
- **说明**: 生成温度。越高随机性越强，越低越确定性。
|
||
|
||
---
|
||
|
||
## 三、ui 配置 (可选 / optional)
|
||
|
||
以下 key 目前为 CLI 前端预留，后续 GUI/Web 前端也会使用。
|
||
|
||
### ui.prompt
|
||
|
||
- **类型**: string
|
||
- **默认**: `"> "`
|
||
- **说明**: 命令行提示符字符串。
|
||
|
||
### ui.multiline
|
||
|
||
- **类型**: string
|
||
- **默认**: `"/"` （即不支持多行输入）
|
||
- **说明**: 多行输入结束符。发送该字符串结束多行输入模式。
|
||
|
||
---
|
||
|
||
## 四、完整配置示例
|
||
|
||
见项目根目录 `config.example.toml`。
|
||
|
||
---
|
||
|
||
## 五、运行时 endpoint 操作
|
||
|
||
`ai_endpoint_mgr` 服务提供以下接口（通过 C ABI）供前端调用:
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| `count()` | 返回已加载的 endpoint 数量 |
|
||
| `list_json()` | 返回 JSON 数组，每项含 `name`, `provider`, `base_url`, `model`, `active` （不含 `api_key`） |
|
||
| `get_active()` | 返回当前激活的 endpoint 名称 |
|
||
| `set_active(name)` | 切换激活 endpoint；返回 0 成功，-2 表示不存在 |
|
||
| `set_model(name, model)` | 修改 endpoint 的模型并同步到 config；name 为 null 时作用于当前 active endpoint |
|
||
| `chat(ep, history, len, input, tools)` | 路由对话到指定 endpoint（ep 为 null 时用 active） |
|
||
| `chat_stream(ep, history, len, input, cb, userdata)` | 流式路由对话 |
|