问题概述用户上传01_MetaGPT.pdf后系统未能成功解析文件内容前端向用户返回了请求超时Request timed out的错误提示。经过日志分析与代码审查问题根因已定位并修复。日志回放问题发生的完整链路以下为服务端日志中截取的关键事件时间线UTC8时间戳事件17:09:13PyMuPDF4LLMLoader开始解析tmpibpf8wm1.pdf多模态模式17:09:35OpenAI/chat/completions第一次重试距开始 ~22s17:09:57OpenAI/chat/completions第二次重试距上次 ~22s17:10:19提取失败Request timed out.总耗时 ~66s17:10:19中间件注入 PDF 上下文仅 144 个字符最终注入到 Agent 对话上下文的PDF 内容只有一行错误信息PDF文件处理出错: Request timed out.由于 Agent 拿不到任何有效的 PDF 文本只能告知用户无法读取该 PDF 的具体内容。根因分析原因一多模态图片解析调用了外部视觉模型 API配置证据.env文件环境变量值ENABLE_PDF_MULTIMODALtrueVISION_MODELgpt-4oVISION_BASE_URLhttps://api.openai.com/v1当ENABLE_PDF_MULTIMODALtrue时PDF 解析走的是带图片提取的多模态路径PyMuPDF4LLMLoader(file_path,modesingle,extract_imagesTrue,# 提取 PDF 中所有图片images_parserimage_parser,# 对每张图片调用 GPT-4o 进行描述table_strategylines)LLMImageBlobParser会将 PDF 中提取到的每一张图片逐个发送给视觉模型 API此处为 GPT-4o生成文字描述后嵌入最终的 Markdown 文本。如果 PDF 包含较多图片或图片体积较大API 调用会非常耗时。原因二视觉模型未配置超时限制src/app/core/llms.py中创建image_llm_model的代码没有设置timeout和max_retries参数# 修复前returnChatOpenAI(base_urlsettings.vision_base_url,api_keysettings.vision_api_key,modelsettings.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 超时exceptExceptionase:logger.error(fPDF文本提取失败:{e})returnfPDF文件处理出错:{str(e)}# ❌ 仅返回了错误信息一句话总结PDF 的文本内容被外部视觉 API 的稳定性挟持了——图片描述失败整篇 PDF 的文本提取也跟着失败。修复方案共三处改动修复 1为视觉模型添加超时与重试控制文件src/app/core/llms.py# 修复后returnChatOpenAI(base_urlsettings.vision_base_url,api_keysettings.vision_api_key,modelsettings.vision_model,timeout120,# ✅ 每次 API 调用最多等待 120 秒max_retries2,# ✅ 明确控制重试次数避免无限等待)参数作用timeout120单次 API 调用超时 120 秒。超时后立即抛出异常不再等待max_retries2失败后最多重试 2 次。加上初始请求共 3 次尝试这意味着最坏情况下的等待时间从不确定变为~360 秒3 × 120s。更关键的是——它可以触发修复 3 中的回退机制。修复 2校验视觉模型可用性文件src/processors/pdf.py——_create_loader()函数# 修复后def_create_loader(file_path:str)-PyMuPDF4LLMLoader:ifsettings.enable_pdf_multimodalandimage_llm_modelisnotNone:# 多模态路径提取图片并用 GPT-4o 描述...returnPyMuPDF4LLMLoader(...,extract_imagesTrue,images_parserimage_parser,...)ifsettings.enable_pdf_multimodalandimage_llm_modelisNone:logger.warning(enable_pdf_multimodalTrue 但 image_llm_model 未初始化回退到纯文本模式)# 纯文本路径不提取图片不调视觉 APIreturnPyMuPDF4LLMLoader(file_path,modesingle,table_strategylines)原代码只判断了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)iftext_content.startswith(PDF文件处理出错):raiseRuntimeError(text_content)exceptException:# ✅ 关键回退多模态失败 → 切换为纯文本模式重试ifsettings.enable_pdf_multimodalandimage_llm_modelisnotNone:logger.warning(多模态 PDF 解析失败回退到纯文本模式重试...)fallback_loaderPyMuPDF4LLMLoader(temp_file_path,modesingle,table_strategylines# 不提取图片不走视觉 API)text_content_extract_text_from_loader(fallback_loader)else:raise执行流程成功 ✅超时 ❌用户上传 PDF多模态解析提取图片GPT-4o返回完整内容含图片描述自动切换纯文本模式重试纯文本解析成功仍失败→报错返回文本表格无图片描述返回错误信息仅此时报错这个设计的核心思想是PDF 的文本提取不依赖外部 API。PyMuPDF4LLM即使不调用任何 LLM也能从 PDF 中提取文字、表格和文档结构Markdown 格式。图片描述只是锦上添花不应该成为阻塞点。影响范围组件影响状态src/app/core/llms.pyimage_llm_model新增超时配置✅ 已修复src/processors/pdf.py_create_loader()增加模型空值校验✅ 已修复src/processors/pdf.pyextract_pdf_text()增加回退逻辑✅ 已修复src/processors/pdf.pyextract_pdf_text_from_file()增加回退逻辑✅ 已修复src/middleware/pdf_parser_middleware.py无需修改通过 PDFProcessor 间接受益—src/app/agents/agent_all.py无需修改独立实现走pymupdf4llm不调 API—验证建议正常多模态场景上传一张图文混排的 PDF确认 GPT-4o 正常生成图片描述超时回退场景推荐模拟临时将.env中VISION_BASE_URL改为一个不可达地址如http://localhost:1上传 PDF观察日志中是否出现多模态 PDF 解析失败回退到纯文本模式重试...警告并确认 PDF 文本内容仍能正常提取关闭多模态场景设ENABLE_PDF_MULTIMODALfalse确认 PDF 解析仅走纯文本路径不产生任何/chat/completionsAPI 调用