RAG multilocatário por trás de um gateway de API compatível com OpenAI

Os assistentes de IA voltados para o cliente precisam de geração de recuperação aumentada, mas o RAG se torna mais difícil quando as solicitações fluem por meio de um gateway de API compatível com OpenAI em vez de pela pilha nativa de um provedor de modelo. O gateway deve manter os dados do locatário isolados, preservar as citações entre os provedores de modelo, excluir o conteúdo indexado dentro do prazo e atribuir os custos de incorporação, recuperação e geração ao cliente certo.

A resposta prática é tratar a recuperação como um subsistema de gateway de primeira classe. Não o esconda dentro da integração de um provedor. Mantenha a recuperação separada da geração, forneça a cada solicitação um contexto de recuperação no escopo do locatário, normalize as citações antes de devolvê-las e registre cada etapa faturável em um livro-razão.

O problema do leitor

Uma equipe que cria um assistente de IA para muitos clientes geralmente começa com um fluxo simples: fazer upload de documentos, incorporar blocos, recuperar as principais correspondências, colocar esses trechos no prompt e pedir a um modelo para responder. Isso funciona até que o produto precise de vários fornecedores de modelos, faturamento no nível do cliente, offboarding e auditabilidade.

O risco não está apenas em respostas imprecisas. Os maiores riscos operacionais são erros de namespace do locatário, citações não verificáveis, índices obsoletos após a exclusão de documentos e margens que não podem ser explicadas porque os custos de recuperação desaparecem nos gastos com infraestrutura genérica.

Este artigo separa fatos, recomendações e previsões. Os fatos são capacidades de implementação documentadas pelas APIs atuais do provedor e do banco de dados vetorial. As recomendações são opções de arquitetura para um produto gateway. As previsões indicam onde essa arquitetura provavelmente precisará de flexibilidade à medida que os recursos de recuperação do provedor continuam mudando.

Arquitetura de referência

Um design RAG em nível de gateway deve ter cinco componentes:

• Resolvedor de locatário: mapeia a chave de API de entrada, o espaço de trabalho, a conta do cliente ou o cliente da API do parceiro para um tenant_id canônico.
• Perfil de recuperação: define qual corpus pesquisar, qual modelo de incorporação a ser usado, contagem de resultados, filtros, opções de reclassificação, requisitos de citação e comportamento de fallback.
• Camada do adaptador de recuperação: chama a recuperação do provedor nativo, um banco de dados de vetor externo ou um serviço de pesquisa personalizado por meio de uma interface interna.
• Montagem de prompt e adaptador de geração: passa o contexto recuperado para o provedor de modelo escolhido sem expor detalhes de back-end do vetor aos chamadores.
• Uso e auditoria razão: incorporação de registros, indexação, recuperação, tokens de prompt, tokens de conclusão, inquilino, modelo, provedor e identificadores de rastreamento.

Um contrato de solicitação mínima pode permanecer neutro em termos de provedor:

{
  "tenant_id": "tenant_123",
  "modelo": "modelo compatível com gpt ou compatível com claude",
  "retrieval_profile": "support_docs_v2",
  "citation_required": verdadeiro,
  "mensagens": [
    {"role": "user", "content": "Qual é a nossa política de reembolso para planos anuais?"}
  ]
}

A resposta também deve ser neutra em relação ao provedor:

{
  "answer": "Planos anuais podem ser reembolsados dentro da janela de política configurada...",
  "citações": [
    {
      "source_id": "doc_789",
      "title": "Política de cobrança",
      "url_or_internal_ref": "kb://politica de faturamento",
      "pedaço_id": "pedaço_044",
      "deslocamentos": {"página": 3},
      "pontuação": 0,82,
      "retrieval_provider": "vetor_db",
      "model_provider": "openai_compatível",
      "provider_payload": {}
    }
  ],
  "retrieval_trace_id": "rt_456",
  "inquilino_faturado": "inquilino_123",
  "embedding_usage": nulo,
  "retrieval_usage": {"consultas": 1, "resultados": 6},
  "model_usage": {"input_tokens": 1920, "output_tokens": 180}}

Fato: os recursos de recuperação do provedor não são idênticos

A API Vector Stores da OpenAI oferece suporte a armazenamentos de vetores que podem ser criados, pesquisados, configurados com estratégias de agrupamento, associados a metadados de arquivos e excluídos. A pesquisa de loja de vetores oferece suporte a consultas, filtros, contagens máximas de resultados, opções de classificação, limites de pontuação e controles de reescrita de consultas. Esses controles fornecem aos autores do gateway botões úteis para latência, relevância e custo.

