ai_search Função

Aplica-se a: Databricks SQL Databricks Runtime

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

A ai_search() função recupera informações de um ou mais índices de busca por IA. Dada uma consulta em linguagem natural e índices configurados como fontes de conhecimento, 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.
• Um ou mais índices de AI Search para usar como fontes de conhecimento.
• 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.

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. Para um índice de busca por IA, defina type como o literal vector_search. O config campo contém a configuração específica da fonte.

Key	Obrigatório	Descrição
type	Yes	O tipo fonte de conhecimento. Atualmente, há suporte apenas para vector_search.
config	Yes	Um objeto contendo a configuração específica da fonte. Para vector_search, veja configuração do índice de busca do AI.

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:

Key	Obrigatório	Descrição
index_name	Yes	O nome de três níveis do Unity Catalog do índice de busca de IA, por catalog.schema.my_indexexemplo.
text_col	Yes	A coluna no índice que contém o texto do documento retornava como page_content.
doc_uri_col	Yes	A coluna no índice que contém o URI do documento retornou como doc_uri.
filter_columns	No	Uma string separada por vírgulas ou array JSON de colunas disponível para filtragem de metadados. Quando omitida, a lista é derivada do esquema de índice, excluindo as colunas de URI reservado, texto e documento.

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.

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
}

Campo	Tipo	Descrição
document	ARRAY	Conjunto de documentos recuperados, ordenados por relevância.
document[].page_content	STRING	Conteúdo do texto do pedaço recuperado.
document[].doc_uri	STRING	URI do documento fonte.
document[].metadata	MAP	Metadados adicionais do índice.
answer	STRING	Uma resposta fundamentada em linguagem natural, sintetizada a partir dos documentos recuperados. null quando a geração de respostas está desativada ou quando nenhum documento é recuperado.

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;

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;

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 atualmente suporta apenas índices de busca por IA. Definido "type": "vector_search" para cada fonte de conhecimento.
• Você pode especificar até 10 fontes de conhecimento por chamada.
• 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