PDF 解析超时问题：根因分析与修复方案

问题概述

用户上传 01_MetaGPT.pdf 后，系统未能成功解析文件内容，前端向用户返回了"请求超时（Request timed out）"的错误提示。经过日志分析与代码审查，问题根因已定位并修复。

---

日志回放：问题发生的完整链路

以下为服务端日志中截取的关键事件时间线（UTC+8）：

时间戳	事件
17:09:13	PyMuPDF4LLMLoader 开始解析 tmpibpf8wm1.pdf（多模态模式）
17:09:35	OpenAI /chat/completions 第一次重试（距开始 ~22s）
17:09:57	OpenAI /chat/completions 第二次重试（距上次 ~22s）
17:10:19	提取失败：Request timed out.（总耗时 ~66s）
17:10:19	中间件注入 PDF 上下文，仅 144 个字符

最终注入到 Agent 对话上下文的"PDF 内容"只有一行错误信息：

PDF文件处理出错: Request timed out.

由于 Agent 拿不到任何有效的 PDF 文本，只能告知用户"无法读取该 PDF 的具体内容"。

---

根因分析

原因一：多模态图片解析调用了外部视觉模型 API

配置证据 （.env 文件）：

环境变量	值
ENABLE_PDF_MULTIMODAL	true
VISION_MODEL	gpt-4o
VISION_BASE_URL	https://api.openai.com/v1

当 ENABLE_PDF_MULTIMODAL=true 时，PDF 解析走的是带图片提取的多模态路径：

PyMuPDF4LLMLoader(
    file_path,
    mode="single",
    extract_images=True,          # 提取 PDF 中所有图片
    images_parser=image_parser,   # 对每张图片调用 GPT-4o 进行描述
    table_strategy="lines"
)

LLMImageBlobParser 会将 PDF 中提取到的每一张图片逐个发送给视觉模型 API（此处为 GPT-4o），生成文字描述后嵌入最终的 Markdown 文本。如果 PDF 包含较多图片，或图片体积较大，API 调用会非常耗时。

原因二：视觉模型未配置超时限制

src/app/core/llms.py 中创建 image_llm_model 的代码没有设置 timeout 和 max_retries 参数：

# 修复前
return ChatOpenAI(
    base_url=settings.vision_base_url,
    api_key=settings.vision_api_key,
    model=settings.vision_model,
    # ❌ 没有 timeout 参数，OpenAI SDK 默认无限等待
    # ❌ 没有 max_retries 参数，SDK 使用默认重试策略（2 次）
)

OpenAI Python SDK 默认不设超时上限，每次 API 调用会无限等待直到 TCP 层面的超时。从日志看，每次重试间隔约 22 秒（SDK 内置的指数退避），两次重试后才彻底放弃，整个过程耗时超过 1 分钟。

原因三：没有降级回退机制

这是最核心的问题 。即使 LLMImageBlobParser 的 API 调用超时了，PDF 中仍然有大量可提取的纯文本、表格和结构信息。然而原代码在异常发生时直接返回错误信息，没有任何回退逻辑：

# 修复前 ------ 异常直接穿透，文本也丢了
try:
    loader = _create_loader(temp_file_path)
    text_content = _extract_text_from_loader(loader)  # 内部调用 GPT-4o 超时
except Exception as e:
    logger.error(f"PDF文本提取失败: {e}")
    return f"PDF文件处理出错: {str(e)}"  # ❌ 仅返回了错误信息

一句话总结：PDF 的文本内容被外部视觉 API 的稳定性"挟持"了------图片描述失败，整篇 PDF 的文本提取也跟着失败。

---

修复方案（共三处改动）

修复 1：为视觉模型添加超时与重试控制

文件： src/app/core/llms.py

# 修复后
return ChatOpenAI(
    base_url=settings.vision_base_url,
    api_key=settings.vision_api_key,
    model=settings.vision_model,
    timeout=120,       # ✅ 每次 API 调用最多等待 120 秒
    max_retries=2,     # ✅ 明确控制重试次数，避免无限等待
)

