API-backed Parser: MinerUApiParser¶
状态: Draft
读者: SDK 开发者、parse-server 开发者、集成方
范围: 通过 v1 API 委托解析的 DocumentParser 实现
来源: 由旧 SDK 底稿迁移整理而来;旧底稿已归档删除
定位¶
MinerUApiParser 是 Tool SDK 中的 API-backed parser。它实现 DocumentParser 接口,但不直接调用本地解析后端,而是通过 v1 Unified API 创建 upload 和 parse job。
它的价值是让调用方使用同一个 parser 心智:
from mineru.parser import MinerUApiParser
parser = MinerUApiParser(
api_url="https://mineru.net/api",
api_key="...",
tier="standard",
)
result = parser.parse("report.pdf")
print(result.markdown())
适用场景:
- Python 调用方希望使用远端
mineru.net解析能力。 - doclib worker 需要调用 local parse-server 或 remote parse-server。
- 用户希望复用
DocumentParser/ParseResult接口,而不是直接操作 HTTP API。
非目标:
- 不提供 doclib 搜索、watch、配置能力。
- 不维护本地缓存。
- 不隐式决定是否可上传远端;调用方传入远端
api_url,或通过环境变量配置远端 API,即表示调用方已经允许上传到该 API。
构造参数¶
目标公开签名:
class MinerUApiParser(DocumentParser):
def __init__(
self,
*,
api_url: str | None = None,
api_key: str | None = None,
tier: str | None = None,
ocr_mode: Literal["auto", "txt", "ocr"] | None = None,
include_images: bool = False,
include_model_output: bool = False,
) -> None: ...
字段:
| 参数 | 说明 |
|---|---|
api_url |
v1 API base URL,如 https://mineru.net/api 或 http://127.0.0.1:16580。省略时读取 MINERU_API_URL,再退回默认官方 API。 |
api_key |
Bearer token。省略时读取 MINERU_API_KEY;Local Parse Server 未启用鉴权时可为空。 |
tier |
flash、basic、standard、advanced 或 None。None 表示 SDK 在 HTTP 请求中省略 tier,让 v1 API 使用默认选择策略;非 PDF/image 文件按 API Server 批量规则归一,见 ADR-0024。 |
include_images |
是否从 zip 产物读取图片 sidecar,并挂载到 ParseResult 图片缓存。 |
ocr_mode |
请求级 OCR 模式:auto 自动判断、txt 使用文本层、ocr 强制 OCR。默认 None,在 HTTP 请求中省略字段,由服务端按 auto 处理;显式设置时同步与异步解析均传入任务顶层。 |
include_model_output |
是否请求并保留模型原始输出;开启时通过 zip 产物读取。 |
行为流程¶
parse(path) 的流程:
- 检查文件存在。
- 判断
api_url是否是本地地址。 - 本地地址先读取
GET /v1/health;只有features.sources包含local时才使用localsource。 - 非本地地址,或本地 server 未允许
localsource 时,使用 Uploads API: create upload -> PUT upload_url -> complete upload,再以file_idsource 创建解析任务。 - 调用
POST /v1/parse/jobs;默认请求output_formats:["middle_json"],需要模型输出或图片缓存时请求["zip"]。 - 如果 job 未完成,则轮询
GET /v1/parse/jobs/{job_id}。 - 普通模式下载
middle_jsonoutput file;zip 模式下载zipoutput file。 - zip 模式从 zip 中读取 middle JSON,并在
include_images=True时读取 middle JSON 引用的图片 sidecar。 - 将 middle JSON 转为
ParseResult。
传输重试¶
客户端对可安全重放的传输操作执行有限重试:
- health、upload 状态、job 轮询和产物下载使用
GET,可以重试。 - 向
upload_url写入相同文件字节使用PUT,可以重试。 - upload complete 的响应丢失后,客户端先查询 upload 状态;已经完成则读取其中的 File,仍为 pending 才再次 complete。
POST /v1/parse/jobs 在 API 提供幂等键契约前不会自动重试。该请求的响应丢失时,服务端可能已经创建任务;直接重放会产生重复任务和费用。
重试耗尽后,doclib 远端解析分别使用 remote_timeout 或 remote_unreachable,不把客户端传输错误归类为 parse_failed。远端 job 自身返回的结构化 parse_failed 保持原语义,客户端不根据错误消息文本猜测错误来源。
本地 source:
Local Parse Server 必须通过 --allow-local-source 开启,并在 features.sources 返回 local,SDK 才会使用该形式。
远端 source:
Tier 映射¶
MinerUApiParser 面向 v1 API 时只使用 tier 术语:
| SDK tier | API tier |
|---|---|
None |
省略 |
flash |
flash |
basic |
basic |
standard |
standard |
advanced |
advanced |
它不接受也不保存 backend 参数。backend 是本地 parser 层的高级实现概念,不应出现在 API-backed parser 的公开构造参数、实例属性或请求 payload 中。
输出格式¶
默认只请求 middle_json。如果 include_images=True 或 include_model_output=True,则请求 zip,并从 zip 中恢复 ParseResult 所需的 middle JSON。API 不支持把 images 作为独立 output_formats 请求值。
目标可选参数:
| 参数 | 说明 |
|---|---|
include_images |
请求 zip 并从其中读取图片 sidecar 到 ParseResult 图片缓存。 |
include_model_output |
请求 zip 并尝试保留模型输出。 |
错误映射¶
API error envelope 应映射为 SDK exception:
| API code | SDK 行为 |
|---|---|
invalid_api_key |
抛出认证错误。 |
file_too_large |
抛出用户可修复错误。 |
quality_tier_unavailable |
抛出引擎不可用错误。 |
rate_limit_exceeded |
抛出可重试错误,并保留 Retry-After。 |
service_unavailable |
抛出可重试错误。 |
remote_timeout |
远端传输超时,有限重试后仍未恢复。 |
remote_unreachable |
远端连接或协议错误,有限重试后仍未恢复。 |
当前实现有内部 _V1APIError。目标公开契约应复用 mineru.errors.MineruError 或统一 SDK exception hierarchy。
隐私约束¶
MinerUApiParser 是显式远端/本地 API client。它不会自己决定“是否可以 remote”。调用方只要传入 https://mineru.net/api,就表示允许上传到该 API。
doclib SDK 或 CLI 在调用它之前必须完成隐私策略判断:
- 用户未显式 remote 时,不应构造指向
mineru.net的MinerUApiParser。 - 用户指定 local parse-server 时,优先使用本地 URL。
- API-backed parser 只负责执行请求,不负责产品策略。
与 mineru.parser.api_server¶
mineru.parser.api_server 是 MinerUApiParser 可以连接的服务端实现之一。它提供 v1 Unified API 的 runtime 和 Pydantic contract。
文档关系:
- HTTP 规格见 Unified API。
MinerUApiParser是该 HTTP 规格的 Python parser 封装。api_server是该 HTTP 规格的本地无状态 server 实现。
公开入口¶
MinerUApiParser 保持现有命名和位置,公开入口为:
不新增 mineru.parser.remote 迁移路径。低层 V1ApiClient 是否公开仍集中维护在 开放问题清单。API-backed parser 的异常应收敛到统一 MineruError 体系。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU