DeepTutor: Seu Assistente Pessoal de Aprendizado

Início Rápido · Módulos Principais · Perguntas Frequentes

🇬🇧 English · 🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português

| ⚡ Q&A de Conhecimento de Documentos Massivos | 📈 Visualização de Aprendizado Interativo |
| 🧠 Reforço de Conhecimento | 🔬 Pesquisa Profunda e Geração de Ideias |

[2026.1.1] Feliz Ano Novo! Junte-se às nossas GitHub Discussions — molde o futuro do DeepTutor! 💬

[2025.12.30] Visite nosso Site Oficial para mais detalhes!

[2025.12.29] DeepTutor v0.1 já está disponível! ✨

Características Principais do DeepTutor

📚 Q&A de Conhecimento de Documentos Massivos

• Base de Conhecimento Inteligente: Faça upload de livros didáticos, artigos de pesquisa, manuais técnicos e documentos específicos do domínio. Construa um repositório de conhecimento abrangente alimentado por IA para acesso instantâneo.
• Resolução de Problemas Multi-Agente: Arquitetura de raciocínio de duplo loop com RAG, busca na web, busca de artigos e execução de código—fornecendo soluções passo a passo com citações precisas.

🎨 Visualização de Aprendizado Interativo

• Simplificação e Explicações do Conhecimento: Transforme conceitos complexos, conhecimento e algoritmos em auxílios visuais fáceis de entender, decomposições detalhadas passo a passo e demonstrações interativas envolventes.
• Q&A Personalizado: Conversas conscientes do contexto que se adaptam ao seu progresso de aprendizado, com páginas interativas e rastreamento de conhecimento baseado em sessões.

🎯 Reforço de Conhecimento com Gerador de Problemas de Prática

• Criação de Exercícios Inteligentes: Gere questionários direcionados, problemas de prática e avaliações personalizadas adaptadas ao seu nível atual de conhecimento e objetivos de aprendizado específicos.
• Simulação de Exame Autêntica: Faça upload de exames de referência para gerar questões de prática que correspondem perfeitamente ao estilo, formato e dificuldade originais—fornecendo preparação realista para o teste real.

🔍 Pesquisa Profunda e Geração de Ideias

• Pesquisa Abrangente e Revisão de Literatura: Realize exploração profunda de tópicos com análise sistemática. Identifique padrões, conecte conceitos relacionados entre disciplinas e sintetize descobertas de pesquisa existentes.
• Descoberta de Insights Inovadores: Gere materiais de aprendizado estruturados e descubra lacunas de conhecimento. Identifique novas direções de pesquisa promissoras através de síntese inteligente de conhecimento entre domínios.

📚 Q&A de Conhecimento de Documentos Massivos

_{Resolução de Problemas Multi-Agente com Citações Exatas}

🎨 Visualização de Aprendizado Interativo

_{Explicações Visuais Passo a Passo com Q&A Personalizado}

🎯 Reforço de Conhecimento

Questões Personalizadas
_{Geração de Questões de Prática Auto-Validadas}

Questões de Imitação
_{Clonar Estilo de Exame para Prática Autêntica}

🔍 Pesquisa Profunda e Geração de Ideias

Pesquisa Profunda
_{Extensão do Conhecimento do Livro Didático com RAG, Web e Busca de Artigos}

IdeaGen Automatizado
_{Brainstorming Sistemático e Síntese de Conceitos com Fluxo de Trabalho de Duplo Filtro}

IdeaGen Interativo
_{Co-Writer Alimentado por RAG e Busca Web com Geração de Podcasts}

🏗️ Sistema de Conhecimento Tudo-em-Um

Base de Conhecimento Pessoal
_{Construa e Organize Seu Próprio Repositório de Conhecimento}

Caderno Pessoal
_{Sua Memória Contextual para Sessões de Aprendizado}

_{🌙 Use DeepTutor no Modo Escuro!}

Arquitetura do Sistema

📋 Tarefas Pendentes

Siga-nos para nossas futuras atualizações!

Suporte para serviços LLM locais (ex. ollama)
Refatoração do módulo RAG (ver Discussions)
Codificação profunda a partir da geração de ideias
Interação personalizada com o caderno

🚀 Início Rápido

Passo 1: Pré-configuração

① Clonar Repositório

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

② Configurar Variáveis de Ambiente

cp .env.example .env
# Edite o arquivo .env com suas chaves de API

📋 Referência de Variáveis de Ambiente

Variável	Obrigatório	Descrição
`LLM_MODEL`	Sim	Nome do modelo (ex: `gpt-4o`)
`LLM_BINDING_API_KEY`	Sim	Sua chave API LLM
`LLM_BINDING_HOST`	Sim	URL do endpoint da API
`EMBEDDING_MODEL`	Sim	Nome do modelo de incorporação
`EMBEDDING_BINDING_API_KEY`	Sim	Chave API de incorporação
`EMBEDDING_BINDING_HOST`	Sim	Endpoint da API de incorporação
`BACKEND_PORT`	Não	Porta do backend (padrão: `8001`)
`FRONTEND_PORT`	Não	Porta do frontend (padrão: `3782`)
`TTS_*`	Não	Configurações de texto para voz
`PERPLEXITY_API_KEY`	Não	Para busca na web

③ Configurar Portas e LLM (Opcional)

Portas: Edite config/main.yaml → server.backend_port / server.frontend_port
LLM: Edite config/agents.yaml → temperature / max_tokens por módulo
Consulte Documentação de Configuração para detalhes

④ Experimentar Bases de Conhecimento Demo (Opcional)

📚 Demos Disponíveis

Artigos de Pesquisa — 5 artigos do nosso laboratório (AI-Researcher, LightRAG, etc.)
Livro Didático de Ciência de Dados — 8 capítulos, 296 páginas (Link do Livro)

Baixar de Google Drive
Extrair para o diretório data/

Os KBs demo usam text-embedding-3-large com dimensions = 3072

⑤ Criar Sua Própria Base de Conhecimento (Após o Início)

Ir para http://localhost:3782/knowledge
Clicar em "New Knowledge Base" → Inserir nome → Fazer upload de arquivos PDF/TXT/MD
Monitorar o progresso no terminal

Passo 2: Escolha seu Método de Instalação

🐳 Implantação Docker

Recomendado — Sem configuração Python/Node.js

Pré-requisitos: Docker e Docker Compose

Início Rápido:

# Construir e iniciar (~5-10 min primeira execução)
docker compose up --build -d

# Ver logs
docker compose logs -f

Comandos:

docker compose up -d      # Iniciar
docker compose logs -f    # Logs
docker compose down       # Parar
docker compose up --build # Reconstruir

Modo Dev: Adicionar -f docker-compose.dev.yml

Avançado:

# Construir imagem personalizada
docker build -t deeptutor:latest .

# Executar standalone
docker run -p 8001:8001 -p 3782:3782 \
  --env-file .env deeptutor:latest

💻 Instalação Manual

Para desenvolvimento ou ambientes não Docker

Pré-requisitos: Python 3.10+, Node.js 18+

Configurar Ambiente:

# Usando conda (Recomendado)
conda create -n deeptutor python=3.10
conda activate deeptutor

# Ou usando venv
python -m venv venv
source venv/bin/activate

Instalar Dependências:

bash scripts/install_all.sh

# Ou manualmente:
pip install -r requirements.txt
npm install --prefix web

Iniciar:

# Iniciar interface web
python scripts/start_web.py

# Ou apenas CLI
python scripts/start.py

# Parar: Ctrl+C

URLs de Acesso

Serviço	URL	Descrição
Frontend	http://localhost:3782	Interface web principal
Documentação API	http://localhost:8001/docs	Documentação de API interativa

📂 Armazenamento de Dados

Todo o conteúdo gerado pelo usuário e os dados do sistema são armazenados na pasta data/:

data/
├── knowledge_bases/              # Armazenamento da base de conhecimento
└── user/                         # Dados de atividade do usuário
    ├── solve/                    # Resultados de resolução de problemas e artefatos
    ├── question/                 # Questões geradas
    ├── research/                 # Relatórios de pesquisa e cache
    ├── co-writer/                # Documentos Co-Writer e arquivos de áudio
    ├── notebook/                 # Registros de caderno e metadados
    ├── guide/                    # Sessões de aprendizado guiado
    ├── logs/                     # Logs do sistema
    └── run_code_workspace/       # Espaço de trabalho de execução de código

Todos os resultados são automaticamente salvos quando você realiza qualquer atividade. As pastas são criadas automaticamente se não existirem.

📖 Documentação dos Módulos

Configuração	Repositório de Dados	Backend API	Utilitários Principais
Base de Conhecimento	Ferramentas	Frontend Web	Módulo de Resolução
Módulo de Questões	Módulo de Pesquisa	Módulo Co-Writer	Módulo de Guia
Módulo de Geração de Ideias

❓ Perguntas Frequentes

O backend não inicia?

Lista de Verificação

Confirme que a versão Python >= 3.10
Confirme que todas as dependências estão instaladas: pip install -r requirements.txt
Verifique se a porta 8001 está em uso (configurável em config/main.yaml)
Verifique a configuração do arquivo .env

Soluções

Mudar porta: Edite config/main.yaml server.backend_port
Verificar logs: Revise as mensagens de erro do terminal

