迁移路径¶
页码规范与历史结果兼容说明见 PDF 页码范围规范。
状态: Draft 读者: 核心开发者、SDK 开发者 范围: 从当前 SDK 代码走向目标公开契约的步骤 来源: 由旧 SDK 底稿迁移整理而来;旧底稿已归档删除
目标¶
SDK 迁移的目标不是重写现有 parser,而是稳定已经成形的边界:
mineru.parser成为 Tool SDK 主入口。MinerUApiParser成为 v1 API-backed parser。DoclibClient成为本地 doclib SDK。ParseResult成为跨 backend 和 API 的统一结果对象。
当前状态¶
| 主题 | 当前状态 |
|---|---|
| Tool SDK 导出 | 已有 mineru.parser.__all__。 |
DocumentParser |
已有 sync/async/batch/context manager 接口。 |
ParseResult |
已有输出方法,from_dict() / from_json() 已实现;仍需稳定 envelope 兼容边界。 |
| Tier 参数 | parse() 已以 tier 为主参数(默认 standard),并接受 ocr_mode / image_analysis / page_range;backend 专家覆盖保留在 mineru-kit parse CLI 层。 |
| API-backed parser | 已有 MinerUApiParser,使用 v1 uploads/jobs/files。 |
| parse-server runtime | 已有 mineru.parser.api_server。 |
| Doclib SDK | 已有 DoclibClient,继承 DoclibInterface 并返回 typed Pydantic response。 |
| 错误模型 | 已有 mineru.errors;仍需确认 SDK exception 是否暴露 user_action 等扩展字段。 |
Phase 1: 文档和命名稳定¶
- 固化 SDK 分层文档。
- 确认 public import path:
from mineru.parser import parse, ParseResultfrom mineru.parser import MinerUApiParserfrom mineru.doclib.client import DoclibClient- 决定是否增加:
from mineru.client import DoclibClient
不新增 from mineru.parser.remote import MinerUApiParser;API-backed parser 保持现有入口。
验收:
- 文档中每个公开入口都有用途、参数和错误说明。
- CLI 文档与 SDK 文档的入口名一致。
Phase 2: ParseResult 补完¶
- 锁定
ParseResult.from_dict()/from_json()对历史 payload 的兼容范围。 - 稳定
to_dict()输出 envelope。 - 定义 writer protocol。
- 统一
save()的文件命名。
验收:
- 本地 parser result 可以 round-trip:
to_json()->from_json()。 - API
middle_jsonoutput 可以恢复为ParseResult。 - Office/PDF/HTML 的 markdown 和 structured_content 输出不回退。
Phase 3: Tier 进入 Tool SDK¶
状态: 已落地。
parse()/parse_async()已接受tier参数,默认standard。parse()不接受backend参数;backend作为高级专家覆盖保留在mineru-kit parseCLI 层。tier与backend的兼容关系由 CLI 的解析逻辑处理,不进入parse()签名。parse()接受显式tier(flash/basic/standard/advanced);tier=None默认选择逻辑未进入parse(),flash-only 输入的 tier 归一仍由 doclib/CLI 层承担。
验收:
parse(path, tier="basic")可用。parse(path, tier="standard")可用;tier 运行时依赖检查由 api-server / doclib server 层执行,parse()本身不做依赖探测。parse(path)默认使用standard,不会静默使用 flash。parse(path, tier="flash")只有显式请求时使用 flash。
Phase 4: 错误模型统一¶
- 将
MinerUApiParser的内部_V1APIError映射到MineruError。 - 补齐 API/tier 错误码:
unsupported_parameterinvalid_requestquality_tier_unavailable- 为 doclib client 保留 error envelope -> exception 的一致行为。
验收:
- API-backed parser、doclib client、本地 parser 的错误都能被统一捕获。
- CLI 可以根据
code给出 user action。
Phase 5: Doclib Client 类型化¶
- 保持
mineru.doclib.types作为 client 返回类型来源。 - 评估是否为
DoclibClient提供高层parse(...)convenience wrapper;当前稳定入口是ensure_parse(ParseRequest)。 - 增加 context manager。
- 评估
AsyncDoclibClient。
验收:
client.ensure_parse(ParseRequest(...))返回稳定ParseResponse。client.search()返回稳定SearchResponse。client.get_file_by_path()返回稳定FileInfoResponse。- 现有 CLI typed model 调用不破坏。
Phase 6: 测试约束¶
需要覆盖:
- Import 不加载 heavy backend。
parse()后缀分派。ParseResultround-trip。MinerUApiParserupload/job/files mock。DoclibClientUDS error 映射。- 默认选择不回退
flash。
未决问题¶
共享 schema 模块、低层 v1 client 和 Product SDK 覆盖范围,集中维护在 开放问题清单。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU