AIチュートリアル

OpenAI互換APIでColab A100上のQwen3.8-Flash-Nextを実行する

collabosmを使ってColab A100のHigh-RAMランタイムをプロビジョニングし、ExLlamaV3でQwen3.8-Flash-Nextを読み込み、Cloudflare経由で保護されたAPIを公開し、クライアントを接続し、ローカルでストリーミングをテストし、キャッシュを調整して、従量課金VMを安全に停止する方法を学びます。

2026年9月26日約24分で読了

OpenAI互換APIでColab A100上のQwen3.8-Flash-Nextを実行する

collabosmの機能

collabosmは、単一のColab A100 80 GB High-RAMインスタンス上でQwen3.8-Flash-Nextを実行します。このモデルは、ハイブリッドGated-DeltaNetとフルアテンションのアーキテクチャを採用した125B-A6B mixture-of-expertsモデルで、ネイティブコンテキスト長は262,144トークンです。

このプロジェクトは、Colab VMのプロビジョニングまたは復元、固定バージョンのExLlamaV3ランタイムのインストール、固定バージョンのモデル重みのダウンロード、OpenAI互換HTTPサーバーの起動、Cloudflareトンネル経由での公開を行います。クライアントは、生成されたBearerキーを使用し、/v1配下のトンネルURLに接続します。

リポジトリで使用する推論エンジンはExLlamaV3のみです。ExLlamaV3にはHTTPサーバーが含まれていないため、APIサーバー自体はcollabosmが実装しています。

主な機能

単一GPUデプロイ: 約63.6 GiBのVRAM常駐重みを、1台のA100 80 GB High-RAMランタイムで実行します。
OpenAI互換インターフェース: インクリメンタルストリーミングを含む、/v1/chat/completionsと/v1/responsesの両方をサポートします。
安全なColab復元: 使い捨てのローカルCLIセッション記録を信用したり、課金対象となるVMを重複作成したりせず、孤立した割り当てに再接続します。
ハードウェア検証: 互換性のない40 GB A100を拒否し、モデルの読み込み前に停止します。
永続的なプロンプトキャッシュ: 長時間存続するExLlamaV3 Generatorを1つ保持し、ページテーブルと固定RAMキャッシュをリクエスト間で維持します。
2層キャッシュ設計: GPU KV容量と、アイドル状態の会話を素早く再開するためのオプションの固定ホストRAMキャッシュを組み合わせます。
ローカルプロトコルテスト: GPUやモデル重みなしで、実際のHTTPハンドラーを検証できるフェイクエンジンを提供します。
オプションのビジョン機能: モデルのビジョンコンポーネントを読み込み、制限付きの画像入力を受け付けられます。
ローカルクライアントとUI: ターミナルチャット、ブラウザーUI、ステータスページ、ストリームから算出するパフォーマンス指標、ブラウザーに上流キーを公開しないプロキシを備えています。

プロジェクトが報告する測定値には、GCS=8192で30Kプロンプトを処理した場合の最大3,882プリフィルトークン/秒、コンテキスト長30KでMTP深度4の場合の97.4デコードトークン/秒、コンテキスト長114Kでの90.1トークン/秒が含まれます。これらの数値を保証値として扱わず、根拠と注意事項についてはdocs/MEASURED.mdを参照してください。

要件と容量計画

開始前に、環境が次の要件をすべて満たしていることを確認してください。

A100を割り当て可能なColabプラン。
HIGH_RAMマシン形状。標準の40 GB A100ではこのモデルを読み込めません。
重み用に約110 GiBのColabディスク容量。
uv tool install google-colab-cliでインストールしたGoogle Colabコマンドラインツール。
リポジトリをフォークまたはプッシュする予定がある場合は、オプションでGitHub CLI。

uv tool install google-colab-cli

High-RAM要件は必須です。「80」を検索してハードウェア出力から適切なカードを判定しないでください。A100はVRAMが40 GBしかない場合でも、計算能力sm_80を報告することがあります。collabosmは代わりに報告されたvram_GiB値を比較します。

このプロジェクトは、月約200コンピュートユニットのColab Proティアで開発されました。測定されたA100 High-RAMのコストは1時間あたり7.52 CUで、記載された環境ではおよそ1時間あたり$0.75でした。料金と割り当ての可用性は、リポジトリとは無関係に変更される場合があります。

サーバーを起動する

1. リポジトリディレクトリを開く

collabosmリポジトリをダウンロードまたはクローンし、ルートディレクトリから次のコマンドを実行します。スクリプトはscripts/up.sh、scripts/bootstrap.sh、scripts/serve.shなどのリポジトリ相対パスを想定しています。

2. プロビジョニング、ブートストラップ、サービス提供

bash scripts/up.sh

この単一コマンドは、可能な場合は既存の割り当てを復元し、それ以外の場合は新しいHigh-RAM割り当てを作成します。その後、プロジェクトをアップロードし、固定バージョンのランタイムをインストールし、固定バージョンの重みをダウンロードし、APIを起動し、Cloudflareトンネルを開始し、正常なヘルスチェックが完了するまで待機します。

実行が成功すると、APIと公開トンネルURLの両方が準備できた後にのみ、ステータス0で終了します。コマンドはトンネルURLとAPIキーを表示します。キーはVM上の/content/api-key.txtにも保存されます。

ランタイムは、ColabのPython、PyTorch、CUDA環境に適合する、固定バージョンのビルド済みExLlamaV3 wheelから選択されます。重みは固定リビジョンのHugging Faceから取得されます。Xetのダウンロード経路が停止した場合、READMEではHF_HUB_DISABLE_XET=1をフォールバックとして示しています。

3. 接続設定を記録する

base_url = https://<host>.trycloudflare.com/v1
api_key  = <printed API key>
model    = qwen3.8-flash-next-exl3

クイックトンネルのホスト名は起動ごとに変わる場合があります。安定したホスト名を使用するには、TUNNEL_TOKENで名前付きCloudflareトンネルを設定し、ステータス出力に表示されるアドレス用のPUBLIC_URLと組み合わせます。

4. 実行中の設定を確認する

GET /v1/statusをリクエストすると、キャッシュ設定、起動パラメーター、稼働時間、ビジョン機能の利用可否、画像入力ポリシーなど、実行中のプロセスが実際に受け取ったパラメーターを確認できます。

リポジトリの注記によると、現在のデフォルト設定はすべてが組み合わせて検証されているわけではありません。特定の組み合わせが検証済みだと判断する前に、実行中のステータスエンドポイントを確認し、docs/MEASURED.mdを参照してください。

キャッシュと生成を設定する

主な起動制御は、scripts/up.sh に渡す環境変数です。例:

SESSION=mybox CACHE_SIZE=524288 CPU_CACHE_GB=8 bash scripts/up.sh

SESSION: ローカルセッション名。デフォルトは collabosm。
CACHE_SIZE: ジョブ全体のKVトークン数。デフォルトは 500224 で、256の倍数である必要があります。
CACHE_QUANT: KVキャッシュのビット幅。デフォルトは 4。2から8までの値を指定できます。
CPU_CACHE_GB: ピン留めRAMを使用する第2階層KVページキャッシュ。デフォルトは32 GiBで、0にすると無効になります。
RECURRENT_CACHE_GB: Gated-DeltaNetチェックポイント用のホストRAM容量。デフォルトは24 GiBです。
GCS: 生成チャンクサイズであり、プリフィル性能を大きく左右する設定。デフォルトは 8192。
NDT: マルチトークン予測のドラフト深度。デフォルトは 4。
RUNTIME: 事前ビルド済みランタイムには wheel、ソースベースのセットアップには source を指定します。
TUNNEL_TOKEN: オプションの名前付きトンネルトークン。

ホストRAMのキャッシュは、無料で使える容量ではありません。デフォルトのCPUキャッシュは全容量がピン留めメモリとして確保され、リカレントキャッシュも大量のRAMを消費します。これらは、リポジトリに記載されている36.4 GiBのn-gramテーブルと共存します。

ピン留めRAM層は、参照されていないページが追い出されたアイドル状態の会話を再開するまでの時間を短縮します。同時に稼働できるコンテキスト数を増やすものではありません。稼働中のページは、ホストRAMを通常のスワップ領域のように扱って追い出すことができないためです。

OpenAI互換APIを呼び出す

モデルを一覧表示する

curl https://<host>.trycloudflare.com/v1/models \
  -H "Authorization: Bearer <api-key>"

エンドポイントは、単一のモデル識別子 qwen3.8-flash-next-exl3 を返します。このAPIルートでは認証が必要ですが、/health は認証不要で、プレーンテキストの ok を返します。

チャット補完を作成する

curl https://<host>.trycloudflare.com/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash-next-exl3",
    "messages": [
      {"role": "user", "content": "Reply with exactly: pong"}
    ],
    "max_tokens": 16
  }'

チャットインターフェースは、choices[].message.content にコンテンツを返します。また、stop または length の終了理由と、キャッシュ済みプロンプトトークンを含む場合がある使用量情報も返します。

補完をストリーミングする

stream を true に設定すると、モデルのデコード中にServer-Sent Eventsを受信できます。チャット補完では、ストリームは [DONE] で終了します。stream_options.include_usage を設定すると、ストリーミングレスポンスに使用量データが含まれます。

{
  "model": "qwen3.8-flash-next-exl3",
  "messages": [{"role": "user", "content": "Explain prompt caching briefly."}],
  "stream": true,
  "stream_options": {"include_usage": true},
  "max_completion_tokens": 200
}

/v1/responses エンドポイントもストリーミングに対応しています。イベントシーケンスには、作成、進捗、出力アイテム、コンテンツパート、テキスト差分、完了、終了レスポンスの各イベントが含まれます。ストリーミングされるすべてのイベントには単調増加する sequence_number が付与され、差分にはクライアントが正しく関連付けるために必要なアイテムインデックスとコンテンツインデックスが含まれます。

思考モードを使用する

通常のチャットクライアントとの互換性のため、思考機能はデフォルトで無効です。enable_thinking: true を指定するか、サポートされている reasoning_effort の値 xhigh、medium、low を指定すると有効になります。チャット画面では、推論トレースは message.reasoning_content に分離して返され、通常のコンテンツフィールドには混入しません。

temperature と top_p は受け付けられますが、サーバーが sampler=None でジョブを構築するため、現在は無視されます。思考制御、max_tokens、停止シーケンスは機能します。

付属クライアントを使用する

ローカルの collabosm.py クライアントはPython標準ライブラリのみを使用し、別途インストールする必要はありません。トンネルのエンドポイントと生成されたキーを指定して設定を初期化します。

python collabosm.py config --init \
  --endpoint https://<host>.trycloudflare.com/v1 \
  --api-key <key>

その後、ターミナルからチャットするか、ローカルのブラウザーインターフェースを起動できます。

python collabosm.py chat "hello"
python collabosm.py ui
python collabosm.py start

ui は http://127.0.0.1:8790 でページとプロキシを提供します。start はチャットウィンドウとステータスウィンドウを開きます。クライアントは意図的にColab VMを起動・停止しないため、これを開くだけで計算ユニットを消費することはありません。

実際のベアラートークンをプロキシに注入させたい場合は、既存のOpenAI互換クライアントにVMのエンドポイントではなくローカルプロキシを指定します。

base URL : http://127.0.0.1:8790/v1
API key  : anything
model    : qwen3.8-flash-next-exl3

この設計により、実際のキーをローカルプロセス内に保持し、広範なCORSポリシーを避け、ブラウザーUIをVMとは独立して更新できます。

GPUなしでプロトコルをテストする

開発用スタブを使用すると、A100の料金を支払ったり重みをダウンロードしたりせずに、リクエストとストリーミングの動作を検証できます。

python scripts/dev_stub.py --port 8099 --chunk 24 --delay 0.01
python scripts/check_surface.py --base http://127.0.0.1:8099/v1

このスタブは実際のストリーミング処理ハンドラーをインポートし、エンジン断片関数だけを置き換えます。サーフェスチェッカーは、初期デルタ、終端イベント、チャット出力とResponses出力の一致、必須アイテムインデックス、単調増加するシーケンス番号など、13項目を検査します。検査に失敗するとステータス1で終了します。

スタブコマンドに--thinkを追加すると、推論アイテムのライフサイクルを検証できます。ストリームイベントの形式を変更する前や、Codex CLIのような厳格なクライアントを接続する前に特に役立ちます。

Visionを慎重に有効化してテストする

モデルパックはマルチモーダルですが、Vision Towerによる追加VRAM消費が、すでに大きく使用されているカード上で測定されていないため、Visionはデフォルトで無効になっています。独立したVisionコンポーネントを明示的に有効化してください。

VISION=1 bash scripts/up.sh

画像に関するオプションの設定は次のとおりです。

IMAGE_URLS=1
MAX_IMAGE_BYTES=12582912
MAX_IMAGES=8

サポートされている2つのAPI方言はいずれも、標準のOpenAI画像パーツを受け付けます。Visionが有効な場合はデータURLを使用できます。リモートのHTTPまたはHTTPS画像URLは、IMAGE_URLS=1を設定しない限り無効です。

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What colour is this image?"},
    {
      "type": "image_url",
      "image_url": {"url": "data:image/png;base64,..."}
    }
  ]
}

リモートURLを有効にすると、サーバーはホスト名を解決し、すべてのアドレスがグローバルにルーティング可能であることを要求します。ループバック、プライベート、リンクローカル、メタデータのアドレスは拒否され、リダイレクトには従いません。ファイルシステムパスは一切受け付けません。画像を埋め込めない場合、サーバーは画像を黙って無視せず、vision_unavailable型のJSON 400エラーを返します。

GET /v1/statusを確認してVisionが有効かどうかを調べ、次のコマンドで有効化された動作、または意図的に拒否される動作を検証してください。

