AI Phase 06 — AI Application Engineering(Day 51–60)

100-Day AI Knowledge Challenge

AI Phase 06 — AI Application Engineering(Day 51–60)

這 10 天是整條 AI 課程線裡最貼近 Backend 本行的一段:你已經會做 retry、timeout、串流、成本控管、輸入驗證,現在要把這些功夫套到「呼叫 LLM」這件事上。所以這個 Phase 不找「AI API 入門」課,而是直接讀兩家 provider 的官方文件,對照著回答一個問題:Provider abstraction 到底應該抽象什麼,又該刻意不抽象什麼?1

主教材是 OpenAI 與 Anthropic 的官方 API 文件,兩家對照著讀;搭配的是 Full Stack Deep Learning(FSDL),從 Problem → Model → Data → Deployment → Monitoring 看完整的 AI 系統,Day 58 集中讀2。總綱第 4 節的重疊對照表在這個 Phase 只列一項:tool calling 的 schema/execution/validation/failure/retry 已在 Backend Day 85 講過,所以 Day 55 只寫「兩家 wire format 的差異」這個新角度,不重寫執行與驗證3。

整個 Phase 圍繞同一個成品,一天加一塊:

Backend → Model abstraction → Provider A / Provider B / Local model

再加上 streaming、retry、timeout、fallback、token/cost tracking、structured output4。Day 51–57 每天寫一個小模組,Day 58 讀 FSDL 並寫下抽象層的設計取捨,Day 59 把模組組成 Router,Day 60 補測試並完成 Phase 驗收:multi-provider abstraction 跑得動(可切換 Provider A/B/Local model),並能說明抽象層刻意不抽象掉什麼、為什麼5。

環境與成本: 所有程式碼只用 Python 標準函式庫,教材作者以 Python 3.12 實跑過。Provider A、B 在 Day 51–59 都用「假的 provider」(程式裡預先寫好會成功或失敗的腳本)代替,所以不需要 API key、不會花錢;Local model 那條路用 Phase 05 的 Ollama 或 vLLM(見 Day 60)。如果你想接真的雲端 API,Day 60 有選做步驟,費用自負。

教材查證的範圍(請先看): 兩家 provider 的文件近期改過網址:OpenAI 文件從 platform.openai.com 轉到 developers.openai.com,Anthropic 文件從 docs.anthropic.com 轉到 platform.claude.com,下面的連結都用轉址後的網址。2026-10-16 與 2026-10-17 查證時,每一頁都實際開過,但只確認到「小節標題+該節重點」的層級,沒有逐字比對;OpenAI 的 Structured outputs 頁後 36,308 字元、Anthropic 的 Structured outputs 頁後 3,037 字元因頁面過長沒讀到。程式碼裡用到的 OpenAI 欄位名,2026-10-17 已對照官方頁面:streaming 的 delta 欄位(Day 52,Streaming 頁範例)、function tool 與 function_call_output 的形狀(Day 55,Function calling 頁)、usage 的輸入與快取欄位(Day 57,Prompt caching 頁)。唯一還沒在頁面上看到的是 OpenAI usage 的輸出 token 欄位名(Day 57),那是你在實作時要親自對一次的地方。

Day 51 — 兩家 API 的形狀:Responses API 與 Messages API

今天要回答的問題

同一句話送給 OpenAI 與 Anthropic,請求與回應各長什麼樣?哪些差異只是「形狀」(欄位名不同),哪些是「語意」(行為不同,不能靠改欄位名抹平)?

主教材(Core)

  • OpenAI 文件 — Migrate to the Responses API(About the Responses API、Responses benefits、Messages vs. Items 三節),預估 30 分鐘
  • Anthropic 文件 — Using the Messages API(Basic request and response、Multiple conversational turns 兩節),預估 25 分鐘
  • 實作,預估 45 分鐘

搭配(Companion,選讀)

  • OpenAI 文件 — Text generation(Message roles and instruction following 一節),對照兩家放「系統指示」的位置;預估 15 分鐘

讀的時候抓這幾個重點

  • 兩家的「一次輸出」不是同一種東西。 Migrate 頁說 Responses API 回傳的是一串有型別的 output Items,而 Chat Completions 回傳的是 choices 清單、每個 choice 裡一則 message。Anthropic 的回應則是一則 message,裡面有 content blocks 的清單(文字區塊、tool_use 區塊等)。兩邊都是「一串有型別的片段」,但片段的名字、種類、巢狀層級都不同,抽象層只能自己定義一個中立的輸出結構,不能直接借某一家的。
  • Messages API 是無狀態的。 Anthropic 頁面明說每次請求都要送完整對話歷史,而且前面的 assistant 訊息不一定真的來自 Claude。OpenAI 的 Responses 則提供「由伺服器保存狀態」的選項(Day 56 細讀)。這個差異意味著「對話歷史存在哪裡」是抽象層必須自己決定的事,不是 provider 幫你決定。
  • 請求欄位的名字與必填性不同。 Anthropic 的官方範例每一個請求都帶 max_tokens,系統指示用最上層的 system 欄位(不放進 messages)。把它們攤開來對照,你會發現「輸出長度上限」「系統指示」「模型名稱」這三個概念兩家都有,但位置與寫法不同——這種差異屬於「形狀」,一層 adapter 就能抹平。
  • 有些參數會隨模型世代消失。 Anthropic 的 Using the Messages API 頁在 Basic request 一節明寫:temperature、top_p、top_k 在 Claude 4.7 之後的模型不支援,設成非預設值會得到 400。這就是「語意」差異:如果你的抽象層對所有 provider 都暴露 temperature,換一個新模型就可能整個請求被拒。今天先記下這個例子,Day 58 會用它來寫「不抽象什麼」。

實作

在一個新資料夾 p06/ 裡建立 api_shapes.py(之後每天的檔案都放在同一個資料夾):

import json
from dataclasses import dataclass


@dataclass
class ChatRequest:
    model: str
    user: str
    max_tokens: int = 1024
    stream: bool = False


def to_openai_responses(r: ChatRequest) -> dict:
    return {"model": r.model, "input": r.user, "stream": r.stream}


def to_anthropic_messages(r: ChatRequest) -> dict:
    return {
        "model": r.model,
        "max_tokens": r.max_tokens,
        "messages": [{"role": "user", "content": r.user}],
        "stream": r.stream,
    }


if __name__ == "__main__":
    req = ChatRequest(model="your-model-id", user="用一句話解釋 idempotency", stream=True)
    print("OpenAI Responses  :", json.dumps(to_openai_responses(req), ensure_ascii=False))
    print("Anthropic Messages:", json.dumps(to_anthropic_messages(req), ensure_ascii=False))

執行 python api_shapes.py。預期(教材作者實跑結果):印出兩行 JSON,第一行只有 model、input、stream 三個欄位,第二行多了 max_tokens,且使用者文字被包在 messages 的 {"role": "user", ...} 裡。這個程式刻意沒有處理系統指示。

接著在你的筆記裡填這張表,每一格都要用兩個主教材頁面(以及 Companion)裡讀到的內容回答,並在格子後面寫出你是在哪一頁哪一節看到的:

概念OpenAI ResponsesAnthropic Messages是形狀差異還是語意差異?
系統指示放哪裡
輸出長度上限的參數
一次回應的結構
結束原因(為什麼停)
對話歷史由誰保存

最後修改 api_shapes.py,讓 to_anthropic_messages 多接受一個 system 欄位並放進正確位置,to_openai_responses 的對應處理則依你在 Companion 讀到的結果補上。

過關標準

  • 能回答:「形狀差異」與「語意差異」各舉一個今天讀到的例子,並說明為什麼前者能用 adapter 抹平、後者不能
  • 能回答:為什麼 temperature 不適合當成抽象層裡對所有 provider 一律提供的欄位?
  • 產出:填完的五列對照表(含出處),以及支援系統指示的 api_shapes.py 與它的輸出
  1. 依 AI 課程線總綱(curriculum/ai/00-master-curriculum.md)第 11 節「Phase 06 — AI Application Engineering」的目標與主教材
  2. 依總綱第 11 節「搭配」:Full Stack Deep Learning 從 Problem → Model → Data → Deployment → Monitoring 看完整 AI system
  3. 依總綱第 4 節跟 Backend 課程的重疊對照表(Phase 06 ↔ Backend Day 85)與第 11 節「跟 Backend 課程重疊」
  4. 依總綱第 11 節「實作」
  5. 依總綱第 11 節「驗收」

