Saltar ao contido
Esforzo de razoamento

Esforzo de razoamento

Novo

Un modelo que razoa devolve o seu texto de razoamento xunto coa resposta, nun campo propio. Nos modelos open-weight alojados, un campo da solicitude define canto razoa o 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)

A resposta leva o texto de razoamento en reasoning_content, a resposta en content e os tokens de razoamento 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}
  }
}

Que modelos razoan

Modelo Devolve texto de razoamento Aplica o campo de esforzo
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 Si —
Todos os modelos open-weight alojados Si Si

Estes son os indicadores capabilities.reasoning e capabilities.reasoning_effort que GET /v1/models informa para cada id. Unha resposta só leva texto de razoamento cando o modelo produciu algún. Modelos e prezos

Definir o esforzo

Cada endpoint ten a súa propia forma de escribir o esforzo. Todas seleccionan un dos mesmos catro niveis.

Campo Tipo Valor predeterminado Descrición Aplicado por
reasoning_effort string high /v1/chat/completions. Canto razoa o modelo antes de responder: off, low, medium ou high. Modelos open-weight alojados
reasoning object | string /v1/chat/completions. O mesmo valor como {"effort": "low"} ou como cadea simple. Cando se envían os dous campos, vale reasoning_effort. Modelos open-weight alojados
reasoning.effort string high /v1/responses. Escrito como o obxecto {"effort": "low"}. Modelos open-weight alojados
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} ou {"type": "disabled"}. O orzamento selecciona un dos niveis; consulta a táboa máis abaixo. Modelos open-weight alojados
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Valor Tamén se acepta Efecto
off none, minimal Sen razoamento. A resposta non leva texto de razoamento.
low Razoamento breve.
medium default Profundidade media.
high max O nivel máis profundo. É o nivel dunha solicitude que non envía ningún valor.
  • Os valores lense sen ter en conta as maiúsculas e minúsculas.
  • O valor default significa medium. Omitir o campo significa high.
  • Os modelos Shannon (shannon-*) definen a súa propia profundidade en cada solicitude; GET /v1/models informa reasoning_effort: false para eles.

O orzamento de thinking en /v1/messages

En /v1/messages o campo thinking selecciona o nivel. budget_tokens escolle un dos niveis anteriores; non é un límite de tokens propio. adaptive lese como enabled.

Ti envías Nivel
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} con n ata 2,048 low
n de 2,049 a 8,192 medium
Un n maior, ou enabled sen budget_tokens high
Sen campo thinking high

Onde chega o texto de razoamento

O texto de razoamento está sempre separado da resposta. Cada formato ten o seu propio lugar para el:

Endpoint Sen stream Con stream
/v1/chat/completions choices[0].message.reasoning_content: unha cadea, ou null cando o modelo non produciu ningún. Chunks con choices[0].delta.reasoning_content, antes dos chunks con delta.content.
/v1/responses Un elemento de output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} antes do elemento message. Sen elemento cando non hai razoamento. response.output_item.added cun elemento reasoning, despois eventos response.reasoning_summary_text.delta e un response.reasoning_summary_text.done.
/v1/messages Un primeiro bloque de contido {"type": "thinking", "thinking": "…"} e despois o bloque text. Sen bloque thinking cando non hai razoamento. Un bloque de contido thinking: content_block_start, eventos content_block_delta con thinking_delta, content_block_stop. O bloque de texto vén despois.
{
  "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}
  }
}

Onde mirar, por modelo:

Modelos Onde chega o texto
Modelos open-weight alojados En todos os endpoints, con stream ou sen el. Unha solicitude con esforzo off, ou con response_format / text.format, responde sen texto de razoamento.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro En todos os endpoints, con stream ou sen el, sempre que o modelo produciu texto de razoamento.
shannon-2-lite, shannon-2-pro /v1/chat/completions, sen stream: en message.reasoning_content. Con stream, nunha solicitude sen tools nin response_format: o stream leva liñas de comentario : thinking mentres o modelo razoa e despois os chunks da resposta. /v1/messages, con stream: un bloque thinking antes do bloque de texto.
shannon-1.6-pro, shannon-coder-1 Nas respostas con stream e nas respostas a solicitudes que levan tools, sempre que o modelo produciu texto de razoamento.

En /v1/responses, unha resposta sen stream leva o elemento reasoning para a familia Shannon 3 e os modelos open-weight alojados.

Ler un stream

Nun stream o texto de razoamento vén primeiro, en deltas propios, e a resposta segue. Imprime ou garda os dous 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

O primeiro chunk dun modelo open-weight alojado, de razoamento ou de resposta, leva tamén delta.role: "assistant". Streaming

Tokens de razoamento e facturación

Nos modelos open-weight alojados, os tokens de razoamento son tokens de saída: factúranse ao prezo de saída do modelo, e o reconto de saída xa os inclúe. Aquí usage mostra a parte de razoamento:

Endpoint Campo Nota
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Xa incluídos en completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Xa incluídos en output_tokens.
/v1/messages usage.output_tokens Razoamento e resposta xuntos. Este formato non ten un reconto separado.
  • Nos modelos open-weight alojados, max_tokens limita o texto da resposta. Os tokens de razoamento non contan para ese límite.
  • Como o razoamento se factura como saída, o nivel de esforzo é tamén un axuste de custo: off non produce tokens de razoamento.
  • Os modelos Shannon informan prompt_tokens, completion_tokens e total_tokens (input_tokens e output_tokens en /v1/messages) sen parte de razoamento, e facturan un prezo fixo por token. Modelos e prezos

O razoamento na seguinte solicitude

Non tes que devolver o razoamento. Un bloque thinking ou un elemento reasoning na conversa que envías non se pasa ao modelo, así que un turno do asistente pode volver con el ou sen el. Un bloque thinking ten os dous campos type e thinking; non ten signature.

Erros

Estado Tipo Mensaxe Cando
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Un modelo open-weight alojado recibiu un valor que non está na lista, por exemplo xhigh. Non se descontou nada do teu saldo.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort non é unha cadea.

Os erros de autenticación, saldo e servidor son os mesmos que para calquera solicitude. Xestión de erros