PARTE II — INSTALAR E USAR

Ambiente virtual, GPU, Jupyter e os primeiros comandos.

8. O ambiente virtual

EM UMA FRASE — Uma pasta isolada com o Python e as bibliotecas deste projeto, para que ele não brigue com os outros.

8.1 · O que é, e por que usar

Quando você instala uma biblioteca Python, ela vai por padrão para a instalação do sistema — compartilhada por todos os projetos da máquina. Isso cria um problema previsível: o projeto A precisa da versão 1.2 de uma biblioteca, o projeto B precisa da 2.0, e instalar uma quebra a outra.

Um ambiente virtual é uma pasta isolada com sua própria cópia do Python e suas próprias bibliotecas. O que você instala nele não afeta mais nada na máquina.

ANALOGIA — É a diferença entre guardar as ferramentas de todos os serviços numa gaveta só, e ter uma caixa por serviço. Na gaveta comum, alguém sempre leva a chave que você precisava.

8.2 · Onde criar

Vamos usar como exemplo a pasta de trabalho do projeto:

C:\0_Desenvolvimento\CNPQ

8.3 · Criar e ativar (Windows PowerShell)

Passo 1 — vá até a pasta do projeto.

cd C:\0_Desenvolvimento\CNPQ

Passo 2 — crie o ambiente virtual.

python -m venv venv

Isso cria a subpasta venv dentro de C:\0_Desenvolvimento\CNPQ. Leva alguns segundos e só precisa ser feito uma vez.

Passo 3 — ative o ambiente.

.\venv\Scripts\Activate.ps1

CONFIRA — O prompt passa a exibir (venv) no início:
(venv) PS C:\0_Desenvolvimento\CNPQ>
Esse prefixo é a única confirmação visual de que você está dentro do ambiente. Se ele não aparecer, o ambiente não está ativo — e tudo o que você instalar irá para o Python do sistema.

8.4 · O erro mais comum no PowerShell

Na primeira ativação, é provável que apareça:

.\venv\Scripts\Activate.ps1 : O arquivo não pode ser carregado porque a
execução de scripts foi desabilitada neste sistema.

Não é um defeito do projeto. O Windows bloqueia a execução de scripts por padrão, como medida de segurança. A solução é liberar apenas para o seu usuário:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Responda S (ou Y) à confirmação e tente ativar de novo. RemoteSigned permite rodar scripts locais e exige assinatura apenas nos baixados da internet — é a configuração recomendada, e não desprotege a máquina.

Isso é feito uma vez por usuário, não a cada projeto.

8.5 · Outros ambientes

Prompt de Comando (CMD):

venv\Scripts\activate.bat

Linux ou macOS:

source venv/bin/activate

9. Instalar as bibliotecas

EM UMA FRASE — Instale tudo de uma vez, na ordem certa, e só depois gere o requirements.txt.

ATENÇÃO — Use sempre python -m pip, nunca pip sozinho.

pip sozinho pode apontar para o Python do sistema mesmo com o ambiente ativo, dependendo de como o PATH está configurado. O resultado é confuso: a instalação diz que deu certo, e o projeto não encontra a biblioteca. python -m pip usa o interpretador que está de fato ativo — sempre.

9.1 · O que cada biblioteca faz aqui

Antes de instalar, vale saber o que se está instalando. Nenhuma destas bibliotecas está no projeto por hábito: cada uma resolve um problema específico, e o manual indica onde ela é usada.

Obrigatórias — o pipeline não roda sem elas

Biblioteca	Para que serve neste projeto	Onde é usada
`torch` (PyTorch)	O motor de cálculo que roda o modelo de vetores. É ele que decide se o trabalho vai para a placa de vídeo ou para o processador.	`semantica/vetores.py`
`sentence-transformers`	A camada que carrega o modelo E5 e transforma texto em vetor com uma chamada só. Também traz o `CrossEncoder`, usado no desempate.	`vetores.py`, `reranker.py`
`pandas`	A tabela em memória. Todas as dez tabelas do currículo, os CSVs classificados e as contagens são objetos do pandas.	todo o pipeline
`numpy`	A matemática dos vetores: similaridade, top-K, ordenação. É o que torna viável comparar 500 mil textos com 295 categorias.	`vetores.py`, `classificador.py`
`pyarrow`	Lê e grava os arquivos `.parquet` — o formato em que ficam os dados completos, com tipos preservados.	`nucleo/arquivos.py`
`openpyxl`	Lê e grava os arquivos `.xlsx` — o dicionário de entrada e todos os relatórios em Excel.	`planilha.py`, `arquivos.py`

LEMBRE-SE — torchvision e torchaudio aparecem nos comandos de instalação, mas o pipeline não os usa. Eles vêm no mesmo comando porque o PyTorch é distribuído como um trio, e instalar os três juntos garante que as três versões sejam compatíveis entre si. Instalar só o torch também funciona; manter o trio evita conflito numa atualização futura.

Para trabalhar no notebook

Biblioteca	Para que serve	Quando instalar
`jupyter`	O ambiente de notebook em si — o servidor e a interface no navegador.	se você for usar o Jupyter (seção 11)
`ipykernel`	Registra o ambiente virtual como um kernel, para o notebook enxergar as bibliotecas do projeto. Sem ele o notebook usa o Python do sistema.	sempre, junto com o Jupyter

Opcionais — só para a descoberta de temas (seção 20.13)

