使用 ai_query

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

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

要求

  • 此功能在經典 SQL 倉庫中無法使用。
  • 需要 Databricks Runtime 15.4 LTS 或更新版本。 如需了解此要求的即將變更,請參閱 AI 函數要求 Databricks Runtime 17.3 LTS 或以上版本。 建議使用 Databricks Runtime 18.2 或以上版本,以獲得最佳效能及使用最新功能。

何時使用 ai_query

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

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

特定任務 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 託管模型、配置吞吐量模型、自訂模型及外部模型。

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

類型 說明 支援的模型 要求
Databricks 託管模型 Azure Databricks 託管這些基礎模型,並提供可讓您使用 ai_query 查詢的 system.ai 模型服務。 請參閱 依區域劃分的模型可用性,了解各項 Model Serving 功能支援哪些模型,以及這些模型在哪些區域可用。 請參閱 Databricks 託管推論 ,以了解模型服務中支援的基礎模型完整列表。 這些模型支援並最佳化,以開始使用批次推論和生產工作流程:
  • system.ai.databricks-claude-fable-5-2
  • system.ai.databricks-claude-fable-5-1
  • system.ai.databricks-claude-fable-5
  • system.ai.databricks-claude-opus-5-5
  • system.ai.databricks-claude-opus-5
  • system.ai.databricks-claude-sonnet-5-5
  • system.ai.databricks-claude-sonnet-5
  • system.ai.databricks-claude-haiku-5-5
  • system.ai.qwen35-122b-a10b
  • system.ai.qwen3-next-80b-a3b-instruct
  • system.ai.claude-opus-4-8
  • system.ai.claude-opus-4-7
  • system.ai.claude-opus-4-6
  • system.ai.claude-sonnet-4-6
  • system.ai.gpt-oss-20b
  • system.ai.gpt-oss-120b
  • system.ai.gemma-3-12b
  • system.ai.llama-4-maverick
  • system.ai.meta-llama-3-3-70b-instruct
  • system.ai.meta-llama-3-1-8b-instruct
  • system.ai.qwen3-embedding-0-6b
  • system.ai.gte-large-en

OpenAI 與 Google Gemini 模型僅透過 Databricks 提供的 ADI 服務提供。 若要在您的Azure Databricks環境中存取這些模型,請參閱 ADI Services。
其他 Azure Databricks 託管的模型可用於 AI 函數,但不建議用於大規模批次推論生產工作流程。 這些其他模型可用於使用 基礎模型 API 按代幣付費進行實時推論。
需要 Databricks Runtime 15.4 LTS 或更新版本才能使用此功能。 如需了解此要求的即將變更,請參閱 AI 函數要求 Databricks Runtime 17.3 LTS 或以上版本。 不需要端點布建或設定。 您使用這些模型時,會依 適用模型術語 及 AI 功能 區域可用性而定。
配置吞吐量模型 AI Functions 與部署於 Model Serving 的已配置吞吐量模型合作。
  • 微調基礎模型部署於模型服務平台
  • 部署於模型服務上的配置吞吐量模型
客製化車型與外部車型 你可以帶著自己的自訂或外部模型,並用 AI 函式查詢它們。 AI Functions 提供彈性,因此您可以查詢即時推論或批次推論案例的模型。

基礎模型的應用ai_query

以下範例示範如何使用 ai_query 搭配 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 進行具名實體辨識筆記本的批次推斷

拿筆記本