Day 52 — Streaming:SSE 事件與中途失敗

今天要回答的問題

串流回應是一串什麼東西?兩家的事件各長什麼樣?如果連線已經回了 200、文字也吐了一半,之後才出錯,你的程式怎麼知道?

主教材(Core)

  • OpenAI 文件 — Streaming API responses(Enable streaming、Read the responses、Advanced use cases、Moderation risk 四節,全頁很短),預估 15 分鐘
  • Anthropic 文件 — Streaming messages(Streaming with SDKs、Event types、Content block delta types、Error recovery 四節),預估 40 分鐘
  • 實作,預估 50 分鐘

搭配(Companion,選讀)

  • Anthropic 文件 — 同一頁的 Full HTTP stream response 一節(Basic streaming request 範例),看一次真實的事件序列長什麼樣;預估 10 分鐘

讀的時候抓這幾個重點

  • 串流就是 HTTP 回應不一次送完。 兩家都在請求裡設 stream 為 true,伺服器改用 server-sent events(SSE)一段一段送:每個事件有一個事件名稱,後面跟一段 JSON 資料。你的程式要做的是把文字流切成一個個事件,再依事件種類處理。
  • 事件有型別,你只處理需要的。 OpenAI 頁列出讀文字時常看的事件:response.created、response.output_text.delta、response.completed、error。Anthropic 的序列則是 message_start、一或多個內容區塊(每個區塊有開始、若干 content_block_delta、結束)、最後 message_stop,中間還可能夾著 ping。文字增量在 Anthropic 是 content_block_delta 裡 delta.type 為 text_delta 的那種;工具呼叫的參數則是另一種 delta(input_json_delta),提醒你「delta」不一定是文字。
  • 錯誤可能在 200 之後才來。 Anthropic 的 Errors 頁明確說:串流時錯誤可能發生在 API 已經回 200 之後,這時不走一般的 HTTP 狀態碼錯誤處理,而是以串流裡的 error 事件出現。這是一個典型的陷阱:只在 try 包住請求、不檢查事件的程式,會把「半截文字」當成完整回答。Anthropic 頁另有 Error recovery 一節,依模型世代分兩種寫法,請讀完再決定你的抽象層要不要支援續傳。
  • 串流讓半成品變得可見。 OpenAI 的 Moderation risk 一節提醒:部分輸出比完整輸出更難審查,審查分數要等整個輸出生成完才有。所以「邊串邊顯示給使用者」與「輸出要先過濾」是衝突的,要不要串流是產品決策,不只是效能決策。

實作

建立 sse.py。這個檔案有兩個目的:把原始 SSE 文字切成事件,再各寫一個把事件轉成「文字片段」的函式。OpenAI 的文字在 delta 欄位,這是對照 Streaming 頁的範例程式(讀 event.delta)確認的;它放成一個常數,是因為欄位名屬於「形狀」,換 provider 或 API 版本時只要改一行:

import json


def parse_sse(raw: str):
    """把 SSE 文字拆成 (event_name, data_dict)。空行代表一個事件結束。"""
    event, data_lines = None, []
    for line in raw.splitlines() + [""]:
        if line == "":
            if data_lines:
                yield event, json.loads("\n".join(data_lines))
            event, data_lines = None, []
        elif line.startswith(":"):
            continue
        elif line.startswith("event:"):
            event = line[len("event:"):].strip()
        elif line.startswith("data:"):
            data_lines.append(line[len("data:"):].strip())


# OpenAI 的 delta 欄位名已對照官方 Streaming 頁範例;放成常數,形狀改變時只改這一行
OPENAI_DELTA_FIELD = "delta"


def openai_text(events):
    for name, data in events:
        if name == "response.output_text.delta":
            yield data[OPENAI_DELTA_FIELD]
        elif name == "error":
            raise RuntimeError(f"mid-stream error: {data}")


def anthropic_text(events):
    for name, data in events:
        if name == "content_block_delta" and data["delta"]["type"] == "text_delta":
            yield data["delta"]["text"]
        elif name == "error":
            raise RuntimeError(f"mid-stream error: {data}")


OPENAI_RAW = """\
event: response.created
data: {"type": "response.created"}

event: response.output_text.delta
data: {"type": "response.output_text.delta", "delta": "Idem"}

event: response.output_text.delta
data: {"type": "response.output_text.delta", "delta": "potent"}

event: response.completed
data: {"type": "response.completed"}
"""

ANTHROPIC_RAW = """\
event: message_start
data: {"type": "message_start", "message": {"content": []}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Idem"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "potent"}}

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}
"""

if __name__ == "__main__":
    print("openai   :", "".join(openai_text(parse_sse(OPENAI_RAW))))
    got = []
    try:
        for piece in anthropic_text(parse_sse(ANTHROPIC_RAW)):
            got.append(piece)
    except RuntimeError as e:
        print("anthropic: 已收到", got, "然後", e)

執行 python sse.py。預期(教材作者實跑結果):

openai   : Idempotent
anthropic: 已收到 ['Idem', 'potent'] 然後 mid-stream error: {'type': 'error', 'error': {'type': 'overloaded_error', 'message': 'Overloaded'}}

第二行就是「HTTP 回 200、文字已經吐了一半,最後才出錯」的情境:呼叫端已經收到兩個片段,卻要在最後得到一個例外。

然後做兩件事:(1) 對照 Companion 的真實事件序列,檢查 ANTHROPIC_RAW 的格式有沒有和官方範例不一致的地方,記在筆記;(2) 找出 OpenAI 頁面或 API reference 裡 response.output_text.delta 事件的資料結構,除了 delta 之外還帶了哪些欄位(例如標示是第幾個輸出的欄位),想一想你的抽象層需不需要保留它們。

過關標準

  • 能回答:為什麼「請求回了 200」不代表「這次生成成功」?你的程式要檢查什麼?
  • 能回答:Anthropic 事件序列裡 ping 與 content_block_delta 各是做什麼用的?處理時為什麼不能假設每個事件都帶文字?
  • 產出:sse.py 的輸出,加上筆記裡「OpenAI delta 事件的其他欄位」與「格式比對結果」各一段

Day 53 — 錯誤、rate limit、retry 與 timeout

今天要回答的問題

收到 429、500、503、529 的時候,哪些該重試、哪些不該?重試要等多久?總共願意等多久?

主教材(Core)

  • OpenAI 文件 — Error codes(API errors 一節的各個狀態碼條目、Handling errors 一節),預估 20 分鐘
  • Anthropic 文件 — Claude API errors(HTTP errors、Long requests 兩節,另掃一下 Error shapes 與 Request ID),預估 25 分鐘
  • Anthropic 文件 — Rate limits(About rate limits、Reaching your spend cap、Response headers 三節),預估 20 分鐘
  • 實作,預估 40 分鐘

搭配(Companion,選讀)

  • OpenAI 文件 — Rate limits(Error mitigation 一節:Handle rapid traffic increases and model overload),預估 15 分鐘

讀的時候抓這幾個重點

  • 同樣是 429,意思可能完全相反。 OpenAI 的 Error codes 頁把 429 拆成好幾條:credit balance exhausted、rate limit reached for requests、slow down、organization/project spend limit reached 等。Anthropic 的 Rate limits 頁也說:到達月度花費上限時回的 429,錯誤類型和一般 rate limit 一樣是 rate_limit_error,但沒有 retry-after 標頭,重試(包含 SDK 自動重試)在額度恢復前一定失敗,要看 error.details.error_code 為 enforced_spend_limit_reached 才能分辨。所以不能寫「看到 429 就重試」。
  • 有 retry-after 就照它等。 Anthropic 說有這個標頭時要等那麼多秒再重試,更早重試必定失敗;OpenAI 的 Handling errors 也是同樣精神,沒有標頭時才用指數退避加 jitter。
  • 官方 SDK 已經會重試。 Anthropic 的 Errors 頁寫明:官方 SDK 會自動重試暫時性失敗(連線錯誤、rate limit、5xx),預設兩次、用指數退避並尊重 retry-after,可用 max_retries 調整或關閉。如果你在 SDK 外面又包一層自己的重試,最壞情況重試次數是兩層相乘,而且你的 timeout 預算會被默默吃掉。決定「重試放在哪一層」是抽象層的設計決策。
  • timeout 與長請求要一起設計。 Anthropic 的 Long requests 一節建議長請求改用 streaming 或 Batches,原因包含:網路可能在閒置一段時間後掐斷連線;SDK 也會檢查非串流請求預計不超過 10 分鐘。504 是 timeout_error,文件的建議正是改用串流。

