Condividi tramite

Funzione ai_query

Si applica a:segno di spunta sì Databricks SQL segno di spunta sì Databricks Runtime

Important

Questa funzionalità è disponibile in anteprima pubblica e conforme a HIPAA.

Durante l'anteprima:

Richiama un endpoint di gestione del modello di Azure Databricks esistente e ne analizza e restituisce la risposta.

ai_query è una funzione di intelligenza artificiale per utilizzo generico che consente di eseguire query sugli endpoint esistenti per carichi di lavoro di inferenza in tempo reale o inferenza batch.

Requisiti

  • Questa funzione non è disponibile in Azure Databricks SQL classico.

  • È necessario abilitare collegamento privato di Azure per usare questa funzionalità nei data warehouse pro SQL.

  • È consigliabile usare Databricks Runtime 15.4 LTS o versione successiva. L'uso di Databricks Runtime 15.3 o versioni precedenti potrebbe comportare una minore velocità delle prestazioni.

  • L'area di lavoro deve trovarsi in un'area di gestione dei modelli supportata.

  • Un endpoint di servizio esistente con il tuo modello caricato. Se si usa un modello di base ospitato in Databricks, viene creato automaticamente un endpoint. In caso contrario, vedere Creare endpoint di servizio per modelli personalizzati o Creare endpoint di servizio per modelli di base.

  • L'esecuzione di query sulle API del modello di base è abilitata per impostazione predefinita. Per eseguire query sugli endpoint che servono modelli personalizzati o modelli esterni :

    • Abilitare AI_Query per modelli personalizzati e modelli esterni nell'interfaccia utente delle anteprime di Databricks.

  • Ilcanale di data warehouse dichiarativo di Lakeflow Spark corrente non usa la versione più recente di Databricks Runtime che supporta ai_query(). Impostare il pipelines.channel nelle proprietà della tabella come 'preview' per usare 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

Per eseguire query su un endpoint che gestisce un modello di base:

ai_query(endpoint, request)

Per eseguire query su un endpoint personalizzato che gestisce un modello con uno schema del modello :

ai_query(endpoint, request)

Per eseguire query su un endpoint personalizzato che gestisce un modello senza uno schema del modello:

ai_query(endpoint, request, returnType, failOnError)

argomenti e restituzioni

Argument Description Returns
endpoint Nome di un endpoint di servizio di un modello di Databricks Foundation, un endpoint di servizio del modello esterno o un endpoint di modello personalizzato nella stessa area di lavoro per le invocazioni come un valore letterale STRING. Il definer deve disporre dell'autorizzazione CAN QUERY per l'endpoint.
request Richiesta utilizzata per richiamare l'endpoint come espressione.
  • Se l'endpoint è un endpoint di servizio per modelli esterno o un endpoint delle API di modelli della Databricks Foundation, la richiesta deve essere un STRING.
  • Se l'endpoint è un endpoint di gestione del modello personalizzato, la richiesta può essere una singola colonna o un'espressione STRUCT. I nomi dei campi STRUCT devono corrispondere ai nomi delle funzionalità di input previsti dall'endpoint.
returnType (Facoltativo per Databricks Runtime 15.2 e versioni successive) Oggetto previsto returnType dall'endpoint come espressione. È simile al parametro dello schema nella funzione from_json, che accetta sia un'espressione STRING che una chiamata di schema_of_json funzione.
  • Per Databricks Runtime 15.2 e versioni successive, questa espressione è facoltativa. Se non viene specificato, ai_query() dedurre automaticamente il tipo restituito dallo schema del modello dell'endpoint di gestione del modello personalizzato.
  • Per Databricks Runtime 15.1 e versioni successive, questa espressione è necessaria per eseguire query su un endpoint di gestione del modello personalizzato.

Usare il responseFormat parametro per specificare i formati di risposta per i modelli di base di chat.
failOnError (Facoltativo) Un valore letterale booleano che per impostazione predefinita è vero. Richiede Databricks Runtime 15.3 o versione successiva. Questo flag indica se includere lo stato di errore nella ai_query risposta.
Vedere Gestire gli errori usando failOnError per un esempio.		 Di seguito viene descritto il comportamento restituito in base allo failOnError scenario:
  • Se failOnError => true, la funzione restituisce lo stesso risultato del comportamento esistente, ovvero la risposta analizzata dall'endpoint. Il tipo di dati della risposta analizzata viene dedotto dal tipo di modello, dall'endpoint dello schema del modello o dal parametro returnType nella funzione ai_query.
  • Se failOnError => false, la funzione restituisce un oggetto STRUCT contenente la risposta analizzata e la stringa di stato dell'errore.
    • Se l'inferenza della riga ha esito positivo, il campo errorStatus è null.
    • Se l'inferenza della riga non riesce a causa di errori dell'endpoint del modello, il campo response è null.
    • Se l'inferenza della riga ha esito negativo a causa di altri errori, l'intera query ha esito negativo.
