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

独自キーの持ち込み(BYOK)

組織は、上流プロバイダの独自キーを持ち込めます。モデルが組織の資格情報を通る経路になると、ゲートウェイはプラットフォームの資格情報ではなく、その組織のキーでプロバイダに認証します。クライアントは同じゲートウェイキー(yb_…)を使い続けます。クライアント側の変更は不要です。

キーを追加できる人​

管理コンソールの組織管理者です。場所は Settings → Provider keys です。すべてのキーは追加した組織に属し、その組織のトラフィックにだけ使われます。

対応プロバイダ​

プロバイダレジストリ種別base_url注記
OpenAIopenaihttps://api.openai.com/v1
Anthropicanthropichttps://api.anthropic.comMessages API
Z.AI (Coding Plan)zai-codinghttps://api.z.ai/api/coding/paas/v4エンドポイントはアダプタが固定します。YABANIN_ZAI_CODING_ENABLED を有効にしてください(プロバイダ を参照)
vLLMopenai-compathttp://<host>:8000/v1OpenAI 互換サーバ
Ollamaopenai-compathttp://<host>:11434/v1Ollama の OpenAI 互換エンドポイント
カスタムopenai-compat任意の HTTPS の OpenAI 互換 base_urlllama.cpp、LM Studio、ゲートウェイ、…

キーの追加​

  1. 組織管理者として管理コンソールにサインインします。
  2. Settings → Provider keys に移動し、Add key をクリックします。
  3. Name(例: prod-openai)、Provider、Base URL、プロバイダの API key を入力します。
  4. 保存します。コンソールは直ちに last-4 マスクだけを表示します。平文は二度と表示されません。
  5. 任意: Test connection は、コンソールから登録済みの base URL へ、保護されたプローブを送ります(組織ごとにレート制限されます。サーバはテスト履歴を保持しません)。
  6. そのプロバイダのモデルへリクエストを経路付けします。ゲートウェイは組織キーで上流に認証します。

Ollama の例​

base_url は http://127.0.0.1:11434/v1、プロバイダは openai-compat です。ゲートウェイがコンテナ内で動く場合(クイックスタートの compose)、代わりにホストのループバックである http://host.docker.internal:11434/v1 を指します。

資格情報の解決​

リクエストが上流の資格情報を必要とするとき、ゲートウェイは次の順で解決します。

順序階層使われる条件
1組織キー(BYOK)リクエスト元の組織が Settings → Provider keys に、プロバイダと上流 base URL(完全一致、または /v1 を除いた形)に一致する有効なキーを持っている。最新の一致が優先されます。
2モデルごと組織キーが一致しなかった場合。モデルレジストリ項目に固定された資格情報です。
3グローバル上記のどちらでもない場合。ゲートウェイに設定されたプラットフォーム全体の資格情報です。

3つの階層すべてで、経路、予算、リネージ、監査は同じです。異なるのは上流の認証だけです。

保存されるものと見えるもの​

  • 保存されるもの: 暗号化された暗号文(api_key_ct)と last-4 マスクだけです。それ以外はありません。保管時の平文コピーは存在しません。
  • コンソールと管理 API で見えるもの: 名前、プロバイダ、base_url、last-4 マスクです。キーそのものは見えません。
  • 平文はリクエスト時にメモリ上でのみ使われます。ログには残らず、作成後に API が返すこともありません。
  • 組織の分離(RLS): キー行は行レベルセキュリティのもとで、その組織にスコープされます。別の組織は見ることや解決することはできません。

トラブルシューティング​

  • http の base_url が拒否される。 リモートのプロバイダは https:// を使う必要があります。平文の http:// が受け入れられるのは、ローカルの Ollama と vLLM が動くように、ループバックホスト(127.0.0.1、localhost)だけです。平文 http のリテラルなプライベート IP エンドポイント(vLLM、TGI)を登録するオンプレミス導入では、管理サーバに YABANIN_ORG_CRED_ALLOW_HTTP_PRIVATE=1 を設定できます。ホスト名の対象はどのモードでも https のみのままです。予約済み範囲(ループバック、リンクローカル / メタデータ)はダイヤル時に禁止されたままです。リモートのものには前段に TLS を置いてください。DNS と TLS のランブック を参照してください。
  • キーが解決されない。 解決順をたどります。(1) 組織は Settings → Provider keys に、有効で一致するキーを持っているか。プロバイダが一致し、base URL がモデルの上流 URL(または /v1 を除いた形)と等しいか。(2) モデルレジストリ項目のモデルごとの資格情報が、それを覆い隠していないか。(3) グローバル資格情報は存在するか。誤っている最初の階層を直します。
  • 別の組織からキーが見えない。 設計どおりです。RLS はすべてのキー行をその組織にスコープします。キーを所有する組織にサインインしていることを確認してください。

スタンドでの確認​

  1. make quickstart-up && make quickstart-seed — スタンドを立ち上げます。表示された管理者パスワードと API キーを保管します。
  2. http://127.0.0.1:8086 を開き、admin@localhost としてサインインします。
  3. Settings → Provider keys → Add key: 名前 local-ollama、プロバイダ openai-compat、base_url http://host.docker.internal:11434/v1、キー ollama。保存された行には名前、base_url、last-4 マスクが表示されます。キーそのものは表示されません。
  4. シードされたキーで、ゲートウェイ経由のチャットを行います。curl -sS -H "Authorization: Bearer yb_…" -H "Content-Type: application/json" -d '{"model":"<ollama-backed registry model>","messages":[{"role":"user","content":"ping"}]}' http://127.0.0.1:8082/v1/chat/completions → 200 となり、Ollama がリクエストをログに残します(組織キーが上流で認証した証明です)。
  5. 否定確認: base_url http://10.0.0.1:8000/v1 のキー追加を試します → デフォルトでは拒否されます(ループバックを超えた平文 http。導入が YABANIN_ORG_CRED_ALLOW_HTTP_PRIVATE=1 を設定している場合を除きます)。
  6. 否定確認: 2つ目の組織としてサインインします → Provider keys は空です(RLS)。
  7. 組織キーを削除して手順 4 を繰り返します。リクエストは依然として解決されます(モデルごと / グローバル階層経由)。手順 4 が組織キーを使っていたことの確認です。

制限​

  • BYOK が変えるのは上流の認証だけです。ゲートウェイのクライアントキー(yb_…)、予算、方針、監査は変わりません。
  • キー素材はエクスポート、再ダウンロード、組織間の移動ができません。
  • Last-4 は表示用マスクにすぎず、キーが有効である証明にはなりません。