Função ai_query

Aplica-se a: Databricks SQL Databricks Runtime

Invoca um endpoint existente do Azure Databricks Model Serving e analisa e retorna a sua resposta.

ai_query é uma função de IA de uso geral que permite consultar pontos de extremidade existentes para inferência em tempo real ou cargas de trabalho de inferência em lote.

• Consulte Função de uso geral: ai_query para modelos suportados e configurações de endpoint necessárias.
• Você também pode usar ai_query para consultar um agente de IA implantado no endpoint de serviço de modelo de Machine Learning, consulte Consultar um agente de IA Mosaic implantado
• Para usar ai_query em fluxos de trabalho de produção, consulte Implementar pipelines de inferência em lote.

Requisitos

• Esta função não está disponível no Azure Databricks SQL Classic.

• Você deve habilitar o Azure Private Link para usar esse recurso em armazéns SQL profissionais.

• Databricks Runtime 15.4 LTS ou superior é recomendado. O uso do Databricks Runtime 15.3 ou inferior pode resultar em velocidades de desempenho mais lentas.

• Seu espaço de trabalho deve estar em uma região de Serviço de Modelo suportada.

• Um endpoint de serviço existente com o seu modelo carregado. Se estiveres a usar um modelo de base hospedado pelo Databricks, um endpoint será criado para ti. Caso contrário, consulte Criar modelo personalizado servindo pontos de extremidade ou Criar modelo de base servindo pontos de extremidade.

• O Querying Foundation Model APIs está habilitado por padrão. Para consultar endpoints que servem modelos personalizados ou modelos externos:

  • Habilite AI_Query para modelos personalizados e modelos externos na interface de pré-visualizações do Databricks.

• O atual canal de armazém do Lakeflow Spark Declarative Pipelines não usa a versão mais recente do Databricks Runtime que suporta ai_query(). Defina o pipelines.channel nas propriedades da tabela como 'preview' para usar ai_query().

  > create or replace materialized view
      ai_query_mv
      TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
    SELECT
      ai_query("databricks-meta-llama-3-3-70b-instruct", text) as response
    FROM
      messages
    LIMIT 10;
  

Syntax

Para consultar um ponto de extremidade que serve um modelo de base:

ai_query(endpoint, request)

Para consultar um ponto de extremidade de serviço de um modelo personalizado com um esquema de modelo :

ai_query(endpoint, request)

Para consultar um ponto de extremidade de serviço de um modelo personalizado sem uma estrutura de modelo:

ai_query(endpoint, request, returnType, failOnError)

Argumentos e devoluções

Exemplo: Consultar um modelo de base

Para consultar o ponto de serviço de um modelo externo:

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

Para consultar um modelo de base suportado pelas APIs do Databricks Foundation Model:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

Opcionalmente, pode também encapsular uma chamada em UDF para a chamada de função ai_query() da seguinte maneira:

 CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Entradas multimodais

ai_query Suporta nativamente entradas de imagem multimodais. Consulte Tipos de modelos fundamentais para os modelos de visão suportados hospedados no Databricks.

Os seguintes tipos de entrada são suportados:

• JPEG
• PNG

O exemplo a seguir mostra como consultar um modelo de base suportado por APIs de modelo de base Databricks para entrada multimodal. Neste exemplo, o files => content parâmetro é usado para passar os dados do arquivo de imagem para ai_query

• files: O nome do parâmetro esperado pelo modelo para entrada multimodal
• content: A coluna no DataFrame retornada por READ_FILES, que contém o conteúdo binário do arquivo de imagem.

> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

Para consultar um modelo de base suportado pelas APIs do Databricks Foundation Model para entrada multimodal e especificar saída estruturada:

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

Exemplo: Consultar um modelo de ML tradicional

Para consultar um modelo personalizado ou um modelo de ML tradicional num ponto de extremidade de serviço:

> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages
  LIMIT 10

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

Exemplos de cenários avançados

As seções a seguir fornecem exemplos de casos de uso avançados, como tratamento de erros ou como incorporar ai_query em uma função definida pelo usuário.

Passar uma matriz de mensagens

O exemplo a seguir mostra como passar um array de mensagens para o seu modelo ou aplicação de agente usando ai_query.

> SELECT ai_query(
    'custom-llama-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

Concatenar as colunas de prompt e de inferência

Há várias maneiras de concatenar o prompt e a coluna de inferência, como usar ||, CONCAT()ou format_string():

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternatively:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Ou usando format_string():

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Configurar um modelo passando parâmetros de modelo

Personalize o comportamento do modelo passando parâmetros específicos, como tokens máximos e temperatura. Por exemplo:

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Please summarize the following article: " || text,
    modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)
) AS summary
FROM uc_catalog.schema.table;

Tratar erros usando failOnError

Use o argumento failOnError para ai_query para manipular erros. O exemplo a seguir mostra como garantir que, se uma linha tiver um erro, ela não interromperá a execução de toda a consulta. Consulte Argumentos e retornos para comportamentos esperados com base em como este argumento é definido.

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "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,
failOnError => false
) AS summary
FROM uc_catalog.schema.table;

Aplicar o esquema de saída utilizando saídas estruturadas

Certifique-se de que a saída esteja em conformidade com um esquema específico para facilitar o processamento posterior usando responseFormat. Consulte Saídas estruturadas no Azure Databricks.

O exemplo a seguir impõe um esquema de cadeia de caracteres JSON estilo DDL:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => 'STRUCT<research_paper_extraction:STRUCT<title:STRING, authors:ARRAY<STRING>, abstract:STRING, keywords:ARRAY<STRING>>>'
)
FROM research_papers;

Como alternativa, usando um formato de resposta de esquema JSON:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => '{
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "authors": {"type": "array", "items": {"type": "string"}},
            "abstract": {"type": "string"},
            "keywords": {"type": "array", "items": {"type": "string"}}
          }
      },
      "strict": true
    }
  }'
)
FROM research_papers;

Uma saída esperada pode assemelhar-se a:

{ "title": "Understanding AI Functions in Databricks", "authors": ["Alice Smith", "Bob Jones"], "abstract": "This paper explains how AI functions can be integrated into data workflows.", "keywords": ["Databricks", "AI", "LLM"] }

Usar ai_query em funções definidas pelo usuário

Você pode encapsular uma chamada para ai_query em um UDF, facilitando o uso de funções em diferentes fluxos de trabalho e compartilhá-las.

CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));

GRANT EXECUTE ON correct_grammar TO ds;

SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;