實作

建立 retry.py。重點有四個:錯誤先分類(可重試/不可重試)、有 retry-after 就照它、沒有就用 full jitter 的指數退避、整體有總預算(deadline),而且睡眠與時鐘都可以注入,這樣測試不用真的等:

import random
import time


class ProviderError(Exception):
    """kind: rate_limit / quota / overloaded / server / timeout / invalid / auth"""

    RETRYABLE = {"rate_limit", "overloaded", "server", "timeout"}

    def __init__(self, kind, status, retry_after=None):
        super().__init__(f"{status} {kind}")
        self.kind, self.status, self.retry_after = kind, status, retry_after

    @property
    def retryable(self):
        return self.kind in self.RETRYABLE


def call_with_retry(fn, *, max_attempts=4, base=0.5, cap=8.0, deadline=None,
                    sleep=time.sleep, now=time.monotonic, rng=random.random):
    start = now()
    for attempt in range(1, max_attempts + 1):
        try:
            return fn()
        except ProviderError as e:
            if not e.retryable or attempt == max_attempts:
                raise
            if e.retry_after is not None:
                delay = e.retry_after                      # 伺服器說等多久就等多久
            else:
                delay = rng() * min(cap, base * 2 ** (attempt - 1))   # full jitter
            if deadline is not None and now() - start + delay > deadline:
                raise                                      # 等完就超過總預算,不如現在失敗
            sleep(delay)


def flaky(errors):
    """依序丟出 errors 裡的例外,用完就回傳 'ok'。"""
    queue = list(errors)

    def fn():
        if queue:
            raise queue.pop(0)
        return "ok"
    fn.calls_left = lambda: len(queue)
    return fn


if __name__ == "__main__":
    slept = []
    fake_sleep = slept.append

    r = call_with_retry(flaky([ProviderError("rate_limit", 429, retry_after=2)]), sleep=fake_sleep)
    print("1) 429 帶 retry-after=2    ->", r, "sleep", slept)

    slept.clear()
    r = call_with_retry(flaky([ProviderError("overloaded", 529)] * 3), sleep=fake_sleep, rng=lambda: 0.5)
    print("2) 529 連三次再成功          ->", r, "sleep", slept)

    slept.clear()
    try:
        call_with_retry(flaky([ProviderError("quota", 429)]), sleep=fake_sleep)
    except ProviderError as e:
        print("3) 額度用完的 429            -> 不重試,直接丟出", e, "sleep", slept)

    slept.clear()
    clock = [0.0]
    try:
        call_with_retry(flaky([ProviderError("server", 500, retry_after=30)]), sleep=fake_sleep,
                        now=lambda: clock[0], deadline=10)
    except ProviderError as e:
        print("4) 等 30 秒會超過 10 秒預算   -> 直接失敗", e, "sleep", slept)

執行 python retry.py。預期(教材作者實跑結果):

1) 429 帶 retry-after=2    -> ok sleep [2]
2) 529 連三次再成功          -> ok sleep [0.25, 0.5, 1.0]
3) 額度用完的 429            -> 不重試,直接丟出 429 quota sleep []
4) 等 30 秒會超過 10 秒預算   -> 直接失敗 500 server sleep []

第 2 列的睡眠時間可以驗算:rng 固定回 0.5,所以是 0.5 × min(8, 0.5 × 2^(n-1)) = 0.25、0.5、1.0。

然後在筆記完成一張分類表:把今天兩家 Errors 頁列出的每個 HTTP 狀態碼,各歸到 ProviderError 的某個 kind(或標註「不屬於任何一種,要新增 kind」),並說明歸類理由。表至少要涵蓋 400、401、402(Anthropic)、403、404、413、429(至少兩種)、500、503、504、529。

過關標準

  • 能回答:為什麼「額度用完」的 429 不該重試?你的程式怎麼分辨它和一般 rate limit?
  • 能回答:官方 SDK 已經會重試時,你自己的重試層要怎麼避免重試次數相乘?
  • 產出:retry.py 的輸出,與涵蓋上述狀態碼的分類表

Day 54 — Structured output:保證格式與自己驗證

今天要回答的問題

兩家都說可以「保證」輸出符合 JSON Schema,那為什麼你還需要自己的驗證?在哪些情況下,輸出會不符合 schema?

主教材(Core)

  • OpenAI 文件 — Structured model outputs(When to use Structured Outputs via function calling vs via text.format、Structured Outputs vs JSON mode、How to use Structured Outputs with text.format 含 Step 3 的 Refusals 小節),預估 35 分鐘
  • Anthropic 文件 — Structured outputs(Why use structured outputs、How it works、Usage、Important considerations 裡的 JSON Schema limitations 與 Invalid outputs),預估 35 分鐘
  • 實作,預估 45 分鐘

搭配(Companion,選讀)

  • Anthropic 文件 — 同一頁的 Strict tool use 一節,看「結構化輸出」與「工具參數 strict」是兩個獨立功能;預估 10 分鐘

讀的時候抓這幾個重點

  • 兩個層次:保證 JSON 合法,與保證符合 schema。 OpenAI 頁把舊的 JSON mode(只保證是合法 JSON)與 Structured Outputs(受 schema 約束)分開講,並建議用後者。兩家的做法在請求裡的位置不同:OpenAI 用 text.format 帶 json_schema,Anthropic 用 output_config.format(type: "json_schema")。這是「形狀」差異。
  • 「保證」有例外。 OpenAI 頁的 edge cases 列出:拒答會出現在專屬的 refusal 欄位,輸出碰到 max output tokens 上限會是不完整的回應。Anthropic 頁也說:當 stop_reason 是 refusal 或 max_tokens 時,回應可能不符合 schema。所以你的程式碼在解析前必須先看「為什麼停」。
  • 兩家支援的 schema 子集不同。 Anthropic 頁列出限制:物件要 additionalProperties: false、不支援遞迴 schema 與外部 $ref、大部分數值與字串限制不可用;SDK 的做法是把不支援的限制移到欄位描述,並在本地驗證。換句話說,同一份 schema 丟給兩家,行為可能不一樣——抽象層不能只負責「把 schema 傳過去」。
  • 第一次用新 schema 會多花時間。 OpenAI 頁提醒第一個使用新 schema 的請求有額外延遲;Anthropic 頁有 Grammar compilation and caching 一節處理類似問題。如果你在 benchmark 結構化輸出,要把第一次請求分開看。

實作

建立 structured.py。它包含:一個極簡的 JSON Schema 驗證器(只支援你今天用得到的子集:type/enum/properties/required/additionalProperties/items)、把各家 stop reason 先翻成三種(正常/拒答/截斷)的結構、以及「驗證失敗就把錯誤回給模型修正一次」的流程:

import json
from dataclasses import dataclass

TYPES = {"string": str, "integer": int, "number": (int, float), "boolean": bool,
         "array": list, "object": dict}


def validate(value, schema, path="$"):
    """極簡 JSON Schema 子集:type / enum / properties / required / additionalProperties / items。
    回傳錯誤字串清單,空清單代表通過。"""
    errors = []
    t = schema.get("type")
    if t:
        ok = isinstance(value, TYPES[t]) and not (t in ("integer", "number") and isinstance(value, bool))
        if not ok:
            return [f"{path}: 需要 {t},拿到 {type(value).__name__}"]
    if "enum" in schema and value not in schema["enum"]:
        errors.append(f"{path}: {value!r} 不在 {schema['enum']}")
    if t == "object":
        props = schema.get("properties", {})
        for key in schema.get("required", []):
            if key not in value:
                errors.append(f"{path}.{key}: 缺少必填欄位")
        if schema.get("additionalProperties") is False:
            for key in value:
                if key not in props:
                    errors.append(f"{path}.{key}: 多出 schema 沒有的欄位")
        for key, sub in props.items():
            if key in value:
                errors += validate(value[key], sub, f"{path}.{key}")
    if t == "array" and "items" in schema:
        for i, item in enumerate(value):
            errors += validate(item, schema["items"], f"{path}[{i}]")
    return errors


