Databricks 讓你用同一套方式查模型

以前我得一個個試入口，現在我先看任務類型、再選查詢路徑。

我用 Databricks 的 model serving 一陣子了，越看越有一種熟悉的煩：文件把選項列得很完整，卻也很容易讓人卡在「到底該從哪個入口打進去」這件事。我本來只是想知道，手上有 foundation model endpoint 之後，最省事的呼叫方式是什麼。結果一翻開文件，OpenAI client、REST API、MLflow Deployments SDK、Databricks Python SDK、AI Functions、Serving UI 全都擺在眼前，像在說你自己挑吧。問題是，選項太多的時候，大家最後都會先亂接，然後再花一個下午除錯。

這篇我是拿 Databricks 官方文件 Use foundation models | Databricks on AWS 來拆。它不是在講一個新玩具，而是在講一個很實際的工作流：你要怎麼把 hosted 或 external foundation model 接進 notebook、SQL、服務或 production。Databricks 這頁最有價值的地方，不是模型清單有多長，是它其實已經把很多人會踩的坑先寫在前面了，只是你得知道怎麼讀。

先把模型當成一般 API，不要把它神格化

Model Serving uses a unified OpenAI-compatible API and SDK for querying them.

翻譯一下就是，Databricks 想把一堆不同模型的呼叫方式收斂成同一套心智模型。你如果用過 OpenAI 風格的 client，這種寫法會很順：同樣的 request 形狀，不同的後端。這件事看起來很平凡，但我其實很買單，因為它直接少掉一堆「今天到底要套哪個 vendor wrapper」的鳥事。

我以前在團隊裡最常看到的狀況，就是 notebook 一套、Python service 一套、SQL 又一套。每個人都覺得自己只是「先方便一下」，結果半年後沒人知道別人的 request 到底怎麼組的。統一 API 不會自動讓架構變好，但至少不會讓大家在最前面那層就各自發明儀式感。

Databricks 也明講了，它同時支援 Databricks-hosted foundation models 和 external models。這表示你可以先用同一個呼叫方式，之後再換底層供應商。實務上這很重要，因為很多團隊一開始先接某個 hosted model，等成本、品質、延遲、合規條件變了，才發現整個整合綁死在某一家。這頁的訊息很直接：把呼叫介面先統一，底層模型再慢慢替換。

我自己的做法是，先把團隊內部的標準呼叫方式定下來。你們如果本來就熟 OpenAI 風格，那就先用那個當預設；如果整個 stack 都在 Databricks 裡面，那就優先看 Databricks Python SDK 或 MLflow Deployments SDK。不要每個人都自己挑一套，最後變成每個 repo 都像不同公司的專案。

• 同一種 request 形狀，盡量用在 notebook、job、service。
• 供應商差異放在邊界，不要散落在每個 caller 裡。
• endpoint 名稱、認證方式、payload schema 要一起記。

真正該先決定的，是你從哪條路進去

Query options: OpenAI client, AI Functions, Serving UI, REST API, MLflow Deployments SDK, Databricks Python SDK.

這句話我看完的感想很簡單：Databricks 給你的是同一間房子的六扇門，不是六個不同的房間。差別只在於你現在要做的是試驗、整合、還是正式上線。文件列了六種查詢 foundation model endpoint 的方式，每一種都對應不同場景。

如果我在 notebook 裡做原型，我會先看 OpenAI client 或 Databricks Python SDK，因為我不想一開始就手刻 HTTP request。要是我只是想快速看 prompt 跑出來長什麼樣，Serving UI 很夠用。若我已經在 SQL 裡，想直接做推論，AI Functions 就是最順的入口。要是我要做跨語言、跨平台、最少依賴的整合，REST 依然是那個老派但可靠的選擇。

