docling-graph

Docling Graph

当任务明确涉及 Docling Graph 时，请使用此技能：将文档转换为带类型的 Pydantic 知识图谱、审查模板、选择抽取契约、调整流水线配置、检查／调试抽取运行，以及导出图谱结果。

不要将其用于通用 Docling 文档解析、仅使用向量的 RAG、图数据库管理、不涉及 Docling Graph 运行的纯本体建模，或无关的 PDF 工具。

分派

将 $ARGUMENTS 解读为 [mode] [source-or-template-or-question] [options]。如果 $ARGUMENTS 为空，请询问最少的缺失上下文，不要擅自假设文档、提供方或抽取契约。

$ARGUMENTS 模式	模式	产出内容
plan [documents/domain]	计划	端到端工作流计划、模板策略、提供方／配置选择、验证路径
template [domain]	模板	Pydantic 图谱模板，或包含稳定 ID 和关系提示的审查说明
`contract [direct	staged	delta] [domain]`
convert [source] [template]	转换	CLI／API 运行方案，包含输入、提供方／模型覆盖项、输出路径和验证
api [source] [template]	API	使用 PipelineConfig 和显式覆盖字段的 Python 集成
inspect [output-path]	检查	针对现有或计划输出目录的 HTML／调试检查工作流
export [output]	导出	JSON／CSV／Cypher／NetworkX 导出及导出后检查
debug [error-or-output]	调试	使用日志、debug/trace_data.json、阶段产物和架构检查的根因排查路径
batch [folder]	批处理	面向大量文档的扩展方案，涵盖清单、重试、幂等性和 QA 抽样
自然语言	自动检测	先分类，再运行匹配的模式
空／不明确	澄清	询问文档类型、目标图谱、运行方式和提供方限制

自动检测

1. 提到 direct、staged、delta、抽取契约、结构化输出、架构强制、稀疏检查、gleaning 或流式处理 -> 契约。
2. 提到 inspect、HTML 报告、trace_data.json、调试产物、输出目录审查或图谱映射失败 -> 检查或调试。
3. 提到 Pydantic 模型、BaseModel、Field、关系、实体或 edge() -> 模板。
4. 提到命令行、docling-graph convert、提供方／模型标志、源文件路径或输出目录 -> 转换。
5. 提到 PipelineConfig、run_pipeline、Python 集成、provider_override、model_override 或编程式运行 -> API。
6. 提到图谱导出、Cypher、Neo4j、NetworkX、CSV 或图谱 JSON -> 导出。
7. 提到文件夹、大量 PDF、重试、吞吐量、清单或 QA 抽样 -> 批处理。
8. 否则，请先提出一个简洁的澄清问题，再给出工作流建议。

示例集

用户提问	回复模式
“为 SEC 文件创建模板”	生成包含图谱 ID 字段、关系字段、抽取说明和验证清单的 Pydantic 模型。
“这应该使用分阶段抽取吗？”	根据架构大小、嵌套、基数、提供方限制和调试成本，对比直接、分阶段和增量契约。
“用 OpenAI 运行这个 PDF”	提供 docling-graph convert 命令及对应的 API 方案，包含提供方／模型覆盖项和输出检查。
“审查这个输出文件夹”	检查 inspect、图谱 JSON、debug/trace_data.json、阶段产物以及架构／稀疏检查结果。
“图谱缺少关系”	排查模板关系建模、抽取契约、结构化输出回退、gleaning 和图谱映射产物。
“导出到 Neo4j”	生成导出步骤，并检查唯一性约束、ID 规范化和关系数量。

工作流

1. 判定范围

每次回复都先判断任务是否与 Docling Graph 相关。

• 属于范围：文档到类型化知识图谱的提取、Pydantic 图模板、docling-graph CLI/API 运行、提取契约、检查/调试产物以及图导出。
• 不属于范围：纯 Docling 转换、仅嵌入的工作流、通用 LLM 提取、图数据库调优，以及不涉及 Docling Graph 执行的本体设计。

如果不属于范围，请说明边界，并推荐最接近且合适的技能或工作流。

2. 收集最少必要输入

仅在缺少的信息会影响答案时才询问：

• 文档类型和示例：PDF/HTML/DOCX/图像、预期长度、扫描版还是数字版、表格密度。
• 图谱目标：实体、关系、ID、必填字段、下游使用方。
• 模板状态：没有、Pydantic 模型草稿、现有包/模块，或无法运行的模板。
• 运行方式：CLI、Python API、批处理、CI 或 notebook。
• 提供方限制：OpenAI、Mistral、Gemini、Watsonx、本地 Ollama/vLLM/LM Studio，以及隐私/成本/延迟限制。
• 提取契约：direct、staged、delta 或尚未确定。
• 调试上下文：命令/API 配置、输出目录、日志、debug/trace_data.json 和具体错误。

3. 选择提取契约

Docling Graph 支持三种契约风格。对于非简单工作流，请明确选择。

