DeepTutor 入門：Agent-Native 個別化学習アシスタントの実戦デプロイ

入門レベル | 約20分 | DeepTutor の中核アーキテクチャ、2種類のデプロイ方式（Setup Tour + Docker）、5モードのワークスペース活用、そして TutorBot の基本設定を身につけます

---

プロジェクト概要

DeepTutor は学習のための AI エージェント・プラットフォームで、その中心となる狙いは「AI を本当に学習に役立てることであり、チャットするだけではない」ことです。香港大学データインテリジェンス研究室（HKUDS）が開発し、2026年1月にオープンソース化されてから39日で10k Starを獲得、現在は GitHub 上でもっとも注目されている AI 教育テックのプロジェクトのひとつになっています。

特長はAgent-Native アーキテクチャにあります。AI をチャット画面に押し込むのではなく、「学習」という目的の周りに、協調して動けるエージェントのツールチェーン一式を設計しています。教材をアップロードすれば、学習ルートの計画、クイズの生成、記憶が弱いポイントの追跡まで行い、さらに数式をアニメーションに変えることもできます。TutorBot はさらに一段上です——それぞれのTA（助教）は独立した AI Agent で、独自の記憶と個性を持ち、復習を能動的にリマインドしてくれます。

もしあなたがローカルデプロイ可能で、機能が充実していて、拡張性が高い AI 学習アシスタントを探しているなら、DeepTutor はぜひ試す価値があります。

---

対象読者のイメージ

• 開発経験 1〜3 年のエンジニアで、AI Agent と LLM アプリケーションに興味がある
• 教育テック愛好家で、ローカルに個別化された AI 学習ツールをデプロイしたい
• 永続化する AI 助教（RAG + 記憶）を構築したいユーザー

コア依存関係と環境

• Python 3.11+、Node.js 18+
• LLM API Key（OpenAI / Anthropic / DeepSeek など）
• Embedding API Key（RAG のベクトル検索用）
• Docker（任意。Docker デプロイ時に使用）

完全なプロジェクト構成ツリー

DeepTutor/
├── deeptutor/              # コアバックエンド
│   ├── capabilities/        # 5つの能力（chat, deep_solve, deep_question など）
│   ├── tools/              # ツール層（rag, web_search, code_execution など）
│   ├── tutorbot/          # TutorBot の永続化助教
│   ├── api/                 # FastAPI サービス
│   └── runtime/             # プラグイン登録とディスパッチ
├── deeptutor_cli/         # CLI エントリ（Typer）
├── web/                   # Next.js 16 フロントエンド
├── scripts/start_tour.py  # インタラクティブな導入ガイド
└── docker-compose.yml     # Docker デプロイ

---

手順（ステップバイステップ）

ステップ1：リポジトリをクローンして Python 環境を作成

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Python の仮想環境を作成（推奨：conda）
conda create -n deeptutor python=3.11 && conda activate deeptutor
# または venv を使用
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                          # Windows

ステップ2：Setup Tour（推奨）でインタラクティブにインストール

DeepTutor はインタラクティブな導入スクリプトを用意しています。依存関係のインストール、設定項目の入力、接続テストを自動で処理するため、手動で .env ファイルを編集する必要はありません：

python scripts/start_tour.py

スクリプトは、どの利用モードを選ぶかを尋ねます：

• Web モード（推奨） — フロント／バックエンドの依存関係をすべてインストールし、一時サーバーを起動してブラウザで LLM、Embedding、Search の設定を案内します。各ステップでリアルタイムの接続テストがあります。設定が完了すると DeepTutor は自動で再起動します。
• CLI モード — ターミナル上で最後まで完結し、GUI のないサーバー環境に適しています。

設定が完了したら http://localhost:3782 にアクセスします。

ステップ3：代替 — .env の環境変数を手動で設定

設定を自分でコントロールしたい場合は、まずサンプルファイルをコピーします：

cp .env.example .env

次に .env を編集し、少なくとも以下の必須項目を埋めてください（Defapi の例）：