我以前很愛一開始就選「最通用」的路，結果就是 REST everywhere，外加一堆 JSON glue、auth boilerplate、錯誤處理。看起來很專業，實際上只是把時間花在重造輪子。這份文件其實是在提醒你，先選符合工作情境的表面層，真的需要控制力再往下走，不要一開始就把自己綁進最硬的那條路。

實操上，我會這樣分：資料科學家在 notebook 用 client library；資料平台或 batch job 用 SDK；SQL 團隊用 ai_query；平台團隊保留 REST 當最低共同分母。這樣每個人都走自己熟的路，但底層還是同一個 endpoint。這種安排才不會讓模型一進 production 就變成大家互相猜對方怎麼接的拼圖。

• Notebook 原型：OpenAI client 或 Databricks SDK。
• SQL 推論：AI Functions。
• 服務整合：REST API。
• 人工檢查：Serving UI。

認證這關，別拿人類帳號硬撐

For production scenarios, Databricks recommends that you use machine-to-machine OAuth tokens for authentication.

白話一點就是，正式環境別再用個人 token 撐場面了。我知道很多人 dev 階段都會先偷懶，用自己的 token 先跑通，因為最快。但文件在這裡講得很清楚，production 就該用 machine-to-machine OAuth，這不是口味問題，是維運問題。

它也提到，testing 和 development 建議用 service principals 的 personal access token，而不是 workspace user 的 token。這個差別很重要，因為它等於是在逼你提早把「人」和「機器」的權限切開。很多團隊出事，不是模型不好，是 token 綁在某個人身上，等那個人離職、換權限、或 token 過期，整條流程就一起倒。

我真的看過這種事：一個 notebook 在某個工程師的帳號下跑得好好的，結果人一休假，整個 pipeline 就開始報錯。大家第一時間還以為是模型壞了，後來才發現只是 token 失效。這種問題最煩，因為它看起來像 AI 問題，實際上是權限設計太隨便。

我的實作原則很簡單：每個 automation boundary 都用自己的 service principal，dev 跟 prod 分開，shared tool 不要偷接 workspace user token。這不是什麼高級技巧，純粹是把之後會爆的事先拆掉。你如果現在覺得麻煩，通常代表你已經在替未來省事了。

文件還補了一句，OpenAI client、REST API、MLflow Deployments SDK 都需要 Databricks API token。這種細節很容易被掃過去，然後你會在 client 還沒碰到 model 前就先撞 auth error。別笑，我真的看過。

你選的套件，取決於 runtime，不取決於感覺

To use the OpenAI client, the databricks-openai package needs to be installed on your cluster.

這句話的意思很直接：不要預設叢集裡已經有你要的 client library。想走 OpenAI 相容路徑，就要裝 databricks-openai。想走 serving REST 路徑，文件會把你導向 MLflow Deployments SDK。而且它也提醒你，Databricks Runtime for Machine Learning 才有 Serving REST API 這條路可以直接用。

另外，Databricks SDK for Python 在 Databricks Runtime 13.3 LTS 以上的 cluster 通常已經內建；如果你還在 12.2 LTS 或更舊版本，就得自己裝。這種 runtime 差異最容易騙人，因為看起來像程式碼壞掉，實際上只是環境版本不對。

我現在只要碰到 model serving，就會先檢查三件事：runtime、package availability、auth path。因為我已經被太多次「模型沒回應」的工單教育過了，最後十之八九都不是模型本身，而是 cluster 沒有那個套件，或版本太舊，或 token 用錯。

實操上，我會把最低支援版本寫進內部文件，然後把 install 指令放在範例旁邊，不要分散到別的頁面。若是 notebook 工作流，就把依賴寫在最前面；若是 job，就把依賴包進環境。你越早把這些東西固定住，後面越少人來問「為什麼我這邊可以，你那邊不行」。

• OpenAI 風格呼叫用 databricks-openai。
• 想要 Databricks 友善包裝就看 MLflow Deployments SDK。
• 先確認 runtime，再假設 SDK 存在。