Os controles de dados da plataforma OpenAI também tornam o design do ciclo de vida importante: o conteúdo do cliente em lojas de vetores é retido até ser excluído. Se um locatário desistir ou se um projeto temporário expirar, o gateway não poderá presumir que o provedor removerá automaticamente o conteúdo indexado de acordo com o cronograma de negócios do produto.

A Anthropic expõe um padrão diferente para citações. Os aplicativos podem fornecer blocos de conteúdo de resultados de pesquisa com metadados de fonte e título e, quando as citações estão habilitadas, o modelo pode anexar referências de citação ao texto gerado. Existem restrições práticas: as configurações de citação de resultados de pesquisa são tudo ou nada dentro de uma solicitação, os blocos de resultados de pesquisa suportam conteúdo de texto e a granularidade de citação depende de como o conteúdo é dividido em blocos.

A implicação é direta: um gateway não deve expor a forma de recuperação de um provedor como seu contrato público, a menos que pretenda tornar esse provedor a autoridade de recuperação permanente.

Recomendação: use adaptadores de recuperação, não recuperação. Lock-In

Crie uma interface de adaptador de recuperação interna. O gateway pode oferecer suporte a vários back-ends por trás dele:

• Recuperação de provedor nativo: útil quando um cliente deseja o caminho mais rápido para os recursos de pesquisa de arquivos ou armazenamento de vetores de um provedor.
• Banco de dados de vetores externo: útil quando o produto deve oferecer suporte a muitos provedores de modelo com isolamento de locatário consistente e controles de ciclo de vida.
• Blocos de resultados de pesquisa pré-buscados: úteis quando o gateway monta o texto recuperado e o passa para um provedor que suporta contexto explícito com reconhecimento de citação.

O adaptador deve retornar a mesma estrutura interna, independentemente do back-end:

interface RetrievalResult {
  recuperaçãoTraceId: string;
  inquilinoId: string;
  corpusId: string;
  pedaços: Matriz<{
    sourceId: string;
    título: sequência;
    texto: sequência;
    urlOrInternalRef?: string;
    pedaçoId: string;
    deslocamentos?: {página?: número; byteStart?: número; byteEnd?: número; tokenStart?: número; tokenEnd?: número };
    pontuação?: número;
    metadados: Registro;
    provedorPayload?: desconhecido;
  }>;
  recuperaçãoUso: {
    provedor: string;
    consultaContagem: número;
    contagem de resultados: número;
    Unidades faturáveis?: número;
  };}

Isso permite que a camada de geração receba contexto sem saber se ele veio de armazenamentos de vetores OpenAI, Pinecone, Weaviate, um índice de pesquisa de texto completo de banco de dados ou um recuperador híbrido interno.

O isolamento do locatário começa antes da consulta do vetor

O isolamento do locatário não deve depender de instruções imediatas. Ele deve ser aplicado antes da recuperação, no limite de armazenamento e no limite de consulta.

Para sistemas estilo Pinecone, o padrão de multitenancy documentado é um namespace por locatário em índices sem servidor. As operações do plano de dados têm como alvo um namespace, o que simplifica o isolamento e a desativação do locatário, pois a exclusão do namespace remove os registros desse locatário. A Pinecone também documenta compensações entre namespaces e filtragem de metadados: a filtragem dentro de um grande namespace compartilhado pode verificar mais dados, custar mais e ter um desempenho mais lento do que consultas com escopo de namespace.

Para sistemas no estilo Weaviate, a multilocação armazena cada locatário em um fragmento separado, de modo que os dados de um locatário não sejam visíveis para outro locatário. A exclusão do locatário exclui o fragmento associado. Weaviate também oferece suporte a estados de locatário, como ativo, inativo e descarregado, o que cria uma opção de ciclo de vida para locatários raramente usados.

Lista de verificação de implementação

• Resolva tenant_id a partir da identidade do gateway autenticado, não apenas de um campo de corpo fornecido pelo usuário.
• Mapeie tenant_id para um namespace de vetor, fragmento ou identificador de armazenamento de vetor de provedor por meio de um registro do lado do servidor.
• Rejeite solicitações em que o inquilino da chave de API e o inquilino do corpus solicitado não correspondem.
• Mantenha os corpora públicos compartilhados separados dos corpora do inquilino privado.
• Use a filtragem de metadados para tipo de documento, idioma, área de produto ou intervalo de datas após o limite do inquilino já ter sido selecionado.
• Registre namespace, shard, corpus_id, retrieval_profile e retrieval_trace_id para auditabilidade.

Reserve pesquisa entre inquilinos para explícita fluxos de trabalho administrativos com autorização separada, índices separados ou caminhos de agregação controlados. Não faça da pesquisa entre locatários um efeito colateral acidental dos filtros de metadados.

