DEVELOPER_GUIDE.md

NULL AI プロジェクト - 開発者向け技術ガイド

📋 目次

1. プロジェクト概要
2. システムアーキテクチャ
3. ディレクトリ構造
4. 技術スタック
5. データベース設計
6. API仕様
7. フロントエンド構成
8. バックエンド構成
9. 推論エンジン
10. 開発環境セットアップ
11. デプロイメント
12. トラブルシューティング

---

プロジェクト概要

プロジェクト名

NULL AI - ドメイン特化型AI推論システム

目的

医療・法律など特定ドメインに特化した、高精度なAI質問応答システムを提供する。

主な機能

• ドメイン特化型推論: 医療(medical)、法律(legal)、一般(general)の3つのドメインに対応
• 多段階判定システム: Judge Alpha → Judge Beta Basic → Judge Beta Advanced の3段階評価
• 知識ベース拡張: IATH (Indexed Athens) 形式での知識タイル管理
• リアルタイムストリーミング: WebSocketによるトークンレベルのリアルタイム配信
• キャッシュ機構: 頻繁なクエリの高速化
• ユーザー認証: JWT based認証システム

---

システムアーキテクチャ

全体構成図

┌─────────────────────────────────────────────────────────┐
│                    クライアント層                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   React UI   │  │ HF Space UI  │  │  REST Client │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    API Gateway層                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │         FastAPI Server (port 8000)                │  │
│  │  - REST API Endpoints                             │  │
│  │  - WebSocket Endpoints                            │  │
│  │  - JWT Authentication Middleware                  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  サービス層                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Inference   │  │    Cache     │  │     Auth     │  │
│  │   Service    │  │   Service    │  │   Service    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  推論エンジン層                           │
│  ┌──────────────────────────────────────────────────┐  │
│  │           Inference Engine Unified                │  │
│  │                                                    │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  │  │
│  │  │Judge Alpha │→│Judge Beta  │→│Judge Beta  │  │  │
│  │  │   Lobe     │ │Basic Lobe  │ │Advanced    │  │  │
│  │  └────────────┘  └────────────┘  └────────────┘  │  │
│  │                                                    │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │        Knowledge Tile Generator            │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   データ層                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  PostgreSQL  │  │  IATH DB     │  │  Hot Cache   │  │
│  │  (Users,     │  │  (Knowledge  │  │  (Redis-like)│  │
│  │   Sessions)  │  │   Tiles)     │  │              │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   AI モデル層                             │
│  ┌──────────────────────────────────────────────────┐  │
│  │      Model Router (Hugging Face Integration)     │  │
│  │                                                    │  │
│  │  - DeepSeek-R1-Distill-Qwen-32B (医療・法律)      │  │
│  │  - Qwen2.5-7B-Instruct (一般)                     │  │
│  │  - その他カスタムモデル                            │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

データフロー

1. ユーザークエリの処理フロー

User Question
    │
    ▼
[Frontend] Send POST /api/questions or WebSocket
    │
    ▼
[API Gateway] Route to appropriate endpoint
    │
    ├─ JWT Token Validation
    │
    ▼
[InferenceService] process_question()
    │
    ├─ Check Hot Cache
    │   └─ Cache Hit? → Return cached response
    │
    ▼
[Judge Alpha Lobe] 初期判定
    │
    ├─ 質問の複雑度評価 (complexity: 0.0-1.0)
    ├─ ドメイン適合性評価 (domain_fit: 0.0-1.0)
    └─ 処理フロー決定
        │
        ▼
    ┌───────────────────────────┐
    │ complexity < 0.3?         │
    └───────────────────────────┘
        │                    │
        │Yes                 │No
        ▼                    ▼
[Judge Beta Basic]    [Judge Beta Advanced]
    │                        │
    ├─ 軽量推論             ├─ 知識ベース検索
    └─ 高速応答             ├─ コンテキスト拡張
                            └─ 高精度推論
        │
        ▼
[Model Router] モデル選択・推論実行
    │
    ├─ ドメイン特化モデル選択
    ├─ プロンプトテンプレート適用
    └─ ストリーミング生成
        │
        ▼
[Response Post-Processing]
    │
    ├─ 幻覚検出 (Hallucination Detection)
    ├─ 確信度計算 (Confidence Scoring)
    └─ メタデータ付与
        │
        ▼
[Cache Update] Hot Cache更新
    │
    ▼
[Response] クライアントへ返却

---

ディレクトリ構造

