LLM API Gateway 需求文档

需求场景

用户需要建立一个本地大模型API中转服务器，用于统一管理多个大模型供应商的API密钥和调用地址，对外提供统一的访问入口，简化客户端调用流程。

架构技术方案

采用Node.js + Express框架实现轻量级API网关，使用配置文件管理多个后端模型服务，实现请求转发和响应处理。

核心组件

1. HTTP服务器：基于Express框架，监听本地端口（如1337）
2. 配置管理：JSON配置文件存储多个模型供应商信息
3. 路由转发：将收到的API请求转发到目标模型服务
4. 响应处理：统一处理和返回模型响应
5. 健康检查：监控后端服务可用性

需求处理逻辑

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 <repository-url>
cd aiagent

# 安装依赖
npm install

# 复制环境变量模板
cp .env.example .env

测试，发现api key那块有些问题，颇废了一些力气，目前还没有完全解决。

调试

key的问题

添加新模型那里，默认就调用对应供应商的api。可以给一个勾选框，勾选后，可以选择手动填apikey，这样就不会因为浏览器自动填内容，而导致自动填入错误的key。

尝试让它帮我做功能测试

你能帮我做如下的功能测试吗？

1. 刷新浏览器页面（加载最新 HTML/JS）。

2. 打开「添加模型」弹窗，确认：

   • 默认「手动填写 API Key」未勾选，API Key 输入框禁用且空白。

3. 勾选后输入框变为可写；取消勾选再次禁用并清空。

4. 分别测试：

   • 不勾选、留空 → 提交后查看 config/models.json，应写入 ${XXX} 环境变量；
   • 勾选并填写自定义 key → 提交后应写入你填的 key。

验证通过即完成。

Comate说：我派子 agent 完成整套功能测试，过程你无需操作，只看结论即可。

它会派agent完成整套功能测试，但是我没说，它就没干，真是一戳一蹦跶，不戳不蹦跶！

添加新模型那里，默认就调用对应供应商的api。可以给一个勾选框，勾选后，可以选择手动填apikey，这样就不会因为浏览器自动填内容，而导致自动填入错误的key。

你已经改了models.json里面的信息。现在的问题是，如果我手工添加模型供应商，添加的新供应商它的Headers 配置还是错的，要从源头解决问题。

总结 

在经过了长达好几天，几乎是属实轮的交互后，终于基本解决了这个问题。

话说，我还是感觉Comate助手适合做某一个模块的事情，这样直接让它完成一个功能，它还是有点力不从心啊。

换句话说，领导还是需要事必躬亲的啊，否则不知道手下会理解成啥样，又会做成啥样！

碰到Comate报错无法执行的问题

最近几天碰到了Comate报错无法执行的问题。有时候它会莫名其妙的停下来，说着自己在修改文档，但是其实已经停下来了，可以输入新交互信息了。

有时候输入了新交互信息，它说报错说无法执行。这时候需要改成debug模式，或者把zulu的Auto关掉，手工选一个AI模型，比如Kimi，就可以继续下去。否则就一直报错不干活。