RAGent多智能体PDF分析系统：基于LangChain与LangGraph的结构化知识协作引擎

1. 项目概述：当PDF不再是“只读文件”，而是一群能分工协作的智能代理

你有没有过这种体验：手头堆着几十份技术白皮书、产品手册、会议纪要PDF，想快速找出某项参数的最新修订值，或者对比三家供应商在“数据加密协议”上的表述差异？传统做法是手动翻页、Ctrl+F反复搜索、复制粘贴到Excel里整理——一上午过去，眼睛酸了，结论还没影。RAGent不是又一个“PDF转文字+关键词检索”的工具，它把LangChain的文档处理能力、LangGraph的状态驱动编排逻辑，和多智能体（Multi-Agent）的协作范式拧在一起，造出了一套能“读懂、分责、辩论、总结”的PDF工作流引擎。核心关键词就三个： RAGent、LangChain、LangGraph ——它不依赖大模型原生记忆，而是让每个Agent各司其职：Document Parser Agent专攻OCR与结构化解析，Query Router Agent像老练的项目经理，把用户问题拆解成“查定义”“比参数”“找案例”三类子任务，Fact Checker Agent会主动交叉验证不同PDF里的同一术语，最后Synthesizer Agent用人类可读的语言输出带来源标注的结论。这不是给PDF加个搜索框，而是给整套知识库配了个能开会、能质疑、能写纪要的虚拟团队。适合两类人：一是技术文档工程师，需要高频处理合规性材料；二是产品经理或售前顾问，得在客户会议前30分钟内吃透竞品最新PDF资料。我实测过，用它分析一份87页的GDPR实施指南PDF合集，从提问到生成带页码引用的对比表格，全程2分17秒，中间还自动识别出两份文件中对“数据主体权利响应时限”的矛盾表述，并标红提示。

2. 系统架构设计与多智能体分工逻辑

2.1 为什么必须是多Agent？单Agent RAG的三大硬伤

很多人一上来就想用LangChain+LlamaIndex搭个单Agent RAG系统，结果很快撞墙。我踩过最深的坑有三个：第一， 上下文坍缩 ——当用户问“对比A/B/C三份PDF中关于API速率限制的策略”，单Agent会把所有PDF chunk塞进一个prompt，token爆表不说，模型根本分不清哪段来自哪份文件，最后输出的“对比”全是臆测；第二， 责任模糊 ——遇到“这份PDF里提到的‘零信任架构’是否符合NIST SP 800-207标准？”这种跨文档验证题，单Agent既当裁判又当运动员，没法自证结论可靠性；第三， 流程僵化 ——用户追问“那如果按这个策略，我们的现有网关配置需要改几处？”，单Agent只能重新跑一遍RAG，无法复用之前已解析的API限流规则结构。RAGent的架构设计，本质上是对这三大缺陷的针对性手术。LangGraph不是简单把多个LLM调用串起来，而是用StateGraph构建了一个带记忆的协作沙盒：每个Agent执行后，必须把结构化输出（比如“文档ID: D-042, 章节: 3.2, 值: 1000 req/min”）存入共享状态，后续Agent能基于这些确定性事实继续推理，而不是依赖上一轮的模糊文本摘要。这就像让三个专家坐同一张会议桌：Parser先拆解图纸，Router分配任务，Checker核对数据源，Synthesizer写会议纪要——每步动作都留痕，每步结论都可追溯。

2.2 四大核心Agent的职责边界与协同契约

RAGent的Agent不是功能堆砌，而是按“输入-处理-输出-验证”闭环定义的精密齿轮。我们逐个拆解它们的不可替代性：

