feat: 添加完整的模型配置指南文档，涵盖配置项和示例
This commit is contained in:
墨梓柒
395
docs/model_configuration_guide.md
Normal file
395
docs/model_configuration_guide.md
Normal file
@@ -0,0 +1,395 @@
|
|||||||
|
# MaiBot 模型配置指南
|
||||||
|
|
||||||
|
本文档详细说明 MaiBot 的模型配置系统，包括 `model_config.toml` 和 `bot_config.toml` 中模型相关的配置项。
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. [配置文件概述](#配置文件概述)
|
||||||
|
2. [model_config.toml 详细配置](#model_configtoml-详细配置)
|
||||||
|
3. [bot_config.toml 模型任务配置](#bot_configtoml-模型任务配置)
|
||||||
|
4. [任务类型和能力系统](#任务类型和能力系统)
|
||||||
|
5. [多API Key支持](#多api-key支持)
|
||||||
|
6. [配置示例](#配置示例)
|
||||||
|
7. [最佳实践](#最佳实践)
|
||||||
|
8. [故障排除](#故障排除)
|
||||||
|
|
||||||
|
## 配置文件概述
|
||||||
|
|
||||||
|
MaiBot 的模型配置分为两个文件：
|
||||||
|
|
||||||
|
- **`model_config.toml`**: 定义可用的模型、API提供商和基础配置
|
||||||
|
- **`bot_config.toml`**: 定义具体任务使用哪些模型以及模型参数
|
||||||
|
|
||||||
|
### 配置关系
|
||||||
|
|
||||||
|
```
|
||||||
|
model_config.toml → 定义模型池
|
||||||
|
↓
|
||||||
|
bot_config.toml → 从模型池中选择模型用于具体任务
|
||||||
|
```
|
||||||
|
|
||||||
|
## model_config.toml 详细配置
|
||||||
|
|
||||||
|
### 基础结构
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[inner]
|
||||||
|
version = "0.2.1" # 配置文件版本
|
||||||
|
|
||||||
|
[request_conf] # 全局请求配置
|
||||||
|
[[api_providers]] # API服务提供商配置（可配置多个）
|
||||||
|
[[models]] # 模型配置（可配置多个）
|
||||||
|
[task_model_usage] # 任务模型使用配置
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1. 请求配置 [request_conf]
|
||||||
|
|
||||||
|
全局的API请求配置，影响所有模型调用：
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[request_conf]
|
||||||
|
max_retry = 2 # 最大重试次数
|
||||||
|
timeout = 10 # API调用超时时长（秒）
|
||||||
|
retry_interval = 10 # 重试间隔（秒）
|
||||||
|
default_temperature = 0.7 # 默认温度值
|
||||||
|
default_max_tokens = 1024 # 默认最大输出token数
|
||||||
|
```
|
||||||
|
|
||||||
|
**参数说明：**
|
||||||
|
- `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
|
||||||
|
[[api_providers]]
|
||||||
|
name = "DeepSeek" # 提供商名称（自定义）
|
||||||
|
base_url = "https://api.deepseek.cn/v1" # API基础URL
|
||||||
|
api_keys = [ # 多个API Key（推荐）
|
||||||
|
"sk-your-first-key-here",
|
||||||
|
"sk-your-second-key-here",
|
||||||
|
"sk-your-third-key-here"
|
||||||
|
]
|
||||||
|
# 或者使用单个key（向后兼容）
|
||||||
|
# key = "sk-your-single-key-here"
|
||||||
|
client_type = "openai" # 客户端类型
|
||||||
|
```
|
||||||
|
|
||||||
|
**参数说明：**
|
||||||
|
- `name`: 提供商的自定义名称，在models配置中引用
|
||||||
|
- `base_url`: API服务的基础URL
|
||||||
|
- `api_keys`: API密钥数组，支持多个key实现负载均衡和错误切换
|
||||||
|
- `key`: 单个API密钥（向后兼容，建议使用api_keys）
|
||||||
|
- `client_type`: 客户端类型，可选值：
|
||||||
|
- `"openai"`: OpenAI兼容格式（默认）
|
||||||
|
- `"gemini"`: Google Gemini专用格式
|
||||||
|
|
||||||
|
#### 多API Key优势
|
||||||
|
|
||||||
|
1. **错误自动切换**: 当某个key失败时自动切换
|
||||||
|
2. **负载均衡**: 在多个key之间循环使用
|
||||||
|
3. **提高可用性**: 避免单点故障
|
||||||
|
|
||||||
|
#### 错误处理机制
|
||||||
|
|
||||||
|
- **401/403认证错误**: 立即切换到下一个API Key
|
||||||
|
- **429频率限制**: 等待后重试，持续失败则切换Key
|
||||||
|
- **网络错误**: 短暂等待后重试，失败则切换Key
|
||||||
|
- **其他错误**: 按照正常重试机制处理
|
||||||
|
|
||||||
|
### 3. 模型配置 [[models]]
|
||||||
|
|
||||||
|
定义可用的模型及其属性：
|
||||||
|
|
||||||
|
```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]]
|
||||||
|
name = "DeepSeek"
|
||||||
|
base_url = "https://api.deepseek.cn/v1"
|
||||||
|
api_keys = [
|
||||||
|
"sk-deepseek-key-1",
|
||||||
|
"sk-deepseek-key-2"
|
||||||
|
]
|
||||||
|
client_type = "openai"
|
||||||
|
|
||||||
|
[[api_providers]]
|
||||||
|
name = "SiliconFlow"
|
||||||
|
base_url = "https://api.siliconflow.cn/v1"
|
||||||
|
key = "sk-siliconflow-key"
|
||||||
|
client_type = "openai"
|
||||||
|
|
||||||
|
[[api_providers]]
|
||||||
|
name = "Google"
|
||||||
|
base_url = "https://api.google.com/v1"
|
||||||
|
api_keys = ["google-api-key-1", "google-api-key-2"]
|
||||||
|
client_type = "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 任务配置示例
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# 核心对话模型
|
||||||
|
[model.replyer_1]
|
||||||
|
model_name = "deepseek-v3"
|
||||||
|
temperature = 0.2
|
||||||
|
max_tokens = 800
|
||||||
|
|
||||||
|
[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"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user