@dataclass
class Reply:
    text: str
    stop: str  # end / refusal / truncated(各家 stop reason 先在 adapter 裡翻成這三個)


class StructuredFailure(Exception):
    pass


def ask_structured(call, prompt, schema, max_repairs=1):
    messages = [prompt]
    for attempt in range(max_repairs + 1):
        reply = call(messages)
        if reply.stop == "refusal":
            raise StructuredFailure("模型拒答,不是格式問題,重試無用")
        if reply.stop == "truncated":
            raise StructuredFailure("輸出被截斷(max tokens),JSON 不完整")
        try:
            data = json.loads(reply.text)
        except json.JSONDecodeError as e:
            problems = [f"不是合法 JSON:{e.msg}"]
        else:
            problems = validate(data, schema)
            if not problems:
                return data
        messages.append(f"上一個回答有問題:{'; '.join(problems)}。請只回傳修正後的 JSON。")
    raise StructuredFailure(f"修正 {max_repairs} 次後仍不合格:{problems}")


SCHEMA = {"type": "object", "additionalProperties": False, "required": ["city", "days"],
          "properties": {"city": {"type": "string"}, "days": {"type": "integer"},
                         "mood": {"type": "string", "enum": ["calm", "busy"]}}}


def scripted(replies):
    it = iter(replies)
    return lambda messages: next(it)


if __name__ == "__main__":
    good = Reply('{"city": "Taipei", "days": 3}', "end")
    bad_type = Reply('{"city": "Taipei", "days": "3"}', "end")
    extra = Reply('{"city": "Taipei", "days": 3, "tip": "x"}', "end")
    print("1) 一次就對      ->", ask_structured(scripted([good]), "p", SCHEMA))
    print("2) 型別錯再修正  ->", ask_structured(scripted([bad_type, good]), "p", SCHEMA))
    for label, replies in [("3) 連錯兩次      ", [bad_type, extra]),
                           ("4) 拒答            ", [Reply("", "refusal")]),
                           ("5) 被截斷          ", [Reply('{"city": "Tai', "truncated")])]:
        try:
            ask_structured(scripted(replies), "p", SCHEMA)
        except StructuredFailure as e:
            print(label, "->", e)

執行 python structured.py。預期(教材作者實跑結果):

1) 一次就對      -> {'city': 'Taipei', 'days': 3}
2) 型別錯再修正  -> {'city': 'Taipei', 'days': 3}
3) 連錯兩次       -> 修正 1 次後仍不合格:['$.tip: 多出 schema 沒有的欄位']
4) 拒答             -> 模型拒答,不是格式問題,重試無用
5) 被截斷           -> 輸出被截斷(max tokens),JSON 不完整

接著在筆記寫一張表:把兩個主教材頁各自提到的「輸出可能不符合 schema 的情況」逐項列出,每一項標出你的 ask_structured 會把它歸到哪個分支(修正/拒答/截斷/其他),歸不進去的要寫出你會怎麼擴充。

過關標準

  • 能回答:為什麼 refusal 與 max_tokens 兩種情況不該走「把錯誤回給模型再修正」的路?
  • 能回答:同一份 JSON Schema 丟給兩家,可能出現什麼差異?抽象層應該負責哪一部分?
  • 產出:structured.py 的輸出,與「輸出可能不符 schema 的情況」對照表

Day 55 — Tool calling 跨 provider:兩家 wire format 的差異

今天要回答的問題

同一個工具,宣告給兩家要怎麼寫?模型要求呼叫時,你回傳結果的訊息怎麼對應回那一次呼叫?

主教材(Core)

  • OpenAI 文件 — Function calling(How it works、Handling function calls、Additional configurations 裡的 Tool choice/Parallel function calling/Strict mode),預估 35 分鐘
  • Anthropic 文件 — Tool use with Claude(How tool use works、When Claude uses tools 兩節),預估 25 分鐘
  • 實作,預估 50 分鐘

搭配(Companion,選讀)

  • Anthropic 文件 — Claude API errors 的 Common validation errors 裡 Forced tool use not supported 一節,看「強制呼叫工具」在新模型上不被支援;預估 10 分鐘

讀的時候抓這幾個重點

  • 這部分已在 Backend Day 85 講過 tool calling 的 schema、執行、驗證、失敗與重試(先驗證模型給的參數、再執行;非 idempotent 的工具失敗時不能自動重試),今天的新角度是:兩家的 wire format 不同,而且「強制選工具」這類控制項不是所有模型都支援。
  • 工具宣告的形狀不同,概念相同。 OpenAI 頁說 function tool 用 JSON schema 描述;Anthropic 的範例用 name、description、input_schema。兩邊都是「名稱+描述+參數 schema」,屬於形狀差異。
  • 結果要用 id 對回呼叫。 OpenAI 頁的重點是模型回傳 tool call、你的程式執行、再把輸出送回去,並以 call_id 對應;Anthropic 的做法是模型回 stop_reason: "tool_use" 與 tool_use 區塊,你送回的 tool_result 區塊帶 tool_use_id。抽象層要做的是用自己的 call_id 當中立名稱,在 adapter 兩端各自翻譯。
  • 控制項不是通用的。 OpenAI 頁有 Tool choice、Parallel function calling、Strict mode;Anthropic 的範例用 disable_parallel_tool_use 限制每回合最多一個工具呼叫。Anthropic 的 Errors 頁還明寫:Claude Opus 5.5、Sonnet 5.5、Fable 5.1 等模型不支援強制呼叫工具(tool_choice 為 any 或 tool 會得到 400)。所以「強制呼叫某個工具」不能是抽象層對所有模型都提供的功能。

實作

建立 tools.py(它會匯入 Day 54 的 validate,所以要放在同一個資料夾)。兩邊的欄位都已對照官方頁面:Anthropic 側對照 Tool use 頁的範例,OpenAI 側的 type: "function"/parameters 與 function_call_output/call_id/output 對照 Function calling 頁的 Defining functions 與 Formatting results 兩節。OpenAI 的宣告還有一個選用的 strict 欄位,這裡沒放:

import json
from dataclasses import dataclass, field
from typing import Callable

from structured import validate


@dataclass
class ToolSpec:
    name: str
    description: str
    schema: dict
    run: Callable[[dict], str]
    idempotent: bool = True   # Backend Day 85:非 idempotent 的工具失敗時不能自動重試


# 以下兩個 adapter 的欄位名:Anthropic 側(name / description / input_schema、
# tool_result + tool_use_id)對照官方 Tool use 頁;OpenAI 側(type=function / parameters、
# function_call_output + call_id + output)對照官方 Function calling 頁。
def declare_anthropic(t: ToolSpec) -> dict:
    return {"name": t.name, "description": t.description, "input_schema": t.schema}


def declare_openai(t: ToolSpec) -> dict:
    return {"type": "function", "name": t.name, "description": t.description, "parameters": t.schema}


@dataclass
class ToolCall:
    call_id: str
    name: str
    arguments: dict


def result_anthropic(call: ToolCall, content: str) -> dict:
    return {"type": "tool_result", "tool_use_id": call.call_id, "content": content}


def result_openai(call: ToolCall, content: str) -> dict:
    return {"type": "function_call_output", "call_id": call.call_id, "output": content}


def execute(call: ToolCall, registry: dict) -> str:
    """模型給的參數一律當外部輸入:先驗證,失敗就把原因當結果回給模型,不執行、不自動重試。"""
    tool = registry.get(call.name)
    if tool is None:
        return f"error: 沒有名為 {call.name} 的工具"
    problems = validate(call.arguments, tool.schema)
    if problems:
        return "error: 參數不合格 " + "; ".join(problems)
    return tool.run(call.arguments)