python scripts/check_vision.py \
  --base https://<host>.trycloudflare.com/v1 \
  --key <key>

並行性とパフォーマンスのヒント

APIはロックで保護された1つの長期間稼働するジェネレーターを使用します。そのためリクエストは直列化され、複数のストリームが並列デコードされるのではなくキューに入ります。1より大きいバッチサイズはテストされておらず、公表されている測定値は1スロットで取得されています。

測定されたライブセッション容量は、コンテキスト長に大きく左右されます。

ストリームあたり500Kトークン: ライブセッション1つ。
ストリームあたり262Kトークン: ライブセッション2つ。
ストリームあたり131Kトークン: ライブセッション5つ。
ストリームあたり32Kトークン: ライブセッション11個。
ストリームあたり16Kトークン: ライブセッション14個。

各ライブスロットは、KVストレージの前にGated-DeltaNetの状態として約546 MiBを消費します。短いコンテキストでは再帰状態が制約要因になります。実用上の文書化された範囲はおよそ8～14のライブスロットですが、現在のAPIロックによりリクエストは引き続き直列化されます。

プレフィルのパフォーマンスについて、プロジェクトで確認された最大の改善要因はGCSでした。ただし、キャッシュ設定を大きくしたり変更したりする場合は、盲目的にコピーせず、VRAMとホストRAMの使用量に対して検証してください。

リクエストごとに新しいGeneratorを構築することは避けてください。ページテーブルとCPUページキャッシュはGenerator.__init__内で作成されるため、再構築するとプロンプトキャッシュの再利用がひそかに失われ、プレフィルが繰り返し実行されます。付属のサーバーは、すでに正しい長期間稼働するインスタンスを維持しています。

トラブルシューティング

CLIにアクティブなセッションがないと表示される

VMがアクティブで課金対象のままであっても、ランタイムプロキシトークンの有効期限が切れると、ローカルのセッション記録が消えることがあります。別のVMを手動で作成するのではなく、リポジトリの復旧ワークフローを使用してください。scripts/restore.pyはサーバー側の割り当てを照会し、孤立したインスタンスを再接続します。

モデルを読み込めない

ランタイムに約80 GBのVRAMがあり、High-RAMの構成であることを確認してください。復旧スクリプトは、モデルの読み込み前に40 GBの割り当てを拒否して停止するよう設計されています。

APIは正常だが公開URLが表示されない

up.shは、正常なVMだが公開されたトンネルURLがない状態と、完全に準備完了した状態を区別します。終了ステータス9はこのケースを示します。エンドポイントが公開アクセス可能だと決めつけず、サービスとトンネルのログを確認してください。

リクエストがサンプリング制御を無視しているように見える

現在のサーバーでは、temperatureとtop_pについてこれは想定された動作です。これらは解析されますが、サンプラーには渡されません。

ストリーミングの互換性が壊れる

scripts/dev_stub.pyで問題を再現してから、scripts/check_surface.pyを実行してください。実際のハンドラーがテスト対象になるため、モデルをプロビジョニングせずにプロトコルのリグレッションを検出できます。

VMを停止してコストを管理する

作業が終わったら、従量課金のランタイムをすぐに停止してください。

bash scripts/down.sh

これはプロジェクトで最も重要なコスト管理コマンドです。ブラウザーを閉じること、ローカルのCLI記録を失うこと、Colabとの接続を切断することは、課金が停止した証拠にはなりません。

オプションのフロントエンド制御プレーンには、プロビジョニング前の確認、ローカルCU台帳、アイドル時の自動停止、最大セッション時間、キャンセル、割り当て後にプロビジョニングが失敗した場合のクリーンアップが追加されます。カードやコンピュートユニットなしで、そのワークフローをリハーサルできます。

python frontend/server.py --fake-provision
python frontend/server.py --mock
python scripts/dev_stub.py --port 8099 &
python frontend/server.py --mock --backend http://127.0.0.1:8099

まとめ

collabosmは、Colab上でQwen3.8-Flash-Nextを実行する際の難しい部分をまとめて処理します。正しいA100シェイプのリクエスト、孤立した割り当ての復旧、互換性のあるExLlamaV3ランタイムのインストール、固定された重みの読み込み、キャッシュの保持、保護されたトンネルの公開、そして2種類のOpenAI互換API方言の提供に対応しています。

bash scripts/up.shで開始し、/v1/statusを通じて実行中の設定を確認します。表示された/v1エンドポイント経由で接続し、必ず最後にbash scripts/down.shを実行してください。本番環境に近い実験では、リクエストの直列化、未実装のサンプリング制御、キャッシュのメモリコスト、Visionによる追加VRAM使用の任意性、そしてアイドルキャッシュからの再開と実際のライブセッション容量の違いに特に注意してください。