Funktionen `ai_query`

Artikel
03/11/2025

Gäller för: markerad ja Databricks SQL 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 => true`returnerar 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 => false`returnerar 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 `responseFormat`returnerar funktionen det parsade svaret och felstatussträngen som ett `STRUCT` objekt. Beroende på vilken JSON-strängtyp som anges i `responseFormat`returneras 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.

Sammanfoga prompt- och slutsatsdragningskolumnen

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

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

För att göra en förfrågan till en extern modellservice-slutpunkt:

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

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

Dela via

Funktionen `ai_query`

Krav

Syntax

argument och returer

Sammanfoga prompt- och slutsatsdragningskolumnen

Konfigurera en modell genom att skicka modellparametrar

Hantera fel med hjälp av `failOnError`

Tillämpa utdataschema med strukturerad utdata

Använda `ai_query` i användardefinierade funktioner

Exempel: Fråga en grundmodell

Exempel: Användningsfall för batchinferens

Exempel: Fråga efter en traditionell ML-modell

Feedback

Ytterligare resurser

Dela via

Funktionen ai_query

Krav

Syntax

argument och returer

Sammanfoga prompt- och slutsatsdragningskolumnen

Konfigurera en modell genom att skicka modellparametrar

Hantera fel med hjälp av failOnError

Tillämpa utdataschema med strukturerad utdata

Använda ai_query i användardefinierade funktioner

Exempel: Fråga en grundmodell

Exempel: Användningsfall för batchinferens

Exempel: Fråga efter en traditionell ML-modell

Feedback

Ytterligare resurser

Funktionen `ai_query`

Hantera fel med hjälp av `failOnError`

Använda `ai_query` i användardefinierade funktioner