if __name__ == "__main__":
    order = ToolSpec(
        name="get_order_status",
        description="查詢單一訂單的狀態",
        schema={"type": "object", "additionalProperties": False, "required": ["order_id"],
                "properties": {"order_id": {"type": "integer"}}},
        run=lambda a: json.dumps({"order_id": a["order_id"], "status": "shipped"}),
    )
    registry = {order.name: order}
    print("Anthropic 宣告:", json.dumps(declare_anthropic(order), ensure_ascii=False))
    print("OpenAI 宣告   :", json.dumps(declare_openai(order), ensure_ascii=False))
    ok = ToolCall("call_1", "get_order_status", {"order_id": 42})
    bad = ToolCall("call_2", "get_order_status", {"order_id": "42; DROP TABLE orders"})
    for c in (ok, bad):
        out = execute(c, registry)
        print(c.call_id, "->", out)
        print("   回給 Anthropic:", result_anthropic(c, out)["tool_use_id"], "| 回給 OpenAI:", result_openai(c, out)["call_id"])

執行 python tools.py。預期(教材作者實跑結果):兩行宣告 JSON 內容相同、只差欄位名(input_schema 對 type+parameters);call_1 的結果是 {"order_id": 42, "status": "shipped"};call_2 的結果是 error: 參數不合格 $.order_id: 需要 integer,拿到 str,也就是壞參數在執行前被擋下,沒有走到工具函式。

然後在筆記寫:(1) OpenAI 宣告裡的 strict 欄位開啟時對 schema 有什麼額外要求(讀 Function calling 頁的 Strict mode),以及你的 ToolSpec 要不要支援它;(2) 把 ToolSpec.idempotent 接到 Day 53 的 call_with_retry:寫出「非 idempotent 工具的失敗,Router 該怎麼處理」的決策(不用寫程式,3~5 句話並引用 Backend Day 85 的判斷邏輯)。

過關標準

  • 能回答:兩家的工具宣告與結果訊息各自長什麼樣?抽象層用什麼中立欄位把它們接起來?
  • 能回答:為什麼模型給的工具參數要先驗證再執行?驗證失敗時應該重試,還是把錯誤回給模型?
  • 產出:tools.py 的輸出、strict 的筆記、非 idempotent 工具的失敗處理決策

Day 56 — 對話狀態與 context:歷史存哪裡、放不放得下

今天要回答的問題

對話歷史應該由你保存,還是由 provider 保存?放不下 context window 時要丟什麼?token 數要怎麼算才可信?

主教材(Core)

  • OpenAI 文件 — Conversation state(Manually manage conversation state、Using the Conversations API、Passing context from the previous response、Managing context for text generation、Compaction),預估 30 分鐘
  • Anthropic 文件 — Token counting(How to count message tokens、Count tokens in basic messages;以及頁中關於新舊 tokenizer 的說明),預估 25 分鐘
  • 實作,預估 45 分鐘

搭配(Companion,選讀)

  • OpenAI 文件 — Migrate to the Responses API 的 Migrating from Chat Completions 裡「Decide when to store state」一節,看何時該讓 provider 保存狀態;預估 10 分鐘

讀的時候抓這幾個重點

  • 每個請求都是無狀態的,狀態怎麼延續是選擇題。 OpenAI 頁的重點是:你可以自己每次重送先前的訊息,或使用 OpenAI 的狀態管理 API(Conversations API 把狀態存在持久物件,或用 previous_response_id 把回應串起來)。Anthropic 的 Messages API 則只有「自己送完整歷史」這一條路(見 Day 51)。即使用 previous_response_id,先前的輸入 token 每一輪仍會計費,所以「provider 幫我保存」不等於「變便宜」。
  • context window 是一個總預算。 OpenAI 頁說 context window 上限涵蓋輸入、輸出與 reasoning tokens 的總和,長對話需要管理,例如 compaction。這意味著你不能只算輸入,要預留輸出(含推理)的空間。
  • token 數是估計,而且不能跨模型搬。 Anthropic 的 Token counting 頁說明:計數端點接受和建立 message 相同的輸入(含 system、tools、圖片、PDF),回傳輸入 token 總數;這個數字是估計,與實際可能有小差異。頁中也寫:Claude 4.7 之後的模型使用新的 tokenizer,同樣文字大約多出 30% 的 token;所以要用你打算呼叫的那個模型重新計數,不能拿舊模型的數字估。這和 Phase 03 講的「tokenizer 是 model 的一部分」是同一件事,只是現在變成了 billing 與 context 預算的問題。
  • 所謂「裁剪歷史」是產品決策。 從最舊的丟、保留 system、保留最近 N 則,是最簡單的策略;它會丟掉使用者早先給的重要條件。compaction 之類的做法是用摘要換空間,各有代價。抽象層至少要讓這個策略可以被替換。
  • 另外,OpenAI 的 Token counting 專頁在 2026-10-16 查證時我們沒有找到可用的連結(猜測的網址回 404),所以今天 OpenAI 側沒有對應的計數頁可讀;OpenAI 側的 token 用量請以回應裡實際回報的 usage 為準(Day 57)。

實作

建立 context.py。用一個粗估函式決定「要不要裁」,策略是保留 system 與最後 N 則、從最舊的開始丟:

