databricks-unstructured-pdf-generation

用于 Databricks 演示和评估数据集的非结构化文档

用于生成合成 PDF 文档 + 配套测试问题的工作流，可将其作为 Unity Catalog 中的数据集，用于 Databricks 上的演示以及 RAG / 非结构化文档检索评估。PDF 生成步骤使用标准的本地 HTML → PDF 工具；Databricks 特有的价值在于工作流的整体设计——UC 卷布局、配套的问题文件，以及与下游 Databricks 检索 / ai_extract / ai_parse_document 评估的集成。

工作流

1. 将 HTML 文件写入 ./raw_data/html/（并行编写多个文件以提高速度），并针对你的检索流水线在生产环境中会处理的文档来设计其内容。
2. 使用 <SKILL_ROOT>/scripts/pdf_generator.py 将 HTML 转换为 PDF（并行转换，该脚本封装了 plutoprint）。
3. 使用 databricks fs cp 将 PDF 上传到 Unity Catalog 卷，保持与生产流水线读取的卷结构一致。
4. 生成 ./raw_data/pdf/pdf_eval_questions.json，将每份文档与检索评估问题配对；该文件将成为 mlflow.genai.evaluate() 或同类检索质量评分器的黄金数据集。

如果你只需要临时生成 PDF（不需要 Databricks 工作流），任何 HTML → PDF 工具（weasyprint、wkhtmltopdf、playwright pdf、plutoprint）都可以直接使用。本技能面向的是在 UC 上端到端构建合成数据集的完整流程，而不是通用 PDF 生成器。

**路径约定：**下文中的 <SKILL_ROOT> = 包含此 SKILL.md 的目录。请解析为绝对安装路径（例如 ~/.claude/skills/databricks-unstructured-pdf-generation）。./raw_data/... 路径相对于你自己的项目 cwd。

依赖项

uv pip install plutoprint

步骤 1：编写 HTML 文件

mkdir -p ./raw_data/html

将 HTML 文档写入 ./raw_data/html/filename.html。可使用子目录进行整理（目录结构会保留）。

步骤 2：转换为 PDF

# Convert entire folder (parallel, 4 workers)
python <SKILL_ROOT>/scripts/pdf_generator.py convert --input ./raw_data/html --output ./raw_data/pdf

如果 PDF 已存在且比 HTML 更新，则会跳过该文件。使用 --force 可重新转换所有文件。

步骤 3：上传到卷

即使是 UC 卷路径，databricks fs 也要求使用 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）或 Supervisor Agent（前称 Multi-Agent Supervisor，MAS）的问题。该文件可以与 PDF 一起上传到卷中，供下游 Agent 使用：

{
  "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 错误参考指南（错误代码、原因、解决方案）
• 包含具体步骤的安装 / 配置指南
• 包含特定版本细节的技术规格

**内容示例：**不要只写笼统的“连接失败”错误，而应写：

• “错误 ERR-4521：OAuth 令牌已过期。原因：令牌 TTL 超过默认值 3600s。解决方案：在令牌过期前，使用 refresh_token 调用 /api/v2/auth/refresh。请参阅第 4.2 节，了解令牌生命周期管理。”

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”	uv pip install plutoprint
PDF 显示异常	检查 HTML/CSS 语法
“卷不存在”	databricks volumes create CATALOG SCHEMA VOLUME_NAME MANAGED（四个独立的位置参数，而不是 catalog.schema.volume）