使用 ai_query

ai_query 是一個通用的 AI 函式，讓你能直接從 SQL 或 Python 查詢任何支援的 AI 模型。 與專為單一任務設計並優化的任務專屬 AI 函數不同，AI ai_query 功能讓你完全掌控模型、提示詞和參數。

完整語法與參數參考，請參見 ai_query 函式。

要求

• 此功能在經典 SQL 倉庫中無法使用。
• 需要 Databricks Runtime 15.4 LTS 或更新版本。 建議使用 Databricks Runtime 18.2 或以上版本，以獲得最佳效能及使用最新功能。

何時使用 ai_query

Databricks 建議你首先使用與你的目標相符的任務專屬 AI 函數。 當某個任務專屬功能不符合你的需求時，才會使用 ai_query 。 例如，當你需要：

• 更精確地控制提示詞、模型參數或輸出格式
• 查詢一個自訂、外部或經微調的模型
• 需要彈性以進一步優化吞吐量或品質

最佳做法

• 使用 Databricks 託管的模型。 使用 system.ai 模型服務而非配置式吞吐量端點。 這些模型服務完全受管理並自動擴展，無需配置或設定。
• 選擇一個針對批次推論優化的模型。 Databricks 會針對高吞吐量批次工作負載優化特定模型。 使用未優化的模型可能導致吞吐量下降及工作完成時間延長。 完整批次優化模型列表請參閱 支援模型 。
• 請在一次查詢中提交完整的資料集。 AI 功能會自動處理平行化、重試與縮放。 手動將資料拆分成小批次可能會降低吞吐量。
• 設定 failOnError 為 false 用於大型工作負載。 這讓工作能完成，並回傳失敗列的錯誤訊息，讓您保留成功的結果而不需要重新處理整個資料集。

Unity Gateway 治理

ai_query 對 system.ai 模型服務（例如） system.ai.gpt-5-4的請求會自動透過 Unity Gateway 路由。 你在 Unity Gateway 建立的模型服務尚未被支援。 只有 Unity Gateway 的部分功能適用於經路由的請求：

• 支援： 使用追蹤、 預算 整合（包括硬性支出上限），以及模型服務的權限檢查。
• 不支援：護欄（服務政策）、推論表、追蹤表、速率限制、備援及外部模型提供者。

如需詳細資訊，請參閱使用 ai_query 查詢端點。

支援的模型

ai_query 支援 Databricks 託管模型、配置吞吐量模型、自訂模型及外部模型。

下表摘要說明支援的模型類型、相關聯的模型，以及針對每個端點組態需求提供服務的模型。

基礎模型的應用ai_query

以下範例示範如何使用 ai_query 搭配 Azure Databricks 主機的基礎模型。

• 如需語法詳細數據和參數，請參閱 ai_query 函式 。
• 如需多模態輸入查詢範例，請參閱多模態輸入。
• 請參閱 進階案例範例， 以取得如何設定進階使用案例參數的指引，例如：
  • 處理錯誤時使用 failOnError
  • Structured outputs on Azure Databricks 了解如何為查詢回應指定結構化輸出。

SQL

SELECT text, ai_query(
    "system.ai.gpt-oss-120b",
    "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
) AS summary
FROM uc_catalog.schema.table;

Python

df_out = df.selectExpr(
  "ai_query('system.ai.gpt-oss-120b', CONCAT('Please provide a summary of the following text: ', text), modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)) as summary"
)
df_out.write.mode("overwrite").saveAsTable('output_table')

範例筆記本：批次推論和結構化資料擷取

以下範例筆記本示範如何利用 ai_query 自動化擷取技術，將原始非結構化資料轉換為有組織且可用的資訊。 本筆記也展示了如何利用代理人評估（Agent Evaluation）利用實地真實數據評估準確性。

批次推論和結構化資料擷取筆記本

拿筆記本

與傳統 ML 模型搭配使用ai_query

ai_query 支援傳統的 ML 模型，包括完全自定義的模型。 這些模型必須部署在模型服務端點上。 如需語法詳細數據和參數，請參閱 ai_query 函式。

SELECT text, ai_query(
  endpoint => "spam-classification",
  request => named_struct(
    "timestamp", timestamp,
    "sender", from_number,
    "text", text),
  returnType => "BOOLEAN") AS is_spam
FROM catalog.schema.inbox_messages
LIMIT 10

範例筆記本：使用 BERT 進行具名實體辨識的批次推斷

下列筆記本顯示使用 BERT 的傳統 ML 模型批次推論範例。

使用 BERT 進行具名實體辨識筆記本的批次推斷

拿筆記本