http-client模型调用另外一台机器部署的VLM，偶发httpx.ReadError

[zzk2021]

🔎 Search before asking | 提交之前请先搜索

• I have searched the MinerU Readme and found no similar bug report.
• I have searched the MinerU Issues and found no similar bug report.
• I have searched the MinerU Discussions and found no similar bug report.

🤖 Consult the online AI assistant for assistance | 在线 AI 助手咨询

• I have consulted the online AI assistant but was unable to obtain a solution to the issue.

Description of the bug | 错误描述

生产中http-client模型调用另外一台机器部署的VLM。偶发这个错误，但是vllm端没看到任何ERROR。
并发量只有2

How to reproduce the bug | 如何复现

http-client模式

Operating System Mode | 操作系统类型

Linux

Operating System Version| 操作系统版本

CentOS 8

Python version | Python 版本

3.10

Software version | 软件版本 (mineru --version)

>=2.5

Backend name | 解析后端

vlm

Device mode | 设备模式

cuda

[dosubot[bot]]

你遇到的 httpx.ReadError 在 MinerU 的 vlm-http-client 模式下是一个已知问题，主要原因是批量处理时只要有一页（比如 404、500、503）失败，整个 batch 就会异常终止，客户端收到 ReadError，即使并发量很低也会发生。这通常和 MinerU 的批量异步处理机制有关，任何单页失败都会导致全局失败，且 doc_analyze 会一次性加载所有页和推理结果到内存，容易触发资源瓶颈或网络异常，即使 GPU/内存未满也可能出现这种情况[详细分析][相关讨论]。

常见排查和缓解建议如下：

1. 升级 MinerU 及依赖：建议 MinerU 升级到 >=2.6.6，mineru_vl_utils >=0.1.7，vllm >=0.10.2，确保 client/server 版本和环境变量（如 VLLM_USE_V1）一致，避免接口不兼容导致的远程调用失败[版本建议]。
2. 优化参数：尝试提升 http_timeout（如 1800 秒）、max_retries（如 5），但注意 404 这类硬错误重试无效。max_concurrency 建议根据实际资源适当调低[参数说明]。
3. 代码层容错：推荐将大文档拆分为单页或小批量循环处理，每页用 try/except 捕获异常，跳过失败页，避免因单页失败导致全局失败。示例代码：

   results = []
   for page_id in range(total_pages):
       try:
           md = pdf_to_md(
               pdf_path,
               backend="vlm-http-client",
               server_url=server_url,
               start_page_id=page_id,
               end_page_id=page_id,
               max_retries=3,
           )
           results.append(md)
       except Exception as e:
           logger.warning(f"Page {page_id} failed: {e}")
           results.append(None)

   [代码示例]
4. 避免多线程并发：pypdfium2 不是线程安全的，建议用多进程并发，避免资源泄漏或崩溃[并发建议]。
5. 检查网络和代理：如果 VLM 端无报错但客户端报错，需排查中间网络、代理、防火墙等是否有 silent drop 或拦截，部分 404 可能是中间件返回的，vllm 本身不会返回 404[网络排查]。
6. 监控资源：用 free -h、lsof、dmesg、nvidia-smi 等监控内存、文件句柄、网络连接，排查资源泄漏或限制。
7. 定期重启服务：长时间高并发或大文档处理后，mineru-api 可能未及时释放资源，定期重启可彻底释放 GPU/内存。

如果 vlm-http-client 后端依然不稳定，可以考虑切换到 pipeline 后端，容错性更好，适合大文档或高并发场景[后端建议]。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[zzk2021]

http_timeout之类的我已经调整过了，如果超时是timeout错误，主要问题在于vllm端没看到任何错误，如何确定是单页失败？

[dosubot[bot]]

你遇到的 httpx.ReadError 在 MinerU 的 vlm-http-client 批量模式下，是因为只要有单页（比如 404、500、503）失败，整个 batch 就会异常终止，客户端收到 ReadError，但 vllm 端通常没有任何报错，因为很多 404/断连其实是中间代理或防火墙返回的，不是 vllm 本身的问题参考。

MinerU 目前没有内置单页失败的详细日志或定位机制，批量模式下只要有一页失败就整体失败，无法直接知道是哪一页出错参考。要定位单页失败，建议把文档拆成单页或小批量循环处理，每页用 try/except 包裹，记录具体哪一页异常。例如：

results = []
for page_id in range(total_pages):
    try:
        md = pdf_to_md(
            pdf_path,
            backend="vlm-http-client",
            server_url=server_url,
            start_page_id=page_id,
            end_page_id=page_id,
            max_retries=3,
        )
        results.append(md)
    except Exception as e:
        logger.warning(f"Page {page_id} failed: {e}")
        results.append(None)

这样可以直接看到是哪些页失败，哪些页正常，避免整体失败参考。

如果你已经调高了 http_timeout 和 max_retries，但依然有 ReadError，建议：

• 检查网络链路、中间代理、防火墙是否有 silent drop 或 404 拦截（vllm 本身不会返回 404）；
• 升级 MinerU 到 >=2.6.6、mineru_vl_utils >=0.1.7、vllm >=0.10.2；
• 多进程并发（pypdfium2 不是线程安全的）；
• 监控内存、文件句柄、网络连接等资源瓶颈；
• 如果 vlm-http-client 依然不稳定，可以考虑切换 pipeline 后端，容错性更好参考。

如需更细致的代码改造或日志分析，可以补充你的调用方式。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[dosubot[bot]]

在 MinerU 的 vlm-http-client 批量模式下，只要有一页（比如 404、500、503）失败，整个 batch 就会直接抛出异常，客户端收到 httpx.ReadError，但 MinerU 本身没有内置单页失败的详细日志或定位机制，服务端通常也不会有报错（404 很可能是中间代理/防火墙返回的）参考。

要确认是否是单页失败导致，可以用如下方式定位：

1. 单页循环处理：将大文档拆成单页或小批量，逐页用 try/except 包裹，记录每一页的异常。这样能直接看到是哪些页失败，哪些页正常，避免全局失败。例如：

   results = []
   for page_id in range(total_pages):
       try:
           md = pdf_to_md(
               pdf_path,
               backend="vlm-http-client",
               server_url=server_url,
               start_page_id=page_id,
               end_page_id=page_id,
               max_retries=3,
           )
           results.append(md)
       except Exception as e:
           logger.warning(f"Page {page_id} failed: {e}")
           results.append(None)

   这样可以明确看到是哪些页导致异常，确认是否为单页问题参考。

2. 检查网络链路：如果服务端无报错但客户端报错，常见原因是中间网络、代理或防火墙 silent drop 或返回 404，vllm 本身不会返回 404。建议抓包或排查中间件。

3. 日志与版本：MinerU 本身没有 per-page 级别的 debug/verbose 日志，批量模式下出错只能看到整体失败。升级到 MinerU >=2.6.6、mineru_vl_utils >=0.1.7、vllm >=0.10.2 可提升稳定性，但单页失败定位仍需用上述代码方式。

总结：MinerU 批量模式下没有内置单页失败检测，需用循环单页处理+异常捕获来定位具体失败页参考。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}