ai_prep_search-Funktion

Gilt für: Databricks SQL Databricks Runtime

Die ai_prep_search() Funktion wandelt Dokumentinhalte in ein Format um, das für RAG-Vektorsuch- und Informationsabrufsysteme optimiert ist. Es akzeptiert entweder die strukturierte Ausgabe oder ai_parse_document den Klartext und Markdown-Inhalte STRING . Für jedes Eingabedokument teilt die Funktion Inhalte in semantische Blöcke auf, erweitert jeden Block durch Kontext auf Dokumentebene, z. B. Den Dokumenttitel, Abschnittsüberschriften, Seitenverweise und erzeugt eine einbettbare Darstellung.

Datensicherheit

Ihre Dokumentdaten werden innerhalb des Databricks-Sicherheitsperimeters verarbeitet. Databricks speichert die Parameter, die in die KI-Funktionsaufrufe eingegeben werden, nicht, behält aber Metadaten-Laufdetails, wie zum Beispiel die verwendete Databricks-Runtime-Version.

Anforderungen

• Databricks Runtime 18.2 oder höher.
• Wenn Sie Serverless Compute verwenden, ist auch Folgendes erforderlich:
  • Die serverlose Umgebungsversionsnummer muss auf 3 oder höher festgelegt werden, da dies Funktionen wie VARIANT ermöglicht.
  • Muss entweder Python oder SQL verwenden. Weitere serverlose Features und Einschränkungen finden Sie unter Serverless Compute-Einschränkungen.
• Die ai_prep_search Funktion ist mit Databricks-Notizbüchern, SQL-Editor, Databricks-Workflows, Aufträgen oder Lakeflow-Pipelines verfügbar.

Syntax

ai_prep_search(parsed [, options])

Argumente

• parsedDokumentieren Sie den Inhalt zur Vorbereitung auf die Suche. Eins der folgenden:
  • Ein Ausdruck, der VARIANT die strukturierte Ausgabe von ai_parse_documentdarstellt.
  • Ein Ausdruck, der STRING Klartext oder Markdown enthält. JSON-Strings, die keine strukturierte ai_parse_document (oder verwandte) Ausgabe sind, werden als wörtlicher Text behandelt und auf die gleiche Weise gehackt.
• options: Optional MAP<STRING, STRING>. Unterstützte Schlüssel:
  • 'version': Die Version des zu verwendenden Ausgabeschemas.
  • 'schema': Ein JSON-Schema, das einen Schlüsselsatz für die Metadatenextraktion auf Dokumentenebene definiert. Das Schema verwendet die gleichen Formate wie ai_extract:
    • Einfaches Schema: Ein JSON-Array von Feldnamen (als Zeichenfolgen angenommen)

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

    • Erweitertes Schema: Ein JSON-Objekt mit Typinformationen, Beschreibungen und geschachtelten Strukturen
      • Unterstützt string, integer, number, , booleanund enum Typen. Führt die Typüberprüfung aus. Ungültige Werte führen zu einem Fehler. Maximal 500 Enumerationswerte.
      • Unterstützt geschachtelte Objekte mit "type": "object""properties"
      • Unterstützt Arrays von Grundtypen oder Objekten, die mit "type": "array""items"
      • Optionales "description" Feld für jede Eigenschaft zur Anleitung der Extraktionsqualität

Rückkehr

Ein VARIANT Dokument, das Dokumentabschnitte enthält, die für die Vektorsuch-Indexierung formatiert sind. Jede Zeile in der Ausgabe stellt ein Eingabedokument dar.

Das Ausgabeschema lautet:

