使用 Docling 和 SDG Hub 准备微调数据
Open Data Hub 将文档转换和合成数据视为同一模型定制流程中的两个步骤:
- Docling 将 PDF、Office 文件、HTML 及类似来源转换为结构化 Markdown 或 JSON。
- SDG Hub 针对这些文档运行由可组合块构成的 YAML flow,并写入合成的问答或聊天轮次。
- 使用生成的 JSONL,通过 Training Hub 或 Workbench VolcanoJob进行微调。
本指南在 Alauda AI Workbench 内运行这两个库。内置镜像均未预安装这两个软件包。对于数千个 PDF,请不要扩展 workbench — 使用末尾介绍的 Ray Data / Kubeflow Pipelines 路径。
与本页面采用相同步骤的可运行 notebook 位于此页面旁边:
下载时,请将 notebook 和 assets/docling-sdg/ 放在一起:
先决条件
内置 Workbench 镜像不包含 Docling、SDG Hub、tesseract 或 qpdf。
因此,需要 OCR 的扫描 PDF 还需要额外的系统库或
自定义 workbench 镜像。
在 Workbench 中安装
在 workbench 中打开 JupyterLab 终端。在工作区 PVC 上的虚拟环境中固定软件包版本,这样 pod 重启后软件包不会丢失。
将 venv 注册为 Jupyter 内核,以便 notebook 单元使用它:
在 JupyterLab 中,将 notebook 内核切换为 Python (Docling + SDG)。
隔离网络的集群:在可联网的计算机上下载 wheels,通过 JupyterLab 的 Upload Files 按钮上传,然后按照 离线安装 Python Wheel 文件 中的说明进行安装。 Docling 首次转换时也会下载布局和表格模型。请预先下载这些模型,并将缓存指向 PVC:
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 时间。
对于单个文件,也可以使用 CLI,效果相同:
将 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 列出的模型名称一致。
查找内置 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。
务必先执行 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:
将 data_path=str(out_path) 传递给 training_hub.sft(...) 或
training_hub.osft(...)。对于 LLaMA-Factory,保留相同的 JSONL,并像使用 Workbench 微调 LLM中一样,将 dataset 指向该文件。
如果你想采用 CPT → SFT 而非仅使用 SFT,还可以准备第二个包含原始文档文本的 JSONL({"text": "..."}),作为 CPT 语料库——请参阅
持续预训练。
扩展到单个 workbench 之外
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)。
故障排查
后续步骤
- 使用 Training Hub 微调 LLM — 对 JSONL 执行
sft/osft/lora_sft。 - 使用 Workbench 微调 LLM — LLaMA-Factory VolcanoJob。
- 使用 Kubeflow Trainer v2 进行微调 — 使用
dataset-initializer的集群TrainJob。 - 使用 AutoRAG Pipelines 优化 RAG 原生应用 — 将 Docling 作为流水线阶段,而不是 workbench 库。
- 上游项目:Docling(MIT)、 SDG Hub(Apache-2.0)、 Open Data Hub data-processing(Apache-2.0)。