メインコンテンツへ移動
AIチュートリアル

One APIの導入・利用チュートリアル：統一OpenAI APIでさまざまな大規模モデルに接続

本チュートリアルでは、One APIの導入、モデルチャネルの追加、アクセストークンの作成、OpenAI互換インターフェースを利用したさまざまな大規模モデルの呼び出し方法を解説します。さらに、データベース、キャッシュ、ロードバランシング、複数マシンでのデプロイに関するポイントも紹介します。

約19分で読了
One APIの導入・利用チュートリアル：統一OpenAI APIで大規模モデルに接続

One API とは

One API は、オープンソースの大規模モデル API 管理・リレーシステムです。異なるモデルプロバイダーのインターフェースを標準の OpenAI API 形式に統一し、クライアントから同じ API Base とアクセストークンを使って複数の上流チャネルを呼び出せるようにします。

OpenAI と Azure OpenAI、Anthropic Claude、Google Gemini、Mistral、豆包、文心一言、通義千問、訊飛星火、ChatGLM、腾讯混元、Moonshot AI、DeepSeek、Ollama、Cohere、Groq、Cloudflare Workers AI、xAI など、さまざまなサービスに対応しています。

コンプライアンスに関する注意：One API の使用時は、OpenAI の利用規約および適用される法令を遵守し、違法な用途に使用してはなりません。中国地域の一般ユーザーに対して、届出のない生成 AI サービスを提供しないでください。

主な機能

  • 統一インターフェース：OpenAI 互換 API 形式で、さまざまな大規模モデルにアクセスできます。

  • 複数チャネルと負荷分散：複数の上流チャネルを設定でき、チャネルを指定しない場合は自動的に負荷分散します。

  • ストリーミング出力：stream モードに対応し、タイプライター形式の応答を実現できます。

  • トークン管理：有効期限、利用枠、許可する IP 範囲、アクセス可能なモデルを設定できます。

  • チャネル管理：チャネルの一括作成、モデル一覧の設定、チャネルグループ化、モデルマッピングに対応しています。

  • 利用枠と請求：利用枠の詳細、ユーザーグループ、チャネルグループ、倍率、米ドル建て利用枠の表示に対応しています。

  • 信頼性：失敗時の自動リトライ、複数サーバーへのデプロイ、Redis キャッシュ、データベース接続設定に対応しています。

  • 管理機能の拡張：システムアクセストークンで管理 API を呼び出せるため、ソースコードを変更せずに管理機能を拡張できます。

  • ユーザーシステム：メール、Feishu、GitHub、WeChat 公式アカウントなどによるログイン・登録に対応しています。

  • インターフェースのカスタマイズ：システム名、Logo、フッター、ホームページ、概要ページ、テーマをカスタマイズできます。

Docker で迅速にデプロイする

データディレクトリを準備する

SQLite は、迅速な試用や低同時実行数のデプロイに適しています。まず書き込み可能なデータディレクトリを用意します。データベースとログはこのディレクトリに保存されます。

mkdir -p /home/ubuntu/data/one-api

One API を起動する

docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

-p 3000:3000 の左側のポートはホスト側のポートなので、必要に応じて変更できます。起動後、http://localhost:3000/ にアクセスします。

初期ユーザー名は root、初期パスワードは 123456 です。

重要：初回に root でログインしたら、すぐにデフォルトパスワードを変更してください。

Docker Hub からイメージを取得できない場合は、justsong/one-api を ghcr.io/songquanpeng/one-api に置き換えてください。コンテナの起動に失敗する場合は、プロジェクトの Issue 記録を参考に --privileged=true の追加を試してください。

MySQL を使用してデプロイする

同時実行数が多い場合、README では SQL_DSN を設定し、SQLite を使い続けないことを明確に推奨しています。データベース oneapi は事前に作成する必要がありますが、テーブルはプログラムが自動的に作成します。

docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

ユーザー名、パスワード、アドレス、ポートを実際のデータベース設定に置き換えてください。MySQL がホスト上で動作している場合は、ネットワーク環境に応じて --network="host" を追加すると、コンテナからホストのデータベースにアクセスできます。

Docker Compose を使用する

リポジトリには Docker Compose による起動方法が用意されています。現在の説明では MySQL を使用し、データを ./data/mysql ディレクトリに保存します。

docker-compose up -d
docker-compose ps

ソースコードから手動でデプロイする

自分でビルドする場合は、Node.js、npm、Go の環境を準備し、フロントエンドとバックエンドを順にビルドします。

