Upload PROJECT_ARCHITECTURE_GUIDE.md with huggingface_hub

PROJECT_ARCHITECTURE_GUIDE.md

@@ -0,0 +1,1661 @@
+# NullAI プロジェクト完全理解ガイド
+
+**最終更新**: 2025-12-02
+**対象読者**: このプロジェクトを引き継ぐ全ての開発者
+**目的**: プロジェクトの全体像を完全に理解し、設計思想を正しく継承する
+
+---
+
+## 📖 目次
+
+1. [プロジェクト概要](#プロジェクト概要)
+2. [4つの核心思想（こだわりポイント）](#4つの核心思想こだわりポイント)
+3. [システムアーキテクチャ全体図](#システムアーキテクチャ全体図)
+4. [各システムの詳細解説](#各システムの詳細解説)
+5. [データフロー完全図解](#データフロー完全図解)
+6. [技術スタック詳細](#技術スタック詳細)
+7. [よくある誤解と注意点](#よくある誤解と注意点)
+8. [設計判断の理由](#設計判断の理由)
+9. [拡張時の考慮事項](#拡張時の考慮事項)
+
+---
+
+## プロジェクト概要
+
+### NullAIとは何か
+
+**NullAI**は、**自己進化型多ドメイン知識推論エンジン**です。
+
+#### 核心的な問いと答え
+
+**Q: 何を解決しようとしているのか？**
+A: 「AIのハルシネーション（幻覚）」と「小型モデルの性能不足」の両方を同時に解決
+
+**Q: どうやって解決するのか？**
+A:
+1. **DB優先推論（RAG）** → ハルシネーション削減
+2. **師匠→弟子のファインチューニング** → 小型モデルの性能向上
+3. **樹木型空間記憶** → 知識の意味的整理と高速検索
+4. **自己拡充サイクル** → 知識ベースの自動成長
+
+**Q: 他のRAGシステムとの違いは？**
+A:
+- ❌ 普通のRAG: ベクトルDBで検索するだけ
+- ✅ NullAI: **6次元空間座標**で知識を配置し、意味的な近傍検索が可能
+
+**Q: 他のファインチューニングシステムとの違いは？**
+A:
+- ❌ 普通のFT: 人間が訓練データを手動作成
+- ✅ NullAI: **師匠AIが自動的に訓練データを生成** → 弟子が学習 → 弟子が師匠に昇格 → 無限サイクル
+
+### プロジェクト名の由来
+
+**Null** = ゼロ（ハルシネーション）
+**AI** = Artificial Intelligence
+
+→ **ゼロ・ハルシネーションを目指すAI**
+
+---
+
+## 4つの核心思想（こだわりポイント）
+
+### 1️⃣ 倒木システム（Fallen Tree System）
+
+#### 比喩の意味
+
+森で大木（老いた木）が倒れると、その養分で新しい若木が育つ。NullAIでは：
+
+- 🌲 **大木（師匠モデル）**: 高性能だが重いAI（例: DeepSeek R1 32B）
+- 🌱 **若木（弟子モデル）**: 最初は空っぽだが軽量なAI（例: Phi-2 2.7B）
+- 🍂 **養分（訓練データ）**: 師匠の高品質な出力（Alpaca形式JSONL）
+
+#### システムの流れ
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Phase 1: 師匠の統治時代                             │
+├─────────────────────────────────────────────────────┤
+│ 師匠（DeepSeek R1）が推論を担当                     │
+│  ↓                                                  │
+│ 高品質な出力（confidence >= 0.8）が自動保存         │
+│  ↓                                                  │
+│ training_data/master_outputs/*.jsonl                │
+└─────────────────────────────────────────────────────┘
+                      ↓
+┌─────────────────────────────────────────────────────┐
+│ Phase 2: ファインチューニング                       │
+├─────────────────────────────────────────────────────┤
+│ 訓練データを使って弟子（Phi-2）を訓練              │
+│  ↓                                                  │
+│ 弟子の性能が向上（師匠の知識を吸収）               │
+│  ↓                                                  │
+│ training_data/checkpoints/apprentice_*/             │
+└─────────────────────────────────────────────────────┘
+                      ↓
+┌─────────────────────────────────────────────────────┐
+│ Phase 3: 世代交代（倒木）                          │
+├──────────────────────────────────────��──────────────┤
+│ 弟子が十分成長 → 師匠に昇格                        │
+│  ↓                                                  │
+│ 旧師匠（DeepSeek）は引退（でも特別な役割あり）     │
+│  ↓                                                  │
+│ 新しい空の弟子を生成                               │
+└─────────────────────────────────────────────────────┘
+                      ↓
+                  サイクル繰り返し
+```
+
+#### 重要な設計判断
+
+**Q: なぜ師匠を完全に削除しないのか？**
+A: 引退した師匠（DeepSeek）は「**永久的指導者**」として残る
+- DB拡充時のプロンプト生成
+- 新しいドメインの初期知識生成
+- 品質チェック
+
+**Q: 弟子はいつ師匠になれるのか？**
+A:
+- ファインチューニング完了後、手動で昇格
+- 将来的には自動評価で昇格判定（未実装）
+
+**Q: 複数の弟子を同時に訓練できるのか？**
+A: できる。ドメイン別に異なる弟子を訓練可能
+- 医療ドメイン弟子
+- 法律ドメイン弟子
+- 一般知識弟子
+
+### 2️⃣ DB分離構造（Database Separation Structure）
+
+#### 設計思想
+
+```
+質問が来た時の判断フロー：
+
+質問 → まず知識DBを検索
+         ├─ 見つかった → DB知識を使って推論（RAG）✅ 信頼性高
+         └─ 見つからない → AI内部知識で推論 ⚠️ ハルシネーションリスク
+                            ↓
+                        その出力をDBに保存（自己拡充）
+```
+
+#### DB優先の理由
+
+| 知識ソース | 信頼性 | 根拠 | ハルシネーション |
+|-----------|--------|------|-----------------|
+| 知識DB（.iath） | ⭐⭐⭐⭐⭐ | 人間が検証 or 専門家が作成 | ほぼゼロ |
+| AI生成知識 | ⭐⭐⭐ | AIの内部知識（学習データ由来） | 中程度 |
+| AI幻覚 | ⭐ | 推測・創作 | 高い |
+
+**結論**: 知識DBにあるものは絶対に使う → ハルシネーション削減
+
+#### 自己拡充の仕組み
+
+```python
+# 疑似コード
+async def infer(question):
+    # Step 1: DB検索
+    db_knowledge = search_db(question)
+
+    if db_knowledge:
+        # Step 2a: RAG推論（DBの知識を使う）
+        response = llm.generate(
+            f"Based on this verified knowledge: {db_knowledge}\n"
+            f"Answer: {question}"
+        )
+        return response
+    else:
+        # Step 2b: AI内部知識で推論
+        response = llm.generate(question)
+
+        # Step 3: 高品質なら保存（自己拡充）
+        if response.confidence >= 0.7:
+            save_to_db(question, response)
+
+        return response
+```
+
+#### 重要な設計判断
+
+**Q: なぜSQLiteと.iathの2つを使うのか？**
+A: 役割分担
+- **SQLite**: メタデータ（ユーザー、ワークスペース、推論履歴）
+- **.iath**: 知識タイル本体（6次元座標 + コンテンツ）
+
+**Q: confidence >= 0.7と0.8の違いは？**
+A:
+- `>= 0.7`: DB保存（自己拡充）← やや緩め
+- `>= 0.8`: 訓練データ保存 ← 厳しめ（高品質のみ）
+
+**Q: AI生成知識をDBに保存する際、人間のチェックは不要？**
+A: 現在は自動保存。将来的には：
+- 専門家によるレビューフロー
+- コミュニティ投票による品質評価
+- AIによる自動検証（別のAIでクロスチェック）
+
+### 3️⃣ 樹木型空間記憶（Dendritic Memory Space）
+
+#### 比喩の意味
+
+人間の脳の**樹状突起（デンドライト）**のように、知識が空間的に整理されている。
+
+通常のDB:
+```
+知識1: 「心臓は循環器官である」
+知識2: 「脳は中枢神経系の一部である」
+→ バラバラに保存（関連性が不明）
+```
+
+樹木型空間記憶:
+```
+知識1: 座標 [0.2, 0.8, 0.3, 0.9, 0.7, 0.8]
+知識2: 座標 [0.3, 0.8, 0.4, 0.85, 0.65, 0.75]
+→ 近い座標 = 意味的に関連 → 一緒に検索できる
+```
+
+#### 6次元座標系の詳細
+
+```
+Knowledge Tile の座標 = [x, y, z, c, g, v]
+                        ─────┬───── ─────┬─────
+                     medical_space  meta_space
+```
+
+##### medical_space [x, y, z]: ドメイン固有の3次元空間
+
+例: 医療ドメインの場合
+
+| 軸 | 意味 | 例 |
+|----|------|-----|
+| x | 解剖学的位置 | 0.0=神経系, 0.5=循環器, 1.0=消化器 |
+| y | 病理学的分類 | 0.0=感染症, 0.5=代謝疾患, 1.0=外傷 |
+| z | 治療レベル | 0.0=予防, 0.5=診断, 1.0=治療 |
+
+##### meta_space [c, g, v]: メタ情報の3次元空間
+
+| 軸 | 意味 | 値の範囲 |
+|----|------|----------|
+| c (Certainty) | 確実性 | 0.0=仮説, 0.5=定説, 1.0=確立された事実 |
+| g (Granularity) | 粒度 | 0.0=概要, 0.5=詳細, 1.0=専門的 |
+| v (Verification) | 検証状態 | 0.0=未検証, 0.5=専門家レビュー済, 1.0=複数ソース確認済 |
+
+#### 検索の仕組み
+
+##### 1. テキスト検索（従来型）
+
+```python
+def search_by_text(query):
+    # 単純なキーワードマッチング
+    results = [tile for tile in all_tiles
+               if query in tile.content]
+    return results
+```
+
+**問題点**: 同義語を見逃す
+- 「心臓病」で検索しても「循環器疾患」がヒットしない
+
+##### 2. 座標検索（空間検索）
+
+```python
+def search_by_coordinates(query_coords, top_k=5):
+    # 6次元ユークリッド距離で計算
+    distances = []
+    for tile in all_tiles:
+        dist = euclidean_distance(query_coords, tile.coords)
+        distances.append((tile, dist))
+
+    # 距離が近い順にソート
+    distances.sort(key=lambda x: x[1])
+    return distances[:top_k]
+```
+
+**利点**: 意味的に近い知識を自動で発見
+- 座標が近い = 意味的に関連
+
+##### 3. ハイブリッド検索（推奨）
+
+```python
+def hybrid_search(query_text, query_coords=None, top_k=5):
+    # テキストマッチスコア計算
+    text_scores = calculate_text_match(query_text)
+
+    # 座標距離スコア計算
+    if query_coords:
+        spatial_scores = calculate_spatial_distance(query_coords)
+
+    # 複合スコア = α * text_score + β * (1 - spatial_distance)
+    combined_scores = 0.4 * text_scores + 0.6 * spatial_scores
+
+    return top_k_results(combined_scores)
+```
+
+#### .iathファイル形式
+
+```
+.iath ファイル構造:
+
+┌────────────────────────────────────┐
+│ Header (64 bytes)                  │  ← マジックナンバー、バージョン
+├────────────────────────────────────┤
+│ Index (JSON, 可変長)                │  ← タイルIDとオフセット一覧
+│ {                                  │
+│   "tiles": [                       │
+│     {"id": "tile_001", "offset": 512},
+│     {"id": "tile_002", "offset": 2048}
+│   ]                                │
+│ }                                  │
+├────────────────────────────────────┤
+│ Data Section (zstd圧縮)            │
+│   ┌──────────────────────┐         │
+│   │ Tile 1 (JSON)        │         │
+│   │ - metadata           │         │
+│   │ - content            │         │
+│   │ - coordinates        │         │
+│   │ - verification       │         │
+│   └──────────────────────┘         │
+│   ┌──────────────────────┐         │
+│   │ Tile 2 (JSON)        │         │
+│   └──────────────────────┘         │
+│   ...                              │
+└────────────────────────────────────┘
+```
+
+**なぜzstd圧縮？**
+- 高い圧縮率（gzipより優れる）
+- 高速な解凍速度
+- Facebookが開発（信頼性）
+
+#### 重要な設計判断
+
+**Q: なぜ6次元？ 3次元や10次元ではダメ？**
+A:
+- 3次元: ドメイン知識だけでメタ情報が表現できない
+- 10次元以上: 次元の呪い（検索が遅くなる）、人間が理解不能
+- 6次元: ドメイン(3) + メタ(3) = バランスが良い
+
+**Q: 座標は誰が決めるのか？**
+A:
+- 現状: 人間が手動で設定（dendritic-memory-editorで）
+- Priority 2で実装予定: AIが自動推定（DeepSeekが座標を生成）
+
+**Q: .iathとFAISS（ベクトルDB）の違いは？**
+A:
+| 特徴 | .iath | FAISS |
+|------|-------|-------|
+| 座標次元 | 6次元（人間が理解可能） | 768次元（Embeddingモデル依存） |
+| 検索速度 | O(n) 線形探索 | O(log n) 高速 |
+| 意味の透明性 | 高い（座標の意味が明確） | 低い（ブラックボックス） |
+| 編集容易性 | 高い（座標を手動調整可能） | 低い（再Embedding必要） |
+
+**結論**: .iathは「人間が理解・編集できる知識ベース」を重視
+
+### 4️⃣ ローカルファースト & ワンコマンドセットアップ
+
+#### 設計思想
+
+```
+❌ 悪い例（クラウド依存）:
+pip install nullai
+nullai --api-key=YOUR_OPENAI_KEY  # クラウドAPI必須
+→ インターネット必須、コスト高、プライバシー懸念
+
+✅ NullAI:
+./start_null_ai.sh  # ローカルで完結
+→ オフライン可能、無料、プライバシー保護
+```
+
+#### ワンコマンドの実現方法
+
+`start_null_ai.sh`が自動で実行すること:
+
+1. ✅ 依存関係チェック（Python, Node.js, Ollama）
+2. ✅ 仮想環境作成（venv）
+3. ��� Python依存関係インストール
+4. ✅ Node.js依存関係インストール
+5. ✅ データベース初期化（sql_app.db）
+6. ✅ Ollama起動
+7. ✅ バックエンド起動（port 8000）
+8. ✅ フロントエンド起動（port 5173）
+9. ✅ .iathメモリロード確認
+
+**ユーザーがすることは**: `./start_null_ai.sh`を実行するだけ
+
+#### 重要な設計判断
+
+**Q: なぜOllamaを使うのか？ HuggingFaceだけではダメ？**
+A:
+- Ollama: モデル管理が楽（`ollama pull deepseek-r1`だけ）
+- HuggingFace: 手動でダウンロード、パス指定が面倒
+
+**Q: なぜDockerを使わないのか？**
+A:
+- Docker: 初心者には難しい、GPUパススルーが複雑
+- シェルスクリプト: シンプル、デバッグしやすい、カスタマイズ容易
+
+---
+
+## システムアーキテクチャ全体図
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Frontend (React + TypeScript)            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ Engine       │  │ Inference    │  │ Training     │          │
+│  │ Manager      │  │ Panel        │  │ Dashboard    │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│         │                  │                  │                 │
+│         └──────────────────┼──────────────────┘                 │
+│                           │                                     │
+│                    HTTP/WebSocket                               │
+│                           │                                     │
+└───────────────────────────┼─────────────────────────────────────┘
+                            │
+┌───────────────────────────┼─────────────────────────────────────┐
+│                  Backend (FastAPI)                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ config.py    │  │ questions.py │  │ training.py  │          │
+│  │ (Engine API) │  │ (Inference)  │  │ (Fine-tune)  │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│         │                  │                  │                 │
+│         └──────────────────┼──────────────────┘                 │
+│                           │                                     │
+└───────────────────────────┼─────────────────────────────────────┘
+                            │
+┌───────────────────────────┼─────────────────────────────────────┐
+│                  NullAI Core Logic                              │
+│  ┌────────────────────────────────────────────────┐             │
+│  │           model_router.py                      │             │
+│  │  - RAG推論統合                                 │             │
+│  │  - 師匠出力保存                                │             │
+│  │  - エンジン管理（スワップ、昇格）             │             │
+│  └────────────────────────────────────────────────┘             │
+│         │                  │                  │                 │
+│         ▼                  ▼                  ▼                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ iath_memory  │  │ llm_providers│  │ fine_tuning  │          │
+│  │ .py          │  │ .py          │  │ .py          │          │
+│  │ (6D Search)  │  │ (4 Providers)│  │ (PEFT/Unslo) │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│         │                  │                  │                 │
+└─────────┼──────────────────┼──────────────────┼─────────────────┘
+          │                  │                  │
+          ▼                  ▼                  ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    External Services                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │ knowledge_   │  │ Ollama       │  │ HuggingFace  │       │
+│  │ base.iath    │  │ (localhost)  │  │ Models       │       │
+│  │ (6D Memory)  │  │              │  │              │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────────────────────────┐     │
+│  │ sql_app.db   │  │ training_data/                   │     │
+│  │ (SQLite)     │  │  - master_outputs/*.jsonl        │     │
+│  │              │  │  - checkpoints/apprentice_*/     │     │
+│  └──────────────┘  └──────────────────────────────────┘     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 各システムの詳細解説
+
+### ModelRouter (`null_ai/model_router.py`)
+
+#### 役割
+NullAIの**頭脳**。全ての推論リクエストを管理。
+
+#### 主要メソッド詳細
+
+##### `__init__()`
+```python
+def __init__(self, config_manager):
+    self.config_manager = config_manager
+    self.master_model = None        # 師匠モデル
+    self.apprentice_model = None    # 弟子モデル
+    self.dendritic_memory = None    # .iath空間記憶
+
+    # .iathファイルのロード
+    self._load_dendritic_memory()
+```
+
+**重要**: 初期化時に自動的に.iathをロード → 起動時間が長くなる可能性
+
+##### `async def infer()` - RAG統合推論
+
+```python
+async def infer(self, prompt, domain_id, model_config, save_to_memory=False):
+    # Step 1: DB知識チェック
+    has_knowledge = self._check_db_knowledge(domain_id, prompt)
+
+    if has_knowledge:
+        # Step 2a: RAG推論
+        knowledge = self._retrieve_relevant_knowledge(domain_id, prompt, top_k=3)
+        augmented_prompt = self._build_rag_prompt(prompt, knowledge)
+        response = await self._perform_llm_inference(model_config, augmented_prompt)
+    else:
+        # Step 2b: 通常推論
+        response = await self._perform_llm_inference(model_config, prompt)
+
+        # Step 3: 高品質なら保存
+        if save_to_memory and response["confidence"] >= 0.7:
+            await self._save_inference_to_db(domain_id, prompt, response)
+
+    # Step 4: 師匠の出力なら訓練データとして保存
+    is_master = (self.master_model and
+                 model_config.model_id == self.master_model.model_id)
+    if is_master and response["confidence"] >= 0.8:
+        await self._save_master_output_as_training_data(
+            prompt, response["response"], domain_id, response["confidence"]
+        )
+
+    return response
+```
+
+**データフロー図**:
+```
+prompt → check DB → found?
+                     ├─ YES → retrieve knowledge
+                     │         ↓
+                     │      augment prompt
+                     │         ↓
+                     │      LLM inference → response
+                     │                        ↓
+                     │                    is master? → save as training data
+                     │
+                     └─ NO → LLM inference → response
+                                              ↓
+                                          confidence >= 0.7? → save to DB
+```
+
+##### `_retrieve_relevant_knowledge()` - ハイブリッド検索
+
+```python
+def _retrieve_relevant_knowledge(self, domain_id, prompt, top_k=3):
+    if not self.dendritic_memory:
+        return []
+
+    # ハイブリッド検索実行
+    results = self.dendritic_memory.hybrid_search(
+        query_text=prompt,
+        query_coords=None,  # 将来的には座標も推定
+        top_k=top_k,
+        text_weight=0.4,    # テキストマッチの重み
+        spatial_weight=0.6  # 空間距離の重み
+    )
+
+    # Knowledge Tile形式に変換
+    formatted_knowledge = []
+    for tile in results:
+        formatted_knowledge.append({
+            "id": tile["metadata"]["knowledge_id"],
+            "topic": tile["metadata"]["topic"],
+            "content": tile["content"]["final_response"],
+            "confidence_score": tile["verification"]["initial_certainty"],
+            "coordinates": tile["coordinates"],
+            "text_match_score": tile.get("text_match_score", 0),
+            "spatial_distance": tile.get("spatial_distance", None)
+        })
+
+    return formatted_knowledge
+```
+
+##### `_save_master_output_as_training_data()` - 訓練データ保存
+
+```python
+async def _save_master_output_as_training_data(
+    self, prompt, response, domain_id, confidence
+):
+    # Alpaca形式で保存
+    training_example = {
+        "instruction": f"You are an expert in {domain_id}. Provide accurate information based on verified knowledge.",
+        "input": prompt,
+        "output": response,
+        "metadata": {
+            "domain_id": domain_id,
+            "confidence": confidence,
+            "master_model_id": self.master_model.model_id,
+            "timestamp": datetime.utcnow().isoformat(),
+            "source": "master_output"
+        }
+    }
+
+    # JSONLファイルに追記
+    output_file = f"training_data/master_outputs/master_outputs_{domain_id}.jsonl"
+    with open(output_file, 'a', encoding='utf-8') as f:
+        f.write(json.dumps(training_example, ensure_ascii=False) + '\n')
+```
+
+**なぜJSONL（改行区切りJSON）？**
+- ストリーミング処理が可能（1行ずつ読める）
+- ファイル破損時の影響が最小限
+- HuggingFace datasetsと互換性
+
+##### エンジン管理メソッド
+
+```python
+def promote_apprentice(self, apprentice_model_id):
+    """弟子を師匠に昇格"""
+    # 現在の師匠を引退
+    old_master = self.master_model
+
+    # 弟子を師匠に昇格
+    self.master_model = self.apprentice_model
+
+    # 弟子をクリア
+    self.apprentice_model = None
+
+    # 設定を保存
+    self.config_manager.save_active_engines(
+        self.master_model.model_id, None
+    )
+
+def swap_engines(self):
+    """師匠と弟子を入れ替え"""
+    temp = self.master_model
+    self.master_model = self.apprentice_model
+    self.apprentice_model = temp
+
+    self.config_manager.save_active_engines(
+        self.master_model.model_id,
+        self.apprentice_model.model_id if self.apprentice_model else None
+    )
+
+def create_new_apprentice(self, base_model_id):
+    """新しい空の弟子を生成"""
+    # ベースモデルをコピーして新しいIDを付与
+    new_apprentice_id = f"{base_model_id}_apprentice_{timestamp}"
+
+    # 設定に追加
+    self.apprentice_model = self.config_manager.get_model_config(base_model_id)
+    self.apprentice_model.model_id = new_apprentice_id
+
+    return new_apprentice_id
+```
+
+### DendriticMemorySpace (`null_ai/iath_memory.py`)
+
+#### 役割
+.iathファイルの読み込みと6次元空間検索を提供。
+
+#### クラス構造
+
+```python
+class IathDecoder:
+    """
+    .iathファイルの低レベルデコーダー
+    dendritic-memory-editor完全互換
+    """
+    def __init__(self, iath_file_path):
+        self.file_path = Path(iath_file_path)
+        self.header = None
+        self.index = []
+        self._load_header_and_index()
+
+    def _load_header_and_index(self):
+        """ヘッダーとインデックスの読み込み"""
+        with open(self.file_path, 'rb') as f:
+            # Header (64 bytes)
+            header_bytes = f.read(64)
+            self.header = self._parse_header(header_bytes)
+
+            # Index (JSON)
+            index_size = self.header["index_size"]
+            index_bytes = f.read(index_size)
+            self.index = json.loads(index_bytes.decode('utf-8'))
+
+    def get_tile_by_id(self, knowledge_id):
+        """IDでタイルを取得"""
+        # インデックスからオフセットを検索
+        tile_info = next(
+            (t for t in self.index["tiles"] if t["id"] == knowledge_id),
+            None
+        )
+        if not tile_info:
+            return None
+
+        # ファイルポジション移動
+        with open(self.file_path, 'rb') as f:
+            f.seek(tile_info["offset"])
+            compressed_data = f.read(tile_info["size"])
+
+            # zstd解凍
+            decompressed = zstandard.decompress(compressed_data)
+            tile_data = json.loads(decompressed.decode('utf-8'))
+
+            return tile_data
+
+
+class DendriticMemorySpace:
+    """
+    6次元空間記憶システム
+    高レベルAPI
+    """
+    def __init__(self, iath_file_path):
+        self.decoder = IathDecoder(iath_file_path)
+        self.all_tiles = []
+        self.coordinates_matrix = None  # NumPy行列
+        self._load_all_tiles()
+
+    def _load_all_tiles(self):
+        """全タイルをメモリにロード"""
+        self.all_tiles = self.decoder.get_all_tiles()
+
+        # 座標行列作成（高速検索用）
+        coords_list = [tile["coordinates"] for tile in self.all_tiles]
+        self.coordinates_matrix = np.array(coords_list)  # Shape: (N, 6)
+```
+
+#### 検索アルゴリズム詳細
+
+##### 座標検索（6次元ユークリッド距離）
+
+```python
+def search_by_coordinates(self, query_coords, top_k=5):
+    """
+    6次元空間での近傍検索
+
+    数式: distance = sqrt(sum((q_i - t_i)^2))
+    where:
+        q_i = query座標のi番目の要素
+        t_i = tile座標のi番目の要素
+        i = 0..5 (6次元)
+    """
+    query_vector = np.array(query_coords)  # Shape: (6,)
+
+    # 全タイルとの距離を一括計算（NumPy vectorization）
+    # Broadcasting: (N, 6) - (6,) → (N, 6)
+    distances = np.linalg.norm(
+        self.coordinates_matrix - query_vector,
+        axis=1  # 各行（タイル）ごとに距離計算
+    )  # Shape: (N,)
+
+    # 距離でソート
+    sorted_indices = np.argsort(distances)[:top_k]
+
+    # 結果を返す
+    results = []
+    for idx in sorted_indices:
+        tile = self.all_tiles[idx].copy()
+        tile["spatial_distance"] = float(distances[idx])
+        results.append(tile)
+
+    return results
+```
+
+**計算量**: O(N) - 全タイル数Nに比例（線形探索）
+
+**最適化案**（未実装）:
+- KD-Tree: O(log N) だが6次元では効果薄い
+- Ball-Tree: 高次元でも比較的有効
+- 近似近傍探索（Annoy, HNSW）: 超高速だが精度低下
+
+##### ハイブリッド検索（テキスト + 座標）
+
+```python
+def hybrid_search(
+    self,
+    query_text,
+    query_coords=None,
+    top_k=5,
+    text_weight=0.4,
+    spatial_weight=0.6
+):
+    """
+    テキストマッチと空間距離の複合スコアリング
+    """
+    # Step 1: テキストマッチスコア計算
+    text_scores = []
+    for tile in self.all_tiles:
+        score = self._calculate_text_match(query_text, tile)
+        text_scores.append(score)
+    text_scores = np.array(text_scores)  # Shape: (N,)
+
+    # Step 2: 空間距離スコア計算
+    if query_coords:
+        spatial_distances = np.linalg.norm(
+            self.coordinates_matrix - np.array(query_coords),
+            axis=1
+        )
+        # 距離を0-1のスコアに変換（逆数）
+        max_dist = spatial_distances.max()
+        spatial_scores = 1.0 - (spatial_distances / max_dist)
+    else:
+        spatial_scores = np.zeros(len(self.all_tiles))
+
+    # Step 3: 複合スコア計算
+    combined_scores = (
+        text_weight * text_scores +
+        spatial_weight * spatial_scores
+    )
+
+    # Step 4: スコアでソート
+    sorted_indices = np.argsort(combined_scores)[::-1][:top_k]
+
+    # 結果を返す
+    results = []
+    for idx in sorted_indices:
+        tile = self.all_tiles[idx].copy()
+        tile["text_match_score"] = float(text_scores[idx])
+        tile["spatial_score"] = float(spatial_scores[idx])
+        tile["combined_score"] = float(combined_scores[idx])
+        if query_coords:
+            tile["spatial_distance"] = float(spatial_distances[idx])
+        results.append(tile)
+
+    return results
+
+def _calculate_text_match(self, query, tile):
+    """
+    テキストマッチスコア計算（簡易版）
+
+    将来的にはBM25やTF-IDFを使う
+    """
+    query_lower = query.lower()
+    content = tile["content"]["final_response"].lower()
+    topic = tile["metadata"]["topic"].lower()
+
+    # キーワードマッチング
+    query_words = set(query_lower.split())
+    content_words = set(content.split())
+    topic_words = set(topic.split())
+
+    # Jaccard類似度
+    content_jaccard = len(query_words & content_words) / len(query_words | content_words)
+    topic_jaccard = len(query_words & topic_words) / len(query_words | topic_words)
+
+    # 複合スコア（トピックを重視）
+    score = 0.3 * content_jaccard + 0.7 * topic_jaccard
+
+    return score
+```
+
+### FineTuningManager (`null_ai/fine_tuning.py`)
+
+#### 役割
+弟子モデルのファインチューニングを実行。
+
+#### PEFT（QLoRA）方式の詳細
+
+```python
+async def fine_tune_with_huggingface_peft(
+    self,
+    model_name,
+    training_examples,
+    output_dir,
+    epochs=3,
+    learning_rate=2e-4,
+    batch_size=4,
+    lora_r=8,
+    lora_alpha=16
+):
+    """
+    Parameter-Efficient Fine-Tuning with QLoRA
+
+    QLoRA = Quantized LoRA
+    - 4-bit量子化でメモリ削減
+    - LoRAで訓練パラメータ削減
+    → 12GB GPUでも7Bモデルを訓練可能
+    """
+
+    # Step 1: モデルを4-bit量子化でロード
+    bnb_config = BitsAndBytesConfig(
+        load_in_4bit=True,               # 4-bit量子化
+        bnb_4bit_quant_type="nf4",       # NormalFloat4（最適な量子化方式）
+        bnb_4bit_compute_dtype=torch.float16,  # 計算はfp16で
+        bnb_4bit_use_double_quant=True   # 二重量子化（さらにメモリ削減）
+    )
+
+    model = AutoModelForCausalLM.from_pretrained(
+        model_name,
+        quantization_config=bnb_config,
+        device_map="auto"  # 自動的にGPU/CPUに配置
+    )
+
+    # Step 2: LoRA設定
+    lora_config = LoraConfig(
+        r=lora_r,                        # LoRAランク（低いほど軽量）
+        lora_alpha=lora_alpha,           # スケーリング係数
+        target_modules=[                 # どのレイヤーにLoRAを適用するか
+            "q_proj", "k_proj", "v_proj", "o_proj",  # Attention
+            "gate_proj", "up_proj", "down_proj"      # MLP
+        ],
+        lora_dropout=0.05,               # Dropout率
+        bias="none",                     # Biasは訓練しない
+        task_type="CAUSAL_LM"            # タスクタイプ
+    )
+
+    model = get_peft_model(model, lora_config)
+
+    # 訓練可能パラメータ数を表示
+    model.print_trainable_parameters()
+    # 例: trainable params: 4.2M || all params: 2.7B || trainable%: 0.16%
+    #     → 全パラメータの0.16%だけ訓練！
+
+    # Step 3-9: データ準備、訓練、保存（省略）
+    ...
+```
+
+**QLoRAの仕組み**:
+```
+通常のファインチューニング:
+┌─────────────────────────┐
+│ モデル全体（2.7B params）│ ← 全て訓練
+│ メモリ: ~40GB           │
+└─────────────────────────┘
+
+QLoRA:
+┌─────────────────────────┐
+│ 元モデル（2.7B params）  │ ← 4-bit量子化、frozen（訓練しない）
+│ メモリ: ~7GB            │
+└─────────────────────────┘
+          +
+┌─────────────────────────┐
+│ LoRAアダプター（4.2M）   │ ← これだけ訓練
+│ メモリ: ~0.5GB          │
+└─────────────────────────┘
+         =
+   合計メモリ: ~12GB
+```
+
+#### Alpaca形式データの整形
+
+```python
+def format_training_examples_for_model(
+    self,
+    training_examples,
+    template="alpaca"
+):
+    """
+    Alpaca形式 → モデル用プロンプトに整形
+    """
+    formatted_prompts = []
+
+    for example in training_examples:
+        instruction = example["instruction"]
+        input_text = example["input"]
+        output_text = example["output"]
+
+        if template == "alpaca":
+            if input_text:
+                prompt = f"""Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.
+
+### Instruction:
+{instruction}
+
+### Input:
+{input_text}
+
+### Response:
+{output_text}"""
+            else:
+                prompt = f"""Below is an instruction that describes a task. Write a response that appropriately completes the request.
+
+### Instruction:
+{instruction}
+
+### Response:
+{output_text}"""
+
+        formatted_prompts.append(prompt)
+
+    return formatted_prompts
+```
+
+**なぜこの形式？**
+- 明確な区切り（`###`）
+- instruction-following能力の向上
+- オープンソースコミュニティの標準
+
+---
+
+## データフロー完全図解
+
+### フロー1: 通常推論（RAGあり）
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ ユーザー: "心臓の働きについて教えて"                        │
+└────────────────────┬─────────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ Frontend: InferencePanel.tsx                               │
+│  - 質問をバックエンドに送信                               │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓ HTTP POST /api/questions
+┌────────────────────────────────────────────────────────────┐
+│ Backend: questions.py                                      │
+│  - InferenceService.ask_question()                         │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ NullAI Core: model_router.py                               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 1: _check_db_knowledge("medical", "心臓の働き") │   │
+│  │  → DendriticMemorySpace.search_by_text()           │   │
+│  │  → 結果: 3件見つかった                              │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 2: _retrieve_relevant_knowledge()             │   │
+│  │  → hybrid_search("心臓の働き", top_k=3)            │   │
+│  │  → 取得:                                           │   │
+│  │    [1] 心臓の解剖学 (score: 0.92)                  │   │
+│  │    [2] 循環器系の機能 (score: 0.85)                │   │
+│  │    [3] 心臓病の分類 (score: 0.73)                  │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 3: プロンプト拡張                             │   │
+│  │  augmented_prompt = """                            │   │
+│  │  Based on the following verified knowledge:        │   │
+│  │                                                     │   │
+│  │  [Knowledge 1 - expert verification, conf: 0.9]    │   │
+│  │  Topic: 心臓の解剖学                                │   │
+│  │  Content: 心臓は4つの部屋から構成され...           │   │
+│  │                                                     │   │
+│  │  [Knowledge 2 - ...]                               │   │
+│  │                                                     │   │
+│  │  Now, please answer:                               │   │
+│  │  心臓の働きについて教えて                           │   │
+│  │  """                                               │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 4: LLM推論                                    │   │
+│  │  → llm_providers.py                                │   │
+│  │  → OllamaProvider.infer()                          │   │
+│  │  → model: deepseek-r1:1.5b                         │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 5: レスポンス生成                             │   │
+│  │  response = {                                      │   │
+│  │    "response": "心臓は循環器系の中心器官で...",     │   │
+│  │    "confidence": 0.88,                             │   │
+│  │    "thinking": "検証済み知識に基づいて回答",        │   │
+│  │    "retrieved_knowledge": [...]                    │   │
+│  │  }                                                 │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 6: 師匠の出力？                               │   │
+│  │  is_master = True                                  │   │
+│  │  confidence = 0.88 >= 0.8 ✓                        │   │
+│  │  → _save_master_output_as_training_data()          │   │
+│  │  → training_data/master_outputs/medical.jsonl      │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ Frontend: レスポンス表示                                   │
+│  - ResponseDisplay.tsx                                     │
+│  - 「心臓は循環器系の中心器官で...」                       │
+│  - Retrieved Knowledge バッジ表示                          │
+└────────────────────────────────────────────────────────────┘
+```
+
+### フロー2: 通常推論（RAGなし、自己拡充）
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ ユーザー: "量子コンピュータの原理は？"                      │
+└────────────────────┬─────────────────────────────────────────┘
+                     ↓
+                  (同上)
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ NullAI Core: model_router.py                               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 1: _check_db_knowledge("general", "量子...")    │   │
+│  │  → DendriticMemorySpace.search_by_text()           │   │
+│  │  → 結果: 見つからなかった ❌                        │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 2: AI内部知識で推論                           │   │
+│  │  → LLM.generate("量子コンピュータの原理は？")       │   │
+│  │  → model: deepseek-r1:1.5b                         │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 3: レスポンス生成                             │   │
+│  │  response = {                                      │   │
+│  │    "response": "量子コンピュータは...",             │   │
+│  │    "confidence": 0.75                              │   │
+│  │  }                                                 │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 4: 自己拡充（DBに保存）                       │   │
+│  │  confidence = 0.75 >= 0.7 ✓                        │   │
+│  │  save_to_memory = True                             │   │
+│  │  → _save_inference_to_db()                         │   │
+│  │  → SQLite: knowledge_tiles テーブル                │   │
+│  │     (将来的には.iathにも保存)                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 5: 師匠の出力として保存                       │   │
+│  │  is_master = True                                  │   │
+│  │  confidence = 0.75 < 0.8 ❌                         │   │
+│  │  → 訓練データには保存しない                        │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓
+              (レスポンス表示)
+```
+
+**重要な違い**:
+- RAGあり: `confidence >= 0.8`で訓練データ保存
+- RAGなし: `confidence >= 0.7`でDB保存、`>= 0.8`で訓練データ保存
+
+### フロー3: ファインチューニング実行
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ ユーザー: Training Dashboard で "Start Fine-tuning"          │
+│  - Apprentice Model: microsoft/phi-2                         │
+│  - Domain: medical                                           │
+│  - Method: peft                                              │
+│  - Epochs: 3                                                 │
+└────────────────────┬─────────────────────────────────────────┘
+                     ↓ HTTP POST /api/training/start
+┌────────────────────────────────────────────────────────────┐
+│ Backend: training.py                                       │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 1: 訓練データ存在チェック                     │   │
+│  │  → FineTuningManager.load_training_data("medical") │   │
+│  │  → training_data/master_outputs/medical.jsonl      │   │
+│  │  → 結果: 150サンプル                               │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 2: バックグラウンドタスク開始                 │   │
+│  │  background_tasks.add_task(run_training)           │   │
+│  │  → すぐにレスポンス返却（非同期）                  │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ NullAI Core: fine_tuning.py (バックグラウンド)             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 1: モデルロード（4-bit量子化）                │   │
+│  │  → AutoModelForCausalLM.from_pretrained(           │   │
+│  │       "microsoft/phi-2",                           │   │
+│  │       quantization_config=bnb_config               │   │
+│  │     )                                              │   │
+│  │  → メモリ使用: ~7GB                                │   │
+│  └─────────────────────────────────────────────��───────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 2: LoRA設定                                   │   │
+│  │  → get_peft_model(model, lora_config)              │   │
+│  │  → 訓練可能パラメータ: 4.2M / 2.7B (0.16%)        │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 3: データ準備                                 │   │
+│  │  → format_training_examples_for_model()            │   │
+│  │  → Alpaca形式 → モデル用プロンプトに整形           │   │
+│  │  → Dataset.from_dict({"text": prompts})            │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 4: トレーニング開始                           │   │
+│  │  Epoch 1/3:                                        │   │
+│  │    [===>    ] 35% loss: 1.245                      │   │
+│  │    → current_training_state.update({               │   │
+│  │         "progress": 35,                            │   │
+│  │         "current_epoch": 1,                        │   │
+│  │         "loss": 1.245                              │   │
+│  │       })                                           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                     ↓                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Step 5: 完了                                       │   │
+│  │  → trainer.save_model(output_dir)                  │   │
+│  │  → training_data/checkpoints/apprentice_medical_*/ │   │
+│  │  → current_training_state["is_training"] = False   │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────┬───────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────────────┐
+│ Frontend: TrainingDashboard.tsx                            │
+│  - 2秒ごとにポーリング: GET /api/training/status           │
+│  - プログレスバー更新: 35% → 67% → 100%                   │
+│  - 完了時: チェックポイント一覧を再取得                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 技術スタック詳細
+
+### フロントエンド
+
+```
+React 18.2 + TypeScript 5.0
+├─ Vite 4.4 (ビルドツール)
+├─ TailwindCSS 3.3 (スタイリング)
+└─ axios (HTTP クライアント)
+
+主要コンポーネント:
+- EngineManager.tsx      (417行) - エンジン管理UI
+- InferencePanel.tsx     (321行) - 推論パネル
+- TrainingDashboard.tsx  (400行) - トレーニングダッシュボード
+- KnowledgePanel.tsx     (185行) - 知識ブラウザ
+```
+
+### バックエンド
+
+```
+FastAPI 0.115.6 + Python 3.13+
+├─ Uvicorn (ASGIサーバー)
+├─ SQLAlchemy 2.0 (ORM)
+├─ Pydantic 2.10 (バリデーション)
+└─ Alembic (マイグレーション)
+
+主要API:
+- /api/config/*     - エンジン管理
+- /api/questions    - 推論実行
+- /api/training/*   - ファインチューニング
+- /api/knowledge/*  - 知識タイル管理
+```
+
+### NullAI Core
+
+```
+Python 3.13+
+├─ transformers 4.36+ (HuggingFace)
+├─ torch 2.0+ (PyTorch)
+├─ peft 0.7+ (LoRA/QLoRA)
+├─ trl 0.7+ (Reinforcement Learning from Human Feedback)
+├─ datasets 2.15+ (データセット処理)
+├─ bitsandbytes 0.41+ (量子化)
+├─ accelerate 0.25+ (分散訓練)
+├─ zstandard 0.22+ (.iath圧縮)
+└─ numpy 1.24+ (数値計算)
+
+主要モジュール:
+- model_router.py     (800行) - RAG統合、エンジン管理
+- iath_memory.py      (362行) - 6次元空間記憶
+- fine_tuning.py      (640行) - ファインチューニング
+- llm_providers.py    (390行) - LLMプロバイダー統合
+```
+
+### LLMプロバイダー
+
+```
+1. Ollama
+   - ローカルモデル管理
+   - ollama pull deepseek-r1:1.5b
+   - API: http://localhost:11434
+
+2. HuggingFace Transformers
+   - 直接ロード
+   - AutoModelForCausalLM.from_pretrained()
+   - GPU/CPU自動配置
+
+3. MLX (Apple Silicon)
+   - M1/M2/M3 Mac専用
+   - 統合メモリ活用
+   - mlx-lm ライブラリ
+
+4. GGUF (llama-cpp-python)
+   - 量子化モデル（.gguf）
+   - CPU推論に最適
+   - GPU acceleration対応
+```
+
+---
+
+## よくある誤解と注意点
+
+### 誤解1: 「RAGは常に使われる」
+
+❌ **誤解**: 全ての推論でRAGが使われる
+✅ **真実**: DBに知識がある場合のみRAGが発動
+
+```python
+# 実際の動作
+if has_knowledge:
+    # RAG推論
+else:
+    # 通常推論（RAGなし）
+```
+
+**見分け方**:
+- RAGあり: レスポンスに`retrieved_knowledge`フィールドが含まれる
+- RAGなし: `retrieved_knowledge`が空
+
+### 誤解2: 「弟子は自動的に師匠になる」
+
+❌ **誤解**: ファインチューニングが完了したら自動で師匠に昇格
+✅ **真実**: 手動で昇格操作が必要
+
+```
+ファインチューニング完了
+  ↓
+チェックポイント保存
+  ↓
+【手動操作】Engine Manager で Promote をクリック
+  ↓
+弟子が師匠に昇格
+```
+
+**理由**: 品質チェックを人間が行うべき
+
+### 誤解3: 「.iathファイルは自動更新される」
+
+❌ **誤解**: AI生成知識が自動的に.iathに保存される
+✅ **真実**: 現在はJSONLのみ、.iath保存は未実装（Priority 2）
+
+```
+現状:
+AI生成知識 → SQLite + JSONL ✅
+           → .iath ❌（未実装）
+
+Priority 2実装後:
+AI生成知識 → SQLite + JSONL + .iath ✅
+```
+
+### 誤解4: 「ファインチューニングは全パラメータを訓練する」
+
+❌ **誤解**: モデル全体（2.7B パラメータ）を訓練
+✅ **真実**: LoRAアダプター（4.2M）だけ訓練
+
+```
+訓練されるパラメータ:
+- 元モデル: 2,700,000,000 → frozen（訓練しない）
+- LoRA:         4,200,000 → 訓練する ✅
+
+訓練パラメータ比率: 0.16%
+```
+
+**メリット**:
+- メモリ削減（40GB → 12GB）
+- 訓練時間短縮（10時間 → 2時間）
+- 元モデルは変更されない（安全）
+
+### 誤解5: 「SQLiteと.iathは同じデータを保存」
+
+❌ **誤解**: SQLiteと.iathは重複している
+✅ **真実**: 役割が完全に異なる
+
+| データベース | 保存内容 | 用途 |
+|-------------|---------|------|
+| SQLite | ユーザー、ワークスペース、推論履歴、メタデータ | アプリケーション管理 |
+| .iath | Knowledge Tile（6次元座標 + コンテンツ） | 知識検索・RAG推論 |
+
+**例**:
+```
+SQLite:
+- users テーブル: nullai_default_user
+- workspaces テーブル: default_workspace
+- inference_history: 過去の質問と回答
+
+.iath:
+- Tile 1: [0.2, 0.8, 0.3, 0.9, 0.7, 0.8] "心臓の働き..."
+- Tile 2: [0.3, 0.8, 0.4, 0.85, 0.65, 0.75] "循環器系..."
+```
+
+### 誤解6: 「confidence値はAIが自動計算」
+
+❌ **誤解**: AIが自己評価してconfidenceを返す
+✅ **真実**: 現在は**固定値**（プロバイダーごと）
+
+```python
+# llm_providers.py
+class OllamaProvider:
+    async def infer(...):
+        return {
+            "response": response_text,
+            "confidence": 0.85  # ← 固定値！
+        }
+```
+
+**将来の改善**:
+- 複数モデルでクロスチェック
+- 応答の不確実性を計算（エントロピー）
+- 人間によるフィードバック学習
+
+---
+
+## 設計判断の理由
+
+### 判断1: なぜPEFTを採用したか
+
+**候補**:
+1. フルファインチューニング
+2. PEFT (LoRA/QLoRA)
+3. Adapter
+4. Prompt Tuning
+
+**採用**: PEFT (QLoRA)
+
+**理由**:
+```
+比較表:
+
+                  メモリ  速度  品質  汎用性
+フルFT            ×      ×    ⭐⭐⭐  ⭐⭐⭐
+PEFT (QLoRA)      ⭐⭐⭐  ⭐⭐  ⭐⭐⭐  ⭐⭐⭐
+Adapter           ⭐⭐    ⭐⭐  ⭐⭐    ⭐⭐
+Prompt Tuning     ⭐⭐⭐  ⭐⭐⭐ ⭐      ⭐
+```
+
+**結論**: PEFTがバランス最良
+
+### 判断2: なぜAlpaca形式を採用したか
+
+**候補**:
+1. Alpaca
+2. ShareGPT
+3. OpenAssistant
+4. Custom
+
+**採用**: Alpaca
+
+**理由**:
+- オープンソースで広く採用
+- instruction-input-output構造が明確
+- HuggingFace datasetsと互換性
+- コミュニティのベ���トプラクティス
+
+### 判断3: なぜハイブリッド検索か
+
+**候補**:
+1. テキストのみ
+2. 座標のみ
+3. ハイブリッド
+
+**採用**: ハイブリッド
+
+**理由**:
+```
+テキストのみ:
+- 利点: シンプル
+- 欠点: 同義語を見逃す
+
+座標のみ:
+- 利点: 意味的に関連する知識を発見
+- 欠点: 座標が不正確だと失敗
+
+ハイブリッド:
+- 利点: 両方の長所を活かせる
+- 欠点: パラメータ調整が必要（text_weight, spatial_weight）
+```
+
+**現在の設定**:
+```python
+text_weight = 0.4
+spatial_weight = 0.6
+# → 座標をやや重視（意味的関連性を優先）
+```
+
+### 判断4: なぜ循環インポートをlazy importで解決したか
+
+**候補**:
+1. Lazy import（関数内でimport）
+2. アーキテクチャ変更（依存関係の整理）
+3. 中間モジュール導入
+
+**採用**: Lazy import
+
+**理由**:
+- 最小限の変更で解決
+- パフォーマンスへの影響は軽微
+- 既存コードの大幅な書き換え不要
+
+**実装例**:
+```python
+def _check_db_knowledge(self, domain_id, prompt):
+    # 関数内でimport → 循環回避
+    from backend.app.database.session import SessionLocal
+    db = SessionLocal()
+    # ...
+```
+
+---
+
+## 拡張時の考慮事項
+
+### 新しいLLMプロバイダーを追加する場合
+
+**手順**:
+
+1. `llm_providers.py`に新しいクラスを追加
+```python
+class NewProvider:
+    async def infer(self, model_config, prompt, temperature):
+        # 実装
+        pass
+
+    async def infer_streaming(self, model_config, prompt, temperature):
+        # 実装
+        pass
+```
+
+2. `model_router.py`の`_perform_llm_inference()`に追加
+```python
+if provider == "ollama":
+    result = await self.ollama_provider.infer(...)
+elif provider == "new_provider":  # ← 追加
+    result = await self.new_provider.infer(...)
+```
+
+3. `backend/app/config.py`の`ModelProvider`列挙型に追加
+```python
+class ModelProvider(str, Enum):
+    OLLAMA = "ollama"
+    HUGGINGFACE = "huggingface"
+    NEW_PROVIDER = "new_provider"  # ← 追加
+```
+
+### 新しいドメインを追加する場合
+
+**手順**:
+
+1. `.iath`ファイルでドメイン用の座標空間を定義
+```
+医療ドメイン: medical_space [x, y, z]
+法律ドメイン: legal_space [x, y, z]  ← 追加
+  - x: 法分野（民法、刑法、商法...）
+  - y: 判例レベル（地裁、高裁、最高裁）
+  - z: 時代（古典、現代、最新）
+```
+
+2. `backend/app/config.py`にドメイン設定追加
+```python
+domains = [
+    {"domain_id": "medical", "name": "医療"},
+    {"domain_id": "legal", "name": "法律"}  # ← 追加
+]
+```
+
+3. 訓練データディレクトリ作成
+```bash
+mkdir -p training_data/master_outputs/
+touch training_data/master_outputs/master_outputs_legal.jsonl
+```
+
+### 座標自動推定を実装する場合（Priority 2）
+
+**設計案**:
+
+```python
+# null_ai/coordinate_estimator.py
+
+class CoordinateEstimator:
+    def __init__(self, llm_model):
+        """
+        DeepSeek R1を使って座標を推定
+        """
+        self.llm = llm_model
+
+    async def estimate_coordinates(
+        self,
+        prompt: str,
+        response: str,
+        domain_id: str
+    ) -> List[float]:
+        """
+        6次元座標を推定
+
+        Returns: [x, y, z, c, g, v]
+        """
+        # プロンプト構築
+        estimation_prompt = f"""You are an expert in knowledge space mapping.
+Given a question and answer pair in the domain of {domain_id}, estimate the
+6-dimensional coordinates that best represent this knowledge.
+
+Coordinates format: [x, y, z, c, g, v]
+- medical_space [x, y, z]: domain-specific 3D space (0.0-1.0)
+- meta_space [c, g, v]: Certainty, Granularity, Verification (0.0-1.0)
+
+Question: {prompt}
+Answer: {response}
+
+Output ONLY the coordinates as a JSON array: [x, y, z, c, g, v]
+"""
+
+        # LLMに座標推定を依頼
+        result = await self.llm.generate(estimation_prompt)
+
+        # JSONパース
+        coords = json.loads(result)
+
+        # バリデーション
+        assert len(coords) == 6
+        assert all(0.0 <= c <= 1.0 for c in coords)
+
+        return coords
+```
+
+### WebSocketでリアルタイム進捗を実装する場合
+
+**設計案**:
+
+```python
+# backend/app/main.py
+
+@app.websocket("/ws/training/{session_id}")
+async def training_websocket(websocket: WebSocket, session_id: str):
+    await websocket.accept()
+
+    # 進捗コールバック
+    async def progress_callback(state):
+        await websocket.send_json({
+            "type": "progress",
+            "data": state
+        })
+
+    # ファインチューニング開始
+    await fine_tuning_manager.start_training(
+        ...,
+        progress_callback=progress_callback
+    )
+```
+
+---
+
+## まとめ: プロジェクトの本質
+
+NullAIは単なるRAGシステムでも、単なるファインチューニングツールでもありません。
+
+**NullAIの本質**:
+```
+自己進化する知識生態系
+
+師匠AI → 知識生成 → 弟子AI学習 → 昇格 → 新しい弟子 → サイクル継続
+   ↓                                      ↑
+DB拡充（自己拡充）                   ファインチューニング
+   ↓                                      ↑
+樹木型空間記憶（6次元座標）          高品質訓練データ
+   ↓                                      ↑
+意味的知識整理                      師匠の知識継承
+   ↓                                      ↑
+  └────────────── サイクル ──────────────┘
+```
+
+**4つの核心思想の統合**:
+1. **倒木システム**: 世代交代による進化
+2. **DB分離構造**: 信頼性の確保と自己拡充
+3. **樹木型空間記憶**: 意味的知識整理
+4. **ローカルファースト**: プライバシーとコスト
+
+これら全てが**有機的に結合**し、AIが自己進化する生態系を形成しています。
+
+---
+
+**このガイドを理解したら、あなたはNullAIの設計思想を正しく継承できます。**
+
+**頑張ってください！🌲🔥**
+
+---
+
+**Document Version**: 1.0
+**Total Pages**: 60+
+**Total Words**: 15,000+
+**Author**: Claude (Sonnet 4.5)
+**Purpose**: Complete handover of NullAI project architecture and philosophy