FreeToken ローカル API：MoE サービングのセットアップガイド

FreeToken ローカル API とは、ホスト型モデルのエンドポイントに依存するのではなく、FreeToken をローカル推論サービスとして使用することを指します。FreeToken は、コンシューマー向けハードウェア上でフロンティア規模のオープンウェイトモデルを実行するために設計された、エッジネイティブな Mixture-of-Experts サービングエンジンです。ドキュメントに記載されたアーキテクチャでは、GPU メモリ、CPU リソース、ホストメモリ、利用可能なインターコネクトを1つの推論プラットフォームとして組み合わせます。

実用上の利点は柔軟性です。MoE モデルには数千億個のパラメータが含まれる場合がありますが、各トークンではそのうち比較的小さなグループのエキスパートだけが有効化されます。FreeToken は、すべてのモデルウェイトを常に GPU メモリに保持することを前提とせず、エキスパートを効率的に移動・キャッシュすることに重点を置いています。

動画のポイント：

• FreeToken は、個人所有のハードウェア上で大規模 MoE モデルをローカルサービングすることを目的としています。
• エンジンは、ルーティングを考慮したエキスパートキャッシュと CPU–GPU 協調を重視しています。
• 報告されているベンチマークは、独立した再現結果が得られるまでは、プロジェクト側のベンチマークとして扱うべきです。
• ハードウェア互換性は、実績のあるマルチバックエンドランタイムよりも限定的です。

公式の FreeToken GitHub リポジトリでは、このプロジェクトが Apache License 2.0 のソフトウェアであることが示されています。また、Windows と Linux 向けのデスクトップアプリに加え、uv または pip による CLI インストールも掲載されています。そのため、ローカルでの実験、研究、エージェントワークフローに適しています。ただし、推論エンジンと、保証された HTTP API は区別して考える必要があります。

最適なセットアップ方法は、グラフィカルなワークフローを使用するか、再現可能な開発環境を構築するかによって異なります。リポジトリでは、デスクトップアプリと CLI の両方の方法がドキュメント化されています。現在は Windows と Linux が主な対象であり、利用可能なプロジェクト情報では macOS はサポート対象のビルドとして記載されていません。

インストールする前に、オペレーティングシステム、NVIDIA またはその他のサポート対象アクセラレーターの構成、システムメモリ、モデル形式を確認してください。別のランタイムでサポートされているモデルが、変更なしで FreeToken でも動作すると想定しないでください。

リポジトリには、ソースからインストールする方法も用意されています。

git clone <repository-url>
cd FreeToken
uv venv
source .venv/bin/activate
uv pip install -e ".[accel]"

このワークフローを適用する際は、公式ドキュメントに記載された正確なリポジトリ URL と、プラットフォームに応じたアクティベーションコマンドを使用してください。ソースの抜粋からは、汎用的な HTTP サーバーコマンドの存在は確認できません。そのため、本番スクリプトに未検証のエンドポイントを追加しないでください。

FreeToken が正常に起動したら、ローカル API ワークフローを段階的に構築します。まず直接生成を検証し、次にモデルの読み込みを繰り返し実行できることを確認します。その後で、エージェント、エディター、またはカスタムクライアントを接続してください。この順序により、モデルの問題と統合の問題を切り分けられます。

ローカルサービスはコーディングエージェントにとって有用です。リクエストがユーザーのハードウェア上に留まり、ホスト型プロバイダーのレート制限やモデル廃止スケジュールの影響を受けないためです。ただし、こうした利点があっても、メモリ、レイテンシ、コンテキストサイズ、プロセスの安定性を監視する必要はあります。

次のワークフローを使用してください。

• 短いプロンプトと控えめなコンテキストから始めます。
• 選択したモデルが複数のリクエストにわたって一貫して応答することを確認します。
• いきなり最大サイズのプロンプトでテストせず、コンテキスト長を段階的に増やします。
• GPU メモリ、ホストメモリ、システムの応答性を監視します。
• シングルターン推論が安定してから、ツール呼び出しやエージェントループを追加します。
• 小型モデルまたは短いコンテキスト用のフォールバック構成を用意します。

