远程传输重试设计¶
问题:#99
目标¶
当重放安全时,使 v1 API 客户端中的瞬时传输故障可恢复,并将耗尽后的故障暴露为结构化传输错误,而不是 parse_failed。
重试边界¶
客户端仅在重放不会创建重复解析任务时重试请求:
- 重试用于健康检查、上传状态、任务轮询和输出下载的
GET请求。 - 使用相同的字节和请求头重试上传内容的
PUT。 - 在上传完成发生传输故障后,查询该上传。如果已完成,则返回其文件;如果仍处于待处理状态,则重试完成操作。
- 不要自动重试
POST /v1/parse/jobs。API 当前未提供幂等性契约,因此丢失的响应可能已经代表一个已创建且可计费的任务。
重试使用较小的有界指数延迟。HTTP 应用错误不属于传输重试;它们继续通过现有的结构化响应处理。
错误模型¶
分类使用异常类型,而不是消息匹配:
- 对于远程目标,
httpx.TimeoutException变为remote_timeout。 - 对于远程目标,其他耗尽的
httpx.TransportError实例变为remote_unreachable。 - 本地 API 目标保留面向 parse-server 的错误语义。
内部传输异常携带请求阶段,以便日志能够区分健康发现、上传创建、字节上传、上传完成、任务提交、轮询和输出下载。它不得暴露凭据或签名上传 URL。
如果远程任务本身返回 parse_failed,客户端保留该结构化服务器结果。它不会根据服务器消息中的文本推断传输故障。
实现形态¶
mineru/parser/api_client.py 拥有对应的同步和异步请求辅助函数。这些辅助函数应用重试策略,并在耗尽后抛出类型化的内部传输错误。上传完成通过 GET /v1/uploads/{upload_id} 增加状态恢复。
ParseService 根据所选 API 目标映射类型化传输故障,并将生成的错误代码记录在解析任务上。现有的 _V1APIError 处理继续负责结构化 API 和任务错误。
任务提交幂等性是一项独立的 API 变更。一旦服务器支持幂等性密钥,客户端就可以使用稳定的密钥安全地重试 POST /v1/parse/jobs。
测试¶
测试覆盖同步和异步行为:
- 瞬时 GET 和 PUT 故障在重试预算内恢复;
- 上传完成在丢失响应后恢复已完成的上传;
- 传输故障后,任务创建仅尝试一次;
- 耗尽的超时和传输故障映射到文档中记录的远程代码;
- HTTP 错误和远程任务
parse_failed响应不会被重试或重新分类; - 重试日志和异常标识阶段,而不暴露请求机密。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU