使用 Docling 和 SDG Hub 准备微调数据

Open Data Hub 将文档转换和合成数据视为同一模型定制流程中的两个步骤:

  1. Docling 将 PDF、Office 文件、HTML 及类似来源转换为结构化 Markdown 或 JSON。
  2. SDG Hub 针对这些文档运行由可组合块构成的 YAML flow,并写入合成的问答或聊天轮次。
  3. 使用生成的 JSONL,通过 Training Hub 或 Workbench VolcanoJob进行微调。

本指南在 Alauda AI Workbench 内运行这两个库。内置镜像均未预安装这两个软件包。对于数千个 PDF,请不要扩展 workbench — 使用末尾介绍的 Ray Data / Kubeflow Pipelines 路径。

PDF / DOCX / HTML
        │  Docling (workbench, or Ray Data for scale)
        ▼
Markdown / DoclingDocument JSON
        │  SDG Hub flow (OpenAI-compatible API or InferenceService)
        ▼
JSONL  (chat messages or instruction/output)
        │  training_hub.sft / LLaMA-Factory / Trainer v2
        ▼
Fine-tuned model

与本页面采用相同步骤的可运行 notebook 位于此页面旁边:

下载时,请将 notebook 和 assets/docling-sdg/ 放在一起:

git clone --depth 1 --filter=blob:none --sparse https://github.com/alauda/aml-docs.git
git -C aml-docs sparse-checkout set --no-cone \
  /docs/en/train/guides/prepare-finetune-data-with-docling-and-sdg.ipynb \
  /docs/en/train/guides/assets/docling-sdg/
cd aml-docs/docs/en/train/guides

先决条件

