架構
最後更新
go-llm-router 分成三層：契約層（core）、組裝層（core/router）、供應商轉接層（各 provider 套件）。本頁只放整體層級關係，模組級展開、序列圖與狀態機在 完整架構文件。
概覽
graph TB
App[呼叫端] --> Router[router.New]
Router --> Registry[newFn 前綴表]
Registry --> KeyAgents[金鑰型 Agent]
Registry --> OAuthAgents[OAuth 型 Agent]
Registry --> CompatAgent[compat Agent]
KeyAgents --> Core[core 契約層]
OAuthAgents --> Core
CompatAgent --> Core
OAuthAgents --> OAuth[core/oauth]
OAuth --> Keychain[go-pkg keychain]
Core --> Stream[串流事件正規化]
Core --> Usage[用量正規化]
Core --> Media[圖片 / 語音介面]
分層
| 層 | 套件 | 職責 | 相依方向 |
|---|---|---|---|
| 契約層 | core |
Agent 介面、訊息與用量型別、推理等級、模式、模型分類、SSE 正規化、多模態選用介面 | 不相依任何 provider |
| 組裝層 | core/router |
由 provider@model 查表建構 Agent；未知前綴改寫為 compat |
相依 core 與全部 provider |
| 轉接層 | core/claude、core/openai、core/gemini、core/grok、core/deepseek、core/mistral、core/nvidia、core/ollamaCloud、core/openRouter、core/cloudflare、core/compat、core/copilot、core/openaiCodex、core/grokOauth |
訊息轉換、線路格式差異、模型清單、選用能力 | 相依 core 與共用傳輸輔助 |
| 共用傳輸輔助 | core/copilot/response、core/xai |
Responses API 輸入／工具／輸出轉換；xAI Responses 請求 body 與 SSE 組裝 | 相依 core |
| 憑證層 | core/oauth/copilot、core/oauth/codex、core/oauth/grok |
登入流程、權杖保存與換新 | 相依 core 與 go-pkg keychain |
轉接層分群
| 群組 | 套件 | 線路格式 |
|---|---|---|
| OpenAI 相容 | openai、deepseek、mistral、nvidia、openRouter、ollamaCloud、cloudflare、compat |
Chat Completions；OpenAI 新世代模型改走 Responses |
| Anthropic | claude |
Messages API，thinking 預算換算 |
gemini |
:generateContent，工具以 parametersJsonSchema 傳送原始 JSON Schema，並使用 cachedContents 前綴快取 |
|
| xAI | grok、grokOauth |
由 core/xai 組出的 Responses API + 圖片端點 |
| OAuth 代理 | copilot、openaiCodex |
廠商內部 Responses 端點，需 session 權杖 |
跨切原則
| 原則 | 內容 |
|---|---|
| 單向相依 | 轉接層相依 core 與共用傳輸輔助（openai、codex、copilot 用 core/copilot/response；兩個 Grok 轉接層用 core/xai）。轉接層之間的例外僅兩處：grokOauth 共用 grok.RequestImage、openaiCodex 共用 openai 的圖片 helper |
| 能力以介面表達 | 串流、推理上下限、圖片、STT、TTS 皆為選用介面，不用旗標或設定欄位表示 |
| 錯誤帶狀態碼 | Send 回傳上游 HTTP 狀態；串流錯誤包成 *llmrouter.StreamError 保留 Provider / Code / Body |
| 讀取上限固定在契約層 | 串流 body 64 MiB、錯誤 body 8 KiB、錯誤 frame 512 bytes、JSON body 64 KiB，由 core 統一定義 |
| HTTP client 共用 | llmrouter.NewHTTPClient 提供 10 分鐘 timeout；codex 與 grok-oauth 另建帶 15 秒 response header timeout 的 client |