alibabacloud-docmind-parse

DocMind 文档解析

两种调用模式

1. 免费模式（直接调用 V2 API）：通过 DOCMIND_V2_ENDPOINT 环境变量配置端点；每日免费额度有限。
2. 阿里云 POP 模式：通过默认凭证链自动获取凭证；每月免费解析 3,000 页，超出部分按量付费。

路由策略

• 当阿里云默认凭证链可用时，优先使用 POP 模式。
• 当凭证不可用，但已配置 DOCMIND_V2_ENDPOINT 时，使用 V2 免费模式。
• 免费额度用尽时，提示用户开通阿里云 DocMind 服务。

环境变量

变量	描述	必需
DOCMIND_V2_ENDPOINT	V2 API 服务端点（域名或 IP）。默认为 docmind.aliyuncs.com	可选

POP 模式通过阿里云默认凭证链自动获取凭证（环境变量、配置文件、ECS RAM 角色等），无需手动管理。

---

用法

python scripts/docmind_parse.py <file_path_or_url> [options]

参数

参数	描述	默认值
<file_path_or_url>	本地文件路径或文件 URL	必需
--mode	调用模式：auto、v2、pop	auto
--enhancement	增强模式：VLM、LLM、DIGITAL、OCR、AUTO	无
--output	输出格式：markdown、json、html	markdown
--pages	要解析的页码范围，例如 1-5	全部
--output-file	输出文件路径	标准输出
--head-foot	解析页眉和页脚	关闭
--user-prompt	自定义用户提示词	无
--option	文档解析选项	无
--markdown-table	表格输出格式：html、markdown	无
--markdown-image	图片输出格式：html、markdown	无
--file-ext	文件扩展名（fileName 的替代项）	自动检测

示例

# Parse a URL (auto-select mode)
python scripts/docmind_parse.py https://example.com/doc.pdf

# Parse with VLM enhancement
python scripts/docmind_parse.py https://example.com/doc.pdf --enhancement VLM

# Parse the first 5 pages, output to a Markdown file
python scripts/docmind_parse.py ./report.pdf --pages 1-5 --output-file result.md

# Parse a local file via V2 mode (auto base64 encoding)
python scripts/docmind_parse.py ./contract.pdf --mode v2

# Parse with custom table/image output formats
python scripts/docmind_parse.py https://example.com/doc.pdf --markdown-table markdown --markdown-image html

# Parse headers and footers with a custom prompt
python scripts/docmind_parse.py https://example.com/doc.pdf --head-foot --user-prompt "Extract all footnotes"

# Force Alibaba Cloud POP mode
python scripts/docmind_parse.py ./contract.pdf --mode pop

---

直接访问 V2 API（免费模式）

支持通过 URL 和本地文件（base64）上传。请求体分为四个部分：文档、处理、输出和通知。

提交端点

POST {DOCMIND_V2_ENDPOINT}/skill/submit

完整请求架构：

{
  "document": {
    "fileUrl": "https://example.com/doc.pdf",
    "fileBase64": "<base64-encoded file content, alternative to fileUrl>",
    "fileName": "doc.pdf",
    "fileNameExtension": "pdf"
  },
  "processing": {
    "enhancementMode": "VLM",
    "pageIndex": "1-5",
    "headFoot": false,
    "userPrompt": "Custom prompt",
    "option": "parsing-option"
  },
  "output": {
    "outputFormat": ["markdown"],
    "markdownTable": ["html"],
    "markdownImage": ["html"],
    "docExtraParameters": {"key": "value"},
    "extraParameters": "audio-video-extra-params",
    "ossConfig": {
      "bucket": "my-bucket",
      "endpoint": "oss-cn-hangzhou.aliyuncs.com",
      "accessKeyId": "...",
      "accessKeySecret": "...",
      "securityToken": "..."
    }
  },
  "notification": {
    "enableEventCallback": false
  }
}

document.fileUrl 和 document.fileBase64 不能同时使用。通过 V2 模式解析本地文件时，脚本会自动读取文件并将其编码为 base64。未明确提供 fileNameExtension 时，会根据文件扩展名自动检测。

响应：

{
  "success": true,
  "data": { "bizId": "docmind-20260519-xxxx" }
}

查询端点

POST {DOCMIND_V2_ENDPOINT}/skill/query

{
  "bizId": "docmind-20260519-xxxx",
  "layoutStepSize": 100,
  "layoutNum": 0
}

响应（成功时）：

{
  "success": true,
  "data": {
    "status": "success",
    "processing": 100.0,
    "layouts": [ ... ]
  }
}

