gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

模型配置文档

Browse Source
This commit is contained in:
UnCLAS-Prommer
2025-07-31 15:33:56 +08:00
parent 84216a4df7
commit 303931e680
1 changed files with 285 additions and 356 deletions
Download Patch File Download Diff File Expand all files Collapse all files

641
docs/model_configuration_guide.md
View File

@@ -1,395 +1,324 @@
# MaiBot 模型配置指南 # 模型配置指南
本文档详细说明 MaiBot 的模型配置系统，包括 `model_config.toml` 和 `bot_config.toml` 中模型相关的配置项。 本文档将指导您如何配置 `model_config.toml` 文件，该文件用于配置 MaiBot 的各种AI模型和API服务提供商。
## 目录 ## 配置文件结构
1. [配置文件概述](#配置文件概述) 配置文件主要包含以下几个部分：
2. [model_config.toml 详细配置](#model_configtoml-详细配置) - 版本信息
3. [bot_config.toml 模型任务配置](#bot_configtoml-模型任务配置) - API服务提供商配置
4. [任务类型和能力系统](#任务类型和能力系统) - 模型配置
5. [多API Key支持](#多api-key支持) - 模型任务配置
6. [配置示例](#配置示例)
7. [最佳实践](#最佳实践)
8. [故障排除](#故障排除)
## 配置文件概述 ## 1. 版本信息
MaiBot 的模型配置分为两个文件：
- **`model_config.toml`**: 定义可用的模型、API提供商和基础配置
- **`bot_config.toml`**: 定义具体任务使用哪些模型以及模型参数
### 配置关系
```
model_config.toml → 定义模型池
↓
bot_config.toml → 从模型池中选择模型用于具体任务
```
## model_config.toml 详细配置
### 基础结构
```toml ```toml
[inner] [inner]
version = "0.2.1" # 配置文件版本 version = "1.1.1"
[request_conf] # 全局请求配置
[[api_providers]] # API服务提供商配置（可配置多个）
[[models]] # 模型配置（可配置多个）
[task_model_usage] # 任务模型使用配置
``` ```
### 1. 请求配置 [request_conf] 用于标识配置文件的版本，遵循语义化版本规则。
全局的API请求配置，影响所有模型调用： ## 2. API服务提供商配置
```toml ### 2.1 基本配置
[request_conf]
max_retry = 2 # 最大重试次数
timeout = 10 # API调用超时时长（秒）
retry_interval = 10 # 重试间隔（秒）
default_temperature = 0.7 # 默认温度值
default_max_tokens = 1024 # 默认最大输出token数
```
**参数说明：** 使用 `[[api_providers]]` 数组配置多个API服务提供商：
- `max_retry`: 单个API调用失败时的最大重试次数
- `timeout`: 单次API调用的超时时间，超过此时间请求将被取消
- `retry_interval`: API调用失败后的重试间隔时间
- `default_temperature`: 当bot_config.toml中未设置时的默认温度值
- `default_max_tokens`: 当bot_config.toml中未设置时的默认最大输出token数
### 2. API提供商配置 [[api_providers]]
配置各个API服务商的连接信息，支持多个提供商：
```toml ```toml
[[api_providers]] [[api_providers]]
name = "DeepSeek" # 提供商名称（自定义） name = "DeepSeek" # 服务商名称（自定义）
base_url = "https://api.deepseek.cn/v1" # API基础URL base_url = "https://api.deepseek.cn/v1" # API服务的基础URL
api_keys = [ # 多个API Key（推荐） api_key = "your-api-key-here" # API密钥
"sk-your-first-key-here", client_type = "openai" # 客户端类型
"sk-your-second-key-here", max_retry = 2 # 最大重试次数
"sk-your-third-key-here" timeout = 30 # 超时时间（秒）
] retry_interval = 10 # 重试间隔（秒）
# 或者使用单个key（向后兼容）
# key = "sk-your-single-key-here"
client_type = "openai" # 客户端类型
``` ```
**参数说明：** ### 2.2 配置参数说明
- `name`: 提供商的自定义名称，在models配置中引用
- `base_url`: API服务的基础URL
- `api_keys`: API密钥数组，支持多个key实现负载均衡和错误切换
- `key`: 单个API密钥（向后兼容，建议使用api_keys）
- `client_type`: 客户端类型，可选值：
- `"openai"`: OpenAI兼容格式（默认）
- `"gemini"`: Google Gemini专用格式
#### 多API Key优势 | 参数 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `name` | ✅ | 服务商名称，需要在模型配置中引用 | - |
| `base_url` | ✅ | API服务的基础URL | - |
| `api_key` | ✅ | API密钥，请替换为实际密钥 | - |
| `client_type` | ❌ | 客户端类型：`openai`（OpenAI格式）或 `gemini`（Gemini格式，现在支持不良好） | `openai` |
| `max_retry` | ❌ | API调用失败时的最大重试次数 | 2 |
| `timeout` | ❌ | API请求超时时间（秒） | 30 |
| `retry_interval` | ❌ | 重试间隔时间（秒） | 10 |
1. **错误自动切换**: 当某个key失败时自动切换 ### 2.3 支持的服务商示例
2. **负载均衡**: 在多个key之间循环使用
3. **提高可用性**: 避免单点故障
#### 错误处理机制
- **401/403认证错误**: 立即切换到下一个API Key
- **429频率限制**: 等待后重试，持续失败则切换Key
- **网络错误**: 短暂等待后重试，失败则切换Key
- **其他错误**: 按照正常重试机制处理
### 3. 模型配置 [[models]]
定义可用的模型及其属性：
#### DeepSeek
```toml ```toml
[[models]]
model_identifier = "deepseek-chat" # API服务商的模型标识符
name = "deepseek-v3" # 自定义模型名称（可选）
api_provider = "DeepSeek" # 对应的API提供商名称
task_type = "llm_normal" # 任务类型（推荐配置）
capabilities = ["text", "tool_calling"] # 模型能力列表（推荐配置）
price_in = 2.0 # 输入价格（元/兆token）
price_out = 8.0 # 输出价格（元/兆token）
force_stream_mode = false # 是否强制流式输出
```
**必填参数：**
- `model_identifier`: API服务商提供的模型标识符
- `api_provider`: 对应在api_providers中配置的服务商名称
**可选参数：**
- `name`: 自定义模型名称，如果不指定则使用model_identifier
- `task_type`: 模型主要任务类型（详见任务类型说明）
- `capabilities`: 模型支持的能力列表（详见能力说明）
- `price_in/price_out`: 用于统计API调用成本
- `force_stream_mode`: 当模型不支持非流式输出时启用
### 4. 任务模型使用配置 [task_model_usage]
定义系统任务使用的默认模型：
```toml
[task_model_usage]
llm_reasoning = {model="deepseek-r1", temperature=0.8, max_tokens=1024, max_retry=0}
llm_normal = {model="deepseek-v3", max_tokens=1024, max_retry=0}
embedding = "bge-m3"
# 可选：模型调度列表
# schedule = ["deepseek-v3", "deepseek-r1"]
```
## bot_config.toml 模型任务配置
### 模型任务分类
MaiBot 将不同功能分配给不同的模型以优化性能：
#### 核心对话模型
```toml
[model.replyer_1] # 首要回复模型
model_name = "siliconflow-deepseek-v3" # 对应model_config.toml中的模型名称
temperature = 0.2 # 模型温度（0.0-2.0）
max_tokens = 800 # 最大输出token数
[model.replyer_2] # 次要回复模型
model_name = "siliconflow-deepseek-r1"
temperature = 0.7
max_tokens = 800
```
#### 功能性模型
```toml
[model.utils] # 通用工具模型
model_name = "siliconflow-deepseek-v3" # 用于表情包、取名、关系等模块
temperature = 0.2
max_tokens = 800
[model.utils_small] # 小型工具模型
model_name = "qwen3-8b" # 用于高频率调用的场景
temperature = 0.7
max_tokens = 800
enable_thinking = false # 是否启用思考模式
[model.planner] # 决策模型
model_name = "siliconflow-deepseek-v3" # 负责决定麦麦该做什么
temperature = 0.3
max_tokens = 800
[model.emotion] # 情绪模型
model_name = "siliconflow-deepseek-v3" # 负责情绪变化
temperature = 0.3
max_tokens = 800
[model.memory] # 记忆模型
model_name = "qwen3-30b" # 用于记忆构建和管理
temperature = 0.7
max_tokens = 800
enable_thinking = false
```
#### 专用模型
```toml
[model.vlm] # 视觉理解模型
model_name = "qwen2.5-vl-72b" # 图像识别和理解
max_tokens = 800
[model.voice] # 语音识别模型
model_name = "sensevoice-small" # 语音转文字
[model.tool_use] # 工具调用模型
model_name = "qwen3-14b" # 需要支持工具调用的模型
temperature = 0.7
max_tokens = 800
enable_thinking = false
[model.embedding] # 嵌入模型
model_name = "bge-m3" # 用于文本向量化
```
#### LPMM知识库模型
```toml
[model.lpmm_entity_extract] # 实体提取模型
model_name = "siliconflow-deepseek-v3"
temperature = 0.2
max_tokens = 800
[model.lpmm_rdf_build] # RDF构建模型
model_name = "siliconflow-deepseek-v3"
temperature = 0.2
max_tokens = 800
[model.lpmm_qa] # 问答模型
model_name = "deepseek-r1-distill-qwen-32b"
temperature = 0.7
max_tokens = 800
enable_thinking = false
```
### 模型参数说明
- **`model_name`**: 必填，对应model_config.toml中配置的模型名称
- **`temperature`**: 模型温度，控制回答的随机性（0.0-2.0）
- 0.0-0.3: 确定性强，适合事实性任务
- 0.4-0.7: 平衡创造性和准确性
- 0.8-2.0: 创造性强，适合创意任务
- **`max_tokens`**: 单次回复的最大token数
- **`enable_thinking`**: 是否启用思考模式（仅支持特定模型）
- **`thinking_budget`**: 思考模式的最大token数
## 任务类型和能力系统
### 任务类型 (task_type)
明确指定模型的主要用途：
- **`llm_normal`**: 普通语言模型，用于一般对话
- **`llm_reasoning`**: 推理语言模型，用于复杂思考
- **`vision`**: 视觉模型，用于图像理解
- **`embedding`**: 嵌入模型，用于文本向量化
- **`speech`**: 语音模型，用于语音识别
### 能力列表 (capabilities)
描述模型支持的具体能力：
- **`text`**: 文本理解和生成
- **`vision`**: 图像理解
- **`embedding`**: 文本向量化
- **`speech`**: 语音处理
- **`tool_calling`**: 工具调用
- **`reasoning`**: 推理思考
### 配置优先级
系统按以下优先级确定模型任务类型：
1. **`task_type`** (最高优先级) - 直接指定任务类型
2. **`capabilities`** (中等优先级) - 根据能力推断任务类型
3. **模型名称关键字** (最低优先级) - 基于模型名称的关键字匹配
### 示例配置
```toml
# 推荐配置方式 - 明确指定任务类型和能力
[[models]]
model_identifier = "deepseek-chat"
name = "deepseek-v3"
api_provider = "DeepSeek"
task_type = "llm_normal" # 明确指定为普通语言模型
capabilities = ["text", "tool_calling"] # 支持文本和工具调用
# 视觉模型示例
[[models]]
model_identifier = "Qwen/Qwen2.5-VL-72B-Instruct"
name = "qwen2.5-vl-72b"
api_provider = "SiliconFlow"
task_type = "vision" # 视觉任务
capabilities = ["vision", "text"] # 支持视觉和文本
# 嵌入模型示例
[[models]]
model_identifier = "BAAI/bge-m3"
name = "bge-m3"
api_provider = "SiliconFlow"
task_type = "embedding" # 嵌入任务
capabilities = ["text", "embedding"] # 支持文本和向量化
```
## 配置示例
### 完整的多提供商配置
```toml
# API提供商配置
[[api_providers]] [[api_providers]]
name = "DeepSeek" name = "DeepSeek"
base_url = "https://api.deepseek.cn/v1" base_url = "https://api.deepseek.cn/v1"
api_keys = [ api_key = "your-deepseek-api-key"
"sk-deepseek-key-1",
"sk-deepseek-key-2"
]
client_type = "openai" client_type = "openai"
```
#### SiliconFlow
```toml
[[api_providers]] [[api_providers]]
name = "SiliconFlow" name = "SiliconFlow"
base_url = "https://api.siliconflow.cn/v1" base_url = "https://api.siliconflow.cn/v1"
key = "sk-siliconflow-key" api_key = "your-siliconflow-api-key"
client_type = "openai" client_type = "openai"
```
#### Google Gemini
```toml
[[api_providers]] [[api_providers]]
name = "Google" name = "Google"
base_url = "https://api.google.com/v1" base_url = "https://api.google.com/v1"
api_keys = ["google-api-key-1", "google-api-key-2"] api_key = "your-google-api-key"
client_type = "gemini" client_type = "gemini" # 注意：Gemini需要使用特殊客户端
# 模型配置示例
[[models]]
model_identifier = "deepseek-chat"
name = "deepseek-v3"
api_provider = "DeepSeek"
task_type = "llm_normal"
capabilities = ["text", "tool_calling"]
price_in = 2.0
price_out = 8.0
[[models]]
model_identifier = "deepseek-reasoner"
name = "deepseek-r1"
api_provider = "DeepSeek"
task_type = "llm_reasoning"
capabilities = ["text", "tool_calling", "reasoning"]
price_in = 4.0
price_out = 16.0
[[models]]
model_identifier = "Pro/deepseek-ai/DeepSeek-V3"
name = "siliconflow-deepseek-v3"
api_provider = "SiliconFlow"
task_type = "llm_normal"
capabilities = ["text", "tool_calling"]
price_in = 2.0
price_out = 8.0
``` ```
### bot_config.toml 任务配置示例 ## 3. 模型配置
### 3.1 基本模型配置
使用 `[[models]]` 数组配置多个模型：
```toml ```toml
# 核心对话模型 [[models]]
[model.replyer_1] model_identifier = "deepseek-chat" # 模型在API服务商中的标识符
model_name = "deepseek-v3" name = "deepseek-v3" # 自定义模型名称
temperature = 0.2 api_provider = "DeepSeek" # 引用的API服务商名称
max_tokens = 800 price_in = 2.0 # 输入价格（元/M token）
price_out = 8.0 # 输出价格（元/M token）
[model.replyer_2]
model_name = "deepseek-r1"
temperature = 0.7
max_tokens = 800
# 工具模型
[model.utils]
model_name = "siliconflow-deepseek-v3"
temperature = 0.2
max_tokens = 800
[model.utils_small]
model_name = "qwen3-8b"
temperature = 0.7
max_tokens = 800
enable_thinking = false
# 专用模型
[model.vlm]
model_name = "qwen2.5-vl-72b"
max_tokens = 800
[model.embedding]
model_name = "bge-m3"
``` ```
### 3.2 高级模型配置
#### 强制流式输出
对于不支持非流式输出的模型：
```toml
[[models]]
model_identifier = "some-model"
name = "custom-name"
api_provider = "Provider"
force_stream_mode = true # 启用强制流式输出
```
#### 额外参数配置
```toml
[[models]]
model_identifier = "Qwen/Qwen3-8B"
name = "qwen3-8b"
api_provider = "SiliconFlow"
[models.extra_params]
enable_thinking = false # 禁用思考模式
```
如果想要添加其他额外参数，可以在 `extra_params` 中添加更多配置项。
### 3.3 配置参数说明
| 参数 | 必填 | 说明 |
|------|------|------|
| `model_identifier` | ✅ | API服务商提供的模型标识符 |
| `name` | ✅ | 自定义模型名称，用于在任务配置中引用 |
| `api_provider` | ✅ | 对应的API服务商名称 |
| `price_in` | ❌ | 输入价格（元/M token），用于成本统计 |
| `price_out` | ❌ | 输出价格（元/M token），用于成本统计 |
| `force_stream_mode` | ❌ | 是否强制使用流式输出 |
| `extra_params` | ❌ | 额外的模型参数配置 |
## 4. 模型任务配置
### 4.1 核心任务模型
#### utils - 工具模型
用于表情包模块、取名模块、关系模块等核心功能：
```toml
[model_task_config.utils]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.2
max_tokens = 800
```
#### utils_small - 小型工具模型
用于高频率调用的场景，建议使用速度快的小模型：
```toml
[model_task_config.utils_small]
model_list = ["qwen3-8b"]
temperature = 0.7
max_tokens = 800
```
#### replyer_1 - 主要回复模型
首要回复模型，也用于表达器和表达方式学习：
```toml
[model_task_config.replyer_1]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.2
max_tokens = 800
```
#### replyer_2 - 次要回复模型
```toml
[model_task_config.replyer_2]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.7
max_tokens = 800
```
### 4.2 智能决策模型
#### planner - 决策模型
负责决定MaiBot该做什么：
```toml
[model_task_config.planner]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.3
max_tokens = 800
```
#### emotion - 情绪模型
负责MaiBot的情绪变化：
```toml
[model_task_config.emotion]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.3
max_tokens = 800
```
#### memory - 记忆模型
```toml
[model_task_config.memory]
model_list = ["qwen3-30b"]
temperature = 0.7
max_tokens = 800
```
### 4.3 多模态模型
#### vlm - 视觉语言模型
用于图像识别：
```toml
[model_task_config.vlm]
model_list = ["qwen2.5-vl-72b"]
max_tokens = 800
```
#### voice - 语音识别模型
```toml
[model_task_config.voice]
model_list = ["sensevoice-small"]
```
#### embedding - 嵌入模型
```toml
[model_task_config.embedding]
model_list = ["bge-m3"]
```
### 4.4 功能增强模型
#### tool_use - 工具调用模型
需要使用支持工具调用的模型：
```toml
[model_task_config.tool_use]
model_list = ["qwen3-14b"]
temperature = 0.7
max_tokens = 800
```
### 4.5 LPMM知识库模型
#### lpmm_entity_extract - 实体提取模型
```toml
[model_task_config.lpmm_entity_extract]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.2
max_tokens = 800
```
#### lpmm_rdf_build - RDF构建模型
```toml
[model_task_config.lpmm_rdf_build]
model_list = ["siliconflow-deepseek-v3"]
temperature = 0.2
max_tokens = 800
```
#### lpmm_qa - 问答模型
```toml
[model_task_config.lpmm_qa]
model_list = ["deepseek-r1-distill-qwen-32b"]
temperature = 0.7
max_tokens = 800
```
## 5. 配置建议
### 5.1 Temperature 参数选择
| 任务类型 | 推荐温度 | 说明 |
|----------|----------|------|
| 精确任务（工具调用、实体提取） | 0.1-0.3 | 需要准确性和一致性 |
| 创意任务（对话、记忆） | 0.5-0.8 | 需要多样性和创造性 |
| 平衡任务（决策、情绪） | 0.3-0.5 | 平衡准确性和灵活性 |
### 5.2 模型选择建议
| 任务类型 | 推荐模型类型 | 示例 |
|----------|--------------|------|
| 高精度任务 | 大模型 | DeepSeek-V3, GPT-4 |
| 高频率任务 | 小模型 | Qwen3-8B |
| 多模态任务 | 专用模型 | Qwen2.5-VL, SenseVoice |
| 工具调用 | 支持Function Call的模型 | Qwen3-14B |
### 5.3 成本优化
1. **分层使用**：核心功能使用高质量模型，辅助功能使用经济模型
2. **合理配置max_tokens**：根据实际需求设置，避免浪费
3. **选择免费模型**：对于测试环境，优先使用price为0的模型
## 6. 配置验证
### 6.1 必要检查项
1. ✅ API密钥是否正确配置
2. ✅ 模型标识符是否与API服务商提供的一致
3. ✅ 任务配置中引用的模型名称是否在models中定义
4. ✅ 多模态任务是否配置了对应的专用模型
### 6.2 测试配置
建议在正式使用前：
1. 使用少量测试数据验证配置
2. 检查API调用是否正常
3. 确认成本统计功能正常工作
## 7. 故障排除
### 7.1 常见问题
**问题1**: API调用失败
- 检查API密钥是否正确
- 确认base_url是否可访问
- 检查模型标识符是否正确
**问题2**: 模型未找到
- 确认模型名称在任务配置和模型定义中一致
- 检查api_provider名称是否匹配
**问题3**: 响应异常
- 检查温度参数是否合理（0-1之间）
- 确认max_tokens设置是否合适
- 验证模型是否支持所需功能
### 7.2 日志查看
查看 `logs/` 目录下的日志文件，寻找相关错误信息。
## 8. 更新和维护
1. **定期更新**: 关注API服务商的模型更新，及时调整配置
2. **性能监控**: 监控模型调用的成本和性能
3. **备份配置**: 在修改前备份当前配置文件