Respuesta y uso
En esta página
Entiende qué devuelve la API
La mayoría de los desarrolladores que se acercan por primera vez a la API leen una única línea de la respuesta —el texto generado— e ignoran todo lo demás. Es un error. Cada llamada a /v1/chat/completions devuelve un objeto JSON completo. Ahí es donde encontrarás los datos que necesitas para controlar los costes, detectar una respuesta truncada antes de que llegue al usuario y localizar una llamada concreta cuando abras un ticket de soporte.
Anatomía completa de la respuesta
Empecemos por los metadatos. Son campos que rara vez consultas, pero que desearías haber registrado el día que ocurra un incidente:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is machine learning?"}],
max_tokens=500
)
# Acceso a los metadatos
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")
El campo id es un identificador único asignado a cada solicitud. Esta es la referencia que proporcionarás al soporte técnico y la que te permitirá vincular una reclamación de un usuario con una llamada específica en tus registros. El campo model confirma qué modelo se ha utilizado realmente. Esto importa más de lo que crees cuando llamas a un alias -latest y el comportamiento cambia de la noche a la mañana sin que hayas modificado tu código.
El array choices
El núcleo de la respuesta reside en choices. Por defecto, este array contiene un único elemento. De él extraes tanto el texto como el veredicto sobre cómo ha terminado la generación:
choice = response.choices[0]
# El mensaje generado
print(choice.message.role) # "assistant"
print(choice.message.content) # El texto de la respuesta
# El índice de esta respuesta en el array
print(choice.index) # 0
# La razón de parada
print(choice.finish_reason) # "stop", "length", o "tool_calls"
Si solicitas varias respuestas mediante el parámetro n, que veremos en la lección 15, choices contendrá varios elementos y el índice volverá a tener sentido.
Valores de finish_reason
Este campo determina la fiabilidad de tu aplicación. Hay tres valores posibles. stop indica que el modelo ha terminado su respuesta de forma natural. Este es el caso normal, en el que puedes mostrar el contenido sin reservas. length significa que la generación se ha cortado por max_tokens, por lo que la respuesta está potencialmente incompleta: un resumen sin conclusión o una lista que se detiene en el séptimo elemento. Por último, tool_calls indica que el modelo está solicitando la ejecución de una herramienta externa como parte de la llamada a funciones, y ahora te toca actuar a ti.
Cada uno de estos casos requiere un tratamiento distinto, que deberías escribir de una vez por todas:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a detailed report."}],
max_tokens=200
)
choice = response.choices[0]
if choice.finish_reason == "stop":
# Respuesta completa — procesamiento normal
result = choice.message.content
elif choice.finish_reason == "length":
# Respuesta truncada — reintentar con más tokens o avisar al usuario
print("Warning: The response was truncated.")
# Opción: Reintentar con un límite de max_tokens mayor
# Opción: Pedir al modelo que continúe
elif choice.finish_reason == "tool_calls":
# El modelo solicita una llamada a herramienta
for tool_call in choice.message.tool_calls:
print(f"Requested tool: {tool_call.function.name}")
Observa que la rama length no deja pasar el texto tal cual. O bien reintentas con un límite mayor, pides al modelo que continúe o avisas al usuario. Lo que nunca debes hacer es mostrar un texto truncado como si estuviera completo.
El objeto usage: controla tus costes
El campo usage cuenta los tokens consumidos por la solicitud, separando la entrada de la salida:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Esta distinción no es cosmética. Los modelos de Mistral tienen tarifas distintas para entrada y salida. Una funcionalidad que envía un contexto largo para obtener tres palabras de vuelta tiene un perfil de costes completamente distinto al de un borrador largo generado a partir de un prompt breve. El cálculo requiere apenas unas líneas:
# Tarifas hipotéticas por millón de tokens (consulta la tarifa actual)
RATE_INPUT = 2.0 # $/M tokens entrada
RATE_OUTPUT = 6.0 # $/M tokens salida
cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output
print(f"Cost of this call: ${cost_total:.6f}")
Una única llamada cuesta una fracción de céntimo, lo cual resulta falsamente tranquilizador. Multiplícalo por el tráfico real de una aplicación y la pregunta pasa a ser: ¿qué funcionalidad consume qué? Para responder, agrega las métricas de uso desde tu primer despliegue. Registra cada llamada junto con el nombre de la funcionalidad que la ha disparado:
import json
from datetime import datetime
def log_usage(response, endpoint_name: str):
"""Registra las métricas de uso de cada llamada a la API."""
log_entry = {
"timestamp": datetime.utcnow().isoformat(),
"endpoint": endpoint_name,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"total_tokens": response.usage.total_tokens,
"finish_reason": response.choices[0].finish_reason,
"request_id": response.id
}
with open("api_usage.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# Uso
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")
Un archivo JSONL como este, revisado al cabo de dos semanas, te dirá sin ambigüedades qué pantalla de tu producto pesa más en la factura y cuántas llamadas terminan con length.
Contenido de la respuesta
El campo content del mensaje del asistente puede adoptar dos formas, exactamente igual que en el lado de la solicitud:
# Forma simple — cadena
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."
# Forma estructurada — lista de bloques (poco frecuente en chat estándar)
# [{"type": "text", "text": "..."}]
En la práctica, para llamadas estándar de Chat Completions, content es siempre una cadena. La forma estructurada está reservada para respuestas multimodales.
Llévalo a la práctica
Vamos a integrar todo esto en una función utilitaria, la que copiarás de proyecto en proyecto. Esta función ensambla los mensajes, realiza la llamada y devuelve un diccionario que expone tanto las métricas como el texto:
from mistralai.client import Mistral
def chat_complete(
client: Mistral,
prompt: str,
system: str = "",
model: str = "mistral-large-latest",
max_tokens: int = 1000
) -> dict:
"""Llamada a Chat Completions con gestión de errores y métricas."""
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
response = client.chat.complete(
model=model,
messages=messages,
max_tokens=max_tokens
)
return {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"tokens_in": response.usage.prompt_tokens,
"tokens_out": response.usage.completion_tokens,
"model": response.model,
"id": response.id
}
Lo clave es lo que devuelve la función: nunca solo el texto. Al hacer llegar al llamador el finish_reason, el recuento de tokens y el ID de la solicitud, haces imposible el error más común: tratar una respuesta cortada como válida.
Puntos clave
- La respuesta contiene
choices(contenido),usage(tokens) y metadatos (id,model) - Comprueba siempre
finish_reason:lengthsignifica una respuesta incompleta usagecuenta por separado los tokens de entrada y salida para un seguimiento preciso de costes- Configura el registro de métricas desde tu primer despliegue en producción
- El campo
ides esencial para la depuración y el soporte técnico