yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,1497 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-08-19
21
+ """MinerUKit —— MinerU 官方解析 API 工具类
22
+
23
+ 支持面:PDF / 图片 / Office / HTML 等(以官方接口文档为准,见
24
+ https://mineru.net/apiManage/docs),两种模式:
25
+ - 精准解析:需 Token,异步批量,结果 zip(Markdown/JSON,可选 docx/html/latex);
26
+ - Agent 轻量:免登录(IP 限频),单文件 ≤10MB 且 ≤20 页,仅输出 Markdown。
27
+
28
+ 实现内容:
29
+ - 低层方法(`create_task` / `get_task_result` / `create_batch` / `upload_files` /
30
+ `get_batch_results` / `agent_*`)直接抛异常,便于精确定位。
31
+ - 高层方法(`parse_url` / `parse_files` / `wait_for_task` / `wait_for_batch` /
32
+ `download_zip` / `agent_parse_url` / `agent_parse_file` / `agent_wait_for_result` /
33
+ `download_markdown`)封装「提交 → 轮询 → 完成」流程。
34
+ - 可选参数为 None 时不写入请求,交由服务端取默认值;本地只校验大小与扩展名。
35
+
36
+ 前提条件:
37
+ - 精准解析需 `MINERU_API_KEY`(Settings / `.env`);Agent 模式免登录、不读 Token。
38
+ - 两种模式都需要外网访问;页数限制(Agent ≤20 页)由服务端校验。
39
+
40
+ 依赖:
41
+ - `requests`(extra `mineru`);未安装时导入报错并提示安装命令。
42
+ """
43
+
44
+ import time
45
+ from dataclasses import dataclass
46
+ from pathlib import Path
47
+ from typing import Any
48
+
49
+ try:
50
+ import requests
51
+ except ImportError as e:
52
+ raise ImportError(
53
+ "mineru_kit 需要可选依赖,请安装:pip install yimo-kit[mineru]"
54
+ ) from e
55
+
56
+ from yimo.kit.config.kit_config import get_settings
57
+ from yimo.kit.config.log_config import get_default_logger
58
+
59
+ logger = get_default_logger(__name__)
60
+
61
+ # 官方限制:单文件大小上限 200MB、单次批量申请上传链接上限 50 个
62
+ _MAX_FILE_SIZE_BYTES: int = 200 * 1024 * 1024
63
+ _MAX_BATCH_FILES: int = 50
64
+
65
+ # Agent 轻量解析官方限制:单文件 ≤ 10MB、≤ 20 页
66
+ # (页数无法本地校验,由服务端校验,超限返回 err_code=-30003)
67
+ _AGENT_MAX_FILE_SIZE_BYTES: int = 10 * 1024 * 1024
68
+
69
+ # Agent 轻量解析支持的文件扩展名
70
+ # 官方概述表口径:PDF / 图片(png/jpg/jpeg/jp2/webp/gif/bmp)/ Docx / PPTx / Xlsx,
71
+ # 不支持 .doc / .ppt / .xls / .html(Office 一律只支持新版格式)。
72
+ # 旧格式 Excel(.xls)不受轻量接口支持(服务端会返回 err_code=-30002),本地校验
73
+ # 已按此收紧;如需解析 .xls 请改用精准解析 API(见 _SUPPORTED_EXTENSIONS)。
74
+ _AGENT_SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
75
+ {
76
+ # PDF
77
+ ".pdf",
78
+ # 图片
79
+ ".png",
80
+ ".jpg",
81
+ ".jpeg",
82
+ ".jp2",
83
+ ".webp",
84
+ ".gif",
85
+ ".bmp",
86
+ # Word / PowerPoint / Excel(仅新版格式,不含 .doc / .ppt / .xls)
87
+ ".docx",
88
+ ".pptx",
89
+ ".xlsx",
90
+ }
91
+ )
92
+
93
+ # 支持的文件扩展名(官方文档:PDF / 图片 / Office / HTML)
94
+ _SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
95
+ {
96
+ # PDF
97
+ ".pdf",
98
+ # 图片
99
+ ".png",
100
+ ".jpg",
101
+ ".jpeg",
102
+ ".jp2",
103
+ ".webp",
104
+ ".gif",
105
+ ".bmp",
106
+ # Word
107
+ ".doc",
108
+ ".docx",
109
+ # PowerPoint
110
+ ".ppt",
111
+ ".pptx",
112
+ # Excel
113
+ ".xls",
114
+ ".xlsx",
115
+ # HTML
116
+ ".html",
117
+ }
118
+ )
119
+
120
+ # 任务终态
121
+ _STATE_DONE: str = "done"
122
+ _STATE_FAILED: str = "failed"
123
+
124
+
125
+ class MinerUError(Exception):
126
+ """MinerU API 调用异常(配置缺失 / 网络失败 / HTTP 或业务错误码)"""
127
+
128
+
129
+ @dataclass(frozen=True, slots=True)
130
+ class TaskResult:
131
+ """单任务查询结果
132
+
133
+ Attributes:
134
+ task_id: 任务 ID
135
+ state: 任务状态(done 完成 / pending 排队 / running 解析中 /
136
+ failed 失败 / converting 格式转换中)
137
+ full_zip_url: 解析结果压缩包地址,state=done 时有效
138
+ err_msg: 失败原因,state=failed 时有效
139
+ data_id: 业务数据 ID(请求时传入才会返回)
140
+ extracted_pages: 已解析页数,state=running 时有效
141
+ total_pages: 文档总页数,state=running 时有效
142
+ start_time: 解析开始时间,state=running 时有效
143
+ """
144
+
145
+ task_id: str
146
+ state: str
147
+ full_zip_url: str | None = None
148
+ err_msg: str | None = None
149
+ data_id: str | None = None
150
+ extracted_pages: int | None = None
151
+ total_pages: int | None = None
152
+ start_time: str | None = None
153
+
154
+
155
+ @dataclass(frozen=True, slots=True)
156
+ class BatchTaskResult(TaskResult):
157
+ """批量任务结果项,在 TaskResult 基础上附加文件名"""
158
+
159
+ file_name: str | None = None
160
+
161
+
162
+ @dataclass(frozen=True, slots=True)
163
+ class BatchFile:
164
+ """批量解析请求中的单个文件描述
165
+
166
+ Attributes:
167
+ name: 文件名(强烈建议带正确扩展名,服务端据此识别类型)
168
+ data_id: 业务数据 ID(可选,用于唯一标识业务数据)
169
+ is_ocr: 是否启用 OCR(可选,仅 pipeline / vlm 模型有效)
170
+ page_ranges: 页码范围(可选),如 "2,4-6"、"2--2"
171
+ """
172
+
173
+ name: str
174
+ data_id: str | None = None
175
+ is_ocr: bool | None = None
176
+ page_ranges: str | None = None
177
+
178
+
179
+ @dataclass(frozen=True, slots=True)
180
+ class BatchUploadInfo:
181
+ """批量申请上传链接结果
182
+
183
+ Attributes:
184
+ batch_id: 批次 ID,用于查询批量任务结果
185
+ file_urls: 预签名上传 URL 列表(有效期 24 小时)
186
+ """
187
+
188
+ batch_id: str
189
+ file_urls: list[str]
190
+
191
+
192
+ @dataclass(frozen=True, slots=True)
193
+ class AgentParseResult:
194
+ """轻量解析任务结果
195
+
196
+ Attributes:
197
+ task_id: 任务 ID
198
+ state: 任务状态(waiting-file 等待文件上传(仅文件上传模式)/
199
+ uploading 文件下载中 / pending 排队中 / running 解析中 /
200
+ done 完成 / failed 失败)
201
+ markdown_url: Markdown 结果 CDN 下载链接,state=done 时有效
202
+ err_msg: 失败原因,state=failed 时有效
203
+ err_code: 错误码,state=failed 时有效:
204
+ -30001 大小超限 / -30002 类型不支持 /
205
+ -30003 页数超限 / -30004 参数错误
206
+ """
207
+
208
+ task_id: str
209
+ state: str
210
+ markdown_url: str | None = None
211
+ err_msg: str | None = None
212
+ err_code: int | None = None
213
+
214
+
215
+ @dataclass(frozen=True, slots=True)
216
+ class AgentUploadInfo:
217
+ """轻量解析签名上传信息
218
+
219
+ Attributes:
220
+ task_id: 解析任务 ID
221
+ file_url: OSS 签名上传 URL,PUT 文件到该地址后系统自动开始解析
222
+ """
223
+
224
+ task_id: str
225
+ file_url: str
226
+
227
+
228
+ class MinerUKit:
229
+ """MinerU 解析 API 工具类(精准解析 + Agent 轻量解析)
230
+
231
+ 精准解析 API 需 Token,使用前在 `.env` 中配置::
232
+
233
+ MINERU_API_KEY=你的token # 在 MinerU 官网 API 管理页面自建
234
+
235
+ 使用方式::
236
+
237
+ # 1. 精准解析公网 URL(提交 + 轮询一步到位)
238
+ result = MinerUKit.parse_url(
239
+ "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
240
+ model_version="vlm",
241
+ )
242
+ if result.state == "done":
243
+ zip_path = MinerUKit.download_zip(result.full_zip_url, "./output")
244
+
245
+ # 2. 精准解析本地文件(批量上传 + 轮询一步到位)
246
+ results = MinerUKit.parse_files(["report1.pdf", "report2.docx"])
247
+
248
+ # 3. 精准解析低层分步调用
249
+ task_id = MinerUKit.create_task(url, model_version="vlm")
250
+ result = MinerUKit.wait_for_task(task_id)
251
+
252
+ # 4. 轻量解析公网 URL(免登录,仅输出 Markdown)
253
+ result = MinerUKit.agent_parse_url(url, page_range="1-10")
254
+ if result.state == "done":
255
+ md_path = MinerUKit.download_markdown(result.markdown_url, "./output")
256
+
257
+ # 5. 轻量解析本地文件
258
+ result = MinerUKit.agent_parse_file("demo.pdf")
259
+
260
+ 注意:
261
+ - 精准解析:单文件 ≤ 200MB、≤ 200 页;单次批量 ≤ 50 个文件(官方限制,
262
+ 大小与数量本地强制校验,页数由服务端校验)。
263
+ - 轻量解析:免登录、IP 限频;单文件 ≤ 10MB(本地强制校验)、≤ 20 页
264
+ (服务端校验,超限 err_code=-30003);仅单文件,不支持批量。
265
+ - github、aws 等国外 URL 可能因网络限制请求超时(官方说明)。
266
+ """
267
+
268
+ SUPPORTED_EXTENSIONS: frozenset[str] = _SUPPORTED_EXTENSIONS
269
+ MAX_FILE_SIZE_BYTES: int = _MAX_FILE_SIZE_BYTES
270
+ MAX_BATCH_FILES: int = _MAX_BATCH_FILES
271
+ AGENT_SUPPORTED_EXTENSIONS: frozenset[str] = _AGENT_SUPPORTED_EXTENSIONS
272
+ AGENT_MAX_FILE_SIZE_BYTES: int = _AGENT_MAX_FILE_SIZE_BYTES
273
+
274
+ # ------------------------------------------------------------------
275
+ # 内部工具
276
+ # ------------------------------------------------------------------
277
+
278
+ @staticmethod
279
+ def _token() -> str:
280
+ """读取 API Key,未配置时抛出 MinerUError"""
281
+ token = get_settings().MINERU_API_KEY
282
+ if not token:
283
+ raise MinerUError(
284
+ "未配置 MINERU_API_KEY,请在 .env 中设置"
285
+ "(在 MinerU 官网 API 管理页面自建)"
286
+ )
287
+ return token
288
+
289
+ @classmethod
290
+ def _headers(cls) -> dict[str, str]:
291
+ """构造带鉴权的请求头"""
292
+ return {
293
+ "Content-Type": "application/json",
294
+ "Authorization": f"Bearer {cls._token()}",
295
+ }
296
+
297
+ @staticmethod
298
+ def _base_url() -> str:
299
+ """读取 API 基础地址(去除尾部斜杠)"""
300
+ return get_settings().MINERU_BASE_API_URL.rstrip("/")
301
+
302
+ @staticmethod
303
+ def _transfer_timeout() -> tuple[int, int]:
304
+ """文件上传/结果下载的 (连接超时, 读取超时)
305
+
306
+ 大文件传输耗时远超普通 API 请求:连接超时沿用 MINERU_TIMEOUT,
307
+ 读取超时单独使用 MINERU_TRANSFER_TIMEOUT。
308
+ """
309
+ settings = get_settings()
310
+ return (settings.MINERU_TIMEOUT, settings.MINERU_TRANSFER_TIMEOUT)
311
+
312
+ @staticmethod
313
+ def _make_poll_plan(
314
+ poll_interval: float | None, timeout: int | None
315
+ ) -> tuple[float, int, float]:
316
+ """解析轮询参数:返回 (间隔秒数, 最大等待秒数, 截止单调时刻)"""
317
+ settings = get_settings()
318
+ interval = (
319
+ poll_interval
320
+ if poll_interval is not None
321
+ else settings.MINERU_POLL_INTERVAL
322
+ )
323
+ max_wait = timeout if timeout is not None else settings.MINERU_MAX_WAIT
324
+ return interval, max_wait, time.monotonic() + max_wait
325
+
326
+ @staticmethod
327
+ def _require_str(data: dict[str, Any], field: str, endpoint: str) -> str:
328
+ """取响应 data 中的必填字符串字段,缺失时抛 MinerUError"""
329
+ value = data.get(field)
330
+ if not isinstance(value, str) or not value:
331
+ raise MinerUError(f"响应缺少 {field} 字段: {endpoint}")
332
+ return value
333
+
334
+ @staticmethod
335
+ def _request(method: str, url: str, **kwargs: Any) -> dict[str, Any]:
336
+ """发送 HTTP 请求并统一校验响应,成功返回 JSON 字典
337
+
338
+ Raises:
339
+ MinerUError: 网络失败 / HTTP 非 200 / 业务 code 非 0
340
+ """
341
+ timeout = get_settings().MINERU_TIMEOUT
342
+ try:
343
+ resp = requests.request(method, url, timeout=timeout, **kwargs)
344
+ except requests.RequestException as e:
345
+ logger.error(f"MinerU API 请求失败: {method} {url}: {e}")
346
+ raise MinerUError(f"网络请求失败: {e}") from e
347
+
348
+ if resp.status_code != 200:
349
+ logger.error(
350
+ f"MinerU API HTTP 错误: {method} {url} -> "
351
+ f"{resp.status_code}: {resp.text[:200]}"
352
+ )
353
+ raise MinerUError(f"HTTP {resp.status_code}: {resp.text[:200]}")
354
+
355
+ try:
356
+ payload: dict[str, Any] = resp.json()
357
+ except ValueError as e: # requests.JSONDecodeError 亦为 ValueError 子类
358
+ logger.error(
359
+ f"MinerU API 响应不是合法 JSON: {method} {url} -> {resp.text[:200]}"
360
+ )
361
+ raise MinerUError(f"响应不是合法 JSON: {resp.text[:200]}") from e
362
+ code = payload.get("code")
363
+ if code != 0:
364
+ msg = payload.get("msg", "未知错误")
365
+ trace_id = payload.get("trace_id", "")
366
+ logger.error(
367
+ f"MinerU API 业务错误: code={code}, msg={msg}, trace_id={trace_id}"
368
+ )
369
+ raise MinerUError(f"API 错误 code={code}: {msg}(trace_id={trace_id})")
370
+ return payload
371
+
372
+ @staticmethod
373
+ def _build_payload(params: dict[str, Any]) -> dict[str, Any]:
374
+ """过滤值为 None 的参数,仅保留显式传入项"""
375
+ return {k: v for k, v in params.items() if v is not None}
376
+
377
+ @classmethod
378
+ def _check_local_file(cls, file_path: str | Path) -> Path:
379
+ """校验本地待上传文件(存在 / 扩展名 / 大小),通过返回绝对路径
380
+
381
+ Raises:
382
+ FileNotFoundError: 文件不存在或不是常规文件
383
+ ValueError: 扩展名不受支持,或超过大小上限
384
+ (`MAX_FILE_SIZE_BYTES`,官方限制 200MB)
385
+ """
386
+ path = Path(file_path).resolve()
387
+ if not path.is_file():
388
+ raise FileNotFoundError(f"文件不存在: {path}")
389
+ ext = path.suffix.lower()
390
+ if ext not in cls.SUPPORTED_EXTENSIONS:
391
+ raise ValueError(
392
+ f"不支持的文件格式: {ext or '<无扩展名>'},"
393
+ f"支持的格式: {', '.join(sorted(cls.SUPPORTED_EXTENSIONS))}"
394
+ )
395
+ if path.stat().st_size > cls.MAX_FILE_SIZE_BYTES:
396
+ size_mb = path.stat().st_size / 1024 / 1024
397
+ raise ValueError(
398
+ f"文件大小 {size_mb:.1f}MB 超过官方限制 200MB: {path.name}"
399
+ )
400
+ return path
401
+
402
+ # ------------------------------------------------------------------
403
+ # 低层 API(一端点一方法)
404
+ # ------------------------------------------------------------------
405
+
406
+ @classmethod
407
+ def create_task(
408
+ cls,
409
+ url: str,
410
+ *,
411
+ model_version: str | None = None,
412
+ is_ocr: bool | None = None,
413
+ enable_formula: bool | None = None,
414
+ enable_table: bool | None = None,
415
+ language: str | None = None,
416
+ data_id: str | None = None,
417
+ callback: str | None = None,
418
+ seed: str | None = None,
419
+ extra_formats: list[str] | None = None,
420
+ page_ranges: str | None = None,
421
+ no_cache: bool | None = None,
422
+ cache_tolerance: int | None = None,
423
+ ) -> str:
424
+ """创建单文件解析任务(URL 方式)
425
+
426
+ 对应官方端点 ``POST /api/v4/extract/task``。该接口不支持文件直接上传,
427
+ 仅接收可公网访问的文件 URL(github、aws 等国外 URL 可能超时)。
428
+
429
+ Args:
430
+ url: 文件 URL(支持 pdf/doc/docx/ppt/pptx/xls/xlsx/图片/html)
431
+ model_version: 模型版本,可选 ``pipeline``(官方默认)/ ``vlm``(推荐)/
432
+ ``MinerU-HTML``(解析 HTML 文件时必须指定)
433
+ is_ocr: 是否启用 OCR,默认服务端 false,仅 pipeline / vlm 有效
434
+ enable_formula: 是否开启公式识别,默认服务端 true,仅 pipeline / vlm 有效
435
+ enable_table: 是否开启表格识别,默认服务端 true,仅 pipeline / vlm 有效
436
+ language: 文档语言(默认 ``ch``),仅 pipeline / vlm 有效
437
+ data_id: 业务数据 ID(字母/数字/下划线/短划线/句号,≤128 字符)
438
+ callback: 解析结果回调通知 URL(POST/UTF-8/JSON);为空需轮询结果
439
+ seed: 回调签名随机字符串(使用 callback 时必须提供,≤64 字符)
440
+ extra_formats: 附加导出格式,仅支持 ``docx`` / ``html`` / ``latex``
441
+ 中一个或多个(markdown、json 默认导出无须设置)
442
+ page_ranges: 页码范围,如 ``"2,4-6"``(第2页及第4~6页)、``"2--2"``
443
+ (第2页至倒数第二页)
444
+ no_cache: 是否绕过缓存,默认服务端 false
445
+ cache_tolerance: 缓存容忍时间(秒),默认服务端 900
446
+
447
+ Returns:
448
+ str: 任务 ID(task_id),用于查询任务结果
449
+
450
+ Raises:
451
+ MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
452
+
453
+ Example:
454
+ >>> task_id = MinerUKit.create_task(
455
+ ... "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
456
+ ... model_version="vlm",
457
+ ... )
458
+ """
459
+ payload = cls._build_payload(
460
+ {
461
+ "url": url,
462
+ "model_version": model_version,
463
+ "is_ocr": is_ocr,
464
+ "enable_formula": enable_formula,
465
+ "enable_table": enable_table,
466
+ "language": language,
467
+ "data_id": data_id,
468
+ "callback": callback,
469
+ "seed": seed,
470
+ "extra_formats": extra_formats,
471
+ "page_ranges": page_ranges,
472
+ "no_cache": no_cache,
473
+ "cache_tolerance": cache_tolerance,
474
+ }
475
+ )
476
+ logger.info(f"提交 MinerU 解析任务: {url}")
477
+ resp = cls._request(
478
+ "POST",
479
+ f"{cls._base_url()}/api/v4/extract/task",
480
+ headers=cls._headers(),
481
+ json=payload,
482
+ )
483
+ data: dict[str, Any] = resp.get("data") or {}
484
+ task_id = cls._require_str(data, "task_id", "/api/v4/extract/task")
485
+ logger.info(f"MinerU 任务已创建: task_id={task_id}")
486
+ return task_id
487
+
488
+ @classmethod
489
+ def get_task_result(cls, task_id: str) -> TaskResult:
490
+ """查询单任务结果
491
+
492
+ 对应官方端点 ``GET /api/v4/extract/task/{task_id}``。
493
+
494
+ Args:
495
+ task_id: 任务 ID(由 create_task / create_batch 返回)
496
+
497
+ Returns:
498
+ TaskResult: 任务状态与结果(state=done 时含 full_zip_url)
499
+
500
+ Raises:
501
+ MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
502
+
503
+ Example:
504
+ >>> result = MinerUKit.get_task_result(task_id)
505
+ >>> result.state
506
+ 'done'
507
+ """
508
+ resp = cls._request(
509
+ "GET",
510
+ f"{cls._base_url()}/api/v4/extract/task/{task_id}",
511
+ headers=cls._headers(),
512
+ )
513
+ data: dict[str, Any] = resp.get("data", {})
514
+ progress: dict[str, Any] = data.get("extract_progress") or {}
515
+ return TaskResult(
516
+ task_id=data.get("task_id", task_id),
517
+ state=data.get("state", ""),
518
+ full_zip_url=data.get("full_zip_url"),
519
+ err_msg=data.get("err_msg"),
520
+ data_id=data.get("data_id"),
521
+ extracted_pages=progress.get("extracted_pages"),
522
+ total_pages=progress.get("total_pages"),
523
+ start_time=progress.get("start_time"),
524
+ )
525
+
526
+ @classmethod
527
+ def create_batch(
528
+ cls,
529
+ files: list[BatchFile],
530
+ *,
531
+ model_version: str | None = None,
532
+ enable_formula: bool | None = None,
533
+ enable_table: bool | None = None,
534
+ language: str | None = None,
535
+ callback: str | None = None,
536
+ seed: str | None = None,
537
+ extra_formats: list[str] | None = None,
538
+ no_cache: bool | None = None,
539
+ cache_tolerance: int | None = None,
540
+ ) -> BatchUploadInfo:
541
+ """批量申请文件上传链接(本地文件解析第一步)
542
+
543
+ 对应官方端点 ``POST /api/v4/file-urls/batch``。申请到的预签名 URL
544
+ 有效期 24 小时;文件上传完成后系统**自动**提交解析任务,无须再调用
545
+ create_task。
546
+
547
+ Args:
548
+ files: 文件描述列表(≤50 个),每项含文件名与可选参数
549
+ model_version: 模型版本(同 create_task;HTML 文件须指定 MinerU-HTML)
550
+ enable_formula: 是否开启公式识别(同 create_task)
551
+ enable_table: 是否开启表格识别(同 create_task)
552
+ language: 文档语言(同 create_task)
553
+ callback: 解析结果回调通知 URL(同 create_task)
554
+ seed: 回调签名随机字符串(使用 callback 时必须提供)
555
+ extra_formats: 附加导出格式(同 create_task)
556
+ no_cache: 是否绕过缓存(同 create_task)
557
+ cache_tolerance: 缓存容忍时间(秒,同 create_task)
558
+
559
+ Returns:
560
+ BatchUploadInfo: 批次 ID 与预签名上传 URL 列表
561
+
562
+ Raises:
563
+ ValueError: 文件列表为空或超过 50 个,或扩展名不受支持
564
+ MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
565
+
566
+ Example:
567
+ >>> info = MinerUKit.create_batch(
568
+ ... [BatchFile(name="demo.pdf")], model_version="vlm"
569
+ ... )
570
+ >>> info.batch_id
571
+ """
572
+ if not files:
573
+ raise ValueError("文件列表不能为空")
574
+ if len(files) > cls.MAX_BATCH_FILES:
575
+ raise ValueError(
576
+ f"单次批量不能超过 {cls.MAX_BATCH_FILES} 个文件,当前: {len(files)}"
577
+ )
578
+ for f in files:
579
+ ext = Path(f.name).suffix.lower()
580
+ if ext not in cls.SUPPORTED_EXTENSIONS:
581
+ raise ValueError(
582
+ f"不支持的文件格式: {f.name}(扩展名 {ext or '<无扩展名>'})"
583
+ )
584
+
585
+ file_dicts = [
586
+ cls._build_payload(
587
+ {
588
+ "name": f.name,
589
+ "data_id": f.data_id,
590
+ "is_ocr": f.is_ocr,
591
+ "page_ranges": f.page_ranges,
592
+ }
593
+ )
594
+ for f in files
595
+ ]
596
+ payload = cls._build_payload(
597
+ {
598
+ "files": file_dicts,
599
+ "model_version": model_version,
600
+ "enable_formula": enable_formula,
601
+ "enable_table": enable_table,
602
+ "language": language,
603
+ "callback": callback,
604
+ "seed": seed,
605
+ "extra_formats": extra_formats,
606
+ "no_cache": no_cache,
607
+ "cache_tolerance": cache_tolerance,
608
+ }
609
+ )
610
+ logger.info(f"申请 MinerU 批量上传链接: {len(files)} 个文件")
611
+ resp = cls._request(
612
+ "POST",
613
+ f"{cls._base_url()}/api/v4/file-urls/batch",
614
+ headers=cls._headers(),
615
+ json=payload,
616
+ )
617
+ data: dict[str, Any] = resp["data"]
618
+ info = BatchUploadInfo(
619
+ batch_id=data["batch_id"],
620
+ file_urls=list(data.get("file_urls", [])),
621
+ )
622
+ logger.info(
623
+ f"MinerU 批量上传链接已获取: batch_id={info.batch_id},"
624
+ f"{len(info.file_urls)} 个链接"
625
+ )
626
+ return info
627
+
628
+ @classmethod
629
+ def upload_files(
630
+ cls, file_paths: list[str | Path], upload_urls: list[str]
631
+ ) -> list[bool]:
632
+ """将本地文件批量上传至预签名 URL(本地文件解析第二步)
633
+
634
+ 对文件执行 PUT 上传。官方要求:上传时**不设置** Authorization 与
635
+ Content-Type 请求头,本方法已按此处理。逐个上传,单个失败记录日志
636
+ 并继续,不影响其余文件。
637
+
638
+ Args:
639
+ file_paths: 本地文件路径列表(与 upload_urls 顺序一一对应)
640
+ upload_urls: create_batch 返回的预签名上传 URL 列表
641
+
642
+ Returns:
643
+ list[bool]: 每个文件的上传结果(True 成功 / False 失败)
644
+
645
+ Raises:
646
+ ValueError: 两个列表长度不一致
647
+ FileNotFoundError: 文件不存在(单个文件校验失败直接抛出)
648
+ MinerUError: 网络请求失败
649
+
650
+ Example:
651
+ >>> results = MinerUKit.upload_files(["demo.pdf"], info.file_urls)
652
+ """
653
+ if len(file_paths) != len(upload_urls):
654
+ raise ValueError(
655
+ f"文件数 ({len(file_paths)}) 与上传链接数 ({len(upload_urls)}) 不一致"
656
+ )
657
+ timeout = cls._transfer_timeout()
658
+ results: list[bool] = []
659
+ for file_path, upload_url in zip(file_paths, upload_urls):
660
+ path = cls._check_local_file(file_path)
661
+ logger.info(f"上传文件到 MinerU: {path.name}({path.stat().st_size} 字节)")
662
+ try:
663
+ resp = requests.put(upload_url, data=path.read_bytes(), timeout=timeout)
664
+ except requests.RequestException as e:
665
+ logger.error(f"文件上传失败: {path.name}: {e}")
666
+ results.append(False)
667
+ continue
668
+ if resp.status_code == 200:
669
+ logger.info(f"✅ 文件上传成功: {path.name}")
670
+ results.append(True)
671
+ else:
672
+ logger.error(
673
+ f"文件上传失败: {path.name} -> HTTP {resp.status_code}: "
674
+ f"{resp.text[:200]}"
675
+ )
676
+ results.append(False)
677
+ return results
678
+
679
+ @classmethod
680
+ def get_batch_results(cls, batch_id: str) -> list[BatchTaskResult]:
681
+ """查询批量任务结果
682
+
683
+ 对应官方端点 ``GET /api/v4/extract-results/batch/{batch_id}``。
684
+ 注意:查询过早时部分任务可能尚未创建(结果列表可能少于上传文件数),
685
+ 等待全部完成请使用 wait_for_batch。
686
+
687
+ Args:
688
+ batch_id: 批次 ID(由 create_batch 返回)
689
+
690
+ Returns:
691
+ list[BatchTaskResult]: 批次内各文件的当前状态
692
+
693
+ Raises:
694
+ MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
695
+
696
+ Example:
697
+ >>> results = MinerUKit.get_batch_results(info.batch_id)
698
+ >>> [(r.file_name, r.state) for r in results]
699
+ """
700
+ resp = cls._request(
701
+ "GET",
702
+ f"{cls._base_url()}/api/v4/extract-results/batch/{batch_id}",
703
+ headers=cls._headers(),
704
+ )
705
+ data: dict[str, Any] = resp.get("data", {})
706
+ raw_list: list[dict[str, Any]] = data.get("extract_result", [])
707
+ results: list[BatchTaskResult] = []
708
+ for item in raw_list:
709
+ progress: dict[str, Any] = item.get("extract_progress") or {}
710
+ results.append(
711
+ BatchTaskResult(
712
+ task_id=item.get("task_id", ""),
713
+ state=item.get("state", ""),
714
+ full_zip_url=item.get("full_zip_url"),
715
+ err_msg=item.get("err_msg"),
716
+ data_id=item.get("data_id"),
717
+ extracted_pages=progress.get("extracted_pages"),
718
+ total_pages=progress.get("total_pages"),
719
+ start_time=progress.get("start_time"),
720
+ file_name=item.get("file_name"),
721
+ )
722
+ )
723
+ return results
724
+
725
+ # ------------------------------------------------------------------
726
+ # 高层便利 API(提交 → 轮询 → 完成)
727
+ # ------------------------------------------------------------------
728
+
729
+ @classmethod
730
+ def wait_for_task(
731
+ cls,
732
+ task_id: str,
733
+ *,
734
+ poll_interval: float | None = None,
735
+ timeout: int | None = None,
736
+ ) -> TaskResult:
737
+ """轮询等待单任务到达终态(done / failed)
738
+
739
+ Args:
740
+ task_id: 任务 ID
741
+ poll_interval: 轮询间隔秒数,None 时使用 MINERU_POLL_INTERVAL
742
+ timeout: 总等待秒数,None 时使用 MINERU_MAX_WAIT
743
+
744
+ Returns:
745
+ TaskResult: 终态结果(state=done 或 failed)
746
+
747
+ Raises:
748
+ MinerUError: 超过总等待时间仍未到达终态
749
+
750
+ Example:
751
+ >>> result = MinerUKit.wait_for_task(task_id, timeout=300)
752
+ """
753
+ interval, max_wait, deadline = cls._make_poll_plan(poll_interval, timeout)
754
+ while True:
755
+ result = cls.get_task_result(task_id)
756
+ if result.state == _STATE_DONE:
757
+ logger.info(f"✅ MinerU 任务完成: {task_id}")
758
+ return result
759
+ if result.state == _STATE_FAILED:
760
+ logger.error(f"❌ MinerU 任务失败: {task_id}: {result.err_msg}")
761
+ return result
762
+ if result.state == "running" and result.total_pages:
763
+ logger.info(
764
+ f"MinerU 解析中: {task_id} "
765
+ f"已解析 {result.extracted_pages or 0}/{result.total_pages} 页"
766
+ )
767
+ else:
768
+ logger.debug(f"MinerU 任务状态: {task_id} -> {result.state}")
769
+ if time.monotonic() >= deadline:
770
+ raise MinerUError(
771
+ f"等待任务 {task_id} 超时({max_wait} 秒),"
772
+ f"最后状态: {result.state}"
773
+ )
774
+ time.sleep(interval)
775
+
776
+ @classmethod
777
+ def wait_for_batch(
778
+ cls,
779
+ batch_id: str,
780
+ *,
781
+ expected_count: int | None = None,
782
+ poll_interval: float | None = None,
783
+ timeout: int | None = None,
784
+ ) -> list[BatchTaskResult]:
785
+ """轮询等待批量任务全部到达终态
786
+
787
+ Args:
788
+ batch_id: 批次 ID
789
+ expected_count: 期望的文件数量。官方在文件上传后才会自动创建任务,
790
+ 查询过早时结果列表可能不完整;传入该值可确保全部任务出现且
791
+ 到达终态后才返回(parse_files 会自动传入)
792
+ poll_interval: 轮询间隔秒数,None 时使用 MINERU_POLL_INTERVAL
793
+ timeout: 总等待秒数,None 时使用 MINERU_MAX_WAIT
794
+
795
+ Returns:
796
+ list[BatchTaskResult]: 批次内全部文件的终态结果
797
+
798
+ Raises:
799
+ MinerUError: 超过总等待时间仍未全部到达终态
800
+
801
+ Example:
802
+ >>> results = MinerUKit.wait_for_batch(info.batch_id, expected_count=2)
803
+ """
804
+ interval, max_wait, deadline = cls._make_poll_plan(poll_interval, timeout)
805
+ while True:
806
+ results = cls.get_batch_results(batch_id)
807
+ all_terminal = bool(results) and all(
808
+ r.state in (_STATE_DONE, _STATE_FAILED) for r in results
809
+ )
810
+ count_ok = expected_count is None or len(results) >= expected_count
811
+ if all_terminal and count_ok:
812
+ done = sum(1 for r in results if r.state == _STATE_DONE)
813
+ failed = sum(1 for r in results if r.state == _STATE_FAILED)
814
+ logger.info(
815
+ f"✅ MinerU 批量任务完成: batch_id={batch_id},"
816
+ f"成功 {done} 个,失败 {failed} 个"
817
+ )
818
+ return results
819
+ if time.monotonic() >= deadline:
820
+ raise MinerUError(
821
+ f"等待批量任务 {batch_id} 超时({max_wait} 秒),"
822
+ f"当前可见 {len(results)} 个任务"
823
+ )
824
+ logger.debug(
825
+ f"MinerU 批量任务进行中: batch_id={batch_id},"
826
+ f"当前可见 {len(results)} 个任务"
827
+ )
828
+ time.sleep(interval)
829
+
830
+ @classmethod
831
+ def parse_url(
832
+ cls,
833
+ url: str,
834
+ *,
835
+ model_version: str | None = None,
836
+ is_ocr: bool | None = None,
837
+ enable_formula: bool | None = None,
838
+ enable_table: bool | None = None,
839
+ language: str | None = None,
840
+ data_id: str | None = None,
841
+ extra_formats: list[str] | None = None,
842
+ page_ranges: str | None = None,
843
+ no_cache: bool | None = None,
844
+ cache_tolerance: int | None = None,
845
+ poll_interval: float | None = None,
846
+ timeout: int | None = None,
847
+ ) -> TaskResult:
848
+ """解析公网 URL 文件(提交 + 轮询一步到位)
849
+
850
+ create_task 与 wait_for_task 的组合封装,参数含义见二者 docstring
851
+ (callback / seed 回调相关参数不参与本方法,如需回调请使用低层方法)。
852
+
853
+ Args:
854
+ url: 文件 URL
855
+ model_version: 模型版本(HTML 文件须指定 MinerU-HTML)
856
+ is_ocr: 是否启用 OCR
857
+ enable_formula: 是否开启公式识别
858
+ enable_table: 是否开启表格识别
859
+ language: 文档语言
860
+ data_id: 业务数据 ID
861
+ extra_formats: 附加导出格式(docx/html/latex)
862
+ page_ranges: 页码范围
863
+ no_cache: 是否绕过缓存
864
+ cache_tolerance: 缓存容忍时间(秒)
865
+ poll_interval: 轮询间隔秒数
866
+ timeout: 轮询总超时秒数
867
+
868
+ Returns:
869
+ TaskResult: 终态结果(state=done 时含 full_zip_url)
870
+
871
+ Raises:
872
+ MinerUError: 未配置 Token / 网络失败 / 轮询超时
873
+
874
+ Example:
875
+ >>> result = MinerUKit.parse_url(
876
+ ... "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
877
+ ... model_version="vlm",
878
+ ... )
879
+ >>> print(result.state, result.full_zip_url)
880
+ """
881
+ task_id = cls.create_task(
882
+ url,
883
+ model_version=model_version,
884
+ is_ocr=is_ocr,
885
+ enable_formula=enable_formula,
886
+ enable_table=enable_table,
887
+ language=language,
888
+ data_id=data_id,
889
+ extra_formats=extra_formats,
890
+ page_ranges=page_ranges,
891
+ no_cache=no_cache,
892
+ cache_tolerance=cache_tolerance,
893
+ )
894
+ return cls.wait_for_task(task_id, poll_interval=poll_interval, timeout=timeout)
895
+
896
+ @classmethod
897
+ def parse_files(
898
+ cls,
899
+ file_paths: list[str | Path],
900
+ *,
901
+ model_version: str | None = None,
902
+ is_ocr: bool | None = None,
903
+ enable_formula: bool | None = None,
904
+ enable_table: bool | None = None,
905
+ language: str | None = None,
906
+ page_ranges: str | None = None,
907
+ extra_formats: list[str] | None = None,
908
+ no_cache: bool | None = None,
909
+ cache_tolerance: int | None = None,
910
+ poll_interval: float | None = None,
911
+ timeout: int | None = None,
912
+ ) -> list[BatchTaskResult]:
913
+ """解析本地文件(申请链接 + 上传 + 轮询一步到位)
914
+
915
+ create_batch + upload_files + wait_for_batch 的组合封装。
916
+ 每个文件共享相同的解析参数(页码范围等);如需每个文件独立参数,
917
+ 请使用低层方法自行组合。
918
+
919
+ Args:
920
+ file_paths: 本地文件路径列表(1~50 个,每个 ≤200MB)
921
+ model_version: 模型版本(HTML 文件须指定 MinerU-HTML)
922
+ is_ocr: 是否启用 OCR(全部文件共享)
923
+ enable_formula: 是否开启公式识别
924
+ enable_table: 是否开启表格识别
925
+ language: 文档语言
926
+ page_ranges: 页码范围(全部文件共享)
927
+ extra_formats: 附加导出格式(docx/html/latex)
928
+ no_cache: 是否绕过缓存(同 create_batch)
929
+ cache_tolerance: 缓存容忍时间(秒,同 create_batch)
930
+ poll_interval: 轮询间隔秒数
931
+ timeout: 轮询总超时秒数
932
+
933
+ Returns:
934
+ list[BatchTaskResult]: 全部文件的终态结果(按 file_name 关联)
935
+
936
+ Raises:
937
+ ValueError: 文件数量 / 格式 / 大小不符合官方限制
938
+ FileNotFoundError: 文件不存在
939
+ MinerUError: 未配置 Token / 网络失败 / 文件上传失败(fail-fast,
940
+ 错误信息含失败文件名与 batch_id)/ 轮询超时
941
+
942
+ Example:
943
+ >>> results = MinerUKit.parse_files(
944
+ ... ["a.pdf", "b.docx"], model_version="vlm"
945
+ ... )
946
+ >>> for r in results:
947
+ ... print(r.file_name, r.state, r.full_zip_url)
948
+ """
949
+ files = [
950
+ BatchFile(name=Path(p).name, is_ocr=is_ocr, page_ranges=page_ranges)
951
+ for p in file_paths
952
+ ]
953
+ info = cls.create_batch(
954
+ files,
955
+ model_version=model_version,
956
+ enable_formula=enable_formula,
957
+ enable_table=enable_table,
958
+ language=language,
959
+ extra_formats=extra_formats,
960
+ no_cache=no_cache,
961
+ cache_tolerance=cache_tolerance,
962
+ )
963
+ upload_results = cls.upload_files(file_paths, info.file_urls)
964
+ # 上传失败的文件不会在服务端生成任务,若不检查会一直等到
965
+ # MINERU_MAX_WAIT 超时(错误信息还会误导为"任务未创建"),
966
+ # 故此处 fail-fast,并给出 batch_id 便于查询已成功上传的文件
967
+ failed = [Path(p).name for p, ok in zip(file_paths, upload_results) if not ok]
968
+ if failed:
969
+ raise MinerUError(
970
+ f"文件上传失败,已中止等待: {', '.join(failed)};"
971
+ f"已成功上传的文件仍在解析,可用 "
972
+ f"get_batch_results('{info.batch_id}') 查询"
973
+ )
974
+ return cls.wait_for_batch(
975
+ info.batch_id,
976
+ expected_count=len(files),
977
+ poll_interval=poll_interval,
978
+ timeout=timeout,
979
+ )
980
+
981
+ @classmethod
982
+ def download_zip(cls, zip_url: str, dest_dir: str | Path) -> str:
983
+ """下载解析结果压缩包到本地
984
+
985
+ 结果 zip 内含 Markdown / JSON(可选 docx/html/latex),文件结构说明见
986
+ https://opendatalab.github.io/MinerU/reference/output_files/
987
+
988
+ Args:
989
+ zip_url: 结果压缩包地址(full_zip_url)
990
+ dest_dir: 目标目录(不存在时自动创建);文件名取 URL 末段,
991
+ 非 .zip 后缀时自动补全
992
+
993
+ Returns:
994
+ str: 保存的本地文件绝对路径
995
+
996
+ Raises:
997
+ MinerUError: 网络失败或 HTTP 非 200
998
+
999
+ Example:
1000
+ >>> MinerUKit.download_zip(result.full_zip_url, "./output")
1001
+ """
1002
+ dest = Path(dest_dir)
1003
+ dest.mkdir(parents=True, exist_ok=True)
1004
+ filename = zip_url.rstrip("/").split("/")[-1] or "mineru_result.zip"
1005
+ if not filename.endswith(".zip"):
1006
+ filename = f"{filename}.zip"
1007
+ target = (dest / filename).resolve()
1008
+ logger.info(f"下载 MinerU 结果包: {zip_url}")
1009
+ try:
1010
+ resp = requests.get(zip_url, timeout=cls._transfer_timeout(), stream=True)
1011
+ except requests.RequestException as e:
1012
+ logger.error(f"下载失败: {e}")
1013
+ raise MinerUError(f"结果包下载失败: {e}") from e
1014
+ try:
1015
+ if resp.status_code != 200:
1016
+ raise MinerUError(f"结果包下载失败: HTTP {resp.status_code}")
1017
+ with open(target, "wb") as f:
1018
+ for chunk in resp.iter_content(chunk_size=1024 * 1024):
1019
+ if chunk:
1020
+ f.write(chunk)
1021
+ finally:
1022
+ resp.close()
1023
+ logger.info(f"✅ 结果包已保存: {target}({target.stat().st_size} 字节)")
1024
+ return str(target)
1025
+
1026
+ # ------------------------------------------------------------------
1027
+ # Agent 轻量解析 API(免登录,IP 限频,单文件 ≤10MB 且 ≤20 页)
1028
+ # ------------------------------------------------------------------
1029
+
1030
+ @staticmethod
1031
+ def _agent_headers() -> dict[str, str]:
1032
+ """构造轻量解析请求头(免登录,无需 Authorization)"""
1033
+ return {"Content-Type": "application/json"}
1034
+
1035
+ @classmethod
1036
+ def _check_agent_file(cls, file_path: str | Path) -> Path:
1037
+ """校验轻量解析待上传文件(存在 / 扩展名 / 大小),通过返回绝对路径
1038
+
1039
+ Raises:
1040
+ FileNotFoundError: 文件不存在或不是常规文件
1041
+ ValueError: 扩展名不受支持,或超过大小上限
1042
+ (`AGENT_MAX_FILE_SIZE_BYTES`,轻量接口限制 10MB)
1043
+ """
1044
+ path = Path(file_path).resolve()
1045
+ if not path.is_file():
1046
+ raise FileNotFoundError(f"文件不存在: {path}")
1047
+ ext = path.suffix.lower()
1048
+ if ext not in cls.AGENT_SUPPORTED_EXTENSIONS:
1049
+ raise ValueError(
1050
+ f"轻量解析不支持的文件格式: {ext or '<无扩展名>'},"
1051
+ f"支持的格式: {', '.join(sorted(cls.AGENT_SUPPORTED_EXTENSIONS))}"
1052
+ )
1053
+ if path.stat().st_size > cls.AGENT_MAX_FILE_SIZE_BYTES:
1054
+ size_mb = path.stat().st_size / 1024 / 1024
1055
+ raise ValueError(
1056
+ f"文件大小 {size_mb:.1f}MB 超过轻量接口限制 10MB: {path.name}"
1057
+ )
1058
+ return path
1059
+
1060
+ @classmethod
1061
+ def agent_create_url_task(
1062
+ cls,
1063
+ url: str,
1064
+ *,
1065
+ file_name: str | None = None,
1066
+ language: str | None = None,
1067
+ is_ocr: bool | None = None,
1068
+ enable_formula: bool | None = None,
1069
+ enable_table: bool | None = None,
1070
+ page_range: str | None = None,
1071
+ ) -> str:
1072
+ """提交轻量解析任务(URL 方式)
1073
+
1074
+ 对应官方端点 ``POST /api/v1/agent/parse/url``(免登录)。
1075
+ 异步模式,成功后返回 task_id,须通过 agent_get_result /
1076
+ agent_wait_for_result 轮询结果。
1077
+
1078
+ Args:
1079
+ url: 远程文件 URL(支持 PDF、图片、Docx、PPTx、Xlsx,不支持 HTML;
1080
+ 具体扩展名以 `AGENT_SUPPORTED_EXTENSIONS` 为准)
1081
+ file_name: 文件名(含扩展名),用于判断类型,缺省从 URL 自动解析
1082
+ language: 解析语言(默认 ``ch``),仅对 PDF 生效
1083
+ is_ocr: 是否启用 OCR,默认服务端 false,仅对 PDF 生效
1084
+ enable_formula: 是否开启公式识别,默认服务端 true,仅对 PDF 生效
1085
+ enable_table: 是否开启表格识别,默认服务端 true,仅对 PDF 生效
1086
+ page_range: 页码范围,如 ``"1-10"`` 或 ``"5"``,不支持逗号分隔格式,
1087
+ 仅对 PDF 生效
1088
+
1089
+ Returns:
1090
+ str: 任务 ID(task_id),用于查询解析结果
1091
+
1092
+ Raises:
1093
+ MinerUError: 网络失败 / HTTP 非 200(含 IP 限频 429)/ 业务错误码
1094
+
1095
+ Example:
1096
+ >>> task_id = MinerUKit.agent_create_url_task(
1097
+ ... "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
1098
+ ... )
1099
+ """
1100
+ payload = cls._build_payload(
1101
+ {
1102
+ "url": url,
1103
+ "file_name": file_name,
1104
+ "language": language,
1105
+ "is_ocr": is_ocr,
1106
+ "enable_formula": enable_formula,
1107
+ "enable_table": enable_table,
1108
+ "page_range": page_range,
1109
+ }
1110
+ )
1111
+ logger.info(f"提交 MinerU 轻量解析任务(URL): {url}")
1112
+ resp = cls._request(
1113
+ "POST",
1114
+ f"{cls._base_url()}/api/v1/agent/parse/url",
1115
+ headers=cls._agent_headers(),
1116
+ json=payload,
1117
+ )
1118
+ data: dict[str, Any] = resp.get("data") or {}
1119
+ task_id = cls._require_str(data, "task_id", "/api/v1/agent/parse/url")
1120
+ logger.info(f"MinerU 轻量解析任务已创建: task_id={task_id}")
1121
+ return task_id
1122
+
1123
+ @classmethod
1124
+ def agent_create_file_task(
1125
+ cls,
1126
+ file_name: str,
1127
+ *,
1128
+ language: str | None = None,
1129
+ is_ocr: bool | None = None,
1130
+ enable_formula: bool | None = None,
1131
+ enable_table: bool | None = None,
1132
+ page_range: str | None = None,
1133
+ ) -> AgentUploadInfo:
1134
+ """申请轻量解析签名上传(本地文件解析第一步)
1135
+
1136
+ 对应官方端点 ``POST /api/v1/agent/parse/file``(免登录)。签名上传
1137
+ 模式:拿到 task_id 与 OSS 签名上传 URL(file_url)后,用
1138
+ agent_upload_file 将文件 PUT 到 file_url,上传完成后系统自动开始
1139
+ 解析。每次仅支持一个文件,不支持批量。
1140
+
1141
+ Args:
1142
+ file_name: 文件名(含扩展名),服务端据此识别类型
1143
+ language: 解析语言(同 agent_create_url_task)
1144
+ is_ocr: 是否启用 OCR(同 agent_create_url_task)
1145
+ enable_formula: 是否开启公式识别(同 agent_create_url_task)
1146
+ enable_table: 是否开启表格识别(同 agent_create_url_task)
1147
+ page_range: 页码范围(同 agent_create_url_task)
1148
+
1149
+ Returns:
1150
+ AgentUploadInfo: 任务 ID 与签名上传 URL
1151
+
1152
+ Raises:
1153
+ MinerUError: 网络失败 / HTTP 非 200 / 业务错误码
1154
+
1155
+ Example:
1156
+ >>> info = MinerUKit.agent_create_file_task("demo.pdf")
1157
+ """
1158
+ payload = cls._build_payload(
1159
+ {
1160
+ "file_name": file_name,
1161
+ "language": language,
1162
+ "is_ocr": is_ocr,
1163
+ "enable_formula": enable_formula,
1164
+ "enable_table": enable_table,
1165
+ "page_range": page_range,
1166
+ }
1167
+ )
1168
+ logger.info(f"申请 MinerU 轻量解析签名上传: {file_name}")
1169
+ resp = cls._request(
1170
+ "POST",
1171
+ f"{cls._base_url()}/api/v1/agent/parse/file",
1172
+ headers=cls._agent_headers(),
1173
+ json=payload,
1174
+ )
1175
+ data: dict[str, Any] = resp.get("data") or {}
1176
+ info = AgentUploadInfo(
1177
+ task_id=cls._require_str(data, "task_id", "/api/v1/agent/parse/file"),
1178
+ file_url=cls._require_str(data, "file_url", "/api/v1/agent/parse/file"),
1179
+ )
1180
+ logger.info(f"MinerU 轻量解析签名上传已获取: task_id={info.task_id}")
1181
+ return info
1182
+
1183
+ @classmethod
1184
+ def agent_upload_file(cls, file_path: str | Path, file_url: str) -> None:
1185
+ """将本地文件上传至签名 URL(轻量解析本地文件第二步)
1186
+
1187
+ 对文件执行 PUT 上传。签名 URL 由服务端生成,上传时不设置
1188
+ Authorization 与 Content-Type 请求头。上传完成后系统自动开始解析。
1189
+
1190
+ Args:
1191
+ file_path: 本地文件路径(≤10MB,扩展名须受轻量接口支持)
1192
+ file_url: agent_create_file_task 返回的签名上传 URL
1193
+
1194
+ Raises:
1195
+ FileNotFoundError: 文件不存在
1196
+ ValueError: 扩展名不受支持或超过 10MB 大小限制
1197
+ MinerUError: 网络失败或 HTTP 非 200
1198
+
1199
+ Example:
1200
+ >>> MinerUKit.agent_upload_file("demo.pdf", info.file_url)
1201
+ """
1202
+ path = cls._check_agent_file(file_path)
1203
+ logger.info(
1204
+ f"上传文件到 MinerU 轻量解析: {path.name}({path.stat().st_size} 字节)"
1205
+ )
1206
+ timeout = cls._transfer_timeout()
1207
+ try:
1208
+ resp = requests.put(file_url, data=path.read_bytes(), timeout=timeout)
1209
+ except requests.RequestException as e:
1210
+ logger.error(f"轻量解析文件上传失败: {path.name}: {e}")
1211
+ raise MinerUError(f"文件上传失败: {e}") from e
1212
+ if resp.status_code != 200:
1213
+ raise MinerUError(f"文件上传失败: {path.name} -> HTTP {resp.status_code}")
1214
+ logger.info(f"✅ 轻量解析文件上传成功: {path.name}")
1215
+
1216
+ @classmethod
1217
+ def agent_get_result(cls, task_id: str) -> AgentParseResult:
1218
+ """查询轻量解析任务结果
1219
+
1220
+ 对应官方端点 ``GET /api/v1/agent/parse/{task_id}``。
1221
+
1222
+ Args:
1223
+ task_id: 任务 ID(agent_create_url_task / agent_create_file_task
1224
+ 返回)
1225
+
1226
+ Returns:
1227
+ AgentParseResult: 任务状态与结果(state=done 时含 markdown_url)
1228
+
1229
+ Raises:
1230
+ MinerUError: 网络失败 / HTTP 非 200 / 业务错误码
1231
+
1232
+ Example:
1233
+ >>> result = MinerUKit.agent_get_result(task_id)
1234
+ >>> result.state
1235
+ 'done'
1236
+ """
1237
+ resp = cls._request(
1238
+ "GET",
1239
+ f"{cls._base_url()}/api/v1/agent/parse/{task_id}",
1240
+ headers=cls._agent_headers(),
1241
+ )
1242
+ data: dict[str, Any] = resp.get("data", {})
1243
+ return AgentParseResult(
1244
+ task_id=data.get("task_id", task_id),
1245
+ state=data.get("state", ""),
1246
+ markdown_url=data.get("markdown_url"),
1247
+ err_msg=data.get("err_msg"),
1248
+ err_code=data.get("err_code"),
1249
+ )
1250
+
1251
+ @classmethod
1252
+ def agent_wait_for_result(
1253
+ cls,
1254
+ task_id: str,
1255
+ *,
1256
+ poll_interval: float | None = None,
1257
+ timeout: int | None = None,
1258
+ ) -> AgentParseResult:
1259
+ """轮询等待轻量解析任务到达终态(done / failed)
1260
+
1261
+ Args:
1262
+ task_id: 任务 ID
1263
+ poll_interval: 轮询间隔秒数,None 时使用 MINERU_POLL_INTERVAL
1264
+ timeout: 总等待秒数,None 时使用 MINERU_MAX_WAIT
1265
+
1266
+ Returns:
1267
+ AgentParseResult: 终态结果(state=done 或 failed)
1268
+
1269
+ Raises:
1270
+ MinerUError: 超过总等待时间仍未到达终态
1271
+
1272
+ Example:
1273
+ >>> result = MinerUKit.agent_wait_for_result(task_id, timeout=300)
1274
+ """
1275
+ interval, max_wait, deadline = cls._make_poll_plan(poll_interval, timeout)
1276
+ warned_waiting_file = False
1277
+ while True:
1278
+ result = cls.agent_get_result(task_id)
1279
+ if result.state == _STATE_DONE:
1280
+ logger.info(f"✅ MinerU 轻量解析完成: {task_id}")
1281
+ return result
1282
+ if result.state == _STATE_FAILED:
1283
+ logger.error(
1284
+ f"❌ MinerU 轻量解析失败: {task_id}: "
1285
+ f"err_code={result.err_code}, {result.err_msg}"
1286
+ )
1287
+ return result
1288
+ if result.state == "waiting-file":
1289
+ # 仅首次提示(否则轮询期间刷屏),后续降为 debug
1290
+ log = logger.warning if not warned_waiting_file else logger.debug
1291
+ log(
1292
+ f"MinerU 轻量解析任务等待文件上传: {task_id},"
1293
+ f"请调用 agent_upload_file"
1294
+ )
1295
+ warned_waiting_file = True
1296
+ else:
1297
+ logger.debug(f"MinerU 轻量解析任务状态: {task_id} -> {result.state}")
1298
+ if time.monotonic() >= deadline:
1299
+ raise MinerUError(
1300
+ f"等待轻量解析任务 {task_id} 超时({max_wait} 秒),"
1301
+ f"最后状态: {result.state}"
1302
+ )
1303
+ time.sleep(interval)
1304
+
1305
+ @classmethod
1306
+ def agent_parse_url(
1307
+ cls,
1308
+ url: str,
1309
+ *,
1310
+ file_name: str | None = None,
1311
+ language: str | None = None,
1312
+ is_ocr: bool | None = None,
1313
+ enable_formula: bool | None = None,
1314
+ enable_table: bool | None = None,
1315
+ page_range: str | None = None,
1316
+ poll_interval: float | None = None,
1317
+ timeout: int | None = None,
1318
+ ) -> AgentParseResult:
1319
+ """轻量解析公网 URL 文件(提交 + 轮询一步到位)
1320
+
1321
+ agent_create_url_task 与 agent_wait_for_result 的组合封装,
1322
+ 参数含义见二者 docstring。
1323
+
1324
+ Args:
1325
+ url: 远程文件 URL(不支持 HTML)
1326
+ file_name: 文件名(含扩展名),缺省从 URL 自动解析
1327
+ language: 解析语言(仅对 PDF 生效)
1328
+ is_ocr: 是否启用 OCR(仅对 PDF 生效)
1329
+ enable_formula: 是否开启公式识别(仅对 PDF 生效)
1330
+ enable_table: 是否开启表格识别(仅对 PDF 生效)
1331
+ page_range: 页码范围(仅对 PDF 生效)
1332
+ poll_interval: 轮询间隔秒数
1333
+ timeout: 轮询总超时秒数
1334
+
1335
+ Returns:
1336
+ AgentParseResult: 终态结果(state=done 时含 markdown_url)
1337
+
1338
+ Raises:
1339
+ MinerUError: 网络失败 / HTTP 非 200 / 轮询超时
1340
+
1341
+ Example:
1342
+ >>> result = MinerUKit.agent_parse_url(
1343
+ ... "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
1344
+ ... )
1345
+ >>> print(result.state, result.markdown_url)
1346
+ """
1347
+ task_id = cls.agent_create_url_task(
1348
+ url,
1349
+ file_name=file_name,
1350
+ language=language,
1351
+ is_ocr=is_ocr,
1352
+ enable_formula=enable_formula,
1353
+ enable_table=enable_table,
1354
+ page_range=page_range,
1355
+ )
1356
+ return cls.agent_wait_for_result(
1357
+ task_id, poll_interval=poll_interval, timeout=timeout
1358
+ )
1359
+
1360
+ @classmethod
1361
+ def agent_parse_file(
1362
+ cls,
1363
+ file_path: str | Path,
1364
+ *,
1365
+ language: str | None = None,
1366
+ is_ocr: bool | None = None,
1367
+ enable_formula: bool | None = None,
1368
+ enable_table: bool | None = None,
1369
+ page_range: str | None = None,
1370
+ poll_interval: float | None = None,
1371
+ timeout: int | None = None,
1372
+ ) -> AgentParseResult:
1373
+ """轻量解析本地文件(申请签名 + 上传 + 轮询一步到位)
1374
+
1375
+ agent_create_file_task + agent_upload_file + agent_wait_for_result
1376
+ 的组合封装。文件须 ≤10MB 且页数 ≤20 页(扩展名/大小本地强制校验,
1377
+ 页数由服务端校验)。
1378
+
1379
+ Args:
1380
+ file_path: 本地文件路径(≤10MB,扩展名受轻量接口支持)
1381
+ language: 解析语言(同 agent_create_url_task)
1382
+ is_ocr: 是否启用 OCR(同 agent_create_url_task)
1383
+ enable_formula: 是否开启公式识别(同 agent_create_url_task)
1384
+ enable_table: 是否开启表格识别(同 agent_create_url_task)
1385
+ page_range: 页码范围(同 agent_create_url_task)
1386
+ poll_interval: 轮询间隔秒数
1387
+ timeout: 轮询总超时秒数
1388
+
1389
+ Returns:
1390
+ AgentParseResult: 终态结果(state=done 时含 markdown_url)
1391
+
1392
+ Raises:
1393
+ ValueError: 文件格式或大小不符合轻量接口限制
1394
+ FileNotFoundError: 文件不存在
1395
+ MinerUError: 网络失败 / HTTP 非 200 / 轮询超时
1396
+
1397
+ Example:
1398
+ >>> result = MinerUKit.agent_parse_file("demo.pdf")
1399
+ >>> print(result.state, result.markdown_url)
1400
+ """
1401
+ path = cls._check_agent_file(file_path)
1402
+ info = cls.agent_create_file_task(
1403
+ path.name,
1404
+ language=language,
1405
+ is_ocr=is_ocr,
1406
+ enable_formula=enable_formula,
1407
+ enable_table=enable_table,
1408
+ page_range=page_range,
1409
+ )
1410
+ cls.agent_upload_file(path, info.file_url)
1411
+ return cls.agent_wait_for_result(
1412
+ info.task_id, poll_interval=poll_interval, timeout=timeout
1413
+ )
1414
+
1415
+ @classmethod
1416
+ def download_markdown(
1417
+ cls, markdown_url: str, dest_dir: str | Path, filename: str | None = None
1418
+ ) -> str:
1419
+ """下载轻量解析结果 Markdown 到本地
1420
+
1421
+ Args:
1422
+ markdown_url: Markdown 结果 CDN 地址(AgentParseResult.markdown_url)
1423
+ dest_dir: 目标目录(不存在时自动创建)
1424
+ filename: 保存文件名,None 时从 URL 末段推断(非 .md 后缀自动补全)
1425
+
1426
+ Returns:
1427
+ str: 保存的本地文件绝对路径
1428
+
1429
+ Raises:
1430
+ MinerUError: 网络失败或 HTTP 非 200
1431
+
1432
+ Example:
1433
+ >>> MinerUKit.download_markdown(result.markdown_url, "./output")
1434
+ """
1435
+ dest = Path(dest_dir)
1436
+ dest.mkdir(parents=True, exist_ok=True)
1437
+ name = filename or markdown_url.rstrip("/").split("/")[-1] or "full.md"
1438
+ if not name.endswith(".md"):
1439
+ name = f"{name}.md"
1440
+ target = (dest / name).resolve()
1441
+ logger.info(f"下载 MinerU 轻量解析结果: {markdown_url}")
1442
+ try:
1443
+ resp = requests.get(
1444
+ markdown_url, timeout=cls._transfer_timeout(), stream=True
1445
+ )
1446
+ except requests.RequestException as e:
1447
+ logger.error(f"下载失败: {e}")
1448
+ raise MinerUError(f"Markdown 下载失败: {e}") from e
1449
+ try:
1450
+ if resp.status_code != 200:
1451
+ raise MinerUError(f"Markdown 下载失败: HTTP {resp.status_code}")
1452
+ with open(target, "wb") as f:
1453
+ for chunk in resp.iter_content(chunk_size=1024 * 1024):
1454
+ if chunk:
1455
+ f.write(chunk)
1456
+ finally:
1457
+ resp.close()
1458
+ logger.info(f"✅ Markdown 已保存: {target}({target.stat().st_size} 字节)")
1459
+ return str(target)
1460
+
1461
+ # ------------------------------------------------------------------
1462
+ # 校验辅助
1463
+ # ------------------------------------------------------------------
1464
+
1465
+ @staticmethod
1466
+ def is_supported(file_path: str | Path) -> bool:
1467
+ """检查文件格式是否受支持(依据扩展名)
1468
+
1469
+ Args:
1470
+ file_path: 文件路径或文件名
1471
+
1472
+ Returns:
1473
+ bool: 扩展名在支持列表中返回 True
1474
+
1475
+ Example:
1476
+ >>> MinerUKit.is_supported("report.pdf")
1477
+ True
1478
+ """
1479
+ return Path(file_path).suffix.lower() in MinerUKit.SUPPORTED_EXTENSIONS
1480
+
1481
+ @staticmethod
1482
+ def is_agent_supported(file_path: str | Path) -> bool:
1483
+ """检查文件格式是否受 Agent 轻量解析支持(依据扩展名)
1484
+
1485
+ Args:
1486
+ file_path: 文件路径或文件名
1487
+
1488
+ Returns:
1489
+ bool: 扩展名在 Agent 轻量解析集合中返回 True
1490
+
1491
+ Example:
1492
+ >>> MinerUKit.is_agent_supported("report.xlsx")
1493
+ True
1494
+ >>> MinerUKit.is_agent_supported("report.doc")
1495
+ False
1496
+ """
1497
+ return Path(file_path).suffix.lower() in MinerUKit.AGENT_SUPPORTED_EXTENSIONS