docs/STARTUP_GUIDE.md

NullAI システム起動ガイド

概要

NullAIは、マルチドメイン対応の知識推論システムです。医療、法律、経済、プログラミングなど、複数の専門領域に対応し、ユーザーが自由にLLMモデルやドメインを追加・管理できます。

主な特徴

• ゲストアクセス: 登録不要でシステムを利用可能
• ORCID認証: 専門家はORCIDで認証し、編集内容に認証マークが付与される
• サーバーレス対応: GitHub/Supabase/JSONBinを使用した無料ストレージ
• HuggingFace対応: Transformers、Inference API、GGUF形式をサポート
• 樹木型空間記憶: DendriticMemorySpaceによる効率的な知識管理

重要: OpenAI/Anthropic/Ollama等の外部APIは利用規約上の理由から削除されました。 NullAIはHuggingFace Transformersおよびオープンソースモデルのみをサポートします。

システム要件

• Python 3.10以上
• Node.js 18以上
• GPU（推奨: CUDA対応 または Apple Silicon MPS）
• PostgreSQL（オプション、SQLiteでも動作）
• ORCID開発者アカウント（専門家認証機能使用時）

クイックスタート

1. 環境構築

# リポジトリのクローン（または既存ディレクトリへ移動）
cd project_locate

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

# Python依存パッケージのインストール
pip install -r requirements.txt

# フロントエンド依存パッケージのインストール
cd frontend
npm install
cd ..

2. HuggingFace Transformersのセットアップ

# 必要なPythonパッケージのインストール
pip install transformers torch accelerate

# GPU確認
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')"

# モデルの事前ダウンロード（オプション - 初回実行時に自動ダウンロードされる）
python -c "from transformers import AutoModelForCausalLM, AutoTokenizer; AutoTokenizer.from_pretrained('deepseek-ai/DeepSeek-R1-Distill-Qwen-7B')"

# GGUF形式を使用する場合（CPU環境向け）
pip install llama-cpp-python

3. 環境変数の設定

# .envファイルを作成
cat > .env << 'EOF'
# API設定
SECRET_KEY=your-secret-key-here-change-in-production
DEBUG=true
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# データベース
DATABASE_URL=sqlite:///./sql_app.db

# HuggingFace設定（オプション - Inference APIを使用する場合）
# HF_API_KEY=hf_xxx

# ========================================
# 以下のAPIは利用規約上の理由からサポートされていません:
# - OPENAI_API_KEY (OpenAI)
# - ANTHROPIC_API_KEY (Anthropic)
# - OLLAMA_URL (Ollama)
# HuggingFace Transformersを使用してください。
# ========================================

# ORCID認証（専門家認証機能使用時）
# ORCID_CLIENT_ID=APP-XXXXXXXXX
# ORCID_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# ORCID_REDIRECT_URI=http://localhost:8000/api/auth/orcid/callback
# ORCID_SANDBOX=true  # 開発時はtrue、本番はfalse

# サーバーレスストレージ設定（オプション）
# OPAQUE_STORAGE_BACKEND=local  # local, github, supabase, jsonbin

# GitHub Storage
# GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# GITHUB_REPO=username/opaque-data
# GITHUB_BRANCH=main
# GITHUB_DATA_PATH=data

# Supabase Storage
# SUPABASE_URL=https://xxxxx.supabase.co
# SUPABASE_ANON_KEY=eyJxxxxxxxx

# JSONBin Storage
# JSONBIN_API_KEY=$2b$xxxxxxxx
# JSONBIN_BIN_ID=xxxxxxxxxxxxxxxx
EOF

4. データベース初期化

# データベーステーブルの作成
python backend/create_db.py

5. システムの起動

方法A: 個別起動（開発時推奨）

# ターミナル1: バックエンドAPIサーバー
cd project_locate
source venv/bin/activate
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

# ターミナル2: フロントエンド開発サーバー
cd project_locate/frontend
npm run dev

