Funktionen ai_query

gäller för: Databricks SQL Databricks Runtime

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

ai_query är en AI-funktion för generell användning som gör att du kan köra frågor mot befintliga slutpunkter för arbetsbelastningar för slutsatsdragning i realtid eller batchinferens. Se Funktionen Generell användning: ai_query för modeller som stöds och nödvändiga slutpunktskonfigurationer.

Information om hur du använder ai_query i produktionsarbetsflöden finns i Distribuera batchinferenspipelines.

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

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;

Multimodala inmatningar

ai_query har inbyggt stöd för multimodala bildindata. Se Grundläggande modelltyper för de Databricks-värdbaserade visionsmodellerna som stöds.

Följande är indatatyper som stöds:

• JPEG
• PNG

Så här frågar du en grundmodell som stöds av Databricks Foundation Model-API:er för multimodala indata:

> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

Så här frågar du en grundmodell som stöds av Databricks Foundation Model-API:er för multimodala indata och anger strukturerade utdata:

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

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

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.

Skicka en meddelandematris

I följande exempel visas hur du skickar en meddelandematris till din modell eller agentapp med hjälp av ai_query.

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

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

Alternatively:

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-gpt-oss-20b",
    "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-gpt-oss-20b",
    "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;