【MLflow LLMs & Agents 實戰】系列 #03（共 4 篇）｜難度：L3-熟練
前置：本系列 #01（Tracing）、#02（評估）＋ 基本 Python

一句話說明

Prompt Registry 就是「提示詞的 Git」——把你餵給 LLM 的那段 prompt 從程式碼裡拉出來，變成一個有版本號、有 commit message、有 production / staging 標籤的東西，讓你隨時能回答：「這個爛輸出，到底是哪一版 prompt 產生的？」

如果你的 AI 助手把 prompt 直接用一大坨字串硬塞在程式碼中間（hardcode），那每次改字、比較效果、回滾，全都要靠翻 git log 猜——這正是 Prompt Registry 要解決的痛點。

為什麼 prompt 需要版本控制？

先講清楚問題，你才知道這篇在救什麼。

在 LLM 應用裡，prompt 就是你的核心邏輯。改一句「請用條列式回答」可能讓輸出品質天差地遠。但 prompt 常見的下場是：

# 🚩 典型的「prompt 埋在程式碼裡」寫法
def summarize(article: str) -> str:
    prompt = f"你是專業編輯，請把以下文章縮成三點重點：\n{article}"
    return call_llm(prompt)
Code language: PHP (php)

這樣寫，會遇到三個問題：

1. 無法回溯：上週輸出品質好，這週變差，是誰改了 prompt？改了什麼？沒人說得準。
2. 無法比較：想 A/B 測兩個版本的 prompt，得同時維護兩份程式碼。
3. 無法安全回滾：發現新 prompt 有問題，想退回舊版，只能翻 git 硬找。

Prompt Registry 把 prompt 變成受管控的資產：每次改動都有版本號、可以打標籤、可以搭配 #02 的評估分數一起看，形成「改 → 評估 → 比較 → 上線」的閉環。

四個必懂的名詞（先認得，再看 code）

讀 Prompt Registry 的程式碼前，先把這四個詞對上白話，後面 code 就好懂了：

✅ 必看懂：template（範本）、version（版本號）、alias（別名標籤）——這三個是每天都會碰的。 📌 知道就好：commit message，遇到再填。

關鍵直覺：version 是不可變的（註冊了就固定住），alias 是可移動的（今天指向 v3，明天可以改指 v5）。程式碼裡「用哪一版」通常是透過 alias 取用，而不是寫死版本號。

最小範例：註冊一個 prompt

import mlflow

prompt = mlflow.genai.register_prompt(
    name="article-summarizer",
    template="你是專業編輯，請把以下文章縮成三點重點：\n\n{{ article }}",
    commit_message="初版：三點重點摘要",
)

print(prompt.name)     # article-summarizer
print(prompt.version)  # 1
Code language: PHP (php)

這在幹嘛：把一段 prompt 範本存進 MLflow，取名叫 article-summarizer。MLflow 自動給它版本號 1。

逐行翻譯：

prompt = mlflow.genai.register_prompt(   # 註冊一個 prompt 到 registry
    name="article-summarizer",           # 這個 prompt 的名字（像檔名）
    template="...{{ article }}",          # 範本本體，{{ article }} 是待填變數
    commit_message="初版：三點重點摘要",   # 這次改動的說明（像 git commit）
)
Code language: PHP (php)

注意 template 裡的 {{ article }}——雙大括號包起來的是「變數插槽」，代表「這裡之後會填東西進去」。這是 MLflow prompt 用的變數語法（跟 Python f-string 的單大括號 {article} 不一樣，別搞混）。

載入並填入變數

註冊只是存起來，真正用的時候要載入 + 填變數：

# 載入最新版
prompt = mlflow.genai.load_prompt("prompts:/article-summarizer/1")

# 把變數填進去，變成真正要送給 LLM 的字串
final_prompt = prompt.format(article="MLflow 是一個開源的 ML 生命週期平台……")

print(final_prompt)
# 你是專業編輯，請把以下文章縮成三點重點：
#
# MLflow 是一個開源的 ML 生命週期平台……
Code language: PHP (php)

