databricks-unstructured-pdf-generation

Databricks 上のデモと評価データセット向け非構造化ドキュメント

Unity Catalog に保存するデータセットとして、合成 PDF ドキュメントと、それに対応するテスト質問を作成するワークフローです。Databricks 上のデモや、RAG／非構造化ドキュメント検索の評価に使用します。PDF の生成には、標準的なローカル HTML → PDF ツールを使用します。Databricks 固有の価値は、ワークフローの構成にあります。UC のボリュームのレイアウト、質問ファイルとのペアリング、さらに Databricks の下流の検索／ai_extract／ai_parse_document 評価との連携を含みます。

ワークフロー

1. ./raw_data/html/ に 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）を直接使えます。このスキルは、汎用 PDF ジェネレーターではなく、UC 上で合成データセットをエンドツーエンドで作成する用途のものです。

パスの規則： 以下の <SKILL_ROOT> は、この SKILL.md が含まれるディレクトリを指します。絶対インストールパスに解決してください（例：~/.claude/skills/databricks-unstructured-pdf-generation）。./raw_data/... のパスは、プロジェクトの作業ディレクトリを基準とします。

依存関係

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 はソースディレクトリの 内容 をターゲットにコピーするため（ソースディレクトリ名は保持されません）、PDF をボリューム上の独立したフォルダーに保管するには、ターゲットとして raw_data/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：テスト質問の生成

Knowledge Assistant（KA）または Supervisor Agent（旧称 Multi-Agent Supervisor、MAS）の評価用に、./raw_data/pdf/pdf_eval_questions.json を作成します。このファイルは 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 エラーリファレンスガイド（エラーコード、原因、解決策）
• 具体的な手順を記載したインストール／設定ガイド
• バージョン固有の詳細を含む技術仕様書

内容の例： 「接続に失敗しました」のような一般的なエラーではなく、次のように記述します。

• 「エラー 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

同梱スクリプト

このスキルには、ヘルパースクリプトが 1 つ同梱されています。

ファイル	説明
scripts/pdf_generator.py	HTML → PDF コンバーター（plutoprint をラップ）。タイムスタンプによるスキップ機能付きの並列フォルダー変換に対応しています。Step 2 と CLI リファレンスから参照されます。

スクリプトは <SKILL_ROOT>/scripts/pdf_generator.py に配置されています。見つからない場合は、上記の CLI リファレンス を参考に再作成してください（--input／--output／--force／--workers を受け取る convert サブコマンドで、HTML → PDF 変換のために plutoprint をラップします）。

トラブルシューティング

問題	解決策
「plutoprint がインストールされていません」	uv pip install plutoprint
PDF の表示がおかしい	HTML／CSS の構文を確認してください
「Volume が存在しません」	databricks volumes create CATALOG SCHEMA VOLUME_NAME MANAGED（4 つの個別の位置引数を指定します。catalog.schema.volume ではありません）