ai_query函式

適用於：Databricks SQL Databricks Runtime

叫用現有的 Azure Databricks 模型服務端點 ，並剖析並傳回其回應。

請參閱下列指南， ai_query 以瞭解如何用於不同的使用案例：

• 使用 ai_query 執行批次 LLM 推理
• 使用 ai_query 查詢外部模型
• 使用 ai_query 查詢服務模型

需求

• 此函數不適用於 Azure Databricks SQL Classic。
• 您必須啟用 Azure Private Link ，才能在 Pro SQL 倉儲上使用這項功能。
• 建議使用 Databricks Runtime 15.3 或更新版本。 使用 Databricks Runtime 15.2 或更低版本可能會導致效能速度變慢。
• 目前的DLT 倉儲通道不會使用支援 ai_query()的最新 Databricks 執行時間版本。 pipelines.channel將資料表屬性中的 設定為 'preview' 使用 ai_query()。 請參閱 範例查詢的範例 。
• 已載入模型，提供端點的現有模型。 請參閱建立自訂模型服務端點。
• 您的工作區必須位於支援的 模型服務區域中。
• 預設會啟用查詢基礎模型 API。 若要查詢提供自訂模型或外部模型的端點：
  • 在 Databricks 預覽 UI 中啟用自定義模型和外部模型的AI_Query。
  • 請參閱 使用 ai_query查詢外部模型。
  • 請參閱 使用 ai_query 執行批次 LLM 推斷

語法

若要查詢提供外部模型或基礎模型的端點：

ai_query(endpoint, request)

若要使用模型架構查詢提供端點的自訂模型：

ai_query(endpoint, request)

若要在沒有模型架構的情況下查詢提供端點的自定義模型：

ai_query(endpoint, request, returnType, failOnError)

引數

• endpoint：STRING 字面值、Databricks Foundation 模型服務端點名稱、外部模型服務端點，或相同工作區中的自定義模型端點以進行調用。 定義器必須具有端點 CAN QUERY 許可權。
• request：表達式，用來叫用端點的要求。
  • 如果端點是外部模型服務端點或 Databricks Foundation 模型 API 端點，則要求必須是 STRING。
  • 如果端點是提供端點的自定義模型，要求可以是單一數據行或結構表達式。 結構域名應該符合端點所預期的輸入特徵名稱。
• returnType：來自端點的預期 returnType 表示式。 這類似於 from_json 函式中的架構參數，它會接受 STRING 表示式或調用 schema_of_json 函式。
  • 如果未提供此表達式，請在 Databricks Runtime 14.2 和更新版本中， ai_query() 從提供端點的自定義模型模型架構自動推斷傳回類型。
  • 在 Databricks Runtime 14.1 和以下版本中，查詢自定義模型服務端點時需要此運算式。
• failOnError:(選擇性） 布爾常值預設為 true。 此旗標指出是否要在回應中包含 ai_query 錯誤狀態。 當這個 設定為 false時，回應格式會有所不同。
• modelParameters （選擇性）：結構欄位，其中包含用於服務基礎模型或外部模型的聊天、完成和內嵌模型參數。 這些模型參數必須是常數參數，而不是數據相依。 未指定這些模型參數或設定為 null 預設值時。 除了預設值為 0.0的 temperature 之外，這些模型參數的預設值與 Foundation 模型 REST API 參考中所列出的預設值相同，。

傳回

來自端點的已剖析回應。

• 如果 failOnError => true為 ，則函式會傳回與現有行為相同的結果，這是來自端點的已剖析回應。 剖析回應的數據類型是從模型類型、模型架構端點或 returnType 函式中的 ai_query 參數推斷而來。
• 如果 failOnError => false，函式會傳回剖析的回應和錯誤狀態字串作為 STRUCT 物件。
  • 如果資料列的推斷成功，則 errorStatus 欄位是 null。
  • 如果資料列的推斷因為模型端點的錯誤而失敗，response 欄位會是 null。
  • 如果數據列的推斷因為其他錯誤而失敗，整個查詢就會失敗。

範例

以下是使用 failOnError 和 modelParameters 與的max_tokenstemperature批次推斷範例。 此範例也會示範如何使用 串連模型的提示和推斷數據行 concat()。 有多種方式可執行串連，例如使用 ||、 concat()或 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}
)

若要查詢服務端點的外部模型：

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

若要查詢 Databricks Foundation 模型 API 所支持的基礎模型：

> 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

或者，您也可以在 UDF 中包裝 對 的呼叫 ai_query() ，以便呼叫函式，如下所示：

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

若要查詢提供端點的自訂模型：

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

將 DLT 通道設定為預覽的範例查詢：

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