Biblioteca	Para que serve	Consequência de não instalar
`umap-learn`	Reduz os vetores de mais de mil dimensões para cerca de dez, preservando a vizinhança. É o passo ① da descoberta.	a descoberta de temas não roda; o resto do pipeline funciona normalmente
`hdbscan`	Encontra grupos densos entre os itens `Indefinido`, e marca como ruído o que estiver espalhado. É o passo ②.	idem
`scikit-learn`	Fornece o cálculo de termos característicos (c-TF-IDF) que nomeia cada grupo encontrado. É o passo ③.	idem

Opcionais — só para redigir glosas com um modelo de nuvem (seção 12.5)

Biblioteca	Provedor	Quando instalar
`google-generativeai`	Google Gemini	só se `provedor = "google"`
`anthropic`	Anthropic Claude	só se `provedor = "anthropic"`
`openai`	OpenAI GPT	só se `provedor = "openai"`

Nenhuma delas é necessária para o padrão do projeto, que é o Ollama — e o Ollama não exige biblioteca Python nenhuma: o sistema fala com ele por HTTP, usando o urllib que já vem no Python.

NA PRÁTICA — Instalação mínima para classificar currículos: torch + sentence-transformers + pandas + numpy + pyarrow + openpyxl. Todo o resto é conveniência (notebook), exploração (descoberta) ou redação de glosas (nuvem).

O que vem junto sem você pedir. O sentence-transformers puxa como dependências o transformers e o huggingface_hub (baixam e executam o modelo), o tokenizers (parte o texto em pedaços que o modelo entende) e o safetensors (formato dos pesos do modelo). Você não os instala nem os chama diretamente — mas eles aparecem no requirements.txt, e agora não são um mistério.

9.2 · Ordem de instalação

A ordem importa em um ponto: o PyTorch deve ser instalado antes do sentence-transformers. Se você instalar na ordem inversa, o sentence-transformers puxa a versão de CPU do PyTorch como dependência, e ela sobrescreve a versão com GPU que você queria.

1º  PyTorch (com suporte a GPU)     ← primeiro, sempre
2º  Bibliotecas do pipeline
3º  Jupyter
4º  Opcionais (calibração e descoberta)
─────────────────────────────────────
5º  requirements.txt                 ← só no fim, com tudo instalado

9.3 · Passo 1 — PyTorch com suporte a GPU

Escolha um dos comandos abaixo, conforme o seu hardware.

NVIDIA (a maioria dos casos):

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

AMD no Windows (via DirectML):

python -m pip install torch torchvision torchaudio
python -m pip install torch-directml

AMD no Linux (via ROCm):

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0

Apple Silicon (M1/M2/M3):

python -m pip install torch torchvision torchaudio

Sem placa de vídeo (só processador):

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

ATENÇÃO — Se você não souber qual tem, abra o Gerenciador de Tarefas → Desempenho no Windows. As placas aparecem como “GPU 0”, “GPU 1”, com o nome do fabricante. Placas integradas Intel não servem para acelerar este trabalho; procure por NVIDIA ou AMD dedicada.

9.4 · Passo 2 — bibliotecas do pipeline

python -m pip install pandas numpy pyarrow openpyxl sentence-transformers

9.5 · Passo 3 — Jupyter

python -m pip install jupyter ipykernel

9.6 · Passo 4 — opcionais

Necessárias apenas para a calibração e a descoberta de temas:

python -m pip install scikit-learn umap-learn hdbscan

9.7 · Tudo de uma vez

Se preferir um bloco único, com a ordem já correta:

cd C:\0_Desenvolvimento\CNPQ
.\venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
python -m pip install pandas numpy pyarrow openpyxl sentence-transformers
python -m pip install jupyter ipykernel
python -m pip install scikit-learn umap-learn hdbscan

9.8 · Passo 5 — gerar o `requirements.txt`

Só depois de tudo instalado e verificado. Este arquivo registra exatamente quais bibliotecas e versões o projeto usa, e serve para reproduzir o mesmo ambiente em outra máquina.

python -m pip freeze > requirements.txt

ATENÇÃO — Gerar o requirements.txt cedo demais é um erro comum. Se você o gerar antes de instalar o PyTorch com GPU, ele congela a versão de CPU — e a máquina seguinte, ao restaurar o ambiente, herda o problema sem ninguém perceber.

Restaurar em outra máquina:

python -m pip install -r requirements.txt

ATENÇÃO — O requirements.txt gerado por pip freeze não preserva o --index-url do PyTorch. Numa máquina nova, instale o PyTorch primeiro, pelo comando da seção 9.3, e só depois rode o install -r.

9.9 · Desativar e recriar

deactivate

O prefixo (venv) desaparece e você volta ao Python do sistema.

Se algo der muito errado, a saída mais rápida é apagar e refazer. Nada de importante se perde: o ambiente virtual contém apenas bibliotecas, nunca o seu código nem os seus dados.

deactivate
Remove-Item -Recurse -Force venv
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
python -m pip install -r requirements.txt

ATENÇÃO — Nunca versione a pasta venv. Ela tem centenas de megabytes, é específica do sistema operacional e é inteiramente reconstruível a partir do requirements.txt. Se o projeto usar Git, inclua no .gitignore:
venv/
__pycache__/

10. Forçar o uso da GPU

EM UMA FRASE — A placa de vídeo torna o processamento de 10 a 50 vezes mais rápido, e a instalação errada faz tudo cair no processador sem avisar.

10.1 · Por que isso importa tanto

