DEV Community

Cover image for ローカルで動くAI予測エンジン「MiroFish」— デプロイからトラブルシューティングまで
yuuto128
yuuto128

Posted on

ローカルで動くAI予測エンジン「MiroFish」— デプロイからトラブルシューティングまで

#群知能 #mirofish #ai予測 #オープンソース

最近、個人的にマルチエージェント系のプロジェクトを色々漁っているんですが、その中で一つ「おっ、これは面白い」と手が止まったのが MiroFish です。

一言でいうと、大量のAIエージェントを仮想世界で自由にやりとりさせて、世論の推移やトレンドを予測するというオープンソースのエンジンです。しかもただのPoCじゃなく、実際にローカルでデプロイして動かせる。コミット数220超え、Docker対応済み、公式サイトにはデモも用意されていて、「ちゃんと動くプロダクト」として仕上がっています。

今回は実際にセットアップして動かしてみたので、その流れと途中でハマったポイントを共有します。

MiroFish

MiroFishとは — 「ハイファイなデジタルパラレルワールド」を作るエンジン

MiroFishは、盛大集団（Shanda Group）のサポートのもと開発されている スウォームインテリジェンス（群知能）ベースのAI予測エンジン です。ざっくり言うとこんな仕組みです：

  1. シードデータ（ニュース記事、政策草案、小説のテキストなど）を投入する
  2. テキストからナレッジグラフを自動構築する
  3. グラフ構造をもとに、独立した人格・記憶・行動ロジックを持つエージェントを大量に生成する
  4. エージェント同士を仮想空間で自由にインタラクションさせ、社会的な振る舞いをシミュレーションする
  5. ReportAgentが最終状態を分析し、構造化された予測レポートを出力する

要するに「デジタルなパラレルワールド」を作って、その中で何が起こるかを観察するというアプローチです。

公式サイトのデモでは大学の世論シミュレーションや、『紅楼夢』（中国古典文学）の失われた結末の予測など、なかなかユニークなユースケースが紹介されています。

📎 公式サイト：mirofish.ai

セットアップ：最短で動かすまで

デプロイ方法はソースコードとDockerの2パターンがあります。詳細な手順は公式READMEの「🚀 Quick Start」セクションにまとまっているので、ここでは要点だけ押さえておきます。

環境要件

項目 要件
Node.js v18以上（node -v で確認）
Python 3.11〜3.12（python --version で確認）
uv Pythonパッケージマネージャー（uv --version で確認）
LLM API OpenAI SDK互換のAPI（GPT、Claude、Qwenなど）
Zep Cloud エージェントの長期メモリ管理（任意だが推奨）

注意⚠️：
公式READMEでは Alibaba Cloud の qwen-plus モデルが推奨されています。LLMのトークン消費がかなりエグいので、最初は 40ラウンド以下 の小規模シミュレーションから試すのが吉です。

ソースコードデプロイ（推奨） 

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env          # .envにAPIキー等を記入
npm run setup:all             # フロント・バックの依存を一括インストール
npm run dev                   # フロント(3000) + バックエンド(5001)を同時起動
Enter fullscreen mode Exit fullscreen mode

フロントエンドとバックエンドを別々に起動したい場合は npm run frontend / npm run backend でOKです。

Dockerデプロイ（サクッと試したい人向け） 

cp .env.example .env          # .envにAPIキー等を記入
docker compose up -d          # ポート3000/5001でサービスが立ち上がる
Enter fullscreen mode Exit fullscreen mode

使い方：何ができるのか

セットアップが終わったら http://localhost:3000 にアクセスして、以下の流れで使います。

  1. シードデータをインポート — テキスト、イベントの記述、データレポートなどを投入
  2. シミュレーション変数を設定 — ソーシャル構造、インタラクションルール、エージェント数など
  3. シミュレーションを実行 — ナレッジグラフの構築→エージェント生成→複数ラウンドのインタラクションが自動で走る
  4. 予測レポートを確認 — トレンドの推移、感情分布、行動クラスタリングなどが出力される
  5. インタラクティブに深掘り — 任意のエージェントやReportAgentと直接チャットして分析できる

開発者的にうれしいのは、ノーコードでもシミュレーションを回せる一方で、自分のイベント処理ロジックを組み込んだり、エージェントの設定パラメータを細かくいじったり、結果をコールバックAPIで受け取ったりもできるところです。

