🎯 YouTube Comments Analyzer

Ferramenta de análise de satisfação de vídeos do YouTube através dos comentários. Coleta comentários com API do Youtube ou MCP Playwright, agrupa por similaridade semântica com RAG, analisa sentimento com LLM e gera relatórios detalhados com score de satisfação. Usando IA local (Ollama) ou na nuvem (OpenRouter).

📋 Índice

Visão Geral

O YouTube Analyzer automatiza a análise qualitativa de comentários de vídeos do YouTube. Em vez de ler centenas de comentários manualmente, a ferramenta:

Coleta os comentários via YouTube Data API v3
Filtra spam e comentários irrelevantes
Agrupa comentários semanticamente similares em clusters
Envia cada cluster para um LLM analisar sentimento, tópicos e intensidade
Calcula um score composto de satisfação (0–100)
Gera um relatório executivo em JSON ou Markdown

Casos de uso

Criadores de conteúdo que querem entender a recepção de seus vídeos
Analistas de marketing avaliando campanhas em vídeo
Pesquisadores estudando comportamento de audiência
Equipes de produto coletando feedback em vídeos de demonstração

Arquitetura

     YouTube URL
         │
         ▼
┌─────────────────┐
│ YouTubeCollector│  ← YouTube Data API v3 + cache SQLite / MCP Playwright
└────────┬────────┘
         │ comentários brutos
         ▼
┌─────────────────┐
│  CommentCleaner │  ← remove spam, filtra idioma, normaliza texto
└────────┬────────┘
         │ comentários limpos
         ▼
┌─────────────────┐
│    Embedder     │  ← paraphrase-multilingual-MiniLM-L12-v2
└────────┬────────┘
         │ vetores semânticos
         ▼
┌─────────────────┐
│ CommentClusterer│  ← KMeans ou HDBSCAN (scikit-learn)
└────────┬────────┘
         │ clusters de comentários
         ▼
┌─────────────────┐
│   RAGPipeline   │  ← FAISS — indexa metadados do vídeo
└────────┬────────┘
         │ contexto relevante
         ▼
┌─────────────────┐
│   LLMAnalyzer   │  ← Ollama (local) ou OpenRouter (nuvem)
└────────┬────────┘
         │ análises por cluster
         ▼
┌─────────────────┐
│   ScoreEngine   │  ← score composto ponderado
└────────┬────────┘
         │ score + breakdown
         ▼
┌─────────────────┐
│ ReportGenerator │  ← JSON ou Markdown
└─────────────────┘

Pré-requisitos

Python 3.10 ou superior
Chave da YouTube Data API v3
Habilitar MCP Playwright
Uma das opções de LLM:
- Ollama instalado localmente (ollama.com)
- OpenRouter com conta gratuita (openrouter.ai) — mais rápido, requer internet

Requisitos de hardware (Ollama local)

Modelo	RAM mínima	Velocidade estimada (CPU)
tinyllama	1 GB	~30s por cluster
phi3:latest	3.5 GB	~2min por cluster
llama3.1:8b	6 GB	~3min por cluster

Com OpenRouter não há requisito de hardware além de conexão com a internet.

Instalação

# 1. Clone o repositório
git clone https://github.com/etrapp/youtube-comments-analyzer.git
cd youtube-comments-analyzer

# 2. Crie e ative o ambiente virtual
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

# 3. Atualize o pip
python -m pip install --upgrade pip

# 4. Instale as dependências
pip install -r requirements.txt

# 5. Instale o browser para o Playwright (coleta alternativa)
python -m playwright install chromium

Se usar Ollama (backend local)

# Instale o Ollama em ollama.com e depois baixe um modelo
ollama pull phi3:latest

# Verifique se está rodando
ollama serve

Configuração

Crie o arquivo .env na raiz do projeto:

# ── YouTube ──────────────────────────────────────────────────
YOUTUBE_API_KEY=sua_chave_youtube_aqui

# ── LLM Backend ──────────────────────────────────────────────
# Opções: "ollama" ou "openrouter"
LLM_BACKEND=openrouter

# ── Ollama (se LLM_BACKEND=ollama) ───────────────────────────
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=phi3:latest
OLLAMA_EMBED_MODEL=nomic-embed-text

# ── OpenRouter (se LLM_BACKEND=openrouter) ───────────────────
# Cadastro gratuito em https://openrouter.ai/keys
OPENROUTER_API_KEY=sk-or-v1-sua_chave_aqui
OPENROUTER_MODEL=openai/gpt-oss-120b:free

# ── Outros ───────────────────────────────────────────────────
HF_HUB_DISABLE_SYMLINKS_WARNING=1

Obtendo a chave do YouTube

Acesse console.cloud.google.com
Crie um projeto e ative a YouTube Data API v3
Em Credenciais → Criar Credenciais → Chave de API, copie a chave

Obtendo a chave do OpenRouter