先看任務類型，再決定模型名字

The following table summarizes the supported foundation models based on task type.

這句話的重點很樸素：Databricks 要你先按工作類型選模型，不是先背一串模型名。這比把整份 model list 丟給你猜要合理多了，因為大部分人其實不是在找「最強」模型，而是在找「最適合這個任務」的模型。

如果是 general-purpose chat，文件列了不少 Databricks-hosted 模型，像 databricks-gpt-5、databricks-gpt-5-mini、databricks-gemini-3、databricks-claude-sonnet、databricks-qwen35 這些家族都有出現。外部模型則包含 OpenAI GPT 與 o 系列、Anthropic Claude、Google Gemini。若是 embeddings，可選的範圍就窄很多。vision 和 reasoning 也各自有對應的支援集合。

這種分類我很喜歡，因為它逼你先想工作需求，再想模型。很多人一上來就挑名字看起來最猛的那個，然後硬拿去做不適合的事。你不需要一個超大 reasoning 模型去做簡單分類；你也不需要 vision 能力去做純文字 embedding。模型選錯，後面所有調校都只是補洞。

我自己的習慣是先定 task type，再縮小到最小可行模型。聊天就用 general-purpose；語意搜尋、RAG、聚類就用 embeddings；圖片或文件理解就挑 vision；多步推理或結構化分析才看 reasoning。這樣比從品牌名或模型大小開始挑，少很多瞎忙。

文件還提到 Meta-Llama-3.1-405B-Instruct 會退役，並且有 pay-per-token 和 provisioned throughput 的日期。這種資訊不要靠記憶，直接寫進 migration note。模型名不要散在程式碼裡，放 config 比較安全，不然你哪天看到退役公告，整個 repo 會一起開始冒煙。

Unity AI Gateway 不是裝飾，是你該先開的閘門

Requests to foundation models, both Databricks-hosted and external, are routed through Unity AI Gateway (Beta), which lets you apply rate limits, budgets, and guardrails.

翻譯一下就是，Databricks 把模型請求先經過一層治理閘門，讓你能做 rate limit、budget、guardrails。這件事我很在意，因為太多團隊都是等帳單爆了才想起來要控成本。等到 prompt loop、錯誤重試、或某個實驗性功能開始狂打模型時，才發現沒有共享規則，真的會很痛。

而且這個 gateway 同時管 Databricks-hosted 和 external models，意思是你不用每接一個供應商就重做一次政策。這對平台團隊來說很實用，因為你可以把模型存取當成一個內部服務來治理，而不是每個應用自己亂接。

我以前處理過一種很典型的爛攤子：每個 team 都直接打 model provider，完全沒有共用的成本限制。前期看起來很自由，後期就會變成誰也不知道哪個 endpoint 在燒錢。Databricks 把這層控制提前放出來，我反而覺得這是整份文件裡最像正經平台設計的地方。

實操上，我會先定義哪些 endpoint 是實驗用、哪些是內部用、哪些是 production-critical，再把 budgets 和 rate limits 放上去。若是要開給分析師或應用團隊使用，guardrails 也要一起上。你不先管，後面再補通常都很醜，而且一定是用事故在提醒你。

誰在用，決定你該給他哪個入口

Serving UI Select Query endpoint from the Serving endpoint page. Insert JSON format model input data and click Send Request.

這句話其實很貼近現場：同一個模型，不同的人要的入口完全不同。工程師要的是可重複、可版本化的呼叫；分析師或 PM 要的是能快速看結果的介面。Databricks 這頁把 Serving UI 也列進來，我反而覺得很務實，因為不是每個人都需要直接寫 code 才能驗證 endpoint。

Serving UI 的價值不在於拿來做正式產品，而是在你要確認 endpoint 活著、輸入 schema 對不對、回傳格式長什麼樣的時候，真的很好用。文件還提到，如果 model 有 logged input example，你可以直接用 Show Example 載入。這種小功能很不起眼，但在 debug 時真的能少掉不少猜測。

