| # 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<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 を使用した状態管理: | |
| ```typescript | |
| 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 | |
| ```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 <repository-url> | |
| 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 <PID> | |
| # または停止スクリプト使用 | |
| ./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 コミットメッセージ | |
| ``` | |
| <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 | |
| ``` | |
| ### テスト | |
| #### バックエンドテスト | |
| ```bash | |
| # ユニットテスト | |
| pytest tests/unit/ | |
| # 統合テスト | |
| pytest tests/integration/ | |
| # カバレッジ | |
| pytest --cov=backend tests/ | |
| ``` | |
| #### フロントエンドテスト | |
| ```bash | |
| # ユニットテスト | |
| npm test | |
| # E2Eテスト | |
| npm run test:e2e | |
| ``` | |
| --- | |
| ## パフォーマンス最適化 | |
| ### 1. モデル最適化 | |
| - **量子化**: 4-bit/8-bit量子化でメモリ削減 | |
| - **Flash Attention**: 高速アテンション計算 | |
| - **Model Pruning**: 不要なレイヤー削減 | |
| ### 2. キャッシング戦略 | |
| ```python | |
| # Hot Cache: 頻繁なクエリをメモリキャッシュ | |
| cache.set(query_hash, response, ttl=3600) | |
| # Cold Cache: 長期保存はDB | |
| db.save_to_cache(query, response) | |
| ``` | |
| ### 3. データベースインデックス | |
| ```sql | |
| -- 頻繁に検索されるカラムにインデックス | |
| 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. 入力検証 | |
| ```python | |
| 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. レート制限 | |
| ```python | |
| 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 | |
| ``` | |
| --- | |
| ## 監視・ログ | |
| ### ログ設定 | |
| ```python | |
| 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](https://fastapi.tiangolo.com/) | |
| - [React Documentation](https://react.dev/) | |
| - [HuggingFace Transformers](https://huggingface.co/docs/transformers) | |
| - [PostgreSQL Documentation](https://www.postgresql.org/docs/) | |
| - [DeepSeek Model Card](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B) | |
| --- | |
| ## ライセンス | |
| MIT License | |
| --- | |
| ## コントリビューション | |
| プルリクエストを歓迎します。大きな変更の場合は、まずIssueで議論してください。 | |
| --- | |
| **最終更新**: 2025-01-26 | |
| **バージョン**: 1.0.0 | |
| **メンテナ**: NULL AI Team | |