A etapa 2 é a mais demorada do pipeline, e o que ela faz — converter texto em vetores — é exatamente o tipo de cálculo em que uma placa de vídeo é muitas vezes mais rápida que um processador.

A diferença não é de conforto, é de viabilidade:

Dispositivo	10 mil currículos	100 mil currículos
GPU dedicada	minutos a poucas horas	horas
Processador (CPU)	horas	dias

ATENÇÃO — O modo de falha é silencioso. Se o PyTorch instalado for a versão de CPU, ou se o driver estiver desatualizado, a biblioteca simplesmente usa o processador. Não há erro, não há aviso. A pessoa conclui que “o modelo é lento assim” e espera seis horas pelo que levaria vinte minutos.

É por isso que a checagem abaixo não é opcional.

10.2 · Confira se a GPU está sendo vista

Com o ambiente ativo, rode:

python -c "import torch; print('GPU disponível:', torch.cuda.is_available()); print('Placa:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'nenhuma')"

Resultado desejado:

GPU disponível: True
Placa: NVIDIA GeForce RTX 4070

Se aparecer False:

Causa provável	Solução
PyTorch de CPU instalado	Reinstale pelo comando da seção 9.3, com o `--index-url` correto
Driver da placa desatualizado	Atualize pelo site do fabricante
Placa integrada Intel apenas	Não há aceleração possível; use `dispositivo = "cpu"`
Ambiente virtual errado	Confira o `(venv)` no prompt

10.3 · Forçar no pipeline

O sistema tem um parâmetro dedicado em config.py:

dispositivo: str = "auto"

Valor	Efeito
`"auto"`	Descobre sozinho: usa GPU se houver, processador se não
`"cuda"`	Força GPU NVIDIA — ou AMD no Linux, via ROCm
`"mps"`	Força GPU Apple Silicon
`"directml"`	Força GPU AMD/Intel no Windows
`"cpu"`	Força processador

ATENÇÃO — Forçar é melhor que confiar. Com "auto", uma instalação errada cai no processador em silêncio. Com "cuda" explícito, você recebe um erro claro se a GPU não estiver disponível — o que é infinitamente preferível a uma espera inexplicável.

Em produção, deixe explícito.

Também é possível definir sem editar o arquivo:

$env:LATTES_DISPOSITIVO = "cuda"

10.4 · Confirme na execução

O pipeline anuncia onde está rodando, logo ao carregar o modelo:

🧠 Carregando modelo vetorial: intfloat/multilingual-e5-large-instruct
⚡ Dispositivo: GPU · NVIDIA GeForce RTX 4070 · 12.0 GB

Se aparecer:

⚡ Dispositivo: PROCESSADOR (CPU) — muito mais lento; confira a instalação do PyTorch

…interrompa e volte à seção 10.2. Vale muito mais gastar cinco minutos ali do que descobrir o problema no fim de uma execução longa.

CONFIRA — O comando python pipeline.py --pre-voo também mostra o dispositivo detectado, antes de processar qualquer coisa. É o primeiro comando a rodar em qualquer máquina nova.

10.5 · Se a memória da placa estourar

Erro típico:

torch.cuda.OutOfMemoryError: CUDA out of memory

Significa que o lote é grande demais para a sua placa. Reduza em config.py:

lote: int = 16     # ou 8, em placas de 4 GB

O resultado da classificação é idêntico com qualquer valor de lote — muda apenas a velocidade e o consumo de memória.

11. Usar com Jupyter Notebook

EM UMA FRASE — O ambiente virtual precisa ser registrado como kernel para o Jupyter enxergá-lo.

11.1 · Registrar o kernel

Com o ambiente ativo:

python -m pip install ipykernel
python -m ipykernel install --user --name lattes --display-name "Python (lattes)"

--name lattes é o identificador interno.
--display-name "Python (lattes)" é o nome que aparece na lista.

Isso é feito uma vez.

11.2 · Abrir o Jupyter

cd C:\0_Desenvolvimento\CNPQ
.\venv\Scripts\Activate.ps1
jupyter notebook

11.3 · Selecionar o kernel

Ferramenta	Como
Jupyter Notebook	Menu Kernel → Change kernel → Python (lattes)
JupyterLab	Clique no nome do kernel, no canto superior direito
VS Code	Clique em Select Kernel, no alto à direita, e escolha o interpretador dentro de `C:\0_Desenvolvimento\CNPQ\venv`

11.4 · Conferir se o kernel certo está ativo

CONFIRA — Este é o teste que resolve a maior parte da confusão. Rode numa célula:
import sys
print(sys.executable)
Resultado esperado:
C:\0_Desenvolvimento\CNPQ\venv\Scripts\python.exe

Se aparecer outro caminho — algo como C:\Python311\python.exe ou um caminho com Anaconda —, o notebook está usando o Python do sistema. As bibliotecas instaladas no venv não estarão disponíveis, e o sintoma será um ModuleNotFoundError em algo que você tem certeza de ter instalado.

A causa quase sempre é uma destas duas: o kernel selecionado está errado (troque no menu), ou o Jupyter foi aberto sem o ambiente ativo (feche, ative e abra de novo).

11.5 · Conferir a GPU dentro do notebook

