RAG local com FastAPI e Ollama: da chamada simples a um LLM até um backend de produção

Um desenvolvedor do Habr analisa um momento específico: quando uma chamada isolada a um modelo local deixa de ser suficiente e o que é preciso acrescentar para chegar a um backend de verdade.

Quando uma chamada simples não basta

A primeira versão parece óbvia: o frontend envia uma pergunta, o FastAPI recebe `POST /ask`, o backend aciona o Ollama e devolve uma string com a resposta. Para uma demo, isso basta. Para um assistente de documentação, não.

As dúvidas surgem logo: em quais documentos a resposta se baseia? Quais trechos entraram no prompt? Por que uma requisição leva dois segundos e outra, quinze? O que acontece se o índice não é atualizado há três semanas? Uma chamada simples a um LLM não consegue responder a nenhuma dessas perguntas.

O que a camada de backend acrescenta

O autor introduz os componentes um a um, explicando o problema concreto que cada um resolve:

• request_id — identificador único da requisição, usado para correlacionar logs e depurar uma falha específica
• sources — lista dos trechos de documentos que entraram no contexto do modelo, com indicação da fonte
• timings — divisão do tempo por etapa: busca no índice, montagem do prompt, geração da resposta
• rebuild index — endpoint separado para reconstruir o índice sem reiniciar o serviço
• negative tests — verificação do comportamento com corpus vazio, perguntas fora do tema e índice desatualizado

A stack é totalmente local: FastAPI para a camada HTTP, Ollama para a geração e embeddings próprios. Nenhuma chave de API externa.

O contrato de API como fronteira do sistema

Uma das teses centrais do artigo é a importância de um contrato explícito na resposta. Quando o `/ask` devolve apenas uma string, o serviço continua sendo uma caixa-preta. Quando a resposta inclui `request_id`, `sources`, `timings` e o status do índice, passa a ser possível monitorar, depurar e melhorar o sistema.

«Mostro não como o RAG funciona em geral, mas o caminho de uma chamada

simples a um LLM local até um pequeno projeto de backend com contrato de API, logs, sources, timings e limitações assumidas com honestidade».

Essa abordagem muda a relação com o serviço: em vez de "o modelo responde de algum jeito", passa-se a ter "o sistema se comporta de forma previsível".

Honestidade sobre as limitações

O autor lista explicitamente o que o projeto não tem: autenticação, cache, suporte a carga multiusuário e CI/CD. Isso torna o artigo mais útil do que a maioria dos tutoriais, em que a seção de limitações simplesmente não existe ou se resume a uma frase de praxe.

Os negative tests merecem destaque à parte. O artigo verifica o comportamento com um corpus de documentos vazio, com perguntas sem conteúdo relevante no índice e com consultas ao índice depois da adição de novos arquivos sem reconstrução. É um conjunto mínimo, mas já permite entender exatamente onde o sistema falha.

O que isso significa

O artigo preenche uma lacuna concreta: a maioria dos materiais sobre RAG ou explica a teoria ou mostra um "hello world" com LangChain. Aqui, o leitor encontra um serviço local funcional, com ferramentas de observabilidade, que pode servir de base para um projeto real.