Condividi tramite

Funzione ai_query

  • Articolo

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

Importante

Questa funzionalità è disponibile in anteprima pubblica.

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

Per informazioni su come usare per casi d'uso ai_query diversi, vedere le guide seguenti:

Fabbisogno

Nota

  • In Databricks Runtime 14.2 e versioni successive questa funzione è supportata nei notebook di Databricks, inclusi i notebook eseguiti come attività in un flusso di lavoro di Databricks.
  • In Databricks Runtime 14.1 e versioni precedenti questa funzione non è supportata nei notebook di Databricks.

Sintassi

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

ai_query(endpoint, request)

Per eseguire query su un endpoint personalizzato che gestisce un modello di schema:

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

Argomenti

  • endpoint: valore letterale STRING, nome di un endpoint di servizio del 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. Il definer deve disporre dell'autorizzazione CAN QUERY per l'endpoint.
  • request: espressione, richiesta usata per richiamare l'endpoint.
    • 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 personalizzato per la gestione dei modelli, la richiesta può essere una singola column o un'espressione strutturata. I nomi dei campi dello struct devono corrispondere ai nomi delle funzionalità di input previsti dall'endpoint.
  • returnType: Un'espressione, il returnType previsto dall'endpoint. È simile al parametro schema nella funzione from_json, che accetta sia un'espressione STRING sia una chiamata della funzione schema_of_json.
    • In Databricks Runtime 14.2 e versioni successive, se questa espressione non viene specificata, ai_query() deduce automaticamente il tipo restituito dal modello schema dell'endpoint di gestione del modello personalizzato.
    • In Databricks Runtime 14.1 e versioni successive questa espressione è necessaria per eseguire query su un endpoint di gestione di un modello personalizzato.
  • failOnError: (facoltativo) Valore letterale booleano che per impostazione predefinita è true. Questo flag indica se includere lo stato di errore nella ai_query risposta.
  • modelParameters (facoltativo): campo struct che contiene chat, completamento e incorporamento del modello parameters per gestire modelli di base o modelli esterni. Questi modelli parameters devono essere costanti parameters e non dipendenti dai dati. Quando il modello parameters non viene specificato o quando da set a null, viene usato il valore predefinito. Ad eccezione di temperature che ha un valore predefinito di 0.0, i values predefiniti per questi modelli parameters sono uguali a quelli elencati nella documentazione di riferimento per l'API REST del modello Foundation .
  • responseFormat (facoltativo): campo stringa JSON che specifica il formato di risposta che si vuole che il modello segua. Sono supportati tre tipi di stringa di formato di risposta:
    • text
    • json_object
    • json_schema

Valori restituiti

Risposta analizzata dall'endpoint.

  • 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, dal modello schema endpoint o dal parametro returnType nella funzione ai_query.
  • Se failOnError => false, la funzione restituisce la risposta analizzata e la stringa di stato dell'errore come oggetto STRUCT.
    • Se l'inferenza della riga ha esito positivo, il campo errorStatus è null.
    • Se l'inferenza della riga non è riuscita a causa di errori dell'endpoint del modello, il campo response è null.
    • Se l'inferenza della riga non è riuscita a causa di altri errori, l'intera query ha esito negativo.
  • 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”...}', la risposta è una stringa JSON. Vedere gli esempi .
  • Se failOnError => false e si è specificato responseFormat, la funzione restituisce la risposta analizzata e la stringa di stato dell'errore come oggetto STRUCT.

esempi di

Nell'esempio seguente viene specificato un formato di risposta json_schema:


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

Di seguito è riportato un output di esempio per il formato di risposta json_schema specificato:

{"title": "<the title of the paper>"}

Di seguito è riportato un esempio di inferenza batch che usa failOnError e modelParameters con max_tokens e temperature. Questo esempio illustra anche come concatenare il prompt per il tuo modello e l'inferenza column usando concat(). Esistono diversi modi per eseguire la concatenazione, ad esempio usando ||, 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}
)

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

Facoltativamente, è anche possibile eseguire il wrapping di una chiamata a ai_query() in una funzione definita dall'utente per chiamare la funzione come indicato di seguito:

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

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


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

Query di esempio per impostare il canale DLT su anteprima:

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