Referência de aplicação. Esta é uma arquitetura ilustrativa e uma lista de verificação de escopo, não um projeto de cliente verificado nem uma implantação com métricas aferidas. As tecnologias, o escopo de integração e os itens de entrega são acordados para o briefing real.
Cenário e restrições
Uma empresa que deseja respostas de IA sobre sua própria documentação de produtos, políticas ou histórico de suporte. Os requisitos que realmente determinam a arquitetura são: as respostas devem citar sua fonte, o sistema deve dizer que não sabe em vez de inventar uma resposta, o custo por conversa deve ser limitado, e a qualidade deve ser mensurável antes e depois de qualquer alteração de prompt ou modelo.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Responsabilidade |
|---|---|---|
| Ingestão | Workers Python | Análise de documentos, divisão em segmentos, geração de embeddings e extração de metadados. Executada como um pipeline, para que uma reindexação seja uma operação rotineira, e não uma reconstrução. |
| Armazenamento vetorial | PostgreSQL + pgvector | Embeddings dos segmentos junto com metadados relacionais. Um banco de dados, em vez de um serviço vetorial separado, mantém permissões e backups simples nessa escala. |
| Recuperação | Serviço Go | Busca híbrida: similaridade vetorial mais correspondência por palavras-chave, seguida de reranking. A recuperação por palavras-chave identifica números exatos de peças e códigos que os embeddings deixam passar regularmente. |
| Geração de respostas | Serviço Go chamando a API do modelo | Montagem do prompt com o contexto recuperado, exigência de citações, resposta em streaming e orçamento de tokens por solicitação. |
| Barreiras de proteção | Camada de aplicação | Verificação de escopo, recusa quando a confiança da recuperação é baixa, filtragem de PII e encaminhamento para uma fila humana. |
| Administração | Painel administrativo em Vue | Gestão de documentos, acionamento de reindexações, revisão de conversas, conjunto de avaliação e painel de custos. |
Modelo de dados
As tabelas abaixo carregam as regras das quais todo o restante depende. Equivocar-se aqui é o que transforma uma demonstração funcional em um sistema que não pode ser ampliado.
Entidades principais
| Entidade | Campos principais, relações e regras |
|---|---|
| documento / versão | Documento de origem com histórico de versões e datas de vigência, para que uma resposta possa ser rastreada até a revisão do documento que a produziu. |
| segmento | Segmento de texto com vetor de embedding, caminho de títulos, contagem de tokens e um ponteiro de volta para o documento e a posição; a posição é o que faz uma citação apontar para o local correto, e não para o arquivo inteiro. |
| access_scope | Quais funções ou locatários podem recuperar um segmento. A filtragem ocorre dentro da consulta de recuperação, nunca depois da geração; caso contrário, conteúdo restrito pode vazar para uma resposta antes que a verificação seja executada. |
| conversa / mensagem | Histórico de interações com ids dos segmentos recuperados, modelo utilizado, contagens de tokens e latência por mensagem, o que permite atribuir custo e qualidade por conversa. |
| feedback | Avaliações, correções e sinalizadores de encaminhamento por resposta, alimentando o conjunto de avaliação em vez de desaparecerem em um arquivo de log. |
| eval_case | Pergunta, fonte esperada e nota de aceitação. Executado a cada alteração de prompt ou modelo, para que regressões sejam identificadas antes do lançamento, e não pelos clientes. |
Interfaces principais
Endpoints que carregam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/ingest | Coloca um documento em fila para análise, divisão em segmentos e geração de embeddings; idempotente por (document, version), para que um novo envio substitua o anterior em vez de duplicá-lo. |
| POST /api/v1/chat | Transmite uma resposta em streaming. Aplica o escopo de acesso à recuperação, limita os tokens de contexto, exige citações e retorna uma recusa quando a confiança da recuperação está abaixo do limite configurado. |
| POST /api/v1/chat/{id}/escalate | Encaminha a conversa, com todo o contexto, para uma fila humana; a válvula de segurança que mantém um sistema com limites honesto, em vez de forçá-lo a responder a tudo. |
| POST /api/v1/eval/run | Executa o conjunto de avaliação com a configuração atual e informa a taxa de aprovação e a precisão das citações por caso. |
| GET /api/v1/usage | Contabilização de tokens e custos por locatário e por período, base para limites de taxa e alertas de orçamento. |
Decisões técnicas
- Recuperação híbrida, não apenas vetorial. A recuperação exclusivamente vetorial pode deixar passar identificadores exatos, como números de peças, códigos de erro ou referências de artigos. Compare as abordagens de recuperação nas perguntas reais do conjunto de avaliação. A correspondência por palavras-chave cobre essa lacuna, e o reranking combina as duas.
- Citações exigidas, não solicitadas. Pedir educadamente a um modelo que cite fontes não é confiável. As respostas são validadas em relação aos ids dos segmentos recuperados e rejeitadas quando não citam nada, o que diferencia um sistema confiável de um sistema apenas plausível.
- Limite de recusa baseado na confiança da recuperação. Uma resposta errada e confiante custa mais do que nenhuma resposta. Abaixo do limite, o sistema informa que não sabe e oferece encaminhamento.
- pgvector em vez de um banco de dados vetorial dedicado. Em volumes de documentos típicos de uma única empresa, uma instância PostgreSQL processa tanto os vetores quanto os metadados, mantendo operações, permissões e backup em um único sistema. Um armazenamento dedicado só justifica sua complexidade em uma escala muito maior.
- Conjunto de avaliação desde a primeira semana. Sem ele, cada alteração de prompt é um palpite e as regressões são descobertas pelos usuários. É o controle de qualidade mais barato em um projeto de IA e o que mais costuma ser ignorado.
- Acesso ao modelo por trás do nosso backend. As chaves de API nunca chegam ao cliente, e limitação de taxa, tetos de orçamento e troca de modelo permanecem como configuração no servidor, em vez de exigirem um lançamento do aplicativo.
Metas hipotéticas de projeto
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados medidos de clientes, recomendação de dimensionamento validada nem um SLA. Defina metas de aceitação específicas do projeto depois de determinar a carga de trabalho, os dispositivos, os dados, o hardware e as dependências de terceiros; valide-as por meio de um piloto e de testes de carga antes de assumir uma meta de produção.
Metas de capacidade e desempenho
| Meta | Valor e premissa |
|---|---|
| Latência do primeiro token | Defina um orçamento hipotético para o primeiro token e, em seguida, faça um benchmark com o provedor escolhido, o pipeline de recuperação e o conjunto de avaliação. A latência do provedor está fora do controle da aplicação; o streaming pode mostrar o progresso sem prometer um tempo de resposta. |
| Recuperação | Menos de 200 ms para busca híbrida mais reranking em um corpus na faixa inferior das centenas de milhares de segmentos, com um índice pgvector apropriado. |
| Custo por conversa | Limitado por um teto de tokens de contexto e por um orçamento por locatário com alertas; o valor real depende da escolha do modelo e da duração da conversa e é medido durante o piloto. |
| Qualidade das respostas | Acompanhada como taxa de aprovação e precisão das citações no conjunto de avaliação. A linha de base é estabelecida durante o piloto, em vez de ser prometida antecipadamente. |
O que a entrega inclui
- Código-fonte do pipeline de ingestão, do serviço de recuperação e geração de respostas e do painel administrativo no seu repositório
- Esquema do banco de dados incluindo tabelas de segmentos, escopo e avaliação, além da configuração de índices
- Modelos de prompt e conjunto de avaliação, ambos versionados junto com o código
- Painel de custos e uso, configuração de limites de taxa e alertas de orçamento
- Notas de implantação, procedimento de gestão de chaves e um caminho documentado para troca de modelo
Planejando isso para sua empresa
Os módulos acima são um ponto de partida, não um pacote fixo. Normalmente reduzimos a primeira versão a um fluxo de trabalho principal e um fluxo administrativo, e depois ampliamos quando o uso real mostra onde estão a carga e os casos-limite. Envie um briefing com o escopo e nós o compararemos com esta arquitetura, informando quais partes você ainda não precisa.