🔹 前言

昨天我們談到 Cache 與回應加速，解決了「同一問題反覆查詢」造成的延遲與成本浪費。
但 LLM 應用還有另一個大挑戰：

👉 模型與知識庫版本要怎麼管理？

在 Day 13 我們談過「知識會過期」的問題：當文件內容更新時，需要偵測 Data Drift 並重建知識庫。而今天我們會談談 LLM 與知識庫（Knowledge Base / Index）要如何安全地做版本切換：

• 供應商會持續更新模型 API（例如 GPT-4o → GPT-4.1 → GPT-5）。
• 我們自己的 知識庫（Knowledge Base / Index） 也需要隨文件與流程更新而重建。

因此，我們需要一個 Registry，讓系統能清楚知道「現在線上用的是哪個版本」，並支援 升級、灰度、回滾、稽核追蹤。

⚠️ 註：在本文中，「模型」泛指外部 LLM API 版本與知識庫版本。
在多數企業場景中，知識庫（KB）更新的頻率通常高於 LLM API 版本切換；
但對於「靜態知識庫、偏追最新模型」的場景，情況未必成立。

🔹 真實案例：模型更新與回滾風險

[註] 以社群貼文為主、並非官方聲明

👉 這些案例清楚顯示：就算模型來自外部 API，沒有完善的版本管理，升級也可能帶來風險。

🔹 為什麼需要 Registry？

補充：Registry 的資料結構（API 模型場景）

一個簡單的自建登錄表，可以包含：

常見的 Registry 工具

[註1] 定位：實驗追蹤＋模型管理。2024 年後官方逐步強化 Model Registry 與版本治理能力；若要唯一 Production／審批流，仍常見自訂擴充。
[註2] 雖與 SageMaker 訓練整合佳，亦可從外部來源（如 S3）註冊模型，不必限制於 SageMaker 訓練作業。

Registry 工具選型表

🔹 Demo：自建的簡單 Model Registry（API 模型場景）

⚠️ 本文 Demo 的重點在於「Registry 管理流程」，
不包含實際模型推理或知識庫檢索，只模擬登錄與狀態管理。

因為篇幅關係，完整可執行專案一樣會放在 GitHub，完整的細節請看 README.md。

以下用一個 faq-bot 模型走完：註冊 ➜ 上線 v1 ➜ 建立 v1.1 金絲雀 ➜ Promote/Rollback ➜ 封存 ➜ 稽核查驗，所有操作都透過 REST API 完成，並且能用 API 管理模型清單，例如：

• 註冊新版本
• 列出所有版本
• 將某個版本標記為 Production

架構示意圖

• 開發者透過 Registry API 註冊 / 更新模型資訊
• API Gateway 根據 Registry 設定，決定要呼叫哪個模型版本
• 用戶則不需要知道後端細節

模型的資訊 Demo 會存在 SQLite，正式上線時請參考後面的資料庫比較表選型

Demo 狀態圖

1) 註冊模型

curl -sX POST localhost:8000/models -H 'Content-Type: application/json' \   -d '{"name":"faq-bot","owner":"hazel","description":"Q&A bot"}' | jq

重點：相同模型只需註冊一次，之後所有版本都掛在這個模型底下。

執行結果：

❯ curl -sX POST localhost:8000/models -H 'Content-Type: application/json' \   -d '{"name":"faq-bot","owner":"hazel","description":"Q&A bot"}' | jq

{
  "id": 1,
  "name": "faq-bot",
  "owner": "hazel",
  "description": "Q&A bot",
  "created_at": "2025-09-14T07:04:35.965212"
}

2) 建立 v1.0.0（預設 None）並逐步上線

階段流轉規則：None → Staging → Production → Archived
直接跳階（例如 None → Production）會被拒絕。

# 建立 v1.0.0（stage 預設 "None"）
curl -sX POST localhost:8000/models/faq-bot/versions -H 'Content-Type: application/json' \
  -d '{"version":"1.0.0","artifact_url":"s3://bucket/faq-bot/1.0.0","tags":["baseline"],"meta":{"commit":"a1b2c3"}}' | jq