project_locate/
│
├── frontend/                          # React フロントエンド
│   ├── src/
│   │   ├── components/                # UI コンポーネント
│   │   │   ├── ChatInterface.tsx      # チャットUI
│   │   │   ├── LoginForm.tsx          # ログインフォーム
│   │   │   └── ThinkingIndicator.tsx  # 思考プロセス表示
│   │   ├── services/                  # API クライアント
│   │   │   ├── api.ts                 # REST API
│   │   │   └── websocket.ts           # WebSocket
│   │   ├── hooks/                     # Reactフック
│   │   ├── App.tsx                    # アプリケーションルート
│   │   └── index.tsx                  # エントリーポイント
│   ├── public/
│   └── package.json
│
├── backend/                           # FastAPI バックエンド
│   ├── app/
│   │   ├── api/                       # APIルート
│   │   │   ├── auth.py                # 認証エンドポイント
│   │   │   ├── questions.py           # 質問処理エンドポイント
│   │   │   └── health.py              # ヘルスチェック
│   │   ├── models/                    # データモデル
│   │   │   ├── user.py                # ユーザーモデル
│   │   │   └── session.py             # セッションモデル
│   │   ├── services/                  # ビジネスロジック
│   │   │   ├── inference_service.py   # 推論サービス
│   │   │   └── cache_service.py       # キャッシュサービス
│   │   ├── middleware/                # ミドルウェア
│   │   │   └── auth.py                # JWT認証
│   │   ├── utils/                     # ユーティリティ
│   │   │   ├── password_hash.py       # パスワードハッシュ化
│   │   │   └── jwt_handler.py         # JWT処理
│   │   └── main.py                    # FastAPIアプリケーション
│   └── requirements.txt
│
├── null_ai/                           # 推論エンジンコア
│   ├── inference_engine_unified.py    # 統合推論エンジン
│   ├── judge_alpha_lobe.py            # Judge Alpha (初期判定)
│   ├── judge_beta_lobe_basic.py       # Judge Beta Basic (軽量推論)
│   ├── judge_beta_lobe_advanced.py    # Judge Beta Advanced (高精度推論)
│   ├── knowledge_tile_generator.py    # 知識タイル生成
│   ├── hallucination_detector.py      # 幻覚検出
│   ├── model_router.py                # モデル選択・ルーティング
│   ├── iath_encoder.py                # IATH エンコーダー
│   ├── iath_decoder.py                # IATH デコーダー
│   ├── hot_cache.py                   # ホットキャッシュ
│   └── db_manager.py                  # データベース管理
│
├── ilm_athens_engine/                 # IATH システム
│   ├── layer1_spatial_encoding.py     # 空間エンコーディング
│   ├── layer2_episodic_binding.py     # エピソード結合
│   └── layer5_state_management.py     # 状態管理
│
├── documentation/                     # ドキュメント
│   ├── API_REFERENCE.md               # API仕様書
│   ├── ARCHITECTURE.md                # アーキテクチャ設計
│   └── DEPLOYMENT.md                  # デプロイ手順
│
├── docker-compose.yml                 # Docker構成
├── start_null_ai.sh                   # 起動スクリプト
├── requirements.txt                   # Pythonパッケージ
└── README.md                          # プロジェクト概要

---

技術スタック

フロントエンド

技術	バージョン	用途
React	18.x	UIフレームワーク
TypeScript	5.x	型安全性
Vite	4.x	ビルドツール
Axios	1.x	HTTP クライアント
WebSocket API	-	リアルタイム通信
Tailwind CSS	3.x	スタイリング

バックエンド

技術	バージョン	用途
FastAPI	0.104+	Web フレームワーク
Python	3.10+	プログラミング言語
Uvicorn	0.24+	ASGI サーバー
PostgreSQL	14+	リレーショナルDB
SQLAlchemy	2.x	ORM
Pydantic	2.x	データバリデーション
JWT	-	認証トークン
Passlib	1.7+	パスワードハッシュ化

AI/ML

技術	バージョン	用途
Transformers	4.36+	HuggingFace モデル
PyTorch	2.1+	深層学習フレームワーク
DeepSeek-R1	32B distill	医療・法律推論
Qwen2.5	7B	一般推論
Accelerate	0.25+	分散処理
CUDA	11.8+	GPU アクセラレーション

インフラ

技術	用途
Docker	コンテナ化
HuggingFace Spaces	デモデプロイ
Nginx	リバースプロキシ
Git	バージョン管理