git clone https://github.com/songquanpeng/one-api.git
cd one-api/web/default
npm install
npm run build

cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

ビルド完了後、実行権限を付与してサービスを起動します。

chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

--port はリッスンポートを指定するために使用し、デフォルト値は 3000 です。--log-dir はログディレクトリを指定します。--version でバージョンを確認し、--help でヘルプを表示することもできます。

基本設定を完了する

  1. One API の管理ページを開き、root アカウントでログインしてデフォルトパスワードを変更します。

  2. チャネルページに移動し、対応するプロバイダーの種類を選択して上流 API Key を追加します。

  3. 上流の機能に応じて、チャネルがサポートするモデル一覧とグループを設定します。

  4. トークンページに移動し、クライアント用のアクセストークンを作成します。

  5. 必要に応じて、トークンの利用枠、有効期間、許可する IP 範囲、アクセス可能なモデルを設定します。

One API はそのまま使用できます。その他の設定は、管理画面、環境変数、.env ファイル、またはコマンドライン引数で行えます。.env を使用する場合は、リポジトリの .env.example を参考にして .env に名前を変更してください。

OpenAI 互換インターフェースを使用する

クライアントの API Base には One API のデプロイ先アドレスを設定し、API Key には先ほど作成した One API トークンを設定します。具体的な Base URL の形式はクライアントによって異なります。OpenAI 公式ライブラリの場合、README に記載されている設定形式は次のとおりです。

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"

リクエストはまず One API に到達し、その後 One API によって OpenAI、Azure、その他のモデルチャネルへ転送されます。インターフェース形式が異なる上流に対しては、One API が中継に必要なリクエストボディとレスポンスボディの変換を処理します。

既存のクライアントと連携する

カスタム OpenAI インターフェースアドレスに対応するクライアントの多くを接続できます。ChatGPT Next Web を例にすると、まずクライアントコンテナを実行します。

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

次に、クライアント画面で One API のインターフェースアドレスと One API トークンを入力します。ポートは One API が使用する 3000 と競合しないようにしてください。

ChatGPT Web も環境変数を使って One API に接続できます。

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.example.com -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

サンプルのドメインとトークンを自分の設定に置き換えてください。

高度な設定のヒント

チャネルを指定する、または負荷分散を有効にする

デフォルトでは、チャネルを指定しないリクエストは複数の利用可能なチャネル間で負荷分散されます。管理者が作成したトークンでは、トークンの末尾にチャネル ID を追加して、今回のリクエストを特定のチャネルで処理するよう強制することもできます。

Authorization: Bearer ONE_API_KEY-CHANNEL_ID

一般ユーザーが作成したトークンでは、この方法でチャネル ID を指定できません。

モデルマッピングは慎重に使用する

モデルマッピングを使うと、ユーザーがリクエストしたモデルを別のモデルへリダイレクトできます。ただし README では、必要がなければモデルマッピングを設定しないよう注意しています。有効にするとリクエストボディがそのまま転送されず、再構築されるため、まだ正式にサポートされていない一部のフィールドを正常に転送できない可能性があります。

Redis キャッシュを使用する

REDIS_CONN_STRING を設定すると、One API は Redis をキャッシュとして使用します。

REDIS_CONN_STRING=redis://default:redispw@localhost:49153

データベースへのアクセス遅延が非常に小さい場合は、キャッシュによってデータ同期の遅延が発生する可能性があるため、Redis を有効にする必要はありません。Sentinel またはクラスター構成では、この変数にノード一覧を設定し、REDIS_PASSWORD と REDIS_MASTER_NAME を併用できます。

データベース接続を最適化する

データベース接続は、次の環境変数で調整できます。

  • SQL_MAX_IDLE_CONNS：最大アイドル接続数。デフォルトは 100。

  • SQL_MAX_OPEN_CONNS：最大オープン接続数。デフォルトは 1000。

  • SQL_CONN_MAX_LIFETIME：接続の最大有効期間。デフォルトは 60 分。

  • BATCH_UPDATE_ENABLED=true：データベースの一括更新集約を有効にします。接続数の過多を緩和できる可能性がありますが、利用枠の更新に遅延が発生します。

  • BATCH_UPDATE_INTERVAL=5：一括更新集約の間隔を設定します。単位は秒です。

Error 1040: Too many connections が発生した場合は、SQL_MAX_OPEN_CONNS を適切に小さくしてください。一括更新を有効にするかどうかを検討することもできます。