方法B: Docker Compose（本番環境推奨）

# Docker Composeで全サービスを起動
docker-compose up -d

# ログの確認
docker-compose logs -f

6. アクセス

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

初期設定

ユーザー登録

1. http://localhost:5173 にアクセス
2. 「Sign up」をクリック
3. メールアドレスとパスワードを入力して登録

管理者権限の付与

# SQLiteの場合
sqlite3 sql_app.db "UPDATE users SET role='admin' WHERE email='your@email.com';"

# または Python スクリプトで
python -c "
from backend.app.database.session import SessionLocal
from backend.app.database.models import User
db = SessionLocal()
user = db.query(User).filter(User.email=='your@email.com').first()
user.role = 'admin'
db.commit()
print('Admin role granted')
"

DB拡充コマンド

基本的な使い方

# ヘルプを表示
python null_ai/db_enrichment_cli.py --help

# 利用可能なモデル一覧
python null_ai/db_enrichment_cli.py --list-models

# 利用可能なドメイン一覧
python null_ai/db_enrichment_cli.py --list-domains

# 生成される質問をプレビュー（実行しない）
python null_ai/db_enrichment_cli.py --domain medical --preview --count 20

DB拡充の実行

# 医療ドメインを50件の質問で拡充
python null_ai/db_enrichment_cli.py --domain medical --count 50

# 全ドメインを拡充（各30件）
python null_ai/db_enrichment_cli.py --all --count 30

# 特定のモデルを使用して拡充
python null_ai/db_enrichment_cli.py --domain legal --model deepseek-r1-32b --count 20

# バッチサイズを指定（レート制限対策）
python null_ai/db_enrichment_cli.py --domain economics --count 100 --batch-size 3

Web検索による拡充

Web検索を使用して最新情報を収集し、DBを拡充できます：

# Web検索で最新情報を収集（DuckDuckGo、無料・キー不要）
python null_ai/db_enrichment_cli.py --domain medical --web-search --count 10

# 特定のクエリでWeb検索
python null_ai/db_enrichment_cli.py --domain medical --web-search --query "最新の糖尿病治療法 2024"

# クエリファイルから検索
python null_ai/db_enrichment_cli.py --domain legal --web-search --queries-file legal_queries.txt

# 利用可能な検索プロバイダーを確認
python null_ai/db_enrichment_cli.py --list-search-providers

追加の検索プロバイダー（オプション）

より高品質な検索結果を得るには、以下の無料APIを設定できます：

# Brave Search API（無料2,000クエリ/月）
# https://brave.com/search/api/ で取得
BRAVE_API_KEY=your-brave-api-key

# Tavily AI Search（AI最適化検索）
# https://tavily.com/ で取得
TAVILY_API_KEY=your-tavily-api-key

拡充結果

結果は enrichment_output/ ディレクトリにJSON形式で保存されます：

enrichment_output/
├── enrichment_medical_20241124_120000.json
├── enrichment_legal_20241124_121500.json
├── web_enrichment_medical_20241124_130000.json  # Web検索結果
└── ...

モデル管理

Web UIでのモデル追加

1. 管理者としてログイン
2. 「Settings」→「Models」に移動
3. 「Add Model」をクリック
4. 必要な情報を入力:
   • Model ID: 一意の識別子（例: custom-medical-llm）
   • Display Name: 表示名
   • Provider: huggingface, huggingface_api, local, gguf
   • Model Name: HuggingFaceモデルID（例: deepseek-ai/DeepSeek-R1-Distill-Qwen-7B）
   • Supported Domains: 対応ドメイン

サポートされていないプロバイダー: openai, anthropic, ollama は利用規約上の理由から削除されました。

APIでのモデル追加

# HuggingFaceモデルを追加
curl -X POST http://localhost:8000/api/models/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "qwen2-72b",
    "display_name": "Qwen2.5 72B",
    "provider": "huggingface",
    "model_name": "Qwen/Qwen2.5-72B-Instruct",
    "supported_domains": ["medical", "legal", "general"],
    "description": "高性能多言語モデル"
  }'

