Dela via

Funktionen ai_query

  • Artikel

Gäller för:markerad ja Databricks SQL markerad ja Databricks Runtime

Viktigt!

Den här funktionen finns som allmänt tillgänglig förhandsversion.

Anropar en befintlig Azure Databricks Model Serving-slutpunkt och parsar och returnerar svaret.

Se följande guider för hur du använder ai_query för olika användningsfall:

Krav

Kommentar

  • I Databricks Runtime 14.2 och senare stöds den här funktionen i Databricks Notebooks, inklusive notebook-filer som körs som en uppgift i ett Databricks-arbetsflöde.
  • I Databricks Runtime 14.1 och nedan stöds inte den här funktionen i Databricks Notebooks.

Syntax

Så här frågar du en slutpunkt som hanterar en extern modell eller en grundmodell:

ai_query(endpoint, request)

För att göra en förfrågan till en anpassad modell som tillhandahåller tjänster via slutpunkten med en modell schema:

ai_query(endpoint, request)

Så här kör du frågor mot en anpassad modell som betjänar slutpunkten utan en modell schema:

ai_query(endpoint, request, returnType, failOnError)

Argument

  • endpoint: En STRING literal, namnet på en Databricks Foundation-modellserveringsslutpunkt, en extern modellserveringsslutpunkt eller en anpassad modellslutpunkt i samma arbetsyta för anrop. Definieraren måste ha CAN QUERY behörighet på slutpunkten.
  • request: Ett uttryck, den begäran som används för att anropa slutpunkten.
    • Om slutpunkten är en extern modellbetjänande slutpunkt eller en slutpunkt för Databricks Foundation-modellens API:er, måste begäran vara en STRING.
    • Om slutpunkten är en anpassad modell som betjänar slutpunkten kan begäran vara ett enda column eller ett struct-uttryck. Fältnamnen för struct ska matcha de indatafunktionsnamn som förväntas av slutpunkten.
  • returnType: Ett uttryck, det förväntade värdet returnType från slutpunkten. Detta liknar parametern schema i from_json funktion, som accepterar både ett STRING-uttryck eller anrop av schema_of_json funktion.
    • Om det här uttrycket inte anges i Databricks Runtime 14.2 och senare, kommer ai_query() automatiskt att härleda returtypen från modellen schema för den anpassade modell som betjänar slutpunkten.
    • I Databricks Runtime 14.1 och nedan krävs det här uttrycket för att köra frågor mot en anpassad modell som betjänar slutpunkten.
  • failOnError: (valfritt) En boolesk literal som standard är true. Den här flaggan anger om du vill inkludera felstatus i svaret ai_query .
  • modelParameters (valfritt): Ett struct-fält som innehåller chatt-, slutförande- och inbäddningsmodell parameters för servering av grundmodeller eller externa modeller. Den här modellen parameters måste vara konstant parameters och inte databeroende. När dessa modeller parameters inte har angetts eller set till null används standardvärdet. Med undantag för temperature som har standardvärdet 0.0är standard values för modellen parameters samma som de som anges i rest-API-referensen för Foundation-modellen.
  • responseFormat (valfritt): Ett JSON-strängfält som anger vilket svarsformat du vill att modellen ska följa. Tre strängtyper av svarsformat stöds:
    • text
    • json_object
    • json_schema

Returer

Det tolkade svaret från slutpunkten.

  • Om failOnError => truereturnerar funktionen samma resultat som det befintliga beteendet, vilket är det tolkade svaret från slutpunkten. Datatypen för det parsade svaret härleds från modelltypen, modellen schema slutpunkten eller parametern returnType i funktionen ai_query.
  • Om failOnError => falsereturnerar funktionen det parsade svaret och felstatussträngen som ett STRUCT objekt.
    • Om slutsatsen av raden lyckades, är errorStatus-fältet null.
    • Om inläsningen av raden misslyckades på grund av fel med modellens slutpunkt, är fältet responsenull.
    • Om radens slutsatsdragning misslyckades på grund av andra fel misslyckas hela frågan.
  • Beroende på vilken JSON-strängtyp som anges i responseFormatreturneras följande svar:
    • För responseFormat => '{“type”, “text”}'är svaret en sträng som “Here is the response”.
    • För responseFormat => '{“type”, “json_object”}'är svaret en nyckel/värde-par-JSON-sträng, till exempel {“key”: “value”}.
    • För responseFormat => '{“type”, “json_schema”...}'är svaret en JSON-sträng. Se Exempel.
  • Om failOnError => false och du har angett responseFormatreturnerar funktionen det parsade svaret och felstatussträngen som ett STRUCT objekt.

Exempel

I följande exempel anges ett json_schema svarsformat:


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
                          }
                      }'
  )

Följande är ett exempel på utdata för det angivna json_schema svarsformatet:

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

Följande är ett exempel på failOnError batchinferens med och modelParameters med max_tokens och temperature. Det här exemplet visar också hur du sammanfogar prompten för din modell och slutsatsdragningen column med hjälp av concat(). Det finns flera sätt att utföra sammanfogning, till exempel att använda ||, concat()eller 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}
)

Så här frågar du en extern modell som betjänar slutpunkten:

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

Så här frågar du en grundmodell som stöds av Api:er för Databricks Foundation-modell:

> 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

Du kan också omsluta ett anrop till ai_query() i en UDF för funktionsanrop enligt följande:

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

Så här frågar du en anpassad modell som betjänar slutpunkten:


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

Exempelfråga för att ställa in DLT-kanalen som förhandsversion:

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