Usar ai_query

info

Visualização

Este recurso está em Pré-visualização Pública.

ai_query É uma funçãoAI de propósito geral que permite consultar qualquer modelo AI compatível diretamente de SQL ou Python. Ao contrário AI Functions específicas para tarefas, que são construídas e otimizadas para uma única tarefa, ai_query oferece controle total sobre o modelo, o prompt e os parâmetros.

Para obter a sintaxe completa e a referência dos parâmetros, consulte a funçãoai_query.

Quando usar ai_query

Databricks recomenda começar com uma função AI específica para a tarefa, quando houver uma que corresponda ao seu objetivo. Use ai_query quando uma função específica da tarefa não atender às suas necessidades. Por exemplo, quando você precisa:

• Controle o prompt, os parâmetros do modelo ou o formato de saída com mais precisão.
• Consultar um modelo personalizado, ajustado ou externo
• Necessidade de flexibilidade para otimizar ainda mais a taxa de transferência ou a qualidade.

Melhores práticas

• Utilize modelos hospedados no Databricks. Use o endpoint do modelo de fundação hospedado Databricks(prefixado com databricks-), em vez do endpoint de provisionamento Taxa de transferência. Esses endpoints são totalmente gerenciados e escalados automaticamente sem provisionamento ou configuração.
• Selecione um modelo otimizado para inferência de lotes. Databricks otimiza modelos específicos para cargas de trabalho de alta taxa de transferência de lotes. A utilização de um modelo não otimizado pode resultar em redução da Taxa de transferência e em tempos de conclusão de tarefas mais longos. Consulte a seção Modelos suportados para obter a lista completa de modelos otimizados para lotes.
• Envie seu dataset completo em uma única consulta. AI Functions lidam automaticamente com paralelização, novas tentativas e escalonamento. A divisão manual de dados em pequenos lotes pode reduzir a Taxa de transferência.
• Defina failOnError como false para cargas de trabalho grandes. Isso permite que o Job seja concluído e retorne mensagens de erro para as linhas com falha, de forma que você retenha os resultados bem-sucedidos sem precisar reprocessar todo o dataset.

Modelos suportados

ai_query suporta modelos hospedados Databricks , modelos de provisionamento de taxa de transferência, modelos personalizados e modelos externos.

A tabela a seguir resume os tipos de modelo suportados, os modelos associados e os requisitos de configuração endpoint do modelo de serviço para cada um.

Tipo	Descrição	Modelos suportados	Requisitos
modelos hospedados no Databricks	Databricks hospeda esses modelos fundamentais e oferece endpoints pré-configurados que você pode consultar usando ai_query. Consulte a seção "Modelos básicos suportados" no Mosaic AI Model Serving para saber quais modelos são suportados para cada recurso de serviço de modelos e sua disponibilidade regional.	Consulte a lista completa de modelos básicos suportados no Mosaic AI Model Serving para obter a lista completa de modelos básicos suportados no serviço de modelos. Esses modelos são suportados e otimizados para iniciar a inferência de lotes e o fluxo de trabalho de produção: databricks-gpt-5-4 databricks-gpt-5-4-mini databricks-gpt-5-4-nano databricks-gpt-5-2 databricks-gpt-5-1 databricks-gpt-5 databricks-gpt-5-mini databricks-gpt-5-nano databricks-gemini-3-1-pro databricks-gemini-3-1-flash-lite databricks-gemini-3-pro databricks-gemini-3-flash databricks-gemini-2-5-pro databricks-gemini-2-5-flash databricks-claude-sonnet-4 databricks-gpt-oss-20b databricks-gpt-oss-120b databricks-gemma-3-12b databricks-llama-4-maverick databricks-meta-llama-3-3-70b-instruct databricks-meta-llama-3-1-8b-instruct databricks-qwen3-embedding-0-6b databricks-gte-large-en Outros modelos hospedados Databricksestão disponíveis para uso com AI Functions, mas não são recomendados para produção de inferência em lotes. Esses outros modelos são disponibilizados para inferência em tempo real usando APIs do Foundation Model, com pagamento por token.	Para usar esta funcionalidade, é necessário ter Databricks Runtime 15.4 LTS ou superior. Não requer provisionamento ou configuração endpoint . O uso desses modelos está sujeito aos termos do modelo aplicáveis e à disponibilidade regional AI Functions .
modelos de provisionamento Taxa de transferência	AI Functions trabalha com provisionamento Taxa de transferência de modelos implantados em modelo instalado.	Modelos de fundação ajustados implantados no modelo de instalação provisionamento Taxa de transferência de modelos implantados em modelo de usuário	Para modelos básicos ajustados, você deve criar um endpointde provisionamento Taxa de transferência no modelo instalado. Consulte Use ai_query com modelos de base para exemplos de Notebook. AI Functions não utilizam o provisionamento compute para o endpoint. AI Functions totalmente gerenciado o escalonamento utilizado para inferência de lotes.
Modelos personalizados e modelos externos	Você pode trazer seus próprios modelos personalizados ou externos e consultá-los usando AI Functions. AI Functions oferece flexibilidade para que você possa consultar modelos para cenários de inferência em tempo real ou em lote.	Modelos básicos hospedados fora do Databricks. Esses modelos são disponibilizados por meio de modelos externos. Consulte a seção "Acessar modelos básicos hospedados fora do Databricks" para obter uma lista de modelos externos compatíveis. Modelos tradicionais personalizados ML e aprendizado profundo	Para modelos externos, você deve criar um endpointde modelo de serviço externo. Para modelos personalizados ML e DL tradicionais, você deve criar um endpointde servir modelo personalizado. Consulte o exemplo em Notebook para obter um exemplo de uso ai_query com modelos ML tradicionais .

