クイックスタート：5分で構築するPortkey AI Gateway
面倒なクラウドサービスの登録は不要です。Dockerを使用すれば、Portkey Gatewayのオープンソース版をローカル環境や専用サーバー上に手軽にセルフホストできます。
Portkey Gatewayコンテナをプルし、ポート8787で起動します：
# Dockerでオープンソース版Portkey Gatewayを起動
docker run -d -p 8787:8787 --name portkey-gateway portkeyai/gateway:latest
コンテナの起動後、Gatewayはリバースプロキシとして機能します。OpenAI、Anthropic、Geminiへのすべてのリクエストは、今後http://localhost:8787/v1を経由するようになります。
Python SDKをインストールします：
pip install portkey-ai openai
使い慣れたOpenAI SDKを使って、Gateway経由で最初のリクエストを送信してみましょう：
from openai import OpenAI
# OpenAIクライアントの向き先をローカルのPortkey Gatewayに変更
client = OpenAI(
api_key="sk-your-openai-api-key",
base_url="http://localhost:8787/v1",
default_headers={
"x-portkey-provider": "openai"
}
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "簡潔に説明してください：AI Gatewayとは何ですか？"}]
)
print(response.choices[0].message.content)
base_urlを変更し、x-portkey-providerヘッダーを追加するだけで完了です。バックエンド側のレスポンス処理ロジックは100%そのまま維持できます。
なぜ本番システムでLLM APIを直接呼び出すべきではないのか？
バックエンドコードから直接OpenAIを呼び出すのは、社員全員に会社のクレジットカードを渡して自由に決済させるようなものです。プロバイダー側に障害（500エラーや503エラー）が発生すればアプリケーション全体が停止します。さらに、誤って無限ループ（while True）を走らせてしまえば、たった一晩でAPIの請求額が数千ドルに跳ね上がるリスクもあります。
Portkey AI Gatewayは、アプリケーションとAIモデルの間に位置するゲートキーパーとして機能し、運用上の代表的な4つの課題を根本から解決します：
1. 負荷分散（Load Balancing）とフォールバック（Fallback）
「すべての卵を一つのカゴに盛るな」という原則の通り、単一プロバイダーへの依存は危険です。リクエストの70%をOpenAI、30%をAnthropicへと柔軟に分散できます。万が一OpenAIで429 Too Many Requestsエラーが発生しても、Gatewayが自動的にリクエストをClaude 3.5 SonnetやGemini 1.5 Flashへルーティングします。切り替えはわずか数ミリ秒で行われるため、エンドユーザーがダウンタイムを感じることはありません。
2. 予算上限ガードとレート制限（Rate Limiting）
部署や機能ごとに利用上限を設定できます。例えば、マーケティングチームの社内ボットには「最大60リクエスト/分、日次予算15ドル」といった上限を設けることが可能です。上限に達した場合、Gatewayが水際でリクエストを遮断するため、会社のクレジットカードが予期せぬ請求に晒される心配がなくなります。
3. キャッシュによるコスト削減とレイテンシ改善
ユーザーからの問い合わせには、表現が違っても意図がほぼ同一の質問が多く存在します。Portkeyは完全一致のSimple Cacheに加え、ベクトル検索で質問の意味を解釈するSemantic Cacheの両方に対応しています。過去に回答済みの同義の質問に対しては、GatewayがRedisから直接キャッシュ結果を返却します。レイテンシは2秒から20ミリ秒未満へと劇的に短縮され、トークン費用も一切発生しません。
4. 一元化されたオブザーバビリティ（Observability）
すべてのリクエストについて、ユーザーID、使用モデル、レイテンシ、入出力トークン数などのログが記録されます。プロジェクトごとの費用集計のために、OpenAI、Anthropic、Google Cloudのダッシュボードを別々に開いて確認する手間はもう不要です。
高度な設定：フォールバック、負荷分散、バーチャルキー
Portkey最大の強みは、Config JSONによる制御メカニズムにあります。複雑なルーティングロジックを構成ファイル側に集約できるため、ビジネスロジックのコードを修正する必要がありません。
障害時の自動フォールバック戦略
以下の構成例では、まずGPT-4oを優先して呼び出します。OpenAIが429や5xx系エラーを返した場合、自動的にClaude 3.5 Sonnetへ切り替わります：
import json
from portkey_ai import Portkey
gateway_config = {
"strategy": {
"mode": "fallback"
},
"targets": [
{
"provider": "openai",
"api_key": "sk-openai-key",
"override_params": {"model": "gpt-4o"}
},
{
"provider": "anthropic",
"api_key": "sk-ant-claude-key",
"override_params": {"model": "claude-3-5-sonnet-20241022"}
}
]
}
client = Portkey(
base_url="http://localhost:8787/v1",
config=json.dumps(gateway_config)
)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "第3四半期の財務諸表を要約してください。"}]
)
print(response.choices[0].message.content)
重み付け負荷分散（Weighted Load Balancing）
異なる組織のOpenAIアカウントを複数運用している場合や、TPM（Tokens Per Minute）のクォータ上限を最大限に活用するためにOpenAIとAzure OpenAIの間で負荷分散を行いたい場合の構成です：
{
"strategy": {
"mode": "loadbalance"
},
"targets": [
{
"provider": "openai",
"api_key": "sk-account-tier-4",
"weight": 0.7
},
{
"provider": "azure-openai",
"api_key": "azure-api-key",
"weight": 0.3
}
]
}
この設定により、リクエストの70%がメインアカウントへ、30%がAzure OpenAIへと自動的に振り分けられます。どちらか一方のクォータが枯渇することなく、双方のリソースを最大限に活用できます。
本番環境へPortkeyを導入する際の実践的なノウハウ
1. OpenAIとAzure OpenAIを組み合わせて429エラーを抑制
ピーク時間帯には、ティアの低いOpenAIアカウントは容易にレートリミットの上限に達してしまいます。実践的な対策として、OpenAIをプライマリターゲットに設定し、近隣リージョン（シンガポールや東日本など）のAzure OpenAIをフォールバック先に指定した上で、指数バックオフによる3回のリトライを組み合わせる構成をおすすめします。筆者の運用環境では、この設定によりユーザーへのエラー返却率を約4%からわずか0.02%にまで低減できました。
2. Virtual Key（バーチャルキー）によるアクセス管理
外部委託チームとの協業時などは特に、OpenAIの本番APIキーをそのまま開発者に渡すのは避けるべきです。PortkeyのVirtual Keyを活用すれば、エイリアスとなるキーのみを配布できます。メンバーの離脱や、万が一キーがGitにコミットされてしまった場合でも、Gatewayのダッシュボードからわずか3秒でVirtual Keyを失効させることが可能です。本番稼働中のマイクロサービス全体を停止させることなく、安全に鍵を管理できます。
3. Semantic Cacheでコストを30〜40%削減
カスタマーサポートボットや社内ドキュメント検索チャットボットでは、言い回しが異なっていても質問の意図がほぼ共通しているケースが35〜40%を占めます。PortkeyをRedisやQdrantと連携させ、類似度閾値（threshold）を0.85〜0.9程度に設定してSemantic Cacheを有効化しましょう。トークン費用を半減させつつ、レスポンス速度を最大5倍に向上させることができます。