速率限制：每个 IP 每秒最多 5 个任务，全局限制为 20。

---

阿里云 POP 调用

使用默认凭证链初始化客户端的三步异步工作流：

1. 提交任务 - SubmitDocParserJob / SubmitDocParserJobAdvance
2. 查询状态 - QueryDocParserStatus（轮询直至成功或失败）
3. 获取结果 - GetDocParserResult（通过 LayoutNum + LayoutStepSize 分页增量获取）

POP 端点：docmind-api.cn-hangzhou.aliyuncs.com，API 版本：2022-07-11

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_docmind_api20220711.client import Client as DocMindClient

cred = CredClient()
config = open_api_models.Config(
    credential=cred,
    endpoint="docmind-api.cn-hangzhou.aliyuncs.com",
    user_agent="AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/" + os.environ.get("SKILL_SESSION_ID", "unknown")
)
client = DocMindClient(config)

---

配额

模式	免费额度	用尽后
直接调用 V2 API	每日额度有限	提示开通阿里云服务
阿里云 POP	每月 3,000 页	自动按量付费

配额用尽时，提示用户访问 https://docmind.console.aliyun.com/doc-overview 开通服务。

---

错误处理

错误代码	含义	解决方法
QuotaExhausted / Throttling	配额已用尽或请求受到速率限制	提示用户启用阿里云服务
FileUrlLegal	文件 URL 无效	确认该 URL 可公开访问
InvalidFileFormat	不支持的文件格式	显示支持格式列表
FileSizeExceeded	文件过大	V2 限制为 5 MB，POP 限制为 150 MB
OssAccessDeniedError / HTTP 403	URL 指向私有或受限的 OSS 资源	请参阅下方的预验证规则

预验证与异常处理

调用脚本前，Agent 必须执行以下检查：

1. 本地文件路径验证：如果输入是本地文件路径，请在调用脚本前确认文件存在且可读。如果文件不存在，立即停止并请用户核实路径。Agent 绝不能创建、伪造或替换文件来绕过文件缺失错误。

2. 私有 URL 检测：如果输入是 URL，且 V2 模式返回 OssAccessDeniedError 或 HTTP 403，则该 URL 可能是私有的或需要身份验证。此时：

   • 告知用户该 URL 无法公开访问。
   • 请用户提供可公开访问的 URL，或将文件下载到本地后使用本地路径重新运行——脚本会自动将其编码为 base64，并通过 V2 上传（--mode v2 会透明地处理 base64 编码）。

3. 网络无法连接：如果脚本因连接错误（例如 ConnectionError、ConnectionRefused）而失败，请检查：

   • 当前环境是否可以访问 DOCMIND_V2_ENDPOINT（默认值为 docmind.aliyuncs.com）。
   • 代理设置或防火墙规则是否阻止了出站 HTTPS 流量。

---

支持的文件格式

• 文档：PDF、Word（doc/docx）、PPT（ppt/pptx）、Excel（xls/xlsx/xlsm）
• 图像：JPG、JPEG、PNG、BMP、GIF
• 其他：Markdown、HTML、EPUB、MOBI、RTF、TXT
• 音频/视频（仅 POP 模式）：MP4、MKV、AVI、MOV、WMV、MP3、WAV、AAC

---

输出格式

Markdown 输出

将每个布局块的 markdownContent 字段拼接起来；表格以内嵌 HTML 表格的形式呈现。

JSON 输出

原始布局结构化数据，包括 type/subType、text、markdownContent、pageNum、index、pos 等字段。

---

可观测性

所有出站 HTTP 请求（V2 API 和阿里云 POP SDK）都会设置以下 User-Agent 标头：

AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/{session-id}

{session-id} 部分在运行时从 SKILL_SESSION_ID 环境变量中读取。如果未设置该变量，则回退为 unknown。

组件	值
UA 模板	AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/{session-id}
session-id 来源	SKILL_SESSION_ID 环境变量
回退值	unknown
环境变量示例	export SKILL_SESSION_ID=agent-abc123-session-xyz

共享相同 SKILL_SESSION_ID 值的所有技能调用，在服务端日志中都会关联为同一个会话。

---

依赖项安装

# POP mode
pip install "alibabacloud-docmind-api20220711>=1.0.0" \
            "alibabacloud-credentials>=1.0.0" \
            "alibabacloud-tea-openapi>=0.3.8" \
            "alibabacloud-tea-util>=0.3.0" \
            "alibabacloud-gateway-pop>=0.1.0"

# V2 mode
pip install "requests>=2.20.0"