Agente de atendimento IA

Como Criar um Agente de Atendimento com IA Generativa 100% Local Usando LLaMA e Memória Vetorial

Por

A inteligência artificial generativa está revolucionando o atendimento ao cliente — mas e se você pudesse ter seu próprio agente de IA rodando totalmente offline, sem depender da nuvem, APIs externas ou envio de dados para terceiros?

Neste artigo, você vai aprender passo a passo como construir um agente de atendimento com IA generativa usando um modelo LLaMA local e memória vetorial com FAISS, tudo rodando no seu próprio computador. Ideal para quem busca controle total, privacidade e performance.

📌 O que você vai aprender

  • O que é um agente de IA com memória vetorial
  • Como integrar IA generativa com recuperação semântica de contexto
  • Como usar o LLaMA quantizado (.gguf) com llama-cpp-python
  • Como construir um pipeline local e funcional com Python e FastAPI
  • Como estruturar uma base de conhecimento para IA

🔍 Conceitos fundamentais

🧠 O que é um agente de IA com memória vetorial?

Um agente de IA com memória vetorial é um sistema capaz de lembrar e utilizar conhecimento prévio para responder perguntas. Ele combina dois componentes principais:

  1. Recuperação semântica: onde embeddings vetoriais são usados para encontrar trechos relevantes em uma base de dados textual.
  2. IA generativa: que gera respostas em linguagem natural com base nesse contexto recuperado.

Essa abordagem resolve o principal problema dos modelos LLM: a falta de conhecimento específico sobre sua empresa ou domínio.

🤖 Por que rodar localmente?

Rodar seu agente localmente tem diversas vantagens:

  • Privacidade total dos dados dos usuários
  • Zero custo com API externa
  • Possibilidade de personalização total
  • Independência da internet

🧩 O que é o LLaMA?

O LLaMA (Large Language Model Meta AI) é uma família de modelos de linguagem desenvolvida pela Meta (Facebook) voltada para pesquisa e aplicações práticas. Seu código é aberto, e sua eficiência computacional o torna uma excelente escolha para rodar localmente — especialmente quando usado em formato quantizado (.gguf).

Ele é capaz de compreender linguagem natural e gerar respostas coerentes e contextuais, muito parecido com modelos comerciais como o GPT-3.5, mas com a vantagem de poder rodar diretamente no seu notebook ou servidor.

Quando usamos o llama-cpp-python, conseguimos acessar esses modelos via Python com consumo de memória otimizado, ideal para quem não possui GPUs de alto desempenho.

📦 O que é FAISS?

O FAISS (Facebook AI Similarity Search) é uma biblioteca desenvolvida pela Meta para busca vetorial de alta performance. Ela permite armazenar milhares (ou milhões) de vetores e fazer consultas rápidas por similaridade.

No contexto do nosso agente de IA, usamos FAISS para:

  • Armazenar os embeddings gerados a partir da base de conhecimento
  • Fazer buscas por similaridade semântica com base na pergunta do usuário
  • Recuperar os trechos mais relevantes que serão usados como contexto para a resposta

FAISS é extremamente leve, rápido, funciona localmente e é amplamente utilizado em sistemas de RAG (Retrieval-Augmented Generation).

⚙️ Arquitetura do Projeto

O projeto é dividido em camadas bem definidas:

Usuário → FastAPI → Recuperador FAISS → IA (LLaMA local) → Resposta

  • base_conhecimento.txt: base textual da empresa
  • SentenceTransformers: converte textos em vetores semânticos
  • FAISS: indexa e busca os vetores
  • llama-cpp-python: roda o modelo LLaMA quantizado
  • FastAPI: serve a aplicação como uma API HTTP

O código completo está disponível no meu Github, através deste link. Você só vai precisar baixar o modelo, que tem por volta de 4Gb, que não foi incluído no repositório devido ao seu tamanho.

🛠️ Passo a passo da implementação

A seguir, vamos montar o projeto do zero, explicando cada etapa e arquivo envolvido.

1. Estrutura do projeto

project/
├── backend/              # API com FastAPI
├── embeddings/           # Criação e uso de embeddings + FAISS
├── inference/            # Inferência com LLaMA
├── llm/                  # Modelos e configuração
├── data/                 # Base de conhecimento textual
├── requirements.txt      # Dependências do projeto

2. Instalando as dependências

Crie um ambiente virtual e instale os pacotes necessários:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

O arquivo requirements.txt deve conter:

fastapi
uvicorn
llama-cpp-python
sentence-transformers
faiss-cpu

3. Criando a base de conhecimento

Edite o arquivo data/knowledge_base.txt com fatos da sua empresa:

Os clientes podem acessar a segunda via da fatura pelo nosso portal online.
Nosso horário de atendimento é de segunda a sexta, das 9h às 18h.
Oferecemos suporte técnico apenas para produtos comprados nos últimos 12 meses.

Cada linha representa um conhecimento factual que o agente pode usar como contexto.

4. Criando o script de indexação FAISS

Antes de gerar o índice, crie o arquivo embeddings/build_index.py com o seguinte conteúdo:

import os
import faiss
import numpy as np
from sentence_transformers import SentenceTransformer

os.makedirs("embeddings/faiss_index", exist_ok=True)

model = SentenceTransformer('all-MiniLM-L6-v2')
corpus = [linha.strip() for linha in open("data/knowledge_base.txt") if linha.strip()]
embeddings = model.encode(corpus)

