Compartir vía

ai_queryFunción

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

Important

Esta funcionalidad está en versión preliminar pública y compatible con HIPAA.

Durante la versión preliminar:

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

ai_query es una función de IA de uso general que permite consultar los puntos de conexión existentes para cargas de trabajo de inferencia en tiempo real o de inferencia por lotes.

Requisitos

  • Esta función no está disponible en Azure Databricks SQL Classic.

  • Debe habilitar Azure Private Link para usar esta característica en almacenes de SQL pro.

  • Se recomienda Databricks Runtime 15.4 LTS o superior. El uso de Databricks Runtime 15.3 o inferior puede dar lugar a velocidades de rendimiento más lentas.

  • El área de trabajo debe estar en una región de servicio de modelos compatible.

  • Un punto de conexión de servicio de modelo existente con el modelo cargado. Si usa un modelo de base hospedado de Databricks, se crea un punto de conexión automáticamente. De lo contrario, consulte Creación de puntos de conexión de servicio de modelos personalizados o Creación de puntos de conexión de servicio de modelos de base.

  • La consulta a las API del modelo base está habilitada de manera predeterminada. Para consultar puntos de conexión que atienden modelos personalizados o modelos externos:

  • El canal actual de almacén de canalizaciones declarativas de Lakeflow Spark no utiliza la versión más reciente de Databricks Runtime que admite . Configure las propiedades de la tabla en pipelines.channel 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 un punto de conexión que sirve un modelo base:

ai_query(endpoint, request)

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

ai_query(endpoint, request)

Para consultar un modelo personalizado que atiende el punto de conexión sin un esquema de modelo:

ai_query(endpoint, request, returnType, failOnError)

Argumentos y devoluciones

Argument Description Returns
endpoint El nombre de un punto de conexión de servicio de Databricks Foundation Model, un punto de conexión de servicio de modelo externo o un punto de conexión de modelo personalizado en la misma área de trabajo para las invocaciones como STRING literal. El definidor debe tener permiso para CAN QUERY en el punto de conexión.
request La solicitud utilizada para invocar al punto de conexión como expresión.
  • Si el punto de conexión es un punto de conexión de servicio de modelo externo o un punto de conexión de API de modelo de Databricks Foundation, la solicitud debe ser un archivo STRING.
  • Si el punto de conexión es un punto de conexión de un modelo de servicio personalizado, la solicitud puede ser una sola columna o una expresión de tipo STRUCT. Los nombres de campo STRUCT deben coincidir con los nombres de características de entrada esperados por el punto de conexión.
returnType (Opcional para Databricks Runtime 15.2 y versiones posteriores) Que se espera returnType del punto de conexión como una expresión. Esto es similar al parámetro de esquema de la from_json función , que acepta una STRING expresión o invocación de schema_of_json función.
  • Para Databricks Runtime 15.2 y versiones posteriores, esta expresión es opcional. Si no se proporciona, ai_query() deduce automáticamente el tipo de valor devuelto del esquema de modelo del punto de conexión de servicio del modelo personalizado.
  • Para Databricks Runtime 15.1 y versiones posteriores, esta expresión es necesaria para consultar un punto de conexión de servicio de modelo personalizado.

Use el responseFormat parámetro para especificar formatos de respuesta para los modelos de base de chat.
failOnError (Opcional) Literal booleano que tiene como valor predeterminado true. Requiere Databricks Runtime 15.3 o superior. Esta marca indica si se debe incluir el estado de error en la ai_query respuesta.
Consulte Control de errores mediante failOnError para obtener un ejemplo.		 A continuación se describe el comportamiento de retorno según el escenario failOnError.
  • Si failOnError => true, la función devuelve el mismo resultado que el comportamiento actual, que es la respuesta analizada del extremo. El tipo de datos de la respuesta analizada se deduce del tipo de modelo, el endpoint del esquema del modelo, o el parámetro returnType en la función ai_query.
  • Si failOnError => falsees , la función devuelve un STRUCT objeto que contiene la respuesta analizada y la cadena de estado de error.
    • Si la inferencia de la fila se realiza correctamente, el errorStatus campo es null.
    • Si la inferencia de la fila falla debido a errores en el punto de conexión del modelo, el campo response es null.
    • Si se produce un error en la inferencia de la fila debido a otros errores, se produce un error en toda la consulta.
modelParameters (Opcional) 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.
  • Requiere Databricks Runtime 15.3 o superior.
  • Cuando no se especifican estos parámetros del modelo o se establecen en null, se utiliza el valor predeterminado. Con la excepción de temperature que tiene un valor predeterminado de 0.0, los valores predeterminados para estos parámetros de modelo son los mismos que los enumerados en la referencia de la API rest del modelo de Foundation.

