ai_query-Funktion

Gilt für: Databricks SQL Databricks Runtime

Ruft einen vorhandenen Modellbereitstellungsendpunkt von Azure Databricks, parst ihn und gibt seine Antwort zurück.

ai_query ist eine allgemeine KI-Funktion , die es Ihnen ermöglicht, vorhandene Endpunkte nach Rückschlüssen in Echtzeit oder Batch-Inference-Workloads abzufragen.

• Siehe Allgemeine Funktion: ai_query für unterstützte Modelle und erforderliche Endpunktkonfigurationen.
• Sie können auch ai_query verwenden, um einen AI-Agenten abzufragen, der auf einem ML-Modell-Serving-Endpunkt bereitgestellt ist. Weitere Informationen finden Sie unter Abfragen eines bereitgestellten Mosaic AI Agent.
• Informationen zur Verwendung ai_query in Produktionsworkflows finden Sie unter Bereitstellen von Batch-Ableitungspipelines.

Anforderungen

• Diese Funktion ist in Azure Databricks SQL Classic nicht verfügbar.

• Sie müssen Azure Private Link aktivieren, um dieses Feature in SQL-Warehouses vom Typ „Pro“ verwenden zu können.

• Databricks Runtime 15.4 LTS oder höher wird empfohlen. Die Verwendung von Databricks Runtime 15.3 oder darunter kann zu langsameren Leistungsgeschwindigkeiten führen.

• Ihr Arbeitsbereich muss sich in einer unterstützten Modellbereitstellungsregion befinden.

• Ein vorhandener Modellbereitstellungsendpunkt mit geladenem Modell. Wenn Sie ein von Databricks gehostetes Foundation-Modell verwenden, wird ein Endpunkt für Sie erstellt. Andernfalls finden Sie informationen unter Erstellen eines benutzerdefinierten Modells, das Endpunkte bedient , oder erstellen eines Foundation-Modells, das Endpunkte bedient.

• Das Abfragen von Foundation Model-APIs ist standardmäßig aktiviert. So fragen Sie Endpunkte ab, die benutzerdefinierte Modelle oder externe Modelle bedienen:

  • Aktivieren Sie AI_Query für benutzerdefinierte Modelle und externe Modelle auf der Databricks Previews-Benutzeroberfläche.

• Der aktuelleLakeflow Spark Declarative Pipelines Warehouse-Kanal verwendet nicht die neueste Databricks-Runtime-Version, die unterstützt ai_query(). Legen Sie die pipelines.channel in den Tabelleneigenschaften als 'preview' fest, um ai_query() zu verwenden.

  > 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

So fragen Sie einen Endpunkt ab, der einem Foundationmodell dient:

ai_query(endpoint, request)

So fragen Sie ein benutzerdefiniertes Modell ab, das Endpunkt mit einem Modellschema bedient:

ai_query(endpoint, request)

Abfragen eines benutzerdefinierten Modellbereitstellungsendpunkts ohne Modellschema:

ai_query(endpoint, request, returnType, failOnError)

Argumente und Rückgaben

Beispiel: Abfragen eines Foundation-Modells

So fragen Sie einen externen Modellbereitstellungsendpunkt ab

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

So fragen Sie ein Foundation-Modell ab, das von Databricks-Foundation-Modell-APIs unterstützt wird

> 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

Optional können Sie auch wie folgt einen Aufruf von ai_query() in einer UDF für Funktionsaufrufe umschließen:

 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;

Multimodale Eingaben

ai_query unterstützt systemeigene multimodale Bildeingaben. Siehe Foundation-Modelltypen für die unterstützten von Databricks gehosteten Vision-Modelle.

Die folgenden Eingabetypen werden unterstützt:

• JPEG
• PNG

Das folgende Beispiel zeigt, wie Sie ein Foundation-Modell abfragen, das von Databricks Foundation Model-APIs für die multimodale Eingabe unterstützt wird. In diesem Beispiel wird der Parameter files => content verwendet, um die Bilddatei-Daten an ai_query weiterzugeben.

• files: Der vom Modell für die multimodale Eingabe erwartete Parametername
• content: Die Spalte im DataFrame, die von READ_FILES zurückgegeben wird und den binären Inhalt der Bilddatei enthält.

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

So fragen Sie ein Foundation-Modell ab, das von Databricks Foundation Model-APIs für die multimodale Eingabe unterstützt wird, und geben Sie eine strukturierte Ausgabe an:

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

Beispiel: Abfragen eines herkömmlichen ML-Modells

So fragen Sie ein benutzerdefiniertes Modell oder einen herkömmlichen ML-Modellbereitstellungsendpunkt ab

> 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

Beispiele für erweiterte Szenarien

In den folgenden Abschnitten finden Sie Beispiele für erweiterte Anwendungsfälle wie die Fehlerbehandlung oder die Integration ai_query in eine benutzerdefinierte Funktion.

Ein Nachrichtenarray übergeben

Das folgende Beispiel zeigt, wie Sie ein Nachrichtenarray mit ai_query an Ihr Modell oder Ihre Agentanwendung übergeben.

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

Verketten des Prompts und der Rückschlussspalte

Es gibt mehrere Möglichkeiten, die Eingabeaufforderung und die Ableitungsspalte zu verketten, wie etwa durch die Verwendung von ||, CONCAT() oder 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};

Oder unter Verwendung von format_string():

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

Konfigurieren eines Modells durch Übergeben von Modellparametern

Passen Sie das Modellverhalten an, indem Sie bestimmte Parameter wie maximale Token und Temperatur übergeben. Beispiel:

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;

Behandeln von Fehlern mithilfe von failOnError

Verwenden Sie das failOnError-Argument für ai_query zur Fehlerbehandlung. Das folgende Beispiel zeigt, wie Sie sicherstellen können, dass die Ausführung der gesamten Abfrage nicht beendet wird, wenn eine Zeile einen Fehler aufweist. Siehe Argumente und Rückgaben für erwartete Verhaltensweisen basierend auf der Festlegung dieses Arguments.

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;

Erzwingen eines Ausgabeschemas mit strukturierter Ausgabe

Stellen Sie sicher, dass die Ausgabe einem bestimmten Schema entspricht, um die nachgelagerte Verarbeitung zu vereinfachen.responseFormat Siehe Strukturierte Ausgaben auf Azure Datenbausteine.

Im folgenden Beispiel wird ein JSON-Zeichenfolgenschema im DDL-Stil erzwungen:

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;

Alternativ können Sie ein JSON-Schemaantwortformat verwenden:

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;

Eine erwartete Ausgabe könnte wie folgt aussehen:

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

Verwenden ai_query in benutzerdefinierten Funktionen

Sie können einen Aufruf ai_query in eine UDF umschließen, sodass Funktionen in verschiedenen Workflows einfach verwendet und freigegeben werden können.

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;