index = faiss.IndexFlatL2(384)
index.add(np.array(embeddings))
faiss.write_index(index, "embeddings/faiss_index/index.bin")

Esse script carrega os textos da base de conhecimento, gera os embeddings vetoriais e salva o índice FAISS em disco.

5. Gerando o índice vetorial com FAISS

Execute o script de indexação:

python embeddings/build_index.py

Ele gera o arquivo embeddings/faiss_index/index.bin, que será usado para recuperar informações com base nas perguntas do usuário.

6. Preparando o Modelo LLaMA

A forma mais prática de baixar o modelo .gguf é utilizando a ferramenta huggingface-cli. Primeiro, instale o pacote necessário:

pip install huggingface_hub

Depois, execute o seguinte comando para baixar o modelo e salvar diretamente na pasta llm/models/:

huggingface-cli download TheBloke/Llama-2-7B-Chat-GGUF llama-2-7b-chat.Q4_K_M.gguf \
  --local-dir llm/models --local-dir-use-symlinks False

Esse comando baixa o arquivo llama-2-7b-chat.Q4_K_M.gguf, já pronto para uso com llama-cpp-python.

A versão Q4_K_M é uma ótima escolha para máquinas com 6 GB de RAM ou mais.

7. Implementando a inferência com contexto

No arquivo inference/agent.py, temos a lógica de carregamento do modelo, recuperação vetorial e geração de resposta com prompt dinâmico:

from llama_cpp import Llama
from sentence_transformers import SentenceTransformer
import faiss
import numpy as np

llm = Llama(model_path="./models/llama-3-8b.Q4_K_M.gguf", n_ctx=2048)
embedder = SentenceTransformer('all-MiniLM-L6-v2')
index = faiss.read_index("embeddings/faiss_index/index.bin")

with open("data/knowledge_base.txt") as f:
    corpus = [l.strip() for l in f if l.strip()]

def recuperar_contexto(pergunta):
    vetor = embedder.encode([pergunta])
    D, I = index.search(np.array(vetor), k=3)
    return [corpus[i] for i in I[0]]

def gerar_resposta(pergunta):
    contexto = recuperar_contexto(pergunta)
    prompt = f"""
Você é um agente de atendimento da empresa X. Use as informações abaixo:

Contexto:
{chr(10).join(contexto)}

Usuário:
{pergunta}

Resposta:
"""
    output = llm(prompt, max_tokens=300)
    return output['choices'][0]['text']

8. Criando o servidor com FastAPI

Crie o arquivo backend/app.py:

from fastapi import FastAPI, Request
from inference.agent import gerar_resposta

app = FastAPI()

@app.post("/responder")
async def responder(request: Request):
    data = await request.json()
    pergunta = data.get("pergunta", "")
    resposta = gerar_resposta(pergunta)
    return {"resposta": resposta}

Inicie o servidor com o comando abaixo:

uvicorn backend.app:app --reload

E teste com:

curl -X POST http://localhost:8000/responder \
     -H "Content-Type: application/json" \
     -d '{"pergunta": "Como posso acessar minha fatura?"}'

🔄 Possibilidades de expansão

Agora que você tem um agente de IA funcional rodando localmente, vamos explorar como você pode ir além — tornando-o mais útil, eficiente e adaptado às suas necessidades.

1. Personalização por perfil de usuário

Você pode adicionar um sistema de identificação do usuário e armazenar seu histórico de conversas ou preferências.

Exemplo: salvar nome, últimas perguntas feitas ou respostas personalizadas com base no tipo de cliente (ex: plano básico vs. premium).

2. Logs e auditoria

Registrar todas as perguntas recebidas e respostas geradas pode ajudar em:

  • Auditoria de segurança
  • Análise de qualidade das respostas
  • Geração de relatórios

Você pode usar um simples print() em modo desenvolvimento ou armazenar em arquivos JSON, SQLite ou até um Elasticsearch local.

3. Cache de perguntas frequentes

Evite recalcular embeddings e rodar o modelo quando a pergunta já foi feita antes. Um dicionário ou banco chave-valor pode armazenar as últimas N respostas mais comuns.

4. Interface gráfica

Embora o agente funcione via API, você pode integrar com:

  • Uma interface web com Streamlit, Flask ou React
  • Um widget de chat no seu site
  • Um app de desktop com Electron ou Tauri

5. Multiidioma

Tanto os modelos LLaMA quanto o all-MiniLM-L6-v2 suportam múltiplos idiomas. Você pode expandir sua base de conhecimento para lidar com perguntas em português, inglês e espanhol, por exemplo.

6. Atualização contínua da base

Crie um script para importar automaticamente entradas de uma planilha do Google, CSV ou base de dados da sua empresa. Isso facilita a manutenção da base de conhecimento sem editar arquivos manualmente.

📣 Pronto para construir o seu próprio agente de IA?

Agora você tem em mãos todas as peças para montar um agente de atendimento com IA generativa, rodando 100% localmente. Seja para atender clientes, treinar colaboradores ou automatizar suporte interno, esse projeto é uma base poderosa para qualquer aplicação personalizada.

👉 Gostou do conteúdo? Então marque este artigo, compartilhe com colegas desenvolvedores e experimente aplicar essa abordagem na sua própria empresa ou projeto pessoal.

Se tiver dúvidas, sugestões ou quiser mostrar como ficou sua implementação, deixe um comentário — vou adorar ver o que você criou!

Deixe um comentário

Privacy Policy