229 lines
6.6 KiB
Markdown
229 lines
6.6 KiB
Markdown
# 变更日志：增加国内大模型厂商接入
|
||
|
||
## 版本信息
|
||
- **版本**：v1.1.0（计划）
|
||
- **日期**：2026-03-31
|
||
- **状态**：计划中
|
||
|
||
## 功能概述
|
||
为 MimiClaw 项目增加国内大模型厂商的接入支持，包括：
|
||
1. **硅基流动** (SiliconFlow) - 提供免费模型和多种高性能大模型
|
||
2. **火山方舟** (Volcengine Ark) - 字节跳动豆包模型系列
|
||
|
||
## 实施计划
|
||
|
||
### 阶段一：准备与设计（1-2天）
|
||
|
||
#### 1.1 详细API调研
|
||
- [ ] 研究硅基流动API文档，确认：
|
||
- 具体的Base URL和端点
|
||
- 认证方式（API Key格式）
|
||
- 支持的模型列表和ID格式
|
||
- 工具调用兼容性
|
||
- 速率限制和配额
|
||
|
||
- [ ] 研究火山方舟API文档，确认：
|
||
- 具体的Base URL和端点
|
||
- 认证方式（API Key格式）
|
||
- 支持的模型列表和ID格式
|
||
- 工具调用兼容性
|
||
- 速率限制和配额
|
||
|
||
#### 1.2 架构设计
|
||
- [ ] 设计提供商扩展机制
|
||
- [ ] 确定配置管理方案
|
||
- [ ] 设计命令行接口扩展
|
||
- [ ] 评估内存影响
|
||
|
||
### 阶段二：核心实现（3-5天）
|
||
|
||
#### 2.1 配置系统扩展
|
||
- [ ] 修改 `mimi_secrets.h.example` 添加新配置项：
|
||
```c
|
||
/* 国内大模型厂商配置 */
|
||
#define MIMI_SECRET_SILICONFLOW_API_KEY ""
|
||
#define MIMI_SECRET_SILICONFLOW_BASE_URL "https://api.siliconflow.cn/v1"
|
||
#define MIMI_SECRET_VOLCENGINE_API_KEY ""
|
||
#define MIMI_SECRET_VOLCENGINE_BASE_URL "https://ark.cn-beijing.volces.com/api/v3"
|
||
```
|
||
|
||
- [ ] 更新 `mimi_config.h` 添加相关默认值
|
||
|
||
#### 2.2 LLM代理扩展
|
||
- [ ] 修改 `llm_proxy.c` 支持新的提供商：
|
||
- 添加 `provider_is_siliconflow()` 函数
|
||
- 添加 `provider_is_volcengine()` 函数
|
||
- 扩展 `llm_api_url()` 函数支持新提供商
|
||
- 扩展 `llm_api_host()` 函数支持新提供商
|
||
- 扩展 `llm_api_path()` 函数支持新提供商
|
||
|
||
- [ ] 添加Base URL配置支持：
|
||
```c
|
||
static char s_siliconflow_base_url[256] = "https://api.siliconflow.cn/v1";
|
||
static char s_volcengine_base_url[256] = "https://ark.cn-beijing.volces.com/api/v3";
|
||
```
|
||
|
||
- [ ] 修改HTTP请求头设置逻辑：
|
||
- 硅基流动：使用Bearer Token认证
|
||
- 火山方舟：使用Bearer Token认证（假设与OpenAI兼容）
|
||
|
||
- [ ] 添加模型名称转换逻辑（如果需要）
|
||
|
||
#### 2.3 命令行界面扩展
|
||
- [ ] 在 `serial_cli.c` 添加新命令：
|
||
- `set_siliconflow_key <key>`：设置硅基流动API密钥
|
||
- `set_siliconflow_url <url>`：设置硅基流动Base URL
|
||
- `set_volcengine_key <key>`：设置火山方舟API密钥
|
||
- `set_volcengine_url <url>`：设置火山方舟Base URL
|
||
|
||
- [ ] 更新现有命令的帮助信息
|
||
- [ ] 更新 `config_show` 命令显示新配置
|
||
|
||
#### 2.4 提供商切换机制
|
||
- [ ] 修改 `set_model_provider` 命令支持新提供商：
|
||
- 支持值：`anthropic`, `openai`, `siliconflow`, `volcengine`
|
||
|
||
- [ ] 更新NVS存储键名：
|
||
- 可能需要扩展 `MIMI_NVS_KEY_PROVIDER` 支持更多值
|
||
|
||
### 阶段三：测试与优化（2-3天）
|
||
|
||
#### 3.1 功能测试
|
||
- [ ] 单元测试：
|
||
- 提供商检测函数测试
|
||
- API URL生成测试
|
||
- 请求头设置测试
|
||
|
||
- [ ] 集成测试：
|
||
- 硅基流动API连接测试
|
||
- 火山方舟API连接测试
|
||
- 工具调用功能测试
|
||
- 提供商切换测试
|
||
|
||
#### 3.2 性能优化
|
||
- [ ] 内存使用优化：
|
||
- 评估新增变量对内存的影响
|
||
- 优化字符串存储大小
|
||
|
||
- [ ] 网络性能：
|
||
- 测试国内网络环境下的连接稳定性
|
||
- 优化超时设置
|
||
|
||
#### 3.3 错误处理
|
||
- [ ] 添加详细的错误日志
|
||
- [ ] 处理API特定的错误响应
|
||
- [ ] 添加重试机制（如果需要）
|
||
|
||
### 阶段四：文档与发布（1天）
|
||
|
||
#### 4.1 文档更新
|
||
- [ ] 更新 `README.md` 添加新功能说明
|
||
- [ ] 更新 `mimi_secrets.h.example` 添加配置示例
|
||
- [ ] 创建国内大模型厂商配置指南
|
||
- [ ] 更新串口CLI命令文档
|
||
|
||
#### 4.2 发布准备
|
||
- [ ] 代码审查
|
||
- [ ] 最终测试
|
||
- [ ] 创建发布标签
|
||
|
||
## 技术细节
|
||
|
||
### 提供商检测逻辑
|
||
```c
|
||
// 在 llm_proxy.c 中添加
|
||
static bool provider_is_siliconflow(void) {
|
||
return strcmp(s_provider, "siliconflow") == 0;
|
||
}
|
||
|
||
static bool provider_is_volcengine(void) {
|
||
return strcmp(s_provider, "volcengine") == 0;
|
||
}
|
||
```
|
||
|
||
### API URL 配置
|
||
```c
|
||
// 扩展 llm_api_url 函数
|
||
static const char *llm_api_url(void) {
|
||
if (provider_is_openai()) {
|
||
return MIMI_OPENAI_API_URL;
|
||
} else if (provider_is_siliconflow()) {
|
||
return s_siliconflow_base_url;
|
||
} else if (provider_is_volcengine()) {
|
||
return s_volcengine_base_url;
|
||
} else {
|
||
return MIMI_LLM_API_URL; // Anthropic
|
||
}
|
||
}
|
||
```
|
||
|
||
### 请求头设置
|
||
```c
|
||
// 扩展 HTTP 请求头设置
|
||
if (provider_is_openai() || provider_is_siliconflow() || provider_is_volcengine()) {
|
||
// OpenAI兼容的Bearer Token认证
|
||
if (s_api_key[0]) {
|
||
char auth[LLM_API_KEY_MAX_LEN + 16];
|
||
snprintf(auth, sizeof(auth), "Bearer %s", s_api_key);
|
||
esp_http_client_set_header(client, "Authorization", auth);
|
||
}
|
||
} else {
|
||
// Anthropic的x-api-key认证
|
||
esp_http_client_set_header(client, "x-api-key", s_api_key);
|
||
esp_http_client_set_header(client, "anthropic-version", MIMI_LLM_API_VERSION);
|
||
}
|
||
```
|
||
|
||
## 风险评估与缓解
|
||
|
||
### 风险1：API兼容性问题
|
||
- **风险**：国内厂商的API可能与OpenAI有细微差异
|
||
- **缓解**：详细测试，添加兼容性处理代码
|
||
|
||
### 风险2：内存限制
|
||
- **风险**：新增配置可能超出ESP32-S3内存限制
|
||
- **缓解**：优化字符串存储，使用固定大小数组
|
||
|
||
### 风险3：网络连接问题
|
||
- **风险**：国内网络环境可能影响API调用
|
||
- **缓解**：添加重试机制，优化超时设置
|
||
|
||
### 风险4：认证安全
|
||
- **风险**：API密钥存储和传输安全
|
||
- **缓解**：使用现有的NVS加密存储，确保安全传输
|
||
|
||
## 预期成果
|
||
|
||
1. **功能完成**：支持硅基流动和火山方舟两个国内大模型厂商
|
||
2. **配置灵活**：用户可以通过命令行或配置文件灵活配置
|
||
3. **向后兼容**：不影响现有的Anthropic和OpenAI功能
|
||
4. **文档完整**：提供完整的配置和使用文档
|
||
|
||
## 时间估算
|
||
|
||
- **总时间**：7-11个工作日
|
||
- **阶段一**：1-2天
|
||
- **阶段二**：3-5天
|
||
- **阶段三**：2-3天
|
||
- **阶段四**：1天
|
||
|
||
## 依赖项
|
||
|
||
1. **外部依赖**：
|
||
- 硅基流动API访问权限
|
||
- 火山方舟API访问权限
|
||
- 稳定的网络连接
|
||
|
||
2. **内部依赖**：
|
||
- 现有的LLM代理架构
|
||
- 配置管理系统
|
||
- 命令行界面系统
|
||
|
||
## 成功标准
|
||
|
||
1. 可以成功连接硅基流动API并获取响应
|
||
2. 可以成功连接火山方舟API并获取响应
|
||
3. 工具调用功能在两个新提供商上正常工作
|
||
4. 提供商切换功能正常
|
||
5. 内存使用在可接受范围内
|
||
6. 所有现有功能保持正常 |