Pensamiento Extendido, Esfuerzo y Mejores Prácticas Multimodales

Prácticas numeradas para obtener resultados fiables y eficientes en cuanto a costes del pensamiento extendido, el parámetro de esfuerzo y la entrada multimodal.

Cómo Usar Esta Lista

• Trata cada regla como un valor predeterminado del que desviarse deliberadamente, no como una ley rígida.
• Aplica primero las reglas de esfuerzo y pensamiento, ya que afectan al coste en cada solicitud.
• Aplica las reglas multimodales cuando tu carga de trabajo incluya imágenes o documentos.
• Revisa estas prácticas periódicamente a medida que cambien los patrones de uso y los objetivos de costes.

A - Pensamiento Extendido

• Habilita el pensamiento adaptativo con thinking={"type": "adaptive"} en lugar de adivinar un presupuesto de razonamiento fijo. El pensamiento adaptativo permite a Claude calibrar la profundidad por solicitud, evitando tanto el sub-razonamiento en tareas difíciles como el desperdicio de razonamiento en tareas fáciles.
• Trata un bloque thinking ausente como esperado, no como un error. Las indicaciones simples a menudo no producen ningún razonamiento visible bajo el pensamiento adaptativo; solo investiga si una indicación genuinamente compleja no devuelve ninguno.
• Analiza response.content iterando y comprobando block.type, nunca por índice fijo. El bloque thinking, cuando está presente, puede ocupar el índice 0, desplazando la posición del bloque text.
• Presupuesta max_tokens generosamente para indicaciones que probablemente activen un razonamiento profundo. Los tokens de razonamiento y los tokens de respuesta comparten el mismo presupuesto de salida, y un bloque thinking truncado puede cortar la respuesta final.
• Registra o almacena el bloque thinking por separado de la respuesta visible para el usuario. Esto permite la depuración y auditoría del razonamiento sin confundirlo con la respuesta que ven tus usuarios.

B - Ajuste del Esfuerzo

• Mapea el nivel de esfuerzo al tipo de tarea en lugar de codificar una única configuración para toda la aplicación. La clasificación y la extracción se ajustan a low, las respuestas generales del asistente se ajustan a medium, la revisión de código y la planificación se ajustan a high, y el análisis crítico para la seguridad se ajusta a max.
• Evalúa la latencia y el coste en cada nivel de esfuerzo candidato frente al tráfico real antes de enviar un cambio. high y max pueden ralentizar significativamente un punto final visible para el usuario; mide antes de comprometerte.
• Crea un conjunto de evaluación que incluya tus indicaciones del mundo real más difíciles antes de elegir un nivel de esfuerzo predeterminado. El impacto de la calidad del esfuerzo es más visible en tareas genuinamente difíciles; probar solo con indicaciones fáciles oculta la diferencia.
• Valida las cadenas de esfuerzo contra el conjunto conocido (low, medium, high, max) antes de enviar la solicitud. Capturar un error tipográfico como "med" en el punto de llamada es más barato que depurar un error opaco de la API más tarde.
• Reserva el esfuerzo max para llamadas genuinamente de alto riesgo. Aplicarlo de forma generalizada "por seguridad" infla el coste y la latencia en toda la aplicación sin un beneficio de calidad correspondiente en tareas rutinarias.

C - Visualización del Pensamiento

• Mantén la visualización del pensamiento separada del esfuerzo en tu modelo mental y en tu código. El esfuerzo controla la profundidad del razonamiento y el coste; la visualización controla si ese razonamiento se devuelve resumido u omitido.
• Por defecto, omite la visualización para las respuestas de producción visibles para el usuario. El razonamiento sin procesar o incluso resumido suele estar destinado a la depuración, no como la superficie de respuesta principal.
• Cualquier visualización de razonamiento debe estar sujeta a una opción de interfaz de usuario explícita. Si muestras a los usuarios una justificación, haz que sea una acción deliberada de "mostrar razonamiento" en lugar de una salida siempre visible.
• Conserva el razonamiento resumido en un registro de auditoría para cargas de trabajo críticas para la seguridad o sensibles al cumplimiento, incluso cuando se omita de la respuesta del usuario final. Esto preserva la trazabilidad sin exponer el razonamiento interno a los usuarios finales.
• Elimina o resume los bloques thinking anteriores antes de añadirlos al historial de una conversación de varios turnos. Reenviar bloques de razonamiento sin procesar como texto plano del asistente hincha el uso de tokens en una conversación larga.

D - Envío de Imágenes

• Deriva media_type del formato de archivo real, nunca lo codifiques o adivines. Un media_type incorrecto puede causar un error en la solicitud o una lectura errónea de la imagen.
• Codifica siempre los bytes de la imagen en base64 con base64.standard_b64encode(...).decode("utf-8") antes de asignarlos a data. La API espera una cadena base64, no bytes sin procesar ni una ruta de archivo.
• Reduce el tamaño o comprime las imágenes demasiado grandes antes de codificarlas. Base64 infla el tamaño de la carga útil aproximadamente un tercio sobre el archivo sin procesar, y las imágenes innecesariamente grandes aumentan el tamaño de la solicitud y el coste.
• Acompaña cada bloque de imagen con una instrucción de texto específica que describa qué analizar. Una imagen sin una pregunta adjunta deja a Claude adivinando la intención.
• Prefiere la API de Archivos sobre base64 en línea para cualquier imagen o documento que se use en más de una solicitud. Reenviar la misma carga útil codificada repetidamente desperdicia ancho de banda y tokens para contenido que no ha cambiado.

E - API de Archivos y Documentos Multi-Solicitud

• Sube un documento una vez y almacena su file_id de forma duradera, no solo en una variable local. Conservar file_id junto con tu propio identificador de documento evita cargas redundantes entre ejecuciones de procesos.
• Maneja el caso en que un file_id referenciado haya caducado o sea inválido. Las políticas de retención varían según la cuenta; captura el error y vuelve a subir si el archivo de origen sigue disponible.
• Incluye solo los turnos anteriores relevantes en la lista messages de una solicitud de seguimiento, no todo el historial de tu sesión local. La API solo sabe lo que hay en la lista messages de la solicitud actual; mantén un historial más completo localmente para registrar sin reenviar todo.
• Varía el esfuerzo por pregunta al hacer una secuencia de preguntas sobre el mismo documento. Una simple consulta y una pregunta de referencia cruzada tienen diferentes necesidades de razonamiento, incluso contra el mismo archivo.
• Establece purpose explícitamente en cada llamada de carga de la API de Archivos. Omitirlo o configurarlo incorrectamente puede hacer que el archivo cargado no sea utilizable en un bloque de contenido de documento más tarde.

Preguntas Frecuentes

Relacionados

• Pensamiento Extendido y el Parámetro de Esfuerzo Explicados - la base conceptual de las prácticas A a C.
• Ajuste del Parámetro de Esfuerzo para Coste y Velocidad - un análisis más profundo de la práctica B.
• Niveles de Esfuerzo y Opciones de Visualización del Pensamiento Referencia - la tabla de referencia que suponen estas prácticas.
• Envío de Imágenes para Análisis de Visión con Codificación Base64 - el detalle completo detrás del grupo de prácticas D.
• Carga y Referencia de PDFs con la API de Archivos - el detalle completo detrás del grupo de prácticas E.

Versiones de la pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.