Vai al contenuto
Sforzo di ragionamento

Sforzo di ragionamento

Nuovo

Un modello che ragiona restituisce il suo testo di ragionamento accanto alla risposta, in un campo a parte. Sui modelli open-weight ospitati un campo della richiesta stabilisce con quale profondità il modello ragiona prima di rispondere.

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 risposta porta il testo di ragionamento in reasoning_content, la risposta in content e i token di ragionamento in 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}
  }
}

Quali modelli ragionano

Modello Restituisce testo di ragionamento Applica il campo effort
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ì —
Ogni modello open-weight ospitato Sì Sì

Sono i flag capabilities.reasoning e capabilities.reasoning_effort che GET /v1/models riporta per ogni id. Una risposta contiene testo di ragionamento solo quando il modello ne ha prodotto. Modelli e prezzi

Impostare l'effort

Ogni endpoint ha una propria grafia per l'effort. Tutte selezionano uno degli stessi quattro livelli.

Campo Tipo Default Descrizione Applicato da
reasoning_effort string high /v1/chat/completions. Con quale profondità il modello ragiona prima di rispondere: off, low, medium o high. Modelli open-weight ospitati
reasoning object | string /v1/chat/completions. Lo stesso valore come {"effort": "low"} oppure come semplice stringa. Quando entrambi i campi vengono inviati, vale reasoning_effort. Modelli open-weight ospitati
reasoning.effort string high /v1/responses. Scritto come oggetto {"effort": "low"}. Modelli open-weight ospitati
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} oppure {"type": "disabled"}. Il budget seleziona uno dei livelli; vedi la tabella più sotto. Modelli open-weight ospitati
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Valore Accettato anche Effetto
off none, minimal Nessun ragionamento. La risposta non contiene testo di ragionamento.
low Ragionamento breve.
medium default Profondità media.
high max Il livello più profondo. È il livello di una richiesta che non invia alcun valore.
  • I valori vengono letti senza distinguere maiuscole e minuscole.
  • Il valore default equivale a medium. Omettere il campo equivale a high.
  • I modelli Shannon (shannon-*) impostano da soli la profondità a ogni richiesta; GET /v1/models riporta per loro reasoning_effort: false.

Il budget di thinking su /v1/messages

Su /v1/messages il campo thinking seleziona il livello. budget_tokens sceglie uno dei livelli qui sopra; non è un limite di token a sé stante. adaptive viene letto come enabled.

Cosa invii Livello
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} con n fino a 2,048 low
n da 2,049 a 8,192 medium
Un n maggiore, oppure enabled senza budget_tokens high
Nessun campo thinking high

Dove arriva il testo di ragionamento

Il testo di ragionamento è sempre separato dalla risposta. Ogni formato ha il suo posto per esso:

Endpoint Senza streaming In streaming
/v1/chat/completions choices[0].message.reasoning_content: una stringa, oppure null quando il modello non ne ha prodotto. Chunk con choices[0].delta.reasoning_content, prima dei chunk con delta.content.
/v1/responses Un elemento output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} prima dell'elemento message. Nessun elemento quando non c'è ragionamento. response.output_item.added con un elemento reasoning, poi eventi response.reasoning_summary_text.delta e un response.reasoning_summary_text.done.
/v1/messages Un primo blocco di contenuto {"type": "thinking", "thinking": "…"}, poi il blocco text. Nessun blocco thinking quando non c'è ragionamento. Un blocco di contenuto thinking: content_block_start, eventi content_block_delta con thinking_delta, content_block_stop. Segue il blocco di testo.
{
  "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}
  }
}

Dove guardare, per modello:

Modelli Dove arriva il testo
Modelli open-weight ospitati Su ogni endpoint, con o senza streaming. Una richiesta con effort off, oppure con response_format / text.format, riceve risposta senza testo di ragionamento.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro Su ogni endpoint, con o senza streaming, ogni volta che il modello ha prodotto testo di ragionamento.
shannon-2-lite, shannon-2-pro /v1/chat/completions, senza streaming: in message.reasoning_content. In streaming, in una richiesta senza tools né response_format: lo stream porta righe di commento : thinking mentre il modello ragiona, poi i chunk della risposta. /v1/messages, in streaming: un blocco thinking prima del blocco di testo.
shannon-1.6-pro, shannon-coder-1 Nelle risposte in streaming e nelle risposte a richieste che portano tools, ogni volta che il modello ha prodotto testo di ragionamento.

Su /v1/responses, una risposta senza streaming porta l'elemento reasoning per la famiglia Shannon 3 e per i modelli open-weight ospitati.

Leggere uno stream

In uno stream il testo di ragionamento viene per primo, in delta propri, e la risposta segue. Stampa o salva i due separatamente:

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

Il primo chunk di un modello open-weight ospitato, di ragionamento o di risposta, porta anche delta.role: "assistant". Streaming

Token di ragionamento e fatturazione

Sui modelli open-weight ospitati, i token di ragionamento sono token di output: vengono fatturati al prezzo di output del modello, e il conteggio dell'output li include già. Qui usage mostra la quota di ragionamento:

Endpoint Campo Nota
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Già incluso in completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Già incluso in output_tokens.
/v1/messages usage.output_tokens Ragionamento e risposta insieme. Questo formato non ha un conteggio separato.
  • Sui modelli open-weight ospitati max_tokens limita il testo della risposta. I token di ragionamento non vengono conteggiati in esso.
  • Poiché il ragionamento è fatturato come output, il livello di effort è anche un'impostazione di costo: off non produce token di ragionamento.
  • I modelli Shannon riportano prompt_tokens, completion_tokens e total_tokens (input_tokens e output_tokens su /v1/messages) senza una quota di ragionamento, e fatturano un prezzo fisso per token. Modelli e prezzi

Il ragionamento nella richiesta successiva

Non devi rimandare indietro il ragionamento. Un blocco thinking o un elemento reasoning nella conversazione che invii non viene passato al modello, quindi un turno dell'assistente può tornare con o senza di esso. Un blocco thinking ha i due campi type e thinking; non ha signature.

Errori

Stato Tipo Messaggio Quando
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Un modello open-weight ospitato ha ricevuto un valore fuori dall'elenco, per esempio xhigh. Non viene prelevato nulla dal tuo saldo.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort non è una stringa.

Gli errori di autenticazione, di saldo e del server sono gli stessi di ogni richiesta. Gestione errori