我的建議是，把 UI 當成檢查入口，把 SDK 當成整合入口，把 REST 當成通用底層。不要逼所有人都走同一條路，因為不同角色本來就不該用同一種工具。你要的是一致的結果，不是大家都得在同一個畫面裡按同一個按鈕。

如果你要做內部平台，我會直接把這個分層寫進 onboarding 文件：誰可以用 UI 試、誰可以用 notebook 跑、誰可以把 endpoint 接進 production。這樣至少不會有人把試驗流程誤當正式流程，然後在上線時才發現自己連 auth 都沒設好。

可抄的模板

# Databricks foundation model 查詢作業模板（繁中版，可直接改成內部文件或 README）

## 1. 先判斷任務類型
- 對話 / 文案 / 摘要
- embeddings / 搜尋 / RAG
- 圖片 / 文件理解
- 多步推理 / 結構化分析

## 2. 再選查詢入口
- OpenAI client：給熟 OpenAI 風格的工程師
- Databricks Python SDK：給 Databricks 原生工作流
- MLflow Deployments SDK：給 model serving 整合
- REST API：給跨語言、跨平台整合
- AI Functions：給 SQL 推論
- Serving UI：給人工檢查與除錯

## 3. 先確認環境
- Databricks Runtime 版本
- cluster 是否已安裝必要套件
- endpoint 是否存在
- workspace 是否支援該服務
- token / OAuth 是否符合環境

## 4. 安裝依賴
# OpenAI 相容路徑
pip install -U databricks-openai

# Databricks SDK
pip install databricks-sdk

# MLflow Deployments SDK
pip install mlflow

## 5. 認證規則
- production：machine-to-machine OAuth
- dev / test：service principal 的 token
- 不要用個人 workspace token 跑共享流程

## 6. OpenAI 風格呼叫範例
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["DATABRICKS_TOKEN"],
    base_url="https:///serving-endpoints"
)

response = client.chat.completions.create(
    model="",
    messages=[
        {"role": "system", "content": "你是協助整理需求的助理。"},
        {"role": "user", "content": "請把這張工單摘要成三點。"}
    ]
)

print(response.choices[0].message.content)

## 7. REST 呼叫範例
POST /api/2.0/serving-endpoints//invocations
Content-Type: application/json
Authorization: Bearer 

{
  "messages": [
    {"role": "user", "content": "請用三句話解釋這段錯誤訊息"}
  ]
}

## 8. SQL 推論範例
SELECT ai_query(
  '',
  '請把這段客服訊息分類成：帳務、錯誤、功能需求。'
);

## 9. 模型選擇原則
- chat：general-purpose
- embeddings：搜尋、聚類、RAG
- vision：圖片、文件
- reasoning：多步推理

## 10. 維運清單
- endpoint 名稱放 config，不要散在程式碼裡
- 模型退役日期要寫進 migration note
- budgets、rate limits、guardrails 要先設
- package 與 runtime 要一起檢查
- 認證方式要和環境分開管理

## 11. 團隊約定
- notebook 用來驗證
- SDK 用來整合
- REST 用來保底
- UI 用來檢查
- 先選任務，再選模型，再選入口

如果我現在要把這份文件直接變成團隊內部 playbook，我會幾乎原封不動貼上這段，然後把 workspace host、endpoint 名稱、允許的認證方式換成自己的版本。這段最重要的不是 code 長相，而是決策順序：先看任務，再看入口，然後才是 auth、套件、request。

我自己很吃這種順序，因為它會逼大家先把最容易出錯的東西講清楚。你只要把這些前置條件寫在一起，後面真的少很多溝通成本。文件原始來源是 Databricks 官方說明；我這篇的拆解、排序跟模板是我自己整理出來的，拿去改成你們團隊能用的版本就好。