Consulte Configuración de un modelo pasando parámetros de modelo para obtener un ejemplo.
responseFormat (Opcional) Especifique el formato de respuesta que desea que siga el modelo de base de chat.
  • Requiere Databricks Runtime 15.4 LTS o superior. Solo está disponible para consultar modelos base de chat.
  • Se admiten dos estilos de formato de respuesta.
    • Cadena JSON de estilo DDL
    • Cadena JSON. Se admiten tres tipos de cadena JSON de formato de respuesta:text , json_object, json_schema

Consulte Aplicación de esquemas de salida con salida estructurada para obtener ejemplos.		 A continuación se describe lo que sucede cuando failOnError también se establece cuando responseFormat se especifica:
  • Si failOnError => false y ha especificado responseFormat, la función devuelve la respuesta analizada y la cadena de estado de error como un STRUCT objeto .
  • Según el tipo de cadena JSON especificado en responseFormat, se devuelve la siguiente respuesta:
    • Para responseFormat => '{"type": "text"}', la respuesta es una cadena como , “Here is the response”.
    • Para responseFormat => '{"type": "json_object"}', la respuesta es una cadena JSON de par clave-valor, como {“key”: “value”}.
    • Para responseFormat => '{"type": "json_schema", "json_schema"...}', la respuesta es una cadena JSON.
files (Opcional) Especifique los archivos y el contenido que se van a usar en las solicitudes de entrada multimodales mediante files=>content. files es el nombre de parámetro esperado por el modelo para la entrada multimodal y content hace referencia a la columna del DataFrame que contiene el contenido binario de los archivos de imagen que desea usar en la consulta.
  • Se requiere para las solicitudes multimodales.
  • Solo se admiten entradas de imagen: JPEG o PNG . Para obtener un ejemplo, consulte entradas multimodales. Como se muestra en este ejemplo, puede especificar la content columna de la salida del read_files al parámetro files.

Ejemplo: Consulta de un modelo de base

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-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, 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-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 multimodales

ai_query admite de forma nativa entradas de imagen multimodales. Consulte Tipos de modelo de Foundation para ver los modelos de visión hospedados en Databricks admitidos.

A continuación se muestran los tipos de entrada admitidos:

  • JPEG
  • PNG

En el ejemplo siguiente se muestra cómo realizar una consulta en un modelo fundamental compatible con las API de modelos fundamentales de Databricks para la entrada multimodal. En este ejemplo, el files => content parámetro se usa para pasar los datos del archivo de imagen a ai_query

  • files: el nombre del parámetro esperado por el modelo para la entrada multimodal.
  • content: la columna del dataframe devuelto por READ_FILES, que contiene el contenido binario del archivo de imagen.

> 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 un modelo de base compatible con las API del modelo de Databricks Foundation para la entrada multimodal y especificar la salida estructurada:

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

Ejemplo: Consulta de un modelo de ML tradicional

Para consultar un modelo personalizado o un modelo de ML tradicional que atiende el punto de conexión:


> 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

Ejemplos de escenarios avanzados

En las secciones siguientes se proporcionan ejemplos de casos de uso avanzados, como el control de errores o cómo incorporar ai_query en una función definida por el usuario.

Pasar una matriz de mensajes

En el ejemplo siguiente se muestra cómo pasar una matriz de mensajes a la aplicación de modelo o agente mediante 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 las columnas de solicitud e inferencia

Hay varias maneras de concatenar la solicitud y la columna de inferencia, como usar ||, CONCAT()o 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};

O bien mediante format_string():

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Configuración de un modelo pasando parámetros de modelo

Personalice el comportamiento del modelo pasando parámetros específicos, como los tokens máximos y la temperatura. Por ejemplo:

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;

Control de errores mediante failOnError

Use el failOnError argumento para ai_query para controlar los errores. En el ejemplo siguiente se muestra cómo asegurarse de que si una fila tiene un error, no impedirá que se ejecute toda la consulta. Consulte Arguments and returns para conocer los comportamientos esperados según cómo se configure este argumento.


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;

Aplicar esquema de salida con salida estructurada

Asegúrese de que la salida se ajusta a un esquema específico para facilitar el procesamiento posterior mediante responseFormat. Consulte Resultados estructurados en Azure Databricks.

En el ejemplo siguiente se aplica un esquema de cadena 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, mediante un formato de respuesta 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;

Una salida esperada podría ser similar a la siguiente:

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

Uso ai_query en funciones definidas por el usuario

Puede encapsular una llamada a ai_query en una UDF, lo que facilita el uso de funciones en distintos flujos de trabajo y compartirlas.

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;
  • Last updated on