Agente de IA local com Python: crie o seu com Ollama
Aprenda a criar um agente de IA local com Python, Ollama e LangChain: rode modelos no seu PC, sem pagar por API e sem expor os dados da empresa.
O que você vai ver aqui?
Introdução
Toda vez que o seu agente responde uma pergunta usando a API da OpenAI, do Claude ou do Gemini, duas coisas acontecem: você paga pela resposta e os documentos da sua empresa viajam até um servidor de fora. Agora imagina ter um agente de IA local, rodando no seu próprio computador, sem custo por pergunta, sem chave de API e funcionando até sem internet.
Dá para fazer isso, e é bem mais simples do que parece. Neste guia, você vai pegar um assistente RAG que responde dúvidas sobre as políticas de RH de uma empresa, com base em um PDF, e colocar ele para rodar 100% na sua máquina com o Ollama e o LangChain. No código, são só três trocas.
Se você ainda não tem esse assistente pronto, vale construir antes seguindo o passo a passo de agentes RAG com Python. Aqui a gente parte desse código e foca só no que muda para ele funcionar localmente.
Para fazer o download do(s) arquivo(s) utilizados na aula, preencha com o seu e-mail:
Não vamos te encaminhar nenhum tipo de SPAM! A Hashtag Treinamentos é uma empresa preocupada com a proteção de seus dados e realiza o tratamento de acordo com a Lei Geral de Proteção de Dados (Lei n. 13.709/18). Qualquer dúvida, nos contate.
Descubra por que vale a pena ter um agente de IA local
Quando você integra IA com Python usando ChatGPT, Claude ou Gemini, o modelo mora na nuvem. Seu código manda o texto, a empresa processa e devolve a resposta. Funciona muito bem, mas tem custo a cada chamada e exige que os dados saiam do seu computador.
Em um agente baseado em RAG, isso pesa ainda mais, porque você paga duas vezes: uma para transformar o documento em embeddings e outra para cada pergunta respondida. E o documento, que muitas vezes é interno e confidencial, vai junto.
Com um agente de IA local, o cenário muda:
- Sem custo por pergunta: o modelo roda no seu hardware, então não existe cobrança por token.
- Sem chave de API: você não precisa criar conta, configurar crédito nem guardar chave no
.env. - Privacidade de verdade: as informações da empresa ficam no seu computador ou no servidor da própria empresa.
- Funciona offline: depois que os modelos estão baixados, dá para usar o agente sem internet.
O preço disso é que a qualidade passa a depender da sua máquina. Quanto mais memória você tiver, maior o modelo que dá para rodar e melhores as respostas. A boa notícia é que a lógica do agente continua exatamente a mesma: só muda quem roda o modelo.
Instale o Ollama e escolha o modelo certo para o seu computador
O Ollama é a ferramenta que faz a mágica acontecer. Pense nele como um gerenciador de modelos de IA locais: ele baixa os modelos, organiza tudo no seu computador, roda cada um quando você pede e disponibiliza esses modelos para os seus códigos em Python. Existem outras formas de rodar IA local, mas o Ollama é das mais simples para começar.
Para instalar, acesse a página de download do Ollama e escolha o seu sistema. No Windows, a página mostra um comando para você copiar e colar no PowerShell (pode ser o terminal do próprio VS Code):
irm https://ollama.com/install.ps1 | iex
Espere a instalação terminar e faça uma coisa que muita gente esquece: feche todas as janelas do VS Code e abra de novo. A instalação cria um comando novo, o ollama, e o VS Code só passa a reconhecer esse comando em todos os terminais depois de reiniciado. Se pular esse passo, um terminal pode funcionar e outro não, e aí a confusão está feita.
Confira a memória da sua placa de vídeo
Antes de baixar qualquer modelo, descubra quanto o seu computador aguenta. Os modelos de linguagem (LLMs) rodam principalmente na memória da placa de vídeo, e não na RAM comum. Então o número que importa é outro.
No Windows 11, abra Configurações > Sistema > Sobre e procure o card Placa gráfica. No exemplo abaixo, o computador tem 32 GB de RAM, mas só 4 GB de placa de vídeo. Para escolher o modelo, o limite é 4 GB.
No Mac com chip Apple Silicon (M1, M2, M3 e seguintes), a história é diferente. A memória é unificada, ou seja, RAM e memória gráfica são a mesma coisa. Com 16 GB de RAM, você poderia rodar modelos de até uns 16 GB.
Nos dois casos, vale a mesma regra prática: escolha um modelo um pouco menor do que a memória disponível. Se o modelo ocupar tudo, o computador fica lento para qualquer outra tarefa. E se você não tiver placa de vídeo dedicada, o modelo até roda no processador, só que bem mais devagar.
Escolha o tamanho do Qwen 3.5 ideal
No site do Ollama, clique em Models, marque o filtro Local e pesquise por qwen3.5. O Qwen é uma das famílias de modelos abertos mais usadas para rodar IA localmente, e a página do Qwen 3.5 no Ollama lista vários tamanhos.
O número com "b" no nome indica bilhões de parâmetros. Quanto mais parâmetros, mais capaz o modelo e mais memória ele consome:
| Modelo | Tamanho aproximado | Para quem serve |
|---|---|---|
| qwen3.5:0.8b | 1,2 a 1,3 GB | Quase qualquer computador. Ótimo para começar |
| qwen3.5:2b | 2,7 a 3,1 GB | Placas de vídeo de 4 GB |
| qwen3.5:4b | 3,3 a 4,0 GB | Placas de 6 GB ou mais |
| qwen3.5:9b | 6,6 a 7,6 GB | Placas de 8 GB ou mais, ou Mac com 16 GB |
| qwen3.5:27b | 17 a 20 GB | Máquinas parrudas ou Mac com 32 GB ou mais |
Neste guia, usamos o qwen3.5:0.8b, o mais leve da família, para que todo mundo consiga acompanhar. Se a sua placa tiver mais memória, teste o 2b ou o 4b, que respondem melhor. E se nem o 0.8b rodar bem, procure o Qwen 3 (sem o .5), que tem versões com menos de 1 GB.
Baixe o LLM e o modelo de embedding
Com o modelo escolhido, abra o terminal e use o comando ollama pull seguido do nome que aparece no site:
ollama pull qwen3.5:0.8bO download leva alguns minutos, dependendo da sua internet. Quando terminar, confira o que está instalado com:
ollama listEsse comando mostra o nome, o tamanho e a data de cada modelo que o Ollama gerencia no seu computador. Guarde esses nomes, porque são eles que você vai colocar no código.
Agora vem um detalhe importante. Como o nosso projeto é um agente RAG, ele precisa de um segundo modelo, especializado em embeddings. Use o qwen3-embedding na versão mais leve, de 639 MB, que entende mais de 100 idiomas, incluindo o português:
ollama pull qwen3-embedding:0.6b
Para não se perder, aqui estão todos os comandos que você vai usar neste projeto:
Teste o modelo direto no terminal
Antes de mexer no código, vale ver o modelo funcionando sozinho. Rode:
ollama run qwen3.5:0.8bIsso abre um chat dentro do terminal. Pergunte, por exemplo, "quem foi Albert Einstein?" e repare em duas coisas. A primeira: tudo acontece no seu computador, sem internet. A segunda: o Qwen roda por padrão no modo thinking (raciocínio), então ele mostra o passo a passo do que está pensando antes de responder. Para sair do chat, digite /bye.
Olhando o raciocínio de perto, dá para ver o modelo se enrolando com datas, e a resposta final diz que Einstein nasceu em 23 de agosto de 1879, quando o correto é 14 de março. Isso é normal para um modelo tão pequeno respondendo de memória. E é justamente por isso que o RAG entra: em vez de confiar no que o modelo lembra, a gente entrega para ele o trecho certo do documento.
Agentes de IA e n8n ImpressionadorCrie agentes de IA que trabalham por você e automações que rodam sozinhas, sem escrever uma linha de código. Aprenda o n8n do zero, conecte WhatsApp, e-mail, planilhas e os sistemas que a empresa já usa, e monte projetos reais como agente de atendimento, de cobrança e de triagem de currículos.
Começar agoraQuero a oferta de Black Friday
Adapte seu agente RAG para rodar localmente com LangChain
Relembrando como o agente funciona: ele carrega o PDF de políticas de RH com o PyPDFLoader, divide o texto em blocos de 1.000 caracteres (com 200 de sobreposição), transforma cada bloco em embeddings e guarda tudo no FAISS, um banco de dados vetorial. Quando chega uma pergunta, o retriever busca os blocos mais parecidos e o LLM escreve a resposta com base neles.
Na versão original, a OpenAI fazia dois desses passos e cobrava por ambos: o embedding, com o text-embedding-3-small, e a resposta, com o gpt-4o-mini. Para rodar o agente de IA local, você só precisa trocar esses dois pontos.
E a troca é tranquila porque o LangChain, a biblioteca mais usada para criar agentes de IA em Python, padroniza as integrações. A classe da OpenAI e a classe do Ollama funcionam do mesmo jeito. Trocar de provedor é, basicamente, trocar o import e o nome do modelo.
Instale a biblioteca langchain-ollama
A integração entre LangChain e Ollama fica em uma biblioteca separada, que não vem instalada por padrão. No terminal, rode:
pip install langchain-ollamaSe preferir instalar tudo que o projeto usa de uma vez, rode pip install -r requirements.txt com o arquivo abaixo (se tiver dúvida nessa parte, veja como usar o pip install no Python):
streamlit
langchain
langchain-community
langchain-openai
langchain-ollama
langchain-text-splitters
faiss-cpu
pypdf
python-dotenv
A langchain-openai só continua na lista para quem quiser rodar a versão antiga do projeto. Para o agente local, ela não é necessária. Todos os detalhes da integração estão na documentação do ChatOllama no LangChain.
Troque o embedding da OpenAI pelo OllamaEmbeddings
No topo do código, importe as duas classes do Ollama. Repare que os nomes são praticamente os mesmos da OpenAI:
# antes
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
# depois
from langchain_ollama import OllamaEmbeddings, ChatOllama
Depois, na função que cria o banco de vetores, troque o OpenAIEmbeddings pelo OllamaEmbeddings e passe o nome do modelo de embedding que você baixou. A dica é copiar o nome exatamente como aparece no ollama list:
def criar_banco_vetores(lista_blocos):
ferramenta_embedding = OllamaEmbeddings(model="qwen3-embedding:0.6b")
banco_vetores = FAISS.from_documents(lista_blocos, ferramenta_embedding)
return banco_vetores
O resto da função continua igual: o FAISS recebe os blocos e a ferramenta de embedding, sem saber se ela é da OpenAI ou local. Se quiser se aprofundar nos parâmetros, a página do OllamaEmbeddings no LangChain explica tudo. Como o agente não usa mais chave de API, o load_dotenv() deixa de ser obrigatório, mas não atrapalha se continuar no código.
Use o ChatOllama e desligue o modo de raciocínio
A última troca é no modelo que escreve as respostas. Dentro da função que monta a chain do agente, substitua o ChatOpenAI pelo ChatOllama com o nome do Qwen que você baixou:
def criar_chain_agente(banco_vetores):
# ... prompt_template continua igual ...
buscador_contexto = banco_vetores.as_retriever()
llm = ChatOllama(model="qwen3.5:0.8b", reasoning=False)
chain = ({"context": buscador_contexto, "question": RunnablePassthrough()}
| prompt_template
| llm
| StrOutputParser())
return chain
O reasoning=False é opcional, mas faz muita diferença aqui. Lembra que o Qwen mostrou todo o raciocínio no terminal? Num agente que só precisa responder com base no PDF, esse pensamento extra deixa a resposta mais lenta e cheia de texto que o usuário não pediu. O parâmetro aceita três valores:
reasoning=False: desliga o raciocínio e o modelo responde direto. É o que a gente usa.reasoning=True: liga o raciocínio, mas separa o pensamento da resposta final, num campo próprio.reasoning=None(padrão): o modelo segue o comportamento dele. No Qwen, isso significa pensar em voz alta dentro da resposta.
Essa descrição está na referência da API do ChatOllama, caso você queira conferir as outras opções, como temperatura e tamanho de contexto.
Rode o agente de IA local e teste com seus documentos
Código ajustado, é hora de ver o agente funcionando. Como a interface foi feita com Streamlit, salve o arquivo e rode no terminal:
streamlit run app_gabarito_ollama.pyUse o nome do arquivo que você editou. No material do projeto, a versão final já pronta se chama app_gabarito_ollama.py. O chat abre no navegador, em localhost:8501. Se aparecer no terminal um aviso de DeprecationWarning sobre o langchain-community, pode seguir: é só um alerta de que a biblioteca vai mudar no futuro, e o app roda normalmente.
Para fazer o teste completo, desconecte a internet e pergunte algo como "posso trabalhar remoto? quais são as regras para ser aprovado no trabalho remoto?". O agente busca os trechos no PDF e responde usando só os modelos que estão no seu computador:
Sem chave de API, sem custo e sem que nenhuma linha do documento saia da sua máquina. Para uma empresa, isso abre espaço para usar IA com contratos, manuais, políticas internas e qualquer arquivo que não poderia ir para um servidor de fora.
Melhore a precisão das respostas do agente
Agora um olhar crítico sobre a resposta. O agente acertou pontos importantes: só é elegível quem não tem advertência disciplinar nos últimos 6 meses, e o auxílio é de R$ 200,00 no regime híbrido e R$ 350,00 no 100% remoto. Mas ele também misturou uma regra do horário flexível (a antecedência de uma semana) e deixou de fora outras do PDF, como ter mais de 90 dias de empresa e trabalhar remoto no máximo 3 dias por semana.
Isso acontece porque o 0.8b é um modelo bem pequeno. Ele é ótimo para aprender e testar, mas vale conhecer os caminhos para melhorar as respostas:
- Suba o tamanho do modelo: se a sua memória permitir, o qwen3.5:2b ou o 4b entendem melhor o contexto e misturam menos as informações.
- Traga mais trechos do documento: por padrão, o retriever busca 4 blocos. Teste
banco_vetores.as_retriever(search_kwargs={"k": 6})para dar mais contexto ao modelo. - Deixe o prompt mais específico: peça para o agente listar todas as condições encontradas e citar só o que estiver no texto.
- Revise o que for crítico: para decisões de RH, jurídicas ou financeiras, trate a resposta como um ponto de partida e confira no documento.
Uma dica extra de Streamlit: repare que os valores em reais aparecem com uma formatação estranha na tela. Isso acontece porque o st.write entende o texto entre dois cifrões como fórmula matemática. Para corrigir, troque a linha que exibe a resposta por st.write(answer.replace("$", "\\$")). Se quiser ir mais fundo nos ajustes de busca e de divisão do texto, o guia de sistema RAG em Python é um ótimo próximo passo.
Conclusão
Criar um agente de IA local é mais uma questão de configuração do que de programação. Você instalou o Ollama, escolheu um modelo que cabe na memória da sua placa de vídeo, baixou o LLM e o modelo de embedding e fez três trocas no código: o import, o OllamaEmbeddings e o ChatOllama. Todo o resto do agente RAG, do PDF até a interface no Streamlit, continuou igual.
A partir daqui, dá para aplicar a mesma ideia em qualquer agente feito com LangChain: testar modelos maiores conforme o seu hardware, trocar o PDF pelos documentos da sua empresa e manter tudo rodando com privacidade e sem custo por pergunta. Se você quer dominar Python a ponto de criar automações, análises e agentes de IA como este do zero, conheça o Python Impressionador, o curso completo de Python da Hashtag.
Caso prefira esse conteúdo no formato de videoaula, assista ao vídeo abaixo ou acesse o nosso canal do YouTube!
FAQ - Perguntas Frequentes sobre Agente de IA local
1. Preciso de internet para usar um agente de IA local?
Só para instalar o Ollama e baixar os modelos. Depois disso, o agente roda totalmente offline, direto no seu computador.
2. Qual computador eu preciso para rodar IA localmente?
O ideal é ter placa de vídeo dedicada: com 4 GB, já dá para rodar o qwen3.5:0.8b e o 2b. No Mac com Apple Silicon, vale a RAM, que é unificada. Sem placa dedicada, o modelo roda no processador, só que mais devagar.
3. O Ollama é gratuito?
Sim. Baixar e rodar modelos locais com o Ollama não tem custo. O site também oferece planos pagos para modelos na nuvem, mas você não precisa deles para um agente local.
4. Dá para usar outro modelo além do Qwen no Ollama?
Dá, sim. O Ollama tem modelos como Llama, Gemma, Mistral e DeepSeek. É só baixar com ollama pull e trocar o nome do modelo no ChatOllama.
5. Posso adaptar qualquer agente da OpenAI para rodar localmente?
Se o agente foi feito com LangChain, na maioria dos casos basta trocar as classes e o nome do modelo. Recursos como chamada de ferramentas dependem de o modelo local ter suporte a eles.
Hashtag Treinamentos
Para acessar outras publicações de Python, clique aqui!
Posts mais recentes de Python
- Agente de IA local com Python: crie o seu com Ollama
Aprenda a criar um agente de IA local com Python, Ollama e LangChain: rode modelos no seu PC, sem pagar por API e sem expor os dados da empresa. - Como Criar CRM com Codex no VS Code usando Python e Flask
Aprenda a criar CRM com Codex no VS Code usando Python, Flask e SQLite, com login, orçamentos e PDF, em fases com testes e commits no Git. - Curso Básico de Python: Saia do Zero em 10 Aulas Grátis
Aprenda com o curso básico de Python gratuito da Hashtag: 10 aulas práticas, exercícios e projetos reais para sair do zero em programação.
Posts mais recentes da Hashtag Treinamentos
- Agente de IA local com Python: crie o seu com OllamaAprenda a criar um agente de IA local com Python, Ollama e LangChain: rode modelos no seu PC, sem pagar por API e sem expor os dados da empresa.
- Claude Dashboards: Como Usar Passo a Passo
Aprenda a usar o Claude Dashboards: conecte o Google Sheets, crie um dashboard com IA, confira de onde vem cada número e atualize os dados em um clique. - O que é tabela dinâmica?
O que é tabela dinâmica no Excel, para que serve e o passo a passo para resumir grandes bases de dados sem fórmulas.