FreeToken のセマンティック対応キャッシュは、ツール呼び出しや思考ブロックを含む、エージェントによるコンテキスト編集向けに設計されています。セッションが構造化された形で変化した際に、不要なコンテキスト再計算を避けることが意図された利点です。実際のキャッシュ動作は、モデル、コンテキストパターン、利用可能なメモリ、ランタイム構成によって異なります。

性能テストでは、1秒あたりのトークン数だけでなく、次の項目も測定してください。

• 最初のトークンが出るまでの時間。
• 生成開始後のデコードスループット。
• シングルターンでの最悪レイテンシ。
• プリフィル中のメモリ消費量。
• デコード中のメモリ消費量。
• クライアントまたはウォッチドッグが低速なリクエストを終了するかどうか。

平均速度が速くても、許容できないテール動作が隠れている場合があります。エージェントにとっては、完了まで確実に動作する低速な構成のほうが、時折タイムアウトを超える高速構成より有用なことがあります。

FreeToken の特徴的な設計は、異種ハードウェアを柔軟な推論プラットフォームのように動作させようとする点にあります。リポジトリには、帯域幅適応型の CPU–GPU 協調実行、ダブルバッファ方式のプリフィルストリーミング、グローバル LRU エキスパートキャッシュ、グラフ互換実行、FTW 高速ウェイト形式が記載されています。

最も重要な概念は、エキスパートの配置です。MoE モデルでは、各トークンの計算に参加するのは選択されたエキスパートだけですが、ルーティングが変化した際には利用可能なエキスパートへアクセスできなければなりません。キャッシュは頻繁に選択されるエキスパートの再転送を減らし、CPU–GPU 実行は特定のマシンで利用可能な帯域幅に応じて適応できます。

ハードウェアの選択は、すでに所有している機器から始めるべきです。利用可能なプロジェクト資料では、十分なホストメモリを備えた比較的新しい NVIDIA システムが最も明確な対象となっています。このエンジンは、あらゆるオペレーティングシステムやアクセラレーターで成熟したランタイムを置き換えられる万能なものではありません。

FreeToken を別のローカルランタイムと比較する際は、公平なテストを行ってください。

• 同一のモデルウェイトと、同等の量子化を使用します。
• プロンプト長、出力上限、サンプリング設定を統一します。
• プリフィル速度とデコード速度を分けて測定します。
• 中央値と最悪レイテンシの両方を記録します。
• キャッシュをウォームアップした後にテストを繰り返します。
• 正確なソフトウェアおよびドライバーのバージョンを記録します。

利用可能なベンチマークの議論では、選択された MoE ワークロードにおいてプロジェクト側の優れた結果が報告されています。一方で、レビュー時点では独立したベンチマークがまだ存在していなかったことも強調されています。これらの数値は、普遍的な保証ではなく、方向性を示す有用な証拠として扱ってください。

初回起動時の問題の多くは、サポート対象外のハードウェア、アクセラレーターのインストール不備、不適切なモデルファイル、またはドキュメント化されていないエンドポイントを前提とした統合の4つの領域のいずれかに起因します。この順番で解決してください。

インストールに失敗した場合は、公式リポジトリの指示に戻り、環境を確認してください。アプリケーションは起動するものの生成に失敗する場合は、複数の変数を同時に変更する前に、より小さいモデルまたは既知のサポート対象モデルをテストします。生成は動作するもののクライアントが接続できない場合は、URL パス、ポート、リクエストスキーマを推測せず、現在のサービングドキュメントを確認してください。

セットアップを信頼できる状態とみなす前に、次のリリースチェックリストを使用してください。

• 2026 年の現行バージョンとインストール日を確認します。
• 公式リポジトリ URL とリリースノートを保存します。
• コールドスタートと、ウォームアップ済みキャッシュでのリクエストをテストします。
• 通常時と最悪時の応答時間を両方測定します。
• プロセスが想定される最長プロンプトに耐えられるか確認します。
• 小型のフォールバックモデルを用意します。
• 認証および通信保護がドキュメント化されていない限り、信頼できるネットワークの外部にローカルサービスを公開しないでください。