Ajuste del parámetro effort para optimizar el costo y la velocidad

El parámetro effort establece la profundidad de razonamiento que Claude aplica a una solicitud, lo que te permite intercambiar calidad por costo y velocidad por llamada.

Resumen

Cada solicitud tiene un costo implícito y un presupuesto de latencia.

El parámetro effort, pasado bajo output_config, te da una palanca directa sobre ese presupuesto.

Un effort más bajo favorece la velocidad y el costo, un effort más alto favorece la exhaustividad.

Esto es distinto de la configuración thinking, que controla si el razonamiento es adaptativo y visible en absoluto.

Las dos configuraciones se componen, por lo que un sistema de producción bien ajustado generalmente establece ambas deliberadamente en lugar de dejar cualquiera en un valor predeterminado.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Summarize this customer support thread."}],
)
 
print(response.content[-1].text)

Cuándo usar esto:

• Puntos finales de alto volumen y sensibles a la latencia donde un effort low mantiene el costo predecible.
• Revisión de código, planificación o tareas críticas para la seguridad donde un effort high o max vale la pena el costo.
• Pruebas A/B de la calidad versus las compensaciones de costos en los niveles de effort para el mismo prompt.
• Dirigir el effort dinámicamente según el tipo de solicitud en lugar de una única configuración fija.
• Limitar el costo de razonamiento descontrolado en una carga de trabajo que anteriormente no tenía un límite de effort.

Ejemplo de trabajo

import anthropic
 
client = anthropic.Anthropic()
 
EFFORT_BY_TASK_TYPE = {
    "classify": "low",
    "summarize": "medium",
    "code_review": "high",
    "incident_root_cause": "max",
}
 
 
def run_task(task_type: str, prompt: str) -> str:
    effort = EFFORT_BY_TASK_TYPE.get(task_type, "medium")
 
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1536,
        thinking={"type": "adaptive"},
        output_config={"effort": effort},
        messages=[{"role": "user", "content": prompt}],
    )
 
    for block in response.content:
        if block.type == "text":
            return block.text
    return ""
 
 
if __name__ == "__main__":
    ticket = "User reports intermittent 502s on checkout, started after last night's deploy."
    result = run_task("incident_root_cause", ticket)
    print(result)

Lo que esto demuestra:

• Una tabla de búsqueda que asigna el tipo de tarea a un nivel de effort, evitando una única configuración codificada en toda la aplicación.
• Emparejar thinking={"type": "adaptive"} con un límite de effort explícito, las dos configuraciones se componen limpiamente.
• Volver a "medium" para tipos de tareas no reconocidos en lugar de fallar.
• Extraer solo el bloque text, ignorando cualquier bloque thinking para los propósitos de este sitio de llamada.
• Aplicar el effort max específicamente al tipo de tarea de mayor riesgo, el análisis de la causa raíz de un incidente.

Análisis detallado

Cómo funciona

• output_config={"effort": "<level>"} establece un límite en la cantidad de computación de razonamiento que Claude aplica antes de responder.
• Los niveles se ordenan low, medium, high, max, de más rápido y barato a más exhaustivo y caro.
• El effort se aplica independientemente de si el bloque thinking es visible; rige el presupuesto de razonamiento subyacente, no solo su visualización.
• Aumentar el effort generalmente aumenta tanto el recuento de tokens de salida (cuando el thinking es visible) como la latencia, ya que Claude realiza más trabajo interno por solicitud.
• El effort se compone con thinking: el thinking adaptativo decide si el razonamiento ocurre en absoluto para un prompt dado, el effort limita la profundidad a la que llega cuando lo hace.

Niveles de esfuerzo de un vistazo

Notas de Python

# Patrón: fallar ruidosamente con un valor de esfuerzo no válido en lugar de un valor predeterminado silencioso.
VALID_EFFORTS = {"low", "medium", "high", "max"}
 
 
def build_output_config(effort: str) -> dict:
    if effort not in VALID_EFFORTS:
        raise ValueError(f"Unknown effort level: {effort!r}")
    return {"effort": effort}

Validar la cadena de effort antes de que llegue a la llamada a la API detecta errores tipográficos ("med" en lugar de "medium") en el sitio de la llamada en lugar de como un error de solicitud opaco.

Errores comunes

• Establecer el effort max en todas partes "para estar seguro". Esto infla el costo y la latencia en toda tu aplicación; la mayoría de las solicitudes no lo necesitan. Solución: asigna el effort al tipo de tarea deliberadamente, reserva max para llamadas de alto riesgo genuinas.
• Asumir que el effort controla si aparece un bloque thinking. El effort controla la profundidad y el costo, no la visibilidad; ese es el trabajo de la configuración thinking. Solución: establece explícitamente tanto thinking como output_config.effort cuando necesites tanto la autocalibración como un límite de costo.
• No medir el impacto de la latencia antes de implementar un nivel de effort más alto. Los niveles high y max pueden ralentizar significativamente un punto final orientado al usuario. Solución: compara la latencia p50 y p95 en cada nivel de effort candidato con tu tráfico real antes de elegir uno.
• Codificar un nivel de effort para una carga de trabajo mixta. Un único punto final que atiende solicitudes triviales y complejas desperdicia presupuesto en las fáciles o atiende insuficientemente las difíciles. Solución: dirige el effort por solicitud utilizando un clasificador ascendente barato o una sugerencia explícita proporcionada por el llamador.
• Comparar los niveles de effort en muy pocos prompts de prueba. El impacto en la calidad del effort es más visible en tareas genuinamente difíciles; probar solo con prompts fáciles oculta la diferencia. Solución: crea un conjunto de evaluación que incluya tus casos más difíciles del mundo real antes de decidir un valor predeterminado.
• Pasar una cadena de effort no válida y solo descubrirlo en el momento de la solicitud. Un error tipográfico como "med" para "medium" aparece como un error de API en lo profundo de una ruta de solicitud. Solución: valida la cadena con el conjunto conocido de niveles antes de construir la solicitud.

Alternativas

Preguntas frecuentes

effort = EFFORT_BY_TASK_TYPE.get(task_type, "medium")
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"effort": effort},
    messages=[{"role": "user", "content": prompt}],
)

Relacionado

• Pensamiento extendido y el parámetro Effort explicados - la relación conceptual entre thinking y effort.
• Habilitar el pensamiento adaptativo con thinking: {type: 'adaptive'} - la configuración complementaria con la que se empareja el effort.
• Niveles de esfuerzo y opciones de visualización de pensamiento: referencia - una tabla de referencia completa para cada nivel.
• Pensamiento extendido, esfuerzo y conceptos básicos multimodales - ejemplos mínimos que cubren el effort junto con el thinking y las imágenes.
• Pensamiento extendido, esfuerzo y mejores prácticas multimodales - prácticas numeradas para ajustar el effort en producción.

Versiones de la pila: Escrito para 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 de 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.