ai_prep_search 関数

適用対象: Databricks SQL Databricks Runtime

ai_prep_search()関数は文書内容をRAGベクトル検索および情報検索システムに最適なフォーマットに変換します。 構造化された出力 ai_parse_document またはプレーンテキストとマークダウンの内容 STRING 受け入れます。 各入力ドキュメントについて、関数はコンテンツをセマンティック チャンクに分割し、ドキュメント タイトル、セクション ヘッダー、ページ参照などのドキュメント レベルのコンテキストで各チャンクをエンリッチし、埋め込み可能な表現を生成します。

データのセキュリティ

ドキュメント データは、Databricks セキュリティ境界内で処理されます。 DatabricksはAI関数呼び出しに渡されるパラメータを保存しませんが、Databricksランタイムバージョンなどのメタデータ実行の詳細は保持します。

必要条件

• Databricks Runtime 18.2 以降。
• サーバーレス コンピューティングを使用している場合は、次も必要です。
  • サーバーレス環境のバージョンは 3 以上に設定する必要があります。これにより、 VARIANTなどの機能が有効になります。
  • Pythonまたは SQL を使用する必要があります。 その他のサーバーレス機能と制限事項については、「 サーバーレス コンピューティングの制限事項」を参照してください。
• ai_prep_search関数は、Databricks ノートブック、SQL エディター、Databricks ワークフロー、ジョブ、または Lakeflow パイプラインを使用して使用できます。

構文

ai_prep_search(parsed [, options])

引数

• parsed検索準備のための文書コンテンツ。 次のいずれか:
  • ai_parse_documentの構造化出力を表すVARIANT式です。
  • プレーンテキストまたはマークダウンを含む STRING 式。 出力 ai_parse_document 構造化されていないJSON文字列も文字通りのテキストとして扱われ、同じようにチャンクされます。
• options: 省略可能な MAP<STRING, STRING>。 サポートされているキー:
  • 'version': 使用する出力スキーマのバージョン。
  • 'schema': ドキュメントレベルのメタデータ抽出のためのキーセットを定義するJSONスキーマ。 スキーマは ai_extractと同じフォーマットを使用しています:
    • 単純なスキーマ: フィールド名の JSON 配列 (文字列と見なされます)

      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
      

    • 高度なスキーマ: 型情報、説明、入れ子構造を持つ JSON オブジェクト
      • string、integer、number、boolean、およびenum型をサポートします。 型の検証を実行します。 無効な値を指定すると、エラーが発生します。 最大 500 個の列挙値。
      • "type": "object"を使用して入れ子になったオブジェクトをサポートします"properties"
      • で "type": "array" を使用するプリミティブまたはオブジェクトの配列をサポートします "items"
      • 抽出品質をガイドする各プロパティの省略可能な "description" フィールド

返品

ベクター検索インデックス作成用に書式設定されたドキュメント チャンクを含む VARIANT 。 出力内の各行は、1 つの入力ドキュメントを表します。

出力スキーマは次のとおりです。

{
  "document": {
    "contents": [
      {
        "chunk_id": STRING,       // Unique identifier composed of the document ID and chunk position
        "chunk_position": INT,    // 0-based position of the chunk within the document
        "chunk_to_retrieve": STRING,  // Raw text content of the chunk
        "chunk_to_embed": STRING, // Context-enriched text prepared for embedding; see chunk_to_embed format
        "metadata": OBJECT,   // Typed values for the keys in schema; empty object when schema is omitted
        "pages": [
          {
            "page_id": INT,       // Page index that this chunk appears on
            "image_uri": STRING   // Path to the page image for multi-modal retrieval
          }
        ]
      }
    ],
    "pages": [
      {
        "id": INT,           // 0-based page index
        "image_uri": STRING  // Path to the rendered page image, populated when
                             // imageOutputPath is set in ai_parse_document
      }
    ],
    "source_uri": STRING   // Source document URI
  },
  "error_status": {...}
}

