ai_search Función

Se aplica a: Databricks SQL Databricks Runtime

La ai_search() función recupera información de una o más fuentes de conocimiento. Las fuentes de conocimiento pueden incluir índices de búsqueda con IA o tablas sincronizadas con Lakebase con Lakebase Search activado.

Dada una consulta en lenguaje natural y fuentes de conocimiento configuradas para la llamada, la función genera consultas de búsqueda optimizadas, recupera y deduplica resultados entre fuentes, los reclasifica por relevancia y devuelve los documentos más relevantes. Por defecto, también sintetiza una respuesta fundamentada en lenguaje natural sobre los documentos recuperados.

Úsalo ai_search para enriquecer datos operativos con contexto relevante a gran escala, construir pipelines de generación aumentada por recuperación por lotes (RAG) o exponer la recuperación como herramienta a un sistema de IA compuesta — todo desde una única llamada a una función SQL.

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.
• Una o más fuentes de conocimiento para buscar: índices de búsqueda de IA, o tablas sincronizadas de Lakebase con Lakebase Search activado.
• Para usar una tabla sincronizada con Lakebase, prepárala primero para la búsqueda. Ver configuración de Lakebase.
• Si usas computación sin servidor, la versión del entorno serverless debe estar configurada en 3 o superior, ya que esto permite funciones como VARIANT.
• La ai_search función está disponible utilizando cuadernos Databricks, editor SQL, flujos de trabajo Databricks, trabajos o Spark Declarative Pipelines en Lakeflow.

Syntax

ai_search(query, knowledge_sources [, instructions] [, options])

Argumentos

• query: una expresión STRING o VARIANT. La consulta de búsqueda en lenguaje natural. VARIANT la entrada, como la salida de otra función de IA, se serializa internamente en una cadena JSON.
• knowledge_sources: A VARIANT o STRING expresión que contiene un array JSON de configuraciones fuente de conocimiento para buscar. Consulta Configuración de la fuente de conocimiento. Puedes especificar hasta 10 fuentes de conocimiento.
• instructions: Una expresión opcional STRING de hasta 4.000 caracteres. Instrucciones en lenguaje natural que guían la generación de consultas, la generación de filtros de metadatos y la reclasificación. Por ejemplo: 'Prefer official documentation over internal articles when both cover the same topic.'
• options: un objeto opcional MAP<STRING, STRING>. Claves admitidas:
  • 'version': La versión de función a usar.
  • 'generate_answer': 'true' (valor predeterminado) o 'false'. Cuando 'true', la función sintetiza una respuesta fundamentada en lenguaje natural a partir de los documentos recuperados y la devuelve al answer campo. Configura para 'false' devolver solo documentos.
  • 'generate_citations': 'true' o 'false' (por defecto). Cuando 'true', la función devuelve citas que muestran qué fragmentos recuperados usó el modelo para soportar su respuesta generada. Esta opción debe 'generate_answer' ser 'true'.

Configuración del origen de conocimiento

El knowledge_sources argumento es un arreglo JSON. Cada elemento es un {type, config} envoltorio. El type campo identifica cómo ai_search se conecta al código fuente y es independiente del nombre del recurso orientado al cliente. Configura type para vector_search un índice de AI Search, o lakebase_search para una tabla sincronizada con Lakebase con Lakebase Search activado. El config campo contiene la configuración específica de la fuente.

Una sola llamada puede combinarse vector_search y lakebase_search obtener fuentes, hasta el límite de 10 fuentes.

Configuración del índice de búsqueda de IA

Para un índice de búsqueda de IA con type el conjunto en vector_search, config acepta las siguientes claves:

El siguiente ejemplo configura un índice de búsqueda de IA como fuente de conocimiento:

[
  {
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }
]

Para construir un índice de búsqueda con IA a partir de documentos en bruto, utiliza ai_parse_document y ai_prep_search crea bloques listos para búsqueda en una tabla Delta. Luego crea un índice de búsqueda de IA a partir de esa tabla. Después de que el índice esté en línea, utiliza su nombre de tres niveles como index_name.

Configuración de la base del lago

Antes de poder usar una tabla sincronizada con Lakebase como fuente de conocimiento, prepárala para la búsqueda:

1. Activa Lakebase Search e instala las extensiones. Sigue Lakebase Search para activar Lakebase Search en la configuración de tu proyecto, luego conéctate a la base de datos Postgres del proyecto e instala la lakebase_vector extensión ejecutando CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;. Proporciona la búsqueda vectorial aproximada del vecino más cercano que ai_search utiliza. Habilitar Lakebase Search requiere acceso beta y es irreversible.
2. Sincroniza tu tabla de Unity Catalog con el proyecto. Usa una tabla sincronizada, mapea la columna de incrustación a una vector(n) columna y construye un lakebase_ann índice sobre ella. La dimensión n debe coincidir con la salida de tu modelo de incrustación.
3. Genera las incrustaciones fuera de línea con un endpoint de servicio de modelo. Llena la columna de incrustación con un modelo de incrustación — por ejemplo, consultando un modelo de incrustación con ai_query — y luego pasa ese mismo extremo como embedding_model (véase más abajo). ai_search incrusta cada consulta en el momento de búsqueda, de modo que la consulta y las incrustaciones de documentos almacenadas comparten un espacio vectorial.

