Control de caché rápido en una puerta de enlace API multimodelo: prefijos estables, aislamiento de inquilinos y análisis de visitas de caché

El almacenamiento en caché rápido es fácil de desperdiciar. Un equipo puede tener un mensaje del sistema de 40.000 tokens, un esquema de herramienta, un bloque de políticas, un mapa de repositorio o una memoria de agente que debería ser reutilizable y luego, accidentalmente, colocar una marca de tiempo, un ID de solicitud, un nombre de usuario, un fragmento de recuperación o un orden aleatorio de herramientas cerca de la parte superior del mensaje. El proveedor ve un prefijo diferente, se pierde el caché, la latencia aumenta y la factura parece confusa.

En una aplicación de un solo proveedor, puede solucionar este problema dentro de la plantilla de la aplicación. En una puerta de enlace multimodelo, el problema es mayor: cada proveedor expone diferentes controles de caché, umbrales de token, comportamiento de tiempo de vida, campos de uso y semántica de facturación. La puerta de enlace necesita un patrón de plano de control portátil para ensamblar mensajes seguros para la caché, medir el comportamiento de la caché, aislar inquilinos y atribuir costos.

Este artículo describe una arquitectura de referencia. No es un estudio de caso de cliente y no pretende obtener resultados comparativos. Los hechos a continuación provienen de documentación de proveedores e investigaciones públicas; las recomendaciones de diseño son una guía operativa a nivel de puerta de enlace.

El modo de falla: ensamblaje de avisos para romper el caché

El almacenamiento en caché de mensajes generalmente recompensa los prefijos de mensajes repetidos. La mecánica exacta varía según el proveedor, pero la implicación práctica es consistente: si el frente del mensaje cambia, la reutilización se ve afectada.

Los disyuntores de caché más comunes incluyen:

• Metadatos por solicitud en la parte superior: marcas de tiempo, ID de seguimiento, ID de sesión, ID de implementación o etiquetas de solicitud generadas.
• Datos específicos del usuario en el prefijo: nombres, atributos de cuenta, permisos o preferencias privadas colocados antes de políticas reutilizables o bloques de herramientas.
• Serialización de herramientas inestable: esquemas de herramientas emitidos en orden no determinista, con espacios en blanco cambiantes o ID generados.
• Fragmentos de recuperación demasiado pronto: contexto RAG insertado antes de instrucciones estables del sistema o contexto de repositorio compartido.
• Desviación de la plantilla: pequeños cambios de redacción se publican con frecuencia sin control de versiones ni diagnóstico de caché.

Una puerta de enlace no puede hacer que un prefijo inestable se pueda almacenar en caché por arte de magia, pero puede imponer un contrato de ensamblaje rápido y hacer visibles los errores de caché.

Datos sobre proveedores para diseñar

Los detalles son importantes porque una puerta de enlace debe normalizar el comportamiento sin pretender que los proveedores sean idénticos.

• OpenAI: OpenAI ha documentado el almacenamiento en caché de mensajes para el prefijo de mensajes más largo calculado anteriormente. Comienza con 1024 tokens, aumenta en incrementos de 128 tokens y expone los recuentos de tokens almacenados en caché en los campos de uso. OpenAI también afirma que los cachés de avisos generalmente se borran después de 5 a 10 minutos de inactividad y siempre se eliminan dentro de una hora después del último uso del caché.
• Antrópico: el almacenamiento en caché del mensaje antrópico se puede solicitar con cache_control. Su documentación describe la coincidencia de caché entre componentes de aviso, como herramientas, contenido del sistema y mensajes hasta el bloque marcado con control de caché. Anthropic documenta un caché efímero, que incluye una duración de 5 minutos y una opción de 1 hora con costo adicional.
• Gemini: el almacenamiento en caché de contexto de Google Gemini expone los recuentos de tokens de aciertos de caché a través de metadatos de uso como total_cached_tokens, y su documentación enumera los recuentos mínimos de tokens de entrada por modelo.
• Implicación del control de datos: la documentación de control de datos de la API de OpenAI señala que el almacenamiento en caché de avisos extendido requiere almacenar tensores clave/valor como estado de la aplicación en el almacenamiento local de la GPU. Incluso cuando los proveedores mantienen garantías de aislamiento, las puertas de enlace deben tratar el comportamiento de la caché como una infraestructura confidencial, no como un almacén de datos de aplicaciones compartidas.
• Señal de investigación: Una investigación pública ha examinado si las arquitecturas de estilo puerta de enlace pueden introducir vulnerabilidades de almacenamiento en caché rápido que eluden los supuestos de aislamiento de caché a nivel de proveedor. Eso no prueba que una puerta de enlace específica sea vulnerable, pero respalda un diseño conservador de aislamiento de inquilinos.

