Saltar a contenido

El consumo de una respuesta

Cada respuesta se apunta con los tokens que gastó y la tarifa con la que se valora. Esta página explica de dónde salen esos tokens, para que una herramienta nueva no gaste sin apuntar.

Una respuesta son varias llamadas

Una respuesta sin herramientas es una llamada al modelo. Con herramientas son varias, y cada una se paga entera, con todo lo que se le manda:

Llamada Entrada Salida
1. El modelo decide qué herramienta pedir El prompt, el historial, la pregunta y la descripción de las herramientas La petición de la herramienta
2. El modelo contesta con el resultado Todo lo anterior, más la petición y el resultado de la herramienta La respuesta

Por eso una respuesta con una herramienta cuesta bastante más del doble que una sin ella, y por eso importan las reglas de qué devolver: el resultado de una herramienta se paga como entrada en cada llamada que viene detrás, y en los turnos siguientes mientras siga en la memoria.

Cómo se cuenta

El agente pide a cada proveedor que mande el uso de tokens en el streaming (stream_usage). TokenUsageTracker (modelos/contador.py) lo recoge así:

  • por mensaje del modelo, la suma de sus trozos, como los junta LangChain: OpenAI manda el uso entero en el último, y Gemini un poco en cada uno;
  • los mensajes se suman: cada llamada al modelo es un mensaje;
  • lo de los sub-agentes va aparte, porque no pasa por el streaming: lo que preguntar va dejando en runtime.context.subagentes, por herramienta, y lo que una herramienta suma a runtime.context.consumo por su cuenta. Cada herramienta, en su propio apunte del mismo mensaje;
  • y lo que el proveedor no dio, estimado con la petición entera que salió hacia el modelo (el prompt, las definiciones de las herramientas, el historial y el turno), como la mide el desglose, y con lo que escribió: una llamada sin uso, o la que quedó a medias al cancelar (ver abajo). Una respuesta nunca sale gratis.

Al terminar, se apunta en token_usage:

Campo Qué es
prompt_tokens, completion_tokens, total_tokens Lo gastado en toda la respuesta
username Quién preguntó: el apunte cuadra aunque se borre la conversación
tarifa_id Con qué tarifa se valora
bolsa_id A qué bolsa se carga, con bolsas
message_id, chat_id La respuesta y la conversación
origen De dónde sale: respuesta, subagente, titulo, resumen o informe (y sugerencias, de cuando eran una llamada aparte)
llamadas, cache_read, estimado Lo exacto del proveedor: cuántas llamadas al modelo y cuántos tokens de la entrada salieron de su caché. Y si algo de lo apuntado se estimó porque no dio el uso
herramienta La herramienta que creó el sub-agente, si el origen es subagente
partes De qué se compone, en la tabla token_usage_parte: una fila por parte de la entrada o de la salida

El apunte no lleva importes. El precio y el margen están solo en la tarifa, y las vistas de consumo calculan los euros. Por eso corregir una tarifa rehace lo cobrado sin tocar los apuntes.

De qué se compone

Cada apunte guarda en desglose de qué se compone, y sus partes suman siempre lo que se cobra (prompt_tokens y completion_tokens):

{"llamadas": 2, "entrada": {"contexto": 4000, "definiciones": 1800, "ronda": 1580, "sistema": 1200, "mensaje": 100},
 "salida": {"razonamiento": 300, "llamadas_herramienta": 80, "texto": 400}, "cache_read": 3072, "estimado": false}

Lo exacto lo da el proveedor: cuántas llamadas hizo la respuesta, los tokens leídos de la caché, el razonamiento (lo que el modelo piensa antes de contestar: no se ve, pero se cobra como salida) y cómo acabó cada llamada. Por eso la salida se separa sin estimar nada: el razonamiento, lo que escribió la llamada que pidió herramientas y el texto de la que contestó.

Lo estimado es de qué se compone la entrada de una respuesta, que ningún proveedor lo dice. El agente estima cada parte de la petición, tal como sale hacia el modelo, con el mismo contador que el recorte del historial, y reparte entre ellas la entrada real de cada llamada. Lo hace MedirConsumoMiddleware (agente/middlewares.py, con la lógica de modelos/desglose.py):

Parte Qué es
sistema El prompt, con las instrucciones de los permisos del usuario
definiciones Las herramientas que se le dan al modelo, en cada llamada
contexto La conversación anterior que queda después del recorte (max_tokens_contexto)
contexto_herramientas Los resultados de herramientas de turnos anteriores que siguen en la memoria
mensaje La pregunta
ronda Las herramientas de esta respuesta: lo que pidió el modelo y lo que devolvieron

El reparto es proporcional, llamada a llamada: si lo estimado da 1000 tokens de sistema y 3000 de contexto y el proveedor dice que entraron 8000, son 2000 y 6000. Lo que sobra al redondear va a las partes con más decimales, para que sumen exacto. Los porcentajes no se configuran: salen de lo que pesa cada parte en esa petición.