# None → Staging
curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Staging","actor":"hazel"}' | jq

# Staging → Production（正式上線）
curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production","actor":"hazel"}' | jq

執行結果：

# 建立 v1.0.0（stage 預設 "None"）
❯ curl -sX POST localhost:8000/models/faq-bot/versions -H 'Content-Type: application/json' \
  -d '{"version":"1.0.0","artifact_url":"s3://bucket/faq-bot/1.0.0","tags":["baseline"],"meta":{"commit":"a1b2c3"}}' | jq
{
  "id": 1,
  "version": "1.0.0",
  "stage": "None", # 預設 "None"
  "artifact_url": "s3://bucket/faq-bot/1.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c3"
  },
  "created_at": "2025-09-14T07:05:08.323930",
  "updated_at": "2025-09-14T07:05:08.323934"
}

# None → Staging
❯ curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Staging","actor":"hazel"}' | jq
{
  "id": 1,
  "version": "1.0.0",
  "stage": "Staging",
  "artifact_url": "s3://bucket/faq-bot/1.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c3"
  },
  "created_at": "2025-09-14T07:05:08.323930",
  "updated_at": "2025-09-14T07:06:11.279993"
}

#  Staging → Production（正式上線）
❯ curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production","actor":"hazel"}' | jq
{
  "id": 1,
  "version": "1.0.0",
  "stage": "Production",
  "artifact_url": "s3://bucket/faq-bot/1.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c3"
  },
  "created_at": "2025-09-14T07:05:08.323930",
  "updated_at": "2025-09-14T07:06:37.803683"
}

3) 建立 v1.1.0 作為「金絲雀」並上 Staging（A/B 準備）

A/B 只在 metadata 與 tags 內登記，不做流量實作；這樣最精簡、也便於延伸。

# 建立 v1.1.0（預設 None）
curl -sX POST localhost:8000/models/faq-bot/versions -H 'Content-Type: application/json' \
  -d '{"version":"1.1.0","artifact_url":"s3://bucket/faq-bot/1.1.0","tags":["canary"],"meta":{"commit":"d4e5f6","traffic_share":20}}' | jq

# None → Staging（開始 A/B）
curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Staging","actor":"hazel"}' | jq

4)（可選）Promote v1.1.0 到 Production（唯一性規則會自動降級）

唯一 Production 規則：同一模型同時間只能有一個 Production。
當 v1.1.0 Promote 至 Production，v1.0.0 會被自動降級為 Staging。

curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production","actor":"hazel"}' | jq

執行結果：

# 把 v1.1.0 升級到 production
❯ curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production","actor":"hazel"}' | jq
{
  "id": 2,
  "version": "1.1.0",
  "stage": "Production",
  "artifact_url": "s3://bucket/faq-bot/1.1.0",
  "tags": [
    "canary"
  ],
  "meta": {
    "commit": "d4e5f6",
    "traffic_share": 20
  },
  "created_at": "2025-09-14T07:07:27.098726",
  "updated_at": "2025-09-14T07:08:30.322485"
}

# 可以看到 v1.0.0 被降級回 staging
❯ curl -s localhost:8000/models/faq-bot/versions | jq 'map({version,stage})'

[
  {
    "version": "1.0.0",
    "stage": "Staging"
  },
  {
    "version": "1.1.0",
    "stage": "Production"
  }
]

5) 回滾：把 v1.0.0 設回 Production（含 rollback_to 審計旗標）

rollback_to 是審計用旗標，不改變邏輯；真正回滾就是把目標版本 Promote 成 Production。

curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' \
  -d '{"to_stage":"Production","actor":"hazel","rollback_to":true}' | jq

效果：

• v1.0.0 → Production
• v1.1.0 → 自動降回 Staging
• /audit 會多一筆 detail.rollback_to=true 的 transition 記錄

執行結果：