---

データベース設計

PostgreSQL スキーマ

users テーブル

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(100) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);

sessions テーブル

CREATE TABLE sessions (
    id SERIAL PRIMARY KEY,
    session_id VARCHAR(255) UNIQUE NOT NULL,
    user_id INTEGER REFERENCES users(id),
    domain_id VARCHAR(50) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    metadata JSONB
);

CREATE INDEX idx_sessions_user_id ON sessions(user_id);
CREATE INDEX idx_sessions_session_id ON sessions(session_id);

conversation_history テーブル

CREATE TABLE conversation_history (
    id SERIAL PRIMARY KEY,
    session_id VARCHAR(255) REFERENCES sessions(session_id),
    question TEXT NOT NULL,
    response TEXT NOT NULL,
    confidence FLOAT,
    model_used VARCHAR(255),
    thinking_process JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_conv_history_session_id ON conversation_history(session_id);

IATH データベース構造

IATH (Indexed Athens) データベースは独自のバイナリ形式で保存されます。

ilm_athens_medical_db.iath
├── Header Section
│   ├── Version: 1.0
│   ├── Domain: medical
│   └── Tile Count: N
│
├── Tile Index
│   └── [tile_id → offset mapping]
│
└── Tile Data Sections
    └── Each Tile:
        ├── tile_id (UUID)
        ├── topic (string)
        ├── coordinates (3D vector)
        ├── content (text)
        ├── metadata (JSON)
        └── timestamp

---

API仕様

ベースURL

http://localhost:8000/api

認証

POST /auth/register

新規ユーザー登録

リクエスト

{
  "email": "user@example.com",
  "username": "username",
  "password": "secure_password"
}

レスポンス

{
  "id": 1,
  "email": "user@example.com",
  "username": "username",
  "created_at": "2025-01-01T00:00:00Z"
}

POST /auth/login

ログイン

リクエスト

{
  "username": "username",
  "password": "secure_password"
}

レスポンス

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "username",
    "email": "user@example.com"
  }
}

質問処理

POST /questions/

質問を送信（非ストリーミング）

リクエスト

{
  "question": "心筋梗塞の初期症状は？",
  "session_id": "sess_123",
  "domain_id": "medical",
  "model_id": "deepseek-r1-32b",
  "stream": false
}

レスポンス

{
  "session_id": "sess_123",
  "question": "心筋梗塞の初期症状は？",
  "response": "心筋梗塞の初期症状には...",
  "status": "success",
  "confidence": 0.92,
  "memory_augmented": true,
  "thinking": "Judge Alpha: complexity=0.7, Judge Beta Advanced selected...",
  "model_used": "deepseek-r1-32b"
}

WebSocket /questions/ws/{session_id}

リアルタイムストリーミング

接続

const ws = new WebSocket('ws://localhost:8000/api/questions/ws/sess_123');

送信メッセージ

{
  "type": "question",
  "question": "糖尿病の予防方法は？",
  "domain_id": "medical",
  "model_id": "deepseek-r1-32b",
  "stream": true
}

受信メッセージ (ストリーミング)

// 接続確認
{"type": "connected", "session_id": "sess_123", "message": "WebSocket connected"}

// 処理開始
{"type": "processing", "message": "Processing your question..."}

// 思考プロセス
{"type": "thinking", "step": "Judge Alpha evaluating..."}

// トークンストリーム
{"type": "token", "content": "糖尿病"}
{"type": "token", "content": "の"}
{"type": "token", "content": "予防"}
...

// 完了
{
  "type": "response",
  "session_id": "sess_123",
  "question": "糖尿病の予防方法は？",
  "response": "糖尿病の予防には...",
  "status": "success"
}

GET /health

ヘルスチェック

レスポンス

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-01T00:00:00Z"
}

---

フロントエンド構成

コンポーネント階層

App
├── AuthProvider
│   ├── LoginForm
│   └── RegisterForm
│
├── ChatInterface
│   ├── MessageList
│   │   ├── UserMessage
│   │   └── AIMessage
│   │       └── ThinkingIndicator
│   ├── InputArea
│   └── DomainSelector
│
└── SettingsPanel
    ├── ModelSelector
    └── ThemeToggle

主要コンポーネント

ChatInterface.tsx

interface ChatInterfaceProps {
  sessionId: string;
  domain: 'medical' | 'legal' | 'general';
}

