Freigeben über

ai_query-Funktion

  • Artikel

Gilt für: durch Häkchen mit „Ja“ markiert Databricks SQL durch Häkchen mit „Ja“ markiert Databricks Runtime

Wichtig

Dieses Feature befindet sich in der Public Preview.

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

In den folgenden Leitfäden erfahren Sie, wie Sie für unterschiedliche Anwendungsfälle verwenden ai_query können:

Anforderungen

Hinweis

  • In Databricks Runtime 14.2 und höher wird diese Funktion in Databricks-Notebooks unterstützt, einschließlich Notebooks, die als Task in einem Databricks-Workflow ausgeführt werden.
  • In Databricks Runtime 14.1 und früher wird diese Funktion in Databricks-Notebooks nicht unterstützt.

Syntax

So fragen Sie einen Endpunkt für ein externes Modell oder Foundation Model-Endpunkt ab

ai_query(endpointName, request)

Vorgehensweise zum Abfragen eines Modellbereitstellungsendpunkt mit Modellschema:

ai_query(endpointName, request)

Vorgehensweise zum Abfragen eines Modellbereitstellungsendpunkt ohne Modellschema:

ai_query(endpointName, request, returnType, failOnError)

Argumente

  • endpointName: Ein Zeichenfolgenliteral, der Name eines Databricks-Basismodell-Bereitstellungsendpunkts, eines externen Modellbereitstellungsendpunkts oder eines benutzerdefinierten Modellendpunkts im selben Arbeitsbereich für Aufrufe. Das Definer-Element muss über die Berechtigung KANN ABFRAGEN für den Endpunkt verfügen.
  • request: Ein Ausdruck, die Anforderung, die zum Aufrufen des Endpunkts verwendet wird.
    • Wenn der Endpunkt ein externer Model Serving-Endpunkt ist oder für Databricks Foundation Model-APIs verwendet wird, muss die Anforderung eine ZEICHENFOLGE sein.
    • Wenn der Endpunkt ein benutzerdefinierter Model Serving-Endpunkt ist, kann die Anforderung eine einzelne Spalte oder ein Strukturausdruck sein. Die Namen des Strukturfelds sollten mit den Featurenamen der Eingabe übereinstimmen, die vom Endpunkt erwartet werden.
  • returnType: Ein Ausdruck, der vom Endpunkt erwartete Rückgabetyp (returnType). Dies ähnelt dem Schemaparameter in der from_json-Funktion, die sowohl einen STRING-Ausdruck als auch den Aufruf der schema_of_json-Funktion akzeptiert.
    • Wenn in Databricks Runtime 14.2 und höher dieser Ausdruck nicht angegeben wird, leitet ai_query() den Rückgabetyp automatisch aus dem Modellschema des benutzerdefinierten Modellbereitstellungsendpunkts ab.
    • In Databricks Runtime 14.1 und darunter ist dieser Ausdruck zum Abrufen eines benutzerdefinierten Modellbereitstellungsendpunkts erforderlich.
  • failOnError: (optional) Ein boolescher Literalstandard auf "true". Dieses Flag gibt an, ob der Fehlerstatus in die ai_query Antwort eingeschlossen werden soll. Das Antwortformat unterscheidet sich, wenn dies auf . false festgelegt ist.
  • modelParameters (optional): Ein Strukturfeld, das Chat-, Abschluss- und Einbettungsmodellparameter für die Bereitstellung von Foundationmodellen oder externen Modellen enthält. Diese Modellparameter müssen Konstantenparameter und keine datenabhängigen Parameter sein. Wenn diese Modellparameter nicht angegeben oder auf null den Standardwert festgelegt werden. Abgesehen davon temperature , dass der Standardwert 0,0 ist, sind die Standardwerte für diese Modellparameter identisch mit denen, die in der Foundation-Modell-REST-API-Referenz aufgeführt sind.

Gibt zurück

Die geparste Antwort vom Endpunkt.

  • Wenn failOnError => true, gibt die Funktion dasselbe Ergebnis wie das vorhandene Verhalten zurück, bei dem es sich um die analysierte Antwort des Endpunkts handelt. Der Datentyp der analysierten Antwort wird vom Modelltyp, dem Modellschemaendpunkt oder dem returnType Parameter in der ai_query Funktion abgeleitet.
  • Wenn failOnError => false, gibt die Funktion die analysierte Antwort und die Fehlerstatuszeichenfolge als STRUCT-Objekt zurück.
    • Wenn die Ableitung der Zeile erfolgreich war, ist das errorStatus Feld null.
    • Wenn die Ableitung der Zeile aufgrund von Modellendpunktfehlern fehlgeschlagen ist, ist das response Feld NULL.
    • Wenn die Ableitung der Zeile aufgrund anderer Fehler fehlgeschlagen ist, schlägt die gesamte Abfrage fehl.

Beispiele

Im Folgenden sehen Sie ein Batch-Ableitungsbeispiel mit und failOnError modelParameters mit max_tokens und temperature. In diesem Beispiel wird auch veranschaulicht, wie Sie die Eingabeaufforderung für Ihr Modell und die Rückschlussspalte mithilfe von concat(). verketten. Es gibt mehrere Möglichkeiten zum Ausführen von Verkettung, z. B. verwenden ||, concat()oder 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}
)

So fragen Sie einen Bereitstellungsendpunkt für ein externes Modell 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-1-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-1-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;

So fragen Sie einen Model Serving-Endpunkt 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

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-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."]}

Beispielabfrage zum Festlegen des DLT-Kanals für die Vorschau:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages