Caché de prompts

Usa el caché de prompts cuando el mismo contexto extenso aparece en muchas solicitudes. Marca instrucciones, documentos, ejemplos, resultados de herramientas o definiciones de herramientas estables como aptos para caché, para que los proveedores compatibles puedan reutilizarlos en llamadas posteriores. El caché de prompts es distinto del caché de respuestas. El modelo sigue ejecutando la inferencia, pero el caché de prompts puede reducir el coste y la latencia de procesar entradas repetidas. El caché de respuestas devuelve una respuesta generada previamente para una solicitud idéntica.

El caché de prompts depende del proveedor y del modelo. Los proveedores no compatibles ignoran las indicaciones de caché o enrutan la solicitud sin precios de caché. Consulta la tabla de precios de la página del modelo para ver las tarifas de lectura y escritura del caché.

Qué almacenar en caché

Almacena en caché el contenido que permanece estable entre solicitudes:

instrucciones largas del sistema
documentos RAG reutilizados
ejemplos few-shot
definiciones de herramientas
resultados extensos de herramientas que se reutilizan en el siguiente turno

Evita almacenar en caché contenido que cambie en cada solicitud, incluya una entrada breve y puntual del usuario o contenga datos sensibles que tu política no permita guardar en el proveedor seleccionado.

Controles de caché

Phaseo acepta una indicación de compatibilidad cache_control de nivel superior en las solicitudes de Chat Completions, Responses y Anthropic Messages:

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

Usa ttl: "5m" para contextos compartidos de corta duración y ttl: "1h" cuando el proveedor y el modelo admitan entradas de caché de prompts de mayor duración. Los proveedores compatibles tratan el control de caché de nivel superior como una política automática o predeterminada. También puedes colocar cache_control directamente en bloques compatibles de texto, imagen, resultados de herramientas y definiciones de herramientas para crear puntos de corte explícitos en la caché:

{
  "type": "text",
  "text": "Large stable reference text...",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "1h"
  }
}

Se siguen admitiendo alias específicos de cada proveedor. Por ejemplo, puedes aplicar una política de caché predeterminada de Anthropic mediante provider_options:

{
  "provider_options": {
    "anthropic": {
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m",
        "scope": "last_user_message"
      }
    }
  }
}

Valores admitidos de scope:

Alcance	Comportamiento
`all_text`	Añade control de caché al texto del sistema y a los bloques de texto o imagen del usuario que aún no lo tengan.
`last_user_message`	Añade control de caché únicamente al mensaje más reciente del usuario.
`none`	No apliques una política de caché predeterminada.

El cache_control de cada bloque prevalece sobre la política predeterminada.

Chat Completions

Usa /v1/chat/completions si utilizas clientes de chat compatibles con OpenAI.

curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "You are a support assistant. Follow the company policy exactly.",
            "cache_control": { "type": "ephemeral", "ttl": "1h" }
          }
        ]
      },
      {
        "role": "user",
        "content": "Summarise the latest ticket."
      }
    ]
  }'

Para las solicitudes enrutadas a OpenAI, envía las opciones de retención de caché de OpenAI mediante el campo compatible de nivel superior:

{
  "prompt_cache_retention": "24h"
}

También se acepta el alias específico del proveedor:

{
  "provider_options": {
    "openai": {
      "prompt_cache_retention": "24h"
    }
  }
}

Responses

Usa /v1/responses para nuevas integraciones de texto compatibles con OpenAI y flujos de agentes.

curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Reference document: Refunds are available for 30 days when...",
            "cache_control": { "type": "ephemeral", "ttl": "5m" }
          },
          {
            "type": "input_text",
            "text": "Answer this customer: Can I return an item after 20 days?"
          }
        ]
      }
    ]
  }'

Si ya tienes un recurso de contenido en caché de Google Gemini, pásalo mediante provider_options.google.cached_content:

{
  "provider_options": {
    "google": {
      "cached_content": "cachedContents/abc123"
    }
  }
}