Porta ocupada após Ctrl+C?

Problema

Após pressionar Ctrl+C durante uma tarefa em execução (por exemplo, pesquisa profunda), reiniciar mostra erro "porta já em uso".

Causa

Ctrl+C às vezes termina apenas o processo frontend enquanto o backend continua executando em segundo plano.

Solução

# macOS/Linux: Encontrar e matar o processo
lsof -i :8001
kill -9 <PID>

# Windows: Encontrar e matar o processo
netstat -ano | findstr :8001
taskkill /PID <PID> /F

Depois reinicie o serviço com python scripts/start_web.py.

Erro "npm: command not found"?

Problema

Executar scripts/start_web.py mostra npm: command not found ou código de saída 127.

Lista de Verificação

Verifique se npm está instalado: npm --version
Verifique se Node.js está instalado: node --version
Confirme que o ambiente conda está ativado (se estiver usando conda)

Soluções

# Opção A: Usar Conda (Recomendado)
conda install -c conda-forge nodejs

# Opção B: Usar instalador oficial
# Baixar de https://nodejs.org/

# Opção C: Usar nvm
nvm install 18
nvm use 18

Verificar Instalação

node --version  # Deve mostrar v18.x.x ou superior
npm --version   # Deve mostrar o número da versão

O frontend não consegue conectar ao backend?

Lista de Verificação