Normalizar citações como objetos de gateway

As citações são um contrato de produto, não apenas uma decoração. Um assistente de suporte ao cliente, uma ferramenta de redação jurídica ou um assistente de conhecimento interno precisa mostrar por que uma resposta foi produzida e de onde veio o texto de apoio.

O gateway deve normalizar os dados de citação em seu próprio esquema:

{
  "source_id": "doc_123",
  "title": "Termos de reembolso",
  "url_or_internal_ref": "kb://refund-terms",
  "pedaço_id": "pedaço_006",
  "deslocamentos": {"página": 2, "byte_start": 4410, "byte_end": 5020},
  "pontuação": 0,79,
  "retrieval_provider": "weaviate",
  "model_provider": "antrópico",
  "model_provider_citation_payload": {}
}

Mantenha os campos normalizados estáveis e permita extensões específicas do provedor. Alguns provedores exporão detalhes de citação mais ricos do que outros. Alguns citarão blocos de resultados de pesquisa. Alguns citarão arquivos carregados. Alguns não fornecerão o formato de deslocamento exato que seu aplicativo deseja. O gateway deve preservar o que existe sem fingir que cada provedor tem semântica de citação idêntica.

Modo de citação estrito

Quando citation_required for verdadeiro, defina o comportamento de falha antecipadamente. Um modo estrito pode exigir que cada parágrafo factual inclua pelo menos uma citação ou que a resposta final contenha citações de partes recuperadas acima de um limite mínimo de pontuação. Se o provedor modelo selecionado não puder satisfazer o contrato de citação, o gateway deverá falhar rapidamente, usar um provedor compatível ou retornar uma recusa estruturada.

Esta é uma recomendação, não uma regra universal. O modo de citação estrito melhora a confiança, mas pode aumentar recusas, novas tentativas e complexidade de fallback. Para fluxos de trabalho criativos de baixo risco, as citações podem ser opcionais. Para suporte ao cliente ou fluxos de trabalho internos regulamentados, citation_required geralmente deve fazer parte do perfil de recuperação.

O ciclo de vida do índice é um recurso do produto

Os sistemas RAG acumulam dados. Os uploads temporários tornam-se permanentes por acidente. Ex-clientes deixam incorporações. As equipes de produto mudam as estratégias de agrupamento e esquecem de reconstruir índices antigos.Um gateway deve tornar os controles de ciclo de vida explícitos.

Os controles de ciclo de vida recomendados incluem:

• Expiração temporária do corpus: os documentos enviados para uma sessão de curta duração devem ter um carimbo de data/hora de expiração e um trabalho de exclusão.
• Desativação do locatário: a exclusão de um locatário deve enfileirar a exclusão de namespaces, fragmentos, armazenamentos de vetores de provedores e arquivos relacionados objetos.
• Manuseio frio de locatários: onde há suporte, locatários inativos podem ser marcados como inativos ou descarregados para reduzir o uso de recursos.
• Reindexação do controle de versão: armazena modelo de incorporação, política de agrupamento, versão do analisador e indexed_at para cada fragmento.
• Exposição do status de exclusão: os fluxos de trabalho da API do parceiro devem mostrar se exclusão de documento, exclusão de vetor e exclusão do lado do provedor concluído.

O fato importante é que parte do conteúdo do armazenamento de vetores é retido até ser excluído. A recomendação da arquitetura é tornar a exclusão visível e testável, em vez de enterrá-la em um trabalho assíncrono, sem estado voltado para o cliente.

Rastrear três registros de custos

Um único registro de token não é suficiente para RAG. Um gateway precisa de pelo menos três livros razão:

• Custo de incorporação e indexação: análise de documentos, fragmentação, chamadas de incorporação, armazenamento de arquivos, gravações de índice e reindexação.
• Custo de recuperação: leituras de banco de dados de vetores, pesquisa de armazenamento de vetores nativos, reclassificação, reescrita de consulta e expansão de resultados.
• Custo de geração: tokens de entrada de mensagens de usuário e recuperados. contexto, tokens de saída, chamadas de ferramentas, novas tentativas e substitutos.

Isso é especialmente importante para agências, fornecedores de SaaS e equipes de plataforma interna que revendem ou alocam custos de IA. Sem livros separados, as margens RAG tornam-se difíceis de explicar. Um locatário com uso de pequena geração ainda pode ser caro se fizer upload constante de documentos, reindexar grandes corpora ou executar consultas de recuperação amplas.

