Esforç de raonament
NouUn 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) 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 resposta porta el text de raonament a reasoning_content, la resposta a content i els tokens de raonament a 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}
}
} 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?"}]
} {
"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?"}]
} | 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
defaultvol dirmedium. Si omets el camp, vol dirhigh. - Els models Shannon (
shannon-*) fixen ells mateixos la profunditat a cada sol·licitud;GET /v1/modelsinformareasoning_effort: falseper 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}
}
} {
"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
}
} 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 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?"}
]
}' 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_tokenslimita 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:
offno produeix tokens de raonament. - Els models Shannon informen
prompt_tokens,completion_tokensitotal_tokens(input_tokensioutput_tokensa/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