🏘️ 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 でも安定して動作する 堅牢なマルチエージェント基盤が完成しました。