Recomendación: implemente el control de caché como una función de puerta de enlace con políticas explícitas, no como un efecto secundario accidental de solicitudes repetidas.

Un contrato de montaje rápido en tres regiones

La decisión de diseño más importante es separar el contenido estable y volátil antes de que la solicitud llegue a un adaptador de proveedor.

Región 1: prefijo estable

El prefijo estable es el contenido que se espera que permanezca idéntico en muchas solicitudes para la misma aplicación, ruta modelo y versión de plantilla de solicitud. Los ejemplos incluyen:

• instrucciones principales del sistema;
• bloqueos de políticas y seguridad;
• esquemas de herramientas;
• documentación estática del producto;
• mapas de repositorio para agentes de codificación;
• Instrucciones de formato de salida fijo.

Esta región debería ser determinista. La puerta de enlace debe construirlo a partir de plantillas versionadas, JSON canonicalizado y reglas de ordenamiento estables. Si se incluye un registro de herramientas, ordene las herramientas por ID de herramienta estable. Si se incluyen esquemas JSON, serialícelos con un orden de claves determinista y sin marcas de tiempo generadas.

Región 2: inquilino semiestable o contexto de espacio de trabajo

La región semiestable cambia con menos frecuencia que las solicitudes individuales, pero no se comparte globalmente. Los ejemplos incluyen:

• anulaciones de políticas específicas de inquilinos;
• listas permitidas de herramientas a nivel de espacio de trabajo;
• Terminología específica del cliente;
• convenciones de codificación del equipo;
• Contexto de proyecto de larga duración.

Esta región debe tener como ámbito un inquilino, un espacio de trabajo o un límite de aplicación. Es posible que aún se pueda almacenar en caché, pero la puerta de enlace nunca debe asumir que otro inquilino puede reutilizarlo de forma segura.

Región 3: sufijo volátil

El sufijo volátil es la parte por solicitud:

• mensaje de usuario;
• fragmentos recuperados para esta consulta;
• marca de tiempo actual, si realmente es necesario;
• ID de solicitud y metadatos de seguimiento, si se incluyen en el mensaje;
• giros de conversación a corto plazo;
• Resultados de la herramienta en tiempo de ejecución.

La mayoría de los errores de caché causados por el diseño de la aplicación ocurren porque los datos de sufijos volátiles se colocan accidentalmente en el prefijo. Un constructor del lado de la puerta de enlace debería hacerlo difícil.

Patrón de implementación: constructores de prefijos estables

Una implementación práctica de puerta de enlace puede exponer una interfaz de ensamblaje de mensajes en lugar de aceptar una cadena de mensajes opaca de cada aplicación.

