Função `ai_query`

Artigo
03/11/2025

Aplica-se a: Sim, selecionado Databricks SQL Databricks Runtime

Importante

Esta funcionalidade está em Pré-visualização Pública.

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

Para usar ai_query em fluxos de trabalho de produção, consulte Executar inferência LLM em lote usando funções de IA.

Requerimentos

Nota

No Databricks Runtime 14.2 e superior, essa função é suportada em blocos de anotações Databricks, incluindo blocos de anotações que são executados como uma tarefa em um fluxo de trabalho Databricks.
No Databricks Runtime 14.1 e versões anteriores, esta função não é suportada em notebooks do Databricks.

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.
O Databricks Runtime 15.3 ou superior é recomendado. O uso do Databricks Runtime 15.2 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 modelo existente servindo ponto de extremidade com 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 atualcanal de depósito DLT 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-dbrx-instruct", text) as response
  FROM
    messages
  LIMIT 10;

Sintaxe

Para consultar um ponto de extremidade que serve um modelo base, incluindo modelos externos ou um modelo base personalizado:

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

Argumento	Descrição	Devoluções
`endpoint`	Um `STRING` literal, o nome de um ponto de extremidade do Databricks Foundation Model, um ponto de extremidade para o serviço de modelo externo ou um ponto de extremidade de modelo personalizado no mesmo espaço de trabalho para invocações. O definidor deve ter permissão `CAN QUERY` no ponto de extremidade.
`request`	Uma expressão, a solicitação que se usa para invocar o endpoint. Se o ponto de extremidade for um ponto de extremidade de serviço de modelo externo ou um ponto de extremidade das APIs do Databricks Foundation Model, a solicitação deverá ser um `STRING`. Se o ponto de extremidade for um modelo personalizado que serve de ponto de extremidade, a solicitação pode ser uma única coluna ou uma estrutura de expressão. Os nomes de campo struct devem corresponder aos nomes de recursos de entrada esperados pelo ponto de extremidade.
`returnType`	Uma expressão, a `returnType` esperada a partir do ponto final. Isso é semelhante ao parâmetro schema na `from_json` função, que aceita tanto uma expressão `STRING` como uma invocação de `schema_of_json` função. No Databricks Runtime 14.2 e superior, se esta expressão não for fornecida, `ai_query()` infere automaticamente o tipo de retorno a partir do esquema de modelo do ponto de serviço do modelo personalizado. No Databricks Runtime 14.1 e em versões anteriores, essa expressão é necessária para consultar um terminal de serviço de modelo personalizado.
`failOnError`	(Opcional) Um literal booleano que, por padrão, assume o valor true. Esse sinalizador indica se o status de erro deve ser incluído na `ai_query` resposta.	Se `failOnError => true`, a função retorna o mesmo resultado que o comportamento existente, que é a resposta analisada do ponto de extremidade. O tipo de dados da resposta analisada é inferido a partir do tipo de modelo, do ponto de extremidade do esquema do modelo ou do parâmetro `returnType` na função `ai_query`. Se `failOnError => false`, a função retorna um objeto `STRUCT` que contém a resposta analisada e a cadeia de status de erro. Se a inferência da linha for bem-sucedida, o campo `errorStatus` será `null`. Se a inferência da linha falhar devido a erros de ponto de extremidade do modelo, o campo `response` será `null`. Se a inferência da linha falhar devido a outros erros, toda a consulta falhará. Consulte Manipular erros usando `failOnError` para obter um exemplo.
`modelParameters`	(Opcional) Um campo de estrutura que contém parâmetros de modelo de chat, conclusão e modelo de incorporação para servir modelos base ou modelos externos. Esses parâmetros do modelo devem ser parâmetros constantes e não dependentes de dados. Quando esses parâmetros de modelo não são especificados ou definidos como `null` o valor padrão é usado. Com exceção do que tem um valor padrão de , os valores padrão para esses parâmetros de modelo são os mesmos listados node referência da API REST do modelo Foundation. Consulte Configurar um modelo passando parâmetros de modelo para obter um exemplo.
`responseFormat`	(Opcional) Um campo de cadeia de caracteres JSON que especifica o formato de resposta que você deseja que o modelo siga. Há suporte para três tipos de cadeia de caracteres de formato de resposta: `text` `json_object` `json_schema`	Se `failOnError => false` e você tiver especificado `responseFormat`, a função retornará a resposta analisada e a cadeia de status de erro como um objeto `STRUCT`. Dependendo do tipo de cadeia de caracteres JSON especificado no `responseFormat`, a seguinte resposta é retornada: Para `responseFormat => '{"type": "text"}'`, a resposta é uma cadeia de caracteres como, `“Here is the response”`. Para `responseFormat => '{"type": "json_object"}'`, a resposta é uma cadeia de caracteres JSON do par chave-valor, como `{“key”: “value”}`. Para `responseFormat => '{"type": "json_schema", "json_schema"...}'`, a resposta é uma cadeia de caracteres JSON. Consulte Aplicar esquema de saída com saída estruturada para obter um exemplo.

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};

Como alternativa:

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;

Impor esquema de saída com saída estruturada

Certifique-se de que a saída esteja em conformidade com um esquema específico para facilitar o processamento a jusante. Por exemplo, você pode impor um formato de resposta de esquema JSON:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "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 esquema JSON estilo DDL:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "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;

Exemplo: Consultar um modelo de base

Para consultar um modelo externo que serve o ponto de extremidade:

> 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;

Exemplo: caso de uso de inferência em lote

A seguir está um exemplo de inferência em lote usando o failOnError e modelParameters com max_tokens e temperature. Este exemplo também mostra como concatenar o prompt para seu modelo e a coluna de inferência usando CONCAT().

Há várias maneiras de realizar concatenações, como usar ||, concat()ou format_string().


CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

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

> 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."]}

Partilhar via

Função `ai_query`

Requerimentos

Sintaxe

Argumentos e devoluções

Concatenar as colunas de prompt e de inferência

Configurar um modelo passando parâmetros de modelo

Tratar erros usando `failOnError`

Impor esquema de saída com saída estruturada

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

Exemplo: Consultar um modelo de base

Exemplo: caso de uso de inferência em lote

Exemplo: Consultar um modelo de ML tradicional

Comentários

Recursos adicionais

Partilhar via

Função ai_query

Requerimentos

Sintaxe

Argumentos e devoluções

Concatenar as colunas de prompt e de inferência

Configurar um modelo passando parâmetros de modelo

Tratar erros usando failOnError

Impor esquema de saída com saída estruturada

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

Exemplo: Consultar um modelo de base

Exemplo: caso de uso de inferência em lote

Exemplo: Consultar um modelo de ML tradicional

Comentários

Recursos adicionais

Função `ai_query`

Tratar erros usando `failOnError`

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