プロバイダ連携ガイド
概要
Yabanin は、上流の LLM API を provider.Provider インターフェース(pkg/provider/provider.go)の背後に抽象化します。すべてのプロバイダは、5 つの操作をサポートします。
| メソッド | 目的 |
|---|---|
Name() | 正規識別子("openai"、"anthropic"、"custom") |
Path(stream bool) | HTTP エンドポイントパ ス(/v1/chat/completions または /v1/messages) |
PrepareRequest(ctx, baseURL, path, body, apiKey, stream) | URL、ヘッダー(Auth、version、beta)、content-type を設定します |
TranslateRequest(openaiBody) | OpenAI JSON → プロバイダネイティブのスキーマ |
TranslateResponse(providerBody) | プロバイダネイティブの JSON → OpenAI の ChatCompletion 形状 |
ParseUsage(respBody) | prompt/completion/cache のトークンを抽出します |
StreamHandler | リアルタイムの SSE 変換(pkg/provider/stream.go 経由) |
アダプタファクトリ(pkg/provider/factory.go)は、実行時に New(name) でプロバイダ名を解決します。上流プール(pkg/upstream/pool.go)は、(provider, URL) ペアごとに 1 つの *Client を作り、それぞれが独自のアダプタを持ちます。
Z.AI GLM Coding Plan(zai-coding)
https://api.z.ai/api/coding/paas/v4 に固定された、OpenAI 互換の Coding Plan アダプタです。YABANIN_ZAI_CODING_ENABLED=true で有効にします。glm-5.3 などのモデルを provider: zai-coding で登録します。upstream_url は無視されるため、クォータが PAYG や任意のホストへ漏れることはありません。フィーチャーフラグはデフォルトでオフです。OpenCode の例: examples/opencode.json。
新しいプロバイダの追加
- アダプタを作成する —
Providerの 6 つのメソッドすべてを実装するpkg/provider/<name>.go。 - ファクトリに登録する —
New(name)に case を追加し、アダプタを返します。 - DB 制約を更新する —
chk_providerに新しい型を追加するマイグレーションを実行します。 - 管理 UI に追加する — モデルの CRUD は、すでに
providerフィールドを受け付けます。コード変更は不要です。 - テストを書く — すべてのイベント型について、TranslateRequest、TranslateResponse、ParseUsage、StreamHandler。
- 結合テスト —
pkg/testutil/mock<name>経由のエンドツーエンド(下記を参照)。 - 料金を追加する —
pkg/pricing/pricing.goの表を"provider:model"キーで拡張します。
変換パターン
システムメッセージの扱い
| プロバイダ | システムメッセージの位置 |
|---|---|
| OpenAI | messages[] 内の {role:"system", content:"..."} |
| Anthropic | トップレベルの system フィールド(文字列、または cache_control 付きの配列) |
| Gemini | リクエストボディ内の systemInstruction: {parts:[...]} |
ツール形式
| プロバイダ | スキーマフィールド | 関数宣言 |
|---|---|---|
| OpenAI | parameters(JSON Schema) | tools[] 内の function |
| Anthropic | input_schema(JSON Schema) | tools[] 内の input_schema + name / description |
| Gemini | N/A | contents 内の functionDeclarations[] |
ストリーミングイベントの対応
| プロバイダ | ネイティブイベント | OpenAI チャンク相当 |
|---|---|---|
| Anthropic | message_start | {choices:[{delta:{role:"assistant", content:""}}]} |
| Anthropic | content_block_delta(text) | {choices:[{delta:{content:"..."}}]} |
| Anthropic | message_stop | data: [DONE]\n\n |
| Anthropic | error | message 付きの error イベント |
新しいプロバイダのテストチェックリスト
- TranslateRequest が対象に含むもの: system、マルチターン会話、ツール使用、構造化コンテンツ、cache_control ブロック
- TranslateResponse: 単一の choice、複数の choice(サポートされる場合)、usage 節
- ParseUsage: prompt_tokens、completion_tokens、total、cache_read、cache_creation — すべて計上します
- StreamHandler: すべてのネイティブイベント型を OpenAI の SSE チャンクへ変換し、
[DONE]で終端します - 結合テスト をモックサーバー(
pkg/testutil/mock<name>)で行います — ゲートウェイ経由のエンドツーエンド 200 レスポンス - 結合エラーマッピング: 4xx エラー →
error.messageとerror.typeを持つ、適切な OpenAI エラー形状 - ヘルスプローブ: プロバイダの
/healthまたは/v1/modelsエンドポイントは、有効なヘルスチェック対象です - 料金表 を
pkg/pricing/pricing.goで、現在の 100 万トークンあたりの料金に更新します
モックサーバーのパターン
結合テストには、pkg/testutil/mockopenai または pkg/testutil/mockanthropic を使います。
srv := mockopenai.New()
ts := httptest.NewServer(srv)
defer ts.Close()
// Configure response
srv.SetResponse(200, `{"id":"test","choices":[...]}`)
// Or simulate rate-limiting then success
srv.FailFirstN(2, 429, "rate limited")
srv.SetResponse(200, `{"id":"ok","choices":[...]}`)
// For streaming endpoints
srv.SetStreamMode(true)
srv.SetResponse(200, `{"delta":{"content":"Hello"}}\n\n`)
// Verify what was sent
recs := srv.Requests() // []Request with Method, URL, Header, Body, Path
assert.Equal(t, "my-key", recs[0].Header.Get("Authorization"))
同じパターンが mockanthropic にも当てはまります。レスポンスボディには MessagesJSON() または MessagesJSONWithCache() を使います。
プロンプトキャッシュ
プロンプトキャッシュをサポートするプロバイダ(Anthropic)の場合:
- アダプタは、メッセージのコンテンツブロック内にある
"cache_control"キーを検出します - 存在するとき、
PrepareRequestがanthropic-beta: prompt-caching-2024-07-31ヘッダーを自動で追加します - キャッシュトークンは
ParseUsageで解析され、pkg/pricing/のComputeCostを通して別途課金されます