MinerU 4.x API 适配修复文档解析 404 导致的上传失败适用场景自建知识库 / RAG 项目调用本地 MinerU 解析服务上传 PDF/Word 报错服务端日志出现POST /file_parse HTTP/1.1 404 Not Found。根因是 MinerU 4.0 重写了 API 契约本文给出定位方法和适配代码。一、问题现象上传 Word 文档接口返回 500应用日志报“文件上传失败”。同时 MinerU 服务终端出现INFO: 127.0.0.1:xxxxx - POST /file_parse HTTP/1.1 404 Not Found请求发出去了但服务端没有这个路由。二、根因API 契约被大版本更换MinerU 4.0 对 API 做了整体重写旧版 2.x 的同步解析契约已下线项旧版 2.x应用按此编写新版 4.x服务实际提供路由POST /file_parsePOST /v1/file_parse参数形式multipart 表单参数query 参数 JSON/multipartZIP 输出表单参数response_format_ziptruequery 参数response_formatzip解析档位表单参数backendpipelinequery 参数tierflash/basic/standard/advanced其他参数return_images/return_model_output/return_middle_json已废弃不再支持认证无业务接口声明 Bearer本地部署通常未强制注意这不是装错了包。官方mineru 4.0.12自身就是这套新契约把服务换成官方新版同样没有/file_parse。三、自查确认服务端的真实契约不要凭记忆猜接口有 Swagger 的服务直接抓规范curl-shttp://localhost:8000/openapi.json|jq.paths | keys输出中能看到/v1/file_parse、/v1/parse/jobs、/v1/uploads等路由没有/file_parse即可确认契约版本。四、修复代码文件src/main/java/know/engine/document/service/impl/MinerUProcessBaseServiceImpl.java方法parseDocumentToZip(String fileName, InputStream fileStream)修改前2.x 契约StringurlfileParseApiUrl/file_parse;HttpPosthttpPostnewHttpPost(url);httpPost.setHeader(Accept,application/json);HttpEntitymultipartEntityMultipartEntityBuilder.create().setCharset(StandardCharsets.UTF_8).addBinaryBody(files,fileStream,ContentType.APPLICATION_OCTET_STREAM,fileName).addTextBody(backend,pipeline).addTextBody(response_format_zip,true).addTextBody(return_images,true).addTextBody(return_model_output,false).addTextBody(return_middle_json,false).build();修改后4.x 契约// MinerU 4.x 新契约路由为 /v1/file_parse旧版 2.x 的 /file_parse 已下线// ZIP 输出通过 query 参数控制response_formatzip 返回 ZIP 字节流// wait_timeout 设为 280s略小于客户端响应超时默认 300s// 避免服务端还在等待而客户端已断开超时服务端会返回 202按失败处理StringurlfileParseApiUrl/v1/file_parse?response_formatzipwait_timeout280;HttpPosthttpPostnewHttpPost(url);httpPost.setHeader(Accept,application/zip);// 4.x 的 multipart 只需 files 二进制字段// 旧版的 backend / response_format_zip / return_images 等表单参数已废弃HttpEntitymultipartEntityMultipartEntityBuilder.create().setCharset(StandardCharsets.UTF_8).addBinaryBody(files,fileStream,ContentType.APPLICATION_OCTET_STREAM,fileName).build();改动点共五处路由/file_parse→/v1/file_parseZIP 输出控制表单参数response_format_ziptrue→ query 参数response_formatzip新增wait_timeout280服务端默认等待 300s与客户端超时相同会导致两边同时断开280s 让服务端先超时并返回明确状态删除backend/return_images/return_model_output/return_middle_json四个废弃参数Accept头application/json→application/zip响应处理逻辑无需改动仍判断statusCode 200后读取响应体为 ZIP 字节流后续解压、提取 markdown、上传对象存储的流程不变。服务端地址配置application.yml无需改动列出供对照file:parse:api:url:http://localhost:8000五、验证重启应用后上传一个 PDF/Word观察两侧日志MinerU 终端应出现POST /v1/file_parse HTTP/1.1 200 OK应用日志出现“文件解析接口调用成功ZIP 文件大小: xxxxx bytes”文档状态进入后续分块、向量化流程六、注意事项首次解析会下载模型权重数 GB服务端可能长时间无输出属正常现象不要中断新契约业务接口声明了 Bearer 认证本地部署通常未强制若返回 401/403需在请求头加Authorization: Bearer key解析耗时超过wait_timeout时服务端返回 202此时需改用异步轮询POST /v1/parse/jobs 查询任务状态本文的同步方案适用于可在一个超时周期内完成的文档排查同类问题的通用方法抓openapi.json对账不凭记忆猜接口——大版本升级换路由是高频事故七、 完整方法直接替换即可文件src/main/java/know/engine/document/service/impl/MinerUProcessBaseServiceImpl.java方法parseDocumentToZip(String fileName, InputStream fileStream)/** * 调用文件解析接口获取 ZIP 格式响应 * 使用 Apache HttpClient 5支持流式下载大文件 * * param fileName 文件名 * param fileStream 文件输入流 * return ZIP 文件字节数组 */privatebyte[]parseDocumentToZip(StringfileName,InputStreamfileStream){// MinerU 4.x 新契约路由为 /v1/file_parse旧版 2.x 的 /file_parse 已下线// ZIP 输出通过 query 参数控制response_formatzip 返回 ZIP 字节流// wait_timeout 设为 280s略小于客户端响应超时默认 300s// 避免服务端还在等待而客户端已断开超时服务端会返回 202下方按失败处理并提示StringurlfileParseApiUrl/v1/file_parse?response_formatzipwait_timeout280;// 配置请求超时RequestConfigrequestConfigRequestConfig.custom().setConnectionRequestTimeout(Timeout.ofMilliseconds(connectTimeout)).setResponseTimeout(Timeout.ofMilliseconds(responseTimeout)).build();try(CloseableHttpClienthttpClientHttpClients.custom().setDefaultRequestConfig(requestConfig).build()){HttpPosthttpPostnewHttpPost(url);httpPost.setHeader(Accept,application/zip);// 4.x 的 multipart 只需 files 二进制字段// 旧版的 backend / response_format_zip / return_images 等表单参数已废弃传了也会被忽略HttpEntitymultipartEntityMultipartEntityBuilder.create().setCharset(StandardCharsets.UTF_8).addBinaryBody(files,fileStream,org.apache.hc.core5.http.ContentType.APPLICATION_OCTET_STREAM,fileName).build();httpPost.setEntity(multipartEntity);log.info(开始调用文件解析接口ZIP 模式: {},url);try(CloseableHttpResponseresponsehttpClient.execute(httpPost)){intstatusCoderesponse.getCode();log.info(文件解析接口响应状态码: {},statusCode);HttpEntityresponseEntityresponse.getEntity();if(statusCode200responseEntity!null){// 读取响应体为字节数组ZIP 文件byte[]zipBytesEntityUtils.toByteArray(responseEntity);log.info(文件解析接口调用成功ZIP 文件大小: {} bytes,zipBytes.length);returnzipBytes;}else{StringresponseBodyresponseEntity!null?EntityUtils.toString(responseEntity,UTF-8):;log.error(文件解析接口调用失败状态码: {}, 响应: {},statusCode,responseBody);thrownewRuntimeException(文件解析接口调用失败: HTTP statusCode, responseBody);}}}catch(Exceptione){log.error(调用文件解析接口异常,e);thrownewRuntimeException(调用文件解析接口失败: e.getMessage(),e);}finally{closeQuietly(fileStream);}}