# LLM 設定 — Defapi の例：半額で Claude/GPT に接続
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Embedding 設定 — RAG のベクトル検索用
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-defapi-xxxxx
EMBEDDING_HOST=https://api.defapi.com/v1
EMBEDDING_DIMENSION=3072

# 任意：Web 検索
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

対応している LLM Provider の完全な一覧は以下の表です：

ステップ4：依存関係をインストールしてサービスを起動

Web モード（フロント／バック分離）：

# バックエンドの依存関係をインストール
pip install -e ".[server]"

# フロントエンドの依存関係をインストール
cd web && npm install && cd ..

# バックエンド起動（ターミナル1）
python -m deeptutor.api.run_server
# サービスは http://localhost:8001 で動作

# フロントエンド起動（ターミナル2）
cd web && npm run dev -- -p 3782
# サービスは http://localhost:3782 で動作

http://localhost:3782 を開けば使えます。

Docker のワンクリックデプロイ（Python／Node.js のインストール不要）：

# 先に .env を設定（第3ステップを参照）
cp .env.example .env
# .env を編集して API Key を入力

# 公式イメージを取得して起動
docker compose -f docker-compose.ghcr.yml up -d

# ログを確認
docker compose logs -f

ステップ5：5モードのワークスペースを手早く使う

DeepTutor の核は統一されたチャット用ワークスペースで、5種類のモードを切り替えられます。すべてのモードで同じ会話のコンテキストが共有されます：

Chat（デフォルト） — スムーズな会話。RAG 検索、Web 検索、コード実行、深い推論などのツールを組み合わせて対応：

あなたは大学生で、線形代数を復習しています。Chat モードで rag ツールを有効にすると、
DeepTutor はあなたの知識ベースから関連する教材内容を検索して質問に答えます。

Deep Solve（深い解法） — 複数エージェントによる問題解決のパイプライン：計画 → 調査 → 解法 → 検証。各ステップで正確な出典引用があります：

deeptutor run deep_solve "√2 が無理数であることを証明せよ" -t reason

Quiz Generation（出題モード） — 知識ベースを元に評価問題を生成し、自動検証にも対応：

deeptutor run deep_question "熱力学" --kb physics --config num_questions=5

Deep Research（深い調査） — テーマをサブトピックに分解し、並列で RAG、Web、学術論文の Agent をディスパッチして、引用付きのリサーチレポートを生成します：

deeptutor run deep_research "Transformer における Attention 機構"

Math Animator（数学アニメーション） — 数学の概念を可視化アニメーションに変換（Manim の依存関係をインストールする必要があります）：

pip install -r requirements/math-animator.txt
deeptutor run math_animator "Visualize a Fourier series"

ステップ6：最初の RAG 知識ベースを構築

知識ベースは DeepTutor の中核です。PDF、Markdown、テキストファイルをアップロードして、検索可能なベクトル知識ベースを構築します：

CLI で知識ベースを作成：

# 知識ベースを作成し、ドキュメントをアップロード
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# 既存の知識ベースにドキュメントを追加
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# 知識ベースを検索
deeptutor kb search textbook "勾配降下法の収束条件"

# デフォルトの知識ベースに設定
deeptutor kb set-default textbook

Web 画面で操作：

1. 「知識管理」ページへ移動
2. 「新しい知識ベース」をクリックし、名前を付ける（例：my-textbook）
3. PDF または Markdown ファイルをアップロード
4. Chat で RAG ツールを有効化し、その知識ベースを選択

ステップ7：最初の TutorBot を作成する

TutorBot は DeepTutor の「決め手」機能です——それぞれの Bot は永続化され、複数インスタンスで動作できる AI 助教で、独立した記憶、個性、スキルを持ちます：

# 数学助教（ソクラテス式の質問風）を作成
deeptutor bot create math-tutor \
  --name "数学助教" \
  --persona "Socratic math teacher who uses probing questions"