参数	作用
timeout=120	单次 API 调用超时 120 秒。超时后立即抛出异常，不再等待
max_retries=2	失败后最多重试 2 次。加上初始请求共 3 次尝试

这意味着最坏情况下的等待时间从不确定 变为 ~360 秒（3 × 120s）。更关键的是------它可以触发修复 3 中的回退机制。

修复 2：校验视觉模型可用性

文件： src/processors/pdf.py ------ _create_loader() 函数

# 修复后
def _create_loader(file_path: str) -> PyMuPDF4LLMLoader:
    if settings.enable_pdf_multimodal and image_llm_model is not None:
        # 多模态路径：提取图片并用 GPT-4o 描述
        ...
        return PyMuPDF4LLMLoader(..., extract_images=True, images_parser=image_parser, ...)
    if settings.enable_pdf_multimodal and image_llm_model is None:
        logger.warning("enable_pdf_multimodal=True 但 image_llm_model 未初始化，回退到纯文本模式")
    # 纯文本路径：不提取图片，不调视觉 API
    return PyMuPDF4LLMLoader(file_path, mode="single", table_strategy="lines")

原代码只判断了 settings.enable_pdf_multimodal 的布尔值，没有检查 image_llm_model 模块变量是否为 None（当 VISION_API_KEY 未设置时，create_image_model() 返回 None）。如果开启多模态但模型未初始化，会直接触发 AttributeError。修复后，这种情况会优雅降级为纯文本解析。

修复 3：多模态失败后自动降级到纯文本模式（核心修复）

文件： src/processors/pdf.py ------ extract_pdf_text() 和 extract_pdf_text_from_file() 两个函数

# 修复后
try:
    loader = _create_loader(temp_file_path)
    try:
        text_content = _extract_text_from_loader(loader)
        if text_content.startswith("PDF文件处理出错"):
            raise RuntimeError(text_content)
    except Exception:
        # ✅ 关键回退：多模态失败 → 切换为纯文本模式重试
        if settings.enable_pdf_multimodal and image_llm_model is not None:
            logger.warning("多模态 PDF 解析失败，回退到纯文本模式重试...")
            fallback_loader = PyMuPDF4LLMLoader(
                temp_file_path,
                mode="single",
                table_strategy="lines"     # 不提取图片，不走视觉 API
            )
            text_content = _extract_text_from_loader(fallback_loader)
        else:
            raise

