DocMind 文档解析

两种调用模式

1. 免费模式（V2 API 直连）：通过 DOCMIND_V2_ENDPOINT 环境变量配置服务端点；享有每日有限的免费配额。
2. 阿里云 POP 模式：凭证自动通过阿里云默认凭证链获取；每月免费 3,000 页，超出后按量付费。

路由策略

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

环境变量

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

使用方法

python scripts/docmind_parse.py  [options]

参数说明

使用示例

# 解析一个 URL（自动选择模式）
python scripts/docmind_parse.py https://example.com/doc.pdf

# 使用 VLM 增强模式解析
python scripts/docmind_parse.py https://example.com/doc.pdf --enhancement VLM

# 仅解析前 5 页，并输出为 Markdown 文件
python scripts/docmind_parse.py ./report.pdf --pages 1-5 --output-file result.md

# 通过 V2 模式解析本地文件（自动 base64 编码）
python scripts/docmind_parse.py ./contract.pdf --mode v2

# 自定义表格与图片输出格式
python scripts/docmind_parse.py https://example.com/doc.pdf --markdown-table markdown --markdown-image html

# 解析页眉页脚并使用自定义提示词
python scripts/docmind_parse.py https://example.com/doc.pdf --head-foot --user-prompt "提取所有脚注"

# 强制使用阿里云 POP 模式
python scripts/docmind_parse.py ./contract.pdf --mode pop

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

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

提交端点

POST {DOCMIND_V2_ENDPOINT}/skill/submit

完整请求结构如下：

{
  "document": {
    "fileUrl": "https://example.com/doc.pdf",
    "fileBase64": "",
    "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)

配额说明

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

错误处理

预校验与异常处理

在调用脚本前，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 输出

各 layout 区块的 markdownContent 字段被拼接输出；表格以内嵌 HTML 表格形式呈现。

JSON 输出

原始 layout 结构化数据，包括 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。

所有使用相同 SKILL_SESSION_ID 值的技能调用，在服务端日志中将被关联为同一会话。

依赖安装

# POP 模式
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 模式
pip install "requests>=2.20.0"