const ChatInterface: React.FC<ChatInterfaceProps> = ({ sessionId, domain }) => {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isThinking, setIsThinking] = useState(false);
  const ws = useRef<WebSocket | null>(null);

  useEffect(() => {
    // WebSocket接続
    ws.current = new WebSocket(`ws://localhost:8000/api/questions/ws/${sessionId}`);

    ws.current.onmessage = (event) => {
      const data = JSON.parse(event.data);
      handleWebSocketMessage(data);
    };

    return () => ws.current?.close();
  }, [sessionId]);

  const sendQuestion = (question: string) => {
    ws.current?.send(JSON.stringify({
      type: 'question',
      question,
      domain_id: domain,
      stream: true
    }));
  };

  // ...
};

状態管理

Redux/Context API を使用した状態管理:

interface AppState {
  auth: {
    user: User | null;
    token: string | null;
    isAuthenticated: boolean;
  };
  chat: {
    sessions: Record<string, Session>;
    currentSessionId: string | null;
    messages: Message[];
  };
  settings: {
    domain: DomainType;
    model: string;
    theme: 'light' | 'dark';
  };
}

---

バックエンド構成

FastAPI アプリケーション構造

backend/app/main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from backend.app.api import auth, questions, health
from backend.app.middleware.auth import JWTMiddleware

app = FastAPI(
    title="NULL AI API",
    version="1.0.0",
    description="Domain-specific AI inference system"
)

# CORS設定
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# ルート登録
app.include_router(auth.router, prefix="/api/auth", tags=["auth"])
app.include_router(questions.router, prefix="/api/questions", tags=["questions"])
app.include_router(health.router, prefix="/api", tags=["health"])

@app.on_event("startup")
async def startup_event():
    """アプリケーション起動時の初期化"""
    # データベース接続
    # キャッシュ初期化
    # モデルプリロード
    pass

@app.on_event("shutdown")
async def shutdown_event():
    """アプリケーション終了時のクリーンアップ"""
    pass

依存性注入

from typing import Generator
from fastapi import Depends
from sqlalchemy.orm import Session
from backend.app.database import SessionLocal

def get_db() -> Generator:
    """データベースセッション取得"""
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db)
) -> User:
    """現在のユーザー取得"""
    payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    user_id = payload.get("sub")
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=401, detail="Invalid token")
    return user

---

推論エンジン

Judge Alpha Lobe (初期判定)

役割: 質問の複雑度とドメイン適合性を評価し、適切な処理フローを決定

実装: null_ai/judge_alpha_lobe.py

class JudgeAlphaLobe:
    def evaluate(self, question: str, domain: str) -> dict:
        """
        質問を評価し、処理フローを決定

        Returns:
            {
                "complexity": float (0.0-1.0),
                "domain_fit": float (0.0-1.0),
                "recommended_judge": "beta_basic" | "beta_advanced",
                "reasoning": str
            }
        """
        # 質問の長さ、専門用語密度、構造複雑度を分析
        complexity = self._calculate_complexity(question)
        domain_fit = self._evaluate_domain_fit(question, domain)

        if complexity < 0.3:
            recommended_judge = "beta_basic"
        else:
            recommended_judge = "beta_advanced"

        return {
            "complexity": complexity,
            "domain_fit": domain_fit,
            "recommended_judge": recommended_judge,
            "reasoning": self._generate_reasoning(complexity, domain_fit)
        }

Judge Beta Basic (軽量推論)

役割: 低複雑度の質問に対して高速に応答

特徴:

• 知識ベース検索なし
• 小型モデル使用 (Qwen2.5-7B)
• 低レイテンシ (<2秒)

Judge Beta Advanced (高精度推論)

役割: 高複雑度の質問に対して知識ベース拡張した高精度応答

特徴:

• IATH知識ベース検索
• 大型モデル使用 (DeepSeek-R1-32B)
• コンテキスト拡張 (最大4096トークン)
• 幻覚検出機構

実装フロー:

class JudgeBetaAdvanced:
    async def process(self, question: str, domain: str, context: dict) -> dict:
        # 1. 知識ベース検索
        relevant_tiles = await self.search_knowledge_base(question, domain)

        # 2. コンテキスト構築
        augmented_context = self.build_context(question, relevant_tiles, context)

        # 3. プロンプト生成
        prompt = self.generate_prompt(question, augmented_context, domain)

        # 4. モデル推論
        response = await self.model_router.generate(
            prompt=prompt,
            model_id=self.select_model(domain),
            max_tokens=2048,
            temperature=0.7
        )

        # 5. 幻覚検出
        is_hallucinated = self.hallucination_detector.detect(response, relevant_tiles)

        # 6. 確信度計算
        confidence = self.calculate_confidence(response, relevant_tiles)

        return {
            "answer": response,
            "confidence": confidence,
            "hallucination_detected": is_hallucinated,
            "sources": [tile.id for tile in relevant_tiles],
            "reasoning": self.extract_reasoning(response)
        }