chunk_to_embed形式

chunk_to_embed フィールドは、生のチャンク テキストとドキュメント レベルのコンテキストを組み合わせて、セマンティック検索中の取得品質を向上させることで、チャンクごとに構築された 1 つの文字列です。

文字列は、次の部分で構成されます。

• ドキュメント メタデータ: Document Title、 Page Header、 Page Footer、 Section Header、 Caption、 Footnote、 Page Number。 解析されたドキュメント構造から直接抽出されます。
• ドキュメントフィールド:追加:ドキュメントレベルのフィールドのキー:値行。 schemaオプションがない場合、LLMは文書ごとにフィールド名(例:「会社」「文書タイプ」「会計年度」)を検出します。 schemaオプションでは、入力したキーが機能に使われます。
• ドキュメント コンテキスト文: LLM によって生成された、ドキュメントの内容を要約した 1 つの文。
• コンテンツ: 生のチャンク テキスト。 チャンクの chunk_to_retrieve フィールドと同じ値。
• テーブルの概要: LLM で生成されたテーブルの内容の簡単な言い換え。 テーブルを含むチャンクの場合、関数はこのテーブルの概要と、テーブルが回答できる自然言語の質問のセットを追加します。
• 関連する質問: テーブルが回答できる自然言語の質問。テーブル コンテンツの取得の再現率を向上させるために使用されます。

文字列は、次のテンプレートに従います。

Document Title: {doc_title}
Page Header: {page_header}
Page Footer: {page_footer}
Section Header: {section_header}
Caption: {caption}
Footnote: {footnote}
Page Number: {page_number}
{additional_document_fields}

{document_context_sentence}

Table summary: {table_summary}

Content:
{chunk_to_retrieve}

Related questions:
{qa_text}

Document Title: Acme Corp 2024 Annual Report
Page Header:
Page Footer:
Section Header: Risk Factors
Caption:
Footnote:
Page Number: 14
Company: Acme Corp
Document Type: 10-K
Fiscal Year: 2024

Acme Corp's 2024 annual report covering financial performance and risk disclosures across global operating segments.

Content:
Our business faces a number of risks, including competition from established providers, evolving regulatory requirements, and concentration in a small number of large customers.

例示

プレーンテキストやマークダウンを用意してください

以下の例は、検索インデックス作成のためのプレーンテキスト STRING を準備しています。

SELECT ai_prep_search(
  'Quarterly revenue grew twenty percent year over year.',
  options => map('version', '2.0')
);

チェーンとai_parse_document

次の例では、ai_prep_searchai_parse_documentを使用してチェーンし、Unity カタログ ボリュームに格納されている未加工ドキュメントから検索可能なチャンクを生成します。

WITH parsed_documents AS (
  SELECT ai_parse_document(content) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
)
SELECT ai_prep_search(parsed) AS result
FROM parsed_documents;

schemaオプションで構造化メタデータを抽出

以下の例では、単純なスキーマを用いて、すべてのチャンクで company、 document_type、 fiscal_year の文字列メタデータを抽出します。

WITH parsed_documents AS (
  SELECT ai_parse_document(content) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
)
SELECT ai_prep_search(
  parsed,
  map('schema', '["company", "document_type", "fiscal_year"]')
) AS result
FROM parsed_documents;

高度なスキーマを用いてタイプ付きメタデータを抽出します

以下の例では、フィールドの種類と記述を指定するために高度なスキーマを使用しています。 記述は抽出を導き、 fiscal_year は整数として返されます。

WITH parsed_documents AS (
  SELECT ai_parse_document(content) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
)
SELECT ai_prep_search(
  parsed,
  map(
    'schema',
    '{
      "company": {"type": "string", "description": "Legal business name"},
      "document_type": {"type": "string", "description": "Filing or document type"},
      "fiscal_year": {"type": "integer", "description": "Fiscal year covered by the document"}
    }'
  )
) AS result
FROM parsed_documents;