# 把 v1.0.0 重新推到 production
❯ curl -sX POST localhost:8000/models/faq-bot/versions/1.0.0/transition \
  -H 'Content-Type: application/json' \
  -d '{"to_stage":"Production","actor":"hazel","rollback_to":true}' | jq
{
  "id": 1,
  "version": "1.0.0",
  "stage": "Production",
  "artifact_url": "s3://bucket/faq-bot/1.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c3"
  },
  "created_at": "2025-09-14T07:05:08.323930",
  "updated_at": "2025-09-14T07:10:12.279054"
}

# 驗證 v1.1.0 回到 staging
❯ curl -s localhost:8000/models/faq-bot/versions | jq 'map({version,stage})'

[
  {
    "version": "1.0.0",
    "stage": "Production"
  },
  {
    "version": "1.1.0",
    "stage": "Staging"
  }
]

# 查看 audit logs
❯ curl -s localhost:8000/audit | jq
[
  ...,
  ...,
  {
    "id": 8,
    "model_name": "faq-bot",
    "version": "1.0.0",
    "action": "transition",
    "actor": "hazel",
    "from_stage": "Staging",
    "to_stage": "Production",
    "detail": {
      "rollback_to": true             # <--- 可以看到 rollback_to = true
    },
    "created_at": "2025-09-14T07:10:12.278070"
  }
]

6) 封存 v1.1.0

curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \   -H 'Content-Type: application/json' -d '{"to_stage":"Archived","actor":"hazel"}' | jq

注意：Archived 後的模型不能再 Promote。

執行結果：

❯ curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \   -H 'Content-Type: application/json' -d '{"to_stage":"Archived","actor":"hazel"}' | jq
{
  "id": 2,
  "version": "1.1.0",
  "stage": "Archived",
  "artifact_url": "s3://bucket/faq-bot/1.1.0",
  "tags": [
    "canary"
  ],
  "meta": {
    "commit": "d4e5f6",
    "traffic_share": 20
  },
  "created_at": "2025-09-14T07:07:27.098726",
  "updated_at": "2025-09-14T07:12:57.089496"
}

# 想要將被 archived 的模型直接升級到 Production 環境會被拒絕。
❯  curl -sX POST localhost:8000/models/faq-bot/versions/1.1.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production","actor":"hazel"}' | jq
{
  "detail": "Illegal transition Archived → Production"
}

7) 查詢與稽核驗證

# 查目前 Production（應為 v1.0.0）
curl -s localhost:8000/models/faq-bot/production | jq

# 列所有版本與狀態
curl -s localhost:8000/models/faq-bot/versions | jq 'map({version,stage,tags,meta})'

# 篩出「回滾」transition（detail.rollback_to = true）
curl -s localhost:8000/audit | \
jq 'map(select(.action=="transition" and (.detail.rollback_to==true)) |
       {version, from_stage, to_stage, detail})'

執行結果：

# 查目前 Production（應為 v1.0.0）
❯ curl -s localhost:8000/models/faq-bot/production | jq
{
  "id": 1,
  "version": "1.0.0",
  "stage": "Production",
  "artifact_url": "s3://bucket/faq-bot/1.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c3"
  },
  "created_at": "2025-09-14T07:05:08.323930",
  "updated_at": "2025-09-14T07:10:12.279054"
}

# 列所有版本與狀態
❯ curl -s localhost:8000/models/faq-bot/versions | jq 'map({version,stage,tags,meta})'
[
  {
    "version": "1.0.0",
    "stage": "Production",
    "tags": [
      "baseline"
    ],
    "meta": {
      "commit": "a1b2c3"
    }
  },
  {
    "version": "1.1.0",
    "stage": "Archived",
    "tags": [
      "canary"
    ],
    "meta": {
      "commit": "d4e5f6",
      "traffic_share": 20
    }
  }
]

❯ # 篩出「回滾」transition（detail.rollback_to = true）
curl -s localhost:8000/audit | \
jq 'map(select(.action=="transition" and (.detail.rollback_to==true)) |
       {version, from_stage, to_stage, detail})'