這在幹嘛：load_prompt 把第 1 版拉出來，.format(...) 把 {{ article }} 換成真實內容，產出最終要餵給 LLM 的完整字串。

那串 "prompts:/article-summarizer/1" 是 MLflow 的 URI（統一資源位址），拆開看：

prompts:/article-summarizer/1
   │            │           │
   協定        prompt 名    版本 or alias
Code language: JavaScript (javascript)

✅ 必看懂：prompts:/名字/版本 這個格式。最後那格可以是版本號（/1），也可以是 alias（/production）——這是重點，下一段講。

用 alias 取用版本（重點！）

直接在程式碼寫死 /1、/2 很脆弱——每次上線新版都得改 code 再部署。正解是用 alias：

# 把 production 這個標籤貼到第 3 版
mlflow.genai.set_prompt_alias(
    name="article-summarizer",
    alias="production",
    version=3,
)

# 應用程式裡永遠這樣載入，不寫死版本號
prompt = mlflow.genai.load_prompt("prompts:/article-summarizer@production")
Code language: PHP (php)

這在幹嘛：先把 production 標籤貼到第 3 版；之後應用程式只認 @production，完全不知道底下是第幾版。

注意 URI 的差別：

• prompts:/名字/3 → 用版本號（斜線 /）
• prompts:/名字@production → 用alias（小老鼠 @）

好處：想上線新版 prompt，只要把 production alias 移到新版本，應用程式一行 code 都不用改、不用重新部署。想回滾？把 alias 移回舊版就好。這就是為什麼「用 alias 取用」是最佳實務。

常見 alias 慣例：production（正式上線）、staging（測試中）、champion / challenger（A/B 對照）。

把 prompt 版本綁到 trace / run

這是 Prompt Registry 真正發威的地方，也是接續 #01 Tracing 的關鍵：當你載入的 prompt 被用來呼叫 LLM，MLflow 會自動把「用了哪一版 prompt」記進 trace。

import mlflow

mlflow.openai.autolog()  # 開啟自動追蹤（見 #01）

prompt = mlflow.genai.load_prompt("prompts:/article-summarizer@production")

# 這次呼叫的 trace 會自動關聯到 production 指向的那個版本
response = call_llm(prompt.format(article="……"))
Code language: PHP (php)

這在幹嘛：因為 prompt 是從 registry 載入的，MLflow 知道它的身分，會在這次呼叫的 trace 上標記「本次使用 article-summarizer v3」。

於是你就能回答那個致命問題：「這個奇怪的輸出，是哪一版 prompt 產生的？」 打開 MLflow UI 的那條 trace，版本號寫在上面。不用再猜。

完整迭代工作流：改 → 評估 → 比較 → 升 alias

把 #02（評估）和本篇串起來，一個健康的 prompt 迭代長這樣：

# 1. 改 prompt，註冊成新版本（不覆蓋舊的，version 自動變 4）
new_prompt = mlflow.genai.register_prompt(
    name="article-summarizer",
    template="你是專業編輯，請用繁體中文把文章縮成三點，每點不超過 20 字：\n\n{{ article }}",
    commit_message="限制每點字數，避免冗長",
)

# 2. 對新版本跑評估（見 #02），拿到分數
results = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=lambda article: call_llm(new_prompt.format(article=article)),
    scorers=[relevance_scorer, conciseness_scorer],
)

# 3. 比較 v3（現任 production）vs v4 的評估分數
#    → 在 MLflow UI 並排看兩個 run 的指標

# 4. 新版更好，才把 production alias 升上去
mlflow.genai.set_prompt_alias(
    name="article-summarizer",
    alias="production",
    version=4,
)
Code language: PHP (php)

整個流程的價值：每一版 prompt 都有版本號、有 commit message、有對應的評估分數，升上 production 是「數據支持的決定」而不是「感覺新的比較好」。要回滾也只是把 alias 移回 v3 的一行事。

🚩 紅旗：看到這些要警覺

AI 幫你寫 LLM 應用時，很容易生出這些「看起來能跑、其實埋雷」的寫法：

