DeepTutor-Einstieg: Agent-nativer, personalisierter Lernassistent in der Praxis bereitstellen

Einsteigerlevel | ca. 20 Minuten | Du wirst die Kernarchitektur von DeepTutor beherrschen, zwei Bereitstellungsarten (Setup Tour + Docker), die Nutzung des Fünf-Modi-Arbeitsbereichs sowie die grundlegende Konfiguration von TutorBot

---

Projektvorstellung

DeepTutor ist eine plattform für lernorientierte AI-Agenten. Die zentrale Ausrichtung lautet: „AI soll wirklich beim Lernen helfen – und nicht nur chatten.“ Entwickelt wurde es vom Data Intelligence Lab der University of Hong Kong (HKUDS). Nach der Open-Source-Veröffentlichung im Januar 2026 wurden innerhalb von 39 Tagen 10k Stars erreicht – aktuell zählt es zu den am stärksten beachteten AI-Education-Tech-Projekten auf GitHub.

Das Besondere liegt in der Agent-Native-Architektur: Es wird nicht einfach eine KI in eine Chat-Oberfläche „eingepflanzt“, sondern rund um das Lernziel wird ein komplettes, zusammenarbeitendes Agent-Toolchain-Set entworfen. Du lädst Lehrmaterial hoch, und es hilft dir beim Erstellen von Lernpfaden, beim Generieren von Quizfragen, beim Nachverfolgen von Gedächtnislücken – und kann sogar mathematische Formeln in Animationen umwandeln. TutorBot geht noch einen Schritt weiter: Jeder Tutor ist ein eigenständiger AI-Agent mit eigener Erinnerung und Persönlichkeit, der dich aktiv an Wiederholungen erinnert.

Wenn du nach einem lokal bereitstellbaren, funktionsumfangreichen und stark erweiterbaren KI-Lernassistenten suchst, ist DeepTutor definitiv einen Versuch wert.

---

Zielgruppenprofil

• Entwickler mit 1–3 Jahren Erfahrung, die sich für AI-Agenten und LLM-Anwendungen interessieren
• Bildungs-Tech-Enthusiasten, die personalisierte lokale KI-Lernwerkzeuge einsetzen möchten
• Nutzer, die einen persistenten KI-Tutor aufbauen wollen (RAG + Gedächtnis)

Kerndependencies und Umgebung

• Python 3.11+、Node.js 18+
• LLM-API-Key (OpenAI / Anthropic / DeepSeek usw.)
• Embedding-API-Key (für RAG-Vektor-Suche)
• Docker (optional, bei Docker-Bereitstellung)

Vollständiger Projekt-Strukturbaum

DeepTutor/
├── deeptutor/              # Core-Backend
│   ├── capabilities/      # Fünf Fähigkeiten (chat, deep_solve, deep_question usw.)
│   ├── tools/             # Tool-Schicht (rag, web_search, code_execution usw.)
│   ├── tutorbot/          # TutorBot – persistenter Tutor
│   ├── api/               # FastAPI-Service
│   └── runtime/           # Plugin-Registrierung und -Dispatch
├── deeptutor_cli/         # CLI-Einstieg (Typer)
├── web/                   # Next.js 16 Frontend
├── scripts/start_tour.py  # Interaktives Installations-Setup
└── docker-compose.yml     # Docker-Bereitstellung

---

Schritt-für-Schritt-Anleitung

Schritt 1: Repository klonen und Python-Umgebung erstellen

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

# Python-Virtualenv erstellen (empfohlen: conda)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# oder venv verwenden
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                          # Windows

Schritt 2: Setup Tour interaktiv installieren (empfohlen)

DeepTutor bietet ein interaktives Setup-Skript, das Dependency-Installation, Konfigurationseinträge und Verbindungstests automatisch abwickelt. Du musst die .env-Datei nicht manuell bearbeiten:

python scripts/start_tour.py

Das Skript fragt dich, welchen Modus du nutzen willst:

• Web-Modus (empfohlen) — Installiert Frontend- und Backend-Dependencies, startet einen temporären Server und öffnet den Browser, um dich durch die LLM-, Embedding- und Search-Konfiguration zu führen. In jedem Schritt gibt es Live-Verbindungstests. Nach Abschluss konfiguriert DeepTutor automatisch neu.
• CLI-Modus — Alles läuft vollständig im Terminal ab, geeignet für Serverumgebungen ohne grafische Oberfläche.

Nach erfolgreicher Konfiguration kannst du auf http://localhost:3782 zugreifen.

Schritt 3: Alternative — .env-Umgebungsvariablen manuell konfigurieren

Wenn du die Konfiguration lieber selbst steuern möchtest, kopiere zuerst die Beispiel-Datei:

cp .env.example .env

Bearbeite dann .env. Fülle mindestens die folgenden Pflichtfelder aus (hier als Beispiel Defapi):

# LLM-Konfiguration — am Beispiel Defapi: halbpreisiger Einstieg zu 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-Konfiguration — für RAG-Vektor-Suche
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

# Optional: Websuche
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

Die vollständige Liste unterstützter LLM-Provider findest du in der Tabelle unten:

Schritt 4: Dependencies installieren und Service starten

Web-Modus (Frontend/Backend getrennt):

# Backend-Dependencies installieren
pip install -e ".[server]"

# Frontend-Dependencies installieren
cd web && npm install && cd ..

# Backend starten (Terminal 1)
python -m deeptutor.api.run_server
# Service läuft auf http://localhost:8001

# Frontend starten (Terminal 2)
cd web && npm run dev -- -p 3782
# Service läuft auf http://localhost:3782

Öffne http://localhost:3782, um es zu verwenden.

Docker-1-Klick-Bereitstellung (ohne Python/Node.js installieren):

# Zuerst .env konfigurieren (siehe Schritt 3)
cp .env.example .env
# .env bearbeiten und API Key eintragen

# Offizielles Image ziehen und starten
docker compose -f docker-compose.ghcr.yml up -d

# Logs ansehen
docker compose logs -f

Schritt 5: Schneller Start mit dem Fünf-Modi-Arbeitsbereich

Der Kern von DeepTutor ist ein einheitlicher Chat-Arbeitsbereich. Er unterstützt fünf Moduswechsel, und alle Modi teilen denselben Dialog-Kontext:

Chat (Standardmodus) — flüssige Konversationen, unterstützt Kombinationswerkzeuge wie RAG-Suche, Websuche, Codeausführung, tiefgehende Herleitung:

Du bist Student und bereitest dich auf eine Wiederholung von Lineare Algebra vor. Aktiviere im Chat-Modus das rag-Tool,
DeepTutor sucht in deiner Wissensbasis nach passenden Inhalten aus dem Lehrmaterial, um deine Fragen zu beantworten.

Deep Solve (Deepes Lösen) — mehrstufige Problem-Löse-Pipeline mit mehreren Agenten: Planen → Recherchieren → Lösen → Validieren, mit exakten Quellenangaben in jedem Schritt:

deeptutor run deep_solve "Beweise, dass √2 irrational ist" -t reason

Quiz Generation (Quizmodus) — generiert Prüf-/Bewertungsaufgaben auf Basis der Wissensbasis und unterstützt automatisches Validieren:

deeptutor run deep_question "Thermodynamik" --kb physics --config num_questions=5

Deep Research (Tiefgehende Recherche) — zerlegt ein Thema in Unterthemen, plant parallel RAG-, Web- und Paper-Agenten und erstellt einen Forschungsbericht mit vollständigen Zitaten:

deeptutor run deep_research "Aufmerksamkeitsmechanismus in Transformern"

Math Animator (Mathe-Animation) — transformiert mathematische Konzepte in visualisierte Animationen (Installation der Manim-Dependencies erforderlich):

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

Schritt 6: Baue deine erste RAG-Wissensbasis

Die Wissensbasis ist der Kern von DeepTutor: Lade PDFs, Markdown und Textdateien hoch, um eine durchsuchbare Vektor-Wissensbasis aufzubauen.

Per CLI eine Wissensbasis erstellen:

# Wissensbasis erstellen und Dokumente hochladen
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# Dokumente zu einer vorhandenen Wissensbasis hinzufügen
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# In der Wissensbasis suchen
deeptutor kb search textbook "Konvergenzbedingungen für den Gradientenabstieg"

# Als Standard-Wissensbasis setzen
deeptutor kb set-default textbook

Per Web-Oberfläche bedienen：

1. Öffne die Seite „Wissensmanagement“
2. Klicke auf „Neue Wissensbasis“, gib einen Namen an (z. B. my-textbook)
3. Lade PDF- oder Markdown-Dateien hoch
4. Aktiviere im Chat RAG-Werkzeuge und wähle diese Wissensbasis

Schritt 7: Erstelle deinen ersten TutorBot

TutorBot ist die „Killer“-Funktion von DeepTutor: Jeder Bot ist ein persistenten, mehrinstanzfähiger KI-Tutor mit eigenem Gedächtnis, eigener Persönlichkeit und eigenen Fähigkeiten.

# Mathe-Tutor erstellen (Socratic-Style: sokratische Fragetechnik)
deeptutor bot create math-tutor \
  --name "Mathe-Tutor" \
  --persona "Socratic math teacher who uses probing questions"

