11节点LangGraph实战：构建合规级RAG智能体完整架构解析

在RAG（检索增强生成）应用日益普及的今天，简单的"检索→生成"链路已经无法满足严肃场景的需求。近日，一位开发者在Reddit的r/LangChain社区分享了他构建的Agentic Financial Parser——一个基于LangGraph、拥有11个节点的自治AI智能体，专门用于解析印度的金融与法律文档（联邦预算、财政法案、所得税、EPF/EPS养老金、RBI KYC、印度宪法等）。

RAG最早由Facebook AI Research在2020年提出，其核心思想是将大语言模型的生成能力与外部知识检索相结合，解决LLM参数知识过时、无法访问私有数据的问题。传统RAG的流程是：用户提问→向量检索→将检索结果作为上下文注入Prompt→LLM生成答案。然而随着应用场景复杂化，这种线性流程暴露出诸多不足：无法处理模糊查询、缺乏对幻觉的后验校验、没有成本控制机制。Agentic RAG是近年来的演进方向，它将智能体（Agent）的决策能力引入RAG管线，使系统能够根据查询性质动态选择执行路径，而非一刀切地走完整检索流程。

这个项目的价值不在于"又一个RAG"，而在于它系统性地回答了一个关键问题：当RAG要投入生产环境、面对合规敏感数据时，需要哪些工程化的护栏？ 意图分类、越狱检测、PII脱敏、模糊查询反问、结果重排、幻觉校验、自我纠错——这些能力都被组织进一张有向状态图中。

从线性链到状态图：LangGraph的11个节点分工

传统RAG是一条直线，而这个项目用LangGraph的StateGraph构建了一张包含11个注册节点的图。每个节点各司其职，配合条件路由实现复杂的决策流程。

LangGraph是LangChain团队推出的框架，专门用于构建有状态的、可循环的LLM应用。与LangChain的链式（Chain）和代理（Agent）抽象不同，LangGraph基于有向图（Directed Graph）的概念，每个节点是一个计算步骤，边定义了数据流向，条件边（conditional edges）则实现了基于运行时状态的动态路由。其底层借鉴了Google Pregel图计算模型的思想，支持状态持久化、人机交互断点（breakpoints）、以及子图嵌套。StateGraph是LangGraph的核心类，开发者通过add_node注册节点函数，通过add_edge和add_conditional_edges定义流转逻辑，最终编译为可执行的图。

核心节点功能详解

• Classifier（分类器）：整个系统的入口大脑。通过1次LLM调用返回结构化JSON（意图、文档类型、置信度），并据此进行6路分流。
• Reject（拒绝）：拦截辱骂性和越狱查询。关键点是它使用正则黑名单在LLM看到内容之前就完成拦截，零LLM调用成本。
• Greet（问候）：处理寒暄类查询，直接绕过整个检索管线，节省向量数据库开销。
• CrossQuestioner（反问）：对模糊查询发起人机交互（HITL）澄清，最多2轮后回退到尽力检索。HITL（Human-in-the-Loop）在AI系统中指在自动化流程的关键决策点引入人类判断。LangGraph原生支持这一机制，通过interrupt_before或interrupt_after在指定节点暂停图的执行，等待外部输入后恢复，状态在暂停期间持久化在checkpointer中。这种"最多2轮"的设计体现了渐进式自主原则——避免无限澄清循环导致用户体验恶化。
• Retriever（检索器）：最重的路径，完整的RAG五阶段管线。
• Web Search / Stock Tool：越界查询走Tavily网络搜索，股票查询走yfinance工具调用。
• Generator（生成器）：使用Gemini Flash Lite，温度0.1，严格基于上下文回答。
• Hallucination Guard（幻觉守卫）：生成后的答案校验层。
• Post-Process / Fallback：持久化、流式输出与熔断恢复。

有意思的是，PII脱敏并不是图中的一个节点，而是运行在图之前的预处理层，通过正则匹配对Aadhaar、PAN卡号、手机号、邮箱、银行账户进行脱敏。这是合规设计上的重要细节——敏感数据在进入任何LLM调用之前就被清洗。

