ai_query Função

Aplica-se a: Databricks SQL Databricks Runtime

Invoca um ponto de extremidade do Serviço de Modelo existente do Azure Databricks e analisa e retorna sua resposta.

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

• Consulte a função de finalidade geral: ai_query para modelos com suporte e configurações de ponto de extremidade necessárias.
• Você também pode usar ai_query para consultar um agente de IA implantado no endpoint de serviço do modelo de ML. Consulte Consultar um agente de IA Mosaic implantado
• Para usar ai_query em fluxos de trabalho de produção, consulte Implantar pipelines de inferência em lote.

Requisitos

• Essa função não está disponível no SQL Clássico do Azure Databricks.

• Você deve habilitar o Link Privado do Azure para usar esse recurso em warehouses SQL profissionais.

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

• O seu workspace deve estar em uma região do Serviço de Modelo com suporte.

• Um ponto de extremidade do serviço existente com seu modelo carregado. Se você estiver usando um modelo de base hospedado pelo Databricks, um endpoint será criado para você. Caso contrário, consulte Criar pontos de extremidade para modelo personalizado ou Criar pontos de extremidade para modelo básico.

• A consulta às APIs do Foundation Model está habilitada por padrão. Para consultar pontos de extremidade que atendem modelos personalizados ou modelos externos:

  • Habilite AI_Query para modelos personalizados e modelos externos na Interface do usuário do Databricks Previews.

• O canal atual do canal de armazenamento do Lakeflow Spark Declarative Pipelines não usa a versão mais recente do Databricks Runtime compatívelai_query(). Defina 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 a um modelo de base:

ai_query(endpoint, request)

Para consultar um modelo personalizado que serve o ponto de extremidade com um esquema de modelo:

ai_query(endpoint, request)

Para consultar um ponto de extremidade do Serviço de Modelo personalizado sem um esquema de modelo:

ai_query(endpoint, request, returnType, failOnError)

Argumentos e retornos

Exemplo: consultar um modelo de base

Para consultar um ponto de extremidade do serviço de 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 fundação compatível com as APIs de Modelo do Databricks Foundation:

> 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, você também pode encapsular uma chamada a ai_query() em um UDF para chamada de função 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 dá suporte nativo a entradas de imagem multimodal. Consulte os tipos de modelo de Foundation para os modelos de visão com suporte do Databricks.

Veja a seguir os tipos de entrada com suporte:

• JPEG
• PNG

O exemplo a seguir mostra como consultar um modelo de fundação com suporte das APIs de Modelo do Databricks Foundation 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 fundamental com suporte pelas APIs do Databricks para Modelos Fundamentais, para entrada multimodal, e especificar a 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 ponto de extremidade do Serviço de Modelo de ML tradicional:

> 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 para 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 uma matriz de mensagens para seu modelo ou aplicativo 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 a coluna de solicitação e 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;

Manipular erros usando failOnError

Use o failOnError argumento para ai_query a fim de lidar com erros. O exemplo a seguir mostra como garantir que, se uma linha tiver um erro, ela não impedirá a execução de toda a consulta. Consulte Argumentos e retornos para comportamentos esperados com base em como esse 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;

Impor o esquema de saída com saída estruturada

Verifique se a saída está em conformidade com um esquema específico para facilitar o processamento downstream usando responseFormat. Consulte Saídas estruturadas no Azure Databricks.

O exemplo a seguir impõe um esquema de cadeia de caracteres JSON de 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 ser semelhante 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 a ai_query em uma UDF, o que facilita o uso e o compartilhamento de funções em diferentes fluxos de trabalho.

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;