Funktionen ai_query
Gäller för: 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:
Den aktuellaDLT-lagerkanalen använder inte den senaste Databricks Runtime-versionen som stöder
ai_query()
. Angepipelines.channel
i tabellegenskaperna till'preview'
för att användaai_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.
|
|
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.
|
|
failOnError |
(Optional) En boolesk literal vars standardvärde är 'true'. Den här flaggan anger om du vill inkludera felstatus i svaret ai_query . |
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:
|
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."]}