# モデル接続テスト
curl -X POST http://localhost:8000/api/models/qwen2-72b/test \
  -H "Authorization: Bearer YOUR_TOKEN"

# サポートされているプロバイダー情報を取得
curl http://localhost:8000/api/models/providers/info

ドメイン管理

新しいドメインの追加

1. Web UIの「Domains」タブで追加
2. または domains_config.json を直接編集:

{
  "domains": [
    {
      "domain_id": "philosophy",
      "name": "Philosophy",
      "description": "哲学・思想に関する知識領域",
      "default_model_id": "deepseek-r1-32b",
      "icon": "philosophy",
      "is_active": true
    }
  ]
}

ドメイン固有の質問テンプレート追加

null_ai/db_enrichment_cli.py の DOMAIN_QUESTION_TEMPLATES に追加:

"philosophy": {
    "categories": [
        {
            "name": "哲学者",
            "questions": [
                "{philosopher}の主要な思想は何ですか？",
                "{philosopher}の代表的な著作について教えてください。",
            ]
        }
    ],
    "topics": {
        "philosopher": ["プラトン", "アリストテレス", "カント", "ニーチェ"]
    }
}

ORCID認証の設定

1. ORCID開発者アカウントの作成

1. https://orcid.org/developer-tools にアクセス
2. 「Register for the free ORCID public API」をクリック
3. アプリケーション情報を入力:
   • Application Name: NullAI
   • Website URL: http://localhost:5173 (開発時)
   • Redirect URIs: http://localhost:8000/api/auth/orcid/callback
4. Client IDとClient Secretを取得

2. 開発用サンドボックス

開発時はORCIDサンドボックス環境を使用できます:

• サンドボックス: https://sandbox.orcid.org
• .envでORCID_SANDBOX=trueを設定

3. 本番環境

本番環境では:

• 本番用ORCID認証情報を取得
• .envでORCID_SANDBOX=falseを設定
• Redirect URIを本番URLに更新

ユーザーロールとアクセスレベル

ロール	説明	権限
guest	未登録ユーザー	閲覧、質問
viewer	登録ユーザー	+ 提案の閲覧
editor	編集者	+ 提案の作成・レビュー
expert	ORCID認証済み専門家	+ 認証マーク付き編集
admin	管理者	+ 全管理機能

認証マークの種類

• none: 未検証
• community: コミュニティレビュー済み
• expert: ORCID認証専門家による編集/レビュー
• multi_expert: 複数の専門家による検証

サーバーレスストレージ設定

GitHub Storage（推奨）

GitHubリポジトリをデータベースとして使用:

1. データ保存用リポジトリを作成
2. Personal Access Token (PAT)を生成:
   • Settings > Developer settings > Personal access tokens
   • repoスコープを付与
3. 環境変数を設定:

OPAQUE_STORAGE_BACKEND=github
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_REPO=username/opaque-data
GITHUB_BRANCH=main
GITHUB_DATA_PATH=data

Supabase Storage

Supabase無料プラン（500MB、50,000リクエスト/月）:

1. https://supabase.com でプロジェクト作成
2. テーブルを作成:

CREATE TABLE domains (id text primary key, data jsonb);
CREATE TABLE proposals (id text primary key, data jsonb);
CREATE TABLE tiles (id text primary key, data jsonb);

3. 環境変数を設定:

OPAQUE_STORAGE_BACKEND=supabase
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJxxxxxxxx

JSONBin Storage

シンプルなJSONストレージ（10,000リクエスト/月無料）:

1. https://jsonbin.io でアカウント作成
2. 新しいBinを作成（初期データ: {"collections": {}}）
3. 環境変数を設定:

OPAQUE_STORAGE_BACKEND=jsonbin
JSONBIN_API_KEY=$2b$xxxxxxxx
JSONBIN_BIN_ID=xxxxxxxxxxxxxxxx

