Add SPACES_DEPLOYMENT_GUIDE.md for HuggingFace Spaces deployment

SPACES_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,560 @@
+# HuggingFace Spacesへのデプロイガイド
+
+このガイドでは、NullAI Phi-4 14B プロジェクトをHuggingFace Spacesにデプロイする方法を説明します。
+
+## 目次
+
+1. [デプロイ方法の選択](#デプロイ方法の選択)
+2. [方法1: Docker Space (推奨)](#方法1-docker-space-推奨)
+3. [方法2: Gradio Space](#方法2-gradio-space)
+4. [トラブルシューティング](#トラブルシューティング)
+
+---
+
+## デプロイ方法の選択
+
+### 方法1: Docker Space (推奨)
+- ✅ フルスタックアプリケーション（FastAPI + React）
+- ✅ 完全なカスタマイズ可能
+- ✅ 本番環境に最適
+- ⚠️ より多くのリソースが必要
+
+### 方法2: Gradio Space
+- ✅ セットアップが簡単
+- ✅ 軽量
+- ✅ プロトタイプに最適
+- ⚠️ UIのカスタマイズが制限される
+
+---
+
+## 方法1: Docker Space (推奨)
+
+### ステップ1: Dockerfileの作成
+
+プロジェクトルートに`Dockerfile`を作成します:
+
+```dockerfile
+# Multi-stage build for optimized image size
+FROM node:18-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+
+# Copy frontend files
+COPY frontend/package*.json ./
+RUN npm ci
+
+COPY frontend/ ./
+RUN npm run build
+
+# Python backend stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy backend files
+COPY backend/requirements.txt ./backend/
+RUN pip install --no-cache-dir -r backend/requirements.txt
+
+# Copy backend code
+COPY backend/ ./backend/
+
+# Copy frontend build
+COPY --from=frontend-builder /app/frontend/dist ./frontend/dist
+
+# Copy configuration files
+COPY models_config.json domains_config.json null_ai_config.json ./
+COPY db_manager.py inference_engine_unified.py runner_engine.py ./
+
+# Create database directory
+RUN mkdir -p /app/data
+
+# Set environment variables
+ENV DATABASE_URL=sqlite:////app/data/sql_app.db
+ENV PYTHONPATH=/app
+ENV HOST=0.0.0.0
+ENV PORT=7860
+
+# Expose port (HuggingFace Spaces uses 7860)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:7860/api/system/health')"
+
+# Run the application
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### ステップ2: README.mdの更新
+
+HuggingFace Spaces用の設定をREADME.mdのヘッダーに追加します:
+
+```yaml
+---
+title: NullAI Phi-4 14B Knowledge System
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
+---
+```
+
+### ステップ3: .dockerignoreの作成
+
+```
+# Git files
+.git
+.gitignore
+.gitattributes
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Database
+*.db
+*.sqlite
+
+# Large files
+*.gguf
+*.bin
+*.pth
+phi-4-f16.gguf
+
+# Logs
+*.log
+
+# Distribution
+dist/
+build/
+```
+
+### ステップ4: Spacesへのデプロイ
+
+#### オプションA: Git経由でデプロイ
+
+```bash
+# 1. HuggingFace Spacesで新しいSpaceを作成
+# https://huggingface.co/spaces にアクセスして "Create new Space" をクリック
+# - Name: nullai-phi-4-knowledge-system
+# - SDK: Docker
+# - Hardware: CPU Basic (または GPU T4)
+
+# 2. Spaceのリポジトリをクローン
+git clone https://huggingface.co/spaces/YOUR_USERNAME/nullai-phi-4-knowledge-system
+cd nullai-phi-4-knowledge-system
+
+# 3. プロジェクトファイルをコピー
+cp -r /Users/motonishikoudai/project_locate/huggingface_repo/* .
+
+# 4. 大きなモデルファイルを除外
+rm -f phi-4-f16.gguf
+
+# 5. コミットしてプッシュ
+git add .
+git commit -m "Initial deployment to Spaces"
+git push
+```
+
+#### オプションB: HuggingFace Hub API経由でデプロイ
+
+```python
+from huggingface_hub import HfApi, create_repo
+
+api = HfApi(token="YOUR_HF_TOKEN")
+
+# Spaceを作成
+repo_id = "YOUR_USERNAME/nullai-phi-4-knowledge-system"
+create_repo(
+    repo_id=repo_id,
+    repo_type="space",
+    space_sdk="docker",
+    private=False
+)
+
+# ファイルをアップロード
+api.upload_folder(
+    folder_path="/Users/motonishikoudai/project_locate/huggingface_repo",
+    repo_id=repo_id,
+    repo_type="space",
+    ignore_patterns=["*.gguf", "*.db", "__pycache__", "node_modules"]
+)
+```
+
+### ステップ5: 環境変数の設定
+
+HuggingFace Spacesの設定画面で環境変数を設定:
+
+```bash
+DATABASE_URL=sqlite:////app/data/sql_app.db
+SECRET_KEY=your-secret-key-here
+CORS_ORIGINS=["https://YOUR_USERNAME-nullai-phi-4-knowledge-system.hf.space"]
+```
+
+### ステップ6: ハードウェアの選択
+
+推奨ハードウェア:
+- **CPU Basic** (無料): デモ・開発用
+- **CPU Upgrade**: 本番環境・多数の���ーザー
+- **GPU T4**: AIモデル推論が必要な場合
+
+---
+
+## 方法2: Gradio Space
+
+より簡単な方法として、Gradioインターフェースでラップしてデプロイすることもできます。
+
+### ステップ1: app.pyの作成
+
+```python
+import gradio as gr
+import requests
+import json
+from typing import List, Dict
+import subprocess
+import os
+import threading
+
+# バックエンドサーバーをバックグラウンドで起動
+def start_backend():
+    subprocess.Popen([
+        "uvicorn",
+        "backend.app.main:app",
+        "--host", "0.0.0.0",
+        "--port", "8000"
+    ])
+
+# バックエンドを起動
+backend_thread = threading.Thread(target=start_backend, daemon=True)
+backend_thread.start()
+
+# APIのベースURL
+API_URL = "http://localhost:8000"
+
+def list_knowledge_tiles(domain_id: str = None) -> str:
+    """知識タイルのリストを取得"""
+    params = {}
+    if domain_id:
+        params["domain_id"] = domain_id
+
+    response = requests.get(f"{API_URL}/api/knowledge/", params=params)
+
+    if response.status_code == 200:
+        data = response.json()
+        tiles = data.get("tiles", [])
+
+        result = f"### 知識タイル ({len(tiles)}件)\n\n"
+        for tile in tiles[:10]:  # 最初の10件のみ表示
+            result += f"**{tile['topic']}** ({tile['domain_id']})\n"
+            result += f"{tile['content'][:100]}...\n\n"
+
+        return result
+    else:
+        return f"エラー: {response.status_code}"
+
+def search_knowledge(query: str) -> str:
+    """知識を検索"""
+    response = requests.get(
+        f"{API_URL}/api/knowledge/",
+        params={"search": query}
+    )
+
+    if response.status_code == 200:
+        data = response.json()
+        tiles = data.get("tiles", [])
+
+        if not tiles:
+            return "検索結果が見つかりませんでした。"
+
+        result = f"### 検索結果: '{query}' ({len(tiles)}件)\n\n"
+        for tile in tiles[:5]:
+            result += f"**{tile['topic']}**\n"
+            result += f"{tile['content']}\n\n"
+            result += "---\n\n"
+
+        return result
+    else:
+        return f"エラー: {response.status_code}"
+
+def create_tile(domain_id: str, topic: str, content: str, token: str) -> str:
+    """新しい知識タイルを作成"""
+    headers = {"Authorization": f"Bearer {token}"}
+    data = {
+        "domain_id": domain_id,
+        "topic": topic,
+        "content": content
+    }
+
+    response = requests.post(
+        f"{API_URL}/api/knowledge/",
+        headers=headers,
+        json=data
+    )
+
+    if response.status_code == 201:
+        return "✅ 知識タイルを作成しました！"
+    else:
+        return f"❌ エラー: {response.text}"
+
+# Gradioインターフェース
+with gr.Blocks(title="NullAI Knowledge System", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🧠 NullAI Phi-4 14B Knowledge System")
+    gr.Markdown("Expert-verified knowledge management with 3D spatial memory")
+
+    with gr.Tabs():
+        # タブ1: 知識の閲覧
+        with gr.Tab("📚 知識の閲覧"):
+            domain_filter = gr.Dropdown(
+                choices=["", "medical", "ai_fundamentals", "logic_reasoning",
+                        "computer_science_theory", "engineering", "philosophy", "law"],
+                label="ドメインでフィルタ",
+                value=""
+            )
+            list_btn = gr.Button("知識タイルを表示")
+            list_output = gr.Markdown()
+
+            list_btn.click(
+                fn=list_knowledge_tiles,
+                inputs=[domain_filter],
+                outputs=[list_output]
+            )
+
+        # タブ2: 検索
+        with gr.Tab("🔍 検索"):
+            search_input = gr.Textbox(
+                label="検索クエリ",
+                placeholder="検索したいキーワードを入力..."
+            )
+            search_btn = gr.Button("検索")
+            search_output = gr.Markdown()
+
+            search_btn.click(
+                fn=search_knowledge,
+                inputs=[search_input],
+                outputs=[search_output]
+            )
+
+        # タブ3: 知識の追加
+        with gr.Tab("➕ 知識の追加"):
+            gr.Markdown("新しい知識タイルを作成するには、ログインが必要です。")
+
+            create_domain = gr.Dropdown(
+                choices=["medical", "ai_fundamentals", "logic_reasoning"],
+                label="ドメイン"
+            )
+            create_topic = gr.Textbox(label="トピック")
+            create_content = gr.Textbox(
+                label="内容",
+                lines=5,
+                placeholder="詳細な説明を入力..."
+            )
+            create_token = gr.Textbox(
+                label="認証トークン",
+                type="password",
+                placeholder="Bearer トークン"
+            )
+            create_btn = gr.Button("作成")
+            create_output = gr.Markdown()
+
+            create_btn.click(
+                fn=create_tile,
+                inputs=[create_domain, create_topic, create_content, create_token],
+                outputs=[create_output]
+            )
+
+    gr.Markdown("""
+    ---
+    ### 🔗 リンク
+    - [GitHub](https://github.com/Ag3497120/nullai-phi-4-14b-v2)
+    - [Model Card](https://huggingface.co/kofdai/nullai-phi-4-14b-v2)
+    - [Documentation](https://huggingface.co/kofdai/nullai-phi-4-14b-v2/blob/main/USER_GUIDE.md)
+    """)
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)
+```
+
+### ステップ2: requirements.txtの作成
+
+```txt
+gradio>=4.0.0
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+requests>=2.31.0
+sqlalchemy>=2.0.0
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+python-multipart>=0.0.6
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+```
+
+### ステップ3: README.mdの設定
+
+```yaml
+---
+title: NullAI Knowledge System
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit
+---
+```
+
+### ステップ4: デプロイ
+
+```bash
+# Spaceを作成してファイルをアップロード
+git clone https://huggingface.co/spaces/YOUR_USERNAME/nullai-knowledge-system
+cd nullai-knowledge-system
+
+# 必要なファイルをコピー
+cp app.py requirements.txt README.md ./
+cp -r backend/ ./
+
+git add .
+git commit -m "Deploy Gradio Space"
+git push
+```
+
+---
+
+## トラブルシューティング
+
+### 問題1: ビルドエラー
+
+**症状**: Docker buildが失敗する
+
+**解決方法**:
+```bash
+# ローカルでビルドをテスト
+docker build -t nullai-test .
+docker run -p 7860:7860 nullai-test
+```
+
+### 問題2: メモリ不足
+
+**症状**: "Out of memory" エラー
+
+**解決方法**:
+- より大きなハードウェアにアップグレード
+- モデルファイルを除外
+- マルチステージビルドを最適化
+
+### 問題3: 起動が遅い
+
+**症状**: アプリケーションの起動に時間がかかる
+
+**解決方法**:
+```dockerfile
+# Dockerfileに以下を追加してキャッシュを活用
+RUN pip install --no-cache-dir -r requirements.txt
+```
+
+### 問題4: データベース接続エラー
+
+**症状**: SQLite database is locked
+
+**解決方法**:
+```bash
+# 環境変数でデータベースパスを設定
+DATABASE_URL=sqlite:////app/data/sql_app.db?check_same_thread=False
+```
+
+### 問題5: CORS エラー
+
+**症状**: フロントエンドからAPIにアクセスできない
+
+**解決方法**:
+```python
+# backend/app/config.py
+CORS_ORIGINS = [
+    "https://YOUR_USERNAME-nullai-knowledge-system.hf.space",
+    "http://localhost:7860"
+]
+```
+
+---
+
+## 高度な設定
+
+### カスタムドメイン
+
+HuggingFace Spacesでカスタムドメインを設定:
+
+1. Spaceの設定画面に移動
+2. "Settings" → "Custom domain"
+3. ドメイン名を入力
+4. DNSレコードを設定
+
+### シークレットの管理
+
+機密情報（API キー、データベース認証情報など）は、Spacesのシークレット機能を使用:
+
+1. Space設定 → "Variables and secrets"
+2. シークレットを追加
+3. コードで `os.environ.get("SECRET_NAME")` を使用
+
+### 自動再起動
+
+Spacesは自動的にクラッシュを検出して再起動しますが、カスタムヘルスチェックを追加することもできます:
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy"}
+```
+
+---
+
+## まとめ
+
+どちらの方法でも、NullAI知識管理システムをHuggingFace Spacesにデプロイできます:
+
+- **Docker Space**: フルスタック、本番環境向け
+- **Gradio Space**: 簡単、プロトタイプ向け
+
+詳細については、以下を参照してください:
+- [HuggingFace Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Gradio Documentation](https://www.gradio.app/docs/)