契约	适用情况	主要风险	必要检查
direct	架构较小且稳定、嵌套有限、提供方可在一次处理中处理完整架构	上下文溢出、关系覆盖不足	架构适配性、稀疏检查结果、字段覆盖率
staged	模板较大，且包含清晰的分区或嵌套实体组	阶段边界可能导致跨阶段链接丢失	各阶段输出、根节点合并规则、关系数量
delta	图谱复杂/高基数、源顺序较弱，或需要增量丰富	解析器质量和稳定 ID 对正确性影响最大	ID 策略、解析器配置、重复实体检查

如果提供方支持，应优先使用结构化输出和架构约束。如果不可用或不稳定，请记录回退解析器、稀疏检查设置以及额外的验证步骤。对于重视召回率的提取，请使用 gleaning；对于需要实时查看进度或取消状态的长时间运行任务，请启用 LLM 流式传输。

4. 执行模式协议

规划

返回：

1. 文档和图谱假设。
2. 模板大纲和稳定 ID 策略。
3. 契约选择，并说明选择 direct/staged/delta 的理由。
4. CLI/API 运行方式、提供方/模型覆盖项，以及结构化输出策略。
5. 验证路径：模板 lint、试运行、检查报告、图不变量、导出检查。
6. 操作路径：批处理清单、重试、幂等输出、跟踪记录和抽样审查。

模板

使用 Pydantic BaseModel 类。优先采用：

• 使用描述明确的 Field(..., description=...) 元数据说明所有提取字段。
• 通过 model_config = ConfigDict(json_schema_extra={"graph_id_fields": [...]}) 或项目支持的等效方式设置稳定的图 ID。
• 将关系字段定义为实体模型或实体模型列表。
• 使用 edge() 等 Docling Graph 辅助工具明确关系语义（如适用）。
• 使用根模型描述文档级图谱，并提供顶层关系集合。

避免：

• 将无类型的 dict/Any 数据块用于图谱关键实体。
• 使用没有源证据或稳定 ID 的关系字段。
• 在没有 staged/delta 契约的情况下进行过深的模型列表嵌套。
• 仅根据提取顺序、页码或模型生成的标签设置 ID。

Contract

返回一张推荐表，其中包含：

• 已选合同和备用合同。
• 合同所需的架构变更。
• 要设置的流水线标志/配置字段。
• 预期的调试产物及其检查方法。
• 应触发切换合同的故障模式。

简单提取使用 direct；自然可分解的模板使用 staged；当正确性取决于跨大量观察结果解析实体/关系时，使用 delta。

Convert

提供 CLI 命令和后续验证步骤。CLI 标志名称应与 API 字段名称区分开。

docling-graph convert SOURCE_PATH \
  --template TEMPLATE_MODULE:RootModel \
  --output-dir OUTPUT_DIR \
  --provider PROVIDER \
  --model MODEL \
  --extraction-contract direct \
  --schema-enforced-llm \
  --structured-sparse-check \
  --llm-streaming \
  --show-llm-config

然后指导用户检查：

• OUTPUT_DIR/graph.json 或已配置的图产物。
• 启用调试转储时的 OUTPUT_DIR/debug/trace_data.json。
• 用于生成 HTML 审查报告的 docling-graph inspect OUTPUT_DIR。
• 关系数量、孤立实体、重复 ID 和必填字段覆盖率。

API

优先使用显式配置和带类型的路径：

from pathlib import Path

from docling_graph import run_pipeline
from docling_graph.pipeline import PipelineConfig

from templates.sec import FilingGraph

config = PipelineConfig(
    source=Path("filing.pdf"),
    output_dir=Path("out/filing"),
    template=FilingGraph,
    provider_override="openai",
    model_override="gpt-4.1-mini",
    extraction_contract="staged",
    structured_output=True,
    structured_sparse_check=True,
    llm_streaming=True,
    gleaning_enabled=True,
    gleaning_max_passes=2,
    dump_to_disk=True,
    debug=True,
)

context = run_pipeline(config)

如果上游 API 的确切名称因已安装版本而异，请查阅已安装的文档/帮助信息并进行适配。保留以下概念的区分：提供商/模型覆盖、合同选择、结构化输出策略、gleaning、流式传输和调试转储。

Inspect

审查输出文件夹或准备调试交接时使用 inspect：

docling-graph inspect OUTPUT_DIR

检查：

• HTML 摘要中的提取阶段、错误、模型调用和图映射。
• debug/trace_data.json 中的阶段输入/输出、回退路径、结构化输出失败和稀疏检查结果。
• 图产物中的根实体数量、关系数量、孤立节点、重复 ID 和缺失的必填字段。
• 实际使用的提供商/模型配置，而不只是预期配置。

Export

根据下游需求选择导出格式：

• JSON：规范产物、回归测试样例、API 交接。
• CSV：分析人员审查、关系表、导入暂存。
• Cypher/Neo4j：使用唯一性约束加载图数据库。
• NetworkX：算法检查、连通分量、中心性、可达性。

导出交接前，根据 inspect 报告验证稳定 ID、关系方向、重复节点和数量。

Debug

按以下顺序调试：

