A capacidade de executar modelos de IA generativa localmente é um marco fundamental para engenheiros e cientistas de dados. Diferente das soluções baseadas em nuvem (como as APIs proprietárias do ChatGPT, Claude ou Gemini), a execução local oferece privacidade de dados, redução de latência e controle total sobre o ciclo de vida do modelo.
Nesta seção, exploraremos o uso do Ollama, uma ferramenta de orquestração que simplifica o processo de download, configuração e execução de modelos de código aberto (Open Source).
O ponto de partida para o desenvolvimento técnico é o repositório oficial da disciplina. Este repositório atua como o hub de engenharia, contendo arquivos de configuração, scripts de diagnóstico e as instruções de instalação (README.md).
Nota Técnica: O arquivo
README.mdé dinâmico e deve ser consultado frequentemente para garantir que as dependências e versões dos modelos (como as variações do Llama e Gemma) estejam atualizadas de acordo com as especificações de hardware do seu sistema (Windows, macOS ou Linux).
O Ollama é uma ferramenta de interface de linha de comando (CLI) que gerencia modelos de IA localmente de forma eficiente e otimizada. Ele permite que modelos complexos sejam "empacotados" e executados com comandos simples, abstraindo a complexidade da gestão de pesos e tensores.
Após o download e instalação do binário do Ollama, a primeira interação ocorre via terminal ou prompt de comando.
Inicialização do Serviço:
ollama serveEste comando inicia o servidor local. Caso o endereço já esteja em uso, o sistema indicará que o serviço já está operacional no backend.
Verificação de Comandos:
ollamaExibe a lista de flags e subcomandos disponíveis (run, list, pull, etc.).
A escolha de um LLM deve ser pautada no equilíbrio entre capacidade cognitiva e disponibilidade de hardware (principalmente VRAM e memória RAM). O tamanho de um modelo é geralmente medido pelo número de parâmetros.
O Gemma, desenvolvido pelo Google, possui versões otimizadas para dispositivos locais. Para testes de baixa latência em hardware modesto, utilizamos a versão de 270 milhões de parâmetros.
ollama run gemma3:270mO Phi-3, da Microsoft, é um modelo altamente eficiente que demonstra como a arquitetura pode compensar o tamanho bruto. Com aproximadamente 3,8 bilhões de parâmetros, ele exige cerca de 2.2 GB de espaço em disco.
ollama run phi3Para aplicações que exigem maior robustez e raciocínio complexo, avançamos para modelos de grande escala, como a versão de 20 bilhões de parâmetros do GPT-OSS.
ollama run gpt-ossAtenção aos Requisitos: Modelos de 20B parâmetros ou superiores geralmente requerem um mínimo de 16 GB de RAM e aproximadamente 20 GB de espaço livre em disco para garantir uma inferência estável.
Uma vez carregado o modelo, o Ollama fornece uma interface de chat direta no terminal. A interação técnica envolve o envio de prompts e a análise da resposta gerada.
Comandos de Fluxo:
Ctrl + D (sai do chat e retorna ao prompt do sistema).ollama list.Ao transitar entre modelos (de Gemma para Phi-3 ou GPT-OSS), o engenheiro de IA deve observar a variação na qualidade do raciocínio e o tempo de resposta (tokens per second), fatores cruciais para a construção de produtos de IA de alta performance que serão abordados no decorrer deste curso.
Após consolidarmos a execução local de modelos via Ollama, o próximo passo na engenharia de IA é a transição da infraestrutura básica para a criação de produtos funcionais. Esta seção detalha a aplicação prática de modelos de código aberto e estabelece a trajetória técnica necessária para atingir a maestria no desenvolvimento de sistemas baseados em LLMs.
A execução de um modelo como o gpt-oss (ou variações de larga escala como o Llama 3) permite a implementação de sistemas especialistas sem dependência de APIs externas. Um caso de uso emblemático é o Tutor de Idiomas Reativo, onde o modelo assume uma persona específica e mantém o contexto da aprendizagem.
Para iniciar uma sessão de tutoria, utilizamos a interface de linha de comando para instanciar o modelo e definir suas diretrizes operacionais através de um system prompt implícito na conversa inicial:
# Inicialização do modelo de alta capacidade localmente
ollama run gpt-ossInteração do Engenheiro:
Oi. Estou tentando aprender espanhol. Sou um iniciante total. Por favor, tenha uma conversa comigo como meu tutor de espanhol.
O diferencial técnico de modelos avançados está na capacidade de manter contexto, adaptar o tom de resposta e estruturar uma saída coerente com o objetivo pedagógico definido no prompt. Em aplicações reais, esse comportamento é determinante para a experiência do usuário e para a previsibilidade do sistema.
Ao observar a saída de modelos de fronteira em ambiente local, notamos frequentemente sinais intermediários de processamento (muitas vezes destacados em metadados ou cores distintas no terminal) que ajudam a inferir a estratégia adotada pelo LLM:
Essa visibilidade parcial do processo de geração é útil para a depuração de aplicações, permitindo que o desenvolvedor ajuste os parâmetros de inferência para otimizar a precisão linguística e a latência.
O desenvolvimento moderno de IA não se limita ao modelo; ele depende de uma stack de ferramentas que garantem a escalabilidade e a observabilidade:
A convergência entre a visão comercial (aplicações reais como geração de atas de reunião ou portabilidade de código) e a técnica rigorosa (ajuste de pesos e tensores) é o que define o profissional competitivo no atual cenário da Inteligência Artificial Generativa.
O estabelecimento de um ambiente de desenvolvimento robusto é o primeiro marco crítico para um Engenheiro de IA. Diferente do desenvolvimento de software tradicional, o ciclo de vida de uma aplicação baseada em LLMs exige ferramentas que priorizem a latência mínima na gestão de dependências e a integração nativa com assistentes de codificação baseados em IA.
Para operar com modelos de fronteira, estruturamos o ambiente em cinco camadas fundamentais:
A escolha do Cursor como ambiente de desenvolvimento integrado (IDE) justifica-se por sua natureza AI-native. Sendo um fork do VS Code, ele permite que o modelo de linguagem indexe localmente o repositório, facilitando a compreensão de contextos complexos e a geração de código contextualizada.
uvO ecossistema Python frequentemente sofre com a fragmentação de gestores e fluxos de instalação. Introduzimos o uv, uma ferramenta extremamente veloz escrita em Rust, voltada para resolução de dependências, gestão de ambientes virtuais e controle de versões do interpretador Python.
.venv) de forma determinística e reprodutível.uvToda a interação técnica pode ser realizada via terminal integrado do Cursor, acessível por View > Terminal ou pelo atalho correspondente da IDE. No mesmo ambiente, o arquivo README.md deve ser consultado com frequência, preferencialmente em modo de visualização renderizada, para acompanhar instruções atualizadas do projeto.
Antes de iniciar, verifique se o uv já está presente no PATH do sistema:
uv --versionSe o comando retornar a versão instalada, o ambiente já possui o binário disponível. Caso contrário, prossiga com a instalação conforme o sistema operacional em uso.
Para macOS e Linux:
curl -LsSf https://astral.sh/uv/install.sh | shPara Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"[!IMPORTANT] Atenção ao Ambiente: Após a instalação, é necessário fechar e reabrir o terminal, ou reiniciar a IDE, para que as variáveis de ambiente sejam atualizadas corretamente. Em cenários específicos de conflito de permissões, especialmente em shells Unix, pode ser necessária a revisão manual dos arquivos de perfil do usuário.
Para garantir acesso às correções e recursos mais recentes, execute:
uv self updateCom o uv instalado, a configuração do ambiente do projeto pode ser consolidada com um único comando:
uv syncEste comando executa, de forma automatizada, etapas fundamentais do setup:
pyproject.toml e demais definições de dependências disponíveis no repositório..venv no diretório raiz do projeto, quando necessário.Ao final desse processo, o ambiente virtual estará provisionado e pronto para uso no fluxo de desenvolvimento.
Para consumir modelos de fronteira sem a necessidade de infraestrutura local massiva, utilizamos APIs. No caso da OpenAI, o modelo operacional segue a lógica de pay-as-you-go, exigindo atenção à configuração de créditos, orçamento e monitoramento de uso.
As API Keys são as credenciais que permitem ao código interagir com os modelos da OpenAI. Devem ser tratadas com o mesmo rigor de segurança de uma credencial sensível de produção.
chave_engenharia_llm.Nota Técnica: A plataforma permite diferentes níveis de permissão para a chave, como acesso total, restrito ou somente leitura. Essa segmentação é especialmente útil em projetos com múltiplos ambientes, equipes ou integrações.
.env)No fluxo profissional de desenvolvimento, nunca inserimos chaves de API diretamente no código-fonte (hardcoding). A abordagem correta é o uso de variáveis de ambiente carregadas a partir de um arquivo .env, localizado na raiz do projeto.
O arquivo deve ser criado na raiz (root) do diretório do projeto com a nomenclatura exata:
.envAtenção: O ponto inicial indica que este é um arquivo oculto em sistemas Unix/Linux. Não adicione extensões como
.txt.
Dentro do arquivo .env, defina a variável no padrão esperado pelos SDKs oficiais:
OPENAI_API_KEY="sua-chave-aqui"
Após inserir o valor, salve o arquivo corretamente (Ctrl + S ou Cmd + S). A ausência de salvamento é uma das causas mais comuns de falha na leitura da variável durante a execução da aplicação.
.env: o arquivo não deve ser enviado para repositórios remotos..env no CursorAo utilizar o Cursor, é comum que arquivos sensíveis como .env sejam tratados com mecanismos adicionais de proteção visual e contextual pela IDE.
Ainda assim, essa proteção não substitui as práticas fundamentais de segurança: revisão de commits, uso disciplinado de variáveis de ambiente e controle rigoroso de acesso ao repositório.
Com o ambiente sincronizado via uv, as credenciais devidamente provisionadas no projeto, o arquivo .env configurado com segurança e o repositório validado no Cursor, o desenvolvedor está apto a iniciar a fase de inferência, experimentação e construção de protótipos baseados em LLMs.
O desenvolvimento de IA exige uma postura proativa na resolução de problemas (Troubleshooting). Identificamos três pilares de suporte para falhas de configuração:
Complementando o uso de APIs de fronteira, a stack permite a execução de modelos locais para garantir privacidade e reduzir latência em tarefas específicas.
Para testar a prontidão do ambiente, utilizamos o Ollama para rodar modelos especializados (como o gpt-oss mencionado anteriormente).
# Comandos de verificação do ambiente virtual e execução
uv venv
source .venv/bin/activate
ollama run gpt-ossLógica de Interação: Ao interagir com o modelo, o engenheiro deve observar a consistência da resposta, a aderência ao prompt inicial e o comportamento da inferência sob diferentes cargas e contextos de uso.
Com o ambiente configurado via uv, chaves de API saneadas no .env, o repositório técnico validado e o Cursor devidamente indexado, o profissional transita da configuração de infraestrutura para a Engenharia de Prompt e Orquestração, onde o foco reside em extrair o valor máximo dos modelos de fronteira.
Para usuários de Windows e macOS, a etapa de setup exige atenção especial à interface de linha de comando, ao controle de versão e à organização do workspace local. Abaixo, consolidamos o fluxo operacional para garantir um ambiente consistente com a stack apresentada.
O PowerShell é uma estrutura de automação de tarefas e gerenciamento de configuração da Microsoft, consistindo em um shell de linha de comando e uma linguagem de script associada.
Windows, digite "PowerShell".Nota Técnica: Se você encontrar erros de execução de scripts, verifique a
ExecutionPolicydo seu sistema para permitir scripts locais.
O Git é o sistema de controle de versão distribuído essencial para gerenciar o código-fonte deste curso. É importante distinguir o Git (a ferramenta local) do GitHub (a plataforma de hospedagem na nuvem).
No seu terminal PowerShell, execute o comando abaixo para verificar se o Git já está integrado ao seu PATH:
gitSe o comando retornar uma lista de opções e subcomandos, o Git está instalado. Caso contrário, siga os passos:
Manter uma estrutura de diretórios organizada é fundamental para o sucesso em projetos complexos de ciência de dados e engenharia de IA. Vamos criar um diretório dedicado para seus projetos.
# Navegar para o diretório de usuário (Home)
cd ~
# Criar um novo diretório para os projetos
mkdir projetos
# Acessar o diretório recém-criado
cd projetos
# Listar o conteúdo para confirmar a estrutura (deve estar vazio no momento)
lsA técnica de clonagem cria uma cópia idêntica de um repositório remoto em sua máquina local. Utilizaremos o repositório oficial do curso para garantir que você tenha acesso a todos os notebooks, scripts de treinamento e guias técnicos.
github.com/santclear/engenharia-de-ia.git.projetos, execute:# Clonar o repositório de engenharia de LLM
git clone https://github.com/santclear/engenharia-de-ia.git
# Acessar a pasta do repositório clonado
cd engenharia-de-ia
# Listar arquivos para verificar a integridade da clonagem
lsDentro deste diretório, você encontrará a pasta guias/, que contém documentação detalhada sobre conceitos fundamentais, incluindo a diferença entre arquivos, pastas e diretórios, além de dicas de troubleshooting para ambientes Windows.
Embora você possa utilizar IDEs tradicionais como VS Code ou PyCharm, recomendamos o uso do Cursor. O Cursor é um fork do VS Code projetado especificamente para programação assistida por IA.
File > Open Folder e selecione o diretório engenharia-de-ia que acabamos de clonar.Importante: Certifique-se de selecionar a pasta raiz (Project Root). Isso é vital para que os recursos de indexação da IA do Cursor funcionem corretamente, permitindo que ela mapeie o conteúdo completo do repositório e os scripts de apoio.
No macOS, a interface principal para configuração do ambiente é o Terminal, utilizado para navegação em diretórios, clonagem de repositórios, execução de scripts e inicialização do stack local.
Nota Técnica: Em sistemas onde o Git ainda não está disponível, o próprio macOS poderá solicitar a instalação automática das Command Line Tools do Xcode ao executar o primeiro comando relacionado a desenvolvimento.
O Git também é o componente central de versionamento no macOS. Antes de prosseguir com a clonagem do repositório, valide se ele está disponível no ambiente.
No terminal, execute:
git --versionSe o sistema retornar a versão instalada, o ambiente está pronto para a etapa seguinte. Caso contrário, siga as instruções apresentadas pelo macOS para instalar as ferramentas de linha de comando.
No macOS, é recomendável manter os projetos em um diretório dedicado dentro da pasta do usuário e evitar diretórios sincronizados automaticamente por serviços como o iCloud Drive, especialmente em projetos com ambientes virtuais, arquivos temporários e repositórios Git extensos.
# Navegar para o diretório home do usuário
cd ~
# Verificar o caminho atual
pwd
# Criar um diretório dedicado para os projetos
mkdir projetos
# Acessar o diretório recém-criado
cd projetos
# Listar o conteúdo para confirmar a estrutura
lsNota Técnica: Evite utilizar pastas como
DesktopouDocumentsquando elas estiverem integradas ao iCloud, pois processos automáticos de sincronização podem introduzir latência, conflitos de leitura/escrita e instabilidade em ambientes virtuais.
Com o workspace preparado, a próxima etapa é a clonagem do repositório técnico oficial.
github.com/santclear/engenharia-de-ia.git.projetos, execute:# Clonar o repositório para a máquina local
git clone https://github.com/santclear/engenharia-de-ia.git
# Listar o conteúdo para confirmar a criação da pasta
ls
# Acessar a pasta do repositório
cd engenharia-de-ia
# Listar arquivos para verificar a integridade da clonagem
lsDentro deste diretório, você encontrará a pasta guias/, que contém documentação detalhada sobre conceitos fundamentais, instruções de configuração e material de suporte para o ambiente do curso.
No macOS, o Cursor mantém o mesmo papel estratégico já descrito anteriormente: operar como uma IDE com integração nativa a assistentes de codificação baseados em IA e indexação contextual do repositório.
engenharia-de-ia dentro da pasta projetos e abra a raiz do repositório.Importante: Assim como no Windows, a seleção da pasta raiz (Project Root) é essencial para que os mecanismos de indexação e compreensão contextual do Cursor operem corretamente sobre toda a base de código e documentação.
Com o ambiente configurado nos dois sistemas operacionais, o profissional está apto a prosseguir para o estudo dos Transformers, a configuração de ambientes virtuais, a integração com APIs de modelos de fronteira e a experimentação prática com modelos locais e pipelines de inferência.