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

## 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