Cadastre-se em openrouter.ai
Vá em Keys → Create Key
Modelos com sufixo :free são gratuitos e sem necessidade de créditos

Como Usar

Interface de linha de comando

# Análise básica — imprime JSON no terminal
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID

# Relatório em Markdown salvo em arquivo
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID \
               --output markdown \
               --save relatorios/meu_video.md

# Forçar nova coleta ignorando o cache
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID --no-cache

# Usar HDBSCAN no lugar de KMeans para clusterização
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID \
               --cluster-method hdbscan

# Analisar comentários em qualquer idioma (sem filtro)
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID \
               --no-language-filter

# Especificar idioma diferente do português
python main.py --url https://www.youtube.com/watch?v=VIDEO_ID \
               --language en

# Iniciar o servidor da API REST
python main.py --serve

Referência de argumentos

Argumento	Padrão	Descrição
`--url`	obrigatório	URL ou ID do vídeo do YouTube
`--output`	`json`	Formato do relatório: `json` ou `markdown`
`--save`	`None`	Caminho para salvar o relatório
`--no-cache`	`False`	Ignora o cache e força nova coleta
`--cluster-method`	`kmeans`	Algoritmo de clusterização: `kmeans` ou `hdbscan`
`--language`	`pt`	Código do idioma dos comentários
`--no-language-filter`	`False`	Desativa o filtro de idioma
`--serve`	`False`	Inicia o servidor FastAPI

Backends de LLM

Ollama (local)

Roda completamente offline, sem custo por chamada, mas depende do hardware disponível. Ideal para uso frequente ou dados sensíveis.

LLM_BACKEND=ollama
OLLAMA_MODEL=phi3:latest

OpenRouter (nuvem)

Mais rápido e sem requisito de hardware. Modelos gratuitos disponíveis:

Modelo	Qualidade	Velocidade
`google/gemma-3-12b-it:free`	★★★★☆	Rápido
`meta-llama/llama-3.1-8b-instruct:free`	★★★★☆	Rápido
`mistralai/mistral-7b-instruct:free`	★★★☆☆	Muito rápido
`microsoft/phi-3-mini-128k-instruct:free`	★★★☆☆	Rápido

LLM_BACKEND=openrouter
OPENROUTER_MODEL=google/gemma-3-12b-it:free
OPENROUTER_API_KEY=sk-or-v1-...

Modelos gratuitos do OpenRouter têm limite de requisições por minuto. Se aparecer erro de rate limit, aguarde alguns segundos e tente novamente.

Estrutura do Projeto

youtube-comments-analyzer/
│
├── main.py                    # Ponto de entrada — CLI e servidor
│
├── config/
│   └── settings.py            # Configurações centralizadas via pydantic
│
├── collector/
│   ├── mcp_playwright.py      # Coleta de comentários via MCP (Playwright)
│   └── youtube_api.py         # Coleta de comentários e metadados via API
│
├── processor/
│   ├── cleaner.py             # Limpeza e filtro de comentários
│   ├── embedder.py            # Geração de embeddings semânticos
│   └── clusterer.py           # Agrupamento por KMeans ou HDBSCAN
│
├── analyzer/
│   ├── rag_pipeline.py        # Indexação e busca FAISS (RAG)
│   └── llm_analyzer.py        # Análise via Ollama ou OpenRouter
│
├── scorer/
│   └── score_engine.py        # Cálculo do score composto
│
├── reporter/
│   └── report_generator.py    # Geração de relatórios JSON e Markdown
│
├── api/
│   └── routes.py              # API REST com FastAPI
│
├── tests/
│   └── test_pipeline.py       # Testes unitários e de integração
│
├── data/
│   ├── cache/                 # Cache SQLite de comentários coletados
│   ├── vector_store/          # Índices FAISS por vídeo
│   └── logs/                  # Logs da aplicação
│
├── .env                       # Variáveis de ambiente (não versionar)
├── .env.example               # Exemplo de configuração
├── requirements.txt           # Dependências Python
└── README.md                  # Este arquivo

Pipeline de Análise

1. Coleta API / MCP

Busca até 500 comentários via YouTube Data API v3 ordenados por relevância. Resultados são armazenados em cache SQLite para evitar chamadas repetidas à API. Em caso de problemas com API do Youtube é utilizado o MCP do Playwright para coletar os comentários.

2. Limpeza

Remove comentários com menos de 15 caracteres, URLs suspeitas, repetição excessiva de caracteres e emojis isolados. Filtra pelo idioma configurado usando detecção automática.

3. Embeddings

Gera representações vetoriais de 384 dimensões usando o modelo paraphrase-multilingual-MiniLM-L12-v2, que suporta português e mais 50 idiomas.

4. Clusterização

Agrupa os vetores em 10 clusters (KMeans) ou número automático (HDBSCAN). Seleciona os 5 comentários mais próximos do centróide de cada cluster como representantes.

5. RAG

