⚙️ Instalação & Técnicas
O coração mão-na-massa do curso: instale o Ollama e rode seu primeiro modelo, ganhe uma interface tipo ChatGPT, aprenda a escolher GGUF e quantização, ajuste contexto e temperatura, sirva uma API local compatível com OpenAI e monte um RAG dos seus documentos.
Mapa da trilha
Conteúdo detalhado
🚀 Primeiro modelo rodando: Ollama
Do zero ao primeiro chat com fricção mínima — instalar, baixar e rodar um modelo local.
Runtime que baixa, gerencia e roda modelos locais com um comando; embrulha o llama.cpp.
É o caminho mais curto até o primeiro resultado.
Runtime, llama.cpp, multiplataforma.
No mac/Linux um script único; no Windows, um instalador gráfico.
Sem build nem dependência manual.
curl install, ollama --version.
O comando ollama run baixa o modelo e abre o prompt para você conversar.
Ver o modelo respondendo prova que o lab funciona.
ollama run, llama3.2, qwen2.5.
Comandos para baixar, listar, remover e ver o que está rodando.
Mantém o disco e a memória sob controle.
pull, list, rm, ps.
As tags :2b/:7b/:14b ligam o modelo à regra de memória da Trilha 2.
Escolher errado trava ou força swapping em disco.
Tags de tamanho, VRAM/RAM, começar pequeno.
Modelfile é a receita que define system prompt, parâmetros e modelo base.
Cria um assistente com personalidade sem programar.
Modelfile, SYSTEM, ollama create.
💬 Interface tipo ChatGPT: Open WebUI & LM Studio
Do terminal para o navegador: chat com histórico, multi-modelo e anexos.
Chat com histórico, troca de modelo e anexos, fora do terminal.
Aproxima o local da experiência do ChatGPT.
Histórico, multi-modelo, anexos.
Front-end que fala com Ollama ou qualquer API OpenAI-compatível, rodando local.
É a interface padrão da comunidade local.
Front-end, OpenAI-compatível, local.
Um comando docker run sobe a interface na porta 3000.
Instala isolado, sem sujar o sistema.
docker run, porta 3000, volume.
App que baixa GGUF e traz chat + servidor local embutido.
Caminho 100% gráfico para quem não quer terminal.
GGUF, servidor embutido, desktop.
Configurar a UI para o endpoint do Ollama e trocar de modelo.
É o elo entre a cara bonita e o motor.
Endpoint, seleção de modelo, system prompt na UI.
Múltiplos chats, RAG de documentos, perfis de prompt e usuários.
Transforma o brinquedo em ferramenta diária.
Múltiplos chats, RAG, perfis.
📦 Escolhendo e baixando o modelo certo: GGUF e quantização
Onde achar modelos, que formato baixar e qual quantização tem o melhor custo × qualidade.
Repositório central de modelos abertos, com um model card por modelo.
É de lá que sai quase tudo que você vai rodar.
Repositório, model card, modelos abertos.
GGUF é o formato empacotado para rodar via llama.cpp/Ollama em CPU/GPU.
Baixar o formato errado não roda no seu runtime.
GGUF, safetensors, GPTQ/AWQ.
Sufixos como Q4_K_M, Q5 e Q8 indicam quanto os pesos foram comprimidos.
Q4_K_M/Q5_K_M costumam ser o equilíbrio qualidade × tamanho.
Q4_K_M, Q5, Q8, ponto doce.
pull pela tag do Ollama, ou baixar o GGUF do HF e importar.
Cada caminho serve a um runtime e a um nível de controle.
ollama pull, GGUF do HF, ollama create.
Recapitula a regra de memória para escolher a quant pela VRAM/RAM.
Evita escolher um modelo que não cabe.
Regra de memória, fluxo de decisão, quant pela VRAM.
Conferir checksum e testar com um prompt-padrão, comparando quants.
Quant agressiva demais degrada a resposta.
Checksum, prompt-padrão, comparar quants.
🎛️ Parâmetros e qualidade: contexto, temperatura, offload
Os botões que mudam a resposta e a velocidade — e como diagnosticar quando algo trava.
num_ctx define quanto o modelo lê de uma vez; contexto longo custa memória (KV cache).
Aumentar sem critério estoura a memória.
num_ctx, KV cache, custo de memória.
Temperatura mede o quão aleatório/criativo é o texto; baixa = determinístico.
Cada tarefa pede uma receita (código = baixa, brainstorm = alta).
temperatura, top_p, top_k.
Define papel, formato e restrições da resposta.
É a alavanca mais barata de qualidade.
Papel, formato, restrições.
num_gpu define quantas camadas cabem na GPU; o resto vai pra CPU, mais lento.
Equilibrar offload é o que faz caber e acelerar.
num_gpu, camadas, GPU vs CPU.
O que acelera ou desacelera a geração, incluindo a quantização do KV cache.
Pequenos ajustes podem dobrar os tokens/s.
KV cache, batch, tokens/s.
Checklist de causas: modelo grande demais, quant agressiva, contexto enorme, swapping.
Resolver sozinho sem chutar no escuro.
OOM, quant, contexto, swapping.
🔌 Servindo via API local compatível com OpenAI
Transforme o modelo local num endpoint que seus apps, scripts e agentes consomem como OpenAI.
Expor o modelo local como se fosse a OpenAI para apps e scripts.
É o que conecta o modelo aos agentes da Trilha 4.
Endpoint, integração, reuso.
O Ollama serve em localhost:11434, com rotas nativas e /v1 OpenAI-compatível.
Saber a rota certa evita metade dos erros.
localhost:11434, /v1, rotas.
Um curl para /v1/chat/completions devolve a resposta em JSON.
Confirma que a API responde antes de escrever código.
curl, chat/completions, JSON.
O mesmo SDK da OpenAI apontado para o base_url local.
Reaproveita todo o ecossistema existente.
SDK OpenAI, base_url, api_key dummy.
stream:true para resposta em tempo real, rota de embeddings e roteamento por modelo.
Cobre os usos reais além do chat simples.
stream, embeddings, roteamento.
OLLAMA_HOST=0.0.0.0 + Tailscale para acessar de outra máquina, sem abrir à internet pública.
Acesso remoto sem deixar um buraco de segurança.
OLLAMA_HOST, tailnet, sem porta pública.
🧠 Embeddings, memória & RAG básico
Dê memória ao modelo: busque trechos relevantes dos seus documentos e responda com base neles.
Vetores que representam o significado de um texto; parecidos ficam perto no espaço.
É a base de toda busca por similaridade.
Vetor, similaridade, espaço semântico.
RAG (Retrieval-Augmented Generation) busca trechos relevantes e os dá de contexto ao modelo.
Responde sobre SEUS documentos sem retreinar.
RAG, retrieval, contexto.
Ingestão (chunk → embed → guardar) e consulta (embed da pergunta → buscar vizinhos → montar prompt).
Entender o fluxo é o que permite depurá-lo.
Chunk, embed, vizinhos.
Baixar um modelo de embedding pequeno e chamar a rota de embeddings via API.
Modelos de embedding rodam até em hardware budget.
nomic-embed-text, rota de embeddings, leve.
Um vector store (Chroma/FAISS/sqlite-vec) guarda os vetores para busca por similaridade.
É onde a memória do RAG vive.
Chroma, FAISS, sqlite-vec.
Ingerir um .txt, embedar, buscar e responder com o modelo local.
Fecha a trilha provando o ciclo completo.
Ingestão, busca, resposta verificável.