FreeLLMAPI

FreeLLMAPIとは？

FreeLLMAPIは、複数のLLMプロバイダーの無料枠アクセスを単一のAPIエンドポイントの背後で集約するOpenAI互換プロキシサーバーです。各プロバイダーごとに別々のSDKを設定したり異なるレート制限を扱ったりする代わりに、OpenAI互換クライアントをプロキシに向け、1つのエンドポイントにリクエストを送信します。

このプロジェクトは個人実験向けに設計されています。約14プロバイダー（プロバイダーアダプタ経由）のキーを集約し、各リクエストを利用可能なモデルにルーティングし、プロバイダーがレート制限やエラーになった際に自動フェイルオーバーを実行します。

主な機能

• OpenAI互換エンドポイント: POST /v1/chat/completions と GET /v1/models を実装。OpenAI SDKや他のOpenAI互換クライアントが base_url を変更するだけで動作します。
• ストリーミング対応: stream: true の場合、サーバーは Server-Sent Events (SSE) でレスポンスを返却。それ以外は標準JSONレスポンスを返します。
• ツール呼び出しパススルー: OpenAIスタイルの tools / tool_choice リクエストをサポートし、アシスタントの tool_calls と以降の tool ロールメッセージをプロバイダーアダプタ経由で転送します。
• 自動フェイルオーバーとリトライ: 選択プロバイダーが 429、5xx を返却またはタイムアウトした場合、ルーターはそのキーを一時的に利用不可としてマークし、フォールバックチェーンの次のプロバイダーでリトライ（最大 20回）。
• キー単位の利用制限追跡: (platform, model, key) ごとに RPM, RPD, TPM, TPD を追跡し、無料枠制限内のキーを選択します。
• スティッキーマルチターンルーティング: 会話を同一モデルに 30分間 維持し、会話途中の切り替えを減らします。
• 暗号化キー保管: 上流プロバイダーキーを AES-256-GCM で暗号化し SQLite に保管。使用直前にメモリ上で復号します。
• 統一プロキシア認証: クライアントは上流プロバイダーキーではなく、単一の freellmapi-... ベアラートークンでプロキシに認証します。
• ヘルスチェックと管理機能: 定期プローブでキーをhealthy/レート制限/無効/エラーとしてラベル付け。付属の管理ダッシュボード（React + Vite）でキー管理、フォールバック優先順位変更、アナリティクス確認、プロンプトプレイグラウンドを実行できます。

FreeLLMAPIの使い方

1. 要件インストール: Node.js 20+ と npm を使用。
2. クローンとインストール:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. 環境設定:
   • 例envをコピー: cp .env.example .env
   • ENCRYPTION_KEY を生成し .env に配置（リポジトリのコマンドでランダム32バイトhexキーを出力）。
4. プロキシ起動: リポジトリのクイックスタート / README に記載のサーバー起動を実行（ページ抜粋にセットアップ手順あり、リポジトリドキュメントに正確な起動コマンド）。
5. OpenAI互換クライアント設定:
   • クライアントの base_url をローカルFreeLLMAPIサーバーに設定。
   • プロキシのベアラートークン（freellmapi-...）で認証し POST /v1/chat/completions を呼び出し（stream: true 可）。

ユースケース

• プロバイダー横断のチャットテスト: 既存のOpenAI互換アプリ（またはライブラリ）をプロキシに向け、別SDK管理なしで多数のモデルを試せます。
• 手動レート制限回避の削減: 429/5xx/タイムアウトを返すプロバイダーを自動スキップし、設定フォールバック順の次のモデルでリクエスト継続。
• ツール使用チャットフロー: tool_calls とツール結果メッセージを同一プロキシフローを経由でルーティングするOpenAIスタイルツール呼び出しを実行。
• 長時間会話の一貫性: アクティブ使用中は同一モデルを維持（30分スティッキーセッション）し、プロバイダー不可時はフォールバック活用。
• 暗号化キー管理のローカル実験: 上流キーをプロキシ内に暗号化保管（at-rest）し、クライアントアプリでプロバイダーキー露出不要。

FAQ

• FreeLLMAPIは完全なOpenAI APIをサポートしますか？ いいえ。チャット補完とモデルリスト（/v1/chat/completions、/v1/models）に特化。エンベディング、画像、音声/スピーチ、マルチモーダル入力は未サポート。レガシー /v1/completions、モデレーション、多重補完も同様。

• FreeLLMAPIはレート制限をどう扱いますか？ キー単位の利用カウンタ（RPM/RPD/TPM/TPD）を追跡し、制限内のキーを選択。プロバイダーが429（または5xx/タイムアウト）を返した場合、ルーターはフォールバックチェーンの次のプロバイダーでリトライ。

• ストリーミングは私のクライアントで動作しますか？ はい。チャットエンドポイントで stream: true 時に SSE 経由でストリーミングをサポート。

• 既存のOpenAI互換ライブラリを使えますか？ 公式OpenAI SDKや他のOpenAI互換クライアントをプロキシの base_url に向けることで動作するよう設計。

• 本番運用向けですか？ リポジトリで明示的に「個人実験専用」と記載。

代替案

• 単一プロバイダを直接使用: 多くのサービスが独自のAPIを提供し一貫したセマンティクスがありますが、マルチプロバイダ集約、自動フェイルオーバー、無料枠の積み重ねが1つのエンドポイントで得られません。
• 独自のルーター/フォールバック層を構築: カスタムプロキシでフェイルオーバーとキー回転を実装できますが、プロバイダ固有のSDK、制限、エラーハンドリングを自分で管理する必要があります。
• 複数LLMバックエンドをサポートするオーケストレーションフレームワークを使用: 一部のツールが異なるモデルプロバイダにリクエストをルーティングしますが、ワークフローが異なり（ここで説明したOpenAI互換の/v1/chat/completionsプロキシ動作を提供しない場合があります）。
• 手動でのキー・モデル切り替え: アプリケーションで手動でプロバイダを選択できますが、FreeLLMAPIが提供する自動リトライ/フェイルオーバーとキー単位のレート追跡が失われます。