← 返回博客

knowledge-agent-workbench 复盘——手写 Workflow 与 LangGraph 双实现对照

仓库:lau0708/knowledge-agent-workbench · Python 3.12 / FastAPI · ChromaDB · Vue 3

一句话:把同一个 RAG + Agent 工作流做两遍——一遍手写 Workflow,一遍 LangGraph,搞清楚框架替你做了什么、你还要对什么负责。

一、为什么做双实现对照

框架不是黑盒。只调 LangGraph,出问题时容易停在「它内部怎么走的」;只手写,又容易重复造轮子。把两者并排做一遍,才能讲清差异,也能在排障和面试时给出有依据的判断。

knowledge-agent-workbench 分层架构(简化)
前端Vue 3 Web 工作台(Dashboard / 知识库 / 助手 / Workflow / 审批 / Trace)+ Swagger UIAPI 层 · FastAPI(src/main.py)文档管理 / RAG 问答 / Agent / Workflow / LangGraph / HITL / Trace服务层document_service · indexing_service · rag_service(Hybrid Retriever) · AgentState · Tool Registry · HITL · Memory存储SQLite(文档 / Chunk / 长期记忆)· ChromaDB(向量)· Trace Store模型DeepSeek(生成)· bge-small-zh-v1.5(嵌入)

二、双存储与混合检索

SQLite 存文档记录、Chunk 和元数据;ChromaDB 存向量索引。检索走混合检索——关键词负责精确,向量负责语义。关键参数都是显式的:

参数默认说明
MIN_SIMILARITY0.60最低相似度阈值,低于此值的召回被丢弃
TOP_K3默认检索数量
CHUNK_SIZE / OVERLAP200 / 40切分长度与重叠长度
AGENT_MAX_TOOL_CALLS5Agent 单轮最大工具调用次数

一致性上有个诚实的取舍:SQLite 与 ChromaDB 是补偿机制,不是跨库强一致事务——文档更新/删除失败时尝试恢复文件与数据库状态,向量索引也能从 Markdown 重新生成 Embedding 重建。

三、手写 Workflow:没有任何魔法

手写版的状态就是一个显式 dict,节点是函数,边是 if/else。它带节点定义、条件路由、有限补充检索和失败处理。好处是完全可控、好调试;坏处是样板代码多,状态一复杂维护成本就上来。

四、LangGraph 对照:图表达 + 检查点

LangGraph 把状态管理、节点/边、检查点做成基础设施,同一套流程用图表达更清晰,自带可观测性。代价是得先理解它的状态模型和执行语义。两个版本都保留在仓库里,/agent/workflow 走手写版,/agent/langgraph 走图版,可以在同一个 Web 工作台里对比执行轨迹。

五、HITL 与 Trace:把「可信」落到可操作

高风险工具触发人工批准,支持批准 / 拒绝 / 修改参数后执行三种处置。Trace 不只记录,还做失败分析——每条 Trace 能查列表、详情和失败原因。Memory 分两层:短期会话历史裁剪,长期记忆持久化在 SQLite。

六、已知限制(诚实地写)

维度当前状态
文档格式仅支持 Markdown,不支持 PDF / Word / HTML
持久化Trace、HITL、Agent Session 为进程内存储,重启后丢失
一致性SQLite 与 ChromaDB 是补偿机制,不是强一致事务
长期记忆关键词 / BM25 检索,尚未向量化
多租户无用户认证、多租户和细粒度权限
规模面向本地小规模知识库,未做分布式索引

七、复盘

这个项目最大的价值不是「又一个 RAG demo」,而是把框架当成可拆开对照的对象:知道每个节点在干什么、哪些能力是框架给的、哪些责任仍然在自己身上。面试被问「LangGraph 和手写 Workflow 怎么选」时,回答是有实测依据的,而不是背概念。