Локальный RAG на FastAPI и Ollama: от простого вызова LLM к production backend

Um desenvolvedor no Habr analisa um momento específico: quando uma simples chamada a um modelo local não é mais suficiente — e o que é necessário adicionar para obter um verdadeiro sistema backend.

Quando uma simples chamada não é o suficiente A primeira versão parece

óbvia: o frontend envia uma pergunta, o FastAPI recebe `POST /ask`, o backend chama o Ollama e retorna uma string com a resposta. Para uma demonstração, é suficiente. Para um assistente de documentação — não. As perguntas surgem imediatamente: em quais documentos a resposta se baseia? Quais fragmentos entraram no prompt? Por que uma requisição leva dois segundos para ser processada, enquanto outra leva quinze? O que acontece se o índice não foi atualizado há três semanas? Não é possível responder a essas perguntas com uma simples chamada a um LLM.

O que a camada backend adiciona O autor introduz componentes um a um,

explicando o problema específico que cada um resolve: request_id — um identificador único de requisição para correlação de logs e depuração de falhas específicas sources — uma lista de fragmentos de documentos que entraram no contexto do modelo, com indicação da fonte timings — divisão de tempo por etapas: busca no índice, formação do prompt, geração da resposta rebuild index — um endpoint separado para reconstruir o índice sem reiniciar o serviço * negative tests — verificação de comportamento com um corpus de documentos vazio, perguntas fora do escopo e índice desatualizado A stack é totalmente local: FastAPI para a camada HTTP, Ollama para a geração, embeddings personalizados. Nenhuma chave de API externa.

Contrato de API como fronteira do sistema

Um dos pontos-chave do artigo — a importância de um contrato explícito no nível da resposta. Quando `/ask` retorna apenas uma string, o serviço permanece uma caixa preta. Assim que a resposta inclui `request_id`, `sources`, `timings` e status do índice — torna-se possível monitorar, depurar e melhorar.

"Estou mostrando não como RAG funciona em geral, mas o caminho de uma

simples chamada a um LLM local para um pequeno projeto backend com um contrato de API, logging, sources, timings e limitações honestas". Esta abordagem muda como você vê o serviço: em vez de "o modelo de alguma forma responde", você obtém "o sistema se comporta de forma previsível."

Honestidade sobre limitações O autor lista explicitamente o que falta

no projeto: autenticação, cache, suporte a carga multi-usuário, CI/CD. Isso torna o artigo mais útil do que a maioria dos tutoriais, onde a seção de limitações não existe ou se resume a um aviso padrão. Negative tests são um tópico separado. O comportamento é verificado com um corpus de documentos vazio, com perguntas sem conteúdo relevante no índice, e ao acessar o índice após adicionar novos arquivos sem reconstruir. Um conjunto mínimo, mas o suficiente para entender exatamente onde o sistema falha.

O que isso significa O artigo preenche uma lacuna específica: a

maioria dos materiais sobre RAG explica teoria ou mostra "hello world" com LangChain. Aqui — um serviço local funcional com ferramentas de observabilidade que pode servir como base para um projeto real.