📌 Python·反欺诈专栏 第 3 篇（架构篇）｜系列：00 开篇 → 01 技术选型 → 📍02 架构 → 03 数据篇 →
上一篇：[技术选型篇：RAG 为什么不用 LangChain](《AgentX Python 专栏》02-技术选型篇：RAG 为什么不用 LangChain，而是选了 LlamaIndex？.md)
🏷️ 标签：#Python #金融反欺诈 #LangGraph #GraphRAG #Agent架构 #Neo4j #Text2Cypher
《AgentX Python 专栏》03-架构篇：Agent 和「调个 API」的本质区别，在架构上长什么样？
这是「用 Python 从 0 打造金融反欺诈 GraphRAG 智能体」专栏的第 3 篇。选型定了，这一篇讲整体架构怎么搭、每个设计为什么这么定——这也是 Agent 工程化和"调个 ChatGPT API"的真正分水岭。
本文速览
- 一个请求的完整旅程：从"P001 有风险吗"到带依据的回答
- 六层分层架构——每层职责 + 为什么这么分
- 🔥核心：LangGraph 编排状态机——Agent 的灵魂，以及"跑崩了怎么办"
- 🌉 站在 Java 肩膀上：六层架构的迁移映射
- 4 个让它"像生产系统"的架构决策
一、先看一个请求的旅程
风控分析师问一句：“申请人 P001 有欺诈风险吗？”
如果是"调个 API"，那就是chat.completions.create("P001有风险吗")→ 模型瞎编一通。它根本不知道 P001 是谁。
而在 AgentX-py 里，这个请求会走完这样一条链：
抽出实体 P001 → 判断意图(风险查询) → 生成图查询 Cypher → 校验 + 交叉验证 → Neo4j 沿关系链检索（P001 和谁共用设备/担保） → 算风险特征（团伙规模/黑名单距离）→ LLM 结合证据解释 → 护栏校验（引用的关系真实存在）→ 返回带依据的回答差别就在这条链上：调 API 是"问一句答一句"，Agent 是"会规划、会查证、会兜底、答得有依据"。支撑这条链的，就是架构。
二、六层分层架构
| 层 | 职责 | 关键组件 |
|---|---|---|
| 接入层 | 收请求、校验、流式返回 | FastAPI + Pydantic + SSE |
| 编排层 | Agent 大脑：决定下一步干什么 | LangGraph 状态机 |
| 能力层 | 干活：检索 / 工具 / 记忆 | LlamaIndex RAG、GraphRAG、工具系统 |
| 模型层 | 推理 + 向量化 | Ollama / DeepSeek、bge-m3 |
| 存储层 | 存关系 + 会话 | Neo4j（图+向量）、Redis |
| 横切 | 贯穿全程：评测 + 可观测 | Ragas / DeepEval、OTel / LangFuse |
为什么分层？一句话：职责分离，换件不动全身。想把 DeepSeek 换成别的模型？只动模型层。想加个新检索策略？只动能力层。编排层不关心"用哪个模型"，存储层不关心"谁在调它"。这是十几年工程养成的直觉——层与层之间靠接口说话，不靠耦合。
三、🔥 核心：LangGraph 编排状态机（Agent 的灵魂）
如果说六层是骨架，编排层就是灵魂。它决定了这东西是"智能体"还是"聊天机器人"。
它是一个状态机
我用 LangGraph 把整条链建成一个有向图——每个节点是一步操作，边是流转条件：
图中的三个关键路径：绿色 ✓ 为正常流程，橙色 ⟳ 为重试（≤N 次），红色 ✗ 为降级兜底。一条链三条路，每个节点职责明确——这才是生产级 Agent 编排该有的样子。
“跑崩了怎么办”——这才是面试官想看的
调 API 的人只想"怎么让它跑通"，做过生产的人想的是"它崩了怎么办"。这条链上我埋了三道防线：
- 重试：Text2Cypher 生成的 Cypher 不可靠（小模型尤甚），失败就重生成，最多 N 次；
- 降级：重试还不行，降级到预审过的参数化模板查询——保证至少能返回正确结果；
- 护栏：LLM 可能"语法对、语义错"或编造关系，最后用护栏校验引用的关系在图里真实存在，防幻觉。
💡这套「条件路由 + 重试 + 降级 + 护栏」，就是 2026 AI 岗最高频的考点——“Agent 编排失败模式”。LangGraph 的
add_conditional_edges+ Checkpointer 让它落地得很自然。
四、🌉 站在 Java 肩膀上：架构迁移映射
我不是从零学 AI——我用 Java 自研过一套 Agent 框架（6644 行），这次是带着架构直觉转 Python。六层几乎一一对应：
| Java 版 AgentX | AgentX-py | 说明 |
|---|---|---|
| Spring Boot Controller | FastAPI router | 换语法 |
| AgentService（调度） | service / 编排入口 | 换语法 |
| AgentWorkflow（自研工作流） | LangGraph StateGraph | 框架替代自研，更强 |
ToolRegistry +@Tool | @tool+ registry | 换语法 |
| ChatMemory（Redis） | LangGraph Checkpointer | 换包装 |
| 可观测（OTel+Jaeger） | 同一套 OTel + Jaeger | 底座直接复用 |
最关键的是
AgentWorkflow → LangGraph这一映射：我自己写过工作流引擎，所以一眼看懂 LangGraph 在干什么——它就是把我手写的 while 循环 + 状态管理，封装成了更优雅的状态机 API。框架不是黑魔法，是把你会的概念封装好。
五、4 个让它「像生产系统」的架构决策
光能跑不够，要"像能上线的系统"：
- 图 + 向量一个库（Neo4j 5 原生向量）——省掉单独维护 Milvus，架构更简。
- 双模型可切换（Ollama / DeepSeek）——抽象统一接入层，私有化走本地、拼性能走 API，不依赖单点；主模型故障自动熔断降级到本地。
- 全链路可观测（OTel → Jaeger + LangFuse）——每个节点、每次 LLM 调用都埋点，"哪一步慢/错"一目了然（这是我 Java 版治"20 秒黑盒"练出来的肌肉记忆）。
- 异常体系 + 只读 DB 账号——统一错误响应；Neo4j 用只读账号连接，从数据库层杜绝 Cypher 注入（金融场景的安全底线）。
这些不是设计时拍脑袋想的——是这份架构经过两轮设计评审 + 迭代打磨出来的（评审记录都在 GitHub 仓库里）。「设计 → 评审 → 修复」的闭环本身，比一份完美文档更能说明工程素养。
六、下一篇
架构图纸有了，下一篇就真正动手搭——《环境与底座 + Faker 造一套会"作弊"的数据》：Docker 起 Neo4j，用 Faker 造 2000 个申请人并故意植入欺诈团伙，让图数据库里真有"设备团伙、循环担保环"可查。代码跑起来，纸上架构才算活了。
🤝 写在最后：关于「关注」这件事
全网 AI 教程很多，但从架构设计、代码实现、真实踩坑到评测数据，一条龙带你做完一个工程级作品的系列，真的不多。这个系列，我会一篇篇认真更下去。
如果这篇对你有点用：
- 👍点赞 + 收藏：让更多同路人刷到，也方便你回头查；
- 🔔关注我：这是个长连载，关注了才不会错过后续——断了衔接就难接上了；
- 💬评论区告诉我：你正在做 AI 转型吗？卡在哪一步？想优先看哪篇？——呼声高的我提前更；
- 📦跟着做能攒出作品：每篇都带可复现的步骤，跟着走，你也能搭出属于自己的那一份。
我是SuniaCoder（汪旭 / Sunia），一个 12 年的全栈老兵，正在记录自己的 AI 突围。
这里只写能落地、可复现的硬核实战——不灌水，不空谈。我们下一篇见。
评论区聊聊：你设计过最复杂的系统架构是什么？分层踩过哪些坑？