Cada evento de razão deve incluir tenant_id, customer_id se for diferente, ID de chave de API, retrieval_profile, corpus_id, modelo, provedor, trace_id e unidades faturáveis. Isso permite que a análise de uso responda a questões práticas: quais locatários têm perfis de recuperação caros, quais corpora são obsoletos, quais modelos produzem falhas de citação e quais clientes estão gerando prompts grandes porque a recuperação retorna muito contexto.

Modos de falha para testar

Um subsistema RAG de gateway deve ter testes para os modos de falha que criam danos visíveis ao cliente:

• Citações ausentes: citation_required é verdadeiro, mas a resposta do provedor não contém referências de citação utilizáveis.
• Índices desatualizados: um documento foi atualizado ou excluído, mas partes antigas ainda aparecem nos resultados da recuperação.
• Incompatibilidade de locatário: a solicitação é resolvida para o locatário A, enquanto o corpus ou namespace pertence ao locatário B.
• Recuperação ampla demais: o perfil retorna muitos blocos, aumentando o custo e diluindo qualidade da resposta.
• Incompatibilidade de tamanho dos pedaços: os pedaços são tão grandes que as citações são imprecisas ou tão pequenos que o contexto perde o significado.
• Incompatibilidade de recursos do provedor: um modelo pode emitir citações na forma exigida, enquanto outro não.
• Falha no ciclo de vida: a exclusão é solicitada, mas o armazenamento do lado do provedor permanece ativo ou não verificado.

Esses testes devem ser executados no nível de contrato de gateway, não apenas dentro de um adaptador de provedor. O objetivo é provar que o comportamento público permanece estável quando o back-end de recuperação ou o provedor de geração mudam.

Compensações

A recuperação do provedor nativo pode reduzir o código do aplicativo e acelerar uma primeira versão. A desvantagem é que o ciclo de vida do armazenamento, o formato de citação, os controles de consulta e a disponibilidade de recursos podem ficar vinculados a um único provedor.

Bancos de dados de vetores externos adicionam área de superfície operacional. O benefício é uma portabilidade mais forte entre modelos compatíveis com OpenAI, modelos Antrópicos e fornecedores futuros. Eles também facilitam o raciocínio sobre namespaces ou fragmentos com escopo de locatário sobre quando o gateway é responsável pelo faturamento e pela desativação.

Os pedaços refinados melhoram a precisão da citação e a auditabilidade. Eles também aumentam o tamanho do índice, o volume de recuperação e a complexidade da montagem imediata. Pedaços grosseiros são mais simples, mas podem produzir citações que apontam para uma página ou seção ampla, em vez da passagem de apoio exata.

O modo estrito de citação obrigatória melhora a confiança do usuário.Isso também força o gateway a lidar com modelos que não conseguem produzir o formato de citação exigido, o que pode significar recusar a solicitação, alterar modelos ou retornar uma resposta com um estado de confiança mais baixo.

Predição: a recuperação se tornará mais nativa, mas os gateways ainda precisarão de seu próprio contrato

Os recursos de recuperação nativos do provedor provavelmente se tornarão mais capazes. Mais modelos aceitarão contexto recuperado com metadados de origem estruturados. Mais APIs exporão controles de classificação, reescrita de consultas e configurações de citação. Isso não elimina a necessidade de um contrato de gateway.

O gateway ainda possui a identidade do locatário, o gerenciamento de chaves, os limites de gastos, a análise de uso, os fluxos de trabalho da API do parceiro e as promessas de exclusão voltadas para o cliente. Os recursos do provedor podem ser usados ​​por trás da camada do adaptador, mas o produto não deve forçar cada locatário, modelo e fluxo de trabalho de cobrança na abstração de recuperação de um provedor.

Conclusão acionável

Construa o RAG multilocatário como um subsistema de gateway com limites explícitos. Resolva a identidade do locatário antes da recuperação. Use namespaces, fragmentos ou armazenamentos de vetores com escopo de locatário. Mantenha a recuperação atrás de adaptadores. Normalize as citações em um esquema de propriedade do gateway. Adicione estados de ciclo de vida e verificação de exclusão. Rastreie os custos de incorporação, recuperação e geração separadamente.

Essa arquitetura mantém o RAG fundamentado sem restringir o produto a um provedor de recuperação. Ele também oferece às equipes os controles operacionais necessários quando um assistente de IA passa de um protótipo para um sistema voltado para o cliente: isolamento, citações, portabilidade, gerenciamento do ciclo de vida e atribuição de custos.

Leituras relacionadas

• recuperação de rastreamento, uso de token e análise de locatário em um modelo de observabilidade
• normalizar resultados específicos do provedor por trás de um contrato de gateway estável
• conectar o provisionamento de locatários e a medição de uso aos fluxos de trabalho da API do parceiro