commit

2026-05-31 21:45:14 +08:00
parent d4b5015beb
commit ac08345369
67 changed files with 11120 additions and 387 deletions
@@ -0,0 +1,42 @@
+# ChatModel + Embedding 解耦 Design
+
+## 架构摘要
+
+当前代码直接使用 DashScope 具体实现类 → 改为面向 Spring AI 抽象接口编程，通过 Spring Boot 自动注入切换实现。
+
+## 关键决策
+
+- ChatModel：Spring Boot Starter 自动注册 Bean，通过 `@Autowired ChatModel` 注入，不再手动工厂创建
+- EmbeddingModel：Spring Boot Starter 自动注册 Bean，通过 `@Autowired EmbeddingModel` 注入，替代 DashScope TextEmbedding SDK
+- RagService 流式对话：用 `ChatModel.stream(Prompt)` 返回 `Flux<ChatResponse>` 替代 DashScope Generation
+- VECTOR_DIM：从 `application.yml` 配置读取，替代 `MilvusConstants.VECTOR_DIM` 常量
+
+## 模块地图
+
+| 模块 | 职责 | 改动 |
+| --- | --- | --- |
+| ChatService | 封装 ChatModel + ReactAgent | 删除工厂方法，注入 ChatModel |
+| ChatController | HTTP API 入口 | 删除 DashScope import，使用注入 ChatModel |
+| AiOpsService | 多 Agent 协作 | DashScopeChatModel → ChatModel |
+| VectorEmbeddingService | 向量化 | DashScope SDK → EmbeddingModel 接口 |
+| RagService | RAG 流式对话 | DashScope Generation → ChatModel.stream() |
+| MilvusConstants | Milvus 常量 | VECTOR_DIM 改为配置化 |
+| MilvusProperties | Milvus 配置 | 新增 vectorDim 字段 |
+| ModelRoutingConfig | 模型路由 | 新增：yml 关键字驱动的 @Primary 路由（Bean 名 > 类名 > 回退） |
+| SiliconFlowEmbeddingConfig | Embedding | 新增：独立 OpenAiApi → SiliconFlow, BGE-M3 |
+| application.yml | 配置 | 新增 vector-dim 配置项 |
+
+## 接口影响
+
+- 级别：L2 内部接口（所有消费者在同一实现范围内）
+- 判级原因：方法签名从具体类改为接口，调用方需同步修改，但都在本项目内
+- 不改变外部 API（/api/chat, /api/chat_stream, /api/ai_ops 的 HTTP 响应不变）
+
+## 架构风险
+
+- RagService 流式适配最复杂：DashScope Generation 返回 Flowable<GenerationResult>，Spring AI ChatModel.stream() 返回 Flux<ChatResponse>，需适配 StreamCallback 接口
+- 缓解：Spring AI 的 Flux 与项目已有的 SSE 推送逻辑天然兼容
+- ChatModel Bean 冲突：多 starter 并存时需 @Primary 或条件注解区分默认实现
+- 缓解：通过 ModelRoutingConfig 集中管理，@Primary 声明默认 Bean；跨厂商时只改 `@Qualifier` 名
+- DashScopeConfig 通用性：`spring.ai.dashscope.chat.options.timeout` 是厂商绑定配置键
+- 缓解：本次保留该配置（只做解耦不换实现）；换模型时改配置键