LangGraph Sidecar 迁移 — 需求与决策汇总
日期: 2026-07-20
状态: 终稿（已批准）
版本: 1.0
1. 背景与动因
1.1 现有 AI 架构
cfc-backend 自 2025 年起接入 Dify（开源 LLM 应用平台）提供全部 AI 能力：
| 使用场景 |
Dify 能力 |
Java 消费者 |
| 家庭 AI 聊天（通用助手 + 精准营养助手） |
Chatbot API |
AIService.sendMessage(), sendNutritionMessage() |
| 工作流（任务解析/舌诊/异步摘要） |
Workflow API |
AIService.runWorkflow(), sendTongueDiagnosis() |
| 知识库检索 |
Datasets API |
DifySyncService.syncToDify() |
| 文章 AI 问答 |
Chatbot API |
ArticleService.getAiQuestions() |
Dify 深度嵌入 8 个 Service、3 个 Controller，承担 AI 能力中间件角色。
1.2 迁移动因
| 问题 |
描述 |
优先级 |
| 数据安全 |
所有对话/报告数据经 Dify 平台流转，无法保证数据不外泄 |
P0 |
| 黑盒 Prompt |
Dify 应用内的 prompt 编辑无版本管理，调试困难 |
P1 |
| 不可控发布 |
Dify 版本升级可能引入不兼容变更，发布节奏被动 |
P1 |
| 运维负担 |
Dify 自部署实例需单独维护资源，偶发不可用 |
P2 |
| 灵活性不足 |
Agent 编排能力有限，难以实现复杂条件路由和 HITL |
P2 |
| 成本 |
Dify 本身无授权费，但作为中间层增加了调用链路开销 |
P3 |
2. 需求分析
2.1 核心需求
| ID |
需求 |
说明 |
优先级 |
| R1 |
消除 Dify 单点依赖 |
所有 AI 能力线下部署，不依赖外部平台 |
P0 |
| R2 |
Java 8/Spring Boot 2.7 不动 |
后端不升级 JDK/框架，最小化 Java 侧改动 |
P0 |
| R3 |
Agent 编排能力 |
支持条件路由、多步骤、工具调用、循环 |
P0 |
| R4 |
对话记忆 |
短期（窗口）+ 长期（实体/事实）+ 语义（向量召回） |
P0 |
| R5 |
RAG 知识库 |
知识文档加载、分块、向量化、混合检索 |
P1 |
| R6 |
工具调用安全 |
Python Agent 通过 HTTP 调 Java 获取数据，不直连 MySQL |
P1 |
| R7 |
灰度迁移 |
Dify 保留为 fallback，流量逐步切换 |
P0 |
| R8 |
运维简单 |
最小化中间件依赖，单机可部署 |
P1 |
2.2 覆盖场景
| 场景 |
当前实现 |
目标 Agent |
| 家庭聊天（通用） |
Dify Chatbot → AIService |
ChatAgent（StateGraph） |
| 精准营养推荐 |
Dify Chatbot → AIService |
RecommendAgent（LLM + RAG） |
| 健康报告解读 |
Dify Workflow |
AnalysisAgent |
| 舌诊分析 |
Dify Workflow |
MultiModalAgent |
| 任务自动解析 |
Dify Workflow |
TaskAgent（ChatAgent 子节点） |
| 文章 AI 问答 |
Dify Chatbot |
ChatAgent + RAG |
| 知识库同步 |
Dify Datasets API |
KnowledgePipeline |
2.3 非需求
- 不改动 Java 端 JDK/Spring Boot 版本
- 不改动 cfc 业务逻辑（Controller/Service 现有行为不变）
- 不立即引入 PostgreSQL/Redis 等额外中间件
- 不做完整的 A/B 测试平台
3. 方案评估
3.1 候选方案
A. Spring AI（Java 侧内嵌）
| 维度 |
评估 |
| 技术栈 |
Spring AI 1.x + Spring Boot 3.x → 需升级 JDK 8→21 |
| Agent 能力 |
基础 Tool Calling + Chain, 无 StateGraph/条件路由 |
| RAG |
基础 ETL pipeline, 不如 LangChain 成熟 |
| 学习成本 |
团队熟悉 Java, 但 Spring AI 2025 年才 GA, 生态不完善 |
| 结论 |
❌ 否决 — 需要 JDK 升级 + Agent 能力不足 |
B. LangChain4j（Java 侧内嵌）
| 维度 |
评估 |
| 技术栈 |
LangChain4j 1.x, 兼容 Java 8 |
| Agent 能力 |
Tool Calling + 简单链, 无 LangGraph 编排 |
| RAG |
完整 pipeline (embedding/store/retrieval) |
| 社区 |
较小, 文档不完善 |
| LLM 调用 |
需通过 Spring AI 或直接 HTTP |
| 结论 |
❌ 否决 — Agent 编排能力不足, 无图执行引擎 |
C. Python LangGraph Sidecar ✅
| 维度 |
评估 |
| 技术栈 |
FastAPI + LangChain + LangGraph + ChromaDB |
| Agent 能力 |
完整 StateGraph：条件路由/循环/并行/HITL/持久化 |
| RAG |
最成熟的 LangChain RAG pipeline |
| 记忆 |
三层记忆（BufferMemory + EntityMemory + VectorStoreMemory） |
| Java 改动 |
最小——仅 AIService 加 HTTP 路由, 新增 AiGateway |
| 社区 |
全球最大 LLM 框架生态 |
| 部署 |
Docker Compose / systemd 均可 |
| 结论 |
✅ 选定方案 |
3.2 决策树
Dify 替代方案
├─ 留在 Java 侧
│ ├─ Spring AI → ❌ 需 JDK 21 + Agent 能力不足
│ └─ LangChain4j → ❌ Agent 编排能力不足 + 社区小
└─ Python 侧服务 → ✅ LangGraph Sidecar
3.3 已否决但文档化的选择
| 方案 |
否决原因 |
存档位置 |
| Spring Boot 3 升级 + Spring AI |
需 JDK 8→21 全量升级, 风险大, Agent能力不足 |
docs/backup/architecture/ |
| LangChain4j 内嵌 |
Agent编排受限, 无StateGraph, 社区不成熟 |
— |
| Dify 继续使用 + 小修小补 |
数据安全问题不解决, 长期不可持续 |
— |
| 替换 Dify 但保留 AxonHub 路由 |
增加第三方依赖, 不如直接调 LLM API |
— |
4. 最终架构
4.1 架构总览
用户 (微信小程序 / Web)
│ HTTP
▼
cfc-backend (Java 8, Spring Boot 2.7.18)
├── 业务 Controller (不变)
├── AIService.java → AiGateway.java (HTTP→Python, fallback→Dify)
└── AiContextService.java (Python 调用的数据接口)
│ HTTP (内网)
▼
langgraph-service (Python 3.11, FastAPI :9000)
├── FastAPI 网关 + Agents (RecommendAgent / ChatAgent / AnalysisAgent / MultiModalAgent)
├── LangGraph StateGraph 引擎 + Checkpointer + Memory Manager
├── RAG Pipeline (ChromaDB 文件模式 + 混合检索 + 重排序)
└── Tool 层 (HTTP → Java 数据接口)
│
▼
LLM API (DeepSeek-V3 / Qwen2.5 / Embedding API)
4.2 关键设计决策
| 决策 |
选项 |
选择 |
理由 |
| JDK 版本 |
8 / 21 |
Java 8 不变 |
全量升级风险大, LangGraph sidecar 不需要 |
| 内存数据库 |
SQLite / Chroma / PGVector |
ChromaDB 文件模式 |
零配置, 10 万条内足够 |
| Checkpointer |
MemorySaver / PG |
MemorySaver 优先 |
Phase 1-2 不依赖 PG, 后续按需升级 |
| 工具调用方式 |
直连 MySQL / HTTP 调 Java |
HTTP 调 Java |
数据主权在 Java 侧, 安全可控 |
| 部署方式 |
Docker Compose / systemd |
两者皆可 |
开发用 Docker, 生产按实际情况选 |
| 模型路由 |
直调 LLM / 通过 AxonHub |
直调 LLM API |
简化架构, 减少第三方依赖 |
| 记忆同步 |
Python 主写 / Java 主写 |
Python 主写 |
记忆是 Agent 的一部分，自然归 Python |
| Dify 处理 |
立即停用 / 保留 fallback |
保留 fallback |
灰度迁移, 按阶段逐步关闭 |
4.3 项目结构
D:\workspace\cfc\cfc-langgraph\ # 新建 Python 项目
├── pyproject.toml / Dockerfile / docker-compose.yml
├── app/
│ ├── main.py / config.py / api/ # FastAPI 入口 + 路由
│ ├── agents/ # LangGraph Agent 定义
│ ├── graphs/ # StateGraph 图定义
│ ├── tools/ # Agent Tool (HTTP→Java)
│ ├── rag/ # RAG Pipeline
│ ├── memory/ # 记忆管理
│ └── models/ # Pydantic 模型
├── data/chroma_db/ # 向量数据库持久化
└── tests/
4.4 API 接口
| 端点 |
方法 |
Agent |
说明 |
/api/v1/chat |
POST |
ChatAgent |
家庭 AI 聊天 |
/api/v1/recommend |
POST |
RecommendAgent |
商品/活动/文章推荐 |
/api/v1/analyze |
POST |
AnalysisAgent |
健康报告解读 |
/api/v1/agent |
POST |
Orchestrator |
多 Agent 编排 |
/api/v1/tongue |
POST |
MultiModalAgent |
舌诊图像分析 |
/api/v1/health |
GET |
— |
健康检查 |
Java AI Gateway 接口（供 Python Tool 层调用）：
| 端点 |
方法 |
用途 |
/api/ai/context/user/{id} |
GET |
用户/家庭上下文 |
/api/ai/context/report/{id} |
GET |
健康报告详情 |
/api/ai/context/emotion/{id} |
GET |
情绪数据 |
/api/product/search |
POST |
商品/活动检索 |
4.5 资源估算
| 资源 |
最低 |
推荐 |
| CPU |
0.5 核 |
1 核 |
| 内存 |
256MB |
512MB |
| 磁盘 |
1GB (代码+Chroma) |
5GB (含日志) |
| LLM Token |
与 Dify 基本持平 (+10% Agent 多轮) |
— |
5. 分阶段迁移计划
Phase 1：基建 + RecommendAgent（第1-2周）
目标: Python 服务跑起来, 第一个 Agent 上线
| Task |
内容 |
文件 |
| 1 |
脚手架：pyproject.toml, FastAPI 骨架, Dockerfile |
cfc-langgraph/ |
| 2 |
配置管理 + .env 模板 |
app/config.py, .env.example |
| 3 |
健康检查 + 基础中间件 |
app/api/health.py |
| 4 |
ChromaDB 初始化 + 知识库文章加载 |
app/rag/ |
| 5 |
RecommendAgent (LLM + tool search_product/search_article) |
app/agents/recommend_agent.py |
| 6 |
推荐 API (POST /api/v1/recommend) |
app/api/recommend.py |
| 7 |
Java AiGateway (HTTP→Python + 熔断 + Dify fallback) |
cfc-backend/.../service/AiGateway.java |
| 8 |
RecommendationController 改造：灰度 5% 走 Python |
cfc-backend/.../controller/ |
| 9 |
Docker Compose 编排 |
docker-compose.yml |
| 10 |
集成测试 + 边界验证 |
tests/ |
交付标准:
curl /api/v1/health 返回 200curl /api/v1/recommend 返回推荐结果（含 LLM 理由）- Java 侧 5% 流量走 Python, 异常自动 fallback
- 编译验证
mvn clean compile
计划文档: docs/superpowers/plans/2026-07-20-langgraph-phase1.md
Phase 2：ChatAgent + RAG + 记忆（第3-4周）
目标: 替代 Dify 核心聊天能力
| Task |
内容 |
| 1 |
三层记忆（BufferMemory + EntityMemory + VectorStoreMemory） |
| 2 |
意图分类器（classify_intent node） |
| 3 |
ChatAgent StateGraph（classify→load_context→llm_call→parse_tasks） |
| 4 |
RAG Pipeline（混合检索 + 重排序 + 压缩） |
| 5 |
Java Context API（供 Python 调用的 HTTP 数据接口） |
| 6 |
Java AIService 改造：聊天优先走 Python, Dify fallback |
| 7 |
集成测试 + 灰度 30% |
| 8 |
AiUserFact / AiConversationSummary 设为只读 |
计划文档: docs/superpowers/plans/2026-07-20-langgraph-phase2.md
Phase 3：高级 Agent + 知识库自动化（第5-6周）
目标: 剩余场景迁移 + 运维就绪
| Task |
内容 |
| 1 |
AnalysisAgent（报告解读 StateGraph） |
| 2 |
MultiModalAgent（舌诊） |
| 3 |
KnowledgePipeline（定时从 Java 拉文章→分块→向量化） |
| 4 |
LangSmith Trace 接入 |
| 5 |
DifySyncService 标记废弃 |
| 6 |
灰度 100%, Dify 降级为冷备 |
计划文档: docs/superpowers/plans/2026-07-20-langgraph-phase3.md
Phase 4：收尾 + 运维（第7-8周）
目标: 运维完善, 代码清理
| Task |
内容 |
| 1 |
Python 侧性能调优（连接池、缓存、异步） |
| 2 |
Prometheus 监控 + /metrics 暴露 |
| 3 |
JSON 日志标准化 + 日志聚合 |
| 4 |
生产级 Docker Compose |
| 5 |
Java 侧清理 Dify 相关代码 |
| 6 |
运维文档 + 架构文档更新 |
计划文档: docs/superpowers/plans/2026-07-20-langgraph-phase4.md
6. 决策日志
6.1 已决定的否决项
| 否决项 |
时间 |
原因 |
| Spring Boot 3 升级 |
2026-07-20 |
全量升级 JDK 8→21 风险大, 收益不足 |
| Dify 原地修补 |
2026-07-20 |
数据安全问题不解决 |
| AxonHub 模型路由 |
2026-07-20 |
增加第三方依赖, 直调 LLM API 更简单 |
| Java LangChain4j |
2026-07-20 |
Agent 编排能力不足, 社区小 |
| Python 直连 MySQL |
2026-07-20 |
数据安全性、事务一致性风险 |
| Dify 立即下线 |
2026-07-20 |
需要灰度过渡期 |
6.2 已确立的原则
- 数据主权: Agent Tool 一律通过 HTTP 调 Java 接口, Python 不直连 DB
- 最小改动: Java 侧只改 AIService 路由和新增 AiGateway, 不动业务逻辑
- 灰度安全: 每个 Phase 都有流量开关 + Dify fallback, 可随时回退
- 渐进式迁移: 4 个 Phase 串行, 每阶段有独立验证点
- 无锁定: LangGraph 是标准 Python 框架, 无需特殊基础设施
7. 文档清单
7.1 当前有效文档（无需变更）
| 文件 |
说明 |
docs/superpowers/specs/2026-07-20-langgraph-migration-design.md |
LangGraph 迁移设计文档（架构/API/记忆/部署） |
docs/superpowers/specs/2026-07-20-langgraph-requirements-summary.md |
本文件 — 需求与决策汇总 |
docs/superpowers/plans/2026-07-20-langgraph-phase1.md |
Phase 1 实施计划（10 个 Task） |
docs/superpowers/plans/2026-07-20-langgraph-phase2.md |
Phase 2 实施计划（8 个 Task） |
docs/superpowers/plans/2026-07-20-langgraph-phase3.md |
Phase 3 实施计划（6 个 Task） |
docs/superpowers/plans/2026-07-20-langgraph-phase4.md |
Phase 4 实施计划（6 个 Task） |
7.2 已归档文档（被本方案否决）
| 原路径 |
现路径 |
说明 |
docs/architecture/SpringBoot3升级+Dify替代实施计划.md |
docs/backup/architecture/SpringBoot3升级+Dify替代实施计划.md |
Spring Boot 3 + Spring AI 方案（JDK 升级前提） |
docs/architecture/Dify替代迁移可行性分析.md |
docs/backup/architecture/Dify替代迁移可行性分析.md |
Spring AI 替代可行性分析 |
docs/architecture/2026-07-20-SB3-upgrade-plan.md |
docs/backup/architecture/2026-07-20-SB3-upgrade-plan.md |
SB3 升级 + Dify 替代实现计划 |
docs/数据与AI结合技术方案.md |
docs/backup/数据与AI结合技术方案.md |
原始数据+AI 技术方案（Dify 时代） |
docs/实现计划.md |
docs/backup/实现计划.md |
原始实现计划（Dify 时代） |
8. 风险登记册
| 风险 |
概率 |
影响 |
应对 |
责任人 |
| Python 服务不稳定 |
中 |
高 |
Phase 1 灰度 5% + 熔断 + Dify fallback |
开发 |
| LangGraph 学习成本 |
高 |
中 |
Phase 1 从最简 Agent 开始 |
开发 |
| 记忆数据迁移丢失 |
低 |
中 |
Phase 2 前 Java 侧保持双写 |
开发 |
| ChromaDB 性能瓶颈 |
低 |
中 |
10 万条内足够, 超出切 PGVector |
架构 |
| LLM API 费用增加 |
中 |
低 |
Agent 多轮约多 10% token |
运营 |
| Java 8 兼容性 |
低 |
高 |
Java 侧不改依赖, 不影响 |
开发 |
9. 当前状态
- ✅ 方案评审通过
- ✅ 设计文档发布
- ✅ 4 个 Phase 计划已编写并推送 (
cfclub 分支)
- ⏸ 等待执行指令
- ❌ Phase 1-4 尚未开始实施
下一步: 用户确认 → 开始 Phase 1 Task 1（脚手架搭建）
