aidea-server を自前で動かす前に読む、Go 製マルチモデル基盤の実像

1 つのサーバーに複数プロバイダーを同居させるという要求

aidea-server が解こうとしているのは、チャットと画像生成を別々のバックエンドに分けずに済ませる問題である。README は「mainstream large language models and image generation models」を統合するサーバーと説明し、GPT 系に加えて通義千問や文心一言といった国産モデル、そして Stable Diffusion 系の文生図、図生図、SDXL1.0、超解像、画像彩色を対象に挙げている。利用者像は 2 つに分かれる。1 つは公式クライアントアプリの backend を自前で持ちたい運営者、もう 1 つは OpenAI 互換の口だけを使いたい既存ツールの利用者である。README のコード構造表は api ディレクトリを「OpenAI-compatible API; endpoints here can be used directly by any third-party software that supports the OpenAI API protocol」と説明しており、後者の用途が想定されていることが読み取れる。

chat 抽象化レイヤーが吸収する差分

pkg/ai/chat は「Abstract chat model interface; all chat models are wrapped here to be compatible with the OpenAI Chat Stream protocol」と説明されている。つまりプロバイダーごとの応答形式の差はこの層で吸収され、上位の api と server は OpenAI の Chat Stream 形式だけを扱う。これは実装上の利点であると同時に制約でもある。OpenAI のストリーム形式に対応付けられない機能、たとえばプロバイダー固有のツール呼び出しやマルチモーダル入力の細かい差異は、この層で表現できない可能性がある。README は各モデルの対応状況を一覧にしておらず、どのモデルがどの機能まで通るかはリポジトリを読まないと確定できない。

Glacier と Eloquent、内製フレームワークへの依存

このプロジェクトは外部の Web フレームワークを使わず、作者自身の Glacier Framework と Eloquent ORM に依存している。Glacier は「in-house modular application development framework with dependency injection support」で、go-ioc を土台に Go アプリの依存伝播とモジュール化を狙う。Eloquent は Laravel に着想を得たコード生成ベースの ORM で、MySQL などに対応する。ここは採用判断の分かれ目になる。内製フレームワークは設計の一貫性を生む一方、外部の知見や既存のエコシステム資産がそのままでは使えない。DI コンテナや ORM の挙動を調べる先は、作者の別リポジトリのドキュメントとソースになる。

ディレクトリ構成から読むデータの流れ

コード構造表は役割分担をかなり明快に示している。cmd がエントリポイント、config が設定定義、migrate が SQL のマイグレーション、pkg/repo がデータモデル層で pkg/repo/model が Eloquent によるモデル定義、pkg/service が Controller にも Repo にも属さないロジックの置き場とされている。非同期処理は internal/queue に定義され、internal/queue/consumer がその消費者である。課金は internal/payment に Alipay や Apple などの実装があり、価格と課金ポリシーは internal/coins が持つ。決済まわりが internal 側に置かれ、pkg 側の公開パッケージと分離されている点は、外部から再利用される範囲を意識した構成と読める。

config.yaml と coins-table.yaml が示す設定の二層構造

リポジトリ直下には config.yaml、coins-table.yaml、nginx.conf、systemd.service の 4 つの例が並ぶ。config.yaml は「Example configuration file」、coins-table.yaml は「Example pricing table configuration」と説明されている。設定がアプリ全体の構成と課金表で分かれているのは、料金改定を設定ファイルの差し替えで回せるようにする意図と推測できるが、README はキーの一覧も書式も示していない。nginx.conf と systemd.service が同梱されていることは、リバースプロキシ配下でサービスとして動かす運用が想定されている証拠である。実際の起動コマンドや設定キーの意味は docs/deploy.md を参照する必要があり、この README だけでは起動手順を再現できない。

ドキュメントの薄さと命名の揺れという現実

README 自身が「Code comments and technical documentation are currently limited and will be supplemented over time」と認めている。さらに命名の揺れが明記されている。コード中の Room と Advisory Group はどちらも Digital Persona を指し、改訂を重ねた結果として Room → Advisory Group → Digital Persona と変わった。Creation Island も v1 と v2 が全く別物で、v1 はアプリ 1.0.1 までで、1.0.2 以降は使われていない。これは単なる歴史的経緯ではなく、現行コードを読むときに古い名前のモジュールを現行機能と誤認するリスクである。ドキュメントが追いついていない領域に手を入れるなら、まずこの対応表を頭に入れておく必要がある。

課金、キュー、レート制御を外して試す

internal/queue と internal/queue/consumer が非同期タスクを担い、pkg/jobs には「daily user token-consumption statistics」のような定期タスクが置かれ、pkg/rate にレート制限の実装がある。画像生成のように時間のかかる処理をキューに逃がす設計は妥当だが、キューと課金とレート制御が同時に絡むと、どこで失敗したのか切り分けにくくなる。最初に確認すべきは、課金とレート制御を無効化した状態で単一のチャットモデルだけを通せるかどうかである。ここが通らなければ、多モデル対応や画像生成を検証する段階には進めない。

代替としてのクライアント直結型と、その差

同じ作者のクライアントである mylxsw/aidea は、サーバーを挟まず各プロバイダーの API を直接叩く構成も取り得る。aidea-server を立てる意味は、API キーをクライアントに配らずに済むこと、利用量と課金をサーバー側で一元管理できること、そして api ディレクトリ経由で OpenAI 互換の口を他のツールに開放できることにある。逆に、単一プロバイダーだけを使い、キー管理も課金も不要で、利用者が自分の端末だけなら、サーバーを運用する理由は薄い。プロバイダーを増やすほど chat 抽象化層の恩恵は大きくなるが、同時に設定と障害点も増える。

ライセンスと更新コストの見積もり

リポジトリ情報ではライセンスが unknown とされており、README にも条項への言及がない。再配布や商用利用の可否は、この材料からは判断できない。導入前にリポジトリの LICENCE 相当のファイルを自分で確認する必要がある。更新面では、直近のリリースが 2024 年 4 月で、最終 push が 2026 年 3 月とされている。リリースノートには Stripe、微信登录、艺术字といった機能追加が並び、モデルの追加や渠道の変更が継続的に入る性質のソフトウェアだと分かる。プロバイダー側の API 仕様変更に追随するコストは、導入後も続くと見ておくべきである。

編集部の結論

aidea-server が向くのは、GPT 系と国産 LLM、画像生成を 1 つのバックエンドに集約したいチームと、OpenAI 互換 API を自前の環境で立てたい開発者である。逆に、コードを読み解く前提なしに短期で本番投入したい場合や、Apache や MIT のような明示的な許諾条件を前提に配布物を組み立てたい場合は、このリポジトリは適さない。導入前に確認すべきは、ライセンス条項、docs/deploy.md の手順が現在の config.yaml と一致するか、そして課金とレート制御を止めた状態で単一モデルだけを通せるか、の 3 点である。

公式情報源

1. Issues
2. mylxsw/aidea-server on GitHub
3. Project website
4. README
5. Releases