Executar um modelo na própria máquina pode ampliar o controle dos dados, permitir trabalho offline e baratear experimentos. Isso não torna o serviço automaticamente seguro ou pronto para produção. Uma arquitetura útil separa a API, o runtime de inferência, o modelo de embeddings, o banco vetorial e o ciclo de vida dos documentos; também deixa visíveis latência, memória, autorização e falhas.
A ingestão documental é uma tarefa controlada: extrair arquivos, associar metadados estáveis de origem e versão, segmentar pela estrutura, gerar embeddings e gravar IDs determinísticos. No caminho de consulta, autentique a pessoa, aplique permissões, gere o embedding da pergunta com o modelo compatível, recupere um conjunto limitado de passagens e monte o contexto com referências. Separar os fluxos facilita reindexação, retries e controle de qualidade.
Use o mesmo modelo de embeddings e o mesmo pré-processamento no índice e na consulta. Trocar o modelo ou as dimensões é uma migração: crie uma coleção compatível, compare os resultados e faça a virada de forma explícita. Guarde versões, regras de segmentação e hashes das fontes para explicar como o corpus foi produzido.
| Limite | Decisão operacional | Por que importa |
|---|---|---|
| Entrada | Limitar corpo, prompt e tipos de arquivo | Controla memória, latência e abuso |
| Concorrência | Semáforo de inferência ou fila | Evita esgotar RAM/VRAM em picos |
| Timeout | Orçamentos separados para busca e geração | Evita conexões presas e falhas imprevisíveis |
| Identidade | Autenticar antes dos filtros por cliente | Impede exposição cruzada de documentos |
| Observabilidade | ID, modelo, tempos e status sem prompts sensíveis | Ajuda no diagnóstico sem registrar segredos |
Use o ciclo de vida da aplicação para inicializar clientes compartilhados e encerrá-los corretamente. Evite carregar uma cópia do modelo por worker da API: muitas vezes a memória do modelo é o recurso escasso, não o processamento das requisições. Valide exatamente a configuração de workers e GPU que será operada.
Pesos, tamanho de contexto, lotes, gerações simultâneas e busca vetorial disputam recursos. Quantização pode reduzir memória com uma troca potencial de qualidade; meça a tarefa e tokens por segundo no hardware de destino. Inicialização fria, espera na fila e geração são partes diferentes da latência. Acompanhe cada uma separadamente.
Limite concorrência e tamanho das filas. Se o usuário puder aguardar, retorne um identificador de tarefa e um endpoint de status em vez de manter conexões HTTP ilimitadas. Defina o comportamento com modelo indisponível, disco cheio ou índice em reconstrução. Um serviço local ainda precisa de backup dos documentos e metadados vetoriais, além de restauração testada.
Prenda as portas de inferência e do banco ao loopback ou a uma interface privada protegida; não as exponha diretamente à internet. Defina autenticação, TLS, autorização e limites de taxa em uma fronteira clara. Mantenha chaves fora do repositório e restrinja quais usuários e processos acessam o modelo e os documentos. Revise telemetria, relatórios de falha, uploads temporários e logs, que também podem vazar conteúdo sensível.
Arquivos recuperados podem conter instruções maliciosas. Trate-os como contexto não confiável, não habilite ferramentas sem necessidade explícita e nunca deixe uma passagem conceder autoridade. Implemente retenção e exclusão que removam de forma coerente a fonte e seus trechos derivados.
Monte um conjunto fixo de perguntas, fontes esperadas, critérios de resposta e casos de recusa. Teste recall e ranking da busca separados de fundamentação, precisão das citações e utilidade da resposta. Inclua concorrência, entradas longas, índice vazio, versões antigas, fronteiras de acesso e reinicialização do modelo. Compare alterações de modelo e quantização em qualidade e operação.
Ollama, ChromaDB e FastAPI compõem uma pilha local útil quando cada responsabilidade está clara: a ingestão mantém o corpus, a busca aplica permissões, a inferência tem limites de recurso e a API oferece um contrato confiável. “Local” é uma decisão de implantação, não uma garantia de segurança. Meça qualidade, capacidade e recuperação na máquina e no fluxo que você realmente vai manter.