メインコンテンツまでスキップ

プロバイダ連携ガイド

概要​

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。


新しいプロバイダの追加​

  1. アダプタを作成する — Provider の 6 つのメソッドすべてを実装する pkg/provider/<name>.go。
  2. ファクトリに登録する — New(name) に case を追加し、アダプタを返します。
  3. DB 制約を更新する — chk_provider に新しい型を追加するマイグレーションを実行します。
  4. 管理 UI に追加する — モデルの CRUD は、すでに provider フィールドを受け付けます。コード変更は不要です。
  5. テストを書く — すべてのイベント型について、TranslateRequest、TranslateResponse、ParseUsage、StreamHandler。
  6. 結合テスト — pkg/testutil/mock<name> 経由のエンドツーエンド(下記を参照)。
  7. 料金を追加する — pkg/pricing/pricing.go の表を "provider:model" キーで拡張します。

変換パターン​

システムメッセージの扱い​

プロバイダシステムメッセージの位置
OpenAImessages[] 内の {role:"system", content:"..."}
Anthropicトップレベルの system フィールド(文字列、または cache_control 付きの配列)
Geminiリクエストボディ内の systemInstruction: {parts:[...]}

ツール形式​

プロバイダスキーマフィールド関数宣言
OpenAIparameters(JSON Schema)tools[] 内の function
Anthropicinput_schema(JSON Schema)tools[] 内の input_schema + name / description
GeminiN/Acontents 内の functionDeclarations[]

ストリーミングイベントの対応​

プロバイダネイティブイベントOpenAI チャンク相当
Anthropicmessage_start{choices:[{delta:{role:"assistant", content:""}}]}
Anthropiccontent_block_delta(text){choices:[{delta:{content:"..."}}]}
Anthropicmessage_stopdata: [DONE]\n\n
Anthropicerrormessage 付きの 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 を通して別途課金されます