Surfaceメタデータフィールドを列として

以下の例はチャンクをフラット化し、 schema オプション内の各キーを独立した列に投影します:

WITH parsed_documents AS (
  SELECT ai_parse_document(content) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
),
prepped_documents AS (
  SELECT ai_prep_search(
    parsed,
    map('schema', '["company", "document_type", "fiscal_year"]')
  ) AS result
  FROM parsed_documents
)
SELECT
  chunk.value:chunk_id::STRING AS chunk_id,
  chunk.value:chunk_to_embed::STRING AS chunk_to_embed,
  chunk.value:metadata:company::STRING AS company,
  chunk.value:metadata:document_type::STRING AS document_type,
  chunk.value:metadata:fiscal_year::INT AS fiscal_year
FROM
  prepped_documents,
  LATERAL variant_explode(prepped_documents.result:document.contents) AS chunk;

ベクター検索ソース テーブルを作成する

次の例では、出力を個々のチャンク行にフラット化し、Delta テーブルに書き込みます。 テーブルは、埋め込み列としてを使用し、主キーとしてchunk_to_embedを使用して、chunk_id インデックスのソースとして使用できます。

WITH parsed_documents AS (
  SELECT
    path,
    ai_parse_document(content) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
),
prepped_documents AS (
  SELECT
    path,
    ai_prep_search(parsed) AS result
  FROM parsed_documents
)
SELECT
  chunk.value:chunk_id::STRING AS chunk_id,
  chunk.value:chunk_position::INT AS chunk_position,
  chunk.value:chunk_to_retrieve::STRING AS chunk_to_retrieve,
  chunk.value:chunk_to_embed::STRING AS chunk_to_embed,
  chunk.value:metadata AS metadata,
  prepped_documents.path AS source_uri
FROM
  prepped_documents,
  LATERAL variant_explode(prepped_documents.result:document.contents) AS chunk;

結果の行には、次のスキーマがあります。

マルチモーダル取得を有効にする

ai_parse_document オプションを使用してimageOutputPathが呼び出されると、レンダリングされたページイメージが Unity カタログ ボリュームに保存され、各チャンクのimage_uri配列のpagesフィールドが設定されます。 これらの画像参照は、クエリ時に視覚対応モデルに渡して、テキストで完全に表現されていないブロック ダイアグラム、グラフ、テーブルなど、視覚的なコンテキストを必要とする質問に回答できます。

WITH parsed_documents AS (
  SELECT ai_parse_document(
    content,
    map(
      'imageOutputPath', '/Volumes/catalog/schema/volume/page_images/',
      'descriptionElementTypes', '*'
    )
  ) AS parsed
  FROM READ_FILES('/Volumes/mydata/documents/', format => 'binaryFile')
),
prepped_documents AS (
  SELECT ai_prep_search(parsed) AS result
  FROM parsed_documents
)
SELECT
  chunk.value:chunk_id::STRING AS chunk_id,
  chunk.value:chunk_to_embed::STRING AS chunk_to_embed,
  chunk.value:pages AS pages
FROM
  prepped_documents,
  LATERAL variant_explode(prepped_documents.result:document.contents) AS chunk;

制限事項

• VARIANTに合格したら、有効なai_parse_document出力を使いましょう。 他の VARIANT データまたはサポートされていないスキーマ バージョンを渡すと、予期しない結果やエラーが発生する可能性があります。
• STRINGを通過するときは、プレーンテキストかマークダウンを使ってください。 構造化されたパースドキュメント出力でないJSON文字列は、拒否されるのではなく、リテラルテキストとしてインデックスされます。
• 最大入力サイズは、 ai_parse_documentの最大出力サイズと一致します。

関連する関数

• ai_classify 関数
• ai_extract 関数
• ai_parse_document 関数
• ai_search 関数
• ai_enrich 関数