RAG multiinquilino detrás de una puerta de enlace API compatible con OpenAI
Una arquitectura de referencia práctica para crear generación de recuperación aumentada detrás de una puerta de enlace API multimodelo: índices con alcance de inquilino, adaptadores de recuperación neutrales para el proveedor, citas normalizadas, controles del ciclo de vida y atribución de costos.
Los asistentes de IA de cara al cliente necesitan generación de recuperación aumentada, pero RAG se vuelve más difícil cuando las solicitudes fluyen a través de una puerta de enlace API compatible con OpenAI en lugar de la pila nativa de un proveedor de modelo. La puerta de enlace debe mantener aislados los datos de los inquilinos, preservar las citas entre los proveedores de modelos, eliminar el contenido indexado a tiempo y atribuir los costos de incrustación, recuperación y generación al cliente correcto.
La respuesta práctica es tratar la recuperación como un subsistema de puerta de enlace de primera clase. No lo ocultes dentro de la integración de un proveedor. Mantenga la recuperación separada de la generación, proporcione a cada solicitud un contexto de recuperación centrado en el inquilino, normalice las citas antes de devolverlas y registre cada paso facturable en un libro mayor.
El problema del lector
Un equipo que crea un asistente de IA para muchos clientes generalmente comienza con un flujo simple: cargar documentos, incrustar fragmentos, recuperar las coincidencias principales, colocar esos fragmentos en el mensaje y pedirle a un modelo que responda. Eso funciona hasta que el producto necesita múltiples proveedores de modelos, facturación a nivel de cliente, baja y auditabilidad.
El riesgo no son solo respuestas inexactas. Los mayores riesgos operativos son errores en el espacio de nombres de los inquilinos, citas no verificables, índices obsoletos después de la eliminación de documentos y márgenes que no se pueden explicar porque los costos de recuperación desaparecen en el gasto en infraestructura genérica.
Este artículo separa hechos, recomendaciones y predicciones. Los hechos son capacidades de implementación documentadas por las API de bases de datos vectoriales y de proveedores actuales. Las recomendaciones son opciones de arquitectura para un producto de puerta de enlace. Las predicciones indican que es probable que esta arquitectura necesite flexibilidad a medida que las características de recuperación del proveedor siguen cambiando.
Arquitectura de referencia
Un diseño RAG a nivel de puerta de enlace debe tener cinco componentes:
- Resolución de inquilinos: asigna la clave de API entrante, el espacio de trabajo, la cuenta de cliente o el cliente de API de socio a un id de inquilino canónico.
- Perfil de recuperación: define qué corpus buscar, cuál incorporación del modelo a utilizar, recuento de resultados, filtros, opciones de reclasificación, requisitos de citación y comportamiento alternativo.
- Capa de adaptador de recuperación: llama a la recuperación del proveedor nativo, una base de datos vectorial externa o un servicio de búsqueda personalizado a través de una interfaz interna.
- Adaptador de generación y ensamblaje rápido: pasa el contexto recuperado al proveedor del modelo elegido sin exponer los detalles del backend vectorial a los llamantes.
- Uso y auditoría Libro mayor: registros de incrustación, indexación, recuperación, tokens de aviso, tokens de finalización, inquilino, modelo, proveedor e identificadores de seguimiento.
Un contrato de solicitud mínima puede permanecer neutral con respecto al proveedor:
{
"tenant_id": "tenant_123",
"modelo": "modelo-compatible-gpt-o-compatible-claude",
"retrieval_profile": "support_docs_v2",
"citation_required": verdadero,
"mensajes": [
{"role": "user", "content": "¿Cuál es nuestra política de reembolso para planes anuales?"}
]
}La respuesta también debe ser neutral en cuanto al proveedor:
{
"answer": "Los planes anuales se pueden reembolsar dentro de la ventana de política configurada...",
"citas": [
{
"source_id": "doc_789",
"title": "Política de facturación",
"url_or_internal_ref": "kb://política-de-facturación",
"chunk_id": "chunk_044",
"compensaciones": {"página": 3},
"puntuación": 0,82,
"retrieval_provider": "vector_db",
"model_provider": "openai_compatible",
"provider_payload": {}
}
],
"retrieval_trace_id": "rt_456",
"billable_tenant": "tenant_123",
"embedding_usage": nulo,
"retrieval_usage": {"consultas": 1, "resultados": 6},
"model_usage": {"input_tokens": 1920, "output_tokens": 180}}Hecho: Las funciones de recuperación de proveedores no son idénticas
La API Vector Stores de OpenAI admite almacenes de vectores que se pueden crear, buscar, configurar con estrategias de fragmentación, asociar con metadatos de archivos y eliminar. La búsqueda en el almacén de vectores admite consultas, filtros, recuentos máximos de resultados, opciones de clasificación, umbrales de puntuación y controles de reescritura de consultas. Esos controles brindan a los autores de puertas de enlace controles útiles para la latencia, la relevancia y el costo.
Los controles de datos de la plataforma OpenAI también hacen que el diseño del ciclo de vida sea importante: el contenido del cliente en los almacenes de vectores se conserva hasta que se elimina. Si un inquilino se retira, o si un proyecto temporal vence, la puerta de enlace no puede asumir que el proveedor eliminará el contenido indexado automáticamente según el cronograma comercial del producto.
Anthropic expone un patrón diferente para las citas. Las aplicaciones pueden proporcionar bloques de contenido de resultados de búsqueda con metadatos de fuente y título, y cuando las citas están habilitadas, el modelo puede adjuntar referencias de citas al texto generado. Existen restricciones prácticas: la configuración de citas de resultados de búsqueda es de todo o nada dentro de una solicitud, los bloques de resultados de búsqueda admiten contenido de texto y la granularidad de las citas depende de cómo se divide el contenido en bloques.
La implicación es directa: una puerta de enlace no debe exponer la forma de recuperación de un proveedor como su contrato público a menos que pretenda convertir a ese proveedor en la autoridad de recuperación permanente.
Recomendación: utilice adaptadores de recuperación, no recuperación Lock-In
Crea una interfaz de adaptador de recuperación interna. La puerta de enlace puede admitir varios backends detrás de ella:
- Recuperación de proveedor nativo: útil cuando un cliente desea la ruta más rápida a las funciones de búsqueda de archivos o almacén de vectores de un proveedor.
- Base de datos vectorial externa: útil cuando el producto debe admitir muchos proveedores de modelos con aislamiento de inquilinos y controles de ciclo de vida coherentes.
- Bloques de resultados de búsqueda precargados: útiles cuando la puerta de enlace reúne texto recuperado y lo pasa a un proveedor que admite contexto explícito de citas.
El adaptador debe devolver la misma estructura interna independientemente del backend:
interface RetrievalResult {
recuperaciónTraceId: cadena;
ID de inquilino: cadena;
ID de corpus: cadena;
fragmentos: Matriz<{
ID de fuente: cadena;
título: cadena;
texto: cadena;
urlOrInternalRef?: cadena;
trozoId: cadena;
¿compensaciones?: { ¿página?: número; byteInicio?: número; byteEnd?: número; tokenStart?: número; tokenEnd?: número };
puntuación?: número;
metadatos: Registro;
¿Carga útil del proveedor?: desconocido;
}>;
uso de recuperación: {
proveedor: cadena;
queryCount: número;
resultadoCount: número;
¿Unidades facturables?: número;
};} Esto permite que la capa de generación reciba contexto sin saber si proviene de almacenes de vectores OpenAI, Pinecone, Weaviate, un índice de búsqueda de texto completo de una base de datos o un recuperador híbrido interno.
El aislamiento de inquilinos comienza antes de la consulta vectorial
El aislamiento de inquilinos no debe depender de instrucciones rápidas. Debe aplicarse antes de la recuperación, en el límite de almacenamiento y en el límite de consulta.
Para los sistemas estilo Pinecone, el patrón de tenencia múltiple documentado es un espacio de nombres por inquilino en índices sin servidor. Las operaciones del plano de datos tienen como objetivo un espacio de nombres, lo que simplifica el aislamiento y la eliminación de inquilinos porque al eliminar el espacio de nombres se eliminan los registros de ese inquilino. Pinecone también documenta las compensaciones entre los espacios de nombres y el filtrado de metadatos: el filtrado dentro de un espacio de nombres compartido grande puede escanear más datos, costar más y funcionar más lentamente que las consultas con ámbito de espacio de nombres.
Para los sistemas de estilo Weaviate, el arrendamiento múltiple almacena a cada inquilino en un fragmento separado, por lo que los datos de un inquilino no son visibles para otro inquilino. La eliminación del inquilino elimina el fragmento asociado. Weaviate también admite estados de inquilinos como activo, inactivo y descargado, lo que crea una opción de ciclo de vida para inquilinos que se utilizan con poca frecuencia.
Lista de verificación de implementación
- Resuelva el id_inquilino a partir de la identidad de la puerta de enlace autenticada, no solo desde un campo de cuerpo proporcionado por el usuario.
- Asigne el id_inquilino a un espacio de nombres vectorial, un fragmento o un identificador de almacén de vectores del proveedor a través de un registro del lado del servidor.
- Rechazar solicitudes en las que el inquilino de la clave API y el inquilino del corpus solicitado no coinciden.
- Mantenga los corpus públicos compartidos separados de los corpus de inquilinos privados.
- Utilice el filtrado de metadatos para el tipo de documento, idioma, área de producto o intervalo de fechas después de que ya se haya seleccionado el límite del inquilino.
- Registrar espacio de nombres, fragmento, corpus_id, retrieval_profile y retrieval_trace_id para auditabilidad.
Reservar Búsqueda entre inquilinos para flujos de trabajo administrativos explícitos con autorización separada, índices separados o rutas de agregación controladas. No haga que la búsqueda entre inquilinos sea un efecto secundario accidental de los filtros de metadatos.
Normalice las citas como objetos de puerta de enlace
Las citas son un contrato de producto, no solo una decoración. Un asistente de atención al cliente, una herramienta de redacción legal o un asistente de conocimiento interno deben mostrar por qué se produjo una respuesta y de dónde proviene el texto de respaldo.
La puerta de enlace debe normalizar los datos de citas en su propio esquema:
{
"source_id": "doc_123",
"title": "Términos de reembolso",
"url_or_internal_ref": "kb://condiciones-de-reembolso",
"chunk_id": "chunk_006",
"compensaciones": {"página": 2, "byte_start": 4410, "byte_end": 5020},
"puntuación": 0,79,
"retrieval_provider": "weaviate",
"model_provider": "antrópico",
"model_provider_citation_payload": {}
}Mantenga estables los campos normalizados y permita extensiones específicas del proveedor. Algunos proveedores expondrán detalles de citas más completos que otros. Algunos citarán bloques de resultados de búsqueda. Algunos citarán archivos cargados. Algunos no proporcionarán el formato de compensación exacto que desea su aplicación. La puerta de enlace debe preservar lo que existe sin pretender que cada proveedor tenga una semántica de citas idéntica.
Modo de citación estricto
Cuando citation_required sea verdadero, defina el comportamiento de falla por adelantado. Un modo estricto puede requerir que cada párrafo fáctico incluya al menos una cita, o que la respuesta final contenga citas de fragmentos recuperados por encima de un umbral de puntuación mínimo. Si el proveedor del modelo seleccionado no puede cumplir con el contrato de citación, la puerta de enlace debería fallar rápidamente, utilizar un proveedor compatible o devolver un rechazo estructurado.
Esta es una recomendación, no una regla universal. El modo de citación estricto mejora la confianza, pero puede aumentar los rechazos, los reintentos y la complejidad de las alternativas. Para flujos de trabajo creativos de bajo riesgo, las citas pueden ser opcionales. Para soporte de cara al cliente o flujos de trabajo internos regulados, citation_required a menudo debe ser parte del perfil de recuperación.
El ciclo de vida del índice es una característica del producto
Los sistemas RAG acumulan datos. Las cargas temporales se vuelven permanentes por accidente. Los antiguos clientes dejan atrás las incrustaciones. Los equipos de productos cambian las estrategias de fragmentación y se olvidan de reconstruir los índices antiguos.Una puerta de enlace debe hacer que los controles del ciclo de vida sean explícitos.
Los controles del ciclo de vida recomendados incluyen:
- Caducidad temporal del corpus: los documentos cargados para una sesión de corta duración deben tener una marca de tiempo de caducidad y un trabajo de eliminación.
- Desconexión de inquilinos: la eliminación de un inquilino debe poner en cola la eliminación de espacios de nombres, fragmentos, almacenes de vectores de proveedores y archivos relacionados. objetos.
- Manejo de inquilinos en frío: cuando sea compatible, los inquilinos inactivos se pueden marcar como inactivos o descargarse para reducir el uso de recursos.
- Control de versiones de reindexación: almacene el modelo de incrustación, la política de fragmentación, la versión del analizador y indexed_at para cada fragmento.
- Exposición del estado de eliminación: Los flujos de trabajo de la API del socio deben mostrar si la eliminación de documentos, la eliminación de vectores y el lado del proveedor eliminación completada.
El hecho importante es que parte del contenido de la tienda de vectores se conserva hasta que se elimina. La recomendación de arquitectura es hacer que la eliminación sea visible y comprobable en lugar de enterrarla en un trabajo asincrónico sin estado de cara al cliente.
Seguimiento de tres libros de contabilidad de costos
Un libro de contabilidad de token único no es suficiente para RAG. Una puerta de enlace necesita al menos tres libros de contabilidad:
- Costo de incrustación e indexación: análisis de documentos, fragmentación, incrustación de llamadas, almacenamiento de archivos, escrituras de índice y reindexación.
- Costo de recuperación: lecturas de bases de datos vectoriales, búsqueda en el almacén de vectores nativos, reclasificación, reescritura de consultas y expansión de resultados.
- Costo de generación: tokens de entrada de mensajes de usuario y contexto recuperado, tokens de salida, llamadas a herramientas, reintentos y alternativas.
Esto es especialmente importante para agencias, proveedores de SaaS y equipos de plataformas internas que revenden o asignan costos de IA. Sin libros de contabilidad separados, los márgenes de RAG resultan difíciles de explicar. Un inquilino con un uso de generación pequeña aún puede resultar costoso si carga documentos constantemente, reindexa grandes corpus o ejecuta consultas de recuperación amplias.
Cada evento del libro mayor debe incluir id_inquilino, id_cliente si es diferente, id. de clave API, perfil_recuperación, id_corpus, modelo, proveedor, id_rastreo y unidades facturables. Esto permite que el análisis de uso responda preguntas prácticas: qué inquilinos tienen perfiles de recuperación costosos, qué corpus están obsoletos, qué modelos producen fallas en las citas y qué clientes generan mensajes de gran tamaño porque la recuperación devuelve demasiado contexto.
Modos de falla para probar
Un subsistema RAG de puerta de enlace debe tener pruebas para los modos de falla que crean daños visibles para el cliente:
- Citas faltantes: citation_required es verdadero, pero la respuesta del proveedor no contiene referencias de citas utilizables.
- Índices obsoletos: un documento se actualizó o eliminó, pero todavía aparecen fragmentos antiguos en los resultados de recuperación.
- No coinciden los inquilinos: la solicitud se resuelve en el inquilino A, mientras que el corpus o espacio de nombres pertenece al inquilino B.
- Recuperación demasiado amplia: el perfil devuelve demasiadas fragmentos, lo que aumenta el costo y diluye la calidad de las respuestas.
- Discordancia en el tamaño de los fragmentos: los fragmentos son tan grandes que las citas son imprecisas, o tan pequeños que el contexto pierde significado.
- Discordancia de características del proveedor: un modelo puede emitir citas en la forma requerida mientras que otro no.
- Error en el ciclo de vida: se solicita la eliminación, pero el almacenamiento del lado del proveedor permanece activo o no verificado.
Estas pruebas deben ejecutarse en el nivel del contrato de puerta de enlace, no solo dentro de un adaptador de proveedor. El objetivo es demostrar que el comportamiento público permanece estable cuando cambia el backend de recuperación o el proveedor de generación.
Compensaciones
La recuperación del proveedor nativo puede reducir el código de la aplicación y acelerar una primera versión. La desventaja es que el ciclo de vida del almacenamiento, el formato de las citas, los controles de consulta y la disponibilidad de las funciones pueden quedar vinculados a un solo proveedor.
Las bases de datos vectoriales externas añaden una superficie operativa. El beneficio es una mayor portabilidad entre modelos compatibles con OpenAI, modelos Anthropic y futuros proveedores. También hacen que sea más fácil razonar sobre los espacios de nombres o fragmentos con ámbito de inquilino sobre cuándo la puerta de enlace es responsable de la facturación y la baja.
Los fragmentos detallados mejoran la precisión y la auditabilidad de las citas. También aumentan el tamaño del índice, el volumen de recuperación y la complejidad del ensamblaje rápido. Los fragmentos gruesos son más simples, pero pueden producir citas que apunten a una página o sección amplia en lugar del pasaje de respaldo exacto.
El modo estricto de cita requerida mejora la confianza del usuario.También obliga a la puerta de enlace a manejar modelos que no pueden producir el formato de cita requerido, lo que puede significar rechazar la solicitud, cambiar los modelos o devolver una respuesta con un estado de confianza más bajo.
Predicción: la recuperación será más nativa, pero las puertas de enlace aún necesitan su propio contrato
Es probable que las funciones de recuperación nativas del proveedor sean más capaces. Más modelos aceptarán contexto recuperado con metadatos de origen estructurados. Más API expondrán controles de clasificación, reescritura de consultas y configuraciones de citas. Eso no elimina la necesidad de un contrato de puerta de enlace.
La puerta de enlace aún posee la identidad del inquilino, la administración de claves, los límites de gasto, el análisis de uso, los flujos de trabajo de API de socios y las promesas de eliminación de cara al cliente. Las funciones del proveedor se pueden utilizar detrás de la capa del adaptador, pero el producto no debe forzar a cada inquilino, modelo y flujo de trabajo de facturación a la abstracción de recuperación de un proveedor.
Conclusión práctica
Construya RAG multiinquilino como un subsistema de puerta de enlace con límites explícitos. Resolver la identidad del inquilino antes de la recuperación. Utilice espacios de nombres, fragmentos o almacenes de vectores con ámbito de inquilino. Mantenga la recuperación detrás de los adaptadores. Normalice las citas en un esquema propiedad de la puerta de enlace. Agregue estados del ciclo de vida y verificación de eliminación. Realice un seguimiento de los costos de incorporación, recuperación y generación por separado.
Esta arquitectura mantiene RAG conectado a tierra sin bloquear el producto a un solo proveedor de recuperación. También brinda a los equipos los controles operativos que necesitan cuando un asistente de IA pasa de un prototipo a un sistema orientado al cliente: aislamiento, citas, portabilidad, gestión del ciclo de vida y atribución de costos.