{
  "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 Format

Das chunk_to_embed Feld ist eine einzelne Zeichenfolge, die pro Block erstellt wird, indem der rohe Textabschnitt mit dem Kontext auf Dokumentebene kombiniert wird, um die Abrufqualität während der semantischen Suche zu verbessern.

Die Zeichenfolge besteht aus den folgenden Teilen:

• Dokumentmetadaten: Document Title, , Page Header, Page FooterSection Header, Caption, , Footnote. Page Number Extrahiert direkt aus der analysierten Dokumentstruktur.
• Dokumentfelder: zusätzliche Schlüssel: Wertzeilen für dokumentenebene Felder. Ohne diese schema Option entdeckt ein LLM Feldnamen pro Dokument (zum Beispiel "Unternehmen", "Dokumententyp", "Haushaltsjahr"). Mit der schema Option verwendet die Funktion die von dir bereitgestellten Tasten.
• Dokumentkontextsatz: Ein einzelner Satz, der zusammenfasst, worum es im Dokument geht, generiert von einer LLM.
• Inhalt: der unformatierte Text. Derselbe Wert wie das chunk_to_retrieve Feld für den Block.
• Tabellenzusammenfassung: eine kurze LLM-generierte Paraphrase des Tabelleninhalts. Bei Blöcken, die eine Tabelle enthalten, fügt die Funktion diese Tabellenzusammenfassung und eine Reihe verwandter Fragen in natürlicher Sprache an, die die Tabelle beantworten kann.
• Verwandte Fragen: Fragen in natürlicher Sprache, die die Tabelle beantworten kann, wird verwendet, um den Abrufrückruf für Tabelleninhalte zu verbessern.

Die Zeichenfolge folgt dieser Vorlage:

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.

Beispiele

Bereite Klartext oder Markdown vor.

Das folgende Beispiel bereitet einen Klartext STRING für die Suchindexierung vor:

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

Kette mit ai_parse_document

Im folgenden Beispiel werden Suchvorgänge aus rohen Dokumenten, die in einem Unity-Katalogvolume gespeichert sind, miteinander ai_prep_search verkettetai_parse_document:

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;

Extrahieren Sie strukturierte Metadaten mit der Option schema

Das folgende Beispiel verwendet ein einfaches Schema, um , document_type, und fiscal_year als String-Metadaten für jeden Chunk zu extrahierencompany.

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;

Extrahiere typisierte Metadaten mit einem fortgeschrittenen Schema

Das folgende Beispiel verwendet ein fortgeschrittenes Schema, um Feldtypen und Beschreibungen zu spezifizieren. Beschreibungen leiten die Extraktion und fiscal_year werden als ganze Zahl zurückgegeben.

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-Metadatenfelder als Spalten

Das folgende Beispiel flacht Chunks ab und projiziert jeden Schlüssel in der schema Option auf eine eigene Spalte:

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;

Erstellen einer Vektorsuchquelltabelle

Im folgenden Beispiel wird die Ausgabe in einzelne Datenabschnittszeilen vereinfacht und in eine Delta-Tabelle geschrieben. Die Tabelle kann dann als Quelle für einen Databricks AI Search-Index verwendet werden, indem chunk_to_embed sie als Einbettungsspalte und chunk_id als Primärschlüssel verwendet wird.

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;

Die resultierenden Zeilen weisen das folgende Schema auf:

Aktivieren des multi modalen Abrufs

Wenn ai_parse_document mit der imageOutputPath Option aufgerufen wird, werden gerenderte Seitenbilder in einem Unity-Katalogvolume gespeichert, und das image_uri Feld im Array der einzelnen Blöcke pages wird aufgefüllt. Diese Bildverweise können zur Abfragezeit an ein sehfähiges Modell übergeben werden, um Fragen zu beantworten, die visuellen Kontext erfordern, z. B. Blockdiagramme, Diagramme oder Tabellen, die nicht vollständig in Text dargestellt sind.

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;

Einschränkungen

• Wenn du ein VARIANTübergibst, verwende gültige ai_parse_document Ausgabe. Das Übergeben anderer VARIANT Daten oder einer nicht unterstützten Schemaversion kann zu unerwarteten Ergebnissen oder Fehlern führen.
• Wenn du ein STRINGFormular passierst, verwende Klartext oder Markdown. JSON-Strings, die keine strukturierte Parse-Dokument-Ausgabe sind, werden als wörtlicher Text indiziert und nicht abgelehnt.
• Die maximale Eingabegröße entspricht der maximalen Ausgabegröße von ai_parse_document.

Verwandte Funktionen

• ai_classify Funktion
• ai_extract Funktion
• ai_parse_document Funktion
• ai_search Funktion
• ai_enrich Funktion