ai_search Função

Aplica-se a: Databricks SQL Databricks Runtime

A ai_search() função recupera informação de uma ou mais fontes de conhecimento. As fontes de conhecimento podem incluir índices de AI Search ou tabelas sincronizadas com Lakebase com Lakebase Search ativado.

Dada uma consulta em linguagem natural e fontes de conhecimento configuradas para a chamada, a função gera consultas de pesquisa otimizadas, recupera e desduplica resultados entre fontes, reclassifica-os por relevância e devolve os documentos mais relevantes. Por defeito, também sintetiza uma resposta fundamentada em linguagem natural sobre os documentos recuperados.

Use ai_search para enriquecer dados operacionais com contexto relevante em escala, construir pipelines de geração aumentada por recuperação em lote (RAG) ou expor a recuperação como ferramenta a um sistema de IA composto — tudo a partir de uma única chamada de função SQL.

Segurança de dados

Os dados do documento são processados dentro do perímetro de segurança Databricks. O Databricks não armazena os parâmetros que são passados para as chamadas de função de IA, mas mantém detalhes de execução de metadados, como a versão de Runtime do Databricks utilizada.

Requisitos

• Databricks Runtime 18.2 ou superior.
• Uma ou mais fontes de conhecimento para pesquisar: índices de AI Search, ou tabelas sincronizadas Lakebase com Lakebase Search ativado.
• Para usar uma tabela sincronizada com Lakebase, prepare-a primeiro para a pesquisa. Ver configuração Lakebase.
• Se estiver a usar computação serverless, a versão do ambiente serverless deve estar definida para 3 ou superior, pois isto permite funcionalidades como VARIANT.
• A ai_search função está disponível utilizando notebooks Databricks, editor SQL, fluxos de trabalho Databricks, jobs ou Spark Declarative Pipelines no Lakeflow.

Sintaxe

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

Arguments

• query: Uma expressão STRING ou VARIANT. A consulta de pesquisa em linguagem natural. VARIANT a entrada, como a saída de outra função de IA, é serializada internamente para uma cadeia JSON.
• knowledge_sources: A VARIANT ou STRING expressão contendo um array JSON de configurações de fonte de conhecimento para pesquisar. Ver configuração da fonte de conhecimento. Pode especificar até 10 fontes de conhecimento.
• instructions: Uma expressão opcional STRING de até 4.000 caracteres. Instruções em linguagem natural que orientam a geração de consultas, geração de filtros de metadados e reclassificação. Por exemplo, 'Prefer official documentation over internal articles when both cover the same topic.'
• options: Um opcional MAP<STRING, STRING>. Teclas suportadas:
  • 'version': A versão da função a usar.
  • 'generate_answer': 'true' (por defeito) ou 'false'. Quando 'true', a função sintetiza uma resposta fundamentada em linguagem natural a partir dos documentos recuperados e devolve-a no answer campo. Defina para 'false' devolver apenas documentos.
  • 'generate_citations': 'true' ou 'false' (padrão). Quando 'true', a função devolve citações que mostram quais fragmentos recuperados o modelo usou para suportar a resposta gerada. Esta opção requer 'generate_answer' que seja 'true'.

Configuração da fonte de conhecimento

O knowledge_sources argumento é um array JSON. Cada elemento é um {type, config} envelope. O type campo identifica como ai_search se liga à fonte e é separado do nome do recurso voltado para o cliente. Definido type para vector_search um índice de AI Search, ou lakebase_search para uma tabela sincronizada com Lakebase com Lakebase Search ativado. O config campo contém a configuração específica da fonte.

Uma única chamada pode combinar vector_search e lakebase_search gerar fontes, até ao limite de 10 fontes.

Configuração do índice de pesquisa por IA

Para um índice de Pesquisa por IA com type definido para vector_search, config aceita as seguintes chaves:

O exemplo seguinte configura um índice de pesquisa de IA como fonte de conhecimento:

[
  {
    "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 um índice de pesquisa por IA a partir de documentos brutos, use ai_parse_document e ai_prep_search crie blocos prontos para pesquisa numa tabela Delta. Depois cria um índice de pesquisa por IA a partir dessa tabela. Depois de o índice estar online, use o seu nome de três níveis como index_name.

Configuração da base do lago

Antes de poderes usar uma tabela sincronizada com Lakebase como fonte de conhecimento, prepara-a para pesquisa:

1. Ativa a pesquisa do Lakebase e instala as extensões. Siga o Lakebase Search para ativar o Lakebase Search nas definições do seu projeto, depois ligue-se à base de dados Postgres do projeto e instale a lakebase_vector extensão executando CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;. Fornece a pesquisa vetorial aproximada do vizinho mais próximo que ai_search utiliza. Ativar a Pesquisa Lakebase requer acesso beta e é irreversível.
2. Sincronize a sua tabela do Catálogo Unity com o projeto. Usa uma tabela sincronizada, mapeia a coluna de embedding para uma vector(n) coluna e constrói um lakebase_ann índice sobre ela. A dimensão n deve corresponder à saída do seu modelo de embedding.
3. Gerar os embeddings offline com um endpoint de serviço de modelo. Preenche a coluna de embedding com um modelo de embedding — por exemplo, consultando um modelo de embedding com ai_query — e depois passa esse mesmo endpoint como embedding_model (ver abaixo). ai_search incorpora cada consulta no momento da pesquisa, de modo que a consulta e as incorporações do documento armazenado partilham um espaço vetorial.

Para uma fonte de conhecimento Lakebase com type definido como lakebase_search, config aceita as seguintes chaves:

O exemplo seguinte configura uma tabela Lakebase como fonte de conhecimento. Substitua embedding_model pelo endpoint que usou para incorporar a tabela offline:

[
  {
    "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 com o seguinte 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
    }
  ]
}

Quando generate_citations é true, leia os answer campos e citations em conjunto. Cada combinação de valores significa algo diferente:

• Um não-nulo answer com um array vazio citations significa que uma resposta foi gerada, mas nenhum bloco devolvido foi selecionado.
• Um null answer com um array vazio citations significa que a geração de citações foi executada mas não produziu citações porque não foi gerada uma resposta fundamentada.
• Um valor nulo citations significa que a geração de citações não estava disponível ou não foi invocada, incluindo quando query é SQL NULL.

Examples

Pesquisa básica

O exemplo seguinte pesquisa um índice de pesquisa por IA e retorna documentos classificados e uma resposta 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;

Devolve os blocos de suporte para a resposta gerada

O exemplo seguinte devolve o subconjunto de blocos recuperados que o modelo selecionou como suporte da resposta:

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;

O document array ainda contém o conjunto completo de chunks devolvidos. Use o document_index em cada citação para escolher as que apoiam essa lista. Estes índices só são válidos dentro de uma única resposta. Podem mudar entre chamadas, quando a reclassificação muda ou quando o índice é atualizado.

Pesquisa multi-fonte com instruções

O exemplo seguinte pesquisa em dois índices de AI Search e é utilizado instructions para orientar a geração de consultas e a reclassificação:

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;

Pesquise numa tabela Lakebase

O exemplo seguinte pesquisa uma tabela sincronizada no Lakebase e retorna documentos classificados e uma resposta 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;

Combine um índice de pesquisa por IA e uma tabela Lakebase

O exemplo seguinte pesquisa um índice de pesquisa por IA e uma tabela Lakebase na mesma chamada. Os resultados de ambas as fontes são desduplicados, reordenados em conjunto e devolvidos como uma única lista ordenada:

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;

Enriquecer uma tabela com recuperação e uma resposta gerada

O exemplo seguinte enriquece cada ticket de suporte com documentação relevante e uma solução sugerida. Como a geração de respostas está ativada por defeito, a resolução sugerida está disponível diretamente no answer campo — não é necessário um passo de geração 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 o formato de saída ou usar um modelo específico, defina 'generate_answer' e 'false' encadeie os documentos recuperados em ai_query vez disso.

Limitações

• ai_search suporta índices de pesquisa por IA ("type": "vector_search") e tabelas sincronizadas com Lakebase ("type": "lakebase_search") como fontes de conhecimento.
• Pode especificar até 10 fontes de conhecimento por chamada, em qualquer combinação dos tipos suportados.
• O instructions argumento limita-se a 4.000 caracteres.

Funções relacionadas

• ai_parse_document Função
• ai_prep_search Função
• ai_query Função
• ai_extract Função
• ai_enrich Função