Medir tokens, modelar costos y cachear bien

La factura de la API se duplicó y el tráfico es el mismo. Finanzas pregunta qué funcionalidad gasta más y la única respuesta es una planilla que divide caracteres por cuatro. Un agente piloto costó varias veces lo presupuestado. En los tres casos el problema es el mismo: se estimó en lugar de medir.

Medir, no estimar

Cada respuesta trae el campo uso de tokens (token usage (usage)) con los números reales:

Campo	Qué cuenta
input_tokens	Entrada que no salió de la caché
cache_creation_input_tokens	Entrada escrita en la caché en este pedido
cache_read_input_tokens	Entrada leída de la caché
output_tokens	Toda la salida, pensamiento incluido
output_tokens_details.thinking_tokens	La parte de la salida que fue pensamiento

Guardalo en cada llamada con una etiqueta de funcionalidad (resúmenes, chat, informes) y vas a saber exactamente quién gasta.

Para frenar una entrada antes de pagarla está el conteo de tokens (token counting): recibe el mismo pedido que la API de mensajes, devuelve los tokens de entrada estimados y es gratis. Es el control correcto para rechazar el PDF de 900 páginas antes de mandarlo, no un límite de caracteres. Contá con el modelo que vas a usar: los modelos más nuevos usan otro tokenizador y el mismo texto puede dar bastantes más tokens.

El costo de un loop

Un modelo de costos (cost model) de un agente que se arma como “un pedido con el prompt y la respuesta visible” siempre se queda corto, porque:

• cada iteración es un pedido, y reenvía el historial completo, que crece con cada resultado de herramienta;
• las definiciones de herramientas se cobran como entrada en cada pedido;
• el pensamiento se cobra como salida aunque esté oculto;
• max_tokens limita cada pedido, no la tarea entera.

Para estimar, multiplicá por la cantidad media de iteraciones y sumá el historial que crece; después validalo con un piloto y el usage real.

Cachear bien

La caché de prompts (prompt caching) reutiliza un prefijo idéntico entre pedidos: la lectura cuesta mucho menos que la entrada normal y baja la latencia; la escritura cuesta algo más. Lo que hay que saber:

• El prefijo va en orden: herramientas, system prompt, mensajes. Se cachea todo lo que está antes de un punto de caché (cache breakpoint), marcado con cache_control. Hay hasta cuatro, o caché automática con un solo campo en el pedido.
• Lo estable arriba, lo variable abajo. Un timestamp, el nombre del usuario o un ID de pedido al principio del system prompt cambian el prefijo y nunca hay lectura de caché (cache hit (cache read)).
• Cambiar herramientas, el nivel de esfuerzo, la configuración de pensamiento o la velocidad invalida la caché.
• Dura poco: cinco minutos por defecto, renovados con cada uso; hay una opción de una hora para tráfico más espaciado. Por debajo de un largo mínimo, el prompt no se cachea (sin error).
• No libera ventana de contexto: baja costo y latencia, pero los tokens siguen ocupando lugar.

Para diagnosticar, mirá usage: si cache_read_input_tokens es cero en pedidos que deberían repetir el prefijo, algo variable quedó antes del punto de caché.

Las trampas típicas

• Estimar tokens dividiendo caracteres y no guardar usage.
• Pedirle al modelo que informe cuántos tokens usó.
• Bajar max_tokens en todo para “respetar el presupuesto”.
• Contar un loop como un solo pedido o no contar el pensamiento oculto.
• Poner la fecha o datos del usuario antes del contenido que se quiere cachear.
• Creer que la caché resuelve un contexto que ya no entra.

En el examen

Si la pregunta es “quién gasta” o “cuánto va a costar”, buscá usage guardado por funcionalidad y el conteo de tokens antes de enviar. Si la factura subió sin más tráfico, sospechá de la caché: un cambio que metió algo variable al principio del prompt. Y en un costo de agente subestimado, buscá las iteraciones que reenvían el historial y el pensamiento cobrado como salida.