アーキテクチャ概要：裏側で何が動いているか

エンジンの内部フローをざっくりまとめると：

テキスト入力
  ↓
① ナレッジグラフ構築（GraphRAG）
  — エンティティとリレーションを自動抽出
  ↓
② 環境 & エージェント生成
  — グラフ構造からペルソナ・行動ルールを生成
  ↓
③ マルチエージェント・シミュレーション
  — パラレル環境でエージェントがインタラクション・メモリを更新
  ↓
④ レポート生成
  — ReportAgentが分析し構造化レポートを出力
Enter fullscreen mode Exit fullscreen mode

単体のLLMに「予測して」と投げるのとは根本的にアプローチが違い、ナレッジグラフ駆動 × マルチエージェント協調 のパターンで予測を行います。内部のシミュレーションエンジンには OASIS（CAMEL-AI） が採用されています。

セットアップで踏んだ地雷と対処法

ここからが実務的に一番ありがたいパートだと思います。自分が実際にハマったポイントをまとめておきます。

1. uv コマンドが見つからない 

'uv' is not recognized as an internal or external command
Enter fullscreen mode Exit fullscreen mode

Conda環境に uv を入れたけど、npm run dev 経由だとConda環境がactivateされず、パスが通らないパターンです。

対処法：フロントエンドとバックエンドを別々に起動するのが確実。

# バックエンド（Conda環境経由で起動）
cd backend
conda run -n your_env_name python run.py

# フロントエンド（別のターミナルで）
cd frontend
npm run dev
Enter fullscreen mode Exit fullscreen mode

あるいは uv をグローバルにインストールしてしまうのも手です：

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

2. Rollupのネイティブモジュールが解決できない（Windows） 

Error: Cannot find module @rollup/rollup-win32-x64-msvc
Enter fullscreen mode Exit fullscreen mode

Windows環境でnpmのoptional dependenciesが正しくインストールされなかっただけなので、手動で入れれば解決します。

cd frontend
npm i -D @rollup/rollup-win32-x64-msvc
Enter fullscreen mode Exit fullscreen mode

それでもダメなら node_modules と package-lock.json を消してクリーンインストール。Node.jsは 18 LTS か 20 LTS を使うのが無難です。

3. APIキーまわりのTips

  • APIキーは必ず .env に書く。ソースコードへのハードコードは厳禁
  • リポジトリに test_api_key.py / test_bailian_api_key.py というテストスクリプトが同梱されているので、接続確認に使うと楽 
python test_bailian_api_key.py
Enter fullscreen mode Exit fullscreen mode

運用で気をつけること

項目 ポイント
APIコスト 大規模シミュレーションはLLM呼び出し回数がかなり多い。事前にコスト感を把握しておくのが大事
メモリの永続化 Zep Cloudを使うとエージェントの長期メモリが格段に良くなる
バージョン相性 PythonとNodeのバージョンが要件と合わないと依存でコケがち。nvm / pyenv 等の活用を推奨
結果の扱い シミュレーション結果はあくまで確率分布。確定的な予測ではないので、従来モデルとの組み合わせが吉

まとめ：「面白い概念」ではなく「動くプロダクト」

正直なところ、「マルチエージェントで未来を予測する」って聞いた時は「またコンセプト止まりでは？」と疑っていました。でも実際にデプロイして動かしてみると、ナレッジグラフの構築からエージェント生成、シミュレーション実行、レポート出力まで、ちゃんと一本のパイプラインとして繋がっている。

  • 開発フェーズ → ソースコードデプロイでホットリロード & デバッグ
  • デモ・本番 → Docker一発で環境分離 & 安定稼働
  • 拡張性 → 自前のロジックを組み込んだり、外部システムと連携するのも自由

マルチエージェントの応用に興味がある方は、一度触ってみる価値ありです。特にシミュレーション系のユースケース（世論シミュレーション、シナリオ分析、複雑系のダイナミクス予測など）を探している方にはぴったりだと思います。

実際に動かしてみた感想や、こんなユースケースで使ってみた、みたいな話があれば、ぜひコメント欄やSNSで教えてください！一緒に沼にハマりましょう

参考リンク：

Top comments (0)