[
  {
    "version": "1.0.0",
    "from_stage": "Staging",
    "to_stage": "Production",
    "detail": {
      "rollback_to": true
    }
  }
]

8)（延伸）錯誤防護與邊界行為

# 跳階：None → Production（應被拒）
curl -sX POST localhost:8000/models/faq-bot/versions/2.0.0 -H 'Content-Type: application/json' \
  -d '{"version":"2.0.0"}' | jq
  
curl -sX POST localhost:8000/models/faq-bot/versions/2.0.0/transition \
  -H 'Content-Type: application/json' -d '{"to_stage":"Production"}' | jq

執行結果：

# 先建立 v2.0.0 模型
❯ curl -sX POST localhost:8000/models/faq-bot/versions -H 'Content-Type: application/json' \
  -d '{"version":"2.0.0","artifact_url":"s3://bucket/faq-bot/2.0.0","tags":["baseline"],"meta":{"commit":"a1b2c4"}}' | jq
{
  "id": 3,
  "version": "2.0.0",
  "stage": "None",
  "artifact_url": "s3://bucket/faq-bot/2.0.0",
  "tags": [
    "baseline"
  ],
  "meta": {
    "commit": "a1b2c4"
  },
  "created_at": "2025-09-14T07:18:12.723062",
  "updated_at": "2025-09-14T07:18:12.723065"
}

# 想要從 None 直接推到 Production 會被拒絕
❯ curl -sX POST localhost:8000/models/faq-bot/versions/2.0.0/transition \
  -H 'Content-Type: application/json' \
  -d '{"to_stage":"Production","actor":"hazel"}' | jq
{
  "detail": "Illegal transition None → Production"
}

以上就是最小可跑的 Model Registry 操作流程演示。

💡 想更符合真實模型上限的場景的話，可以將 線上 KPI（如 eval_f1, latency_p95_ms, traffic_share）寫入 meta，在 Promote 模型之前做 Stage Gate 自動檢查；或把唯一性從「自動降級」改成「嚴格禁止，需要人工降級」以符合更嚴謹的治理流程。

🔹 我會需要 Registry 特別需要關聯式資料庫 (Relational Database) 嗎？

在多模型、多團隊、需嚴格治理與審計的情境成立。
小團隊或低流量可考慮 Git＋YAML 作為輕量 Registry；單一模型、簡單路由亦可用 DynamoDB 等 KV/NoSQL（搭配條件寫入與 TransactWriteItems）滿足需求。隨規模與治理需求再演進至 RDB。

• 交易與一致性（ACID）：確保 Promote / Rollback 不出錯

  • Registry 最怕「兩個版本同時是 Production」。
  • 關聯式資料庫的交易保證，可以讓「降級舊 Prod → 升級新 Prod → 寫 Audit」這些步驟要嘛一起成功，要嘛一起失敗。

• 資料約束（Constraints） ：把規則寫死在 DB 層

  • 一個模型只能有一個 Production 版本。
  • 每個版本號必須唯一。
  • Stage 值只能在固定集合裡。
  • 這些規則直接靠 DB 來保護，即使應用程式程式碼有 bug，也不會破壞 Registry。

• 複雜查詢（Query Flexibility）：找到正確的候選版本

  • 例如：「找出 2025Q1 訓練，F1 > 0.85 的 canary 版本」。
  • 沒有強大的 SQL 查詢，這些需求會變得很痛苦。
  • RDB 的 JOIN、CTE、Window Function 可以輕鬆支援。

• 稽核與追蹤（Auditability）：回答「誰在什麼時候上線了什麼」

  • Audit log 在事故調查、法規合規（如金融/醫療）時非常重要。
  • 關聯式資料庫的索引與查詢讓這些查詢即時可得。

• 遷移與治理（Schema Evolution）：讓 Registry 可持續演進

  • 今天只有基本欄位（name, version, stage），明天可能要加上「實驗指標」、「部署環境」 等欄位。
  • RDB 的 schema migration 工具（Alembic, Liquibase）能安全地擴充結構，讓系統跟著需求長大。

