119 lines
6.7 KiB
Markdown
119 lines
6.7 KiB
Markdown
# LLM モデル設定の再編
|
||
|
||
## 背景
|
||
|
||
決定済みの LLM プロバイダサポート方針（`docs/plan/llm_providers.md`）に従って llm-worker のプロバイダ層を再編する。Pod 側で「使う LLM モデル」を宣言する構造にし、共通の通信層 + scheme の組合せで任意のプロバイダを収容できるようにする。
|
||
|
||
### 現状の問題
|
||
|
||
- `crates/llm-worker/src/llm_client/providers/{anthropic,openai,gemini,ollama}.rs` は各々 HTTP 骨格 + scheme 呼び出しの薄いアダプタで、構造が重複
|
||
- `providers/ollama.rs` (67行) は scheme 未分離で整合性が崩れている
|
||
- OpenAI 互換ルーター系（xAI / Groq / OpenRouter / Together / BLACKBOX 等）を追加するたびに新ファイルを書く必要がある
|
||
|
||
## 要件
|
||
|
||
1. **Pod マニフェストで LLM モデルを宣言できる**
|
||
|
||
```
|
||
ModelConfig {
|
||
scheme: Scheme, // Anthropic / OpenAIChat / OpenAIResponses / Gemini
|
||
base_url: Url,
|
||
model_id: String,
|
||
auth: AuthRef,
|
||
}
|
||
```
|
||
|
||
継承（commit ebee0b9）と整合し、親 Pod の定義を子 Pod が override 可能。
|
||
|
||
2. **`providers/` 層の廃止**: llm-worker は `HttpTransport<S: Scheme>` 相当の汎用通信層 1 本を持ち、`ModelConfig` を食わせてインスタンス化する
|
||
|
||
3. **既存 scheme の再編**:
|
||
- `scheme/openai` を `scheme/openai_chat` にリネーム
|
||
- `scheme/anthropic` / `scheme/gemini` はそのまま
|
||
- `scheme/openai_responses` は別チケット（llm-scheme-openai-responses）で新設
|
||
- Ollama は **scheme/anthropic を base_url 差し替えで流用**（独自 scheme は作らない）
|
||
|
||
4. **認証の分離**: `AuthRef` は `ApiKey(EnvVar | ConfigRef)` / `CodexOAuth` / `None` を表現でき、scheme とは直交する層で管理される。`CodexOAuth` の実装自体は別チケット（llm-auth-codex-oauth）
|
||
|
||
5. **決定済みプロバイダ方針との整合**:
|
||
- 第一級: Ollama / Codex OAuth / Anthropic API
|
||
- 二次: OpenAI 互換共通枠（`{ scheme: OpenAIChat, base_url: 各社, auth: ApiKey }` の宣言だけで収容）
|
||
|
||
6. **ModelCapability を分離**: モデルに紐づく機能差を別メタデータとして表現
|
||
|
||
```
|
||
ModelCapability {
|
||
tool_calling: ToolCallingSupport, // parallel 可否含む
|
||
structured_output: StructuredOutput, // JsonObject / JsonSchema
|
||
reasoning: Option<ReasoningSupport>, // effort / budget_tokens
|
||
vision: bool,
|
||
prompt_caching: CacheStrategy, // Explicit { max_breakpoints } / Auto
|
||
}
|
||
```
|
||
|
||
`ReasoningControl { effort, budget_tokens }` は共通型、scheme アダプタで各社形式に投影。プロバイダ側高次ツール（web_search 等）は採用しないため軸から除外。
|
||
|
||
7. **Streaming は現状維持**: 既存 `BlockStart / BlockDelta / BlockStop / BlockAbort` + `DeltaContent::{Text, Thinking, InputJson}` を変更しない。Gemini や Ollama のように ToolCall 引数 delta を送らないプロバイダは scheme アダプタで「BlockStart → InputJson(全体 1 回) → BlockStop」の擬似ストリーム化で吸収
|
||
|
||
8. **Ollama 運用の注意点**: scheme/anthropic 流用前提で以下を守る
|
||
- `cache_control` は送らない（`ModelCapability::prompt_caching = Auto`）
|
||
- `tool_choice` / `metadata` / URL 画像は送らない（Ollama 側非対応）
|
||
- `/v1/messages/count_tokens` は叩かない（issue #13949 でサーバ不安定化）
|
||
- `/v1/chat/completions` は stream+tools バグ (#9092) のため使わない
|
||
|
||
9. **完了時の動作**: 既存の動作は変わらず、Pod マニフェストで `ModelConfig` を宣言するだけでモデル切替できる。OpenAI 互換の新規プロバイダは新コードなしで追加可能
|
||
|
||
## 設計決定
|
||
|
||
### 1. `Scheme` trait の境界（方針A: 全面抽象化）
|
||
|
||
trait で URL 組立・認証要件・body 変換・SSE パースをすべて抽象化し、`HttpTransport` は 1 本にする。trait スケッチ:
|
||
|
||
```rust
|
||
trait Scheme {
|
||
fn path(&self, model: &str) -> String; // "/v1/messages" 等
|
||
fn required_auth(&self) -> AuthRequirement; // Bearer / XApiKey / QueryParam / None
|
||
fn additional_headers(&self) -> Vec<(&str, String)>; // anthropic-version 等
|
||
fn build_request_body(&self, model: &str, req: &Request, cap: &ModelCapability) -> Value;
|
||
fn parse_sse(&self, event_type: &str, data: &str) -> Result<Vec<Event>, ClientError>;
|
||
fn default_base_url(&self) -> &'static str;
|
||
}
|
||
```
|
||
|
||
`parse_sse` は `Vec<Event>` に統一（Anthropic は 1 要素 Vec で扱う）。
|
||
|
||
### 2. `AuthRef` と `Scheme` の組合せ検証（方針B: 構築時検証）
|
||
|
||
`Scheme::required_auth()` で要求する `AuthRequirement` を宣言し、`build_client` 時に `AuthRef` と照合。非対応組合せは構築エラーにする（実行時に落とさない）。
|
||
|
||
### 3. `crates/provider/` の去就（方針A: 残す）
|
||
|
||
`provider` クレートは保持。`build_client(ModelConfig) -> Box<dyn LlmClient>` は `(Scheme, AuthRef)` 照合 + `HttpTransport::new` の薄ラッパーに縮退する。`~/.codex/auth.json` 読み取り等の認証ストア解決は `provider` クレートに肉付けしていく（llm-worker は低レベル基盤に留める方針と整合）。
|
||
|
||
### 4. `ModelCapability` の保持（方針: ハイブリッド）
|
||
|
||
- scheme 実装側に `model_id → ModelCapability` の静的テーブルを持つ（既知モデル分）
|
||
- `ModelConfig` で明示宣言すれば override
|
||
- 未知モデルは scheme ごとの安全側デフォルト（`prompt_caching: Auto` 等）にフォールバック
|
||
|
||
今チケットのスコープ:
|
||
- 型定義 + 既知モデルの固定値
|
||
- `CacheStrategy::Explicit` で `cache_control` マーカー挿入（既存実装を capability で分岐）
|
||
- `ReasoningControl { effort, budget_tokens }` を scheme 側で各社形式に投影
|
||
- `CacheStrategy::Auto` は何もしない（Ollama で重要）
|
||
|
||
### 5. マニフェスト継承との統合（方針: フィールド単位 override）
|
||
|
||
`ProviderConfigPartial` と同じ方針で、`ModelConfig` の全フィールド（`scheme` / `base_url` / `model_id` / `auth`）を `Option<T>` で継承。子 Pod は `base_url` だけ差し替える等が可能。
|
||
|
||
### 6. TOML 後方互換
|
||
|
||
旧 `[provider] kind = "..."` フォーマットは互換を切る。新 `[model]` セクションで `scheme` / `base_url` / `model_id` / `auth` を宣言する。
|
||
|
||
## Scope 外
|
||
|
||
- OpenAI Responses scheme の新設（`tickets/llm-scheme-openai-responses.md`）
|
||
- Codex OAuth 認証アダプタの実装（`tickets/llm-auth-codex-oauth.md`）
|
||
- OpenAI 互換ルーター各社の動作確認
|
||
- プロバイダ選択 UI（将来の native GUI / TUI 拡張）
|