ストレージ比較

バックエンド	無料枠	特徴
Local	無制限	ローカル開発用
GitHub	無制限*	バージョン管理、透明性
Supabase	500MB	SQLクエリ、リアルタイム
JSONBin	10K/月	シンプル、セットアップ簡単

*プライベートリポジトリは制限あり

トラブルシューティング

HuggingFace Transformersの確認

# Transformersが正しくインストールされているか確認
python -c "from transformers import AutoModel; print('OK')"

# GPUが利用可能か確認
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')"

モデルのダウンロードが遅い

# キャッシュディレクトリを確認
python -c "from transformers import TRANSFORMERS_CACHE; print(TRANSFORMERS_CACHE)"

# 軽量モデルを使用（7Bモデル）
# config.pyでデフォルトモデルを deepseek-r1-7b に変更

メモリ不足エラー

# 32Bモデルには32GB以上のVRAM/RAMが推奨
# メモリが足りない場合:
# 1. 7Bモデルを使用 (models_config.json でデフォルト変更)
# 2. 4bit量子化を有効化 (config.pyで use_4bit_quantization: true)
# 3. GGUF形式の量子化モデルを使用

データベースエラー

# データベースをリセット
rm sql_app.db
python backend/create_db.py

API エンドポイント一覧

エンドポイント	メソッド	説明
/api/auth/signup	POST	ユーザー登録
/api/auth/token	POST	ログイン（トークン取得）
/api/questions/	POST	質問を送信
/api/questions/ws/{session_id}	WS	ストリーミング回答
/api/domains/	GET	ドメイン一覧
/api/domains/{id}	GET/PUT/DELETE	ドメイン操作
/api/models/	GET/POST	モデル一覧/追加
/api/models/{id}	GET/PUT/DELETE	モデル操作
/api/models/{id}/test	POST	モデル接続テスト
/api/proposals/	GET/POST	編集提案一覧/作成
/api/proposals/{id}/review	PUT	提案レビュー
/health	GET	ヘルスチェック

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                     NullAI System                         │
├─────────────────────────────────────────────────────────────┤
│  Frontend (React + TypeScript)                              │
│  ├── Authentication UI                                      │
│  ├── Chat Interface (REST/WebSocket)                       │
│  ├── Domain Editor                                          │
│  └── Model Management                                       │
├─────────────────────────────────────────────────────────────┤
│  Backend (FastAPI)                                          │
│  ├── Auth API (JWT)                                         │
│  ├── Questions API                                          │
│  ├── Domains API                                            │
│  ├── Models API                                             │
│  └── Proposals API                                          │
├─────────────────────────────────────────────────────────────┤
│  NullAI Core                                              │
│  ├── ModelRouter (Multi-LLM Support)                        │
│  ├── ConfigManager                                          │
│  ├── DendriticMemorySpace (Tree-like Memory)               │
│  └── DB Enrichment CLI                                      │
├─────────────────────────────────────────────────────────────┤
│  Inference Engine                                           │
│  ├── IlmAthensEngine (Orchestrator)                        │
│  ├── SpatialEncodingEngine (Coordinate Mapping)            │
│  ├── Judge Layer (Alpha + Beta Lobe)                       │
│  └── NurseLogSystem (Continuous Learning)                  │
├─────────────────────────────────────────────────────────────┤
│  Data Layer                                                 │
│  ├── IathDB (Compressed Knowledge Tiles)                   │
│  ├── SQLite/PostgreSQL (User Data)                         │
│  └── JSON Config Files                                      │
├─────────────────────────────────────────────────────────────┤
│  LLM Providers                                              │
│  ├── Ollama (Local)                                         │
│  ├── OpenAI API                                             │
│  ├── Anthropic API                                          │
│  └── Custom Endpoints                                       │
└─────────────────────────────────────────────────────────────┘

ライセンス

MIT License