{
  "template_id": "agente-de-código-v3",
  "tenant_id": "tenant_123",
  "ruta": "codificación-largo-contexto",
  "prefijo_estable": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "herramientas-v12",
    "repo_context_version": "repo-map-8491"
  },
  "contexto_semi_estable": {
    "workspace_policy_version": "espacio de trabajo-44-v6"
  },
  "sufijo_volatil": {
    "user_message": "Explica por qué falla esta prueba...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

La puerta de enlace luego presenta la solicitud específica del proveedor. Esto le da a la puerta de enlace un lugar para hacer cumplir las reglas:

• rechazar marcas de tiempo en campos de prefijo estables;
• canonicalizar esquemas de herramientas;
• hash cada región por separado;
• adjuntar controles de caché cuando un proveedor los admita;
• preservar la semántica del mensaje mientras se mueve material volátil más adelante;
• plantilla de registro y prefijo de huellas dactilares para diagnóstico.

Para las aplicaciones heredadas que envían solo mensajes sin procesar, la puerta de enlace aún puede proporcionar un modo lint: inspeccionar el orden de los mensajes, calcular las huellas digitales de los prefijos e informar sobre posibles disyuntores de caché sin tener que reescribir el mensaje inicialmente.

Capa de adaptador de proveedor: normaliza el uso de la caché sin ocultar diferencias

Una puerta de enlace multimodelo no debería exponer a los desarrolladores tres informes de caché no relacionados. Tampoco debería reducir la economía específica del proveedor de manera tan agresiva que las facturas sean imposibles de explicar.

Cree un libro mayor de caché normalizado con campos como:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "agente de código",
  "ruta": "codificación-largo-contexto",
  "proveedor": "nombre_proveedor",
  "modelo": "model_id",
  "template_id": "agente-de-código-v3",
  "stable_prefix_hash": "sha256:...",
  "semi_stable_hash": "sha256:...",
  "input_tokens_total": 58200,
  "input_tokens_uncached": 8200,
  "cache_write_tokens": 50000,
  "cache_read_tokens": 0,
  "tokens_salida": 1300,
  "cache_ttl_class": "efímero_5m",
  "provider_cache_fields": {
    "raw_field_names": "uso_del_proveedor_almacenado_o_redactado"
  }
}

El adaptador asigna el uso del proveedor a categorías normalizadas:

• Tokens de entrada sin caché: tokens procesados sin descuento de lectura de caché ni contabilidad de lectura de caché.
• Tokens de escritura de caché: tokens que crearon o actualizaron una entrada de caché del lado del proveedor cuando el proveedor informa esta distinción.
• Tokens de lectura de caché: tokens servidos desde la caché o contados como almacenados en caché según los metadatos de uso del proveedor.
• Tokens de salida: tokens generados, que deben permanecer separados de la economía de caché inmediata.
• Opción TTL: la clase de duración de caché seleccionada donde un proveedor expone una elección.

Recomendación: almacene el uso del proveedor sin procesar en un formulario redactado con versión de esquema junto con campos normalizados. La normalización es útil para los paneles; Los campos sin formato son necesarios para la conciliación cuando cambia la semántica del proveedor.

Observabilidad de la caché: paneles que explican los errores

Un útil panel de caché hace más que mostrar el total de tokens almacenados en caché. Debería ayudar a los equipos a responder: "¿Qué carga de trabajo está rompiendo el prefijo y qué cambió?"

Seguimiento de las métricas de caché mediante:

• inquilino;
• espacio de trabajo o aplicación;
• ruta modelo;
• proveedor y modelo;
• versión de plantilla inmediata;
• hash de prefijo estable;
• hash de contexto semiestable;
• Clave API o cuenta de servicio, cuando corresponda;
• ventana de tiempo, especialmente porque los TTL de caché son cortos para muchas cargas de trabajo.

Las métricas derivadas útiles incluyen:

• Tasa de lectura de caché: tokens de entrada almacenados en caché divididos por el total de tokens de entrada elegibles para el almacenamiento en caché.
• Abandono de prefijos: número de hashes de prefijos estables distintos por versión de plantilla por hora.
• Desviación de la plantilla: cambios en el caché después del lanzamiento de una plantilla.
• Costo de inicio en frío: escritura en caché o gasto de entrada sin caché para la primera solicitud en una ráfaga.
• Comparación de rutas: tasas de aciertos entre rutas de proveedores para la misma carga de trabajo lógica.

