Recursos · Começar · Explorar · TutorBot · CLI · Roteiro · Comunidade
🇬🇧 English · 🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português · 🇹🇭 ภาษาไทย
[2026.4.21] v1.2.1 — Limites de tokens por etapa em
agents.yaml(respostas de 8000 tokens), regenerar a última resposta (CLI / WebSocket / Web UI), correção de falha RAG com embeddingsNone, compatibilidade Gemmajson_object, legibilidade de blocos de código escuros.
[2026.4.20] v1.2.0 — Book Engine: compilador multiagente de «livros vivos» com 14 tipos de blocos, espaço de trabalho Co-Writer multidocumento, visualizações HTML interativas, menções @ do banco de questões no chat, fase 2 de externalização de prompts e reformulação da barra lateral.
[2026.4.18] v1.1.2 — Aba Channels orientada por schema com mascaramento de segredos; RAG unificado em um único pipeline; reforço de consistência RAG/KB; prompts de chat externalizados; README em tailandês.
[2026.4.17] v1.1.1 — «Responder agora» universal em todas as capacidades; sincronização de rolagem no Co-Writer; seleção de mensagens ao salvar no caderno; painel de configurações unificado; botão Stop em streaming; gravação atômica da configuração do TutorBot.
[2026.4.15] v1.1.0 — Reformulação do parsing de LaTeX em bloco; sonda de diagnóstico LLM via
agents.yaml; correção do encaminhamento de cabeçalhos extras; correção de UUID no SaveToNotebook; guia Docker + LLM local.
[2026.4.14] v1.1.0-beta — Sessões com URL marcável; tema Snow; heartbeat WebSocket e reconexão automática; desempenho do ChatComposer; reformulação do registro de provedores de embeddings; provedor de busca Serper.
[2026.4.13] v1.0.3 — Caderno de questões com favoritos e categorias; Mermaid no Visualize; detecção de incompatibilidade de embeddings; compatibilidade Qwen/vLLM; suporte LM Studio e llama.cpp; tema Glass.
[2026.4.11] v1.0.2 — Consolidação de busca com fallback SearXNG; correção da troca de provedor; vazamentos de recursos no frontend.
[2026.4.10] v1.0.1 — Capacidade Visualize (Chart.js/SVG); prevenção de duplicatas em questionários; suporte ao modelo o4-mini.
[2026.4.10] v1.0.0-beta.4 — Acompanhamento de embeddings com nova tentativa sob limite de taxa; dependências multiplataforma; validação MIME.
[2026.4.8] v1.0.0-beta.3 — SDK nativo OpenAI/Anthropic (sem litellm); Math Animator no Windows; parsing JSON mais robusto; i18n chinês completo.
[2026.4.7] v1.0.0-beta.2 — Recarga a quente de configurações; saída aninhada MinerU; correção WebSocket; mínimo Python 3.11+.
[2026.4.4] v1.0.0-beta.1 — Reescrita nativa de agentes (~200k linhas): plugins Tools + Capabilities, CLI e SDK, TutorBot, Co-Writer, aprendizado guiado e memória persistente.
Lançamentos anteriores
[2026.1.23] v0.6.0 — Persistência de sessão, upload incremental, RAG flexível, localização em chinês.
[2026.1.18] v0.5.2 — Docling, logs, correções.
[2026.1.15] v0.5.0 — Config unificada, RAG por KB, geração de questões, barra lateral.
[2026.1.9] v0.4.0 — Multi-provedor LLM/embeddings, nova home, desacoplamento RAG, variáveis de ambiente.
[2026.1.5] v0.3.0 — PromptManager, CI/CD, imagens GHCR.
[2026.1.2] v0.2.0 — Docker, Next.js 16 e React 19, WebSocket, vulnerabilidades.
[2026.4.4] Há quanto tempo! ✨ DeepTutor v1.0.0 chegou — evolução nativa de agentes com reescrita da arquitetura do zero, TutorBot e modos flexíveis sob Apache-2.0. Um novo capítulo começa!
[2026.2.6] 🚀 10k estrelas em 39 dias — obrigado à comunidade!
[2026.1.1] Feliz Ano Novo! Junte-se ao Discord, WeChat ou Discussions.
[2025.12.29] DeepTutor é lançado oficialmente.
- Workspace de chat unificado — Seis modos, um fio: Chat, Deep Solve, quiz, Deep Research, Math Animator e Visualize compartilham contexto.
- AI Co-Writer — Espaço Markdown multidocumento com IA como colaborador: reescrever, expandir ou encurtar com KB e web.
- Book Engine — Transforme materiais em «livros vivos» estruturados e interativos: pipeline multiagente, 14 tipos de blocos (quiz, flashcards, linhas do tempo, grafos de conceitos e mais).
- Hub de conhecimento — Bases RAG, cadernos coloridos, banco de questões e Skills personalizados que moldam o ensino.
- Memória persistente — Resumo de progresso e perfil do aprendiz; compartilhado com TutorBots.
- TutorBots pessoais — Não são chatbots: tutores autônomos com espaço de trabalho, memória, personalidade e habilidades. nanobot.
- CLI nativo para agentes — Capacidades, KB, sessões e TutorBot em um comando; Rich e JSON.
SKILL.md.
Antes de começar, certifique-se de ter instalado:
| Requisito | Versão | Verificar | Notas |
|---|---|---|---|
| Git | Qualquer | git --version |
Para clonar o repositório |
| Python | 3.11+ | python --version |
Backend |
| Node.js | 18+ | node --version |
Build do frontend (não necessário só CLI ou Docker) |
| npm | 9+ | npm --version |
Geralmente vem com o Node.js |
Você também precisa de uma chave API de pelo menos um provedor LLM (por exemplo OpenAI, DeepSeek, Anthropic). O tour guiado ajuda a inseri-la e testar a conexão.
Um único script interativo cobre instalação de dependências, configuração do ambiente, teste de conexão em tempo real e inicialização. Quase não é preciso editar .env manualmente.
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
# Ambiente virtual Python (escolha um):
conda create -n deeptutor python=3.11 && conda activate deeptutor # se usar Anaconda/Miniconda
python -m venv .venv && source .venv/bin/activate # caso contrário (macOS/Linux)
python -m venv .venv && .venv\Scripts\activate # caso contrário (Windows)
python scripts/start_tour.pyO tour pergunta como deseja usar o DeepTutor:
- Modo web (recomendado) — Instala todas as dependências (pip + npm), sobe um servidor temporário e abre Configurações no navegador; quatro passos para LLM, embeddings e busca com teste de conexão em tempo real; ao terminar, o DeepTutor reinicia automaticamente com sua configuração.
- Modo CLI — Fluxo totalmente interativo no terminal: perfil, instalação, provedores, verificação e aplicação sem sair do shell.
Em ambos os casos você terá o DeepTutor em http://localhost:3782.
Início diário — O tour só é necessário uma vez. Depois disso, inicie com:
python scripts/start_web.pyInicia backend e frontend em um único comando e abre o navegador. Execute
start_tour.pynovamente apenas se precisar reconfigurar provedores ou reinstalar dependências.
Se preferir controle total, instale e configure tudo manualmente.
1. Instalar dependências
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
# Criar e ativar ambiente virtual (igual à opção A)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# DeepTutor com dependências de backend + servidor web
pip install -e ".[server]"
# Frontend (requer Node.js 18+)
cd web && npm install && cd ..2. Configurar ambiente
cp .env.example .envEdite .env e preencha pelo menos os campos obrigatórios:
# LLM (obrigatório)
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.openai.com/v1
# Embeddings (obrigatório para a base de conhecimento)
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=3072Provedores LLM suportados
| Provedor | Binding | URL base padrão |
|---|---|---|
| AiHubMix | aihubmix |
https://aihubmix.com/v1 |
| Anthropic | anthropic |
https://api.anthropic.com/v1 |
| Azure OpenAI | azure_openai |
— |
| BytePlus | byteplus |
https://ark.ap-southeast.bytepluses.com/api/v3 |
| BytePlus Coding Plan | byteplus_coding_plan |
https://ark.ap-southeast.bytepluses.com/api/coding/v3 |
| Custom (OpenAI-compat) | custom |
— |
| DashScope (Qwen) | dashscope |
https://dashscope.aliyuncs.com/compatible-mode/v1 |
| DeepSeek | deepseek |
https://api.deepseek.com |
| Gemini | gemini |
https://generativelanguage.googleapis.com/v1beta/openai/ |
| GitHub Copilot | github_copilot |
https://api.githubcopilot.com |
| Groq | groq |
https://api.groq.com/openai/v1 |
| llama.cpp | llama_cpp |
http://localhost:8080/v1 |
| LM Studio | lm_studio |
http://localhost:1234/v1 |
| MiniMax | minimax |
https://api.minimax.io/v1 |
| Mistral | mistral |
https://api.mistral.ai/v1 |
| Moonshot (Kimi) | moonshot |
https://api.moonshot.ai/v1 |
| Ollama | ollama |
http://localhost:11434/v1 |
| OpenAI | openai |
https://api.openai.com/v1 |
| OpenAI Codex | openai_codex |
https://chatgpt.com/backend-api |
| OpenRouter | openrouter |
https://openrouter.ai/api/v1 |
| OpenVINO Model Server | ovms |
http://localhost:8000/v3 |
| Qianfan (Ernie) | qianfan |
https://qianfan.baidubce.com/v2 |
| SiliconFlow | siliconflow |
https://api.siliconflow.cn/v1 |
| Step Fun | stepfun |
https://api.stepfun.com/v1 |
| vLLM | vllm |
http://localhost:8000/v1 |
| VolcEngine | volcengine |
https://ark.cn-beijing.volces.com/api/v3 |
| VolcEngine Coding Plan | volcengine_coding_plan |
https://ark.cn-beijing.volces.com/api/coding/v3 |
| Xiaomi MIMO | xiaomi_mimo |
https://api.xiaomimimo.com/v1 |
| Zhipu AI (GLM) | zhipu |
https://open.bigmodel.cn/api/paas/v4 |
Provedores de embedding suportados
| Provedor | Binding | Exemplo de modelo | Dimensão padrão |
|---|---|---|---|
| OpenAI | openai |
text-embedding-3-large |
3072 |
| Azure OpenAI | azure_openai |
nome do deployment | — |
| Cohere | cohere |
embed-v4.0 |
1024 |
| Jina | jina |
jina-embeddings-v3 |
1024 |
| Ollama | ollama |
nomic-embed-text |
768 |
| vLLM / LM Studio | vllm |
Qualquer modelo de embedding | — |
| Compatível OpenAI | custom |
— | — |
Provedores compatíveis com OpenAI (DashScope, SiliconFlow, etc.) funcionam com o binding custom ou openai.
Provedores de busca web suportados
| Provedor | Variável de ambiente | Notas |
|---|---|---|
| Brave | BRAVE_API_KEY |
Recomendado, há nível gratuito |
| Tavily | TAVILY_API_KEY |
|
| Serper | SERPER_API_KEY |
Resultados Google via Serper |
| Jina | JINA_API_KEY |
|
| SearXNG | — | Auto-hospedado, sem chave API |
| DuckDuckGo | — | Sem chave API |
| Perplexity | PERPLEXITY_API_KEY |
Requer chave API |
3. Iniciar serviços
A forma mais rápida:
python scripts/start_web.pyInicia backend e frontend e abre o navegador automaticamente.
Ou inicie cada serviço manualmente em terminais separados:
# Backend (FastAPI)
python -m deeptutor.api.run_server
# Frontend (Next.js) — outro terminal
cd web && npm run dev -- -p 3782| Serviço | Porta padrão |
|---|---|
| Backend | 8001 |
| Frontend | 3782 |
Abra http://localhost:3782.
O Docker empacota backend e frontend em um único contêiner; não é necessário Python ou Node.js locais. Basta Docker Desktop (ou Docker Engine + Compose no Linux).
1. Variáveis de ambiente (necessárias nas duas variantes abaixo)
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .envEdite .env e preencha pelo menos os campos obrigatórios (como na opção B).
2a. Puxar imagem oficial (recomendado)
As imagens oficiais são publicadas no GitHub Container Registry a cada release, para linux/amd64 e linux/arm64.
docker compose -f docker-compose.ghcr.yml up -dPara fixar uma versão, edite a tag da imagem em docker-compose.ghcr.yml:
image: ghcr.io/hkuds/deeptutor:1.0.0 # ou :latest2b. Build a partir do código-fonte
docker compose up -dConstrói a imagem localmente a partir do Dockerfile e inicia o contêiner.
3. Verificar e gerenciar
Abra http://localhost:3782 quando o contêiner estiver healthy.
docker compose logs -f # acompanhar logs
docker compose down # parar e remover o contêinerNuvem / servidor remoto
Em um servidor remoto, o navegador precisa da URL pública da API backend. Adicione em .env:
# URL pública onde o backend é acessível
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001O script de inicialização do frontend aplica esse valor em tempo de execução — não é necessário rebuild.
Modo desenvolvimento (hot-reload)
Sobreponha o override de desenvolvimento para montar o código-fonte e habilitar hot-reload em ambos os serviços:
docker compose -f docker-compose.yml -f docker-compose.dev.yml upAlterações em deeptutor/, deeptutor_cli/, scripts/ e web/ refletem-se imediatamente.
Portas personalizadas
Substitua as portas padrão em .env:
BACKEND_PORT=9001
FRONTEND_PORT=4000Depois reinicie:
docker compose up -d # ou docker compose -f docker-compose.ghcr.yml up -dPersistência de dados
Dados do usuário e bases de conhecimento persistem via volumes Docker mapeados para diretórios locais:
| Caminho no contêiner | Caminho no host | Conteúdo |
|---|---|---|
/app/data/user |
./data/user |
Configurações, memória, workspace, sessões, logs |
/app/data/knowledge_bases |
./data/knowledge_bases |
Documentos enviados e índices vetoriais |
Esses diretórios permanecem após docker compose down e são reutilizados no próximo docker compose up.
Referência de variáveis de ambiente
| Variável | Obrigatório | Descrição |
|---|---|---|
LLM_BINDING |
Sim | Provedor LLM (openai, anthropic, etc.) |
LLM_MODEL |
Sim | Nome do modelo (ex.: gpt-4o) |
LLM_API_KEY |
Sim | Chave API do LLM |
LLM_HOST |
Sim | URL do endpoint |
EMBEDDING_BINDING |
Sim | Provedor de embeddings |
EMBEDDING_MODEL |
Sim | Nome do modelo de embedding |
EMBEDDING_API_KEY |
Sim | Chave API de embeddings |
EMBEDDING_HOST |
Sim | Endpoint de embeddings |
EMBEDDING_DIMENSION |
Sim | Dimensão do vetor |
SEARCH_PROVIDER |
Não | Busca (tavily, jina, serper, perplexity, etc.) |
SEARCH_API_KEY |
Não | Chave API de busca |
BACKEND_PORT |
Não | Porta backend (padrão 8001) |
FRONTEND_PORT |
Não | Porta frontend (padrão 3782) |
NEXT_PUBLIC_API_BASE_EXTERNAL |
Não | URL pública do backend para nuvem |
DISABLE_SSL_VERIFY |
Não | Desativar verificação SSL (padrão false) |
Se quiser apenas a CLI sem o frontend web:
pip install -e ".[cli]"Ainda é necessário configurar o provedor LLM. O caminho mais rápido:
cp .env.example .env # depois edite .env com suas chaves APIApós configurar:
deeptutor chat
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4"
deeptutor kb create my-kb --doc textbook.pdfGuia completo: DeepTutor CLI.
Seis modos com contexto unificado.
| Modo | Função |
|---|---|
| Chat | RAG, web, código, raciocínio, brainstorming, papers. |
| Deep Solve | Multiagente com citações. |
| Geração de quiz | Avaliações na KB. |
| Deep Research | Subtópicos, agentes paralelos, relatório citado. |
| Math Animator | Manim. |
| Visualize | SVG, Chart.js, Mermaid ou HTML autocontido a partir de linguagem natural. |
Ferramentas desacopladas dos fluxos.
Crie e gerencie vários documentos, cada um persistido — não um rascunho único: Markdown completo com IA como coautora. Reescrever, Expandir, Encurtar; desfazer/refazer; cadernos.
Dê um tema, aponte para a sua base de conhecimento: o DeepTutor produz um livro estruturado e interativo — documento vivo para ler, autoavaliar e discutir em contexto.
Por trás, um pipeline multiagente propõe o esquema, recupera fontes, funde a árvore de capítulos, planeja cada página e compila cada bloco. Você continua no controle: revisão da proposta, reordenação de capítulos e chat ao lado de cada página.
14 tipos de blocos — texto, destaque, quiz, flashcards, código, figura, mergulho profundo, animação, interativo, linha do tempo, grafo de conceitos, seção, nota do usuário e marcador — cada um com componente interativo. Linha do tempo de progresso em tempo real.
Coleções de documentos, notas e personas de ensino.
- Bases de conhecimento — PDF, TXT, MD.
- Cadernos — Insights de Chat, Co-Writer, Book ou Deep Research, por cores.
- Banco de questões — Revise quizzes gerados; favoritos e @menções no chat para analisar desempenho passado.
- Skills — Personas com
SKILL.md: nome, descrição, gatilhos opcionais e corpo Markdown injetado no prompt do sistema do chat quando ativos.
- Resumo — Progresso.
- Perfil — Preferências, nível, metas. Compartilhado com TutorBots.
Agente multi-instância persistente com nanobot.
- Modelos Soul — Personalidade e pedagogia.
- Workspace independente — Memória, sessões, habilidades; camada compartilhada.
- Heartbeat proativo — Lembretes e tarefas.
- Ferramentas completas — RAG, código, web, papers, raciocínio, brainstorming.
- Habilidades — Arquivos skill.
- Multicanal — Telegram, Discord, Slack, Feishu, WeCom, DingTalk, e-mail, etc.
- Equipes e subagentes.
deeptutor bot create math-tutor --persona "Socratic math teacher who uses probing questions"
deeptutor bot create writing-coach --persona "Patient, detail-oriented writing mentor"
deeptutor bot list
Sem navegador: capacidades, KB, sessões, memória, TutorBot. Rich + JSON. SKILL.md.
deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook
deeptutor run deep_solve "Prove that √2 is irrational" -t reason
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms in transformers"
deeptutor run visualize "Draw the architecture of a transformer"deeptutor chat --capability deep_solve --kb my-kb
# No REPL: /cap, /tool, /kb, /history, /notebook, /config para alternar em tempo realdeeptutor kb create my-kb --doc textbook.pdf
deeptutor kb add my-kb --docs-dir ./papers/
deeptutor kb search my-kb "gradient descent"
deeptutor kb set-default my-kbdeeptutor run chat "Summarize chapter 3" -f rich
deeptutor run chat "Summarize chapter 3" -f jsondeeptutor session list
deeptutor session open <id>Referência completa da CLI
Nível superior
| Comando | Descrição |
|---|---|
deeptutor run <capability> <message> |
Executa uma capacidade em um turno (chat, deep_solve, deep_question, deep_research, math_animator, visualize) |
deeptutor chat |
REPL interativo com --capability, --tool, --kb, --language, etc. |
deeptutor serve |
Inicia o servidor API do DeepTutor |
deeptutor bot
| Comando | Descrição |
|---|---|
deeptutor bot list |
Lista instâncias do TutorBot |
deeptutor bot create <id> |
Cria e inicia um bot (--name, --persona, --model) |
deeptutor bot start <id> |
Inicia um bot |
deeptutor bot stop <id> |
Para um bot |
deeptutor kb
| Comando | Descrição |
|---|---|
deeptutor kb list |
Lista bases de conhecimento |
deeptutor kb info <name> |
Detalhes da base |
deeptutor kb create <name> |
Cria a partir de documentos (--doc, --docs-dir) |
deeptutor kb add <name> |
Adiciona documentos |
deeptutor kb search <name> <query> |
Busca na base |
deeptutor kb set-default <name> |
Define KB padrão |
deeptutor kb delete <name> |
Remove (--force) |
deeptutor memory
| Comando | Descrição |
|---|---|
deeptutor memory show [file] |
Ver (summary, profile, all) |
deeptutor memory clear [file] |
Limpar (--force) |
deeptutor session
| Comando | Descrição |
|---|---|
deeptutor session list |
Lista sessões (--limit) |
deeptutor session show <id> |
Mensagens da sessão |
deeptutor session open <id> |
Retomar no REPL |
deeptutor session rename <id> |
Renomear (--title) |
deeptutor session delete <id> |
Excluir |
deeptutor notebook
| Comando | Descrição |
|---|---|
deeptutor notebook list |
Lista cadernos |
deeptutor notebook create <name> |
Criar (--description) |
deeptutor notebook show <id> |
Registros |
deeptutor notebook add-md <id> <path> |
Importar Markdown |
deeptutor notebook replace-md <id> <rec> <path> |
Substituir registro |
deeptutor notebook remove-record <id> <rec> |
Remover registro |
deeptutor book
| Comando | Descrição |
|---|---|
deeptutor book list |
Lista todos os livros do espaço de trabalho |
deeptutor book health <book_id> |
Verifica deriva da KB e saúde do livro |
deeptutor book refresh-fingerprints <book_id> |
Atualiza impressões digitais da KB e limpa páginas obsoletas |
deeptutor config / plugin / provider
| Comando | Descrição |
|---|---|
deeptutor config show |
Resumo da configuração |
deeptutor plugin list |
Ferramentas e capacidades registradas |
deeptutor plugin info <name> |
Detalhe de ferramenta ou capacidade |
deeptutor provider login <provider> |
OAuth (openai-codex, github-copilot) |
| Status | Marco |
|---|---|
| 🎯 | Autenticação e login — Página de login opcional para implantações públicas com multiusuário |
| 🎯 | Temas e aparência — Mais temas e personalização da interface |
| 🎯 | Melhoria de interação — Refinar ícones e detalhes de interação |
| 🔜 | Memórias melhores — Integrar gestão de memória mais robusta |
| 🔜 | Integração LightRAG — Integrar LightRAG como motor avançado de bases de conhecimento |
| 🔜 | Site de documentação — Documentação completa com guias, referência de API e tutoriais |
Se o DeepTutor for útil para você, dê uma estrela — isso nos ajuda a continuar!
| Projeto | Papel |
|---|---|
| nanobot | Motor do TutorBot |
| LlamaIndex | RAG |
| ManimCat | Math Animator |
| ⚡ LightRAG | 🤖 AutoAgent | 🔬 AI-Researcher | 🧬 nanobot |
|---|---|---|---|
| RAG rápido | Agentes sem código | Pesquisa automática | Agente ultraleve |
Esperamos que o DeepTutor seja um presente para a comunidade. 🎁
Veja CONTRIBUTING.md.