關聯式資料庫能提供 強一致性、嚴格約束、靈活查詢、審計能力與持續演進，這些正是 Registry 管理的核心需求。

🔹 在實際的產線環境我可以選擇其他資料庫嗎？

[註1] 這欄「JSON / Tags 查詢」之所以重要，是因為模型登記常要靠可變的中繼資料 (Metadata)與語義標籤來做日常營運決策與治理，像是：
零 schema 變更地記錄指標與脈絡：eval_f1、dataset_sha、traffic_share、framework、commit、region…實驗不斷增加欄位，用 JSON 最彈性。
快速篩選/路由：找出 task=faq 且 tag=canary 且 f1>0.88 的版本，用於上線、回滾或灰度放量。
治理與稽核：標記 approved, owner, risk_level，用標籤與 JSON 查詢切出合規清單與審計報表。
可發現性：跨團隊用關鍵字/標籤搜尋，減少口耳相傳與維運盲點。

[註2] MySQL 8.0.13+ 可用 Functional/Generated Index 模擬 Partial Unique。做法：建立產生欄位或函數索引，僅在 stage='Production' 時產生非空值，配 UNIQUE 約束達成「每模型僅一個 Production」。
[註3]一致性/交易：有限事務支援（TransactWriteItems，最多 25 項）；非完整 ACID（無 RDB 等級的隔離級別如 READ COMMITTED）

🔹 常見疑惑解答

Q：我們不自己訓練模型，還需要 Registry 嗎？
A：需要，但重點會放在知識庫 / 索引版本。Registry 幫你把「LLM 選型 + 知識庫版本」當作可觀測、可回滾的單位；多數回滾都只需切換知識庫的版本。

Q：model_version 和 kb_version 要怎麼搭配？
A：常見做法是固定 model_version（外部 API），用 kb_version 做金絲雀與回滾；遇到供應商大更新才動 model_version。

🔹 小結

今天我們把焦點放在 模型版本與週期管理 (含知識庫版本管理)。
它的角色，就像「LLM 與知識庫的版本控制中心」：確保任何時候，線上跑的都是唯一可控的組合（模型 API + 知識庫版本），並且所有升級、回滾都有紀錄可查：

我們談到：

• 為什麼需要 Registry：避免版本混亂，支援快速回滾，讓團隊能協作治理。
• 真實案例：即使是 OpenAI、Anthropic 這樣的供應商，也曾因更新品質問題而被迫回滾。
• 最小實作：用 FastAPI + SQLite 建立簡單的 API Registry，示範註冊、Promote、Archive 等基本操作。
• 工程延伸：在實務上，Registry 特別需要 關聯式資料庫 來保證交易一致性、唯一 Production 約束、以及可追溯的稽核能力。

有了 Registry，我們就能同時管理 外部模型版本 與 知識庫版本，並且確保系統在演進的過程中 更新有紀錄、問題能回滾、團隊能協作。這是企業級 LLM 應用走向成熟的必備基礎建設。

👉 明天（Day 23），我們會進一步探討 重新訓練與持續學習 (Retraining & Continual Learning) ：如何讓模型隨著資料更新而持續進步。

📚 引用來源

1. The Verge – OpenAI says its GPT-4o update could be ‘uncomfortable, unsettling, and cause distress’
2. PCWorld – OpenAI makes GPT-5 ‘friendlier’ after widespread user backlash
3. Reddit – Update on recent performance concerns (Claude Opus 4 / 4.1)
4. LLM Rollout Strategy and Risk Mitigation
5. Building enterprise knowledge bases with LLMs: architecture considerations for Vanilla RAG, GraphRAG, and agentic RAG
6. Our Guide to an LLM Knowledge Base - Findings from R&D
7. MLflow Model Registry
8. MLflow Data Versioning: Techniques, Tools & Best Practices
9. AWS 官方的 ML 部署策略最佳實踐，包含 SageMaker 的實作範例
10. Modern rollback strategies
11. Modern Deployment Rollback Techniques for 2025