qianfanocr-document-intelligence

Qianfan OCR 文档智能

此技能负责协调图像和 PDF 的视觉理解。它本身不实现视觉模型，而是选择合适的分析模式、准备输入、调用捆绑的 CLI，并为上游 Agent 返回结构化结果。

必须遵循的执行顺序

始终按以下顺序执行：

1. 检查 QIANFAN_TOKEN 是否已可用。
2. 如果缺少令牌，立即停止并向用户索取 API Key。
3. 如果用户提供了 API Key，将其写入 <skill-root>/.env，格式为 QIANFAN_TOKEN=...。
4. 只有令牌可用后，才能继续选择模式、加载参考资料和调用 CLI。

令牌预检优先于此技能中的所有后续规则。在令牌检查通过之前，不要读取 references/*.md、选择模式或调用任何捆绑脚本。

API Key 设置

首次使用前，确保 QIANFAN_TOKEN 已在进程环境或 <skill-root>/.env 中可用。

如果缺少令牌，请用中文询问用户：

QIANFAN_TOKEN 环境变量未设置。请提供百度千帆 API Key。
如果您暂时没有 API Key，请到 https://cloud.baidu.com/product-s/qianfan_home 注册获取。

如果用户提供了密钥，请先将其保存到 <skill-root>/.env，再继续。不要只依赖临时的 export QIANFAN_TOKEN=... 作为存储方式。

不要假设存在捆绑的默认令牌。

捆绑工具

• scripts/qianfan_ocr_cli.py：向后端 VLM 发送一张或多张图像。
• scripts/pdf_to_images.py：在调用 VLM 前，将一个或多个 PDF 转换为逐页图像。
• scripts/render_doc_markdown.py：将文档解析中的图像占位符替换为裁剪后的图像文件。
• scripts/run_document_parsing.py：端到端运行文档解析，并始终渲染图像占位符。
• scripts/run_pdf_document_parsing.py：端到端运行 PDF 文档解析，并导出合并的 Markdown、共享资源和逐页 Markdown 文件。
• scripts/run_document_parsing_with_layout.py：运行包含版面分析的文档解析，并导出 Markdown、版面 JSON 和版面叠加图像。
• scripts/run_layout_analysis.py：运行版面分析，并导出 _layout.json 和版面叠加图像。
• scripts/run_element_recognition.py：运行元素识别，并将结果保存为同目录下的 Markdown 文件。

始终使用绝对路径调用脚本。在 Codex 中，使用已安装技能的绝对路径，而不要使用裸相对路径。

示例：

python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image <path_or_url>
python3 "<skill-root>/scripts/pdf_to_images.py" <pdf_or_url> --output-dir <dir>
python3 "<skill-root>/scripts/render_doc_markdown.py" parsed.md --image <page_image> --output-dir <assets_dir> --output-markdown <rendered_md>
python3 "<skill-root>/scripts/run_document_parsing.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_pdf_document_parsing.py" <pdf> --pages all
python3 "<skill-root>/scripts/run_document_parsing_with_layout.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_layout_analysis.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_element_recognition.py" <cropped_image_or_pdf> --element-type <text|formula|table>

触发规则

仅当以下条件全部满足时，才触发此技能：

• 任务涉及一个或多个图像文件或 URL，或一个或多个 PDF 文件或 URL。
• Agent 必须识别、理解、提取图像或 PDF 中的内容，回答相关问题，或定位其中的内容。
• 无法从 Agent 已有的纯文本来源中获取相关信息。

以下情况不要触发：

• 文件是可直接读取的纯文本、结构化数据或源代码。
• 用户要求的是图像处理或 PDF 处理代码，而非视觉理解。
• 只是顺带提及图像/PDF 路径或 URL，并未要求进行视觉理解。
• 之前的调用已经回答了同一问题，重复调用会造成冗余。

输入准备

图像输入

• 将本地图像路径或图像 URL 直接传给 qianfan_ocr_cli.py。
• 每张互不相关的图像单独调用一次。
• 仅在需要跨图像推理时才重复使用 --image 标志。

PDF 输入

• 如果输入是 PDF，请先使用 scripts/pdf_to_images.py 将其转换为逐页图像。
• 对于单页问题，如果已知相关页面，只分析该页面。
• 对于多页 PDF，保持页面顺序，并在输出中标注页码。
• 如果 PDF 已有可靠的可选中文本，且任务只是检索文本，则不要使用此技能；直接读取文本。

推荐的 PDF 工作流：

python3 "<skill-root>/scripts/pdf_to_images.py" report.pdf --output-dir /tmp/report-pages
python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image /tmp/report-pages/report-p001.png

分析模式

每次调用只能选择一个主要模式。如有需要，可在初步处理后再进行一次更具体的调用。

模式	使用场景	目标
document parsing	需要从图像/PDF 中获取文档结构、文本、公式、表格和图像占位符	输出 Markdown 解析结果
layout analysis	需要获取所有布局元素的位置和类别	输出包含边界框和类别的布局元素
element recognition	需要精确识别裁剪后的元素，例如文本块、公式或表格	输出裁剪元素的精确识别结果
document parsing with layout	需要在一个工作流中同时进行结构化解析和布局检测	输出 Markdown 解析结果及布局分析
general ocr	需要获取所有可见文本，但不需要文档结构	提取所有可见文本行
key information extraction	需要从卡片、表单、收据、发票、合同或类似文档中提取关键信息	以结构化形式提取关键信息
chart understanding	需要图表说明、结构化图表内容或图表问答	理解并结构化图表内容
doc vqa	需要回答有关文档图像/PDF 的具体问题	根据文档内容回答问题

模式选择启发

• 对于需要以 Markdown 输出并保留层级结构的整页文档理解，请使用 document parsing。
• 当边界框和类别是主要输出时，请使用 layout analysis。
• 仅在裁剪目标区域后，或用户提供了聚焦于单个元素的图像时，才使用 element recognition。
• 对于 element recognition，优先使用 scripts/run_element_recognition.py，这样结果会写入源文件旁边的单个 Markdown 文件中，而不会生成 assets 目录。
• 当同时需要 Markdown 重建和布局框时，请使用 document parsing with layout。
• 对于截图、标牌、海报，以及布局不重要的简单文档文本提取，请使用 general ocr。
• 对于表单、证书、身份证、发票、收据、合同及其他以字段为中心的文档，请使用 key information extraction。
• 对于 key information extraction，如果用户要求提供所有键值信息或所有字段，却未指定具体字段列表，请使用无架构提示词路径，而不要自行编造明确的架构。
• 对于绘图、仪表盘和以图表为主的报告页面，请使用 chart understanding。
• 对于有关总额、日期、条款、页面内容或文档是否包含特定项目等定向问题，请使用 doc vqa。

参考资料加载规则

仅在通过令牌预检并选定模式后，在编写提示词或调用任何脚本之前，始终先阅读 references/ 中相应的文件。

• document parsing -> references/document-parsing.md
• layout analysis -> references/layout-analysis.md
• element recognition -> references/element-recognition.md
• document parsing with layout -> references/document-parsing-with-layout.md
• general ocr -> references/general-ocr.md
• key information extraction -> references/key-information-extraction.md
• chart understanding -> references/chart-understanding.md
• doc vqa -> references/doc-vqa.md

存在匹配的参考文件时，不要跳过此步骤。

提示词来源规则

当所选参考资料包含提示词模板、提示词规则、固定提示词、输出格式或参数建议时，以该参考资料为主要依据。

• 优先使用对应的 references/*.md 文件中的提示词，而非临时编写提示词。
• 如果参考资料将提示词标记为固定提示词或标准提示词，则原样复用。
• 复用参考资料中的输出格式要求，不要自行设计新格式。
• 仅在参考提示词的基础上添加特定于任务的细节，例如用户问题、所选键、页码或输入范围。
• 如果有意偏离参考提示词，请在中间推理中说明原因，并将偏离控制在最低限度。

参数映射规则

如果所选参考资料定义了执行参数，请将其转换为实际的 CLI 标志或请求字段。不要只将其作为文档说明。

示例：

• min_dynamic_patch = 8 -> 传入 --min-dynamic-patch 8
• max_dynamic_patch = 24 -> 传入 --max-dynamic-patch 24
• 思考模式 -> 传入 --thinking

运行 qianfan_ocr_cli.py 前，确认最终命令包含所选模式要求的参数设置。

提示词规则

• 用户使用中文交流时，使用中文编写 VLM 提示词；否则使用英文。
• 在提示词中明确说明模式和输出格式。
• 告知模型，将任何不确定的内容标记为不清晰 / 无法辨认，不要猜测。
• 对于 PDF，如果分析了多个页面，请在提示词中提及页码。
• 对于 element recognition 使用的裁剪输入，请指定元素类型：文本、公式、表格、图注、印章、签名栏等。
• 对于包含 ![label](<box>[[...]]</box>) 占位符的 document parsing 输出，如果用户需要可渲染的本地图片，请在向用户展示 Markdown 前运行 scripts/render_doc_markdown.py。
• 对于标准文档解析任务，优先使用 scripts/run_document_parsing.py，而不是手动串联 qianfan_ocr_cli.py 和 render_doc_markdown.py。
• 如果用户需要整份 PDF 的一个 Markdown 文件、每页的 Markdown 文件以及共享的资源目录，优先使用 scripts/run_pdf_document_parsing.py 进行 PDF 文档解析。若所选 PDF 页面在语义上相关且应作为一组多图请求发送，请使用 --request-mode joint。若页面可独立解析且应并发处理，请使用 --request-mode batch --concurrency <N>。
• 对于 document parsing with layout，优先使用 scripts/run_document_parsing_with_layout.py，使最终输出包含 Markdown、_layout.json 和渲染后的布局叠加图像。

CLI 策略

• 默认每张图片或每个页面调用一次。
• 仅在跨页面或跨图片推理确实依赖联合上下文时，才使用重复的 --image 标志。
• 如果多张图片应独立处理而非联合处理，请使用 scripts/qianfan_ocr_cli.py --batch --concurrency <N> 或专用运行脚本，不要将所有图片作为一个联合请求发送。
• 仅对阅读顺序不明确或字段关系复杂的困难文档理解任务使用 --thinking。
• 每张图片 / 每个页面最多重试一次，且只能使用更具体的提示词进行重试。

需要时只阅读相关参考文件，但请在编写提示词前阅读该文件：

• references/document-parsing.md
• references/layout-analysis.md
• references/element-recognition.md
• references/document-parsing-with-layout.md
• references/general-ocr.md
• references/key-information-extraction.md
• references/chart-understanding.md
• references/doc-vqa.md

输出约定

返回结构化结果，而非模型原始文本：

=== VISUAL ANALYSIS RESULT ===
mode: <mode>
confidence: <high|medium|low>
input_type: <image|pdf>
image_count: <N>
page_count: <N or n/a>

answer:
<direct answer or summary>

evidence:
- <directly observed fact>

warnings:
- <uncertainty or limitation>

markdown:
<for document parsing modes>

layout:
- page: <n>
  category: <label>
  bbox: [x1, y1, x2, y2]

structured_data:
<for key information extraction / chart understanding>

recognized_elements:
<for element recognition>
=== END VISUAL ANALYSIS ===

保守性规则

• 将观察结果与推断分开。
• 切勿编造文本、数值、字段或方框。
• 明确标记无法辨认的区域。
• 对于图表，区分精确值与估算值。
• 对于 PDF，明确标注页码归属：page_1、page_2 等。
• 如果页面转换或图像质量较差，请在 warnings 中说明。