ai_prep_search Función

Se aplica a: Databricks SQL Databricks Runtime

La ai_prep_search() función transforma el contenido del documento en un formato optimizado para sistemas de búsqueda vectorial RAG y recuperación de información. Acepta tanto la salida estructurada o ai_parse_document texto plano y contenido de marcado STRING . Para cada documento de entrada, la función divide el contenido en fragmentos semánticos, enriquece cada fragmento con contexto de nivel de documento, como el título del documento, los encabezados de sección, las referencias de página y genera una representación lista para insertar.

Seguridad de datos

Los datos del documento se procesan dentro del perímetro de seguridad de Databricks. Databricks no almacena los parámetros que se pasan a las llamadas a funciones de IA, pero sí conserva los detalles de la ejecución de metadatos, como la versión de ejecución de Databricks utilizada.

Requisitos

• Databricks Runtime 18.2 o superior.
• Si usa proceso sin servidor, también se requiere lo siguiente:
  • La versión del entorno sin servidor debe establecerse en 3 o superior, ya que esto habilita características como VARIANT.
  • Debe usar Python o SQL. Para obtener más características y limitaciones sin servidor, consulte Limitaciones de proceso sin servidor.
• La ai_prep_search función está disponible mediante cuadernos de Databricks, editor de SQL, flujos de trabajo, trabajos o canalizaciones de Lakeflow de Databricks.

Sintaxis

ai_prep_search(parsed [, options])

Argumentos

• parsed: Documentar el contenido para prepararse para la búsqueda. Uno de los siguientes:
  • Una expresión que VARIANT representa la salida estructurada de ai_parse_document.
  • Una STRING expresión que contiene texto plano o markdown. Las cadenas JSON que no son salida estructurada ai_parse_document (o relacionada) se tratan como texto literal y se agrupan en bloques de la misma manera.
• options: un objeto opcional MAP<STRING, STRING>. Claves admitidas:
  • 'version': la versión del esquema de salida que se va a usar.
  • 'schema': Un esquema JSON que define un conjunto de claves para la extracción de metadatos a nivel de documento. El esquema utiliza los mismos formatos que ai_extract:
    • Esquema simple: matriz JSON de nombres de campo (se supone que son cadenas)

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

    • Esquema avanzado: un objeto JSON con información de tipo, descripciones y estructuras anidadas
      • Admite stringlos tipos , integer, number, booleany enum . Realiza la validación de tipos. Los valores que no son válidos producen un error. Máximo de 500 valores de enumeración.
      • Admite objetos anidados mediante "type": "object" con "properties"
      • Admite matrices de primitivos o objetos mediante "type": "array" con "items"
      • Campo opcional "description" para cada propiedad para guiar la calidad de extracción

Devoluciones

que VARIANT contiene fragmentos de documento con formato para la indexación de búsqueda vectorial. Cada fila de la salida representa un documento de entrada.

El esquema de salida es:

{
  "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": {...}
}

formato de chunk_to_embed

El chunk_to_embed campo es una sola cadena creada por fragmento mediante la combinación del texto del fragmento sin formato con contexto de nivel de documento para mejorar la calidad de recuperación durante la búsqueda semántica.

La cadena se compone de las siguientes partes:

• Metadatos del documento: Document Title, Page Header, Page Footer, Section HeaderCaption, , Footnote, . Page Number Extraído directamente de la estructura del documento analizado.
• Campos de documento: adicionales. Clave: líneas de valor para campos a nivel de documento. Sin esta schema opción, un LLM descubre nombres de campos por documento (por ejemplo, "Empresa", "Tipo de documento", "Año fiscal"). Con la schema opción, la función utiliza las teclas que proporcionas.
• Frase de contexto del documento: una sola oración que resume lo que trata el documento, generado por un LLM.
• Contenido: texto de fragmento sin formato. El mismo valor que el chunk_to_retrieve campo del fragmento.
• Resumen de tabla: una frase breve generada por LLM del contenido de la tabla. En el caso de los fragmentos que contienen una tabla, la función anexa este resumen de tabla y un conjunto de preguntas relacionadas de lenguaje natural que la tabla puede responder.
• Preguntas relacionadas: preguntas en lenguaje natural que la tabla es capaz de responder, que se usa para mejorar la recuperación del contenido de la tabla.

La cadena sigue esta plantilla:

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.

Ejemplos

Preparar texto plano o markdown

El siguiente ejemplo prepara un texto STRING plano para la indexación de búsqueda:

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

Cadena con ai_parse_document

En el ejemplo siguiente se encadena ai_prep_search con ai_parse_document para generar fragmentos listos para la búsqueda a partir de documentos sin procesar almacenados en un volumen de Catálogo de 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;

Extrae metadatos estructurados con la schema opción

El siguiente ejemplo utiliza un esquema sencillo para extraer company, document_type, y fiscal_year como metadatos de cadena en cada bloque.

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;

Extraer metadatos tipados usando un esquema avanzado

El siguiente ejemplo utiliza un esquema avanzado para especificar tipos de campos y descripciones. Las descripciones guían la extracción y fiscal_year se devuelve como un entero.

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;

Campos de metadatos Surface como columnas

El siguiente ejemplo aplana los chunks y proyecta cada tecla en la schema opción hacia su propia columna:

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;

Creación de una tabla de origen de búsqueda vectorial

En el ejemplo siguiente se aplana la salida en filas de fragmentos individuales y se escriben en una tabla Delta. Después, la tabla se puede usar como origen para un índice de Búsqueda de IA de Databricks , mediante chunk_to_embed como columna de inserción y chunk_id como clave principal.

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;

Las filas resultantes tienen el esquema siguiente:

Habilitación de la recuperación multi modal

Cuando ai_parse_document se llama a con la imageOutputPath opción , las imágenes de página representadas se guardan en un volumen del catálogo de Unity y el image_uri campo de la matriz de pages cada fragmento se rellena. Estas referencias de imagen se pueden pasar a un modelo compatible con la visión en el momento de la consulta para responder a preguntas que requieren contexto visual, como diagramas de bloques, gráficos o tablas que no están totalmente representados en texto.

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;

Limitaciones

• Cuando pases un VARIANT, usa una salida válida ai_parse_document . Pasar otros VARIANT datos o una versión de esquema no compatible puede producir resultados o errores inesperados.
• Cuando pases un STRING, usa texto plano o markdown. Las cadenas JSON que no son salida estructurada de documentos de análisis se indexan como texto literal en lugar de ser rechazadas.
• El tamaño máximo de entrada es coherente con el tamaño máximo de salida de ai_parse_document.

Funciones relacionadas

• ai_classify Función
• ai_extract Función
• ai_parse_document Función
• ai_search Función
• ai_enrich Función