1. 确认已安装的 docling-graph 版本、Python 版本、提供商凭据以及 CLI/API 命令。
2. 检查模板，确认根模型、稳定 ID、字段描述、关系类型和合同适配性。
3. 启用调试转储并使用少量源数据样本进行复现。
4. 检查 debug/trace_data.json 中的结构化输出回退、稀疏检查失败、阶段/delta 解析器未命中和图映射错误。
5. 对照源证据 -> 提取的 JSON -> 图产物 -> 导出产物。
6. 提出最小修复方案：模板字段描述、合同切换、提供商/模型覆盖、gleaning 处理轮次、解析器配置或导出映射。

Batch

处理大量文档时，请指定：

• 清单格式，包括源路径、模板、合同、提供商/模型、输出目录和重试状态。
• 幂等的输出目录和可恢复运行。
• 除非合规要求保留所有跟踪记录，否则仅为失败项保留每份文档的跟踪记录。
• 按文档类别和故障类别抽样进行 QA。
• 汇总检查：必填字段覆盖率、关系密度、重复 ID、提供商成本、延迟和回退率。

Helper Scripts

此技能包含可选的本地辅助工具：

uv run python skills/docling-graph/scripts/check-env.py --provider openai --format json
uv run python skills/docling-graph/scripts/lint-template.py path/to/template.py --root FilingGraph --format json

这些辅助工具仅供参考，不应取代运行已安装的 docling-graph CLI/API 和检查实际输出。

参考文件

参考文件	在以下情况下加载
references/template-design.md	创建或审查 Pydantic 图模板、稳定 ID、关系字段、分阶段／增量建模时
references/pipeline-configuration.md	选择契约、提供方／模型覆盖项、结构化输出、gleaning、流式处理、调试转储时
references/cli-api-recipes.md	编写 CLI/API 运行模式、检查工作流或批处理清单时
references/export-graph-management.md	规划 JSON/CSV/Cypher/NetworkX 导出和图完整性检查时
references/debugging.md	调试跟踪、检查报告、图映射失败或产物交接时

规范术语

规范术语。请严格使用以下术语：

规范术语	含义
direct contract	一次性地从源证据中提取内容，写入根图模式
staged contract	将提取分解为多个阶段输出，再合并到根图中
delta contract	先提取观察结果，再解析实体／关系并写入图中
structured output	提供方支持的模式约束或等效的受约束生成
sparse check	用于识别缺失或填充不足的模式字段的验证流程
gleaning	有限次数的后续处理，用于提高实体和关系的召回率
inspect report	根据输出目录生成、供人工审查的界面
trace data	调试产物，例如 debug/trace_data.json，用于关联源内容、提取结果、映射结果和图输出

渐进式披露

仅在请求需要时加载参考资料：

1. 从本技能正文开始，了解任务分派、范围和模式协议。
2. 为当前模式打开一个参考文件。
3. 仅在有人要求运行本地检查或维护本技能时，才打开辅助脚本。
4. 对于简单的范围重定向或只需一条命令的回答，避免加载所有参考资料。

扩展策略

扩展 Docling Graph 工作时，应先增加操作控制，再增加模型复杂度：

范围	策略
小规模	使用调试转储和检查输出，验证一份有代表性的文档
中等规模	添加清单、幂等输出、重试和抽样 QA
大规模	使用批处理执行，并汇总指标、制定跟踪保留策略、分阶段推广
100+ 个文件	仅在通过单文档不变量测试套件后，才按清单分片并行处理

1. 使用调试转储和检查输出，验证一份有代表性的文档。
2. 为批处理添加清单，列出来源、模板、契约、提供方／模型、输出路径和状态。
3. 确保输出具有幂等性且可恢复。
4. 保留失败案例和抽样成功案例的跟踪。
5. 汇总必填字段覆盖率、关系密度、重复 ID、孤立关系、回退率、成本和延迟。
6. 仅在抽样集通过图不变量检查后，才推广到更大批次。

验证约定

在本技能目录中运行以下内容，再宣布更改已完成：

python scripts/check.py
python -m py_compile scripts/check-env.py scripts/lint-template.py
pytest -q tests/test_docling_graph_skill.py
git diff --check

完成标准：

1. scripts/check.py 以 0 退出。
2. 辅助脚本编译通过，且针对性测试通过。
3. git diff --check 以 0 退出。
4. 本技能目录中不存在违反可移植 CLI 规范的内容。

更改技能定义、公开描述、参考文件或评估行为后，如果 docs-steward 可用，请调用它。

关键规则

1. 严格限定 Docling Graph 的适用范围；将通用解析或图数据库问题转交处理。
2. 区分 CLI 标志与 Python API 字段。
3. 在宣称图质量良好前，先验证 ID、必填字段、关系以及调试／检查产物。
4. 在可用时，优先采用结构化输出／模式约束，并说明回退行为。
5. 对于复杂模板，明确选择 direct、staged 或 delta。
6. 在调试交接中保留源证据路径。
7. 从命令、日志、示例、跟踪和生成的配置中移除秘密信息。