执行流程：
#mermaid-svg-zH30ymx9NxoMSl0I{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zH30ymx9NxoMSl0I .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zH30ymx9NxoMSl0I .error-icon{fill:#552222;}#mermaid-svg-zH30ymx9NxoMSl0I .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zH30ymx9NxoMSl0I .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zH30ymx9NxoMSl0I .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zH30ymx9NxoMSl0I .marker.cross{stroke:#333333;}#mermaid-svg-zH30ymx9NxoMSl0I svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zH30ymx9NxoMSl0I p{margin:0;}#mermaid-svg-zH30ymx9NxoMSl0I .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-zH30ymx9NxoMSl0I .cluster-label text{fill:#333;}#mermaid-svg-zH30ymx9NxoMSl0I .cluster-label span{color:#333;}#mermaid-svg-zH30ymx9NxoMSl0I .cluster-label span p{background-color:transparent;}#mermaid-svg-zH30ymx9NxoMSl0I .label text,#mermaid-svg-zH30ymx9NxoMSl0I span{fill:#333;color:#333;}#mermaid-svg-zH30ymx9NxoMSl0I .node rect,#mermaid-svg-zH30ymx9NxoMSl0I .node circle,#mermaid-svg-zH30ymx9NxoMSl0I .node ellipse,#mermaid-svg-zH30ymx9NxoMSl0I .node polygon,#mermaid-svg-zH30ymx9NxoMSl0I .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zH30ymx9NxoMSl0I .rough-node .label text,#mermaid-svg-zH30ymx9NxoMSl0I .node .label text,#mermaid-svg-zH30ymx9NxoMSl0I .image-shape .label,#mermaid-svg-zH30ymx9NxoMSl0I .icon-shape .label{text-anchor:middle;}#mermaid-svg-zH30ymx9NxoMSl0I .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zH30ymx9NxoMSl0I .rough-node .label,#mermaid-svg-zH30ymx9NxoMSl0I .node .label,#mermaid-svg-zH30ymx9NxoMSl0I .image-shape .label,#mermaid-svg-zH30ymx9NxoMSl0I .icon-shape .label{text-align:center;}#mermaid-svg-zH30ymx9NxoMSl0I .node.clickable{cursor:pointer;}#mermaid-svg-zH30ymx9NxoMSl0I .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zH30ymx9NxoMSl0I .arrowheadPath{fill:#333333;}#mermaid-svg-zH30ymx9NxoMSl0I .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zH30ymx9NxoMSl0I .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zH30ymx9NxoMSl0I .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zH30ymx9NxoMSl0I .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zH30ymx9NxoMSl0I .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zH30ymx9NxoMSl0I .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zH30ymx9NxoMSl0I .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zH30ymx9NxoMSl0I .cluster text{fill:#333;}#mermaid-svg-zH30ymx9NxoMSl0I .cluster span{color:#333;}#mermaid-svg-zH30ymx9NxoMSl0I div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zH30ymx9NxoMSl0I .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zH30ymx9NxoMSl0I rect.text{fill:none;stroke-width:0;}#mermaid-svg-zH30ymx9NxoMSl0I .icon-shape,#mermaid-svg-zH30ymx9NxoMSl0I .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zH30ymx9NxoMSl0I .icon-shape p,#mermaid-svg-zH30ymx9NxoMSl0I .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zH30ymx9NxoMSl0I .icon-shape .label rect,#mermaid-svg-zH30ymx9NxoMSl0I .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zH30ymx9NxoMSl0I .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zH30ymx9NxoMSl0I .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zH30ymx9NxoMSl0I :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 成功 ✅
超时 ❌
用户上传 PDF
多模态解析（提取图片+GPT-4o）
返回完整内容（含图片描述）
自动切换纯文本模式重试
纯文本解析成功
仍失败→报错
返回文本+表格（无图片描述）
返回错误信息（仅此时报错）

这个设计的核心思想是：PDF 的文本提取不依赖外部 API 。PyMuPDF4LLM 即使不调用任何 LLM，也能从 PDF 中提取文字、表格和文档结构（Markdown 格式）。图片描述只是锦上添花，不应该成为阻塞点。

---

影响范围

组件	影响	状态
src/app/core/llms.py	image_llm_model 新增超时配置	✅ 已修复
src/processors/pdf.py	_create_loader() 增加模型空值校验	✅ 已修复
src/processors/pdf.py	extract_pdf_text() 增加回退逻辑	✅ 已修复
src/processors/pdf.py	extract_pdf_text_from_file() 增加回退逻辑	✅ 已修复
src/middleware/pdf_parser_middleware.py	无需修改（通过 PDFProcessor 间接受益）	---
src/app/agents/agent_all.py	无需修改（独立实现，走 pymupdf4llm 不调 API）	---

---

验证建议

1. 正常多模态场景：上传一张图文混排的 PDF，确认 GPT-4o 正常生成图片描述
2. 超时回退场景 （推荐模拟）：临时将 .env 中 VISION_BASE_URL 改为一个不可达地址（如 http://localhost:1），上传 PDF，观察日志中是否出现 "多模态 PDF 解析失败，回退到纯文本模式重试..." 警告，并确认 PDF 文本内容仍能正常提取
3. 关闭多模态场景 ：设 ENABLE_PDF_MULTIMODAL=false，确认 PDF 解析仅走纯文本路径，不产生任何 /chat/completions API 调用