Knowledge Tile Generator

役割: ドメイン知識を構造化されたタイル形式で生成・管理

タイル構造:

@dataclass
class KnowledgeTile:
    tile_id: str                # UUID
    topic: str                  # トピック
    coordinates: tuple[float, float, float]  # 3D空間座標
    content: str                # 知識コンテンツ
    domain: str                 # ドメイン
    confidence: float           # 確信度
    metadata: dict              # メタデータ
    created_at: datetime
    updated_at: datetime

---

開発環境セットアップ

必要環境

• OS: macOS / Linux / Windows (WSL2)
• Python: 3.10 以上
• Node.js: 18 以上
• PostgreSQL: 14 以上
• GPU: NVIDIA (CUDA 11.8+) 推奨
• メモリ: 32GB以上推奨 (DeepSeek-R1-32B使用時)

セットアップ手順

1. リポジトリクローン

git clone <repository-url>
cd project_locate

2. Python環境構築

# 仮想環境作成
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 依存関係インストール
pip install -r requirements.txt

3. データベースセットアップ

# PostgreSQL起動
brew services start postgresql  # macOS
# または
sudo systemctl start postgresql  # Linux

# データベース作成
createdb nullai_db

# マイグレーション実行
alembic upgrade head

4. 環境変数設定

.env ファイルを作成:

# データベース
DATABASE_URL=postgresql://user:password@localhost/nullai_db

# JWT認証
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# HuggingFace
HF_TOKEN=your-huggingface-token

# モデル設定
DEFAULT_MODEL=deepseek-r1-32b
MODEL_CACHE_DIR=./model_cache

5. フロントエンドセットアップ

cd frontend
npm install

6. 起動

バックエンド起動

./start_null_ai.sh backend
# または
cd backend && uvicorn app.main:app --reload --port 8000

フロントエンド起動

cd frontend && npm run dev

アクセス

• フロントエンド: http://localhost:3000
• バックエンドAPI: http://localhost:8000
• API ドキュメント: http://localhost:8000/docs

---

デプロイメント

Docker デプロイ

docker-compose.yml

version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/nullai
      - SECRET_KEY=${SECRET_KEY}
    depends_on:
      - db
    volumes:
      - ./model_cache:/app/model_cache

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

  db:
    image: postgres:14
    environment:
      - POSTGRES_DB=nullai
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

デプロイコマンド

# ビルド
docker-compose build

# 起動
docker-compose up -d

# ログ確認
docker-compose logs -f

# 停止
docker-compose down

HuggingFace Spaces デプロイ

requirements.txt (Space用)

gradio==4.44.0
huggingface_hub==0.19.4
transformers==4.36.0
torch==2.1.0
accelerate==0.25.0

app.py (Space用)

import gradio as gr
from null_ai.inference_engine_unified import InferenceEngine

engine = InferenceEngine()

def chat(message, history, domain):
    response = engine.process_question(
        question=message,
        domain_id=domain,
        user_id="space_user"
    )
    return response["answer"]

iface = gr.ChatInterface(
    fn=chat,
    additional_inputs=[
        gr.Dropdown(["medical", "legal", "general"], label="Domain")
    ],
    title="NULL AI - Domain-Specific AI Assistant"
)

iface.launch()

アップロード

huggingface-cli upload kofdai/null-ai . --repo-type space

---

トラブルシューティング

1. Port Already in Use (ポート競合)

症状: Address already in use エラー

解決方法:

# ポート8000を使用しているプロセスを確認
lsof -i :8000

# プロセスを終了
kill -9 <PID>

# または停止スクリプト使用
./start_null_ai.sh stop

2. Model Loading Error (モデル読み込みエラー)

症状: OutOfMemoryError または Model not found

解決方法:

# 1. メモリ不足の場合: 軽量モデルに切り替え
export DEFAULT_MODEL=qwen2-7b

# 2. モデルキャッシュクリア
rm -rf ~/.cache/huggingface/

# 3. モデル再ダウンロード
python -c "from transformers import AutoModelForCausalLM; AutoModelForCausalLM.from_pretrained('deepseek-ai/DeepSeek-R1-Distill-Qwen-32B')"

3. Database Connection Error

症状: Connection refused または Database does not exist

解決方法:

# PostgreSQL起動確認
brew services list  # macOS
systemctl status postgresql  # Linux

# データベース存在確認
psql -l

# データベース作成
createdb nullai_db

# マイグレーション実行
alembic upgrade head

4. bcrypt Password Hashing Error

症状: Password too long エラー

解決方法: パスワードは自動的に72バイトに切り詰められます。backend/app/utils/password_hash.py 参照。

5. WebSocket Connection Failed

症状: WebSocket接続が確立できない

解決方法:

# CORS設定確認
# backend/app/main.py の CORSMiddleware 設定を確認

# WebSocketサポート確認
pip install websockets

# ファイアウォール確認
sudo ufw allow 8000  # Linux

6. HuggingFace Space Error

症状: ImportError: cannot import name 'HfFolder'

解決方法:

# requirements.txtに正しいバージョンを指定
echo "huggingface_hub==0.19.4" > requirements.txt
huggingface-cli upload kofdai/null-ai requirements.txt --repo-type space

---

開発ガイドライン

コーディング規約

Python (PEP 8準拠)

# 良い例
def process_question(question: str, domain: str) -> dict:
    """
    質問を処理し、応答を生成する

    Args:
        question: ユーザーの質問
        domain: ドメインID (medical/legal/general)

    Returns:
        応答辞書 {answer, confidence, sources}
    """
    pass

# 悪い例
def pq(q, d):  # 不明瞭な変数名
    pass

TypeScript

// 良い例
interface Question {
  id: string;
  content: string;
  domain: DomainType;
  timestamp: Date;
}

// 悪い例
let q: any;  // any型の乱用

Git コミットメッセージ

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: 新機能
• fix: バグ修正
• docs: ドキュメント
• style: コードスタイル
• refactor: リファクタリング
• test: テスト
• chore: ビルド・ツール

例:

feat(inference): Add hallucination detection

Implement hallucination detection mechanism in Judge Beta Advanced
using cosine similarity between generated response and source knowledge tiles.

Closes #123

テスト

バックエンドテスト

# ユニットテスト
pytest tests/unit/

# 統合テスト
pytest tests/integration/

# カバレッジ
pytest --cov=backend tests/

フロントエンドテスト

# ユニットテスト
npm test

# E2Eテスト
npm run test:e2e

---

パフォーマンス最適化

1. モデル最適化

• 量子化: 4-bit/8-bit量子化でメモリ削減
• Flash Attention: 高速アテンション計算
• Model Pruning: 不要なレイヤー削減

2. キャッシング戦略

# Hot Cache: 頻繁なクエリをメモリキャッシュ
cache.set(query_hash, response, ttl=3600)

# Cold Cache: 長期保存はDB
db.save_to_cache(query, response)

3. データベースインデックス

-- 頻繁に検索されるカラムにインデックス
CREATE INDEX idx_sessions_user_id ON sessions(user_id);
CREATE INDEX idx_conv_history_created_at ON conversation_history(created_at DESC);

---

セキュリティ

1. 認証・認可

• JWT: トークンベース認証
• bcrypt: パスワードハッシュ化 (salt rounds: 12)
• HTTPS: 本番環境では必須

2. 入力検証

from pydantic import BaseModel, validator

class QuestionRequest(BaseModel):
    question: str
    domain_id: str

    @validator('question')
    def validate_question(cls, v):
        if len(v) > 1000:
            raise ValueError('Question too long')
        return v

3. レート制限

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@app.post("/api/questions/")
@limiter.limit("10/minute")
async def submit_question(request: Request):
    pass

---

監視・ログ

ログ設定

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('nullai.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)
logger.info("Inference started", extra={"session_id": session_id})

メトリクス収集

• Prometheus: メトリクス収集
• Grafana: ダッシュボード
• Sentry: エラートラッキング

---

参考リンク

• FastAPI Documentation
• React Documentation
• HuggingFace Transformers
• PostgreSQL Documentation
• DeepSeek Model Card

---

ライセンス

MIT License

---

コントリビューション

プルリクエストを歓迎します。大きな変更の場合は、まずIssueで議論してください。

---

最終更新: 2025-01-26 バージョン: 1.0.0 メンテナ: NULL AI Team