import torch
print("GPU disponível:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("Placa:", torch.cuda.get_device_name(0))

11.6 · A célula de abertura — sempre a primeira

Todo notebook deste projeto começa com a mesma célula. Ela ensina o Python onde o pipeline mora e confirma que a configuração resolveu certo.

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

from config import CFG
print("domínio ativo:", CFG.dominio)
print(CFG.caminhos.como_texto())

O r antes das aspas (raw string) faz a contrabarra ser literal. Sem ele, "\0" viraria o caractere nulo e o caminho quebraria em silêncio — erro clássico no Windows.

CONFIRA — Se esta célula falhar com ModuleNotFoundError: config, o caminho está errado: aponte para a pasta que contém config.py, não para a pasta acima dela.

11.7 · Executar o pipeline pelo notebook

Tudo de uma vez — o equivalente exato a python pipeline.py:

import pipeline
pipeline.executar()

Com dados simulados, para testar a instalação:

pipeline.executar(demonstracao=300)

Uma etapa só:

pipeline.executar(etapas=["classificacao"])

Silenciar a saída detalhada (útil quando o log polui o notebook):

pipeline.executar(verboso=False)

LEMBRE-SE — pipeline.executar() é literalmente a mesma função que o comando de terminal chama. Não existe “modo notebook” e “modo terminal”: existe uma função, chamada de dois lugares. Os arquivos gravados, o cache e os relatórios são idênticos.

11.8 · Executar etapa por etapa, com o resultado na mão

É aqui que o notebook ganha do terminal. Rodando etapa a etapa, cada resultado intermediário fica em memória, pronto para ser inspecionado antes de seguir.

Etapa 1 — ingestão

from etapas import e01_ingestao

e01_ingestao.executar()                       # lê 1_ENTRADA e grava 2_CURRICULOS
tabelas = e01_ingestao.carregar_curriculos()  # devolve as dez tabelas

for nome, df in tabelas.items():
    print(f"{nome:16s} {len(df):>8,} linha(s)")

tabelas["producao_tec"].head()

Etapa 2 — classificação

import pipeline
from etapas import e02_classificacao

taxonomias, dominio = pipeline.carregar_taxonomias(CFG.dominio)
codificador, classificador = pipeline.montar_motor()

classificados = e02_classificacao.executar(
    tabelas, taxonomias, dominio, classificador)

# inspecionar um bloco específico
df = classificados["producao_tecnica"]
df[["texto", "Setor_PRODUCAO_TECNICA",
    "CONFIANCA_Setor_PRODUCAO_TECNICA"]].head(10)

Etapa 3 — quantificação

from etapas import e03_quantificacao

quantificacao = e03_quantificacao.executar(
    tabelas, classificados, taxonomias, dominio)

quantificacao.head()

Etapa 4 — vetorização

from etapas import e04_vetorizacao

base = e04_vetorizacao.executar(tabelas, quantificacao, codificador)
base.columns.tolist()

ATENÇÃO — A ordem importa e as etapas dependem umas das outras: a 2 precisa das tabelas da 1, a 3 precisa dos classificados da 2, a 4 precisa da quantificacao da 3 e do mesmo codificador usado na 2. Rodar uma célula fora de ordem produz NameError — que é o comportamento desejável, porque o erro aparece na hora, e não como um resultado silenciosamente errado.

11.9 · A tabela de equivalências — terminal ↔︎ notebook

No terminal (PowerShell)	No notebook (Python)
`python pipeline.py`	`pipeline.executar()`
`python pipeline.py --demonstracao 300`	`pipeline.executar(demonstracao=300)`
`python pipeline.py --etapas classificacao`	`pipeline.executar(etapas=["classificacao"])`
`python pipeline.py --config`	`print(CFG.caminhos.como_texto())`
`python pipeline.py --pre-voo`	`pipeline.pre_voo()`
`python pipeline.py --dominios`	`import dominios; dominios.listar()`
`python pipeline.py --dominio saude`	`CFG.dominio = "saude"` antes de executar
`python testes/test_integracao.py`	`!python testes/test_integracao.py`
`python -m ingestao.adaptadores amostra.xml`	`from ingestao import adaptadores`
`python ferramentas/construir_glosas.py --simular`	ver 13.5

NA PRÁTICA — A exclamação (!) no início de uma célula manda a linha para o terminal do sistema, sem sair do notebook. Serve para qualquer comando — !ollama list, !python -m pip install ..., !dir. É a saída mais rápida quando não existe equivalente em Python.

11.10 · Mudar parâmetros sem editar o `config.py`

No notebook dá para experimentar um valor e rodar de novo, sem tocar em arquivo:

CFG.semantica.limiar_curto = 0.74    # mais permissivo
CFG.semantica.margem = 0.03          # mais itens marcados como ambíguos
CFG.semantica.reranker_ativo = False # desliga o desempate

pipeline.executar(etapas=["classificacao"])

ATENÇÃO — Duas consequências que confundem quem não sabe delas. Primeira: mudar limiar, margem ou reranker altera a assinatura do eixo, e a classificação é refeita sozinha — não é preciso apagar cache nenhum. Segunda: a mudança vale só até o notebook ser reiniciado. Ela não é gravada em config.py. Isso é uma vantagem enquanto se está calibrando e uma armadilha quando se esquece: o valor que ficou bom precisa ser copiado para o config.py à mão, senão a próxima execução pelo terminal usa o valor antigo.

11.11 · Armadilhas próprias do notebook

O módulo alterado não recarrega sozinho. Se você editar blocos.py ou config.py com o notebook aberto, o Python continua usando a versão que já estava na memória. A saída limpa é ligar o recarregamento automático, na primeira célula:

%load_ext autoreload
%autoreload 2

Sem isso, a alternativa é reiniciar o kernel (Kernel → Restart) e rodar tudo de novo.

O modelo ocupa a memória da placa e não devolve. Depois de uma etapa 2, o modelo de vetores continua carregado. Se você for rodar o Ollama na mesma placa, libere antes:

codificador.descarregar()

A ordem de execução das células não é a ordem da tela. Uma célula rodada, apagada e reescrita continua tendo efeito na memória. Ao terminar uma investigação, rode Kernel → Restart & Run All para confirmar que o notebook funciona de cima para baixo.

A barra de progresso polui. Em lotes grandes, passe verboso=False ou use pipeline.executar(verboso=False).

11.12 · Um notebook mínimo, do zero ao resultado

Cole estas cinco células num notebook novo e você tem o pipeline inteiro rodando:

# ── célula 1 · abertura ────────────────────────────────
%load_ext autoreload
%autoreload 2
import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")
from config import CFG
print(CFG.caminhos.como_texto())

# ── célula 2 · conferir o ambiente ─────────────────────
import pipeline
pipeline.pre_voo()

# ── célula 3 · rodar com dados simulados ───────────────
pipeline.executar(demonstracao=300)

# ── célula 4 · abrir o resultado ───────────────────────
import pandas as pd
q = pd.read_parquet(CFG.caminhos.resultados / "quantificacao.parquet")
q.head()

# ── célula 5 · ver a distribuição de um eixo ───────────
q["setor_industrial_predominante"].value_counts().head(10)

12. Instalar o Ollama e o modelo de linguagem

EM UMA FRASE — O Ollama roda um modelo de linguagem na sua máquina, de graça, sem que nenhum texto saia do computador.

12.1 · Para que ele serve aqui

O modelo de linguagem não classifica currículos. Ele é usado por uma única ferramenta: o assistente que redige as glosas do dicionário (seção 13).

ATENÇÃO — A separação é deliberada. Classificar precisa ser determinístico e auditável: mesmo texto, mesmo resultado, sempre. Um modelo de linguagem daria respostas ligeiramente diferentes a cada execução, e não haveria como explicar uma decisão a um comitê.

Redigir glosa é o oposto: é trabalho de texto, sem resposta única correta, e o resultado passa por revisão humana antes de valer.

12.2 · Instalar

Windows / macOS: baixe o instalador em https://ollama.com/download e execute. Ele se instala como serviço e sobe sozinho com o sistema.

Linux:

curl -fsSL https://ollama.com/install.sh | sh

CONFIRA — Abra um terminal novo e rode:
ollama --version
Se aparecer um número de versão, está instalado.

12.3 · Baixar o modelo

O padrão do projeto é o Gemma 2, do Google. Cerca de 5,4 GB.

ollama pull gemma2

Alternativas, conforme a sua máquina:

Modelo	Comando	Tamanho	Quando usar
Gemma 2	`ollama pull gemma2`	~5,4 GB	padrão — bom equilíbrio
Gemma 2 grande	`ollama pull gemma2:27b`	~16 GB	placa de 24 GB ou mais
Qwen 2.5	`ollama pull qwen2.5:14b`	~9 GB	forte em texto técnico
Gemma 4	`ollama pull gemma4:12b`	~8 GB	geração mais recente
Gemma 2 pequeno	`ollama pull gemma2:2b`	~1,6 GB	máquina modesta

ATENÇÃO — O modelo precisa caber na memória da placa de vídeo. Numa placa de 4 GB, o gemma2 padrão já fica apertado — se a resposta demorar demais ou falhar, use gemma2:2b. O Ollama também roda no processador, mas fica bem mais lento.

12.4 · Verificar se o Ollama está pronto

Três formas de conferir: pelo terminal, pelo notebook e pelo próprio sistema. Todas respondem à mesma pergunta — “o Ollama está no ar e o modelo que eu quero está baixado?”.

NO TERMINAL (PowerShell)

ollama --version               # está instalado?
ollama list                    # quais modelos estão baixados?
ollama run gemma2 "Diga olá"   # o modelo responde?

NO NOTEBOOK — forma rápida

A exclamação manda o comando para o terminal do sistema sem sair do notebook:

!ollama list

ATENÇÃO — Não use !ollama run gemma2 "Diga olá" no notebook. Esse comando abre uma sessão interativa, que fica esperando a próxima pergunta — e a célula trava, sem devolver o controle. Para testar a resposta do modelo pelo notebook, use uma das duas formas abaixo.

NO NOTEBOOK — a verificação que o próprio sistema faz

Esta é a melhor: usa exatamente o mesmo código que o assistente de glosas executa antes de trabalhar, e devolve a mesma mensagem de erro — já escrita para ser lida por quem vai resolver o problema.

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

from config import CFG
from ia.provedores import Ollama

provedor = Ollama(modelo=CFG.ia.modelo, url=CFG.ia.ollama_url)
ok, mensagem = provedor.disponivel()

print("✅" if ok else "❌", mensagem)

Saída quando está tudo certo:

✅ Ollama ativo · modelo 'gemma2' disponível

Saída quando o Ollama está rodando mas falta o modelo — repare que ele já entrega o comando da correção:

❌ O Ollama está rodando, mas o modelo 'gemma2' não foi baixado.
   Baixe com:  ollama pull gemma2
   Modelos presentes: llama3:latest

Saída quando o serviço não está no ar:

❌ Não consegui falar com o Ollama em http://localhost:11434.
   Confira se ele está instalado e rodando (veja o manual).
   Teste rápido:  ollama list

NO NOTEBOOK — testar a resposta do modelo de verdade

Se quiser ir além da checagem e ver o modelo escrever:

resposta = provedor.conversar(
    sistema="Você responde em uma frase curta, em português.",
    usuario="Diga olá.",
)
print(resposta)

A primeira chamada demora mais: o Ollama carrega o modelo na memória da placa. As seguintes são rápidas.

NO NOTEBOOK — perguntar direto ao serviço, sem o projeto

Útil para depurar quando nem o import está funcionando:

import json, urllib.request

with urllib.request.urlopen("http://localhost:11434/api/tags", timeout=5) as r:
    modelos = json.loads(r.read())["models"]

for m in modelos:
    print(f"{m['name']:24s} {m['size'] / 1e9:5.1f} GB")

Se esta célula levantar erro de conexão, o problema é o serviço do Ollama — não o Python, não o kernel, não o projeto.

CONFIRA — O assistente de glosas faz essa verificação sozinho, antes de qualquer trabalho, e diz exatamente o que falta:
🤖 Ollama ativo · modelo 'gemma2' disponível
Se algo estiver errado, ele mostra o comando exato para corrigir. Ou seja: rodar o assistente é, por si só, um teste do Ollama.

LEMBRE-SE — O Ollama é um serviço, não uma biblioteca Python. Ele roda fora do ambiente virtual, sobe junto com o sistema operacional e responde por HTTP na porta 11434. Por isso ele não aparece no pip list e não é afetado por recriar o venv.

12.5 · Se preferir usar um serviço de nuvem

O Ollama é o padrão porque é gratuito e privado. Mas modelos de nuvem são maiores e redigem melhor. O sistema aceita três:

Provedor	Modelo padrão	Chave (variável de ambiente)	Onde obter
Google	`gemini-2.0-flash`	`GOOGLE_API_KEY`	https://aistudio.google.com/apikey
Anthropic	`claude-sonnet-4-5`	`ANTHROPIC_API_KEY`	https://console.anthropic.com/settings/keys
OpenAI	`gpt-4o-mini`	`OPENAI_API_KEY`	https://platform.openai.com/api-keys

Instale a biblioteca do provedor escolhido:

python -m pip install google-generativeai    # Google
python -m pip install anthropic              # Anthropic
python -m pip install openai                 # OpenAI

Defina a chave. Só na sessão atual do PowerShell:

$env:ANTHROPIC_API_KEY = "sua-chave-aqui"

Permanentemente, para o seu usuário:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sua-chave", "User")

(Feche e reabra o PowerShell para a mudança valer.)

ATENÇÃO — Nunca escreva a chave dentro de um arquivo do projeto. Chave em código vaza no primeiro git push, e chave vazada é chave usada por outra pessoa, na sua conta. O sistema lê as chaves exclusivamente de variáveis de ambiente, e não há como configurá-las de outro jeito — isso é proposital.

Escolha o provedor em config.py:

provedor: str = "anthropic"      # ollama | google | anthropic | openai
modelo:   str = "claude-sonnet-4-5"

Ou, sem editar arquivo:

python ferramentas/construir_glosas.py --provedor anthropic

LEMBRE-SE — Serviços de nuvem cobram por uso e enviam o texto para fora da sua máquina. Se a base contiver dado sensível, ou se houver restrição institucional de sigilo, use o Ollama.

13. O assistente de glosas

EM UMA FRASE — Ele escreve o rascunho de cada glosa; você revisa e aprova. O que você aprova, ele nunca mais toca.

13.1 · O que ele faz, e o que não faz

Faz: percorre o dicionário, monta uma instrução técnica para cada categoria — incluindo as categorias irmãs do mesmo agrupador — e pede ao modelo uma glosa escrita de forma contrastiva.

Não faz: substituir a curadoria humana. Ele produz um rascunho qualificado, o que reduz muito o trabalho de escrever do zero. A revisão continua sendo o passo que determina a qualidade final.

ANALOGIA — É a diferença entre receber uma minuta e receber uma folha em branco. A minuta acelera; ela não decide.

13.2 · A regra inviolável

ATENÇÃO — Categoria com revisado = SIM nunca é alterada. Nem com --aprimorar, nem com qualquer outra opção.

O motivo é de confiança: se o script pudesse sobrescrever o trabalho de revisão, ninguém o usaria. Uma tarde de curadoria apagada por engano custa mais do que toda a automação economiza.

Para reescrever uma glosa já revisada, mude revisado para NAO na planilha. É um ato deliberado e visível.

13.3 · Por que o assistente recebe as categorias irmãs

Esta é a decisão de projeto que mais afeta a qualidade do resultado.

Uma glosa escrita no vácuo sai genérica — não por incapacidade do modelo, mas por falta de informação. Ele não tem como saber de que precisa se distinguir.

O assistente entrega, junto com o pedido, todas as categorias do mesmo agrupador com suas glosas atuais. O modelo então enxerga a vizinhança e consegue escrever a fronteira.

NA PRÁTICA — Ao redigir «Metalurgia e Siderurgia», o assistente informa que existem «Mineração e Beneficiamento Mineral» e «Metalmecânica e Bens de Capital» no mesmo grupo. A glosa resultante diz onde uma termina e a outra começa — que é exatamente o que separa os vetores.

Passamos apenas as irmãs do mesmo agrupador porque é ali que a confusão acontece. Ninguém confunde «Metalurgia» com «Farmacêutica»; confunde-se «Metalurgia» com «Metalmecânica».

13.4 · Como usar — no terminal (PowerShell)

Fluxo recomendado — não pule os dois primeiros passos:

# 1. Ver o que seria feito, sem alterar nada
python ferramentas/construir_glosas.py --simular

# 2. Testar a qualidade num eixo só, com poucas categorias
python ferramentas/construir_glosas.py --taxonomia setor_industrial --limite 3

# 3. Se gostou do resultado, rodar completo
python ferramentas/construir_glosas.py

# 4. Revisar na planilha e marcar revisado = SIM nas aprovadas

# 5. Rodar de novo — as aprovadas ficam intocadas
python ferramentas/construir_glosas.py --aprimorar

Todas as opções:

Opção	O que faz
`--simular`	Mostra o que seria feito; não altera nada
`--aprimorar`	Reescreve também as que já têm glosa (e não foram revisadas)
`--taxonomia <nome>`	Limita a um eixo
`--limite <n>`	Processa no máximo N categorias
`--provedor <nome>`	`ollama` · `google` · `anthropic` · `openai`
`--modelo <nome>`	Sobrepõe o modelo do `config.py`
`--dominio <nome>`	Trabalha noutra área

13.5 · Como usar — no notebook

O assistente é um script de linha de comando, e por isso tem duas formas de ser chamado do notebook. A primeira é a mais simples; a segunda dá controle e devolve o resultado em memória.

Forma 1 — chamar o script pelo terminal, sem sair do notebook

Basta pôr a exclamação na frente. É o mesmo comando da seção 13.4, com o mesmo resultado:

!python ferramentas/construir_glosas.py --simular
!python ferramentas/construir_glosas.py --taxonomia setor_industrial --limite 3
!python ferramentas/construir_glosas.py --aprimorar

ATENÇÃO — O ! executa a partir da pasta em que o notebook foi aberto, não da pasta do projeto. Se der No such file or directory, confirme onde você está com !cd (Windows) ou passe o caminho completo: !python C:\0_Desenvolvimento\CNPQ\lattes_pipeline\ferramentas\construir_glosas.py --simular.

Forma 2 — chamar a função Python diretamente

Aqui você monta as opções como um objeto e chama a mesma função executar() que a linha de comando chama. A vantagem é poder mudar um parâmetro e repetir a célula, sem redigitar o comando inteiro:

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

from argparse import Namespace
from ferramentas import construir_glosas
from config import CFG

opcoes = Namespace(
    dominio=CFG.dominio,      # "industria"
    provedor="",              # "" = usa o do config.py
    modelo="",                # "" = usa o do config.py
    taxonomia="setor_industrial",
    limite=3,
    aprimorar=False,
    simular=True,             # ⬅️ comece SEMPRE por aqui
)

construir_glosas.executar(opcoes)

Para valer de verdade, troque simular=True por simular=False. Para reescrever as glosas que já existem e ainda não foram revisadas, aprimorar=True.

LEMBRE-SE — A regra inviolável da seção 13.2 vale igual nos dois modos: categoria com revisado = SIM nunca é alterada, nem pelo terminal, nem pelo notebook, nem com --aprimorar.

Conferir o resultado sem sair do notebook

Depois de rodar, o relatório e o dicionário podem ser abertos ali mesmo:

import pandas as pd

# as glosas que a validação automática marcou como frágeis
rel = pd.read_excel(CFG.caminhos.relatorios / "glosas_geradas.xlsx",
                    sheet_name="REVISAR_PRIMEIRO")
rel.head(20)

# o dicionário atualizado
import dominios
dic = pd.read_excel(dominios.caminho_dicionario(CFG.dominio))
dic[dic["taxonomia"] == "setor_industrial"][["nivel2", "glosa", "revisado"]]

NA PRÁTICA — O ciclo de curadoria fica bom no notebook: rodar com --limite 3, ler as três glosas na tela, ajustar o prompt em ia/prompts.py, recarregar (%autoreload 2 cuida disso) e rodar de novo. Só quando o padrão agradar é que se roda o dicionário inteiro.

13.6 · O que ele grava

Onde	O quê
O dicionário	glosa e exemplares novos
`origem`	`ia:<modelo>` — a procedência fica registrada
`revisado`	`NAO` — sempre; nada gerado por máquina nasce aprovado
Backup	cópia do dicionário anterior, com a data no nome
`5_RELATORIOS/glosas_geradas.xlsx`	o antes e o depois de cada glosa

CONFIRA — O relatório tem três abas. Comece pela REVISAR_PRIMEIRO: são as glosas que a validação automática apontou como frágeis. Se o tempo for curto, revise só essas.

13.7 · A validação automática

Antes de gravar, o assistente confere cada glosa recebida:

Verificação	Por quê
Entre 25 e 55 palavras	Curta não dá sinal; longa dilui o foco
Cita alguma categoria irmã	É o contraste que separa os vetores
Não começa com metalinguagem	“Esta categoria abrange…” não carrega significado
Não repete o rótulo no início	Redundante — o rótulo já entra separadamente
Ao menos 4 exemplares	Termos de busca reforçam o vetor

LEMBRE-SE — Os avisos não impedem a gravação. Eles vão para o relatório, sinalizando o que a revisão humana deve olhar primeiro. Só glosa vazia é descartada.

13.8 · Se a qualidade não agradar

Em ordem de eficácia:

Troque o modelo. gemma2:27b ou um provedor de nuvem redigem visivelmente melhor que modelos pequenos.
Escreva você mesmo 2 ou 3 glosas exemplares do domínio e marque-as como revisado = SIM. Elas passam a ser exibidas como irmãs, e o modelo imita o padrão.
Ajuste o prompt em ia/prompts.py. É o único lugar que define o estilo — mudar ali muda todas as glosas seguintes.

14. Primeira execução

EM UMA FRASE — Dois comandos: um confere o ambiente, o outro roda tudo com dados simulados. Se os dois passarem, a instalação está correta.

14.1 · Os dois comandos de estreia

NO TERMINAL (PowerShell)

# 1. Confira o ambiente. Ele diz exatamente o que falta.
python pipeline.py --pre-voo

# 2. Rode com dados simulados, para ver tudo funcionando.
python pipeline.py --demonstracao 300

NO NOTEBOOK

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

import pipeline
pipeline.pre_voo()                    # 1. confere o ambiente
pipeline.executar(demonstracao=300)   # 2. roda com dados simulados

Se os dois funcionarem, a instalação está correta.

Na primeira execução, dois modelos são baixados automaticamente: o de vetores (~2 GB) e o de desempate (~2,2 GB). Depois disso, o sistema funciona inteiramente offline — nenhum currículo sai da sua máquina.

CONFIRA — O --pre-voo é o primeiro comando a rodar em qualquer máquina nova. Ele confere caminhos, dicionário, dados de entrada e bibliotecas, mostra o dispositivo detectado (GPU ou processador) e sai — sem processar nada. Cinco segundos ali evitam descobrir um problema no fim de uma execução de seis horas.

14.2 · Com dados reais

NO TERMINAL (PowerShell)

# 1. Deposite os arquivos do Lattes na pasta de entrada.
#    A pasta é mostrada por: python pipeline.py --config

# 2. Rode.
python pipeline.py

# 3. Confira o primeiro relatório antes de qualquer coisa.
#    5_RELATORIOS\1_ingestao.xlsx

NO NOTEBOOK

from config import CFG
print("deposite os arquivos em:", CFG.caminhos.entrada)

import pipeline
pipeline.executar()

# conferir o primeiro relatório sem sair do notebook
import pandas as pd
pd.read_excel(CFG.caminhos.relatorios / "1_ingestao.xlsx",
              sheet_name="RESUMO")

ATENÇÃO — Confira o relatório da etapa 1 antes de olhar qualquer resultado de classificação. Se uma tabela veio vazia porque o caminho de tag mudou, tudo o que vier depois estará incompleto — e o defeito é muito mais barato de corrigir agora do que depois de uma execução completa. Ver a seção 24.

15. Comandos e arquivos

15.1 · Todos os comandos

Comando	O que faz
`python pipeline.py`	Roda as quatro etapas
`python pipeline.py --demonstracao 300`	Roda com 300 currículos simulados
`python pipeline.py --etapas classificacao`	Roda só uma etapa
`python pipeline.py --pre-voo`	Confere o ambiente e sai
`python pipeline.py --config`	Mostra caminhos e parâmetros
`python pipeline.py --dominios`	Lista as áreas disponíveis
`python pipeline.py --dominio saude`	Usa outra área nesta execução
`python testes/test_integracao.py`	Bateria completa de verificação
`python -m ingestao.adaptadores <arq>`	Inspeciona uma amostra de dados

Os mesmos comandos, no notebook. A tabela completa de equivalências está em 11.9; esta é a versão curta:

No terminal	No notebook
`python pipeline.py`	`pipeline.executar()`
`python pipeline.py --demonstracao 300`	`pipeline.executar(demonstracao=300)`
`python pipeline.py --etapas classificacao`	`pipeline.executar(etapas=["classificacao"])`
`python pipeline.py --pre-voo`	`pipeline.pre_voo()`
`python pipeline.py --config`	`print(CFG.caminhos.como_texto())`
`python pipeline.py --dominios`	`import dominios; dominios.listar()`
`python pipeline.py --dominio saude`	`CFG.dominio = "saude"` antes de executar
`python testes/test_integracao.py`	`!python testes/test_integracao.py`

15.2 · Onde ficam os arquivos

raiz do projeto/
├── 1_ENTRADA/          ← você deposita os dados aqui
├── 2_CURRICULOS/          etapa 1: tabelas padronizadas
├── 3_CLASSIFICADO/        etapa 2: currículos com rótulos
├── 4_RESULTADOS/          etapas 3 e 4: contagens e vetores
├── 5_RELATORIOS/          relatórios em Excel, para leitura humana
└── _trabalho/             cache e registros (pode apagar; será refeito)

A pasta raiz é definida em config.py, na função _raiz_padrao(). Também pode ser trocada pela variável de ambiente LATTES_RAIZ.

15.3 · Os dois formatos em `4_RESULTADOS`

Formato	Para quê
`.parquet`	O dado completo. Preserva tipos, é compacto e rápido. É o que outras ferramentas devem consumir.
`.xlsx`	Visualização humana. Para abrir, conferir, filtrar e mostrar a alguém.

As planilhas são limitadas a 100.000 linhas. Não é o limite do Excel (1.048.576) — é um teto de usabilidade: uma planilha com centenas de milhares de linhas trava ao abrir.

LEMBRE-SE — Quando há truncamento, o próprio arquivo traz uma aba AVISO informando quantas linhas existem no total. Assim ninguém analisa uma amostra pensando que é o universo.

O arquivo curriculos_vetorizados.xlsx sai sem a coluna de vetor — são centenas de números por linha, ilegíveis numa planilha. Quem precisa do vetor lê o Parquet.