Use ai_query com modelos de fundação

O exemplo a seguir demonstra como usar ai_query com um modelo de base hospedado pelo Databricks.

• Consulte a funçãoai_query para obter detalhes de sintaxe e parâmetros.
• Consulte Entradas multimodais para exemplos de consultas de entrada multimodal.
• Consulte os exemplos para cenários avançados para obter orientações sobre como configurar parâmetros para casos de uso avançados, como:
  • Lidar com erros usando failOnError
  • Saídas estruturadas no Databricks : como especificar a saída estruturada para as respostas de suas consultas.

SQL

SQL

SELECT text, ai_query(
    "databricks-gpt-oss-120b",
    "Summarize the given text comprehensively, covering key points and main ideas concisely while retaining relevant details and examples. Ensure clarity and accuracy without unnecessary repetition or omissions: " || text
) AS summary
FROM uc_catalog.schema.table;

Python

Python

df_out = df.selectExpr(
  "ai_query('databricks-gpt-oss-120b', CONCAT('Please provide a summary of the following text: ', text), modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)) as summary"
)
df_out.write.mode("overwrite").saveAsTable('output_table')

Exemplo de Notebook: inferência de lotes e extração de dados estruturados

O seguinte exemplo de Notebook demonstra como realizar extração básica de dados estruturados usando ai_query para transformar dados brutos e não estruturados em informações organizadas e utilizáveis por meio de técnicas de extração automatizadas. Este Notebook também mostra como aproveitar a Avaliação de Agentes para avaliar a precisão usando dados de referência.

Notebook para inferência de lotes e extração de dados estruturados

Abrir notebook em uma nova aba

Use ai_query com modelos ML tradicionais

ai_query Suporta modelos ML tradicionais, incluindo modelos totalmente personalizados. Esses modelos devem ser implantados no endpoint do modelo de instalação. Para detalhes de sintaxe e parâmetros, veja a funçãoai_query.

SQL

SELECT text, ai_query(
  endpoint => "spam-classification",
  request => named_struct(
    "timestamp", timestamp,
    "sender", from_number,
    "text", text),
  returnType => "BOOLEAN") AS is_spam
FROM catalog.schema.inbox_messages
LIMIT 10

Notebook de exemplo: inferência de lotes usando BERT para reconhecimento de entidades nomeadas

O seguinte Notebook mostra um exemplo de inferência de lotes de um modelo ML tradicional usando BERT.

Inferência de lotes usando BERT para reconhecimento de entidades nomeadas (Notebook)

Abrir notebook em uma nova aba