要求详细信息
WorkbenchStandard Data Science (Python 3.12)。请参阅创建 Workbench。workbench 本身可以仅使用 CPU。
持久化存储用于存储源文档、Docling 缓存、SDG 检查点和输出 JSONL 的工作区 PVC。仅安装在容器文件系统中的软件包会在重新创建 workbench 时消失。
Teacher LLMOpenAI 兼容的聊天 API(/v1/chat/completions)。使用集群内的 InferenceService(基础 URL 为 http://<isvc-name>-predictor.<namespace>.svc.cluster.local/v1),或任何兼容的外部端点。
网络PyPI 或内部索引,用于安装 docling 和 sdg-hub,以及用于 Docling 布局模型的 Hugging Face(或镜像缓存)。
可选,用于扩展规模使用 KubeRay Operator 处理 Ray Data PDF 批次;使用 Kubeflow Pipelines 处理 SDG Hub KFP 组件。

内置 Workbench 镜像不包含 Docling、SDG Hub、tesseract 或 qpdf。 因此,需要 OCR 的扫描 PDF 还需要额外的系统库或 自定义 workbench 镜像。

在 Workbench 中安装

在 workbench 中打开 JupyterLab 终端。在工作区 PVC 上的虚拟环境中固定软件包版本,这样 pod 重启后软件包不会丢失。

python -m venv /opt/app-root/src/venvs/docling-sdg
source /opt/app-root/src/venvs/docling-sdg/bin/activate
python -m pip install -U pip
pip install 'docling>=2.70' 'sdg-hub>=0.7'
# Optional: document-parsing extras used by SDG Hub example notebooks
# pip install 'sdg-hub[examples]'

将 venv 注册为 Jupyter 内核,以便 notebook 单元使用它:

python -m pip install ipykernel
python -m ipykernel install --user --name docling-sdg --display-name "Python (Docling + SDG)"

在 JupyterLab 中,将 notebook 内核切换为 Python (Docling + SDG)。

隔离网络的集群:在可联网的计算机上下载 wheels,通过 JupyterLab 的 Upload Files 按钮上传,然后按照 离线安装 Python Wheel 文件 中的说明进行安装。 Docling 首次转换时也会下载布局和表格模型。请预先下载这些模型,并将缓存指向 PVC:

export HF_HOME=/opt/app-root/src/.cache/huggingface
export DOCLING_CACHE_DIR=/opt/app-root/src/.cache/docling

docling 2.70 及更高版本需要 Python 3.10+。Standard Data Science 使用 3.12,符合要求。除非你自行安装其余的数据科学组件,否则不要安装到 Minimal Python 镜像中。

使用 Docling 转换文档

Docling 是 Open Data Hub 用于准备非结构化数据以供模型使用的 Python 库。在 workbench 中,处理方式是对 PVC 上的文件执行 DocumentConverter。这足以处理几十份原生数字 PDF。每个文件通常需要 5–60 秒的 CPU 时间。

import json
from pathlib import Path
from docling.document_converter import DocumentConverter

src = Path("/opt/app-root/src/data/source")
out = Path("/opt/app-root/src/data/docling")
out.mkdir(parents=True, exist_ok=True)

converter = DocumentConverter()
for path in sorted(src.glob("*.pdf")):
    result = converter.convert(str(path))
    (out / f"{path.stem}.md").write_text(result.document.export_to_markdown())
    (out / f"{path.stem}.json").write_text(
        json.dumps(result.document.export_to_dict(), ensure_ascii=False)
    )

对于单个文件,也可以使用 CLI,效果相同:

docling /opt/app-root/src/data/source/policy.pdf \
  --output /opt/app-root/src/data/docling

将 Markdown(或纯文本)用作 SDG 的 document 列。如果需要表格、边界框或后续的 RAG 索引,请保留 JSON——AutoRAG 的 text-extraction 阶段会写入相同的 DoclingDocument JSON。请参阅 使用 AutoRAG Pipelines 优化 RAG 应用。

ODH 在 opendatahub-io/data-processing 下提供的 notebook 涵盖转换、分块、字段提取和子集选择。如果需要这些示例流程,请在 JupyterLab 中克隆该代码库;本页只进行必要的转换,以便将数据输入 SDG Hub,然后用于 SFT。

使用 SDG Hub 生成合成数据

SDG Hub 是一个由 block 和 flow 组成的库。block 执行一项操作(构建 prompt、调用 LLM、解析回复)。flow 是由多个 block 组成的 YAML 列表。Open Data Hub 会克隆 sdg_hub/examples 并在 workbench 中运行这些 notebook。此处使用相同的安装方式。

使用兼容 OpenAI 的 teacher 配置 SDG Hub。提供集群内的 InferenceService predictor URL,或提供你控制的其他 /v1 chat endpoint。 SDG_MODEL 必须与服务器在 /v1/models 列出的模型名称一致。

import os

SDG_MODEL = os.environ.get("SDG_MODEL", "qwen3")
SDG_API_BASE = os.environ.get(
    "SDG_API_BASE",
    "http://qwen3-predictor.my-namespace.svc.cluster.local/v1",
)
SDG_API_KEY = os.environ.get("SDG_API_KEY", "not-needed")

查找内置 flow,然后按 ID 加载其中一个,或加载自定义 YAML。知识调优 flow epic-jade-656(Extractive Summary Knowledge Tuning)是 ODH 针对领域问答的默认 flow,但它需要额外的上下文列(document_outline、icl_document、icl_query_1 ……),并且 teacher 需要能够承受约 50 路并发。建议先使用包含三个 block 的 flow,然后在 teacher 和 schema 准备就绪后切换到 registry flow。

assets/docling-sdg/flow.yaml 就是这个三 block flow:prompt → LLMChatBlock → extract。必需的列为 document 和 domain。

from datasets import Dataset
from sdg_hub import Flow, FlowRegistry

FlowRegistry.discover_flows()

flow = Flow.from_yaml("assets/docling-sdg/flow.yaml")
flow.set_model_config(model=SDG_MODEL, api_base=SDG_API_BASE, api_key=SDG_API_KEY)

dataset = Dataset.from_dict({
    "document": [Path("data/docling/policy.md").read_text()],
    "domain": ["internal-policy"],
})

probe = flow.dry_run(dataset, sample_size=1, enable_time_estimation=True, max_concurrency=4)
print(probe["final_dataset"]["columns"])

result = flow.generate(
    dataset,
    max_concurrency=8,
    checkpoint_dir="/opt/app-root/src/data/sdg-ckpt",
    save_freq=50,
)

务必先执行 dry_run,再执行 generate。即使 teacher 支持 50 路并发,在包含 266 篇文章的语料上运行知识调优 notebook 也需要数小时;enable_time_estimation 会打印预估结果,让你在进行完整运行之前评估 NUMBER_OF_SUMMARIES 和并发数。

对于抽取式摘要知识调优 flow,请按照 SDG Hub 仓库中的 examples/knowledge_tuning 操作:使用 Docling 解析,然后针对每份文档生成多个增强样本(主题摘要、关系、原子事实),并针对每个摘要生成三组问答。这是 Open Data Hub 将专有事实注入指令微调模型的处理方式。

编写微调 JSONL

Training Hub 要求每行包含一个聊天对象。将 SDG 输出列映射到 messages:

import json

out_path = Path("/opt/app-root/src/data/sft/train.jsonl")
out_path.parent.mkdir(parents=True, exist_ok=True)

with out_path.open("w") as fh:
    for row in result:
        question = row["question"].strip()
        answer = row.get("answer") or row["document"]
        fh.write(json.dumps({
            "messages": [
                {"role": "system", "content": "You are a helpful assistant for this team's documents."},
                {"role": "user", "content": question},
                {"role": "assistant", "content": answer},
            ]
        }, ensure_ascii=False) + "\n")

将 data_path=str(out_path) 传递给 training_hub.sft(...) 或 training_hub.osft(...)。对于 LLaMA-Factory,保留相同的 JSONL,并像使用 Workbench 微调 LLM中一样,将 dataset 指向该文件。

如果你想采用 CPT → SFT 而非仅使用 SFT,还可以准备第二个包含原始文档文本的 JSONL({"text": "..."}),作为 CPT 语料库——请参阅 持续预训练。

扩展到单个 workbench 之外

数量工具适用场景
数十份原生数字化 PDFworkbench 中的 Docling交互式、仅使用 CPU,无需额外 operator
数千份 PDFKubeRay 上的 Ray Data + Docling编译实验性的 parse_and_chunk 组件。请参阅从 pipelines-components 运行 Ray Data Pipeline。需要 RWX PVC、Ray+Docling 镜像和 KubeRay。
在 CI 中重复运行 SDGKFP sdg_hub 组件pipelines-components 中的 Beta 组件。编译 pipelines/data_processing/sdg/pipeline.py,上传 YAML,并传入 model / flow_id 或 flow ConfigMap。使用与 notebook 相同的 OpenAI 兼容型教师模型。
复杂布局 / 图像说明Docling VLM pipelineODH docling-vlm KFP 示例。需要 GPU 运行时镜像。

Ray 批处理路径会在每个 worker 上挂载一个 RWX PVC,在子进程中处理每份 PDF,以便终止卡住的转换器,并将 Markdown + JSON 写回同一卷。不要在 Ray head 上调度 Docling actor。

KFP SDG 路径是 Open Data Hub 在 workbench notebook 之后的后续方案:为 flow YAML 创建 ConfigMap,为教师模型 API key 创建 Secret,然后运行 pipeline。Alauda 的镜像组件是 pipelines-components SDG Hub 组件(components/data_processing/sdg) (稳定性:beta)。

故障排查

症状原因
pip install docling 在 UBI9 上失败,提示缺少 tesseract / qpdfWorkbench 镜像中不包含 OCR 扩展。请跳过 OCR,或将这些 RPM 打包到 BYO 镜像 中。
首次 convert() 卡住或从 Hugging Face 下载布局模型未缓存。请在 PVC 上设置 HF_HOME / DOCLING_CACHE_DIR,或预先获取模型。
FlowValidationError: model config已跳过 set_model_config()。对于兼容 OpenAI 的 teacher,请传入 model 和 api_base。
MissingColumnError数据集缺少 flow required_columns 字段。请打印 flow.get_dataset_requirements()。
Teacher 401 / 404SDG_API_BASE 必须是 predictor Service …/v1,且 SDG_MODEL 必须与服务器在 /v1/models 列出的名称匹配。
Knowledge-tuning 运行超时降低 NUMBER_OF_SUMMARIES,增大 teacher 上的 HTTP 超时时间,或使用可承载 ≥50 个并发请求的端点。
Workbench 在转换 PDF 时发生 OOM将作业移至 Ray Data。单个 Docling actor 需要数 GB 内存和多个 CPU。

后续步骤