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