# Schreib-Coach erstellen
deeptutor bot create writing-coach \
  --name "Schreib-Coach" \
  --persona "Patient, detail-oriented writing mentor"

# Alle Bots anzeigen
deeptutor bot list

# Bot starten / stoppen
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot unterstützt Multi-Channel-Anbindung (Telegram, Discord, Feishu, E-Mail usw.) und kann proaktiv Lernhinweise sowie Wiederholungsaufgaben anstoßen, wenn du gerade nicht da bist.

Schritt 8: Übersicht der täglichen CLI-Befehle

# Interaktives REPL (Terminal-Chat)
deeptutor chat --capability deep_solve --kb textbook --tool rag

# Einmalige Ausführung
deeptutor run chat "Erkläre die Fourier-Transformation" -t rag --kb textbook -l zh

# Sitzungen verwalten
deeptutor session list
deeptutor session open <session-id>

# Gedächtnis anzeigen / löschen
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# Aktuelle Konfiguration anzeigen
deeptutor config show

# Alle Plugins und Tools auflisten
deeptutor plugin list

---

Häufige Probleme & Troubleshooting

1. LLM-Verbindung fehlgeschlagen (401 Unauthorized oder 403 Forbidden)

# Prüfe, ob der API Key korrekt ist
cat .env | grep LLM_API_KEY

# Prüfe Netzwerk-Konnektivität (hier als Beispiel Defapi)
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

Typische Ursachen: falsch eingetragener API Key, nicht aktivierte Umgebungsvariablen (Service neu starten), Netzwerk kann auf nicht im Inland erreichbare APIs nicht zugreifen.

2. Keine Treffer bei Embedding-Suche

# Embedding-Konfiguration prüfen
deeptutor config show | grep EMBEDDING

# Sicherstellen, dass die Wissensbasis erfolgreich indexiert ist
deeptutor kb info textbook

Mögliche Ursachen: Indexierung nach dem Hochladen ist noch nicht abgeschlossen, falsche Vektor-Dimensionen (müssen zum Embedding-Modell passen), Abfrage passt nicht zu den Inhalten des Dokuments.

3. Port ist belegt

# Prozess finden, der den Port belegt
lsof -i :8001  # Backend-Port
lsof -i :3782  # Frontend-Port

# Oder unter Windows
netstat -ano | findstr :8001

Lösung: Belegenden Prozess beenden oder BACKEND_PORT und FRONTEND_PORT in .env anpassen.

4. Docker-Container-Health-Check fehlgeschlagen

# Detaillierte Container-Logs ansehen
docker compose logs --tail=100

# Prüfen, ob .env existiert und gültige API Keys enthält
cat .env

5. Frontend kann WebSocket vom Backend nicht erreichen

Bei Remote-Bereitstellung sicherstellen, dass die korrekte externe Adresse gesetzt ist:

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

Dann Services neu starten, damit die Konfiguration wirksam wird.

6. TutorBot reagiert nicht auf Nachrichten

Prüfe den Status des Bots und stelle sicher, dass er gestartet ist:

deeptutor bot list
deeptutor bot start <bot-id>

Multi-Channel-Bots (z. B. Telegram) benötigen außerdem einen Check, ob die Webhook-Konfiguration auf der jeweiligen Plattform korrekt ist.

---

Weiterführende Lektüre / Ausbau-Richtungen

TutorBot Soul-Vorlagen anpassen: Durch das Bearbeiten der „Soul“-Datei eines Bots kannst du Charakter, Tonfall und die Lehrphilosophie definieren – so entsteht ein vollständig personalisierter AI-Tutor. Siehe die eingebauten Vorlagen im Verzeichnis deeptutor/tutorbot/souls/.

Plugin-Entwicklung: DeepTutor nutzt eine zweistufige Plugin-Architektur (Tools-Schicht + Capabilities-Schicht). Du kannst beliebige Funktionen erweitern, indem du manifest.yaml + eine BaseCapability-Unterklasse schreibst. Detaillierte Entwicklungsrichtlinien findest du in AGENTS.md.

Multi-Channel-Anbindung: TutorBot unterstützt Kanäle wie Telegram, Discord, Feishu, Enterprise-WeChat sowie E-Mail. Damit kannst du deine KI-Tutoren mit jeder Plattform verbinden, die du regelmäßig nutzt.

nanobot-Engine: Die unterliegende Engine von TutorBot wird von nanobot angetrieben – eine ultraleichte AI-Agent-Engine. Es lohnt sich, ihre Agent-Loop-Implementierung genauer zu untersuchen.

LightRAG-Integration (im Roadmap-Plan): Die nächste Generation der Wissensbasis-Engine, LightRAG, wird integriert. Dann wird die Fähigkeit zur Wissenssuche deutlich verbessert.