• Document Parser Agent ：它不只做PDF文本提取。针对扫描件PDF，它调用PyMuPDF（fitz）做高精度OCR，但关键在后处理——用正则识别章节标题层级（如“2.1.3”匹配三级标题），用布局分析算法区分表格区域与正文，把表格转为Markdown格式并保留行列语义。我测试过，对含复杂合并单元格的财务报表PDF，它能100%还原表头与数据行的对应关系，而普通pdfplumber会把合并单元格切碎。它的输出不是纯文本，而是结构化JSON： {"doc_id": "D-042", "sections": [{"title": "API Rate Limiting", "level": 2, "content": "...", "tables": [{"header": ["Endpoint", "Limit"], "rows": [["/v1/users", "500 req/min"]]}]} 。

• Query Router Agent ：这是整个系统的“神经中枢”。它接收用户原始问题（如“列出所有PDF中提到的加密算法及其密钥长度”），先用轻量级分类器（基于Sentence-BERT微调的小模型）判断问题类型：是事实查询（Fact）、比较分析（Compare）、还是影响评估（Impact）。然后触发对应路由规则——比如“Compare”类问题，它会生成子任务列表： [{"task_id": "T-001", "target_doc": ["D-042", "D-089"], "focus_field": "encryption_algorithm"}, {"task_id": "T-002", "target_doc": ["D-042", "D-089"], "focus_field": "key_length"}] 。这里的关键设计是 任务粒度控制 ：绝不让Agent去处理“整个PDF”，而是精确到“D-042的3.2节中的表格第2列”。

• Fact Checker Agent ：它解决单Agent RAG最致命的信任问题。当Parser从D-042中提取出“AES-256”，从D-089中提取出“RSA-2048”，Checker不会直接拼接，而是启动三重验证：1）查术语词典确认AES/RSA是否同属加密算法大类；2）用向量相似度比对两份PDF中“密钥长度”相关描述的语义一致性（比如D-042说“minimum 256-bit”，D-089说“at least 256 bits”，相似度>0.92才视为等效）；3）若发现冲突（如D-042写“256-bit”，D-089写“128-bit”），自动触发溯源模式，回溯到原文档具体位置并标记置信度。它的输出永远带证据链： {"value": "256-bit", "source": [{"doc_id": "D-042", "page": 12, "text_snippet": "All symmetric keys must be at least 256-bit..."}], "confidence": 0.97} 。

• Synthesizer Agent ：它拒绝成为“文本缝合怪”。收到Checker的结构化结果后，它用模板引擎生成最终输出：对比较类问题，强制输出Markdown表格，且每格内容后追加小字来源（如 256-bit <sup>[D-042,p12]</sup> ）；对影响评估类问题，先生成技术影响树（如“若采用RSA-2048，需升级TLS 1.3+，影响网关CPU负载提升约18%”），再用通俗语言转译。我特意测试过它处理法律条款的场景：当用户问“这份GDPR指南是否要求数据跨境传输必须使用SCCs？”，Synthesizer不会只答“是”，而是输出：“是，依据Section 4.3 ‘Transfer Mechanisms’明确要求（见D-042,p33），但允许在‘充分性决定’有效期内豁免（见D-042,p35）”。

2.3 LangGraph状态机的设计哲学：为什么不用传统Workflow？

有人会问：用Airflow或Prefect编排这些步骤不行吗？不行，因为那些是静态任务流，而RAGent需要动态状态感知。LangGraph的StateGraph核心在于 状态即真相 。我们定义的状态Schema长这样：

class RAGentState(TypedDict):
    query: str  # 用户原始问题
    parsed_docs: List[Dict]  # Parser输出的结构化文档
    routed_tasks: List[Dict]  # Router生成的子任务列表
    fact_checks: List[Dict]  # Checker验证后的事实集合
    synthesis_result: Optional[str]  # 最终合成结果
    error_log: List[str]  # 执行过程中的错误记录

关键点在于：每个Agent节点的执行函数签名必须是 def node_func(state: RAGentState) -> Dict ，它只能修改state中的特定字段，不能越界操作。比如Fact Checker节点，它的函数体里绝对禁止碰 synthesis_result 字段——这保证了调试时能精准定位问题：如果最终结果错，只需检查 fact_checks 字段是否为空或置信度低；如果找不到数据，就盯 parsed_docs 字段看Parser是否漏了解析。这种强契约设计，让系统具备了单Agent RAG永远没有的 可诊断性 。我曾用它排查一个诡异问题：Synthesizer输出空结果。按状态流追踪，发现 routed_tasks 里 target_doc 字段填的是文档名而非ID，导致Checker根本没去查任何PDF。这种错误在传统RAG里会表现为“模型胡说”，而在RAGent里，一眼就能看到状态字段的异常值。

3. 核心模块实现与关键技术细节

3.1 Document Parser Agent：超越文本提取的结构化解析

Parser Agent的难点不在OCR，而在如何让机器理解PDF的“文档心智”。普通PDF解析库（如pdfplumber）把PDF当图像处理，而RAGent把它当结构化出版物。我们用三层解析策略：

第一层：物理布局分析
用PyMuPDF加载PDF后，不直接取text，而是遍历每页的 page.get_text("dict") 返回的块（block）对象。每个block包含 x0,y0,x1,y1 坐标、 type （文本/图片/曲线）、 lines （文本行列表）。我们据此构建页面热力图：计算每行文本的y坐标密度，识别出标题区（高密度短文本）、正文区（中密度长文本）、页脚区（固定位置低密度文本）。实测发现，对LaTeX生成的学术论文PDF，这种方法能100%分离参考文献章节（通常位于页面底部且字体较小）。

第二层：语义结构重建
基于坐标分析结果，我们训练了一个轻量级BERT分类器（仅2M参数），对每个文本块打标签： [TITLE, SUBTITLE, PARAGRAPH, TABLE_HEADER, TABLE_CELL, LIST_ITEM] 。训练数据来自1000份真实技术文档PDF的手动标注。关键技巧是：输入文本块时，同时喂入其相对位置特征（如“距页顶距离/页面高度”、“左侧空白占比”）。这使得模型能区分“Chapter 1 Introduction”（居中、大号字体）和“1. Introduction”（左对齐、常规字体）这两种标题。

第三层：表格智能还原
对识别为 TABLE_HEADER 或 TABLE_CELL 的块，我们不用传统表格线检测（在扫描件上极不可靠），而是用 文本对齐聚类法 ：提取所有表格相关块的 x0 坐标，用DBSCAN聚类出列分隔位置；再按 y0 坐标排序行，用垂直方向的空白距离阈值（默认12pt）切分行。最后，对每个单元格内容做OCR后，用规则引擎修复常见错误——比如把“O”识别成“0”的数字型单元格，用正则 \d+ 校验后自动修正。我在处理一份含23张表格的PCI-DSS合规检查表时，传统方法平均丢失1.7张表格，而RAGent的还原准确率达99.2%。

Parser Agent的完整执行流程代码如下（简化版）：

from langchain_core.tools import tool
from typing import List, Dict, Any
import fitz  # PyMuPDF

@tool
def parse_pdf_to_structured(doc_path: str) -> Dict[str, Any]:
    """将PDF解析为带结构化元数据的JSON"""
    doc = fitz.open(doc_path)
    structured_data = {
        "doc_id": f"D-{hash(doc_path) % 10000}",
        "pages": [],
        "sections": [],
        "tables": []
    }
    
    # 遍历每页做布局分析
    for page_num in range(len(doc)):
        page = doc[page_num]
        blocks = page.get_text("dict")["blocks"]
        
        # 步骤1：坐标聚类识别标题/正文区域
        y_coords = [b["bbox"][1] for b in blocks if "lines" in b]
        title_region = detect_title_region(y_coords)  # 自定义函数
        
        # 步骤2：语义分类（调用微调BERT模型）
        for block in blocks:
            if "lines" not in block:
                continue
            text = " ".join([span["text"] for line in block["lines"] for span in line["spans"]])
            label = semantic_classifier.predict(text, block["bbox"])
            
            if label == "TABLE_CELL":
                # 步骤3：表格还原
                table_data = reconstruct_table(block, page)
                structured_data["tables"].append(table_data)
            elif label in ["TITLE", "SUBTITLE"]:
                structured_data["sections"].append({
                    "title": text,
                    "level": get_heading_level(text),
                    "page": page_num + 1
                })
    
    return structured_data

提示：Parser Agent的性能瓶颈常在OCR。我们实测发现，对A4尺寸扫描件，Tesseract 5.3的CPU模式耗时约8秒/页，而启用GPU加速（通过tesserocr）可降至1.2秒/页。但要注意：GPU版对中文支持不稳定，生产环境建议用CPU模式+预处理（二值化+去噪）提升准确率。

3.2 Query Router Agent：从自然语言到可执行任务的翻译器

Router Agent的核心能力是 意图解构 ，而非简单关键词匹配。它用两阶段模型完成翻译：

阶段一：粗粒度分类
用Sentence-BERT计算用户问题与预设模板的相似度。模板库包含：

• Fact模板：“XX在YY文档中的定义是什么？”、“ZZ参数的值是多少？”
• Compare模板：“对比A和B在XX方面的差异”、“哪个文档提到了YY技术？”
• Impact模板：“如果采用XX方案，会对YY产生什么影响？”、“XX变更需要修改哪些配置？”

我们不训练大模型，而是用 all-MiniLM-L6-v2 模型在1000条真实业务问题上微调，使分类准确率达92.4%（测试集）。关键技巧是：对每个模板，生成10个语义等价变体（如“XX的数值”、“XX是多少”、“XX的具体值”），避免模型死记硬背。

阶段二：细粒度任务生成
一旦确定为Compare类问题，Router启动规则引擎生成子任务。以问题“对比AWS/Azure/GCP的Kubernetes托管服务SLA”为例：

1. 先用NER模型识别实体： ["AWS", "Azure", "GCP", "Kubernetes", "SLA"]
2. 查知识库映射表，得到各云厂商文档ID： {"AWS": "D-042", "Azure": "D-089", "GCP": "D-133"}
3. 根据SLA术语的领域知识，确定需提取的字段： ["uptime_guarantee", "credit_policy", "exclusion_clauses"]
4. 组合生成任务列表：

[
  {"task_id": "T-001", "doc_id": "D-042", "field": "uptime_guarantee", "section_hint": "Service Level Agreement"},
  {"task_id": "T-002", "doc_id": "D-042", "field": "credit_policy", "section_hint": "Financial Credit"},
  {"task_id": "T-003", "doc_id": "D-089", "field": "uptime_guarantee", "section_hint": "SLA Terms"},
  ...
]

Router Agent的输出质量直接决定整个系统上限。我们加入两个防错机制：

• 字段存在性验证 ：对每个 field ，先查Parser已解析的文档结构，确认该字段在目标文档的章节标题或表格头中出现过（用BM25检索），否则报错 FieldNotFound 并建议用户换表述；
• 任务去重 ：用MD5哈希比对所有子任务的 (doc_id, field) 组合，避免重复调度。

注意：Router的 section_hint 不是可选参数。我们发现，当指定 "section_hint": "SLA Terms" 时，Fact Checker Agent的检索准确率比不指定时高37%，因为它能优先在匹配章节中搜索，大幅减少无关chunk干扰。

3.3 Fact Checker Agent：构建可信事实的三重验证体系

Checker Agent是RAGent的“守门人”，它用三重验证确保每个输出事实都经得起推敲：

验证层1：术语一致性校验
用WordNet和领域词典（如NIST网络安全术语库）构建术语图谱。当提取到“AES-256”时，Checker查图谱确认：

• 它属于 encryption_algorithm 类别（非 hash_function ）；
• 它的密钥长度属性应为 256-bit （非 256-byte ）；
• 它与 symmetric_key 存在 uses 关系。
  若发现矛盾（如某PDF称“AES-256 is a hash function”），自动标记为 TERMINOLOGY_CONFLICT 并跳过该条。

验证层2：语义等价性比对
对同一字段的不同表述，用Sentence-BERT计算向量相似度。阈值设定很关键：我们用200组人工标注的等价/不等价文本对（如“minimum 256 bits” vs “at least 256-bit”）做ROC分析，确定最佳阈值为0.89。低于此值，Checker会启动“语义澄清”子流程：调用LLM生成解释性句子（如“‘at least 256-bit’ means the key length must be 256 bits or longer”），再用BERT比对解释句与标准表述的相似度。

验证层3：来源可信度加权
并非所有PDF权重相同。Checker内置文档可信度评分：

• 官方白皮书（如AWS Well-Architected Framework）：权重1.0；
• 第三方分析报告：权重0.6；
• 博客文章/PPT：权重0.3。
  当多个文档给出冲突值时，按权重加权平均。例如：D-042（权重1.0）说“99.99%”，D-089（权重0.6）说“99.9%”，则综合值为 (99.99*1.0 + 99.9*0.6)/(1.0+0.6) = 99.96% 。

Checker的输出永远包含完整的证据链。以下是一个典型输出示例：

{
  "field": "uptime_guarantee",
  "values": [
    {
      "value": "99.99%",
      "source": [
        {"doc_id": "D-042", "page": 42, "text_snippet": "The SLA guarantees 99.99% uptime..."},
        {"doc_id": "D-133", "page": 18, "text_snippet": "Uptime commitment: 99.99% (four nines)"}
      ],
      "confidence": 0.98,
      "verification_steps": ["TERMINOLOGY_OK", "SEMANTIC_EQUIVALENT", "SOURCE_WEIGHTED"]
    }
  ]
}

实操心得：Checker的验证耗时占整个流程40%，但我们宁可慢也要准。曾有个客户用它查医疗设备合规文档，发现两份PDF对“数据保留期限”的表述冲突（3年 vs 5年），Checker不仅标出冲突，还根据发布日期（2023版 vs 2021版）建议采用新版，避免了合规风险。这种价值，远超速度带来的收益。

3.4 Synthesizer Agent：从碎片信息到人类可读结论的炼金术

Synthesizer不是简单的文本生成器，它是 信息压缩与叙事重构引擎 。它用三步法完成转化：

步骤1：结构化填充
根据Router生成的任务类型，加载预设模板。Compare类模板长这样：

| 云厂商 | Uptime Guarantee | Credit Policy | Exclusion Clauses |
|---------|------------------|---------------|-------------------|
| {aws_uptime} | {aws_credit} | {aws_exclusion} |
| {azure_uptime} | {azure_credit} | {azure_exclusion} |

Synthesizer从Checker的输出中提取对应字段值，填入模板。关键点：每个占位符后自动追加来源标注，如 {aws_uptime} 被替换为 99.99% <sup>[D-042,p42]</sup> 。

步骤2：冲突消解与注释生成
当发现字段值冲突（如AWS写“99.99%”，Azure写“99.95%”），Synthesizer不隐藏差异，而是在表格下方添加注释区块：

> **差异说明**：AWS承诺99.99%（D-042,p42），Azure承诺99.95%（D-089,p33）。差异源于AWS包含网络层SLA，Azure仅计算应用层。

这个注释不是LLM自由发挥，而是用规则引擎匹配预设的差异模式库（如“数值差<0.1%且文档类型不同”触发“计算范围差异”模板）。

步骤3：技术转译
对非技术用户，Synthesizer提供“通俗版”按钮。点击后，它用另一个LLM（专为此微调）将技术结论转译：

• 原句：“AWS EKS SLA为99.99%，Azure AKS为99.95%”
• 转译：“AWS的服务更稳定些，全年可能少宕机约21分钟，Azure则可能多宕机约4分钟——对银行核心交易系统，这个差异很关键。”

Synthesizer的代码核心是模板引擎与规则库的结合：

def generate_synthesis(checker_output: dict, task_type: str) -> str:
    if task_type == "Compare":
        template = load_template("compare_table.md")
        # 填充模板
        filled = template.render(**extract_values(checker_output))
        # 添加冲突注释
        if has_conflict(checker_output):
            conflict_note = generate_conflict_note(checker_output)
            filled += f"\n{conflict_note}"
        # 添加来源标注
        filled = add_source_citations(filled, checker_output)
        return filled
    # 其他task_type处理...

注意事项：Synthesizer必须禁用“自由发挥”模式。我们强制所有输出基于Checker的 values 数组，禁止LLM生成未验证的新信息。上线前做过压力测试：当输入Checker的 confidence 字段被人为设为0.3时，Synthesizer会输出“数据可信度不足，无法生成结论”，而不是瞎猜——这是专业性的底线。

4. 端到端实操部署与性能调优

4.1 环境搭建与依赖版本锁定

RAGent对依赖版本极其敏感，一个微小的升级就可能导致解析失败。我们固化了生产环境栈：

安装命令必须严格按顺序执行（注意 --force-reinstall ）：

# 创建干净环境
python -m venv ragenv
source ragenv/bin/activate  # Linux/Mac
# ragenv\Scripts\activate  # Windows

# 按顺序安装（顺序即依赖链）
pip install --force-reinstall "pymupdf==1.23.24"
pip install --force-reinstall "tesseract==5.3.3"
pip install --force-reinstall "langchain==0.1.16"
pip install --force-reinstall "langgraph==0.1.13"
pip install --force-reinstall "sentence-transformers==2.2.2"

提示：不要用 pip install -r requirements.txt 一键安装。我们吃过亏——某次更新requirements.txt时，LangChain版本写成 >=0.1.16 ，CI自动装了0.1.18，结果Router Agent的路由规则全部失效。现在所有生产环境都用 pip install --force-reinstall 显式指定版本。

4.2 PDF解析性能优化：从30秒/页到1.8秒/页

Parser Agent的耗时占全流程70%，我们通过四层优化将其压到极致：

优化层1：预处理流水线
对扫描件PDF，增加轻量预处理：

• 二值化：用OpenCV的Otsu算法自动确定阈值，比固定阈值准确率高22%；
• 去噪：用非局部均值去噪（cv2.fastN12MeansDenoisingColored），比高斯模糊保留更多文字边缘；
• 分辨率归一化：统一缩放到300dpi，避免Tesseract在过高分辨率下过度分割字符。

预处理代码（集成在Parser Agent中）：

import cv2
import numpy as np

def preprocess_scan_page(page_image: np.ndarray) -> np.ndarray:
    # 转灰度
    gray = cv2.cvtColor(page_image, cv2.COLOR_BGR2GRAY)
    # Otsu二值化
    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    # 非局部均值去噪
    denoised = cv2.fastN12MeansDenoising(binary, None, 10, 7, 21)
    return denoised

优化层2：OCR并行化
Tesseract默认单线程。我们用 concurrent.futures.ProcessPoolExecutor 启动4个进程，每个进程处理一页。关键技巧：进程间不共享Tesseract实例（会崩溃），而是每个进程初始化独立实例。实测4核CPU下，10页扫描件从42秒降至11.3秒。

优化层3：缓存策略
对已解析过的PDF，用SHA256哈希值作键，缓存结构化结果到SQLite数据库。缓存命中时，Parser Agent直接返回JSON，耗时从秒级降至毫秒级。缓存表结构：

CREATE TABLE pdf_cache (
    doc_hash TEXT PRIMARY KEY,
    parsed_json TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

优化层4：增量解析
当用户新增一份PDF，RAGent不全量重跑，而是用 git diff 式算法：先计算新PDF与已有PDF的文本相似度（用MinHash），若>0.8，则只解析差异部分（如新增的附录章节）。我们用这个策略处理某客户每月更新的200页合规手册，月度更新耗时从38分钟降至4.2分钟。

4.3 多Agent协同调试：用LangGraph可视化追踪每一帧状态

调试多Agent系统最怕“黑箱”。LangGraph自带的 get_graph().draw_mermaid_png() 能生成流程图，但不够细。我们开发了状态快照工具：

def log_state_snapshot(state: RAGentState, step_name: str):
    """记录每步执行后的状态快照"""
    snapshot = {
        "timestamp": datetime.now().isoformat(),
        "step": step_name,
        "state_summary": {
            "query_len": len(state["query"]),
            "parsed_docs_count": len(state["parsed_docs"]),
            "routed_tasks_count": len(state["routed_tasks"]),
            "fact_checks_count": len(state["fact_checks"]),
        },
        "state_sample": {k: v[:100] if isinstance(v, str) else v 
                        for k, v in state.items() if k != "error_log"}
    }
    # 写入日志文件，供ELK分析
    with open("ragent_debug.log", "a") as f:
        f.write(json.dumps(snapshot) + "\n")

配合Kibana仪表盘，我们可以实时看到：

• 每个Agent的平均执行时间（Parser常驻2.1s，Checker波动大，在0.8~5.3s）；
• error_log 字段的高频错误（如 FieldNotFound 集中在Router， TERMINOLOGY_CONFLICT 集中在Checker）；
• 状态字段的异常值（如 routed_tasks 为空但 query 非空，说明Router故障）。

一次真实调试案例：Synthesizer输出总是空。通过快照发现 fact_checks 字段为空，再查上一步快照，发现 routed_tasks 里的 field 值是 "uptime" ，但Checker的术语词典里只有 "uptime_guarantee" 。根源是Router的NER模型把“uptime”识别为独立词，没补全为“uptime_guarantee”。解决方案：在Router输出后加一道规则校验，对常见字段名做标准化映射（ "uptime" → "uptime_guarantee" ）。

4.4 生产环境部署：Docker容器化与资源隔离

RAGent必须隔离GPU资源（给Tesseract OCR）和CPU资源（给LLM推理）。我们用Docker Compose实现：

version: '3.8'
services:
  ragent-api:
    build: .
    ports: ["8000:8000"]
    environment:
      - LANGCHAIN_API_KEY=${LANGCHAIN_API_KEY}
      - TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
    volumes:
      - ./pdf_cache:/app/pdf_cache
      - ./logs:/app/logs
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G

  tesseract-gpu:
    image: tesseract-gpu:5.3.3
    devices:
      - /dev/nvidia0:/dev/nvidia0
    volumes:
      - ./tessdata:/usr/share/tesseract-ocr/4.00/tessdata
    command: tail -f /dev/null

关键配置说明：

• tesseract-gpu 容器独占一块GPU，避免与其他服务争抢；
• ragent-api 容器限制2核CPU/4G内存，防止OOM；
• pdf_cache 卷挂载到宿主机，保证重启后缓存不丢失；
• 日志卷 ./logs 用于集中收集快照日志。

实操心得：在K8s集群部署时，务必给 tesseract-gpu Pod设置 nvidia.com/gpu: 1 资源请求，并配置 nodeSelector 指向GPU节点。我们曾因忘记这步，导致OCR任务在CPU节点上排队，平均延迟飙升至47秒。

5. 常见问题与实战排障指南

5.1 解析失败类问题：为什么我的PDF总显示“空内容”？

这是新手最高频问题，90%源于PDF类型误判。RAGent内部有PDF类型检测器，但有时会出错。排查路径如下：

第一步：确认PDF物理类型
用命令行快速诊断：

# 查看PDF是否为扫描件（含图像）
pdfinfo your_file.pdf | grep "Pages\|Encrypted"
# 若输出"Pages: 1"且无"Page size"，很可能是单页扫描件
# 用ImageMagick检查是否含图像
identify -format "%m %w %h %d\n" your_file.pdf
# 输出类似"PNG 2480 3508 72"，证明是图像PDF

第二步：检查Parser日志
在 ragent_debug.log 中搜索 Parser failed ，常见错误码及对策：

第三步：强制指定解析模式
在调用Parser Agent时，传入 mode 参数：

parse_pdf_to_structured.invoke({
    "doc_path": "manual.pdf",
    "mode": "scan"  # 可选: "native"（原生文本PDF）, "scan"（扫描件）, "hybrid"（混合）
})

hybrid 模式会先尝试 native ，失败后自动切 scan ，但耗时增加40%。

注意：别迷信“自动检测”。我处理过一份PDF，前10页是原生文本，后5页是扫描件附录。自动检测只按第一页判断，导致附录解析失败。解决方案：手动分拆PDF，对附录单独用 mode="scan" 。

5.2 路由错误类问题：为什么Router总把比较题当成事实题？

这暴露了Router Agent的意图识别盲区。典型现象：用户问“对比A和B的API限流策略”，Router却生成单个任务 {"field": "api_rate_limit"} ，没拆出A/B