Confirme que o backend está em execução (visite http://localhost:8001/docs)
Verifique o console do navegador para mensagens de erro

Solução

Crie .env.local no diretório web:

NEXT_PUBLIC_API_BASE=http://localhost:8001

Falha na conexão WebSocket?

Lista de Verificação

Confirme que o backend está em execução
Verifique as configurações do firewall
Confirme que a URL WebSocket está correta

Solução

Verifique os logs do backend
Confirme o formato da URL: ws://localhost:8001/api/v1/...

Onde as saídas do módulo são armazenadas?

Módulo	Caminho de Saída
Resolver	`data/user/solve/solve_YYYYMMDD_HHMMSS/`
Questão	`data/user/question/question_YYYYMMDD_HHMMSS/`
Pesquisa	`data/user/research/reports/`
Co-Writer	`data/user/co-writer/`
Caderno	`data/user/notebook/`
Guia	`data/user/guide/session_{session_id}.json`
Logs	`data/user/logs/`

Como adicionar uma nova base de conhecimento?

Interface Web

Visite http://localhost:{frontend_port}/knowledge
Clique em "New Knowledge Base"
Digite o nome da base de conhecimento
Faça upload de documentos PDF/TXT/MD
O sistema processará os documentos em segundo plano

CLI

python -m src.knowledge.start_kb init <kb_name> --docs <pdf_path>

Como adicionar documentos incrementalmente a uma BC existente?

CLI (Recomendado)

python -m src.knowledge.add_documents <kb_name> --docs <new_document.pdf>

Benefícios

Processa apenas novos documentos, economiza tempo e custo da API
Fusão automática com o grafo de conhecimento existente
Preserva todos os dados existentes

Erro uvloop.Loop ao extrair elementos numerados?

Problema

Ao inicializar uma base de conhecimento, você pode encontrar este erro:

ValueError: Can't patch loop of type <class 'uvloop.Loop'>

Isso ocorre porque Uvicorn usa o loop de eventos uvloop por padrão, que é incompatível com nest_asyncio.

Solução

Use um dos seguintes métodos para extrair elementos numerados:

# Opção 1: Usar script shell (recomendado)
./scripts/extract_numbered_items.sh <kb_name>

# Opção 2: Comando Python direto
python src/knowledge/extract_numbered_items.py --kb <kb_name> --base-dir ./data/knowledge_bases

Isso extrairá elementos numerados (Definições, Teoremas, Equações, etc.) da sua base de conhecimento sem reinicializá-la.

📄 Licença

Este projeto está licenciado sob AGPL-3.0.

⭐ Histórico de Stars

🤝 Contribuição

Acolhemos contribuições da comunidade! Para garantir qualidade e consistência do código, siga as diretrizes abaixo.

Configuração de Desenvolvimento

Configuração dos Pre-commit Hooks

Este projeto usa pre-commit hooks para formatar automaticamente o código e verificar problemas antes de fazer commit.

Passo 1: Instalar pre-commit

# Usar pip
pip install pre-commit

# Ou usar conda
conda install -c conda-forge pre-commit

Passo 2: Instalar os hooks do Git

cd DeepTutor
pre-commit install

Passo 3: (Opcional) Executar verificações em todos os arquivos

pre-commit run --all-files

Sempre que você executar git commit, os pre-commit hooks executarão automaticamente:

Formatar o código Python com Ruff
Formatar o código frontend com Prettier
Verificar erros de sintaxe
Validar arquivos YAML/JSON
Detectar problemas de segurança potenciais

Ferramentas de Qualidade de Código

Ferramenta	Objetivo	Configuração
Ruff	Verificação e formatação do código Python	`pyproject.toml`
Prettier	Formatação do código frontend	`web/.prettierrc.json`
detect-secrets	Verificação de segurança	`.secrets.baseline`

Nota: O projeto usa Ruff format em vez de Black para evitar conflitos de formatação.

Comandos Comuns

# Commit normal (os hooks são executados automaticamente)
git commit -m "Sua mensagem de commit"

# Verificar manualmente todos os arquivos
pre-commit run --all-files

# Atualizar os hooks para as versões mais recentes
pre-commit autoupdate

# Ignorar os hooks (não recomendado, apenas para emergências)
git commit --no-verify -m "Correção de emergência"

Diretrizes de Contribuição

Fork e Clone: Faça fork do repositório e clone-o
Criar uma Branch: Crie uma branch de funcionalidade a partir de main
Instalar Pre-commit: Siga as etapas de configuração acima
Fazer Modificações: Escreva código seguindo o estilo do projeto
Testar: Certifique-se de que suas modificações funcionam corretamente
Commit: Os pre-commit hooks formatarão automaticamente seu código
Push e PR: Faça push para seu fork e crie uma Pull Request

Reportar Problemas

Use GitHub Issues para reportar bugs ou sugerir funcionalidades
Forneça informações detalhadas sobre o problema
Se for um bug, inclua as etapas para reproduzi-lo

❤️ Agradecemos a todos os nossos contribuidores por suas valiosas contribuições.

🔗 Projetos Relacionados

⚡ LightRAG	🎨 RAG-Anything	💻 DeepCode	🔬 AI-Researcher
RAG Simples e Rápido	RAG Multimodal	Assistente de Código IA	Automação de Pesquisa

Laboratório de Inteligência de Dados @ HKU

⭐ Siga-nos · 🐛 Reportar um bug · 💬 Discussões

✨ Obrigado por visitar DeepTutor!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DeepTutor: Seu Assistente Pessoal de Aprendizado

Características Principais do DeepTutor

📚 Q&A de Conhecimento de Documentos Massivos

🎨 Visualização de Aprendizado Interativo

🎯 Reforço de Conhecimento com Gerador de Problemas de Prática

🔍 Pesquisa Profunda e Geração de Ideias

📚 Q&A de Conhecimento de Documentos Massivos

🎨 Visualização de Aprendizado Interativo

🎯 Reforço de Conhecimento

🔍 Pesquisa Profunda e Geração de Ideias

🏗️ Sistema de Conhecimento Tudo-em-Um

📋 Tarefas Pendentes

🚀 Início Rápido

Passo 1: Pré-configuração

Passo 2: Escolha seu Método de Instalação

🐳 Implantação Docker

💻 Instalação Manual

URLs de Acesso

📂 Armazenamento de Dados

📖 Documentação dos Módulos

❓ Perguntas Frequentes

📄 Licença

⭐ Histórico de Stars

🤝 Contribuição

Configuração dos Pre-commit Hooks

Ferramentas de Qualidade de Código

Comandos Comuns

Diretrizes de Contribuição

Reportar Problemas

🔗 Projetos Relacionados

FilesExpand file tree

README_PT.md

Latest commit

History

README_PT.md

File metadata and controls

DeepTutor: Seu Assistente Pessoal de Aprendizado

Características Principais do DeepTutor

📚 Q&A de Conhecimento de Documentos Massivos

🎨 Visualização de Aprendizado Interativo

🎯 Reforço de Conhecimento com Gerador de Problemas de Prática

🔍 Pesquisa Profunda e Geração de Ideias

📚 Q&A de Conhecimento de Documentos Massivos

🎨 Visualização de Aprendizado Interativo

🎯 Reforço de Conhecimento

🔍 Pesquisa Profunda e Geração de Ideias

🏗️ Sistema de Conhecimento Tudo-em-Um

📋 Tarefas Pendentes

🚀 Início Rápido

Passo 1: Pré-configuração

Passo 2: Escolha seu Método de Instalação

🐳 Implantação Docker

💻 Instalação Manual

URLs de Acesso

📂 Armazenamento de Dados

📖 Documentação dos Módulos

❓ Perguntas Frequentes

📄 Licença

⭐ Histórico de Stars

🤝 Contribuição

Configuração dos Pre-commit Hooks

Ferramentas de Qualidade de Código

Comandos Comuns

Diretrizes de Contribuição

Reportar Problemas

🔗 Projetos Relacionados