紅旗 1：prompt 硬編碼在程式碼裡

prompt = "你是專業編輯，請把文章縮成三點：" + article  # 🚩 沒進 registry
Code language: PHP (php)

沒版本、沒法回溯、沒法評估比較。看到成串 prompt 字串直接埋在函式裡，就該問 AI 能不能改用 Prompt Registry 管理。

紅旗 2：應用程式寫死版本號

prompt = mlflow.genai.load_prompt("prompts:/summarizer/7")  # 🚩 寫死 /7
Code language: PHP (php)

每次上線都要改 code 重部署，還容易忘。正解是用 @production alias。

紅旗 3：改 prompt 直接覆蓋，沒留舊版 如果 AI 的作法是「把 template 字串改掉就好」而沒有 register_prompt 註冊成新版本，那舊版就消失了，出事無法回滾。每次改動都該是新版本，而不是就地覆蓋。

紅旗 4：升 production 前沒跑評估

# 🚩 改完 prompt 直接把 production 指過去，沒經過評估
mlflow.genai.set_prompt_alias(name="summarizer", alias="production", version=9)
Code language: PHP (php)

沒有 #02 的評估數據就升上線，等於用正式流量當白老鼠。升 alias 前應該先有評估分數撐腰。

紅旗 5：搞混 {{ }} 和 f-string 的 { }

template = f"請摘要：{{ article }}"  # 🚩 混用，容易出錯
Code language: PHP (php)

MLflow prompt 變數用雙大括號 {{ article }} 且不要加 f-string 前綴 f——加了 f 會被 Python 先處理掉。範本就是普通字串，變數留給 .format() 填。

Vibe Coder 驗收檢查點

拿到 AI 寫的 Prompt Registry 程式碼，這樣驗收：

1. 確認 prompt 有進 registry：搜尋程式碼裡有沒有 register_prompt。如果 prompt 只是普通字串變數，請 AI 改成註冊制。
2. 確認用 alias 而非寫死版本：載入語句應該長得像 @production，不該是 /7 這種硬版本號。可以問 AI：「這裡為什麼用寫死版本號而不是 alias？上線後要改版怎麼辦？」
3. 跑一次載入 + format，看輸出對不對：
4. 打開 MLflow UI 確認 trace 有標到版本：跑一次呼叫後，到 UI 找那條 trace，應該能看到關聯的 prompt 版本。看得到，才代表回溯能力真的接上了。
5. 確認迭代有評估撐腰：升 production alias 的那段程式碼前後，應該找得到 evaluate 的呼叫。沒有評估就升版，是紅旗 4。

看不懂就這樣問 AI

把程式碼貼給你的 AI 助手，直接問：

「這段用了 MLflow Prompt Registry，請一行一行用白話解釋，我是初學者。特別說明 register_prompt、load_prompt、set_prompt_alias 各自在幹嘛，還有 prompts:/名字@production 這個 URI 怎麼讀。」

想確認有沒有踩紅旗，問：

「這段 LLM 應用的 prompt 是硬編碼還是有進 Prompt Registry？載入時是用 alias 還是寫死版本號？升上 production 前有沒有先跑評估？有的話幫我指出哪幾行，沒有的話幫我補上。」

小結

• Prompt Registry = 提示詞的 Git：template（範本）、version（不可變版本號）、alias（可移動標籤）、commit message。
• 註冊用 register_prompt，載入用 load_prompt，變數用雙大括號 {{ }} 搭配 .format() 填。
• 應用程式用 alias（@production）取用，別寫死版本號——上線改版不用動 code。
• prompt 版本會綁進 trace，讓你能回答「這輸出是哪一版 prompt 產的」。
• 健康的迭代 = 改 → 評估（#02）→ 比較 → 升 alias，每步都有數據可回溯。
• 看到 prompt 硬編碼、寫死版本號、就地覆蓋、無評估升版——都是紅旗。

下一篇（#04）會把 Tracing、評估、Prompt Registry 這些拼圖組成一個完整的 LLM 應用觀測與迭代流程。