docs(model-provider): 补充模型服务商配置与路由设计

docs/MODEL_PROVIDER_REQUIREMENTS.md

@@ -0,0 +1,448 @@
+# 模型服务商配置与路由需求文档
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+|------|------|
+| 所属项目 | Common Agent |
+| 文档类型 | 需求文档 |
+| 编写日期 | 2026-05-25 |
+| 目标阶段 | RAG 最小检索闭环与模型平台化前置能力 |
+| 相关模块 | `model-provider`、`rag-core`、`platform-admin` |
+
+## 2. 背景
+
+Common Agent 的长期目标是建设一套可复用的企业级 AI 应用基础平台，后续需要支持 RAG、Agent 编排、工具调用、会话管理和模型统一接入。
+
+当前项目已经完成基础工程、附件上传、文档解析、RAG 知识库和知识文档管理。下一步需要将解析结果切片、生成向量并写入 `rag_chunk_embedding`，再继续建设检索召回和 Agent 运行时。
+
+在模型接入层面，项目需要同时支持：
+
+- 自建模型服务，例如云服务器上的 Ollama。
+- 云端模型平台，例如硅基流动、阿里云百炼、OpenAI 兼容服务。
+- 不同任务使用不同模型，例如简单任务走本地小模型，复杂推理走云端大模型。
+- RAG 向量化使用稳定且可控的 embedding 模型，并保证同一知识库内向量空间一致。
+
+因此，本阶段需要建设一个轻量但可扩展的模型服务商配置与路由能力，作为 RAG 向量导入和后续 Agent 调用的统一入口。
+
+## 3. 建设目标
+
+### 3.1 业务目标
+
+1. 支持在后台配置多个模型服务商，包括本地 Ollama、硅基流动、百炼和其他 OpenAI-compatible 服务。
+2. 支持在后台维护每个服务商下的具体模型，例如聊天模型、Embedding 模型、重排序模型。
+3. 支持按任务类型选择模型，达到“小任务本地处理，大任务云端处理”的成本控制目标。
+4. 支持 RAG 向量导入从配置中选择 Embedding 模型，不在代码中写死服务商和模型名。
+5. 支持记录模型调用日志，为后续成本统计、质量评估、失败排查和限流策略提供数据基础。
+
+### 3.2 技术目标
+
+1. 抽象统一的 `ModelGateway`，业务模块不直接依赖具体服务商 SDK。
+2. 优先兼容 OpenAI API 形态，降低接入 Ollama、硅基流动、百炼等平台的差异成本。
+3. 将 API Key 与业务配置解耦，避免密钥明文散落在业务代码或普通配置中。
+4. 为后续 Spring AI 接入、Agent 运行时和模型调用观测保留扩展点。
+5. 保持与当前项目风格一致：Spring Boot、MyBatis-Plus、DTO、统一返回体、结构化枚举。
+
+## 4. 范围说明
+
+### 4.1 本阶段范围
+
+本阶段覆盖以下能力：
+
+- 模型服务商配置管理。
+- 模型配置管理。
+- 模型路由规则管理。
+- 模型调用日志记录。
+- Embedding 调用网关。
+- Chat 调用网关的基础接口设计。
+- RAG 切片向量导入接入模型网关。
+- Ollama 远程服务接入设计。
+- 硅基流动等 OpenAI-compatible 云服务接入设计。
+
+### 4.2 本阶段不覆盖
+
+本阶段不实现以下完整能力：
+
+- 完整 Agent 运行时。
+- 多租户权限体系。
+- 复杂模型质量评测平台。
+- 自动提示词优化。
+- 按用户或部门计费结算。
+- 高级模型编排工作流。
+- 完整密钥管理系统。
+
+这些能力可以在模型服务商配置与路由能力稳定后继续扩展。
+
+## 5. 术语定义
+
+| 术语 | 说明 |
+|------|------|
+| 模型服务商 | 提供模型调用能力的上游服务，例如 Ollama、硅基流动、百炼、OpenAI |
+| 模型配置 | 某个服务商下的具体模型配置，例如 `Qwen/Qwen3-Embedding-0.6B` |
+| 模型路由 | 根据任务类型、成本、质量、可用性选择具体模型的规则 |
+| OpenAI-compatible | 兼容 OpenAI API 风格的服务接口，通常包含 `/v1/chat/completions`、`/v1/embeddings` |
+| 本地模型 | 由用户自行部署和维护的模型服务，例如云服务器上的 Ollama |
+| 云端模型 | 第三方平台托管的模型服务，例如硅基流动或百炼 |
+| Embedding | 将文本转换为向量，用于 RAG 检索召回 |
+| Rerank | 对召回结果二次排序，提高检索结果相关性 |
+
+## 6. 当前问题
+
+### 6.1 模型配置不可管理
+
+当前项目尚未接入统一模型配置层。如果在 RAG 向量化阶段直接写死模型服务商、模型名和 API 地址，后续切换服务商会产生重复改造。
+
+### 6.2 成本控制缺少入口
+
+不同任务对模型能力要求不同。简单分类、标题生成、短文本摘要可以使用本地小模型，复杂推理、长上下文问答和 Agent 规划适合使用云端大模型。当前缺少统一路由层，无法系统性节省调用成本。
+
+### 6.3 RAG 向量模型需要稳定约束
+
+同一知识库中的向量必须来自同一个语义空间。随意混用不同 Embedding 模型或不同维度，会导致检索结果不稳定。当前 `rag_chunk_embedding` 已有模型名和维度字段，但缺少知识库级别的模型绑定和重建索引约束。
+
+### 6.4 调用可观测性不足
+
+模型调用需要记录耗时、状态、错误、token、费用估算和业务来源。当前没有统一日志表，后续无法分析失败原因、成本趋势和模型效果。
+
+### 6.5 密钥管理需要提前约束
+
+模型服务商通常需要 API Key。若直接明文存储在数据库或配置文件中，会带来泄露风险。项目早期可以简化实现，但必须明确密钥引用和加密策略。
+
+## 7. 用户角色
+
+| 角色 | 诉求 |
+|------|------|
+| 平台管理员 | 配置模型服务商、模型、路由规则和密钥引用 |
+| 知识库维护者 | 为知识库选择 Embedding 模型，触发索引重建 |
+| Agent 配置者 | 为不同 Agent 选择默认模型或路由策略 |
+| 系统开发者 | 通过统一网关调用模型，不关心具体服务商差异 |
+| 运维人员 | 查看模型服务可用性、调用失败、耗时和成本趋势 |
+
+## 8. 典型使用场景
+
+### 8.1 RAG 使用硅基流动生成向量
+
+管理员配置硅基流动服务商，添加 `Qwen/Qwen3-Embedding-0.6B` 模型，设置维度为 1024。知识库选择该模型作为 Embedding 模型。文档上传后，系统解析、切片、调用模型生成向量，并写入 `rag_chunk_embedding`。
+
+### 8.2 简单任务使用远程 Ollama
+
+用户在云服务器部署 Ollama，并开放安全访问地址。管理员配置 Ollama 服务商和本地小模型，例如 `qwen2.5:7b`。系统在标题生成、短摘要、分类等任务中优先调用 Ollama，减少云端模型费用。
+
+### 8.3 复杂任务使用云端大模型
+
+当任务类型为复杂 Agent 规划、长上下文问答或工具调用编排时，路由规则选择云端大模型。若主模型调用失败，可以按规则切换到备用模型。
+
+### 8.4 Embedding 模型变更触发索引重建
+
+知识库已经使用某个 Embedding 模型完成索引。管理员切换该知识库的 Embedding 模型时，系统标记该知识库需要重建索引，并阻止新旧模型向量混合检索。
+
+### 8.5 查看模型调用日志
+
+运维人员进入模型调用日志页面，查看某段时间内的调用次数、失败率、平均耗时和费用估算，定位某个服务商或模型的异常。
+
+## 9. 功能需求
+
+### 9.1 模型服务商管理
+
+系统应支持新增、编辑、启用、停用和查询模型服务商。
+
+服务商至少包含：
+
+- 服务商编码。
+- 服务商名称。
+- 服务商类型。
+- API 基础地址。
+- 鉴权方式。
+- 密钥引用。
+- 超时时间。
+- 默认优先级。
+- 是否启用。
+- 备注。
+
+服务商编码应全局唯一。
+
+### 9.2 模型配置管理
+
+系统应支持在服务商下维护具体模型。
+
+模型至少包含：
+
+- 所属服务商。
+- 模型编码。
+- 上游模型名称。
+- 模型类型。
+- 上下文窗口。
+- 输出 token 上限。
+- Embedding 维度。
+- 是否本地模型。
+- 是否默认模型。
+- 能力标签。
+- 价格配置。
+- 是否启用。
+
+同一服务商下模型编码应唯一。
+
+### 9.3 模型路由规则管理
+
+系统应支持按任务类型配置模型路由。
+
+路由规则至少包含：
+
+- 任务类型。
+- 匹配范围。
+- 主模型。
+- 备用模型列表。
+- 路由策略。
+- 最大允许耗时。
+- 是否启用。
+
+任务类型初始支持：
+
+- RAG 文档向量化。
+- RAG 查询向量化。
+- RAG 问答生成。
+- 简单文本处理。
+- 复杂文本处理。
+- Agent 规划。
+- Rerank。
+
+### 9.4 模型网关
+
+系统应提供统一模型网关，供业务模块调用。
+
+模型网关应支持：
+
+- 根据任务类型选择模型。
+- 调用 Embedding 模型生成向量。
+- 调用 Chat 模型生成回复。
+- 记录调用日志。
+- 在主模型失败时按规则尝试备用模型。
+- 返回统一错误信息。
+
+业务模块不应直接调用具体服务商接口。
+
+### 9.5 RAG 向量导入
+
+系统应将 RAG 文档索引流程接入模型网关。
+
+向量导入流程应支持：
+
+1. 读取文档解析快照。
+2. 按切片策略生成 `rag_chunk`。
+3. 根据知识库或全局路由选择 Embedding 模型。
+4. 调用模型生成向量。
+5. 写入 `rag_chunk_embedding`。
+6. 更新文档索引状态。
+7. 记录模型调用日志。
+
+同一知识库应固定 Embedding 模型和维度。模型变更时应触发重建索引流程。
+
+### 9.6 Ollama 接入
+
+系统应支持配置远程 Ollama 服务。
+
+Ollama 接入要求：
+
+- 支持 OpenAI-compatible 地址，例如 `http://host:11434/v1`。
+- 支持 Chat 模型。
+- 支持 Embedding 模型。
+- 支持模型健康检查。
+- 支持设置本地模型标签。
+
+Ollama 远程访问不应直接裸露在公网。生产环境应通过 VPN、内网、反向代理鉴权、Tailscale、Cloudflare Tunnel 或安全网关访问。
+
+### 9.7 云端 OpenAI-compatible 服务接入
+
+系统应支持硅基流动、百炼、OpenAI 或其他兼容接口。
+
+接入要求：
+
+- 服务商可配置 `baseUrl`。
+- 服务商可配置 `apiKey` 引用。
+- 模型可配置上游模型名。
+- Embedding 支持设置维度。
+- Chat 支持设置温度、最大输出等参数。
+
+### 9.8 调用日志
+
+系统应记录模型调用日志。
+
+日志至少包含：
+
+- 请求 ID。
+- 服务商。
+- 模型。
+- 任务类型。
+- 业务来源。
+- 调用状态。
+- 耗时。
+- token 数量。
+- 费用估算。
+- 错误码。
+- 错误消息。
+- 请求哈希。
+- 创建时间。
+
+日志中不得记录完整 API Key。
+
+### 9.9 后台管理界面
+
+后台管理界面应逐步提供：
+
+- 服务商列表。
+- 模型列表。
+- 路由规则配置。
+- 调用日志查询。
+- 模型健康检查结果。
+- 知识库 Embedding 配置入口。
+
+首期可先完成后端接口和 SQL 结构，前端在 RAG 最小闭环后接入。
+
+## 10. 非功能需求
+
+### 10.1 可扩展性
+
+模型服务商接入应通过统一接口扩展。新增 OpenAI-compatible 服务商时，原则上只需要新增配置，不需要修改业务调用代码。
+
+### 10.2 可用性
+
+模型调用应支持超时控制和失败兜底。云端模型失败时，可以根据路由规则切换备用模型。本地 Ollama 不可用时，不应阻塞整个系统启动。
+
+### 10.3 性能
+
+Embedding 批量生成应支持批处理，减少网络请求次数。批量大小应可配置，避免超过上游接口限制。
+
+### 10.4 可观测性
+
+每次模型调用应有请求 ID，并记录耗时、状态和错误原因。后续可接入监控告警。
+
+### 10.5 可维护性
+
+新增核心代码应补充中文注释，说明类职责、关键分支和扩展边界。新增枚举应同步纳入系统枚举初始化测试。
+
+## 11. 数据安全需求
+
+1. API Key 不得写死在代码中。
+2. API Key 不应明文返回给前端。
+3. 数据库可保存 `secretRef` 或加密后的 `apiKeyCipher`。
+4. 若保存加密密钥，主加密密钥应来自环境变量或外部配置，不应存储在数据库。
+5. 调用日志不得保存完整请求正文中的敏感信息。
+6. 管理接口后续应接入权限控制。
+7. Ollama 远程服务应限制访问来源，避免未授权公网调用。
+
+## 12. 成本控制需求
+
+系统应支持以下成本控制策略：
+
+- 本地优先：简单任务优先走 Ollama。
+- 成本优先：优先选择单价较低的云模型。
+- 质量优先：复杂任务优先选择能力更强的模型。
+- 手动指定：某个知识库或 Agent 固定使用指定模型。
+- 失败兜底：主模型失败后切换备用模型。
+
+调用日志应记录费用估算所需字段，为后续成本报表提供基础。
+
+## 13. RAG 特殊约束
+
+### 13.1 向量维度约束
+
+当前 `rag_chunk_embedding.embedding` 使用 `VECTOR(1024)`。因此首期 Embedding 模型应统一输出 1024 维向量。
+
+适配方向：
+
+- 硅基流动：可使用 `Qwen/Qwen3-Embedding-0.6B`，配置 1024 维。
+- Ollama：应选择输出维度与表结构匹配的 embedding 模型。
+- 百炼：可使用支持 1024 维的文本向量模型。
+
+### 13.2 模型一致性约束
+
+同一知识库同一索引版本内，应使用同一个 Embedding 模型和维度。
+
+当知识库 Embedding 模型或维度变化时：
+
+- 已有索引应标记为需要重建。
+- 新索引写入前应清理旧切片向量，或写入新的索引版本。
+- 检索时应只使用当前生效模型生成的向量。
+
+### 13.3 失败状态约束
+
+向量生成失败时，文档 `indexStatus` 应更新为 `FAILED`，并记录失败原因。部分切片成功、部分失败时，首期按整个文档索引失败处理，避免半成品参与检索。
+
+## 14. 验收标准
+
+### 14.1 服务商配置验收
+
+- 可以新增一个 Ollama 服务商。
+- 可以新增一个硅基流动服务商。
+- 可以为服务商配置至少一个 Chat 模型和一个 Embedding 模型。
+- 服务商编码和模型编码唯一性校验生效。
+
+### 14.2 路由验收
+
+- 可以为 RAG 文档向量化配置默认 Embedding 模型。
+- 可以为简单文本处理配置 Ollama 模型。
+- 可以为复杂文本处理配置云端模型。
+- 主模型不可用时，可以根据配置切换备用模型。
+
+### 14.3 RAG 向量导入验收
+
+- 文档解析完成后，可以生成切片。
+- 切片可以调用配置的 Embedding 模型生成 1024 维向量。
+- 向量可以写入 `rag_chunk_embedding`。
+- 文档索引状态可以从 `PENDING` 流转到 `INDEXING`、`INDEXED` 或 `FAILED`。
+- 调用日志可以记录 Embedding 调用信息。
+
+### 14.4 安全验收
+
+- 前端查询服务商详情时不返回明文 API Key。
+- 调用日志中不包含完整 API Key。
+- 未配置密钥时，云端服务调用失败信息清晰。
+- Ollama 远程地址可配置，但文档中明确生产环境访问安全要求。
+
+### 14.5 测试验收
+
+- 后端新增实体、Mapper、Service、Controller 结构测试。
+- 模型路由单元测试。
+- Embedding 网关单元测试。
+- RAG 向量导入服务单元测试。
+- 配置缺失、模型停用、服务商停用、调用失败等异常测试。
+
+## 15. 分阶段里程碑
+
+### 15.1 阶段一：模型配置基础
+
+- 新增模型服务商表。
+- 新增模型配置表。
+- 新增基础 CRUD 接口。
+- 支持 OpenAI-compatible 服务商配置。
+- 支持密钥引用字段。
+
+### 15.2 阶段二：Embedding 网关与 RAG 接入
+
+- 新增 Embedding 调用网关。
+- 接入硅基流动或 Ollama Embedding。
+- RAG 切片后调用 Embedding 并写入 `rag_chunk_embedding`。
+- 更新文档索引状态。
+- 记录调用日志。
+
+### 15.3 阶段三：模型路由与失败兜底
+
+- 新增模型路由规则。
+- 支持按任务类型选择模型。
+- 支持主备模型调用。
+- 支持本地优先、成本优先、质量优先策略。
+
+### 15.4 阶段四：后台管理与成本观测
+
+- 前端接入服务商管理。
+- 前端接入模型管理。
+- 前端接入路由规则管理。
+- 前端接入调用日志查询。
+- 增加费用估算和调用趋势展示。
+
+## 16. 参考资料
+
+- Ollama OpenAI-compatible API: https://docs.ollama.com/api/openai-compatibility
+- Ollama Embeddings: https://docs.ollama.com/capabilities/embeddings
+- Spring AI OpenAI Embeddings: https://docs.spring.io/spring-ai/reference/api/embeddings/openai-embeddings.html
+- SiliconFlow Embedding 模型列表: https://www.siliconflow.com/models/embedding