ai_prep_search 函數

適用於：Databricks SQL Databricks Runtime

此功能 ai_prep_search() 將文件內容轉換為最適合 RAG 向量搜尋與資訊檢索系統的格式。 它接受結構化輸出 ai_parse_document 或純文字與 markdown STRING 內容。 對於每個輸入文件，函式會將內容拆分為語意區塊，並以文件層級的上下文（如文件標題、章節標題、頁面參考）豐富每個區塊，並產生可嵌入的表示。

數據安全性

您的文件數據會在 Databricks 安全性周邊內處理。 Databricks 不儲存傳遞給 AI 函式呼叫的參數，但會保留元資料執行細節，例如 Databricks 執行時版本。

要求

• Databricks 執行環境 18.2 或以上。
• 如果你使用無伺服器運算，以下條件也必須具備：
  • 無伺服器環境版本必須設定為 3 或更高版本，因為這會啟用 VARIANT.
  • 必須使用 Python 或 SQL 其中之一。 如需其他無伺服器功能和限制，請參閱 無伺服器計算限制。
• 此功能 ai_prep_search 可透過 Databricks 筆記本、SQL 編輯器、Databricks 工作流程、工作或 Lakeflow 管線使用。

語法

ai_prep_search(parsed [, options])

引數

• parsed：準備搜尋所需的文件內容。 下列其中一項：
  • 一個 VARIANT 表示結構 ai_parse_document化輸出的表達式。
  • STRING包含純文字或標記的表達式。 非結構 ai_parse_document 化（或相關）輸出的 JSON 字串會被視為文字，並以相同方式分塊。
• options：一個可選 MAP<STRING, STRING>的 。 支援的按鍵：
  • 'version'：輸出結構的版本。
  • 'schema'： 一個定義文件層級元資料擷取金鑰集的 JSON 架構。 該結構使用與以下格式相同的格式：ai_extract
    • 簡單結構：一個 JSON 陣列，包含欄位名稱（假設為字串）

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

    • 進階結構：一個包含型別資訊、描述與巢狀結構的 JSON 物件
      • 支援、stringinteger、number、booleanenum、及類型。 執行型別驗證。 不有效的數值會導致錯誤。 最多可有 500 個 enum 值。
      • 支援巢狀物件，使用"type": "object""properties"
      • 支援使用 "type": "array" 的原始元件或物件陣列 "items"
      • 每個物業的選用 "description" 欄位用以指導萃取品質

退貨

包含 VARIANT 格式化為向量搜尋索引的文件區塊。 輸出中的每一列代表一個輸入文件。

輸出模式為：

{
  "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 欄位是每個區塊建立的單一字串，透過結合原始區塊文字與文件層級上下文，提升語意搜尋時的檢索品質。

弦由以下部分組成：

• 文件元資料：Document Title， Page Header， 。 Page FooterSection HeaderCaptionFootnotePage Number 直接從解析過的文件結構中擷取。
• 文件欄位：附加 文件層級欄位的 Key： value 行。 若沒有這個選項， schema LLM 會發現每個文件的欄位名稱（例如「公司」、「文件類型」、「財政年度」）。 有了 schema 這個選項，功能會使用你提供的金鑰。
• 文件上下文句子：由大型語言模型（LLM）產生的一句話，總結文件內容。
• 內容：原始的區塊文字。 該區塊的值與 chunk_to_retrieve 欄位相同。
• 表格摘要：由大型語言模型生成的簡短意譯。 對於包含表格的區塊，函式會附加此表格摘要及一組表格可回答的相關自然語言問題。
• 相關問題：表能回答的自然語言問題，用以提升表內容的檢索性。

字串遵循以下範本：

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.

Examples

準備純文字或降價

以下範例準備了用於搜尋索引的純文字 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_typefiscal_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 表格。 此表格可作為 Databricks AI 搜尋 索引的來源，作為 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函式