No utilice de forma predeterminada el almacenamiento de mensajes sin procesar para la depuración. Prefiere hashes, longitudes de regiones, ID de plantillas, advertencias de canonicalización y diferencias redactadas. Si un equipo necesita una depuración más profunda, solicite controles de acceso explícitos y límites de retención.

Política de aislamiento de inquilinos: no diseñar para la reutilización entre inquilinos

La suposición de la puerta de enlace más segura es simple: el comportamiento almacenable en caché debe estar limitado al inquilino. Incluso si dos inquilinos comparten un bloque de políticas públicas idéntico, la puerta de enlace no debe enrutar ni configurar el tráfico intencionalmente para explotar la reutilización de la caché entre inquilinos.

Una política conservadora incluye:

• Enrutamiento según el inquilino: enruta el tráfico que se puede almacenar en caché utilizando los límites del inquilino, el espacio de trabajo y la aplicación.
• Sin prefijos que contengan secretos compartidos: nunca coloque secretos de inquilinos, credenciales, documentos privados o datos específicos del usuario en un prefijo compartido reutilizable.
• Huellas digitales de prefijo separadas: calcula las huellas digitales con el alcance del inquilino incluido en el libro mayor de la puerta de enlace, incluso si el texto representado es idéntico.
• Controles a nivel de organización: permiten a los administradores desactivar las funciones de caché del proveedor para cargas de trabajo confidenciales.
• El aislamiento de proveedores no es una característica del producto para revender: trate el aislamiento de caché de proveedores como una protección básica, no como un permiso para crear grupos de caché entre clientes.

Predicción: a medida que los agentes de contexto largo se vuelvan más comunes, el comportamiento de la caché pasará a formar parte de las revisiones de seguridad, no solo de las revisiones de costos. Las puertas de enlace que puedan demostrar una política de caché centrada en el inquilino serán más fáciles de gobernar.

Atribución de facturación: lecturas, escrituras y tokens normales de caché separados

El almacenamiento en caché rápido puede hacer que las facturas sean más difíciles de entender si todos los tokens de entrada se muestran como un solo número. El libro de facturación debe conservar al menos cinco categorías:

1. tokens de entrada sin caché;
2. tokens de escritura en caché;
3. tokens de lectura en caché;
4. tokens de salida;
5. Cargos TTL o de control de caché específicos del proveedor.

Esto es importante cuando un proveedor descuenta las lecturas en caché, otro cobra de manera diferente por las escrituras en caché y otro expone una opción TTL más larga. La factura de un cliente debería poder explicar por qué dos solicitudes con tokens de entrada totales similares tenían costos diferentes.

Para contracargos internos, atribuya los efectos de caché al inquilino y a la aplicación que realizó la solicitud. Evite asignar un beneficio de lectura de caché de un inquilino a otro. Si un equipo de plataforma interna compartida posee la plantilla de aviso estable, informe el rendimiento de la caché a nivel de plantilla por separado de las facturas de los inquilinos.

Lista de verificación de eliminación de caché

Antes de habilitar la aplicación de caché, ejecute plantillas de aviso a través de una lista de verificación de pelusa:

• Las instrucciones del sistema estable aparecen antes de la entrada volátil del usuario.
• Los esquemas de herramientas están ordenados por ID o nombre estable.
• JSON se serializa de forma determinista.
• No aparecen marcas de tiempo, ID aleatorios, ID de solicitud ni ID de seguimiento en el prefijo estable.
• No aparecen secretos específicos del usuario en los bloques reutilizables compartidos.
• Los fragmentos de RAG se colocan después de las secciones de políticas y herramientas reutilizables, a menos que exista una razón deliberada para no hacerlo.
• Las plantillas de mensajes tienen versiones explícitas.
• Las versiones de plantillas se pueden correlacionar con cambios en la tasa de aciertos de caché.
• Los controles de caché del proveedor se utilizan únicamente a través del código del adaptador, no de la lógica de la aplicación dispersa.
• El registro de avisos sin formato está deshabilitado de forma predeterminada o protegido por reglas estrictas de retención y acceso.

