Structured Chunk Schema and Reference API v2

このドキュメントでは、RAG パイプライン再構築に向けた基盤スキーマと API 契約を定義します。フロントエンドは描画専用に徹し、ETL / API 層が完全な構造化データを提供する方針です。

目的

• UI 側での文字整形・パンくず再構築を廃止し、API から完成形データを返す。
• 段落・表・別表などの「型」を明確化し、それぞれに最適な表示 / 検索表現を用意する。
• 安定 ID、情報漏洩ガード、LLM 依存境界を設計段階で確立する。

StructuredChunk

{
  "chunk_id": "doc_001::chapter-3::article-10::annex-1::tbl-1", // 安定 ID
  "doc_id": "doc_001",
  "text_type": "table",                   // paragraph | table | list | heading | annex_title
  "content": "年次有給休暇の概略...",     // paragraph / list 用 (pre-wrap 表示)
  "content_md": "| 勤続年数 | 2年目 | ...", // table / code 用 (Markdown)
  "metadata": {
    "doc_title": "就業規則（2025改訂版）",
    "section_path": [
      { "level": 1, "type": "chapter", "label": "第3章", "title": "勤務" },
      { "level": 2, "type": "article", "label": "第104条", "title": "社員紹介制度" },
      { "level": 3, "type": "annex", "label": "別表", "title": "年次有給休暇付与日数" }
    ],
    "parent_section_title": "第104条 社員紹介制度",
    "annex_title": "別表 年次有給休暇付与日数",
    "page_range": [4, 4],
    "anchors": { "bbox": [120, 80, 480, 320] },
    "text_hash": "sha256:...",              // 再処理検知用
    "embed_version": "text-embedding-3-small@2025-10-01"
  },
  "display": {
    "title": "第104条 社員紹介制度 / 別表 年次有給休暇付与日数",
    "breadcrumb": [
      "第3章 勤務",
      "第104条 社員紹介制度",
      "別表 年次有給休暇付与日数"
    ],
    "body_text": null,
    "body_md": "| 勤続年数 | 2年目 | 3年目 | ..."
  }
}

主要ポリシー

• ID 安定化: chunk_id は doc 名 + section path + text_type + 連番の決定論的ハッシュで生成し、再取り込み時も不変にする。
• テーブル二重表現: content_md を表示、content（もしくは normalized_for_embed）を検索に利用。テーブルは key:value 化したサマリーテキストを別フィールドに保持。
• LLM 依存の境界: ETL 正規化はルールベースが主体。Marker --use_llm 等の LLM ベース後処理は副次的に利用し、処理履歴をメタデータ（例: metadata.preprocessing.llm_revision）に記録。
• 情報漏洩ガード: source_path / filesystem_path は API レスポンスに含めない。内部ジョブ専用フィールドとして Data Lake にのみ保存する。

Reference API v2

{
  "reference": {
    "doc": {
      "id": "doc_001",
      "title": "就業規則（2025改訂版）",
      "version": "2025-04-01"
    },
    "chunk": { /* StructuredChunk */ },
    "related_chunks": [ /* Optional: StructuredChunk[] */ ]
  }
}

HTTP 契約

• Endpoint: POST /api/reference
• Request: { "chunkId": "...", "docId": "..." }
• Response: 上記 JSON。source_path は返却しない。
• エラー: 404 (未収載), 422 (不正 ID), 429, 5xx 等。

UI の責務

1. text_type に応じて描画コンポーネントを選択。
2. paragraph → <pre class="whitespace-pre-wrap">
3. table → MarkdownView (display.body_md をそのまま描画)
4. list → MarkdownView or リスト専用
5. display.title / display.breadcrumb をそのまま表示。
6. metadata.section_path はフィルターやアンカー（別表へのジャンプ）に利用。
7. metadata.page_range 等は UI 表示しない（必要なら内部 QA 用パネルで限定表示）。

実装ロードマップ概要

1. フェーズ1: 新スキーマの型定義・API モック導入・UI のディスパッチ実装。
2. フェーズ2: ETL パイプラインで StructuredChunk JSON を生成（Marker など利用）。
3. フェーズ3: Azure AI Search に新データ投入、ハイブリッド検索 + セマンティックランカー導入。
4. フェーズ4: E2E / Recall 指標の自動化、LLM Grounding チェック導入。

用語集

用語	説明
StructuredChunk	コンテンツの最小表示単位。型情報と display 情報を抱える。
text_type	描画 / 検索を振り分ける型。段落、表、リスト、見出しなど。
section_path	章・条・節・別表の完全修飾パス。パンくずと同義。
normalized_for_embed	埋め込み計算用のテキスト。表は key:value 化。
related_chunks	同一条文内の補助チャンク群（例：本文＋別表）。

---

本スキーマをベースに、フロントエンド／バックエンド／ETL／検索の各層を疎結合で再構築します。