Sforzo di ragionamento
NuovoUn 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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "low",
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
const message = response.choices[0].message;
console.log("Reasoning:", message.reasoning_content);
console.log("Answer:", message.content);
console.log("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "low",
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' La risposta porta il testo di ragionamento in reasoning_content, la risposta in content e i token di ragionamento in usage:
{
"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?"}]
} {
"model": "Kimi-K3-3BIT-REAP",
"reasoning": {"effort": "low"},
"input": "Is 221 a prime number?"
} {
"model": "Kimi-K3-3BIT-REAP",
"max_tokens": 1024,
"thinking": {"type": "enabled", "budget_tokens": 2048},
"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
defaultequivale amedium. Omettere il campo equivale ahigh. - I modelli Shannon (
shannon-*) impostano da soli la profondità a ogni richiesta;GET /v1/modelsriporta per lororeasoning_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}
}
} {
"output": [
{
"id": "rs_6f0a2c4e8b1d4f3a9c7e5b3d1f8a6c4e",
"type": "reasoning",
"summary": [
{
"type": "summary_text",
"text": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
}
]
},
{
"id": "msg_1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f1a",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "No. 221 = 13 x 17, so it is not prime.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 14,
"input_tokens_details": {"cached_tokens": 0},
"output_tokens": 43,
"output_tokens_details": {"reasoning_tokens": 27},
"total_tokens": 57
}
} {
"content": [
{
"type": "thinking",
"thinking": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
},
{"type": "text", "text": "No. 221 = 13 x 17, so it is not prime."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 14,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 43
}
} 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 import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const stream = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "medium",
stream: true,
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta ?? {};
if (delta.reasoning_content) process.stdout.write(delta.reasoning_content); // the reasoning text comes first
if (delta.content) process.stdout.write(delta.content); // then the answer
} curl -N https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "medium",
"stream": true,
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' 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_tokenslimita 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:
offnon produce token di ragionamento. - I modelli Shannon riportano
prompt_tokens,completion_tokensetotal_tokens(input_tokenseoutput_tokenssu/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