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

  • 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 di gestione del modello personalizzato, la richiesta può essere una singola colonna o un'espressione di struct. 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 dello schema nella funzione from_json, che accetta sia un'espressione STRING che una chiamata di schema_of_json funzione.
    • In Databricks Runtime 14.2 e versioni successive, se questa espressione non viene fornita, ai_query() deduce automaticamente il tipo restituito dallo schema del modello personalizzato che gestisce l'endpoint.
    • 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 i parametri del modello di chat, completamento e incorporamento per la gestione di modelli di base o modelli esterni. Questi parametri del modello devono essere parametri costanti e non dipendenti dai dati. 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.
  • 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, dall'endpoint dello schema del modello 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 del modello e la colonna di inferenza 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;