200 lines
7.4 KiB
Markdown
200 lines
7.4 KiB
Markdown
# 软件需求规格说明书（SRS）
|
||
## 自建多模态 AI 网关系统（AI Gateway System）
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 文档版本 | V1.0 |
|
||
| 编写日期 | 2026-08-23 |
|
||
| 项目负责人 | 紫川 |
|
||
| 文档状态 | 草案 |
|
||
|
||
---
|
||
|
||
## 1. 引言
|
||
|
||
### 1.1 编写目的
|
||
|
||
本文档描述"自建多模态 AI 网关系统"的功能需求、非功能需求与约束条件，作为后续软件设计说明书（SDD）编写和开发实现的依据。
|
||
|
||
### 1.2 项目背景
|
||
|
||
由于公司内网访问 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，希望在自有美国服务器上搭建一套类似 Gemini 首页体验的对话系统，聚合多个免费 AI API 渠道，实现"一个渠道不可用自动切换下一个"的高可用能力，同时支持图文多模态问答。
|
||
|
||
### 1.3 项目目标
|
||
|
||
- 提供稳定、统一的 Web 对话入口，界面体验接近 Gemini 首页
|
||
- 聚合至少 5 家免费多模态 API（Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral）
|
||
- 单一渠道失败时自动故障转移（Failover），用户无感知
|
||
- 支持图片 + 文字混合输入的问答
|
||
- 部署在美国服务器，规避公司内网对海外 API 的直连限制
|
||
- 全部使用免费额度，不产生 API 调用费用
|
||
|
||
### 1.4 术语定义
|
||
|
||
| 术语 | 说明 |
|
||
|---|---|
|
||
| 渠道（Channel） | 指某一家 AI API 提供商的接入配置，如 Gemini 渠道、Groq 渠道 |
|
||
| 网关（Gateway） | 统一转发、聚合多个渠道请求的中间层服务，本项目采用 One-API |
|
||
| Failover | 故障转移，某渠道不可用时自动切换到下一优先级渠道 |
|
||
| 多模态（Multimodal） | 同时支持文本与图像作为输入的模型能力 |
|
||
| RPM | Requests Per Minute，每分钟请求数限制 |
|
||
|
||
---
|
||
|
||
## 2. 总体描述
|
||
|
||
### 2.1 产品定位
|
||
|
||
本系统是一个**私有部署的 AI 对话网关**，面向单用户（紫川本人，未来可扩展至团队），核心价值是"聚合免费额度 + 高可用" —— 让用户无需关心具体调用了哪家模型，只需要在统一界面里提问、上传图片，系统自动选择当前可用的免费渠道完成响应。
|
||
|
||
### 2.2 用户角色
|
||
|
||
| 角色 | 描述 |
|
||
|---|---|
|
||
| 终端用户 | 使用 LobeChat 前端进行日常图文问答的人（紫川本人） |
|
||
| 系统管理员 | 配置渠道、监控用量、调整优先级的人（紫川本人，同一人身兼两角） |
|
||
|
||
### 2.3 运行环境
|
||
|
||
- 部署位置：美国服务器（无地区网络限制）
|
||
- 访问方来源：公司内网（网络不稳定，仅需保证到本服务器一段链路可用）
|
||
- 容器化部署：Docker + Docker Compose
|
||
- 操作系统：Linux（Ubuntu/Debian 系）
|
||
|
||
### 2.4 约束与假设
|
||
|
||
- 假设：美国服务器可稳定访问 Google、NVIDIA、Groq、OpenRouter、Mistral 官方域名
|
||
- 约束：仅使用各平台免费额度，不产生付费调用
|
||
- 约束：不做未成年人相关内容、不涉及企业内部代码泄露到公网模型（需用户自行注意脱敏）
|
||
- 假设：公司内网到美国服务器的连接比公司内网直连各 API 官方域名更稳定
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### FR-1 统一对话界面
|
||
|
||
| 编号 | 描述 | 优先级 |
|
||
|---|---|---|
|
||
| FR-1.1 | 提供 Web 端对话界面，支持文本输入 | 高 |
|
||
| FR-1.2 | 支持图片上传并随文本一起提问（多模态输入） | 高 |
|
||
| FR-1.3 | 支持流式输出（打字机效果） | 中 |
|
||
| FR-1.4 | 支持多轮对话上下文保留 | 高 |
|
||
| FR-1.5 | 支持对话历史保存与查看 | 中 |
|
||
| FR-1.6 | 界面访问需密码验证（Access Code） | 高 |
|
||
|
||
### FR-2 多渠道聚合与路由
|
||
|
||
| 编号 | 描述 | 优先级 |
|
||
|---|---|---|
|
||
| FR-2.1 | 支持接入 Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral 五家渠道 | 高 |
|
||
| FR-2.2 | 支持为渠道设置优先级与权重 | 高 |
|
||
| FR-2.3 | 支持将多个渠道的不同模型映射为统一对外模型名 | 高 |
|
||
| FR-2.4 | 请求失败（限流/超时/额度耗尽）时自动切换下一优先级渠道 | 高 |
|
||
| FR-2.5 | 渠道故障后自动禁用，冷却期后自动恢复重试 | 中 |
|
||
|
||
### FR-3 多模态能力
|
||
|
||
| 编号 | 描述 | 优先级 |
|
||
|---|---|---|
|
||
| FR-3.1 | 图文问答仅路由到支持视觉的渠道/模型 | 高 |
|
||
| FR-3.2 | 纯文本问答可路由到所有渠道（含无视觉能力的 Groq） | 中 |
|
||
|
||
### FR-4 渠道管理（管理员）
|
||
|
||
| 编号 | 描述 | 优先级 |
|
||
|---|---|---|
|
||
| FR-4.1 | 支持在后台新增/编辑/删除渠道 | 高 |
|
||
| FR-4.2 | 支持查看每个渠道的调用次数、成功率、余额/额度状态 | 中 |
|
||
| FR-4.3 | 支持手动启用/禁用某个渠道 | 中 |
|
||
| FR-4.4 | 支持生成/吊销对外 Token | 高 |
|
||
|
||
### FR-5 安全与访问控制
|
||
|
||
| 编号 | 描述 | 优先级 |
|
||
|---|---|---|
|
||
| FR-5.1 | 前端需 Access Code 才能进入对话界面 | 高 |
|
||
| FR-5.2 | 后台管理端口不直接暴露公网 | 高 |
|
||
| FR-5.3 | 全站启用 HTTPS | 高 |
|
||
| FR-5.4 | API Key 等敏感信息通过环境变量管理，不写入代码仓库 | 高 |
|
||
|
||
---
|
||
|
||
## 4. 非功能需求
|
||
|
||
### 4.1 性能需求
|
||
|
||
| 指标 | 目标值 |
|
||
|---|---|
|
||
| 单次请求响应首字延迟 | < 3 秒（视具体渠道而定） |
|
||
| Failover 切换耗时 | < 5 秒 |
|
||
| 并发用户数 | 支持 1~5 人同时使用（当前阶段单用户为主） |
|
||
|
||
### 4.2 可用性需求
|
||
|
||
- 系统整体可用性目标：99%（不含各免费 API 官方自身故障）
|
||
- 任一单个渠道不可用不应导致整体服务中断
|
||
|
||
### 4.3 可维护性需求
|
||
|
||
- 渠道配置修改无需重新部署代码，后台界面操作即可生效
|
||
- 日志需可追溯每次请求实际路由到了哪个渠道，便于排查
|
||
|
||
### 4.4 兼容性需求
|
||
|
||
- 前端需兼容主流桌面浏览器（Chrome/Edge/Safari）及移动端浏览器
|
||
- 网关对外接口需兼容 OpenAI API 格式，便于未来接入其他客户端（如 Claude Code、第三方 App）
|
||
|
||
### 4.5 安全需求
|
||
|
||
- 所有对外 API Key 不得硬编码在配置文件中提交至版本库
|
||
- HTTPS 全站加密传输
|
||
- 访问密码需具备一定复杂度
|
||
|
||
---
|
||
|
||
## 5. 外部接口需求
|
||
|
||
### 5.1 用户接口
|
||
|
||
- Web 浏览器访问，响应式布局，适配桌面与移动端
|
||
|
||
### 5.2 外部 API 接口
|
||
|
||
| 渠道 | Base URL | 认证方式 |
|
||
|---|---|---|
|
||
| Gemini | generativelanguage.googleapis.com/v1beta | API Key（Header/Query） |
|
||
| NVIDIA NIM | integrate.api.nvidia.com/v1 | Bearer Token（OpenAI 兼容） |
|
||
| Groq | api.groq.com/openai/v1 | Bearer Token（OpenAI 兼容） |
|
||
| OpenRouter | openrouter.ai/api/v1 | Bearer Token（OpenAI 兼容） |
|
||
| Mistral | api.mistral.ai/v1 | Bearer Token（OpenAI 兼容） |
|
||
|
||
---
|
||
|
||
## 6. 数据需求
|
||
|
||
| 数据项 | 存储位置 | 说明 |
|
||
|---|---|---|
|
||
| 对话历史 | LobeChat（浏览器 IndexedDB 或 PostgreSQL） | 视部署模式而定 |
|
||
| 渠道配置、API Key | One-API 数据库（MySQL） | 敏感信息，需备份加密 |
|
||
| 调用日志 | One-API 数据库 | 用于用量统计与故障排查 |
|
||
|
||
---
|
||
|
||
## 7. 验收标准
|
||
|
||
1. 通过 Web 界面可正常发起文本对话并获得响应
|
||
2. 上传图片后可正常获得图片理解相关的回答
|
||
3. 手动关闭优先级最高的渠道后，系统能自动切换到下一渠道且用户侧无明显感知
|
||
4. 后台可查看各渠道当日调用次数
|
||
5. 全站访问强制 HTTPS，非法访问无法进入后台管理端口
|
||
|
||
---
|
||
|
||
## 8. 后续可扩展需求（非本期范围）
|
||
|
||
- 多用户账号体系与权限隔离
|
||
- 语音输入/输出支持
|
||
- 与紫川的 FAM（家庭 AI 监控系统）前端集成展示
|
||
- 接入更多免费渠道（如 Cerebras、阿里云百炼等）
|