🏘️ AIの町 Version 3 — llm-executor による LLM 中央制御と安定化アーキテクチャの実装記録

※この記事は AI（Microsoft Copilot）によって生成され、筆者が内容を確認・調整しています。
※この記事は前回の記事
https://qiita.com/genkyoryo110/items/0ab6fdd5802da2cfbf5b
の続編です。

AI の町（AI Town）は、複数の AI エージェントが協力してタスクを実行する 自律型マルチエージェント基盤です。
Version 3 では、GPU 競合による不安定さを根本的に解決するために、llm-executor を導入し、LLM 呼び出しを完全に一元化しました。

RTX 4060 のような GPU でも安定して動作するように、優先度付きキュー + GPU ロック による直列実行を採用しています。

この記事では、Version 3 の技術的背景、アーキテクチャ、実装内容をまとめます。

---

🎯 Version 3 のゴール

• LLM 呼び出しの 完全一元化
• GPU 競合の ゼロ化
• launcher / manager-api / 検証レイヤの 統合制御
• Semantic Similarity（bge-m3）の 安定化
• RTX 4060 でも動く 堅牢なアーキテクチャ

---

🚀 Version 3 の主な変更点

1. llm-executor の導入（最重要）

Version 3 最大の変更は、すべての LLM 呼び出しを llm-executor に集約したことです。

✔ 役割

• LLM 呼び出しの中央制御
• 優先度付きキュー（priority=1,2,3）
• GPU ロックによる直列実行
• OllamaClient の一元化

✔ なぜ必要だったのか？

Version 2 までは：

• Worker
• 管理AI（setuna-manager）
• 検証レイヤ（Verification / Critic / Embedding）

が それぞれ独立に Ollama を叩いていたため、
RTX 4060 のような GPU では モデルロード競合 → フリーズ が頻発していた。

Version 3 ではこれを完全に解消。

---

2. 優先度付きキュー（priority=1,2,3）

priority	用途
1	Worker（最優先）
2	管理AI（setuna-manager）
3	検証レイヤ（Verification / Critic / Embedding）

同時に複数のリクエストが来ても、
高優先度 → 低優先度の順で実行される。

実行中のタスクは 途中で止めない（非プリエンプティブ） ため、GPU が安全。

---

3. launcher / manager-api の LLM 呼び出しを統一

✔ launcher（Worker）

• 旧：OllamaClient（直接叩く）
• 新：LLMExecutorClient（priority=1）

✔ manager-api（管理AI）

• 旧：OllamaClient（直接叩く）
• 新：LLMExecutorClient（priority=2）

✔ 検証レイヤ

• 旧：直接 bge-m3 を叩く
• 新：LLMExecutorClient（priority=3）

---

4. Validation Layer Version 3

Semantic Similarity（bge-m3）を安定化するために：

• Embedding API を /api/embeddings → /v1/embeddings に修正
• llm-executor 経由に統一
• Zero-vector 対策（cosine similarity の安全化）を導入
• IsolationForest 導入準備（正常データ収集）

これにより、検証レイヤの安定性が大幅に向上。

---

🏗️ アーキテクチャ（Version 3）

ユーザー（Next.js UI）
     ↓
管理AI（manager-api）
     ↓ Proposed API Calls
WorkerLauncher
     ↓
Worker（code_ai / scenario_ai / ...）
     ↓ LLM リクエスト
llm-executor
     ├─ PriorityQueue（1,2,3）
     ├─ GPU ロック
     └─ OllamaClient（/api/chat, /api/generate, /v1/embeddings）
          ↓
         Ollama

✔ Version 3 の特徴

• GPU を使う処理は 必ず llm-executor を通る
• GPU 競合が完全に排除される
• RTX 4060 でも安定して動作

---

📁 ディレクトリ構成（抜粋）

ai-town/
├── manager-api/
│   └── llm/llm_executor_client.py
├── launcher/
│   └── llm/llm_executor_client.py
├── llm-executor/
│   ├── main.py
│   └── executor/
│       ├── manager.py
│       └── ollama_client.py

---

🔧 llm-executor の実装ポイント

優先度付きキュー

self.queue.put((priority, self.seq, task))

GPU ロック

with self.lock:
    result = func()

run_forever でタスクを直列実行

while True:
    _, _, task = self.queue.get()
    task()

---

🧪 Semantic Similarity（bge-m3）の安定化

Version 3 では、Embedding API を以下に変更：

/v1/embeddings

これにより、bge-m3 が空ベクトルを返す問題が解消。

さらに、Zero-vector 対策として：

if norm1 == 0 or norm2 == 0:
    return 0.0

を導入し、NaN を完全に排除。

---

🧠 Obsidian 統合記憶システム

Worker は以下の Markdown を参照してタスクを実行：

• preferences.md
• style.md
• environment.md
• failures/
• improvements/

Version 3 でもこの仕組みは継続。

---

🛠️ セットアップ手順（抜粋）

llm-executor の起動

cd llm-executor
uvicorn main:app --port 10000

WorkerLauncher

uvicorn launcher.main:app --port 8000

manager-api

uvicorn main:app --port 9000

---

🔮 今後の拡張（Version 3.1〜）

• image_prompt_ai / video_prompt_ai の強化
• Obsidian ファイルの自動最適化
• IsolationForest の本格導入
• browser_ai / blender_ai / voice_ai
• マルチユーザー対応

---

📝 まとめ

Version 3 では、AI の町の根幹である LLM 呼び出しの安定性 を徹底的に改善しました。

• llm-executor による中央制御
• 優先度付きキュー
• GPU ロック
• Semantic Similarity の安定化
• launcher / manager-api の統一化

これにより、RTX 4060 でも安定して動作する 堅牢なマルチエージェント基盤が完成しました。