document-granular-decompose

文档粒度分解

核心目标

• 通过 POST /mineru_with_images 解析本地文档。
• 始终强制设置 return_txt=true。
• 从环境变量读取端点、请求身份和模型路由信息：
  • UNSTRUCTURED_API_BASE_URL（示例：https://your-unstructured-host:7770）
  • UNSTRUCTURED_AUTH_TOKEN
  • UNSTRUCTURED_PROVIDER（可选）
  • UNSTRUCTURED_MODEL（可选）
• 仅返回纯文本全文（优先使用 API 的 txt；否则拼接 result[].text）。

触发条件

• 需要从 PDF、Office 或图像文件中稳健地提取文档全文。
• 需要使用 MinerU 解析图像内容，但仅向下游分块、搜索或摘要步骤输出文本。
• 需要通过环境变量统一输入 provider、model 和 token，而不是使用临时命令参数。

工作流

1. 准备环境变量。

export UNSTRUCTURED_AUTH_TOKEN="your-fastapi-bearer-token"
export UNSTRUCTURED_API_BASE_URL="https://your-unstructured-host:7770"
# Optional routing overrides. Omit them to let the server choose its defaults.
export UNSTRUCTURED_PROVIDER="vllm"
export UNSTRUCTURED_MODEL="Qwen/Qwen3.5-122B-A10B-FP8"

2. 运行提取并将全文打印到 stdout。

python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf"

3. 需要时将全文保存到本地文件。

python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf" \
  --output "/absolute/path/to/fulltext.txt"

请求约定

• 端点解析：
  • 如果提供了 --api-url，则使用它
  • 否则使用 UNSTRUCTURED_API_BASE_URL + /mineru_with_images
  • 否则快速失败，并提示缺少环境变量
• 方法：POST multipart form。
• 查询参数：
  • 强制设置 return_txt=true（始终由脚本设置）。
• 发送的表单字段：
  • file（必填）
  • provider（可选；设置了 UNSTRUCTURED_PROVIDER 时使用）
  • model（可选；设置了 UNSTRUCTURED_MODEL 时使用）
• 发送的标头：
  • Authorization: Bearer $UNSTRUCTURED_AUTH_TOKEN

支持的文件类型（严格）

• 支持的文件类型：
  • .bmp, .doc, .docm, .docx, .dot, .dotx, .gif, .jp2, .jpeg, .jpg, .odp, .odt, .pdf, .png, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .tiff, .webp, .xls, .xlsm, .xlsx, .xlt, .xltx
• Office 格式：
  • .doc, .docm, .docx, .dot, .dotx, .odp, .odt, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .xls, .xlsm, .xlsx, .xlt, .xltx
• 发送 API 请求前会拒绝任何其他扩展名。

输出规则

• 成功时只能输出纯文本全文。
• 在两种受支持的响应路径中，都将已确认的上游 Markdown 下划线转义 \_ 规范化为 _；保留其他反斜杠和转义字符。
• 全文来源优先级：
  1. response.txt
  2. 使用空行拼接非空的 response.result[].text
• 除非用户明确请求调试信息，否则不要输出分块元数据或 JSON。

错误处理

• 缺少必需的环境变量（UNSTRUCTURED_API_BASE_URL、UNSTRUCTURED_AUTH_TOKEN）：快速失败并提供可执行的提示。
• 缺少 UNSTRUCTURED_PROVIDER 或 UNSTRUCTURED_MODEL：省略相应表单字段，由服务选择默认值。
• HTTP 401/403：报告 token/身份验证问题。
• HTTP 4xx/5xx：打印状态码，以及 API 错误正文（若有）。
• 响应中缺少文本：失败并明确提示架构不匹配错误。

参考资料

• references/env.md
• references/request-response.md

资源

• assets/config.example.env

脚本

• scripts/mineru_fulltext_extract.py