El título, el resumen del historial, el informe y los sub-agentes no se reparten por dentro: su entrada va entera en peticion. Un apunte con algo estimado (el proveedor no dio el uso de alguna llamada) lleva "estimado": true, y sus partes, que en las llamadas estimadas son las medidas. Solo si no se pudo medir ninguna llamada se estima por las palabras, y entonces no lleva partes. Los anteriores al desglose no tienen ni origen ni desglose, y salen como sin_desglose.

Dónde se mira

El desglose es interno: la aplicación no lo enseña, porque el reparto de la entrada es una estimación y sirve a quien mantiene el chatbot, no a quien chatea. Se mira:

  • en un informe, con tai-chat consumo: de qué se compone la entrada y la salida de las respuestas, las más caras y avisos de lo que suele tener arreglo, en Markdown, HTML con gráficas o PDF;
  • en la base de datos, en token_usage (lo exacto) y token_usage_parte (las partes);
  • en las vistas consumo_apunte y consumo_parte, con importes: cada apunte, con su origen, su modelo, lo leído y escrito en la caché y lo que ahorró; y cada parte, con la entrada a su precio medio. Solo las lee el Administrador;
  • en el log, la línea de cada respuesta (abajo).

En el log

Al terminar cada respuesta, el log de la API lleva una línea [desglose] en nivel DEBUG. El logger del chat (tai-chatbot, de tai-alphi) escribe en consola desde INFO, así que no sale salvo que se le baje el nivel en su configuración. Por ejemplo, en routers/custom/__init__.py:

from tai_alphi import Alphi

Alphi.configure_logger("tai-chatbot", {"consola": {"log_level": "DEBUG"}})

Sin tocar el arranque de la API: es la configuración del logger, y se quita igual. La línea:

[desglose] [azure-openai:gpt-5.1] chat 42: 2 llamada(s), entrada 8680 (apuntada 8680, aproximada 9512): contexto 4000 (46 %), definiciones 1800 (21 %), ronda 1580 (18 %), sistema 1200 (14 %), mensaje 100 (1 %) · razonamiento 300
  • apuntada es lo que se cobra por las llamadas del agente. Si no coincide con entrada, algo se está contando mal: en un sitio o en el otro.
  • aproximada es lo que dio el contador. La diferencia con entrada dice cuánto se equivoca con vuestro contenido, y por tanto cuánto recorta de verdad max_tokens_contexto.

Lo que gasta una herramienta

La herramienta… ¿Se apunta?
Lee datos, llama a una API, calcula No gasta tokens: no hay nada que apuntar
Usa un sub-agente con crear_subagente y preguntar Sí, solo: preguntar lo suma
Llama al modelo del contexto (runtime.context.modelo) Solo si lo suma ella, como en este ejemplo
Llama a otro modelo, o a un servicio de IA externo No: no es el modelo de la respuesta ni tiene su tarifa

La regla: si una herramienta llama a un LLM, su consumo tiene que acabar en runtime.context.consumo (runtime.context.consumo.sumar(respuesta.usage_metadata)), o se gasta sin que nadie lo vea.

Lo que no es una respuesta

Todo lo que se gasta en una conversación se apunta, también lo que no acaba en una respuesta. Va con chat_id y, cuando no hay mensaje del que colgarlo, con message_id vacío. Las vistas que facturan leen token_usage sin pasar por el mensaje, así que se cobra igual.

Qué pasó Qué se apunta Dónde
El título de la conversación Su llamada al modelo del mensaje Suelto, con la conversación
Las sugerencias de una respuesta Nada aparte: el modelo las escribe al final de la respuesta, en la misma llamada En el apunte de la respuesta
El resumen del historial, cuando llega a su límite Su llamada al modelo de la respuesta Con el mensaje de la respuesta que lo hizo
El informe de la conversación Sus llamadas al modelo de la conversación (las tandas si no cabía, y la redacción) Con el mensaje de sistema que lo entrega; si falla o se cancela, suelto con la conversación, con la llamada cortada estimada
El agente se pasa de max_iteraciones Todas las llamadas que hizo En el mensaje que lo explica
El usuario la cancela Las llamadas que terminaron, y la que estaba en curso, estimada (abajo) En el mensaje de la cancelación
Una excepción la corta Las llamadas que terminaron, sin estimar la que falló: puede que el proveedor no la recibiera Suelto, con la conversación

La llamada que estaba en curso al cancelar. El proveedor la cobra: la entrada entera y lo que llegó a escribir. OpenAI y Azure mandan el uso al final del streaming, y cortado no llega; así que se estima: la entrada, con la petición que salió (el desglose la mide al enviarla), y la salida, con lo que llegó por el stream. El razonamiento de esa llamada no se ve, y no se cuenta: la estimación se queda corta en un modelo que razona. Con Gemini no hace falta: manda el uso en cada trozo, y lo que llegó ya está apuntado. Si se cancela mientras se resume el historial, la entrada del resumen se apunta igual, estimada, con origen resumen. Lo que hacía un sub-agente en ese momento no se estima.

Probar el consumo de una herramienta

Con el permiso app-lab, debajo de cada respuesta aparecen sus tokens. Para una herramienta nueva, lo útil es comparar una pregunta que la usa con una que no: la diferencia es lo que cuesta. Si una herramienta con sub-agente apenas sube el consumo, es que no está sumando el del sub-agente.