Funktionen `ai_query`

2025-05-20

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

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.4 LTS eller senare rekommenderas. Användning av Databricks Runtime 15.3 eller lägre kan leda till 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 aktuellaLakeflow Deklarativa pipelines-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-meta-llama-3-3-70b-instruct", text) as response
  FROM
    messages
  LIMIT 10;

Syntax

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

ai_query(endpoint, request)

Så här gör du en förfrågan till en anpassad modelltjänstslutpunkt 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`	Namnet på en tjänstslutpunkt för Databricks Foundation-modell, en extern tjänstslutpunkt eller en anpassad modellslutpunkt i samma arbetsyta för anrop som en `STRING` literal. Definieraren måste ha `CAN QUERY` behörighet på slutpunkten.
`request`	Den begäran som används för att anropa slutpunkten som ett uttryck. 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`	Förväntas `returnType` från slutpunkten som ett uttryck. Detta liknar schemaparametern i `from_json` funktion, som accepterar både ett `STRING`-uttryck eller anrop av `schema_of_json` funktion. I Databricks Runtime 15.2 och senare, om det här uttrycket inte tillhandahålls, härleds `ai_query()` automatiskt returtypen från modellschemat för den anpassade modellens serveringsslutpunkt. I Databricks Runtime 15.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 har true som standardvärde. Kräver Databricks Runtime 15.3 eller senare. 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. Kräver Databricks Runtime 15.3 eller senare. 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) Ange det svarsformat som du vill att chattmodellen ska följa. Kräver Databricks Runtime 15.4 LTS eller senare. Endast tillgängligt för att ställa frågor till chattbaserade grundmodeller. Två format för svarsformat stöds. En JSON-sträng i DDL-format En JSON-sträng. Tre JSON-strängtyper av svarsformat stöds: `text` `json_object` `json_schema` Se Tillämpa utdataschema med strukturerade utdata för exempel.	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. Se Tillämpa utdataschema med strukturerade utdata för exempel.

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

Exempel på avancerade scenarier

Följande avsnitt innehåller exempel på avancerade användningsfall som felhantering eller hur du införlivar ai_query i en användardefinierad funktion.

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

Kontrollera att utdata överensstämmer med ett specifikt schema för enklare nedströmsbearbetning med hjälp av responseFormat. Se Strukturerade utdata på Azure Databricks.

I följande exempel tillämpas ett JSON-strängschema i DDL-format:

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

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;

Dela via

Funktionen ai_query