12. Assistente de IA

No dia da venda, o suporte recebe milhares das mesmas perguntas: quando é o show? quanto custa? cadê o meu pedido? Um assistente consegue respondê-las em segundos, às 3 da manhã, em português e em inglês — se não inventar shows, não vazar dados e não custar mais que os ingressos. Este lab constrói um com a arquitetura da aula de sistemas de IA, rodando inteiramente na sua máquina com um modelo aberto local (Ollama) e, opcionalmente, no Claude para comparação. Na história da disciplina, este lab constrói o capítulo 13: ele implementa as decisões do gateway de LLM (rotas e um fallback), do loop do agente e das suas ferramentas só de leitura, da recuperação com pgvector e da malha de segurança.

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Antes de começar

Todo comando roda na raiz do seu repositório boxoffice, no estado em que o lab 11 o deixou:

boxoffice/
├── docker-compose.yaml     # the Compose stack of labs 1-9 (catalog behind gateway, order, ...)
├── .github/  k8s/          # labs 10-11
├── infra/  load/  scripts/
└── services/               # auth, catalog, gateway, inventory, notification, order, payment

Todo arquivo deste lab aparece completo nestas páginas e é publicado em https://insper.github.io/platform/2027.1/hands-on/12/code/<caminho>.

Arquitetura

flowchart LR
    fan[fã / interface de chat] -->|"POST /assistant/chat/stream"| api[assistant: FastAPI]
    api --> gin{guarda de entrada}
    gin --> orch[loop do agente]
    orch -->|"search_query: ..."| emb[modelo de embeddings]
    emb --> vdb[("pgvector: assistant.documents")]
    vdb -->|top-k eventos| orch
    orch -->|router do LiteLLM| gw[gateway de LLM]
    gw -->|local| ollama["Ollama: qwen2.5:1.5b"]
    gw -.->|"opcional, fallback para o local"| claude[API do Claude]
    orch -->|chamadas de ferramenta| reg[registro de ferramentas]
    reg -->|GET /catalog/events| cat[gateway -> catalog]
    reg -->|"GET /orders/id + X-User-Email"| ord[order]
    orch --> gout{guarda de saída}
    gout -->|tokens SSE + done| fan
    api -.->|métricas OTLP| lgtm[otel-lgtm]

O que você vai medir

Pré-requisitos

• Labs 1 (catalog), 7 (order) e 8 (Grafana) concluídos.
• Leia a aula de sistemas de IA: gateway de LLM, agentes, RAG e memória, segurança e avaliações.

Passos

1. O serviço e o gateway de LLM — Ollama, pgvector, o projeto uv, as rotas e o fallback do LiteLLM, a rota opcional do Claude.
2. RAG com pgvector — embeddings, o índice HNSW, a ingestão do catálogo, a avaliação da recuperação.
3. Ferramentas e o loop do agente — o registro de ferramentas, o loop limitado, streaming, a API.
4. Guardrails e métricas — injection e PII na entrada, ancoragem na saída; tokens, custo e TTFT no Grafana.
5. Meça — TTFT sob carga, qualidade da recuperação e das respostas, escolha do modelo.

Experimente no playground

Experimente: rode o cenário ai-assistant com o perfil load. Aumente os steps do orquestrador de 1 para 4 e veja a latência e o custo por requisição se multiplicarem — cada step é mais uma chamada ao LLM. Depois ative o cache semântico do gateway de LLM e veja que fração do tráfego nunca chega ao modelo.

O simulador completo está no playground.

Meça

O passo Meça tem os scripts e a tabela de resultados para guardar em results/lab12.md.

Solução de problemas

Limpeza

docker compose stop assistant ollama        # free the CPU/RAM of the model
docker compose down -v                      # or remove everything (including the downloaded models)

O docker compose down -v também apaga o volume ollama-models: a próxima execução baixa os modelos de novo. Mantenha-o se for continuar para o lab 13, que pode usar o mesmo modelo local. Com o Ollama nativo, ollama stop qwen2.5:1.5b libera a memória do modelo na hora (ele também sai da memória após 5 minutos ocioso), e ollama rm qwen2.5:1.5b nomic-embed-text apaga os modelos quando você não precisar mais deles.

Estado final

boxoffice/
├── .gitignore              # + __pycache__/, .venv/
├── docker-compose.yaml     # db/db-replica -> pgvector image; + ollama, ollama-init, assistant
├── scripts/
│   ├── assistant_load.py   # TTFT load test (uv inline script)
│   └── eval_retrieval.py   # hit@k / MRR (uv inline script)
├── results/lab12.md
└── services/assistant/     # new: pyproject.toml, uv.lock, .python-version, Dockerfile, .dockerignore,
    └── app/                # __init__, config, llm, db, rag, tools, agent, guardrails, metrics, main

Faça o commit e a tag: git add -A && git commit -m "lab 12: AI assistant" && git tag lab12.

Checklist

• ollama, ollama-init e assistant rodam no docker-compose.yaml (ou o Ollama nativamente, com OLLAMA_URL); o db usa a imagem do pgvector
• services/assistant é um projeto uv com pyproject.toml e uv.lock commitados; a imagem é construída com uv sync --frozen
• o /assistant/ingest carregou pelo menos 300 eventos; o scripts/eval_retrieval.py reporta hit@5 e MRR
• /assistant/chat e /assistant/chat/stream respondem com citações conferidas pelo guarda de saída; uma tentativa de injection retorna 422
• get_order_status só responde para o usuário em X-User-Email
• métricas assistant_* (tokens, custo, TTFT) visíveis no Grafana
• tabela de resultados preenchida em results/lab12.md, incluindo onde o modelo rodou
• autoverificação: docker compose up -d --build assistant a partir de um clone limpo, e então curl localhost:8088/assistant/health retorna "status":"UP"; push com a tag lab12

Relacionados

• Teoria: Sistemas de IA e agentes · Gateway de LLM · Agentes e ferramentas · RAG e memória · Segurança e avaliações
• Estudo de caso: Assistente de IA
• Próximo lab: 13. IA no CI/CD usa modelos de linguagem dentro do pipeline de entrega do lab 11.

Começar: O serviço e o gateway de LLM