common_agent/docs/MODEL_PROVIDER_REQUIREMENTS.md

模型服务商配置与路由需求文档

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