knowledge-agent-workbench 复盘——手写 Workflow 与 LangGraph 双实现对照
仓库:lau0708/knowledge-agent-workbench · Python 3.12 / FastAPI · ChromaDB · Vue 3
一句话:把同一个 RAG + Agent 工作流做两遍——一遍手写 Workflow,一遍 LangGraph,搞清楚框架替你做了什么、你还要对什么负责。
一、为什么做双实现对照
框架不是黑盒。只调 LangGraph,出问题时容易停在「它内部怎么走的」;只手写,又容易重复造轮子。把两者并排做一遍,才能讲清差异,也能在排障和面试时给出有依据的判断。
二、双存储与混合检索
SQLite 存文档记录、Chunk 和元数据;ChromaDB 存向量索引。检索走混合检索——关键词负责精确,向量负责语义。关键参数都是显式的:
| 参数 | 默认 | 说明 |
|---|---|---|
MIN_SIMILARITY | 0.60 | 最低相似度阈值,低于此值的召回被丢弃 |
TOP_K | 3 | 默认检索数量 |
CHUNK_SIZE / OVERLAP | 200 / 40 | 切分长度与重叠长度 |
AGENT_MAX_TOOL_CALLS | 5 | Agent 单轮最大工具调用次数 |
一致性上有个诚实的取舍: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 怎么选」时,回答是有实测依据的,而不是背概念。