commit

2026-05-29 21:38:16 +08:00
parent 80eada415d
commit d4b5015beb
28 changed files with 3373 additions and 47 deletions
@@ -0,0 +1,29 @@
+# 上下文词汇表
+
+## 术语
+
+### ChatModel
+- 定义：Spring AI 的聊天模型抽象接口，所有 LLM 提供商（DashScope、OpenAI、Ollama 等）都实现此接口
+- 使用场景：所有需要 LLM 推理/生成回答的代码应面向此接口编程
+
+### EmbeddingModel
+- 定义：Spring AI 的文本向量化抽象接口，将文本转换为向量
+- 使用场景：RAG 流程中将文档文本转为向量存入 Milvus
+
+### DashScopeChatModel
+- 定义：DashScope（阿里云）对 ChatModel 的具体实现
+- 使用场景：当前项目硬编码使用，需要改为通过 ChatModel 接口引用
+
+### ReactAgent
+- 定义：Spring AI Alibaba Agent Framework 的反应式 Agent 实现
+- 使用场景：Planner-Executor-Replanner 多 Agent 协作
+
+### Spring AI Alibaba Agent Framework
+- 定义：基于 Spring AI 的多 Agent 协作框架，提供 ReactAgent、PlannerAgent、ExecutorAgent 等
+- 使用场景：项目核心 Agent 逻辑，ReactAgent.builder().model() 接受 ChatModel 接口
+
+## 业务规则
+
+- ChatModel 是唯一 LLM 调用抽象：替换模型只需更换 Spring Boot starter 和配置
+- EmbeddingModel 是唯一向量化抽象：替换向量模型只需更换 starter 和配置
+- ReactAgent 已兼容 ChatModel 接口，不绑定 DashScope
@@ -0,0 +1,7 @@
+# devflow 索引
+
+## 项目
+
+| 日期 | slug | 领域 | 关键词 | 状态 |
+|---|---|---|---|---|
+| 2026-05-29 | chatmodel-abstraction | 解耦 | ChatModel, EmbeddingModel, DashScope, Spring AI | 进行中 |
@@ -0,0 +1,42 @@
+# ChatModel Abstraction Decisions
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | ChatModel 注入方式：Spring Boot 自动注入 vs 手动工厂创建 | evidence-driven | 已解决 |
+| Q2 | 边界 | RagService 流式对话：Spring AI ChatModel.stream() 替代 DashScope Generation | evidence-driven | 已解决 |
+| Q3 | 验收 | VECTOR_DIM 是否需要动态化 | user-interview | 已解决 |
+| Q4 | 边界 | VectorEmbeddingService 批量向量化：EmbeddingModel 支持批量调用 | evidence-driven | 已解决 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| ReactAgent.builder().model() 接受 ChatModel 接口 | javap 反编译 | 已汇报 |
+| ChatModel 应通过 Spring Boot 自动注入 | DashScope starter 自动注册 ChatModel Bean | 已汇报 |
+| RagService 可用 ChatModel.stream() 替代 Generation | Spring AI 接口有 stream(Prompt) 返回 Flux | 已汇报 |
+| EmbeddingModel 支持批量调用 | EmbeddingModel.call(EmbeddingRequest) 接受多条文本 | 已汇报 |
+
+## User-interview
+
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
+|---|---|---|---|
+| VECTOR_DIM 怎么处理？ | "配置文件动态化" | 已确认 | 已回写 proposal |
+
+## 关键取舍
+
+- 决策：本次只解耦不替换实现
+  - 原因：先验证抽象层正确再换模型
+  - 影响：代码改动不改变运行行为
+  - 风险接受：用户同意先只做解耦
+- 决策：VECTOR_DIM 从配置文件读取
+  - 原因：换模型时改 yml 即可
+  - 影响：MilvusConstants.VECTOR_DIM 改为从 MilvusProperties 读取
+
+## 架构审计
+
+- 风险1：RagService 流式适配 — DashScope Generation 和 Spring AI ChatModel.stream() 返回结构不同，需验证 thinking/content 分离逻辑
+- 风险2：DashScopeConfig 通用性 — 硬编码 dashscope 配置键，换模型后需改为通用键
+- 风险3：ChatModel Bean 冲突 — 多 starter 并存时需 @Primary 或条件注解
+- 低风险/无风险：VectorEmbeddingService、MilvusClientFactory 直接替换无问题