Anthropic Messages

Usa /v1/messages si tu cliente es compatible con Anthropic.

curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "system": [
      {
        "type": "text",
        "text": "You are a careful support assistant. Use the policy below.",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Policy: refunds are available for 30 days when...",
            "cache_control": { "type": "ephemeral", "ttl": "5m" }
          },
          {
            "type": "text",
            "text": "Can this customer return an item after 20 days?"
          }
        ]
      }
    ],
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order status.",
        "input_schema": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"]
        },
        "cache_control": { "type": "ephemeral", "ttl": "5m" }
      }
    ]
  }'

Anthropic Messages admite el control de caché en:

bloques de texto system
bloques de texto e imagen de los mensajes
bloques de resultados de herramientas
definiciones de herramientas

Campos de uso y precios

Cuando un proveedor devuelve datos de uso del caché, Phaseo los normaliza en campos de uso comunes.

Campo	Significado
`input_tokens_details.cached_tokens`	Tokens de entrada leídos de la caché de prompts de un proveedor.
`output_tokens_details.cached_tokens`	Tokens de entrada escritos en la caché de prompts de un proveedor.
`cached_read_text_tokens`	Medidor de precio de las lecturas del caché. Es texto de entrada en caché que se reutiliza desde el caché del proveedor.
`cached_write_text_tokens`	Medidor de precio de las escrituras en caché cuando el proveedor tiene un único precio para ellas.
`cached_write_text_tokens_5m`	Tokens escritos en caché con un TTL de 5 minutos, cuando el proveedor informa de escrituras por TTL.
`cached_write_text_tokens_1h`	Tokens escritos en caché con un TTL de 1 hora, cuando el proveedor informa de escrituras por TTL.

Las escrituras en caché suelen costar más que los tokens de entrada normales. Las lecturas suelen ser más baratas. El precio exacto depende del proveedor, el modelo y el TTL.

Comprobaciones prácticas

Después de añadir el caché de prompts:

Envía una solicitud para crear o preparar el caché.
Envía una segunda solicitud con el mismo contenido apto para caché.
Revisa el uso de la respuesta y los detalles de la solicitud para ver los campos de lectura y escritura del caché.
Compara la latencia y el coste tras varias llamadas, no solo en la primera.

Afinidad con el proveedor

Por defecto, Phaseo utiliza el uso del caché de prompts del proveedor como señal de enrutamiento. Cuando un proveedor devuelve tokens de entrada en caché, las solicitudes con la misma clave de caché o un contexto inicial prefieren ese proveedor durante 15 minutos. Así se evita pagar a otro proveedor para reconstruir la misma caché de prompts. Si incluyes session_id, una lectura de caché detectada también crea afinidad de sesión. Phaseo conserva esa afinidad durante la ventana activa de la sesión y sigue permitiendo el failover si el proveedor no está sano o deja de cumplir los requisitos de la política. Establece provider.cache_aware_routing en false para excluir una solicitud. Establece routing.session_affinity en false cuando la solicitud incluya session_id pero deba usar únicamente el enrutamiento normal basado en contexto.

Resumen

Modelos y enrutamiento

Funciones

Integraciones

Espacios de trabajo y acceso

Fiabilidad y operaciones

Plataforma e investigación

Guías de migración

Comunidad

Qué almacenar en caché

Controles de caché

Chat Completions

Responses

Anthropic Messages

Campos de uso y precios

Comprobaciones prácticas

Afinidad con el proveedor

Páginas relacionadas

​Qué almacenar en caché

​Controles de caché

​Chat Completions

​Responses

​Anthropic Messages

​Campos de uso y precios

​Comprobaciones prácticas

​Afinidad con el proveedor

​Páginas relacionadas

Qué almacenar en caché

Controles de caché

Chat Completions

Responses

Anthropic Messages

Campos de uso y precios

Comprobaciones prácticas

Afinidad con el proveedor

Páginas relacionadas