Indexa título, descrição e tags do vídeo no FAISS. Antes de cada chamada ao LLM, recupera o trecho de contexto mais relevante para o cluster.

6. Análise LLM

Envia os comentários representantes + contexto do vídeo para o LLM. Obtém sentimento, score, intensidade, ironia, tópicos e resumo de cada cluster.

7. Score

Calcula um score composto de 0 a 100 com quatro dimensões ponderadas:

Dimensão	Peso	O que mede
Sentimento	45%	Média ponderada do sentiment_score dos clusters
Engajamento	25%	Ratio likes/visualizações normalizado
Consistência	20%	Ausência de ironia e sentimentos contraditórios
Volume	10%	Taxa de comentários por visualização

8. Relatório

Consolida tudo em um documento estruturado com sumário executivo, detalhes por cluster, tópicos mais discutidos e recomendações.

Entendendo o Score

Faixa	Categoria	Interpretação
80 – 100	Excelente	Audiência muito satisfeita, alto engajamento positivo
60 – 79	Satisfatório	Boa recepção geral com pontos de melhoria
40 – 59	Mediano	Recepção mista, oportunidades claras de melhoria
20 – 39	Fraco	Predominância de críticas, revisão necessária
0 – 19	Crítico	Rejeição significativa da audiência

API REST

Inicie o servidor com:

python main.py --serve
# Documentação interativa em http://localhost:8000/docs

Endpoints

`POST /analyze`

Executa o pipeline completo de análise.

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "use_cache": true,
    "cluster_method": "kmeans",
    "filter_language": true,
    "target_language": "pt"
  }'

`GET /health`

Verifica se o serviço está no ar.

`GET /cache/{video_id}`

Consulta se um vídeo está em cache.

`DELETE /cache/{video_id}`

Remove o cache de um vídeo específico.

Exemplos de Output

Resumo no terminal

============================================================ Vídeo : por que eu migrei pro Cursor Score : 75.72/100 Categoria: Satisfatório

Breakdown do score

"score": {
  "final_score": 75.72,
  "category": "Satisfatório",
  "breakdown": {
    "sentiment": 57.09,
    "engagement": 100.0,
    "consistency": 90.0,
    "volume": 70.26
  }
}

Exemplo de cluster analisado

{
  "cluster_id": 6,
  "cluster_size": 30,
  "sentiment": "negativo",
  "sentiment_score": 0.95,
  "intensity": "alto",
  "irony_detected": false,
  "main_topics": ["custo do Cursor", "comparação com o Codex"],
  "negative_aspects": ["custo excessivo", "limitações com modelos novos"],
  "summary": "Comentários negativos sobre o alto custo e desvantagens em relação a alternativas."
}

Testes

# Rodar todos os testes
pytest tests/ -v

# Com cobertura de código
pytest tests/ -v --cov=. --cov-report=term-missing

# Apenas um módulo específico
pytest tests/test_pipeline.py::TestScoreEngine -v

Limitações Conhecidas

YouTube Data API: a cota gratuita permite ~100 vídeos analisados por dia. Comentários de vídeos muito populares (+10k comentários) são limitados a 500 por coleta.
Modelos gratuitos do OpenRouter: possuem limite de requisições por minuto e podem ser desativados sem aviso. Consulte openrouter.ai/models para ver quais estão ativos com o sufixo :free.
Ollama na CPU: modelos acima de 3B parâmetros ficam lentos sem GPU. Em máquinas com menos de 8 GB de RAM, use tinyllama ou prefira o OpenRouter.
Detecção de idioma: comentários muito curtos (menos de 20 caracteres) podem ser classificados incorretamente pelo detector de idioma.
Ironia e sarcasmo: modelos menores têm dificuldade com ironia fina, especialmente em gírias regionais do português brasileiro.

📝 Licença

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
analyzer		analyzer
api		api
collector		collector
config		config
images		images
processor		processor
reporter		reporter
scorer		scorer
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🎯 YouTube Comments Analyzer

📋 Índice

Visão Geral

Casos de uso

Arquitetura

Pré-requisitos

Requisitos de hardware (Ollama local)

Instalação

Se usar Ollama (backend local)

Configuração

Obtendo a chave do YouTube

Obtendo a chave do OpenRouter

Como Usar

Interface de linha de comando

Referência de argumentos

Backends de LLM

Ollama (local)

OpenRouter (nuvem)

Estrutura do Projeto

Pipeline de Análise

1. Coleta API / MCP

2. Limpeza

3. Embeddings

4. Clusterização

5. RAG

6. Análise LLM

7. Score

8. Relatório

Entendendo o Score

API REST

Endpoints

POST /analyze

GET /health

GET /cache/{video_id}

DELETE /cache/{video_id}

Exemplos de Output

Resumo no terminal

Breakdown do score

Exemplo de cluster analisado

Testes

Limitações Conhecidas

📝 Licença

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /analyze`

`GET /health`

`GET /cache/{video_id}`

`DELETE /cache/{video_id}`

Packages