Plan de implementación

1. Observe antes de cambiar las indicaciones

Comience recopilando campos de uso del proveedor y métricas de caché normalizadas para el tráfico existente. Calcule las huellas digitales de prefijo para los primeros N tokens o para las regiones de aviso definidas por la puerta de enlace. El objetivo es encontrar rutas de gran volumen y contexto largo con una alta rotación de prefijos.

2. Clasificar cargas de trabajo

Agrupe el tráfico en categorías: sesiones de agentes, asistentes de codificación, RAG, automatización de soporte, análisis de documentos, trabajos por lotes y chat breve. El trabajo de caché rápido generalmente presta más atención a las cargas de trabajo de contexto largo y prefijos repetidos. Es posible que las indicaciones breves por debajo de los umbrales del proveedor no resulten beneficiosas.

3. Introducir constructores de prefijos estables

Mueva una carga de trabajo de la construcción rápida sin formato al ensamblaje basado en regiones. Mantenga la solicitud del proveedor representada semánticamente equivalente. No combine este cambio con la migración del modelo, el rediseño de herramientas o reescrituras importantes de mensajes, o no sabrá qué causó los cambios en las métricas.

4. Canarias una ruta

Habilite controles de caché para una pequeña porción de un inquilino o aplicación interna. Compare la tasa de lectura de caché, la rotación de prefijos, el tiempo hasta el primer token, la tasa de error y las categorías de costos. Evite reclamar ahorros hasta que las facturas de los proveedores se concilien con los libros de entrada.

5. Aplicar gradualmente

Después del canario, convierta las advertencias de pelusa en comprobaciones de políticas. Por ejemplo, advierta al principio sobre el orden inestable de las herramientas y luego rechace nuevas versiones de plantillas que incluyan metadatos volátiles en el prefijo estable.

Compensaciones

• Mayor tasa de aciertos de caché frente a flexibilidad de solicitud: los prefijos estables mejoran la reutilización, pero es posible que los equipos necesiten mover instrucciones dinámicas más adelante o rediseñar plantillas.
• Almacenamiento en caché nativo del proveedor frente a portabilidad: el uso de los controles de caché de cada proveedor puede mejorar la economía, pero los umbrales, los TTL, los campos y la semántica de precios difieren.
• Observabilidad frente a registro sensible: las diferencias de avisos ayudan a depurar errores, pero los hashes y los diagnósticos redactados son valores predeterminados más seguros.
• Aislamiento de inquilinos frente a reutilización máxima: la reutilización amplia puede parecer atractiva, pero el comportamiento centrado en los inquilinos es más seguro y más fácil de explicar.
• Retención más prolongada frente a costos y complejidad de las políticas: las opciones de TTL más largas pueden ayudar a las sesiones de los agentes, pero pueden introducir diferentes consideraciones de precios y control de datos.

Conclusión procesable

Trate el almacenamiento en caché de mensajes como un problema del plano de control de la puerta de enlace, no como una casilla de verificación del proveedor. El patrón práctico es: definir regiones rápidas estables, semiestables y volátiles; representarlos de manera determinista; adaptar los controles de caché específicos del proveedor detrás de una interfaz; normalizar el uso de la caché en un libro de contabilidad; exponer diagnósticos de aciertos de caché por inquilino, aplicación, ruta y versión de plantilla; y hacer cumplir las suposiciones que afectan al inquilino.

El primer paso útil no es reescribir. Agregue observabilidad de caché a sus solicitudes más largas, identifique la rotación de prefijos y elimine las plantillas que causan la mayor cantidad de errores. Una vez que pueda explicar el comportamiento de la caché, podrá optimizarla de forma segura.

Lectura relacionada

• construya categorías que tengan en cuenta la caché en el libro mayor de facturación
• unir métricas de caché con observabilidad LLM segura
• mantener contexto de recuperación con ámbito de inquilino en cargas de trabajo RAG