def estimate_tokens(text: str) -> int:
    """粗估:只用來決定裁不裁。真正的數字要用各家的 token 計數或回應裡的 usage。"""
    return max(1, len(text) // 3)


def trim_history(messages, budget, count=estimate_tokens, keep_last=2):
    """保留 system 與最後 keep_last 則,從最舊的非 system 訊息開始丟,直到估計值 <= budget。"""
    system = [m for m in messages if m["role"] == "system"]
    rest = [m for m in messages if m["role"] != "system"]

    def total(ms):
        return sum(count(m["content"]) for m in ms)

    dropped = 0
    while total(system + rest) > budget and len(rest) > keep_last:
        rest.pop(0)
        dropped += 1
    return system + rest, dropped


if __name__ == "__main__":
    history = [{"role": "system", "content": "你是客服助理。" * 5}]
    for i in range(1, 7):
        history.append({"role": "user" if i % 2 else "assistant", "content": f"第{i}則 " + "字" * 60})
    print("原本", len(history), "則,估計", sum(estimate_tokens(m["content"]) for m in history), "tokens")
    for budget in (150, 80, 30):
        kept, dropped = trim_history(history, budget)
        print(f"budget={budget:3d} -> 留 {len(kept)} 則,丟 {dropped} 則,留下的是",
              [m["content"][:3] for m in kept])

執行 python context.py。預期(教材作者實跑結果):

原本 7 則,估計 137 tokens
budget=150 -> 留 7 則,丟 0 則,留下的是 ['你是客', '第1則', '第2則', '第3則', '第4則', '第5則', '第6則']
budget= 80 -> 留 4 則,丟 3 則,留下的是 ['你是客', '第4則', '第5則', '第6則']
budget= 30 -> 留 3 則,丟 4 則,留下的是 ['你是客', '第5則', '第6則']

注意 budget=30 時仍留下 3 則,因為 keep_last=2 加 system 是下限:這是「寧可超過預算也不丟最近訊息」的取捨,真實系統遇到這種情況應該回報錯誤或改用摘要。

然後在筆記寫一份短短的「狀態決策」:你的抽象層要把對話歷史存在自己這邊,還是允許用 OpenAI 的伺服器端狀態?寫出理由,至少涵蓋「換 provider 時能不能帶走歷史」與「計費」兩點。

過關標準

  • 能回答:用 previous_response_id 串回應,為什麼不會讓輸入 token 的費用消失?
  • 能回答:為什麼不能拿舊模型算出的 token 數去估新模型的 context 用量?
  • 產出:context.py 的輸出,與你的「狀態決策」一段(含兩個要點)

Day 57 — Token/cost tracking 與 prompt caching

今天要回答的問題

一次呼叫到底花了多少 token、多少錢?prompt caching 怎麼改變這個算式?怎麼把兩家不同格式的 usage 收進同一個帳本?

主教材(Core)

  • Anthropic 文件 — Rate limits 的 Cache-aware ITPM 一節(哪些 token 計入、total_input_tokens 的算式),預估 20 分鐘
  • OpenAI 文件 — Prompt caching(Why prompt caching matters、How caching works、How prefix matching works、How to optimize prompt caching 裡的 Preserve conversation history 與 Monitor cache performance),預估 30 分鐘
  • 實作,預估 55 分鐘

搭配(Companion,選讀)

  • OpenAI 文件 — 同一頁的 Gotchas 一節(A shared prefix is not always a cached prefix、Compaction can reduce cache reuse),看快取失效的陷阱;預估 15 分鐘
  • Anthropic 文件 — Token counting 的 Pricing and rate limits 一節與 FAQ,確認「計數端點本身免費、也不使用快取」;預估 5 分鐘

讀的時候抓這幾個重點

  • 輸入 token 要分三種記。 Anthropic 的 Rate limits 頁說明回應 usage 裡有三種輸入:input_tokens(最後一個 cache breakpoint 之後的部分,不是全部輸入)、cache_creation_input_tokens(寫入快取的)、cache_read_input_tokens(從快取讀的)。總輸入是三者相加。最容易誤會的是看到 input_tokens 很小就以為這次很便宜:頁中的例子是 20 萬 token 的文件已快取,使用者只問了 50 token 的問題,input_tokens 只有 50,但總輸入是 200,050。
  • 同一個欄位名,兩家算法相反。 OpenAI 的 Prompt caching 頁在 Monitor cache performance 一帶列出 usage.input_tokens、usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens,而它算快取命中率的方式是「cached tokens 除以 total input tokens」,算未快取部分的範例程式則是 inputTokens - cachedTokens - cacheWriteTokens——也就是說,OpenAI 的 input_tokens 已經包含快取的部分,Anthropic 的 input_tokens 卻不包含。兩家都叫 input_tokens,直接相加或直接比較就會算錯,這是典型的「語意」差異,adapter 一定要換算。
  • 快取是以「前綴完全相同」為前提。 OpenAI 頁說快取重用的是未變動的 prompt 前綴所儲存的處理狀態,要命中必須整段前綴一致,所以要把穩定的內容放前面、新訊息用附加的方式加在後面,而不是改寫前面的訊息。這個做法同時決定了你組 prompt 的方式,也就是說「成本優化」會反過來影響「抽象層怎麼組裝 messages」。
  • 快取也影響 rate limit。 Anthropic 頁說大多數 Claude 模型只有未快取的輸入 token 計入 ITPM 限額,讀快取的 token 不計入,頁中的例子是 80% 命中率下可處理的總輸入是限額的五倍。所以追蹤快取命中率不只是省錢,也是容量規劃。
  • 價格是資料,不是程式碼。 單價會變、會依模型與快取狀態而不同;寫死在程式裡會悄悄過期。教材裡的範例單價都標明是假的,只是為了讓算式可驗算。真實單價請從各家官方價格頁抄當天的值,並放在一份設定檔裡。

實作

建立 cost.py。內部統一用一個 Usage(四欄位,input_tokens 定義為「沒走快取的輸入」);Anthropic 的 adapter 已對照官方欄位名寫好。OpenAI 的 adapter 留給你寫:輸入與快取的三個欄位名在上面的重點已經列出(出自 Prompt caching 頁),但要記得先扣掉快取的部分才能放進 Usage.input_tokens;輸出 token 的欄位名在本教材查證過的頁面上沒有出現,請你打一次真實的 OpenAI 請求,或讀 API reference 的回應物件定義後確認,並在筆記記下出處:

from dataclasses import dataclass


@dataclass
class Usage:
    input_tokens: int = 0         # 沒走快取的輸入
    cache_write_tokens: int = 0   # 寫入快取的輸入
    cache_read_tokens: int = 0    # 從快取讀的輸入
    output_tokens: int = 0

    def __add__(self, o):
        return Usage(self.input_tokens + o.input_tokens, self.cache_write_tokens + o.cache_write_tokens,
                     self.cache_read_tokens + o.cache_read_tokens, self.output_tokens + o.output_tokens)

    @property
    def total_input(self):
        return self.input_tokens + self.cache_write_tokens + self.cache_read_tokens


def usage_from_anthropic(u: dict) -> Usage:
    # 欄位名與「total = read + creation + input」的算法已對照官方 Rate limits 頁
    return Usage(input_tokens=u["input_tokens"],
                 cache_write_tokens=u.get("cache_creation_input_tokens", 0),
                 cache_read_tokens=u.get("cache_read_input_tokens", 0),
                 output_tokens=u["output_tokens"])


# OpenAI 的 usage_from_openai 留給你寫:輸入/快取欄位見 Prompt caching 頁(input_tokens 已含快取,
# 要先扣掉);輸出欄位名本教材沒查到,實際打一次 API 或讀 API reference 的 Response 物件確認。


@dataclass
class Price:
    """每百萬 token 的單價。數字請從供應商價格頁抄當天的值,不要寫死在程式裡。"""
    input: float
    cache_write: float
    cache_read: float
    output: float


def cost(u: Usage, p: Price) -> float:
    return (u.input_tokens * p.input + u.cache_write_tokens * p.cache_write
            + u.cache_read_tokens * p.cache_read + u.output_tokens * p.output) / 1_000_000


class Meter:
    def __init__(self, prices: dict):
        self.prices, self.by_model = prices, {}

    def record(self, model: str, u: Usage):
        self.by_model[model] = self.by_model.get(model, Usage()) + u

    def report(self):
        return {m: (u, round(cost(u, self.prices[m]), 6)) for m, u in self.by_model.items()}


if __name__ == "__main__":
    # 範例單價(不是真實價格):只為了讓算式可驗算
    demo = Price(input=1.0, cache_write=1.25, cache_read=0.1, output=5.0)
    first = usage_from_anthropic({"input_tokens": 50, "cache_creation_input_tokens": 200_000,
                                  "cache_read_input_tokens": 0, "output_tokens": 400})
    second = usage_from_anthropic({"input_tokens": 50, "cache_creation_input_tokens": 0,
                                   "cache_read_input_tokens": 200_000, "output_tokens": 400})
    print("第 1 次 total_input =", first.total_input, " cost =", round(cost(first, demo), 6))
    print("第 2 次 total_input =", second.total_input, " cost =", round(cost(second, demo), 6))
    m = Meter({"model-a": demo})
    m.record("model-a", first)
    m.record("model-a", second)
    for model, (u, c) in m.report().items():
        print(model, "累計 output =", u.output_tokens, " 累計 cost =", c)

執行 python cost.py。預期(教材作者實跑結果):

第 1 次 total_input = 200050  cost = 0.25205
第 2 次 total_input = 200050  cost = 0.02205
model-a 累計 output = 800  累計 cost = 0.2741

兩次的總輸入一樣,成本卻差十倍以上,原因是第 1 次付的是快取寫入、第 2 次付的是快取讀取。你可以手算驗證第 1 次:50×1.0 + 200,000×1.25 + 400×5.0 = 252,050,除以一百萬得 0.25205。

最後寫 usage_from_openai,並用它補一個「OpenAI 版第二次呼叫」的例子(例如 input_tokens 200,050、其中 cached_tokens 200,000),確認轉出來的 Usage.input_tokens 是 50 而不是 200,050,total_input 仍是 200,050。

過關標準

  • 能回答:Anthropic 回應裡 input_tokens 很小時,為什麼不代表這次輸入很少?總輸入怎麼算?OpenAI 的 input_tokens 又跟它差在哪裡?
  • 能回答:為什麼 prompt 的組裝方式(穩定內容放前面、新訊息附加在後)會影響成本?
  • 產出:cost.py 的輸出、你寫的 usage_from_openai(附欄位名的出處)與 OpenAI 版例子的輸出

Day 58 — FSDL:從 Problem 到 Monitoring,以及「抽象什麼、不抽象什麼」

今天要回答的問題

把 LLM 當成一個要上線的系統而不是一個 API,要考慮哪些事?你的抽象層該收進哪些、又該刻意留在外面?

主教材(Core)

  • Full Stack Deep Learning — LLM Bootcamp:LLMOps(Why LLMOps?、Choosing your base LLM、Iteration and prompt management、Deployment and monitoring),預估 40 分鐘
  • Full Stack Deep Learning — FSDL 2022 Lecture 5:Deployment(2.2 Model-as-Service 裡的 REST APIs、Performance Optimization 的 Caching 與 Batching、Model Rollouts),預估 30 分鐘
  • 實作,預估 40 分鐘

搭配(Companion,選讀)

讀的時候抓這幾個重點

  • 注意這些教材的年份。 LLMOps 與 Launch 兩份是 2023 年春季的 LLM Bootcamp,Lecture 5 是 2022 年的課程,都比今天兩家 provider 的 API 老。查證時只確認到頁面的小節標題與重點層級。拿它們的「方法論」,不要拿它們的「產品名稱與數字」。
  • 模型呼叫只是系統的一小塊。 LLMOps 頁的小節順序本身就是一張檢查清單:為什麼需要 LLMOps、怎麼選基礎模型、怎麼管理迭代與 prompt、怎麼部署與監控。對照你過去做 backend 的經驗,這些都是熟悉的問題(版本管理、上線、監控),只是對象變成了 prompt 與模型。
  • model-as-service 的好處是獨立伸縮。 Lecture 5 的摘要是:把模型從 UI 分開,包成 service,可以獨立擴充,並用 containers、quantization、batching、serverless 等手段調效能。你的抽象層就是 application 與這個 service 之間的那條邊界。
  • 「選基礎模型」是會重做的決定。 LLMOps 頁把 Choosing your base LLM 單獨列為一節,並分開談 proprietary 與 open-source。這意味著抽象層的第一個價值是讓這個決定可以改,而不是一次選對。

實作

今天的產出不是程式,是一份設計文件:抽象層合約。在筆記建立下面這張表,並把 Day 51–57 讀到的每個證據填進去,每一列都要寫出出處(哪一天哪一頁)。我先放進三列有證據的範例,你要再補至少五列:

能力抽象(所有 provider 一個介面)還是不抽象(留給呼叫端/adapter)為什麼(附證據出處)
取樣參數(temperature 等)不抽象成通用欄位Anthropic 的 Messages API 頁:Claude 4.7 之後的模型不支援 temperature/top_p/top_k,設非預設值會 400(Day 51)
強制呼叫指定工具不抽象成通用功能Anthropic Errors 頁:部分新模型不支援 tool_choice 為 any/tool(Day 55)
重試與退避抽象(Router 內統一做)兩家都區分可重試與不可重試的錯誤,額度用完的 429 重試無效(Day 53)
串流的文字片段
用量/成本
對話歷史的存放
結構化輸出的驗證
工具呼叫 id 的對應

表格填完後,用 5~8 句話寫一段「抽象層的原則」:什麼樣的差異應該被抹平、什麼樣的差異要讓呼叫端看見。這段話是 Day 60 驗收時要用的。

過關標準

  • 能回答:為什麼說 LLM 應用的上線問題多半是你熟悉的 backend 問題換了對象?舉兩個 LLMOps 頁小節裡的例子
  • 能回答:抽象層的第一個價值是什麼?為什麼不能把某一家的 API 形狀直接當作抽象層的介面?
  • 產出:填完的「抽象層合約」表(至少 8 列,每列有出處)與「抽象層的原則」一段

Day 59 — 把模組組成 Router:fallback 與記帳

今天要回答的問題

主 provider 失敗時,什麼情況下該換下一家?什麼情況下換了也沒用、反而會藏 bug?成功與失敗的呼叫各該怎麼記帳?

主教材(Core)

  • OpenAI 文件 — Rate limits(Error mitigation 裡的 Handle rapid traffic increases and model overload),預估 15 分鐘
  • Anthropic 文件 — Claude API errors(SDK error types 與 Request ID 兩節),預估 15 分鐘
  • 實作,預估 80 分鐘

搭配(Companion,選讀)

  • 本課程 Phase 05 的 Day 46(Ollama:本機 server 接上自己的 backend),Local model 這條路已在那裡跑通,今天的 Router 只需要把它當作第三個 provider;預估 10 分鐘

讀的時候抓這幾個重點

  • fallback 不是對所有錯誤都有用。 如果是你的請求本身有問題(參數錯誤、格式不合),換一家多半一樣被拒,只是把你的 bug 藏起來。如果是對方的問題(過載、額度、暫時性故障),換一家才有意義。OpenAI 的 Error mitigation 與 Anthropic 的錯誤分類都支持這個區分。
  • 每一次呼叫都要能追查。 Anthropic 的 Request ID 一節說每個回應都帶 request-id 標頭,錯誤內容也有 request_id,聯絡支援時要附上。你的 Router 應該把 provider 名稱、嘗試結果與(可取得時的)request id 記下來,否則出事時沒辦法回頭查。
  • 失敗的呼叫不記帳;成功的才記。 今天先採最簡單的規則(只對成功回應記 usage),但要在筆記寫下這個規則的缺口,例如串流到一半才失敗的呼叫是否已產生費用,教材沒有查證過,需要你自己去文件確認。
  • 本機模型也是一個 provider。 vLLM、Ollama、llama.cpp server 都提供 OpenAI 相容的 /v1/chat/completions(見 Phase 05),所以 Local provider 可以是一個只需要 base URL 的 adapter。注意 Phase 05 也提過各家對 OpenAI 規格的相容程度不同,不能假設完全一致。

實作

建立 router.py,它匯入 Day 53 的 retry 與 Day 57 的 cost。包含:FakeProvider(用腳本控制成功或失敗,用來測試)、OpenAICompatibleProvider(打本機 server,本教材沒有替它實跑,你在 Day 60 對自己的 server 跑一次)、以及 Router:

import json
import urllib.request
from dataclasses import dataclass, field

from cost import Meter, Usage
from retry import ProviderError, call_with_retry


@dataclass
class Request:
    prompt: str
    max_tokens: int = 256


@dataclass
class Response:
    text: str
    usage: Usage
    provider: str = ""
    model: str = ""


class AllProvidersFailed(Exception):
    def __init__(self, attempts):
        super().__init__(f"全部 provider 都失敗:{attempts}")
        self.attempts = attempts


class FakeProvider:
    """script 依序放 ProviderError(丟出)或 str(回傳該文字);用完後一律回 'ok'。"""

    def __init__(self, name, model, script=()):
        self.name, self.model, self.script = name, model, list(script)

    def complete(self, req: Request) -> Response:
        step = self.script.pop(0) if self.script else "ok"
        if isinstance(step, ProviderError):
            raise step
        return Response(step, Usage(input_tokens=len(req.prompt), output_tokens=len(step)), self.name, self.model)


class OpenAICompatibleProvider:
    """打 Ollama / vLLM / llama.cpp server 的 /v1/chat/completions。本教材沒有替它跑過,
    請在 Day 60 對你自己的本機 server 跑一次,回應欄位以你機器上看到的為準。"""

    def __init__(self, name, base_url, model, timeout=30):
        self.name, self.base_url, self.model, self.timeout = name, base_url.rstrip("/"), model, timeout

    def complete(self, req: Request) -> Response:
        body = json.dumps({"model": self.model, "max_tokens": req.max_tokens,
                           "messages": [{"role": "user", "content": req.prompt}]}).encode()
        http = urllib.request.Request(self.base_url + "/v1/chat/completions", body,
                                      {"Content-Type": "application/json"})
        try:
            with urllib.request.urlopen(http, timeout=self.timeout) as r:
                data = json.load(r)
        except TimeoutError as e:
            raise ProviderError("timeout", 0) from e
        except urllib.error.HTTPError as e:
            kind = {429: "rate_limit", 503: "overloaded"}.get(e.code, "server" if e.code >= 500 else "invalid")
            raise ProviderError(kind, e.code) from e
        u = data.get("usage", {})
        return Response(data["choices"][0]["message"]["content"],
                        Usage(input_tokens=u.get("prompt_tokens", 0), output_tokens=u.get("completion_tokens", 0)),
                        self.name, self.model)


class Router:
    """依序嘗試 providers。每個 provider 先照 Day 53 的規則重試;仍失敗才換下一個。
    invalid(我們自己的請求有問題)不 fallback:換一家也會被拒,只會把 bug 藏起來。"""

    def __init__(self, providers, meter: Meter, **retry_kwargs):
        self.providers, self.meter, self.retry_kwargs = providers, meter, retry_kwargs
        self.attempts = []

    def complete(self, req: Request) -> Response:
        self.attempts = []
        for p in self.providers:
            try:
                resp = call_with_retry(lambda: p.complete(req), **self.retry_kwargs)
            except ProviderError as e:
                self.attempts.append((p.name, f"{e.kind}/{e.status}"))
                if e.kind == "invalid":
                    raise
                continue
            self.attempts.append((p.name, "ok"))
            self.meter.record(resp.model, resp.usage)
            return resp
        raise AllProvidersFailed(self.attempts)

Router.complete 的邏輯有兩個容易看漏的地方:(1) 只有 kind 為 invalid 才直接丟出,其他錯誤(含 auth 與 quota)都會換下一家,因為那是這家 provider 的問題;(2) lambda: p.complete(req) 在迴圈裡綁的是當下的 p,因為它在同一輪就被呼叫,所以沒有 late-binding 問題。請你自己確認這兩點,並在筆記寫下你同不同意把 auth 歸到「換一家」。今天還不用跑,Day 60 一起用測試驗證。

過關標準

  • 能回答:為什麼 invalid 類錯誤不該 fallback?如果它被 fallback,最壞會發生什麼?
  • 能回答:你的 Router 記了哪些資訊讓事後能追查一次失敗?還缺什麼?
  • 產出:router.py 通過 python -c "import router"(不報錯),加上筆記裡對 auth 歸類的立場與理由

Day 60 — Phase 驗收:切換 A/B/Local、測試、寫「不抽象什麼」

今天要回答的問題

你的抽象層能不能真的在 Provider A、B、Local model 之間切換?壞掉的時候行為對不對?你能不能說清楚它刻意不做什麼?

主教材(Core)

  • Full Stack Deep Learning — LLM Bootcamp:LLMOps(Testing LLMs: What works?、Test-driven development for LLMs 兩節),預估 20 分鐘
  • 實作,預估 100 分鐘

搭配(Companion,選讀)

  • OpenAI 文件 — Error codes 的 Python library error types 一節,若你選做接真實 OpenAI provider,用它決定 SDK 例外怎麼對應到 ProviderError;預估 10 分鐘

讀的時候抓這幾個重點

  • LLM 的測試要分層。 LLMOps 頁有兩節專談 Testing LLMs(為什麼難、什麼有效),另有 Test-driven development for LLMs。你今天寫的測試屬於最底層、最穩定的那一種:不呼叫模型,只驗證你的程式碼在各種失敗腳本下的行為。模型輸出本身的品質評估,是 Phase 09 的主題。
  • 測試要證明的是決策,不是 happy path。 今天五個測試各自釘住一條 Router 的決策:主 provider 成功、過載後 fallback、額度用完不睡覺直接 fallback、請求錯誤不被 fallback 藏起來、全部失敗時錯誤帶著每一家的結果。
  • 跑得動才算數。 驗收條件是「可以切換 Provider A/B/Local」。fake 的 A、B 證明切換邏輯,Local 那條要對你自己機器上的真實 server 跑一次,才算把最後一段接起來。

實作

第一步:自動化測試。 建立 test_router.py(用標準函式庫的 unittest,不用安裝任何東西):

import unittest

from cost import Meter, Price
from retry import ProviderError
from router import AllProvidersFailed, FakeProvider, Request, Router

PRICES = {"model-a": Price(1.0, 1.25, 0.1, 5.0), "model-b": Price(0.5, 0.6, 0.05, 2.0)}


def make(a_script=(), b_script=()):
    slept = []
    a = FakeProvider("A", "model-a", a_script)
    b = FakeProvider("B", "model-b", b_script)
    router = Router([a, b], Meter(PRICES), sleep=slept.append, rng=lambda: 0.5, max_attempts=3)
    return router, slept


class RouterTest(unittest.TestCase):
    def test_primary_ok(self):
        router, slept = make()
        r = router.complete(Request("hi"))
        self.assertEqual((r.provider, router.attempts, slept), ("A", [("A", "ok")], []))
        self.assertIn("model-a", router.meter.by_model)

    def test_overloaded_then_fallback(self):
        router, slept = make(a_script=[ProviderError("overloaded", 529)] * 3)
        r = router.complete(Request("hi"))
        self.assertEqual(r.provider, "B")
        self.assertEqual(router.attempts, [("A", "overloaded/529"), ("B", "ok")])
        self.assertEqual(len(slept), 2)          # 3 次嘗試之間睡 2 次
        self.assertNotIn("model-a", router.meter.by_model)   # 失敗的呼叫不記帳

    def test_quota_falls_back_without_sleeping(self):
        router, slept = make(a_script=[ProviderError("quota", 429)])
        self.assertEqual(router.complete(Request("hi")).provider, "B")
        self.assertEqual(slept, [])

    def test_invalid_is_not_hidden_by_fallback(self):
        router, _ = make(a_script=[ProviderError("invalid", 400)])
        with self.assertRaises(ProviderError):
            router.complete(Request("hi"))
        self.assertEqual(router.attempts, [("A", "invalid/400")])   # B 根本沒被試

    def test_all_fail(self):
        router, _ = make([ProviderError("server", 500)] * 3, [ProviderError("server", 500)] * 3)
        with self.assertRaises(AllProvidersFailed) as cm:
            router.complete(Request("hi"))
        self.assertEqual(cm.exception.attempts, [("A", "server/500"), ("B", "server/500")])


if __name__ == "__main__":
    unittest.main(verbosity=2)

執行 python test_router.py。預期(教材作者實跑結果):五個測試全部 ok,最後印出 Ran 5 tests 與 OK。接著做一次「變異測試」:把 Router.complete 裡 if e.kind == "invalid": raise 那兩行註解掉再跑一次,確認 test_invalid_is_not_hidden_by_fallback 會失敗;改回來後再跑確認恢復全綠。這樣你才知道這個測試真的在守那條規則。

第二步:接上 Local。 啟動 Phase 05 Day 46 的 Ollama(或 Day 48 的 vLLM),用 OpenAICompatibleProvider("local", "http://localhost:11434", "<你的 model 名稱>") 單獨發一個請求。Ollama 的 port 與 model 名稱以你自己機器上的設定為準(Phase 05 查證時 Ollama 預設 port 是 11434)。把 Router 的 providers 順序換成 [local, FakeProvider(...)] 與 [FakeProvider(... 腳本讓它一直失敗), local],各發一次請求,確認:第一種由 local 回答、第二種 fake 失敗後 fallback 到 local,router.attempts 與 router.meter.report() 的內容符合預期。記下 Local 的回應有哪些欄位和我寫的解析方式不同(例如 usage 缺漏),並修正 OpenAICompatibleProvider。

第三步(選做,費用自負):接真實雲端 provider。 用 Day 51 的 payload 與 Day 53 的錯誤分類,寫兩個真實 provider adapter(可以用 urllib 自己發請求,或用官方 SDK;安裝 SDK 是你自己環境的事)。Anthropic 側的請求標頭已在官方範例中確認:x-api-key、anthropic-version: 2023-06-01、content-type: application/json;OpenAI 側的認證標頭請對照官方 API reference。完成後用同一個測試腳本確認 A/B 可切換。

第四步:寫文件。 把 Day 58 的「抽象層合約」表與原則整理成 1 頁的 DESIGN 筆記,並用今天的測試輸出與 Local 實測,補上兩段「這個設計刻意不做的事」:(1) 至少三個你明知道 provider 之間有差異、卻選擇不抹平的項目,各寫理由與證據出處;(2) 至少兩個目前實作的已知缺口(例如失敗呼叫的費用、串流中途失敗的重試)。

過關標準

  • 能回答:你的抽象層刻意不抽象掉什麼?為什麼?(用 DESIGN 筆記裡的三個項目回答,每項附證據)
  • 能回答:怎麼證明 invalid 不 fallback 的測試真的在守規則,而不是永遠綠燈?
  • 產出:
  • test_router.py 五個測試全綠的輸出,以及變異測試「先紅、改回後轉綠」的紀錄
  • Local model 實測紀錄:換 provider 順序後的兩次請求,各附 router.attempts 與 router.meter.report() 的輸出
  • 1 頁 DESIGN 筆記,含「刻意不做的事」與「已知缺口」

Deep Dive(選讀)

  • 把 Day 52 的串流整合進 Router:串流到一半失敗時,已經送給使用者的文字怎麼辦?重試時要不要用不同的 provider 重新生成?寫下你的決策與取捨(Deep Dive 層級,沒有標準答案)
  • 把 Day 54 的 ask_structured 包進 Router,讓「輸出不符 schema」也能觸發 fallback,並討論這樣做會不會把模型品質問題誤判成可用性問題