Compartir vía

ai_queryFunción

  • Artículo

Se aplica a: casilla marcada como Sí Databricks SQL casilla marcada como Sí Databricks Runtime

Importante

Esta característica está en versión preliminar pública.

Invoca un punto de conexión existente del servicio de modelo de Azure Databricks y analiza y devuelve su respuesta.

Consulte las siguientes guías para ver cómo usar ai_query para diferentes casos de uso:

Requisitos

Nota:

  • En Databricks Runtime 14.2 y versiones posteriores, esta función se admite en cuadernos de Databricks, incluidos los cuadernos que se ejecutan como una tarea en un flujo de trabajo de Databricks.
  • En Databricks Runtime 14.1 y versiones posteriores, esta función no se admite en cuadernos de Databricks.

Sintaxis

Para consultar un punto de conexión que sirve un modelo externo o un modelo de base de:

ai_query(endpointName, request)

Para consultar un punto de conexión de servicio de modelo personalizado con un esquema de modelo:

ai_query(endpointName, request)

Para consultar un punto de conexión de servicio de modelo personalizado sin un esquema de modelo:

ai_query(endpointName, request, returnType, failOnError)

Argumentos

  • endpointName: un literal STRING, el nombre de un punto de conexión de servicio de modelo de Databricks Foundation, un modelo externo que sirve un punto de conexión o un punto de conexión de modelo personalizado en la misma área de trabajo para las invocaciones. El definidor debe tener el permiso CAN QUERY en el punto de conexión.
  • request: una expresión, la solicitud utilizada para invocar el punto de conexión.
    • Si el punto de conexión es un modelo externo que atiende el punto de conexión o Databricks Foundation Model API, la solicitud debe ser una cadena.
    • Si el punto de conexión es un punto de conexión de servicio de modelo personalizado, la solicitud puede ser una sola columna o una expresión de estructura. Los nombres de campo de estructura deben coincidir con los nombres de características de entrada esperados por el punto de conexión.
  • returnType: una expresión, el valor returnType esperado del punto de conexión. Esto es similar al parámetro de esquema en from_json función, que acepta una expresión STRING o invocación de schema_of_json función.
    • En Databricks Runtime 14.2 y versiones posteriores, si no se proporciona esta expresión, ai_query() deduce automáticamente el tipo de valor devuelto del esquema de modelo del punto de conexión de servicio del modelo personalizado.
    • En Databricks Runtime 14.1 y versiones posteriores, esta expresión es necesaria para consultar un punto de conexión de servicio de modelo personalizado.
  • failOnError: (opcional) Literal booleano predeterminado en true. Esta marca indica si se debe incluir el estado de error en la ai_query respuesta. El formato de respuesta es diferente cuando se establece en false.
  • modelParameters (opcional): un campo de estructura que contiene parámetros de modelo de chat, finalización e inserción para servir modelos básicos o modelos externos. Estos parámetros del modelo deben ser parámetros constantes y no dependientes de los datos. Cuando no se especifican estos parámetros de modelo o se establecen en null el valor predeterminado. Con la excepción de temperature que tiene un valor predeterminado de 0,0, los valores predeterminados para estos parámetros del modelo son los mismos que los enumerados en la referencia de la API REST del modelo de Foundation.

Devoluciones

Respuesta analizada del punto de conexión.

  • Si failOnError => truees , la función devuelve el mismo resultado que el comportamiento existente, que es la respuesta analizada del punto de conexión. El tipo de datos de la respuesta analizada se deduce del tipo de modelo, el punto de conexión del esquema del modelo o el returnType parámetro de la ai_query función .
  • Si failOnError => falsees , la función devuelve la respuesta analizada y la cadena de estado de error como un objeto STRUCT.
    • Si la inferencia de la fila se realizó correctamente, el errorStatus campo es NULL.
    • Si se produjo un error en la inferencia de la fila debido a errores de punto de conexión del modelo, el response campo es NULL.
    • Si se produjo un error en la inferencia de la fila debido a otros errores, se produce un error en toda la consulta.

Ejemplos

A continuación se muestra un ejemplo de inferencia por lotes mediante failOnError y modelParameters con max_tokens y temperature. En este ejemplo también se muestra cómo concatenar la solicitud del modelo y la columna de inferencia mediante concat(). Hay varias maneras de realizar la concatenación, como usar ||, concat()o 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 un punto final de servicio 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 un modelo de base compatible con las API de modelo de Databricks Foundation:

> 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, también puede encapsular una llamada a ai_query() en una UDF para realizar llamadas de función como se indica a continuación:

> 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 un punto de conexión de servicio 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

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

Consulta de ejemplo para establecer el canal DLT en versión preliminar:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages