# NULL AI プロジェクト - 開発者向け技術ガイド ## 📋 目次 1. [プロジェクト概要](#プロジェクト概要) 2. [システムアーキテクチャ](#システムアーキテクチャ) 3. [ディレクトリ構造](#ディレクトリ構造) 4. [技術スタック](#技術スタック) 5. [データベース設計](#データベース設計) 6. [API仕様](#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 テーブル ```sql 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 テーブル ```sql 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 テーブル ```sql 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 新規ユーザー登録 **リクエスト** ```json { "email": "user@example.com", "username": "username", "password": "secure_password" } ``` **レスポンス** ```json { "id": 1, "email": "user@example.com", "username": "username", "created_at": "2025-01-01T00:00:00Z" } ``` #### POST /auth/login ログイン **リクエスト** ```json { "username": "username", "password": "secure_password" } ``` **レスポンス** ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "user": { "id": 1, "username": "username", "email": "user@example.com" } } ``` ### 質問処理 #### POST /questions/ 質問を送信（非ストリーミング） **リクエスト** ```json { "question": "心筋梗塞の初期症状は？", "session_id": "sess_123", "domain_id": "medical", "model_id": "deepseek-r1-32b", "stream": false } ``` **レスポンス** ```json { "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} リアルタイムストリーミング **接続** ```javascript const ws = new WebSocket('ws://localhost:8000/api/questions/ws/sess_123'); ``` **送信メッセージ** ```json { "type": "question", "question": "糖尿病の予防方法は？", "domain_id": "medical", "model_id": "deepseek-r1-32b", "stream": true } ``` **受信メッセージ (ストリーミング)** ```json // 接続確認 {"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 ヘルスチェック **レスポンス** ```json { "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 ```typescript interface ChatInterfaceProps { sessionId: string; domain: 'medical' | 'legal' | 'general'; } const ChatInterface: React.FC = ({ sessionId, domain }) => { const [messages, setMessages] = useState([]); const [isThinking, setIsThinking] = useState(false); const ws = useRef(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 を使用した状態管理: ```typescript interface AppState { auth: { user: User | null; token: string | null; isAuthenticated: boolean; }; chat: { sessions: Record; currentSessionId: string | null; messages: Message[]; }; settings: { domain: DomainType; model: string; theme: 'light' | 'dark'; }; } ``` --- ## バックエンド構成 ### FastAPI アプリケーション構造 #### backend/app/main.py ```python 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 ``` ### 依存性注入 ```python 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` ```python 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トークン) - 幻覚検出機構 **実装フロー**: ```python 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 **役割**: ドメイン知識を構造化されたタイル形式で生成・管理 **タイル構造**: ```python @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. リポジトリクローン ```bash git clone cd project_locate ``` #### 2. Python環境構築 ```bash # 仮想環境作成 python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 依存関係インストール pip install -r requirements.txt ``` #### 3. データベースセットアップ ```bash # PostgreSQL起動 brew services start postgresql # macOS # または sudo systemctl start postgresql # Linux # データベース作成 createdb nullai_db # マイグレーション実行 alembic upgrade head ``` #### 4. 環境変数設定 `.env` ファイルを作成: ```bash # データベース 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. フロントエンドセットアップ ```bash cd frontend npm install ``` #### 6. 起動 **バックエンド起動** ```bash ./start_null_ai.sh backend # または cd backend && uvicorn app.main:app --reload --port 8000 ``` **フロントエンド起動** ```bash cd frontend && npm run dev ``` **アクセス** - フロントエンド: http://localhost:3000 - バックエンドAPI: http://localhost:8000 - API ドキュメント: http://localhost:8000/docs --- ## デプロイメント ### Docker デプロイ #### docker-compose.yml ```yaml 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: ``` #### デプロイコマンド ```bash # ビルド docker-compose build # 起動 docker-compose up -d # ログ確認 docker-compose logs -f # 停止 docker-compose down ``` ### HuggingFace Spaces デプロイ #### requirements.txt (Space用) ```txt gradio==4.44.0 huggingface_hub==0.19.4 transformers==4.36.0 torch==2.1.0 accelerate==0.25.0 ``` #### app.py (Space用) ```python 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() ``` #### アップロード ```bash huggingface-cli upload kofdai/null-ai . --repo-type space ``` --- ## トラブルシューティング ### 1. Port Already in Use (ポート競合) **症状**: `Address already in use` エラー **解決方法**: ```bash # ポート8000を使用しているプロセスを確認 lsof -i :8000 # プロセスを終了 kill -9 # または停止スクリプト使用 ./start_null_ai.sh stop ``` ### 2. Model Loading Error (モデル読み込みエラー) **症状**: `OutOfMemoryError` または `Model not found` **解決方法**: ```bash # 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` **解決方法**: ```bash # 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接続が確立できない **解決方法**: ```bash # CORS設定確認 # backend/app/main.py の CORSMiddleware 設定を確認 # WebSocketサポート確認 pip install websockets # ファイアウォール確認 sudo ufw allow 8000 # Linux ``` ### 6. HuggingFace Space Error **症状**: `ImportError: cannot import name 'HfFolder'` **解決方法**: ```bash # requirements.txtに正しいバージョンを指定 echo "huggingface_hub==0.19.4" > requirements.txt huggingface-cli upload kofdai/null-ai requirements.txt --repo-type space ``` --- ## 開発ガイドライン ### コーディング規約 #### Python (PEP 8準拠) ```python # 良い例 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 ```typescript // 良い例 interface Question { id: string; content: string; domain: DomainType; timestamp: Date; } // 悪い例 let q: any; // any型の乱用 ``` ### Git コミットメッセージ ``` ():