Para una fuente de conocimiento de Lakebase con type conjunto en lakebase_search, config acepta las siguientes claves:

El siguiente ejemplo configura una tabla Lakebase como fuente de conocimiento. Sustituye embedding_model por el endpoint que usaste para incrustar la tabla fuera de línea:

[
  {
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }
]

Returns

A VARIANT con el siguiente esquema:

{
  "document": [
    {
      "page_content": STRING,  // Text content of the retrieved chunk
      "doc_uri": STRING,       // URI of the source document
      "metadata": MAP          // Additional metadata from the index
    }
  ],
  "answer": STRING,            // Grounded answer synthesized from the retrieved
                               // documents, or null
  "citations": [               // Present only when generate_citations is true
    {
      "document_index": INT    // Position in the document array above, starting at 0
    }
  ]
}

Cuando generate_citations es true, lee los answer campos y citations juntos. Cada combinación de valores significa algo diferente:

• Un no nulo answer con un array vacío citations significa que se generó una respuesta, pero no se seleccionó ningún fragmento devuelto.
• Un nulo answer con un array vacío citations significa que la generación de citas se ejecutó pero no produjo citas porque no se generó una respuesta fundamentada.
• Un valor nulo citations significa que la generación de citas no estaba disponible o no se invocó, incluyendo cuándo query es SQL NULL.

Examples

Búsqueda básica

El siguiente ejemplo busca en un índice de búsqueda de IA y devuelve documentos clasificados y una respuesta fundamentada:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }]')
) AS result;

Devuelve los chunks de soporte para la respuesta generada

El siguiente ejemplo devuelve el subconjunto de fragmentos recuperados que el modelo seleccionó para soportar la respuesta:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url"
    }
  }]'),
  options => map('generate_citations', 'true')
) AS result;

El document array aún contiene el conjunto completo de chunks devueltos. Usa el document_index de cada cita para elegir las que apoyan de ese conjunto. Estos índices solo son válidos dentro de una única respuesta. Pueden cambiar entre llamadas, cuando cambia el reranking o cuando se actualiza el índice.

Búsqueda multifuente con instrucciones

El siguiente ejemplo busca en dos índices de búsqueda de IA y se utiliza instructions para guiar la generación y reclasificación de consultas:

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.internal_kb", "text_col": "body", "doc_uri_col": "source_uri"}
    }
  ]'),
  'Focus on firewall rules and VPC/VNet configuration. Prefer official documentation over internal articles when both cover the same topic.'
) AS result;

Buscar en una tabla de Lakebase

El siguiente ejemplo busca una tabla sincronizada en Lakebase y devuelve documentos clasificados y una respuesta fundamentada:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }]')
) AS result;

Combina un índice de búsqueda con IA y una tabla de Lakebase

El siguiente ejemplo busca en un índice de búsqueda de IA y en una tabla de Lakebase en la misma llamada. Los resultados de ambas fuentes se deduplican, se reordenan juntos y se devuelven como una sola lista clasificada:

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "lakebase_search",
      "config": {
        "index_name": "prod_catalog.docs.internal_kb_synced",
        "text_col": "body",
        "doc_uri_col": "source_uri",
        "embedding_column": "body_embedding",
        "embedding_model": "databricks-gte-large-en",
        "lakebase_project_id": "my-lakebase-project"
      }
    }
  ]')
) AS result;

Enriquece una tabla con recuperación y una respuesta generada

El siguiente ejemplo enriquece cada ticket de soporte con documentación relevante y una solución sugerida. Como la generación de respuestas está activada por defecto, la resolución sugerida está disponible directamente en el answer campo — no se requiere un paso de generación separado.

SELECT
  ticket_id,
  customer_description,
  ai_search(
    customer_description,
    PARSE_JSON('[{
      "type": "vector_search",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]'),
    'Find product documentation, known issues, and troubleshooting guides relevant to this support ticket.'
  ):answer::STRING AS suggested_resolution
FROM support.tickets.open_tickets;

Para controlar el formato de salida o usar un modelo específico, configura 'generate_answer' y 'false' encadena los documentos recuperados en ai_query en su lugar.

Limitaciones

• ai_search soporta índices de búsqueda con IA ("type": "vector_search") y tablas sincronizadas con Lakebase ("type": "lakebase_search") como fuentes de conocimiento.
• Puedes especificar hasta 10 fuentes de conocimiento por llamada, en cualquier combinación de los tipos soportados.
• El instructions argumento está limitado a 4.000 caracteres.

Funciones relacionadas

• ai_parse_document Función
• ai_prep_search Función
• ai_query Función
• ai_extract Función
• ai_enrich Función