Função `ai_query`

Artigo
01/02/2025

Aplica-se a: Marque Sim Databricks SQL Databricks Runtime

Importante

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

Invoca um ponto de extremidade existente do Azure Databricks Model Serving e analisa e retorna sua resposta.

Consulte os seguintes guias para saber como usar ai_query para diferentes casos de uso:

Requerimentos

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.3 ou superior é recomendado. O uso do Databricks Runtime 15.2 ou inferior pode resultar em velocidades de desempenho mais lentas.
O canal de depósito DLT atualnão usa a versão mais recente do Databricks Runtime que suporta ai_query()o . Set o pipelines.channel nas propriedades table como 'preview' usar ai_query(). Consulte Exemplos para uma consulta de exemplo.
Um modelo existente servindo ponto de extremidade com seu modelo carregado. Consulte Criar pontos de extremidade de serviço de modelo personalizado.
Seu espaço de trabalho deve estar em uma região de Serviço de Modelo suportada.
O Querying Foundation Model APIs está habilitado por padrão. Para consultar pontos de extremidade que servem modelos personalizados ou modelos externos:
- Habilite AI_Query para modelos personalizados e modelos externos na interface do usuário de visualizações do Databricks.
- Consulte Consultar um modelo externo com ai_query.
- Consulte Executar inferência LLM em lote usando ai_query

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 inferior, esta função não é suportada em blocos de notas Databricks.

Sintaxe

Para consultar um ponto de extremidade que serve um modelo externo ou um modelo básico:

ai_query(endpoint, request)

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

ai_query(endpoint, request)

Para consultar um endpoint de disponibilização de modelo personalizado sem um modelo schema:

ai_query(endpoint, request, returnType, failOnError)

Argumentos

endpoint: Um literal STRING, o nome de um endpoint de serviço de modelo da Databricks Foundation, um endpoint de serviço de modelo externo ou um endpoint de serviço 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 usada para invocar o ponto de extremidade.
- 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 servindo o ponto de extremidade, a solicitação poderá ser um único column ou uma expressão struct. 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 em from_json função, que aceita uma expressão STRING ou invocação de schema_of_json função.
- No Databricks Runtime 14.2 e versões posteriores, se esta expressão não for disponibilizada, ai_query() infere automaticamente o tipo de retorno a partir do modelo schema do ponto de extremidade de serviço de modelo personalizado.
- No Databricks Runtime 14.1 e inferior, essa expressão é necessária para consultar um modelo personalizado que serve o ponto de extremidade.
failOnError: (opcional) Um padrão literal booleano para true. Esse sinalizador indica se o status de erro deve ser incluído na ai_query resposta.
modelParameters (opcional): um campo de estrutura que contém chat, completação e incorporação de modelos parameters para servir modelos base ou modelos externos. Estes modelos parameters devem ser constantes parameters e não dependentes de dados. Quando estes modelos parameters não são especificados ou quando set até null são usados, o valor padrão é aplicado. Com exceção do que tem um valor padrão de , os padrão para esses de modelo são os mesmos listados node referência da API REST do modelo Foundation.
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

Devoluções

A resposta analisada do ponto de extremidade.

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 modelo schema ou do parâmetro returnType na função ai_query.
Se failOnError => false, a função retorna a resposta analisada e a cadeia de status de erro como um objeto STRUCT.
- Se a inferência da linha foi bem-sucedida, o campo errorStatus é null.
- Se a inferência da linha falhou devido a erros de ponto de extremidade do modelo, o campo response será null.
- Se a inferência da linha falhou devido a outros erros, toda a consulta falhará.
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”...}', a resposta é uma cadeia de caracteres JSON. Veja os Exemplos.
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.

Exemplos

O exemplo a seguir especifica um formato de resposta json_schema:


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

A seguir está um exemplo de saída para o formato de resposta json_schema especificado:

{"title": "<the title of the paper>"}

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 o seu modelo e o column 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}
)

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-1-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 em um UDF para chamada de ai_query() função da seguinte maneira:

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-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;

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


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

Exemplo de consulta para definir o canal DLT para visualização:

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

Partilhar via

Função `ai_query`

Requerimentos

Sintaxe

Argumentos

Devoluções

Exemplos

Comentários

Recursos adicionais

Partilhar via

Função ai_query

Requerimentos

Sintaxe

Argumentos

Devoluções

Exemplos

Comentários

Recursos adicionais

Função `ai_query`