セッション、タイムアウト、プロキシを設定する

  • SESSION_SECRET：固定セッションキーを設定します。再起動後もログイン済みユーザーの Cookie が有効になります。

  • RELAY_TIMEOUT：中継リクエストのタイムアウトを設定します。単位は秒です。

  • RELAY_PROXY：中継リクエストが指定したプロキシ経由で上流 API にアクセスするようにします。

  • USER_CONTENT_REQUEST_TIMEOUT：ユーザーがアップロードしたコンテンツのダウンロードタイムアウトを設定します。

  • USER_CONTENT_REQUEST_PROXY：画像など、ユーザーがアップロードしたコンテンツのダウンロード用プロキシを設定します。

チャネル監視を設定する

チャネル残高を定期的に更新し、チャネルの利用可能性をテストできます。

CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVAL=5

最初の2つの変数の単位は分、POLLING_INTERVAL の単位は秒で、バッチ操作時のリクエスト間隔を制御します。

複数サーバー構成の設定

複数サーバー構成では、ローカル SQLite に依存し続けることはできません。すべてのノードを同じ MySQL データベースに接続し、セッション設定を統一する必要があります。

  1. すべてのサーバーで同じ SESSION_SECRET を設定します。

  2. すべてのサーバーで SQL_DSN を使用して同じ MySQL データベースに接続します。

  3. スレーブサーバーでは NODE_TYPE=slave を設定します。未設定の場合はデフォルトでマスターサーバーになります。

  4. SYNC_FREQUENCY を使用して、データベースから定期的に設定を同期します。

  5. スレーブサーバーでは FRONTEND_BASE_URL を設定し、ページリクエストをマスターサーバーにリダイレクトできます。

  6. 各スレーブサーバーに Redis をデプロイして REDIS_CONN_STRING を設定すると、キャッシュの有効期間中のデータベースアクセスを減らせます。

  7. マスターサーバーからデータベースへのアクセス遅延が大きい場合は、Redis と定期同期の有効化も検討してください。

SESSION_SECRET=random_string
SQL_DSN=root:123456@tcp(database:3306)/oneapi
NODE_TYPE=slave
SYNC_FREQUENCY=60
FRONTEND_BASE_URL=https://openai.example.com
REDIS_CONN_STRING=redis://default:redispw@localhost:49153

Nginx と HTTPS の設定

本番環境では、Nginx を使用して One API のリバースプロキシを構成できます。応答時間の長いモデルに対しては、読み取りタイムアウトを適切に延長してください。

server {
    server_name openai.example.com;

    location / {
        client_max_body_size 64m;
        proxy_http_version 1.1;
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header Accept-Encoding gzip;
        proxy_read_timeout 300s;
    }
}

Ubuntu では、Certbot を使用して HTTPS を申請・設定できます。

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart

よくある問題のトラブルシューティング

  • 「クォータ不足」と表示される：アカウントのクォータに加えて、トークン自体のクォータ上限も確認してください。

  • 「利用可能なチャネルがありません」と表示される：ユーザーグループ、チャネルグループ、およびチャネルが対応しているモデル一覧を確認してください。

  • 現在のグループ負荷が飽和している：通常、上流チャネルが 429 を返したことを示します。

  • クライアントに Failed to fetch と表示される：インターフェースアドレス、API Key、HTTPS 設定を確認してください。HTTPS ページからの HTTP リクエストは、ブラウザーによってブロックされる場合があります。

  • チャネルテストで invalid character が返される：上流が有効な JSON ではなく HTML を返している可能性があります。また、デプロイサーバーの IP やプロキシノードが Cloudflare によってブロックされている可能性もあります。

  • アップグレード後のデータ消失が心配：通常のアップグレードで MySQL のデータが失われることはありません。SQLite では、one-api.db を永続化するためにデータボリュームを正しくマウントする必要があります。

まとめ

One API は、複数のモデルプロバイダーを OpenAI 互換の呼び出し方式に統一し、チャネル、トークン、クォータ、ユーザーを一元管理するのに適しています。個人利用や低同時実行数の環境では Docker と SQLite から始め、高同時実行数や複数サーバー環境では共有データベースを使用し、遅延状況に応じて慎重に Redis を導入してください。運用を開始する前に、デフォルトパスワードを変更し、HTTPS を設定し、データを永続化するとともに、サービスが関連する規約および法令に準拠していることを確認してください。

このプロジェクトは MIT ライセンスでオープンソース化されていますが、README ではページ下部にクレジットとプロジェクトリンクを残すよう求めています。クレジットを削除する場合は、事前に許可を得る必要があります。詳しくは One API GitHub リポジトリ をご覧ください。