Dela via


Funktionen ai_query

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.

Information om hur du använder ai_query i produktionsarbetsflöden finns i Utföra batch-LLM-slutsatsdragning med hjälp av AI Functions.

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.
  • Den här funktionen är inte tillgänglig i Azure Databricks SQL Classic.

  • Du måste aktivera Azure Private Link för att kunna använda den här funktionen i pro SQL-lager.

  • Databricks Runtime 15.3 eller senare rekommenderas. Användning av Databricks Runtime 15.2 eller lägre kan resultera i långsammare prestandahastigheter.

  • Arbetsytan måste finnas i en modellserverregion som stöds.

  • En befintlig slutpunkt för modellhantering med din modell inläst. Om du använder en grundmodell som är värd av Databricks skapas en slutpunkt åt dig. Annars kan du läsa Skapa anpassade modellserverslutpunkter eller Skapa grundmodellserverslutpunkter.

  • Att köra frågor mot Foundation Model-API:er är aktiverat som standard. Så här skickar du frågor till slutpunkter som tillhandahåller anpassade modeller eller externa modeller:

    • Aktivera AI_Query för anpassade modeller och externa modeller i användargränssnittet för Databricks Previews.
  • Den aktuellaDLT-lagerkanalen använder inte den senaste Databricks Runtime-versionen som stöder ai_query(). Ange pipelines.channel i tabellegenskaperna till 'preview' för att använda ai_query().

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

Syntax

För att göra en förfrågan till en slutpunkt som tillhandahåller en grundmodell, inklusive externa modeller eller en anpassad grundmodell:

ai_query(endpoint, request)

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

ai_query(endpoint, request)

Att skicka en förfrågan till en anpassad modellslutpunkt utan ett modellschema:

ai_query(endpoint, request, returnType, failOnError)

argument och returer

Argumentation Beskrivning Returer
endpoint En STRING literal, namnet på en Databricks Foundation-modell som betjänar slutpunkten, en extern modell som betjänar slutpunkten eller en anpassad modellslutpunkt på 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 en enda kolumn eller ett struct-uttryck. Fältnamnen för struct bör överensstämma med namnen på indatafunktionerna som förväntas av slutpunkten.
returnType Ett uttryck, det förväntade returnType från slutpunkten. Detta liknar schemaparametern i from_json funktion, som accepterar både ett STRING-uttryck eller anrop av schema_of_json funktion.
  • I Databricks Runtime 14.2 och senare, om det här uttrycket inte tillhandahålls, härleder ai_query() automatiskt returtypen från modellschemat 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 (Optional) En boolesk literal vars standardvärde är 'true'. Den här flaggan anger om du vill inkludera felstatus i svaret ai_query .
  • 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, modellschemaslutpunkten eller parametern returnType i funktionen ai_query.
  • Om failOnError => falsereturnerar funktionen ett STRUCT objekt som innehåller det tolkade svaret och felstatussträngen.
  • Om slutsatsdragningen av raden lyckas, är fältet errorStatusnull.
  • Om inferenstransaktionen för raden misslyckas på grund av modellens slutpunktsfel, är response-fältet null.
  • Om radens slutsatsdragning misslyckas på grund av andra fel misslyckas hela frågan.

Ett exempel finns i Hantera fel med hjälp av failOnError.
modelParameters (Valfritt) Ett struct-fält som innehåller chatt-, slutförande- och inbäddningsmodellparametrar för servering av grundmodeller eller externa modeller. Dessa modellparametrar måste vara konstanta parametrar och inte databeroende. När dessa modellparametrar inte anges eller anges till null används standardvärdet. Med undantag för temperature som har standardvärdet 0.0är standardvärdena för dessa modellparametrar desamma som de som anges i rest-API-referensen för Foundation-modellen.
Ett exempel finns i Konfigurera en modell genom att skicka modellparametrar.
responseFormat (Valfritt) Ett JSON-strängfält som anger det svarsformat som du vill att modellen ska följa. Tre strängtyper av svarsformat stöds:
  • text
  • json_object
  • json_schema
  • Om failOnError => false och du har angett responseFormatreturnerar funktionen det parsade svaret och felstatussträngen som ett STRUCT objekt.
  • 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", "json_schema"...}'är svaret en JSON-sträng.

Ett exempel finns i Tillämpa utdataschema med strukturerad utdata.

Konfigurera en modell genom att skicka modellparametrar

Anpassa modellbeteendet genom att skicka specifika parametrar, till exempel maximala token och temperatur. Till exempel:

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;

Hantera fel med hjälp av failOnError

Använd argumentet failOnError för ai_query för att hantera fel. I följande exempel visas hur du ser till att om en rad har ett fel hindrar det inte hela frågan från att köras. Se Argument och returnerar för förväntade beteenden baserat på hur det här argumentet anges.


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;

Tillämpa utdataschema med strukturerad utdata

Se till att utdata överensstämmer med ett specifikt schema för enklare nedströmsbearbetning. Du kan till exempel tillämpa ett JSON-schemasvarsformat:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "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;

Du kan också använda ett JSON-schema i DDL-format:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "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;

Förväntade utdata kan se ut så här:

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

Använda ai_query i användardefinierade funktioner

Du kan avsluta ett anrop till ai_query i en UDF, vilket gör det enkelt att använda funktioner i olika arbetsflöden och dela dem.

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;

Exempel: Fråga en grundmodell

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 gör du en förfrågan till en grundmodell som stöds av Databricks Foundation Model API:er:

> 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

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

Sammanfoga kolumnerna för utlösare och slutsatser

Det finns flera sätt att sammanfoga prompten och slutsatsdragningskolumnen, till exempel att använda ||, CONCAT()eller format_string():

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternativt:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Eller använda format_string():

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

Skicka failOnError och modelParameters för grundmodeller

I följande exempel visas hur du skickar parametrarna failOnError och modelParameters, inklusive max_tokens och temperature, för grundmodeller.

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

Exempel: Användningsfall för batchinferens

Följande är ett exempel på batchinferens med failOnError och modelParameters, tillsammans med max_tokens och temperature. Det här exemplet visar också hur du sammanfogar prompten för din modell och slutsatsdragningskolumnen 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}
)

Exempel: Fråga efter en traditionell ML-modell

För att göra en förfrågan till en anpassad modell eller en traditionell ML-modell som används vid en tjänstgörande slutpunkt:


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