Partilhar via

Função ai_query

  • Artigo

Aplica-se a:Marque Sim Databricks SQL Marque Sim 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 . Defina as pipelines.channel propriedades da tabela 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:

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 esquema de modelo:

ai_query(endpoint, request)

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

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 que serve o ponto de extremidade, a solicitação pode ser uma única coluna 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 a invocação de schema_of_json função.
    • No Databricks Runtime 14.2 e superior, se essa expressão não for fornecida, ai_query() infere automaticamente o tipo de retorno do esquema de modelo do ponto de extremidade de serviço do 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. O formato de resposta é diferente quando está definido como false.
  • modelParameters (opcional): um campo struct que contém parâmetros de modelo de chat, conclusão e incorporação para servir modelos de fundação 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.

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 esquema do modelo ou do returnTypeai_query parâmetro na função.
  • 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á.

Exemplos

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

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;