Salta al contingut
Esforç de raonament

Esforç de raonament

Nou

Un model que raona retorna el seu text de raonament al costat de la resposta, en un camp propi. En els models open-weight hostejats, un camp de la sol·licitud fixa com de profund raona el model abans de respondre.

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 resposta porta el text de raonament a reasoning_content, la resposta a content i els tokens de raonament a 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}
  }
}

Quins models raonen

Model Retorna text de raonament Aplica el camp d'esforç
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í —
Tots els models open-weight hostejats Sí Sí

Són els indicadors capabilities.reasoning i capabilities.reasoning_effort que GET /v1/models informa per a cada id. Una resposta només porta text de raonament quan el model n'ha produït. Models i preus

Definició de l'esforç

Cada endpoint té la seva manera d'escriure l'esforç. Totes seleccionen un dels mateixos quatre nivells.

Camp Tipus Per defecte Descripció S'aplica a
reasoning_effort string high /v1/chat/completions. Com de profund raona el model abans de respondre: off, low, medium o high. Models open-weight hostejats
reasoning object | string /v1/chat/completions. El mateix valor que {"effort": "low"} o com una cadena sola. Quan s'envien tots dos camps, compta reasoning_effort. Models open-weight hostejats
reasoning.effort string high /v1/responses. S'escriu com l'objecte {"effort": "low"}. Models open-weight hostejats
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} o {"type": "disabled"}. El pressupost selecciona un dels nivells; vegeu la taula de més avall. Models open-weight hostejats
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Valor També s'accepta Efecte
off none, minimal Sense raonament. La resposta no porta text de raonament.
low Raonament breu.
medium default Profunditat mitjana.
high max El nivell més profund. És el nivell d'una sol·licitud que no envia cap valor.
  • Els valors es llegeixen sense distingir majúscules i minúscules.
  • El valor default vol dir medium. Si omets el camp, vol dir high.
  • Els models Shannon (shannon-*) fixen ells mateixos la profunditat a cada sol·licitud; GET /v1/models informa reasoning_effort: false per a ells.

El pressupost de thinking a /v1/messages

A /v1/messages, el camp thinking selecciona el nivell. budget_tokens tria un dels nivells de dalt; no és un límit de tokens per si sol. adaptive es llegeix com enabled.

Tu envies Nivell
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} amb n fins a 2,048 low
n de 2,049 a 8,192 medium
Una n més gran, o enabled sense budget_tokens high
Sense camp thinking high

On arriba el text de raonament

El text de raonament sempre és separat de la resposta. Cada format té el seu lloc per a ell:

Endpoint Sense streaming Amb streaming
/v1/chat/completions choices[0].message.reasoning_content: una cadena, o null quan el model no n'ha produït cap. Fragments amb choices[0].delta.reasoning_content, abans dels fragments amb delta.content.
/v1/responses Un element d'output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} abans de l'element message. Cap element quan no hi ha raonament. response.output_item.added amb un element reasoning, després esdeveniments response.reasoning_summary_text.delta i un response.reasoning_summary_text.done.
/v1/messages Un primer bloc de contingut {"type": "thinking", "thinking": "…"}, després el bloc text. Cap bloc thinking quan no hi ha raonament. Un bloc de contingut thinking: content_block_start, esdeveniments content_block_delta amb thinking_delta, content_block_stop. El bloc de text ve despré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}
  }
}

On mirar, per model:

Models On arriba el text
Models open-weight hostejats A tots els endpoints, amb streaming o sense. Una sol·licitud amb esforç off, o amb response_format / text.format, es respon sense text de raonament.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro A tots els endpoints, amb streaming o sense, sempre que el model hagi produït text de raonament.
shannon-2-lite, shannon-2-pro /v1/chat/completions, sense streaming: a message.reasoning_content. Amb streaming, en una sol·licitud sense tools ni response_format: el stream porta línies de comentari : thinking mentre el model raona, i després els fragments de la resposta. /v1/messages, amb streaming: un bloc thinking abans del bloc de text.
shannon-1.6-pro, shannon-coder-1 A les respostes amb streaming i a les respostes a sol·licituds que porten tools, sempre que el model hagi produït text de raonament.

A /v1/responses, una resposta sense streaming porta l'element reasoning per a la família Shannon 3 i els models open-weight hostejats.

Lectura d'un stream

En un stream, el text de raonament arriba primer, en deltas propis, i la resposta el segueix. Imprimeix o desa els dos per separat:

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 fragment d'un model open-weight hostejat, de raonament o de resposta, també porta delta.role: "assistant". Streaming

Tokens de raonament i facturació

En els models open-weight hostejats, els tokens de raonament són tokens de sortida: es facturen al preu de sortida del model, i el recompte de sortida ja els inclou. usage mostra aquí la part de raonament:

Endpoint Camp Nota
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Ja inclòs a completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Ja inclòs a output_tokens.
/v1/messages usage.output_tokens Raonament i resposta junts. Aquest format no té un recompte separat.
  • En els models open-weight hostejats, max_tokens limita el text de la resposta. Els tokens de raonament no hi compten.
  • Com que el raonament es factura com a sortida, el nivell d'esforç també és un ajust de cost: off no produeix tokens de raonament.
  • Els models Shannon informen prompt_tokens, completion_tokens i total_tokens (input_tokens i output_tokens a /v1/messages) sense part de raonament, i facturen un sol preu pla per token. Models i preus

El raonament a la sol·licitud següent

No cal que tornis a enviar el raonament. Un bloc thinking o un element reasoning a la conversa que envies no es passa al model, així que un torn de l'assistent pot tornar amb ell o sense. Un bloc thinking té els dos camps type i thinking; no té signature.

Errors

Estat Tipus Missatge Quan
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Un model open-weight hostejat ha rebut un valor fora de la llista, per exemple xhigh. No es descompta res del teu saldo.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort no és una cadena.

Els errors d'autenticació, de saldo i del servidor són els mateixos que a qualsevol sol·licitud. Gestió d’errors