Saltar al contenido
Esfuerzo de razonamiento

Esfuerzo de razonamiento

Nuevo

Un modelo que razona devuelve su texto de razonamiento junto a la respuesta, en un campo propio. En los modelos de pesos abiertos alojados, un campo de la solicitud define qué tan a fondo razona el modelo antes de responder.

POST https://api.shannon-ai.com/v1/chat/completions 

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

message = response.choices[0].message
print("Reasoning:", getattr(message, "reasoning_content", None))
print("Answer:", message.content)
print("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens)

La respuesta lleva el texto de razonamiento en reasoning_content, la respuesta en content y los tokens de razonamiento en usage:

200 JSON 
{
  "id": "chatcmpl-2a6c8e0b4d1f4a3c9e7b5d3f1a8c6e4b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

Qué modelos razonan

Modelo Devuelve texto de razonamiento Aplica el campo de esfuerzo
shannon-1.6-lite — —
shannon-1.6-pro, shannon-2-lite, shannon-2-pro, shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro, shannon-coder-1 Sí —
Todos los modelos de pesos abiertos alojados Sí Sí

Estos son los indicadores capabilities.reasoning y capabilities.reasoning_effort que GET /v1/models informa para cada id. Una respuesta lleva texto de razonamiento solo cuando el modelo produjo alguno. Modelos y precios

Definir el esfuerzo

Cada endpoint tiene su propia forma de escribir el esfuerzo. Todas eligen uno de los mismos cuatro niveles.

Campo Tipo Predeterminado Descripción Aplicado por
reasoning_effort string high /v1/chat/completions. Qué tan a fondo razona el modelo antes de responder: off, low, medium o high. Modelos de pesos abiertos alojados
reasoning object | string /v1/chat/completions. El mismo valor como {"effort": "low"} o como una cadena simple. Si se envían ambos campos, cuenta reasoning_effort. Modelos de pesos abiertos alojados
reasoning.effort string high /v1/responses. Se escribe como el objeto {"effort": "low"}. Modelos de pesos abiertos alojados
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} o {"type": "disabled"}. El presupuesto elige uno de los niveles; consulta la tabla más abajo. Modelos de pesos abiertos alojados 
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Valor También se acepta Efecto
off none, minimal Sin razonamiento. La respuesta no lleva texto de razonamiento.
low Razonamiento breve.
medium default Profundidad media.
high max El nivel más profundo. Es el nivel de una solicitud que no envía ningún valor.
  • Los valores se leen sin distinguir mayúsculas de minúsculas.
  • El valor default equivale a medium. Omitir el campo equivale a high.
  • Los modelos Shannon (shannon-*) fijan su propia profundidad en cada solicitud; GET /v1/models informa reasoning_effort: false para ellos.

El presupuesto de thinking en /v1/messages

En /v1/messages el campo thinking elige el nivel. budget_tokens elige uno de los niveles anteriores; no es un límite de tokens propio. adaptive se lee como enabled.

Tú envías Nivel
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} con n hasta 2,048 low
n de 2,049 a 8,192 medium
Una n mayor, o enabled sin budget_tokens high
Sin campo thinking high

Dónde llega el texto de razonamiento

El texto de razonamiento siempre va separado de la respuesta. Cada formato tiene su propio lugar para él:

Endpoint Sin stream Con stream
/v1/chat/completions choices[0].message.reasoning_content: una cadena, o null cuando el modelo no produjo ninguna. Fragmentos con choices[0].delta.reasoning_content, antes de los fragmentos con delta.content.
/v1/responses Un elemento de output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} antes del elemento message. Sin elemento cuando no hay razonamiento. response.output_item.added con un elemento reasoning, luego eventos response.reasoning_summary_text.delta y un response.reasoning_summary_text.done.
/v1/messages Un primer bloque de contenido {"type": "thinking", "thinking": "…"}, luego el bloque text. Sin bloque thinking cuando no hay razonamiento. Un bloque de contenido thinking: content_block_start, eventos content_block_delta con thinking_delta, content_block_stop. El bloque de texto va después. 
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

Dónde mirar, por modelo:

Modelos Dónde llega el texto
Modelos de pesos abiertos alojados En todos los endpoints, con stream o sin él. Una solicitud con esfuerzo off, o con response_format / text.format, se responde sin texto de razonamiento.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro En todos los endpoints, con stream o sin él, siempre que el modelo haya producido texto de razonamiento.
shannon-2-lite, shannon-2-pro /v1/chat/completions, sin stream: en message.reasoning_content. Con stream, en una solicitud sin tools ni response_format: el stream lleva líneas de comentario : thinking mientras el modelo razona, y después los fragmentos de la respuesta. /v1/messages, con stream: un bloque thinking antes del bloque de texto.
shannon-1.6-pro, shannon-coder-1 En las respuestas con stream y en las respuestas a solicitudes que llevan tools, siempre que el modelo haya producido texto de razonamiento.

En /v1/responses, una respuesta sin stream lleva el elemento reasoning para la familia Shannon 3 y los modelos de pesos abiertos alojados.

Leer un stream

En un stream el texto de razonamiento llega primero, en deltas propios, y la respuesta lo sigue. Imprime o guarda los dos por separado:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

stream = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="medium",
    stream=True,
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)      # the reasoning text comes first
    if delta.content:
        print(delta.content, end="", flush=True)  # then the answer

El primer fragmento de un modelo de pesos abiertos alojado, de razonamiento o de respuesta, lleva también delta.role: "assistant". Streaming

Tokens de razonamiento y facturación

En los modelos de pesos abiertos alojados, los tokens de razonamiento son tokens de salida: se facturan al precio de salida del modelo, y el conteo de salida ya los incluye. Aquí usage muestra la parte de razonamiento:

Endpoint Campo Nota
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Ya incluido en completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Ya incluido en output_tokens.
/v1/messages usage.output_tokens Razonamiento y respuesta juntos. Este formato no tiene un conteo separado.
  • En los modelos de pesos abiertos alojados, max_tokens limita el texto de la respuesta. Los tokens de razonamiento no cuentan contra él.
  • Como el razonamiento se factura como salida, el nivel de esfuerzo también es un ajuste de costo: off no produce tokens de razonamiento.
  • Los modelos Shannon informan prompt_tokens, completion_tokens y total_tokens (input_tokens y output_tokens en /v1/messages) sin una parte de razonamiento, y facturan un precio fijo por token. Modelos y precios

El razonamiento en la siguiente solicitud

No tienes que reenviar el razonamiento. Un bloque thinking o un elemento reasoning en la conversación que envías no se pasa al modelo, así que un turno del asistente puede volver con él o sin él. Un bloque thinking tiene los dos campos type y thinking; no tiene signature.

Errores

Estado Tipo Mensaje Cuándo
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Un modelo de pesos abiertos alojado recibió un valor fuera de la lista, por ejemplo xhigh. No se descuenta nada de tu saldo.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort no es una cadena.

Los errores de autenticación, saldo y servidor son los mismos que en cualquier solicitud. Manejo de errores