ai_search Função

Aplica-se a: Databricks SQL Databricks Runtime

A ai_search() função recupera informações de uma ou mais fontes de conhecimento. 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 busca otimizadas, recupera e desduplica resultados entre fontes, os reclassifica por relevância e retorna os documentos mais relevantes. Por padrão, 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 composto de IA — 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 do 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 busca por IA, ou tabelas sincronizadas com Lakebase com Lakebase Search ativado.
• Para usar uma tabela sincronizada com Lakebase, prepare-a primeiro para busca. Veja configuração Lakebase.
• Se você estiver usando computação serverless, a versão do ambiente serverless deve ser definida como 3 ou superior, pois isso permite recursos como VARIANT.
• A ai_search função está disponível usando notebooks Databricks, editor SQL, fluxos de trabalho Databricks, jobs ou Spark Declarative Pipelines no Lakeflow.

Sintaxe

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

Argumentos

• query: uma expressão STRING ou VARIANT. A consulta de busca em linguagem natural. VARIANT a entrada, como a saída de outra função de IA, é serializada internamente para uma string JSON.
• knowledge_sources: A VARIANT ou STRING expressão contendo um array JSON de configurações de fonte de conhecimento para pesquisar. Veja Configuração da fonte de conhecimento. Você 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>. Chaves com suporte:
  • 'version': A versão da função a ser usada.
  • 'generate_answer': 'true' (padrão) ou 'false'. Quando 'true', a função sintetiza uma resposta fundamentada em linguagem natural a partir dos documentos recuperados e a retorna no answer campo. Defina para 'false' devolver apenas documentos.
  • 'generate_citations': 'true' ou 'false' (padrão). Quando 'true', a função retorna citações que mostram quais blocos recuperados o modelo usou para suportar sua resposta gerada. Essa opção precisa 'generate_answer' ser 'true'.

Configuração da fonte de dados de conhecimento

O knowledge_sources argumento é um array JSON. Cada elemento é um {type, config} envelope. O type campo identifica como ai_search se conecta à fonte e é separado do nome do recurso voltado para o cliente. Defina type para vector_search um índice de Busca por IA, 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 se combinar vector_search e lakebase_search gerar fontes, até o limite de 10 fontes.

Configuração do índice de busca da IA

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

O exemplo a seguir configura um índice de busca por 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 busca por IA a partir de documentos brutos, use ai_parse_document e ai_prep_search crie blocos prontos para busca em uma tabela Delta. Depois , crie um índice de busca por IA a partir dessa tabela. Depois que o índice estiver online, use seu nome em três níveis como index_name.

Configuração da base do lago

Antes de poder usar uma tabela sincronizada com Lakebase como fonte de conhecimento, prepare-a para busca:

1. Ative o Lakebase Search e instale as extensões. Siga o Lakebase Search para ativar o Lakebase Search nas configurações do seu projeto, depois conecte-se ao banco de dados Postgres do projeto e instale a lakebase_vector extensão executando CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;. Ele fornece a busca vetorial aproximada pelo vizinho mais próximo que ai_search utiliza. Ativar o Lakebase Search requer acesso beta e é irreversível.
2. Sincronize sua tabela do Catálogo Unity com o projeto. Use uma tabela sincronizada, mapeie a coluna de embedding para uma vector(n) coluna e construa um lakebase_ann índice nela. A dimensão n deve corresponder à saída do seu modelo de incorporação.
3. Gerar as incorporações offline com um endpoint de serviço modelo. Preencha a coluna de embedding com um modelo de embedding — por exemplo, consultando um modelo de embedding com ai_query — e então passe esse mesmo endpoint como embedding_model (veja abaixo). ai_search incorpora cada consulta com ele no momento da busca, de modo que a consulta e as incorporações do documento armazenado compartilham um espaço vetorial.

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

O exemplo a seguir configura uma tabela Lakebase como fonte de conhecimento. Substitua embedding_model pelo endpoint que você 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 juntos. Cada combinação de valores significa algo diferente:

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

Examples

Pesquisa básica

O exemplo a seguir pesquisa um índice de busca por IA e retorna documentos ranqueados 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;

Devolver chunks de suporte para a resposta gerada

O exemplo a seguir retorna o subconjunto de chunks recuperados que o modelo selecionou como suporte à 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 retornados. Use o document_index em cada citação para escolher os que apoiam nesse arranjo. Esses índices só são válidos em uma única resposta. Eles podem mudar entre chamadas, quando a reclassificação muda ou quando o índice é atualizado.

Busca multi-fonte com instruções

O exemplo a seguir pesquisa em dois índices de busca por IA e é usado instructions para direcionar a geração de consultas e o reposicionamento:

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 uma tabela Lakebase

O exemplo a seguir pesquisa uma tabela sincronizada do Lakebase e retorna documentos ranqueados 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 busca por IA e uma tabela Lakebase

O exemplo a seguir pesquisa um índice de busca por IA e uma tabela Lakebase na mesma chamada. Os resultados de ambas as fontes são desduplicados, reordenados juntos e retornados como uma única lista ranqueada:

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 a seguir enriquece cada chamado de suporte com documentação relevante e uma solução sugerida. Como a geração de respostas está ativada por padrão, 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 em instead.

Limitations

• ai_search suporta índices de busca por IA ("type": "vector_search") e tabelas sincronizadas com Lakebase ("type": "lakebase_search") como fontes de conhecimento.
• Você pode especificar até 10 fontes de conhecimento por chamada, em qualquer combinação dos tipos suportados.
• O instructions argumento é limitado 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