ai_queryFunción

Se aplica a: Databricks SQL Databricks Runtime

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.

• Consulte Función de uso general: ai_query para ver los modelos admitidos y las configuraciones de punto de conexión necesarias.
• También puede usar ai_query para consultar un agente de IA implementado en el punto de conexión de servicio del modelo de ML. Consulte Consulta de un agente de IA de Mosaico implementado.
• Para usar ai_query en flujos de trabajo de producción, ver Despliegue de canalizaciones de inferencia en lote.

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:

  • Habilite AI_Query para modelos personalizados y modelos externos en la interfaz de usuario de Databricks Previews.

• 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

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;