modelParameters (Facoltativo) Un campo struct che contiene i parametri per i modelli di chat, completamento ed embedding per servire modelli di base o modelli esterni. Questi parametri del modello devono essere parametri costanti e non dipendenti dai dati.
  • Richiede Databricks Runtime 15.3 o versione successiva.
  • Quando questi parametri del modello non vengono specificati o impostati su null viene usato il valore predefinito. Ad eccezione di temperature che ha un valore predefinito di 0.0, i valori predefiniti per questi parametri del modello sono uguali a quelli elencati in Foundation model REST API reference.

Per un esempio, vedere Configurare un modello passando i parametri del modello.
responseFormat (Facoltativo) Specificare il formato di risposta che si vuole che il modello di base della chat segua.
  • Richiede Databricks Runtime 15.4 LTS o versione successiva. Disponibile solo per l'esecuzione di query sui modelli di base di chat.
  • Sono supportati due stili di formato di risposta.
    • Stringa JSON di stile DDL
    • Una stringa JSON. Sono supportati tre tipi di stringa JSON di formato di risposta:text , json_object, json_schema

Per esempi, vedere Applicare lo schema di output con output strutturato .		 Di seguito viene descritto cosa accade quando failOnError viene impostato anche quando responseFormat viene specificato:
  • Se failOnError => false e si è specificato responseFormat, la funzione restituisce la risposta analizzata e la stringa di stato dell'errore come oggetto STRUCT.
  • A seconda del tipo di stringa JSON specificato in responseFormat, viene restituita la risposta seguente:
    • Per responseFormat => '{"type": "text"}', la risposta è una stringa, ad esempio, “Here is the response”.
    • Per responseFormat => '{"type": "json_object"}', la risposta è una stringa JSON della coppia chiave-valore, ad esempio {“key”: “value”}.
    • Per responseFormat => '{"type": "json_schema", "json_schema"...}', la risposta è una stringa JSON.
files (Facoltativo) Specificare i file e il contenuto da usare nelle richieste di input multifunzionali usando files=>content. files è il nome del parametro previsto dal modello per l'input multimodale e content fa riferimento alla colonna nel dataframe che contiene il contenuto binario dei file di immagine che si desidera usare nella query.
  • Obbligatorio per le richieste multimodali.
  • Sono supportati solo gli input dell'immagine: JPEG o PNG . Per un esempio, vedere Input multimodali. Come illustrato in questo esempio, è possibile specificare la content colonna dell'output di read_files al files parametro.

esempio di : Eseguire query su un modello di base

Per eseguire query su un endpoint di gestione di un modello esterno:

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

Per eseguire query su un modello di base supportato dalle API del modello di 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

Facoltativamente, puoi anche avvolgere la chiamata a ai_query() in una UDF per la chiamata della funzione come segue.

 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;

Input multifunzionali

ai_query supporta nativamente gli input di immagini multimodali. Vedere Tipi di modello di base per i modelli di visione ospitati in Databricks supportati.

Di seguito sono riportati i tipi di input supportati:

  • JPEG
  • PNG

Nell'esempio seguente viene illustrato come interrogare un modello foundation supportato dalle API di Databricks Foundation Model per input multimodale. In questo esempio il files => content parametro viene usato per passare i dati del file di immagine a ai_query

  • files: nome del parametro previsto dal modello per l'input multimodale
  • content: colonna nel dataframe restituito da READ_FILES, che contiene il contenuto binario del file di immagine.

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

Per eseguire query su un modello di base supportato dalle API del modello di Databricks Foundation per l'input multifunzionale e specificare l'output strutturato:

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

Esempio: Eseguire query su un modello di Machine Learning tradizionale

Per eseguire query su un modello personalizzato o un modello di Machine Learning tradizionale che gestisce un endpoint:


> 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

Esempi per scenari avanzati

Le sezioni seguenti forniscono esempi di casi d'uso avanzati, ad esempio la gestione degli errori o come incorporare ai_query in una funzione definita dall'utente.

Passare una matrice di messaggi

Nell'esempio seguente viene illustrato come passare una matrice di messaggi all'applicazione modello o agente usando 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."]}

Concatenare la colonna di richiesta e inferenza

Esistono diversi modi per concatenare la richiesta e la colonna di inferenza, ad esempio usando ||, 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};

Oppure usando format_string():

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

Configurare un modello passando i parametri del modello

Personalizzare il comportamento del modello passando parametri specifici, ad esempio token e temperatura massimi. Per esempio:

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;

Gestire gli errori usando failOnError

Utilizzare l'argomento failOnError per ai_query per gestire gli errori. Nell'esempio seguente viene illustrato come assicurarsi che, se una riga presenta un errore, l'intera query non verrà interrotta dall'esecuzione. Consultare Argomenti e valori restituiti per i comportamenti previsti in base a come è impostato questo argomento.


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;

Imporre lo schema di output con un output strutturato

Assicurarsi che l'output sia conforme a uno schema specifico per semplificare l'elaborazione downstream usando responseFormat. Consulta Output strutturati in Azure Databricks.

L'esempio seguente applica uno schema stringa JSON di stile 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;

In alternativa, usando un formato di risposta dello schema 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;

Un output previsto potrebbe essere simile al seguente:

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

Usare ai_query nelle funzioni definite dall'utente

È possibile incapsulare una chiamata a ai_query in una UDF, semplificando l'uso di funzioni in flussi di lavoro diversi per condividerle.

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