LLM API Gateway：使用Comate Spec Mode创建大模型调用中转服务器
LLM API Gateway 需求文档
需求场景
用户需要建立一个本地大模型API中转服务器，用于统一管理多个大模型供应商的API密钥和调用地址，对外提供统一的访问入口，简化客户端调用流程。
架构技术方案
采用Node.js + Express框架实现轻量级API网关，使用配置文件管理多个后端模型服务，实现请求转发和响应处理。
核心组件
- HTTP服务器：基于Express框架，监听本地端口（如1337）
- 配置管理：JSON配置文件存储多个模型供应商信息
- 路由转发：将收到的API请求转发到目标模型服务
- 响应处理：统一处理和返回模型响应
- 健康检查：监控后端服务可用性
需求处理逻辑
1. 配置管理
- 支持配置多个模型供应商（OpenAI、Claude、通义千问等）
- 每个供应商包含：name、apiKey、baseUrl、model映射
- 支持动态加载和热更新配置
2. 请求转发
- 接收标准OpenAI格式的API请求
- 根据请求中的model参数确定目标供应商
- 自动添加对应的API密钥
- 转发请求到目标供应商的API端点
3. 响应处理
- 直接透传供应商响应
- 统一错误处理和日志记录
- 支持流式响应和非流式响应
4. 兼容性
- 兼容OpenAI API格式
- 支持chat/completions、embeddings等常见端点
- 保留原始请求的所有参数和头信息
# LLM API Gateway 任务计划
- [ ] 任务1：项目初始化和基础配置
- 1.1: 创建package.json文件，配置项目依赖（express、axios、dotenv等）
- 1.2: 创建基础目录结构（config、utils、routes等）
- 1.3: 创建环境变量配置文件(.env.example和.gitignore)
- 1.4: 创建基础README.md文档
- [ ] 任务2：配置管理系统实现
- 2.1: 创建配置加载工具utils/config.js，实现配置文件读取和验证
- 2.2: 创建模型配置文件config/models.json，定义供应商配置结构
- 2.3: 创建默认配置文件config/default.json，设置服务器默认参数
- 2.4: 实现配置热更新功能，支持运行时重新加载配置
- [ ] 任务3：核心服务器框架搭建
- 3.1: 创建主服务器文件server.js，设置Express应用基础结构
- 3.2: 配置中间件（JSON解析、CORS、日志记录等）
- 3.3: 实现健康检查端点/health，返回服务器和供应商状态
- 3.4: 配置错误处理中间件，统一处理异常响应
- 3.5: 单元测试
- [ ] 任务4：API路由转发核心功能
- 4.1: 创建路由工具utils/router.js，实现请求转发逻辑
- 4.2: 实现POST /v1/chat/completions端点，支持流式和非流式响应
- 4.3: 实现模型参数解析和供应商配置匹配逻辑
- 4.4: 处理API密钥注入和请求头转发
- 4.5: 单元测试
- [ ] 任务5：扩展API端点支持
- 5.1: 实现POST /v1/embeddings端点，支持向量嵌入调用
- 5.2: 实现GET /v1/models端点，返回可用模型列表
- 5.3: 支持其他常见OpenAI兼容端点（如completions、moderations等）
- 5.4: 实现请求参数验证和错误响应
- 5.5: 单元测试
- [ ] 任务6：日志记录和监控系统
- 6.1: 创建日志工具utils/logger.js，实现结构化日志记录
- 6.2: 记录请求转发详情（模型、供应商、响应时间等）
- 6.3: 实现错误日志分级记录和告警机制
- 6.4: 添加请求统计和性能监控功能
- 6.5: 单元测试
- [ ] 任务7：容错和优化机制
- 7.1: 实现供应商API失败重试机制
- 7.2: 添加请求限流和并发控制
- 7.3: 实现供应商健康检查和故障转移
- 7.4: 优化内存使用和请求处理性能
- 7.5: 单元测试
- [ ] 任务8：文档完善和测试验证
- 8.1: 完善README.md，包含安装、配置、使用说明
- 8.2: 创建API使用示例和测试脚本
- 8.3: 验证多个供应商配置和调用功能
- 8.4: 进行集成测试和边界条件验证
LLM API Gateway 任务计划
- 任务1：项目初始化和基础配置
- 1.1: 创建package.json文件，配置项目依赖（express、axios、dotenv等）
- 1.2: 创建基础目录结构（config、utils、routes等）
- 1.3: 创建环境变量配置文件(.env.example和.gitignore)
- 1.4: 创建基础README.md文档
- 任务2：配置管理系统实现
- 2.1: 创建配置加载工具utils/config.js，实现配置文件读取和验证
- 2.2: 创建模型配置文件config/models.json，定义供应商配置结构
- 2.3: 创建默认配置文件config/default.json，设置服务器默认参数
- 2.4: 实现配置热更新功能，支持运行时重新加载配置
- 任务3：核心服务器框架搭建
- 3.1: 创建主服务器文件server.js，设置Express应用基础结构
- 3.2: 配置中间件（JSON解析、CORS、日志记录等）
- 3.3: 实现健康检查端点/health，返回服务器和供应商状态
- 3.4: 配置错误处理中间件，统一处理异常响应
- 3.5: 单元测试
- 任务4：API路由转发核心功能
- 4.1: 创建路由工具utils/router.js，实现请求转发逻辑
- 4.2: 实现POST /v1/chat/completions端点，支持流式和非流式响应
- 4.3: 实现模型参数解析和供应商配置匹配逻辑
- 4.4: 处理API密钥注入和请求头转发
- 4.5: 单元测试
- 任务5：扩展API端点支持
- 5.1: 实现POST /v1/embeddings端点，支持向量嵌入调用
- 5.2: 实现GET /v1/models端点，返回可用模型列表
- 5.3: 支持其他常见OpenAI兼容端点（如completions、moderations等）
- 5.4: 实现请求参数验证和错误响应
- 5.5: 单元测试
- 任务6：日志记录和监控系统
- 6.1: 创建日志工具utils/logger.js，实现结构化日志记录
- 6.2: 记录请求转发详情（模型、供应商、响应时间等）
- 6.3: 实现错误日志分级记录和告警机制
- 6.4: 添加请求统计和性能监控功能
- 6.5: 单元测试
- 任务7：容错和优化机制
- 7.1: 实现供应商API失败重试机制
- 7.2: 添加请求限流和并发控制
- 7.3: 实现供应商健康检查和故障转移
- 7.4: 优化内存使用和请求处理性能
- 7.5: 单元测试
- 任务8：文档完善和测试验证
- 8.1: 完善README.md，包含安装、配置、使用说明
- 8.2: 创建API使用示例和测试脚本
- 8.3: 验证多个供应商配置和调用功能
- 8.4: 进行集成测试和边界条件验证
安装
# 克隆项目
git clone
cd aiagent
# 安装依赖
npm install
# 复制环境变量模板
cp .env.example .env
测试，发现api key那块有些问题，颇废了一些力气，目前还没有完全解决。
调试
key的问题
添加新模型那里，默认就调用对应供应商的api。可以给一个勾选框，勾选后，可以选择手动填apikey，这样就不会因为浏览器自动填内容，而导致自动填入错误的key。
尝试让它帮我做功能测试
你能帮我做如下的功能测试吗？
-
刷新浏览器页面（加载最新 HTML/JS）。
-
打开「添加模型」弹窗，确认：
- 默认「手动填写 API Key」未勾选，API Key 输入框禁用且空白。
-
勾选后输入框变为可写；取消勾选再次禁用并清空。
-
分别测试：
- 不勾选、留空 → 提交后查看
config/models.json，应写入${XXX}环境变量； - 勾选并填写自定义 key → 提交后应写入你填的 key。
- 不勾选、留空 → 提交后查看
验证通过即完成。
Comate说：我派子 agent 完成整套功能测试，过程你无需操作，只看结论即可。
它会派agent完成整套功能测试，但是我没说，它就没干，真是一戳一蹦跶，不戳不蹦跶！
添加新模型那里，默认就调用对应供应商的api。可以给一个勾选框，勾选后，可以选择手动填apikey，这样就不会因为浏览器自动填内容，而导致自动填入错误的key。
你已经改了models.json里面的信息。现在的问题是，如果我手工添加模型供应商，添加的新供应商它的Headers 配置还是错的，要从源头解决问题。
总结
在经过了长达好几天，几乎是属实轮的交互后，终于基本解决了这个问题。
话说，我还是感觉Comate助手适合做某一个模块的事情，这样直接让它完成一个功能，它还是有点力不从心啊。
换句话说，领导还是需要事必躬亲的啊，否则不知道手下会理解成啥样，又会做成啥样！
碰到Comate报错无法执行的问题
最近几天碰到了Comate报错无法执行的问题。有时候它会莫名其妙的停下来，说着自己在修改文档，但是其实已经停下来了，可以输入新交互信息了。
有时候输入了新交互信息，它说报错说无法执行。这时候需要改成debug模式，或者把zulu的Auto关掉，手工选一个AI模型，比如Kimi，就可以继续下去。否则就一直报错不干活。