在印度语境下，这一设计的合规必要性尤为突出：Aadhaar号码（12位唯一身份标识）受《Aadhaar法案2016》保护，PAN卡号（永久账户号）属于税务敏感信息，任何未经授权的存储或传输都可能违反2023年通过的DPDP法案（Digital Personal Data Protection Act）。将PII脱敏放在LLM调用之前意味着：即使API提供商承诺不存储数据，系统在架构层面就已经满足了"数据最小化原则"——不发送不必要的敏感数据。正则匹配是这类具有严格格式规范的结构化标识符（如Aadhaar的XXXX-XXXX-XXXX格式、PAN的5字母4数字1字母格式）的高效脱敏方案。

6路智能路由：用分类器驱动决策

这个架构最精妙的设计之一，是分类器返回6种路由之一，通过add_conditional_edges实现分流：

• reject：辱骂/越狱
• greet：问候/闲聊
• cross_question：模糊查询→HITL澄清
• web_search：越界→Tavily
• stock_tool：股票查询→yfinance
• retriever：法律/金融→完整RAG

这种设计的好处显而易见：不是所有查询都值得走完整的检索管线。问候语和越界查询在早期就被分流，既节省了向量数据库和LLM的成本，也降低了端到端延迟。这体现了成本敏感型智能体的核心思路——用便宜的判断替代昂贵的执行。

RAG检索管线：五阶段精度工程

作为最重的路径，检索器包含五个串联阶段，每一步都有明确的工程权衡：

存储与召回的精细平衡

1. Jina AI v3 MRL嵌入：以1024维嵌入后截断到256维。这节省了75%的Pinecone存储空间，而质量损失可忽略。这里用到的是MRL（Matryoshka Representation Learning，套娃表示学习）技术，允许在同一嵌入上灵活取用不同维度。MRL由马里兰大学研究者在2022年提出，其名称来源于俄罗斯套娃——嵌入向量的前d维本身就是一个有效的d维表示。传统嵌入模型训练出固定维度的向量，要降维只能通过PCA等后处理方法且损失较大。MRL在训练阶段就对多个前缀维度（如32、64、128、256、512、1024）同时施加损失函数，使模型学会将最重要的信息编码在靠前的维度中。因此从1024维截断到256维时，关键语义信息得以保留，而存储和检索计算成本大幅降低。

2. Pinecone Serverless：双命名空间设计，共14662个活跃向量。

3. 父子块解析：先检索小的子块（精度高），再从Supabase取回父块（上下文密度高）。这是解决"小块精准但缺上下文、大块完整但噪声多"矛盾的经典方案。具体而言，这一策略解决的是RAG中的"检索粒度悖论"：小块文本（如100-200 token）在语义检索时精度高，因为与查询的语义匹配更精确；但它缺少足够上下文供LLM理解和推理。大块文本（如1000+ token）包含完整上下文，但引入了大量无关噪声，降低了检索命中率。父子块方案的解法是：索引时用小块计算嵌入和做相似度匹配，但在实际送入LLM的上下文中替换为其对应的大块。实现上需要一个关系型存储（如本项目中的Supabase/PostgreSQL）来维护子块到父块的映射关系。

4. Cohere Rerank v3.0：15个候选重排为Top 10"黄金块"，对多文档查询质量提升显著。重排序是信息检索中的二阶段策略：第一阶段用高效但相对粗糙的向量相似度召回大量候选，第二阶段用更精确但计算成本更高的交叉编码器（Cross-Encoder）模型对候选进行精排。Cohere Rerank v3.0将查询和每个候选文档拼接后输入Transformer，直接输出相关性得分，能捕获查询与文档之间的细粒度交互。从15个候选重排为Top 10意味着约33%的初始候选被过滤，有效提高了送入LLM上下文的信噪比。

5. 置信度门控：得分<30%时优雅降级，<45%时触发HITL提示。这是从源头预防幻觉的关键设计。

幻觉守卫设计：咨询式而非阻断式

项目中一个深思熟虑的设计决策是：幻觉守卫采用咨询模式（advisory），而非阻断模式（blocking）。