# 執筆コーチを作成
deeptutor bot create writing-coach \
  --name "執筆コーチ" \
  --persona "Patient, detail-oriented writing mentor"

# すべての Bot を表示
deeptutor bot list

# Bot を起動／停止
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot は複数チャネルでの接続に対応（Telegram、Discord、Workplace by Facebook/飛書、メールなど）。あなたがいない間にも、学習リマインドや復習タスクを主導的に開始できます。

ステップ8：CLI の日常的な使用コマンド一覧

# インタラクティブ REPL（ターミナルチャット）
deeptutor chat --capability deep_solve --kb textbook --tool rag

# 単発実行
deeptutor run chat "フーリエ変換を説明して" -t rag --kb textbook -l zh

# セッション管理
deeptutor session list
deeptutor session open <session-id>

# 記憶の表示／クリア
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# 現在の設定を確認
deeptutor config show

# すべてのプラグインとツールを列挙
deeptutor plugin list

---

よくあるトラブルシューティング

1. LLM 接続に失敗（401 Unauthorized または 403 Forbidden）

# API Key が正しいか確認
cat .env | grep LLM_API_KEY

# ネットワーク疎通を確認（Defapi の例）
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

よくある原因：API Key の入力ミス、環境変数が反映されていない（サービスの再起動が必要）、ネットワークから海外 API へアクセスできない。

2. Embedding 検索で結果が出ない

# Embedding 設定を確認
deeptutor config show | grep EMBEDDING

# 知識ベースが正常にインデックス化されているか確認
deeptutor kb info textbook

考えられる原因：ドキュメントアップロード後のインデックス作成が完了していない、ベクトル次元の設定が誤っている（Embedding モデルと一致させる必要あり）、クエリ文とドキュメント内容のマッチが取れていない。

3. ポートが使用中

# 使用中のプロセスを探す
lsof -i :8001  # バックエンドポート
lsof -i :3782  # フロントエンドポート

# または Windows で
netstat -ano | findstr :8001

解決方法：使用中のプロセスを終了する、または .env で BACKEND_PORT と FRONTEND_PORT を変更します。

4. Docker コンテナのヘルスチェック失敗

# コンテナの詳細ログを確認
docker compose logs --tail=100

# .env ファイルが存在し、有効な API Key が含まれているか確認
cat .env

5. フロントエンドがバックエンド WebSocket に接続できない

リモートデプロイ時は、正しい外部アドレスが設定されていることを確認してください：

NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

その後、設定が反映されるようにサービスを再起動します。

6. TutorBot がメッセージに反応しない

Bot の状態を確認し、起動されていることを確実にしてください：

deeptutor bot list
deeptutor bot start <bot-id>

複数チャネルの Bot（例：Telegram）では、該当プラットフォームの Webhook 設定が正しいかも確認が必要です。

---

拡張読書／上級方向性

TutorBot Soul テンプレートのカスタマイズ：Bot の Soul ファイルを編集することで、教助の性格、話し方、教育哲学を定義でき、完全に個別化された AI 冒険者（メンター）を作れます。deeptutor/tutorbot/souls/ ディレクトリにある組み込みテンプレートを参照してください。

プラグイン開発：DeepTutor は 2層のプラグインアーキテクチャ（Tools 層 + Capabilities 層）を採用しており、manifest.yaml + BaseCapability のサブクラスを書いて任意の機能を拡張できます。詳細な開発ガイドは AGENTS.md をご覧ください。

マルチチャネル接続：TutorBot は Telegram、Discord、飛書、エンタープライズ向け微信、メールなどのチャネルに対応しており、AI 助教をあなたが普段使っているどんなプラットフォームにも接続できます。

nanobot エンジン：TutorBot の基盤は nanobot により駆動されており、超軽量級の AI Agent エンジンです。Agent Loop の実装を深掘りして研究する価値があります。

LightRAG 統合（ロードマップ）：次世代の知識ベースエンジン LightRAG が統合される予定で、知識検索能力が大幅に向上します。