databricks-unstructured-pdf-generation

用途

该技能提供一套在 Databricks 上生成合成 PDF 文档及配对测试问题的工作流，用于构建演示（Demo）和 RAG / 非结构化文档检索评估数据集。生成的 PDF 与问题文件以 Unity Catalog 卷（UC Volume）为存放位置，便于下游检索、ai_extract、ai_parse_document 等评估流程直接读取。

PDF 生成本身使用标准本地 HTML → PDF 工具（plutoprint），Databricks 特有的价值在于整体工作流形态：UC 卷布局、配对问题文件，以及与下游 Databricks 检索 / ai_extract / ai_parse_document 评估的集成。

主要能力

将 HTML 文件批量转换为 PDF（并行转换，默认 4 个 worker，支持时间戳跳过与强制重转）。
保留子目录结构，便于按类别组织文档。
通过 databricks fs cp 将 PDF 上传到 Unity Catalog 卷，形成与生产管道一致的卷结构。
生成 pdf_eval_questions.json，为每份文档配对检索评估问题，作为 mlflow.genai.evaluate() 或同类检索质量评分器的黄金数据集。
提供文档内容编写指南，帮助生成适合 Knowledge Assistant 测试或演示的多页、含具体错误码与解决方案的文档。

使用方式

依赖安装

uv pip install plutoprint

步骤 1：编写 HTML 文件

mkdir -p ./raw_data/html

将 HTML 文档写入 ./raw_data/html/filename.html。可使用子目录组织，结构会被保留。

步骤 2：转换为 PDF

# 转换整个文件夹（并行，4 个 worker）
python <SKILL_ROOT>/scripts/pdf_generator.py convert --input ./raw_data/html --output ./raw_data/pdf

若 PDF 已存在且比 HTML 新，则跳过。使用 --force 可强制全部重转。

步骤 3：上传到卷

databricks fs 即使对 UC Volume 路径也需要 dbfs: 前缀。-r 会将源目录内容复制到目标（不保留源目录名），因此请将目标显式命名为 raw_data/pdf，使 PDF 位于卷上的独立文件夹中。它们会落在 raw_data/pdf/ 下，即 dbfs:/Volumes/my_catalog/my_schema/raw_data/pdf/report.pdf，这样 Knowledge Assistant 或摄取管道可以指向该单一文件夹。

databricks fs cp -r --overwrite ./raw_data/pdf dbfs:/Volumes/my_catalog/my_schema/raw_data/pdf

步骤 4：生成测试问题

创建 ./raw_data/pdf/pdf_eval_questions.json，包含用于 Knowledge Assistant（KA）或 Multi-Agent Supervisor（MAS）评估的问题。该文件可以随 PDF 一起上传到卷，供下游智能体使用：

{
  "api_errors_guide.pdf": {
    "question": "What is the solution for error ERR-4521?",
    "expected_fact": "Call /api/v2/auth/refresh with refresh_token before the 3600s TTL expires"
  },
  "installation_manual.pdf": {
    "question": "What port does the service use by default?",
    "expected_fact": "Port 8443 for HTTPS, configurable via CONFIG_PORT environment variable"
  }
}

该 JSON 可用于构建 KA 测试用例并验证检索准确性。

文档内容指南

为 Knowledge Assistant 测试或演示生成文档时：

多页文档：每份 PDF 应有多页且内容充实。
具体错误码与解决方案：包含产品特定的错误码、原因和解决步骤。
技术细节：API 端点、配置参数、版本号、具体命令。
简单 CSS：保持样式最简，以便快速创建 HTML 并可靠转换 PDF。
可查询事实：包含 KA 必须阅读文档才能回答的细节（而非通用知识）。

适合的文档类型：

含故障排除章节的产品用户手册
API 错误参考指南（错误码、原因、解决方案）
含具体步骤的安装/配置指南
含版本特定细节的技术规格

示例内容：不要写通用的“Connection failed”错误，而应写：

“Error ERR-4521: OAuth token expired. Cause: Token TTL exceeded 3600s default. Solution: Call /api/v2/auth/refresh with your refresh_token before expiration. See Section 4.2 for token lifecycle management.”

CLI 参考

python <SKILL_ROOT>/scripts/pdf_generator.py convert [OPTIONS]

  --input, -i     Input HTML file or folder (required)
  --output, -o    Output folder for PDFs (required)
  --force, -f     Force reconvert (ignore timestamps)
  --workers, -w   Parallel workers (default: 4)

文件夹结构

子文件夹结构会被保留：

./raw_data/html/                    ./raw_data/pdf/
├── report.html             →       ├── report.pdf
├── quarterly/                      ├── quarterly/
│   └── q1.html             →       │   └── q1.pdf
└── legal/                          └── legal/
    └── terms.html          →           └── terms.pdf

捆绑脚本

该技能附带一个辅助脚本：

文件	描述
scripts/pdf_generator.py	HTML → PDF 转换器（封装 plutoprint）；并行文件夹转换，支持时间戳跳过。被步骤 2 和 CLI 参考引用。

脚本位于 <SKILL_ROOT>/scripts/pdf_generator.py。若缺失，可根据上方 CLI 参考重建（一个 convert 子命令，接受 --input/--output/--force/--workers，封装 plutoprint 实现 HTML → PDF）。

故障排除

问题	解决方案
“plutoprint not installed”	`uv pip install plutoprint`
PDF 看起来不对	检查 HTML/CSS 语法
“Volume does not exist”	`databricks volumes create CATALOG SCHEMA VOLUME_NAME MANAGED`（四个独立位置参数，而非 catalog.schema.volume）

适用场景与限制

适用场景：在 Databricks 上为 Knowledge Assistant 或 RAG / 非结构化文档检索评估构建合成 PDF 数据集与配对测试问题，并希望数据集以 Unity Catalog 卷形式存放、与生产管道结构一致。

限制：如果只需要临时生成 PDF（不涉及 Databricks 工作流），任何 HTML → PDF 工具（weasyprint、wkhtmltopdf、playwright pdf、plutoprint）都可直接使用；该技能的存在是为了“UC 上的合成数据集”端到端形态，而非通用 PDF 生成器。路径约定：<SKILL_ROOT> 指包含该 SKILL.md 的目录，需解析为绝对安装路径（例如 ~/.claude/skills/databricks-unstructured-pdf-generation）；./raw_data/... 路径相对于你自己的项目 cwd。