Usaha penaakulan
baruModel yang bernalar memulangkan teks penaakulannya di sebelah jawapan, dalam medan tersendiri. Pada model open-weight yang dihoskan, satu medan permintaan menetapkan sedalam mana model bernalar sebelum menjawab.
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?"}
]
}' Balasan membawa teks penaakulan dalam reasoning_content, jawapan dalam content, dan token penaakulan dalam 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}
}
} Model mana yang bernalar
| Model | Memulangkan teks penaakulan | Menggunakan medan usaha |
|---|---|---|
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 | Ya | — |
| Setiap model open-weight yang dihoskan | Ya | Ya |
Ini ialah bendera capabilities.reasoning dan capabilities.reasoning_effort yang dilaporkan oleh GET /v1/models bagi setiap id. Balasan membawa teks penaakulan hanya apabila model menghasilkannya. Model & harga
Menetapkan usaha
Setiap endpoint mempunyai ejaan usaha tersendiri. Semuanya memilih salah satu daripada empat tahap yang sama.
| Medan | Jenis | Lalai | Penerangan | Dilaksanakan oleh |
|---|---|---|---|---|
reasoning_effort | string | high | /v1/chat/completions. Sedalam mana model bernalar sebelum menjawab: off, low, medium atau high. | Model open-weight yang dihoskan |
reasoning | object | string | /v1/chat/completions. Nilai yang sama seperti {"effort": "low"} atau sebagai rentetan sahaja. Apabila kedua-dua medan dihantar, reasoning_effort yang diambil kira. | Model open-weight yang dihoskan | |
reasoning.effort | string | high | /v1/responses. Ditulis sebagai objek {"effort": "low"}. | Model open-weight yang dihoskan |
thinking | object | /v1/messages. {"type": "enabled", "budget_tokens": n} atau {"type": "disabled"}. Bajet memilih salah satu tahap; lihat jadual di bawah. | Model open-weight yang dihoskan |
{
"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?"}]
} | Nilai | Turut diterima | Kesan |
|---|---|---|
off | none, minimal | Tiada penaakulan. Balasan tidak membawa teks penaakulan. |
low | Penaakulan ringkas. | |
medium | default | Kedalaman sederhana. |
high | max | Tahap paling dalam. Ini ialah tahap permintaan yang tidak menghantar nilai. |
- Nilai dibaca tanpa mengira huruf besar atau kecil.
- Nilai
defaultbermaksudmedium. Tidak menyertakan medan bermaksudhigh. - Model Shannon (
shannon-*) menetapkan kedalamannya sendiri dalam setiap permintaan;GET /v1/modelsmelaporkanreasoning_effort: falseuntuknya.
Bajet thinking pada /v1/messages
Pada /v1/messages, medan thinking memilih tahap. budget_tokens memilih salah satu tahap di atas; ia bukan had token tersendiri. adaptive dibaca seperti enabled.
| Anda hantar | Tahap |
|---|---|
{"type": "disabled"} | off |
{"type": "enabled", "budget_tokens": n} dengan n sehingga 2,048 | low |
n daripada 2,049 hingga 8,192 | medium |
n yang lebih besar, atau enabled tanpa budget_tokens | high |
Tiada medan thinking | high |
Tempat teks penaakulan tiba
Teks penaakulan sentiasa berasingan daripada jawapan. Setiap format mempunyai tempatnya sendiri:
| Endpoint | Tidak di-stream | Di-stream |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content: rentetan, atau null apabila model tidak menghasilkan apa-apa. | Chunk dengan choices[0].delta.reasoning_content, sebelum chunk dengan delta.content. |
/v1/responses | Item output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} sebelum item message. Tiada item apabila tiada penaakulan. | response.output_item.added dengan item reasoning, kemudian peristiwa response.reasoning_summary_text.delta dan satu response.reasoning_summary_text.done. |
/v1/messages | Blok kandungan pertama {"type": "thinking", "thinking": "…"}, kemudian blok text. Tiada blok thinking apabila tiada penaakulan. | Blok kandungan thinking: content_block_start, peristiwa content_block_delta dengan thinking_delta, content_block_stop. Blok teks menyusul. |
{
"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
}
} Tempat untuk melihat, bagi setiap model:
| Model | Tempat teks tiba |
|---|---|
| Model open-weight yang dihoskan | Pada setiap endpoint, di-stream atau tidak. Permintaan dengan usaha off, atau dengan response_format / text.format, dijawab tanpa teks penaakulan. |
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | Pada setiap endpoint, di-stream atau tidak, apabila model menghasilkan teks penaakulan. |
shannon-2-lite, shannon-2-pro | /v1/chat/completions, tidak di-stream: dalam message.reasoning_content. Di-stream, dalam permintaan tanpa tools atau response_format: stream membawa baris komen : thinking semasa model bernalar, kemudian chunk jawapan. /v1/messages, di-stream: blok thinking sebelum blok teks. |
shannon-1.6-pro, shannon-coder-1 | Dalam balasan yang di-stream dan dalam balasan kepada permintaan yang membawa tools, apabila model menghasilkan teks penaakulan. |
Pada /v1/responses, balasan yang tidak di-stream membawa item reasoning bagi keluarga Shannon 3 dan model open-weight yang dihoskan.
Membaca stream
Dalam stream, teks penaakulan datang dahulu, dalam delta tersendiri, dan jawapan menyusul. Cetak atau simpan keduanya secara berasingan:
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?"}
]
}' Chunk pertama model open-weight yang dihoskan, penaakulan atau jawapan, turut membawa delta.role: "assistant". Penstriman
Token penaakulan dan pengebilan
Pada model open-weight yang dihoskan, token penaakulan ialah token output: ia dibilkan pada harga output model, dan kiraan output sudah merangkumi token itu. usage menunjukkan bahagian penaakulan di sini:
| Endpoint | Medan | Nota |
|---|---|---|
/v1/chat/completions | usage.completion_tokens_details.reasoning_tokens | Sudah termasuk dalam completion_tokens. |
/v1/responses | usage.output_tokens_details.reasoning_tokens | Sudah termasuk dalam output_tokens. |
/v1/messages | usage.output_tokens | Penaakulan dan jawapan bersama. Format ini tidak mempunyai kiraan berasingan. |
- Pada model open-weight yang dihoskan,
max_tokensmengehadkan teks jawapan. Token penaakulan tidak dikira terhadapnya. - Oleh sebab penaakulan dibilkan sebagai output, tahap usaha juga merupakan tetapan kos:
offtidak menghasilkan token penaakulan. - Model Shannon melaporkan
prompt_tokens,completion_tokensdantotal_tokens(input_tokensdanoutput_tokenspada/v1/messages) tanpa bahagian penaakulan, dan membilkan satu harga rata bagi setiap token. Model & harga
Penaakulan dalam permintaan seterusnya
Anda tidak perlu menghantar penaakulan kembali. Blok thinking atau item reasoning dalam perbualan yang anda hantar tidak diteruskan kepada model, jadi giliran assistant boleh dihantar kembali dengan atau tanpanya. Blok thinking mempunyai dua medan type dan thinking; ia tidak mempunyai signature.
Ralat
| Status | Jenis | Mesej | Bila |
|---|---|---|---|
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Model open-weight yang dihoskan menerima nilai di luar senarai, contohnya xhigh. Tiada apa-apa ditolak daripada baki anda. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | reasoning_effort bukan rentetan. |
Ralat pengesahan, baki dan server adalah sama seperti bagi setiap permintaan. Pengendalian Ralat