生成答案后，系统用一次独立的LLM调用做"LLM-as-Judge"验证："这个答案是否基于所提供的上下文？回答YES或NO。" 如果判定未grounded，系统会追加免责声明，但仍然返回答案。

LLM-as-Judge是近年来LLM应用评估领域的重要范式，最早在Stanford的Alpaca评估和LMSYS的Chatbot Arena中大规模应用。其核心思想是用一个LLM来评判另一个LLM的输出质量，替代昂贵的人工标注。在RAG幻觉检测场景中，Judge模型的任务是判断生成答案是否"grounded"（有据可依）于提供的检索上下文。学术界的RAGAS、TruLens等框架已经将这一范式标准化为RAG评估的核心指标之一：Faithfulness（忠实度）。不过这种方法存在固有局限：Judge模型本身也可能犯错，且增加了一次额外的LLM调用延迟和成本——这也是为什么本项目选择咨询模式而非阻断模式的原因之一。

这一取舍的理由值得深思：直接阻断会在LLM合理地知道超出检索范围的知识时造成糟糕的用户体验。免责声明把信任判断权交给用户。在生产环境中这很有参考价值——过度严格的护栏往往适得其反。

生产级韧性：熔断器与HITL权限控制

熔断器防止级联故障

LLM和嵌入API都被pybreaker包裹：3次连续失败→熔断打开→30秒内即时回退→半开后重试。这避免了请求挂起和级联故障，是把智能体投入真实流量所必需的工程实践。

熔断器模式（Circuit Breaker Pattern）源自电气工程中的过载保护概念，由Michael Nygard在2007年的《Release It!》一书中引入软件工程领域，后被Netflix的Hystrix库广泛推广。其核心状态机包含三个状态：闭合（正常通过请求）、打开（拒绝所有请求并立即返回降级响应）、半开（允许少量探测请求通过以检测服务是否恢复）。在LLM应用中，熔断器特别重要：LLM API的延迟高（通常1-10秒）且费用按token计费，如果API出现间歇性故障，没有熔断器的系统会让请求堆积，导致用户长时间等待，同时可能在超时后重试造成更多无效开销。本项目设定3次失败阈值和30秒恢复窗口，是对LLM API故障模式（通常为短暂的速率限制或服务过载）的合理匹配。

网络搜索的权限流设计

系统从不自动触发Tavily。当检索置信度低时，它会先询问用户"我在文档里没找到，要搜索网络吗？"，用户同意后才路由到网络搜索节点。这既控制了API成本，又让用户对智能体"离开知识边界"这一行为拥有控制权。这种设计体现了"渐进式自主"原则——智能体在知识边界内自主行动，在边界处征求人类许可，避免了完全自主系统可能带来的不可预测行为和成本失控。

零成本基础设施与性能指标

或许最令人印象深刻的是，整个系统运行在各类免费额度上：Render（512MB）部署、Pinecone Serverless、MongoDB Atlas（30天TTL）、Supabase、Upstash Redis（<100ms语义缓存）、Gemini Flash Lite、Langfuse可观测性、Cohere与Jina。

关键性能数据

• graph.py共1809行代码
• 11个注册节点、6条路由路径、2个熔断器
• 14662个活跃向量，索引20+部印度政府法案
• 缓存命中<100ms，冷启动端到端延迟<8秒

此外，同一套11节点管线还通过Meta WhatsApp Cloud API对外服务——同样的图、同样的护栏、同样的PII盾牌，无需单独的机器人逻辑。

总结：RAG工程化的设计决策清单

这个项目的意义在于，它把散落在各处的"最佳实践"整合进了一个可运行、可观测、可低成本部署的系统里。对于任何计划将RAG投入合规敏感场景的团队，它至少提供了几个值得借鉴的问题：

• 幻觉守卫是阻断还是咨询？
• MRL嵌入截断的质量/存储权衡如何取舍？
• LLM API的熔断阈值定多少？
• 是否让智能体自动搜索还是先征得许可？

生产级Agentic RAG还远未有标准答案——每一个设计决策背后，都是对成本、体验、安全与准确性的多维权衡。项目已在GitHub开源，感兴趣的开发者可以深入研究其实现细节。