zophos

← Notes · 02-Provider 實作經驗:從枚舉到反向依賴.md

Provider 實作經驗:從枚舉到反向依賴

寫 Rust Coding Agent 遇到的一個問題:

模型供應商(LLM Provider) 該用 enum、dyn trait,還是泛型?

code review時,注意力放在「怎麼 dispatch」。

後來改成 enum + match,再後來又把 Provider trait 移進 agent-core,重新使用 dyn trait。

回頭看,真正值得留下來的並不是「最後選了 dyn」,而是我後來才意識到:

enum、dyn、generic 是派發問題;Provider trait 放在哪裡,則是架構問題。


第ㄧ版:Provider trait 放 Provider crate

trait Provider {
    async fn stream(
        &self,
        request: ModelRequest,
    ) -> Result<ModelStream>;
}

然後有:Anthropic、Gemini、OpenAI

開始思考哪種派發方式更優雅、效能更好:

enum?
trait?
Box<dyn Provider>?
泛型?

code review 時陷入誤區:著眼於代碼派發方式,潛意識忽略 Provider 依賴關係與抽象邊界

如果 agent-core 的 Agent loop 只需要:

「給我一個東西,我可以把 prompt / tools 交給它,然後取得 model events。」

那麼這個 capability 顯然是 Core 的需求。

依賴關係:正解 vs 第一版

             agent-core
          ┌──────────────┐
          │   Provider   │
          │    trait     │
          └──────▲───────┘
                 │ impl
        ┌────────┼────────┐
        │        │        │
    Anthropic  Gemini   OpenAI
        agent-core
             │
             ▼
        providers
             │
       ┌─────┼─────┐
       ▼     ▼     ▼
    Claude Gemini OpenAI

抽象應該由使用方定義

Core 不應該知道各家模型 impl 如何實現

如果高層模組需要某種能力,那麼高層模組應該定義它所需要的 interface

一般實現:

底層實作
    │
    │ 定義一個 trait
    ▼
高層策略依賴它

Dependency Inversion:

高層策略
    │
    │ 需要某種能力
    ▼
  Trait
    ▲
    │ implements
    │
底層實作

agent-core 只需要定義 Provider trait,底層 Provider 再去實作各家 impl:

impl agent_core::Provider for AnthropicConfig {
    // ...
}

進而讓 Core 脫離 provider 具體實現


Enum & Dyn Trait

Enum

enum 不是錯誤答案。

enum+match 是個人很喜歡的 Rust 寫法:

enum Provider {
    Anthropic(Anthropic),
    Gemini(Gemini),
    OpenAI(OpenAI),
}

match provider {
    Provider::Anthropic(p) => p.stream(...).await,
    Provider::Gemini(p) => p.stream(...).await,
    Provider::OpenAI(p) => p.stream(...).await,
}

優點包括:

  • 沒有 vtable
  • 不需要 trait object
  • 型別資訊完整保留
  • compiler 可以做最佳化
  • pattern matching 很直接

真正的問題:把 enum 搬到 agent-core,Core 還是要知道 Anthropic、Gemini。

沒有真正完成依賴反轉

Dyn Trait

當 Provider trait 位於 agent-core 後:

pub trait Provider {
    async fn stream(
        &self,
        request: ModelRequest,
    ) -> Result<ModelStream>;
}

pub struct Harness {
    provider: Box<dyn Provider>,
}

在這個 interface 上,不要求呼叫端(agent-core 裡驅動 agent loop 的 Harness)知道 concrete type,不被具體impl綁住,從而實現依賴反轉。


Static Dispatch & Dynamic Dispatch

Static dispatch

fn run<P: Provider>(provider: P) {
    // ...
}

compiler 會對不同 P 產生專門化版本:

run::<Anthropic>()
run::<Gemini>()
run::<OpenAI>()
  • compiler 能看見 concrete type
  • 可能 inline
  • 沒有 vtable dispatch
  • 可能產生較大的 binary / compile time

Dynamic dispatch

fn run(provider: Box<dyn Provider>) {
    // ...
}

呼叫時透過 vtable 找到實作。

Box<dyn Provider>
      │
      ├── data pointer
      └── vtable
             │
             └── stream()

多一些間接成本,並伴隨 trait object 的 heap allocation。

但這些成本放回實際場景看 —— 如果一次 Provider 呼叫最後會:

建立 HTTP request
      ↓
網路
      ↓
LLM inference
      ↓
token streaming

那麼一次 vtable dispatch 和一次 Box allocation,效能影響其實不大。


泛型

「Provider 是執行期選擇,所以不能用 泛型」不夠精確,透過 match 分支,可以知道每個Provider的 concrete type(AnthropicConfig/GeminiConfig/…),問題是泛型會如何解「哪個分支會執行」—— 讓每個分支各自呼叫一份泛型函式:

async fn run<P: Provider + 'static>(provider: P, args: Args) -> anyhow::Result<()> {
    let mut harness = Harness::new(provider, ...);  // Harness<P>
    // ...cli::run_cli / tui::run_tui...
}

match choice.as_str() {
    "anthropic" => run(AnthropicConfig { ... }, args).await,
    "gemini"    => run(GeminiConfig { ... }, args).await,
    ...
}

優點:每個分支各自呼叫、各自單態化(monomorphize)— 完全不需要 dyn,Provider 用原生 async fn in trait(不用管 object-safety,也不用 async_trait)。

取捨:型別滲透、程式碼膨脹

為什麼不用泛型 Harness<P: Provider>

一旦 Harness 變成 Harness<P>,所有拿著它的函式簽名都要跟著泛型化,呼叫鏈變成:

run_cli<P: Provider>(...)
run_tui<P: Provider>(...)
run_app<P: Provider>(...)

Provider 這個泛型參數會一路向上或向下滲透整條呼叫鏈。

三個 provider 分支(Anthropic、Gemini、OpenAI)各自 monomorphize,一大坨邏輯在編譯出來的二進位裡變成三份,不是共用一份跑時判斷。

這不一定是壞事,對 CPU-heavy、極度重視 zero-cost abstraction 的程式來說,甚至是不錯的選擇。

但 Agent Core 主要成本在:

  • LLM inference
  • HTTP
  • serialization
  • streaming
  • tool execution

對一個受限於網路 I/O、一次呼叫成本遠大於一次 Box 分配的場景,付出的代價換不到有意義的效能。

因此選擇 dyn Provider,用非常小的 runtime cost(heap allocation),換取

  • Harness 不需要泛型化
  • CLI 不需要泛型化
  • TUI 不需要泛型化

陷入的 Rust 開發思考陷阱

誤區:static dispatch → zero-cost → 一定比較好

真正應該問的是:

為了消除這個 dispatch 在整個 workload 的成本,願意付出多少架構成本?

如果:

dynamic dispatch cost < code complexity + generic propagation + binary growth

那 dyn 可能是更合理的工程選擇。

Zero-cost abstraction 不等於 zero-cost architecture。


Provider 演變總結

dyn      →       enum              →             dyn
         ↓                         ↓
「集合封不封閉?」   →    「Provider abstraction 屬於誰?」

先看 依賴方向 再 判斷集合

  • enum 少一次間接呼叫

  • dyn trait 少一點 compile-time specialization

  • 泛型 讓 compiler 看見 concrete type

都很Rusty,但如果依賴方向錯了,得到的是一個:

效能可能更漂亮,但架構上更難替換、演化的代碼。錯誤的依賴方向比派發方式更難換。


依賴方向是 architecture;派發方式是 implementation detail。

依賴方向與抽象邊界,優先於靜態/動態派發,以及開放/封閉集合所帶來的局部效能最佳化。