جهد الاستدلال
جديدالنموذج الذي يستدل يعيد نص استدلاله بجانب الإجابة، في حقل مستقل. وفي النماذج المفتوحة الأوزان المستضافة يحدد حقل طلب واحد مدى عمق استدلال النموذج قبل أن يجيب.
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?"}
]
}' يحمل الرد نص الاستدلال في reasoning_content، والإجابة في content، وtokens الاستدلال في 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}
}
} أي النماذج تستدل
| النموذج | يعيد نص الاستدلال | يطبّق حقل الجهد |
|---|---|---|
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 | نعم | — |
| كل نموذج مفتوح الأوزان مستضاف | نعم | نعم |
هذه هي الأعلام capabilities.reasoning وcapabilities.reasoning_effort التي يبلّغ عنها GET /v1/models لكل معرّف. ولا يحمل الرد نص استدلال إلا إذا أنتج النموذج واحداً. النماذج والأسعار
ضبط الجهد
لكل نقطة نهاية صيغتها الخاصة للجهد. وكلها تختار أحد المستويات الأربعة نفسها.
| الحقل | النوع | الافتراضي | الوصف | يطبّقه |
|---|---|---|---|---|
reasoning_effort | string | high | /v1/chat/completions. مدى عمق استدلال النموذج قبل أن يجيب: off أو low أو medium أو high. | النماذج المفتوحة الأوزان المستضافة |
reasoning | object | string | /v1/chat/completions. القيمة نفسها بصيغة {"effort": "low"} أو كسلسلة مجردة. وعند إرسال الحقلين معاً يُعتمد reasoning_effort. | النماذج المفتوحة الأوزان المستضافة | |
reasoning.effort | string | high | /v1/responses. تُكتب كالكائن {"effort": "low"}. | النماذج المفتوحة الأوزان المستضافة |
thinking | object | /v1/messages. {"type": "enabled", "budget_tokens": n} أو {"type": "disabled"}. وتختار الميزانية أحد المستويات؛ انظر الجدول أدناه. | النماذج المفتوحة الأوزان المستضافة |
{
"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?"}]
} | القيمة | مقبول أيضاً | الأثر |
|---|---|---|
off | none, minimal | بلا استدلال. ولا يحمل الرد نص استدلال. |
low | استدلال موجز. | |
medium | default | عمق متوسط. |
high | max | أعمق مستوى. وهو مستوى الطلب الذي لا يرسل قيمة. |
- تُقرأ القيم دون اعتبار للأحرف الكبيرة أو الصغيرة.
- القيمة
defaultتعنيmedium. وإهمال الحقل يعنيhigh. - نماذج Shannon (
shannon-*) تحدد عمقها بنفسها في كل طلب؛ ويبلّغGET /v1/modelsعنها بـreasoning_effort: false.
ميزانية التفكير على /v1/messages
على /v1/messages يختار الحقل thinking المستوى. وbudget_tokens يختار أحد المستويات أعلاه؛ وليس حداً للـ tokens بحد ذاته. ويُقرأ adaptive مثل enabled.
| ما ترسله | المستوى |
|---|---|
{"type": "disabled"} | off |
{"type": "enabled", "budget_tokens": n} مع n حتى 2,048 | low |
n من 2,049 إلى 8,192 | medium |
n أكبر، أو enabled بدون budget_tokens | high |
لا يوجد حقل thinking | high |
أين يصل نص الاستدلال
نص الاستدلال منفصل دائماً عن الإجابة. ولكل صيغة مكانها الخاص له:
| نقطة النهاية | دون بث | مع البث |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content: سلسلة نصية، أو null إذا لم ينتج النموذج استدلالاً. | أجزاء فيها choices[0].delta.reasoning_content، قبل الأجزاء التي فيها delta.content. |
/v1/responses | عنصر output هو {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} قبل عنصر message. ولا يوجد عنصر عند عدم وجود استدلال. | response.output_item.added مع عنصر reasoning، ثم أحداث response.reasoning_summary_text.delta وحدث واحد response.reasoning_summary_text.done. |
/v1/messages | كتلة محتوى أولى {"type": "thinking", "thinking": "…"}، ثم الكتلة text. ولا توجد كتلة thinking عند عدم وجود استدلال. | كتلة محتوى thinking: content_block_start، ثم أحداث content_block_delta مع thinking_delta، ثم content_block_stop. وتتبعها كتلة النص. |
{
"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
}
} أين تنظر، لكل نموذج:
| النماذج | أين يصل النص |
|---|---|
| النماذج المفتوحة الأوزان المستضافة | على كل نقطة نهاية، مع البث أو بدونه. والطلب بجهد off، أو مع response_format / text.format، يُجاب عنه دون نص استدلال. |
shannon-3، shannon-3-pro، shannon-3.1، shannon-3.1-pro | على كل نقطة نهاية، مع البث أو بدونه، متى أنتج النموذج نص استدلال. |
shannon-2-lite، shannon-2-pro | /v1/chat/completions دون بث: في message.reasoning_content. ومع البث، في طلب بلا tools أو response_format: يحمل البث أسطر تعليق : thinking أثناء استدلال النموذج، ثم أجزاء الإجابة. /v1/messages مع البث: كتلة thinking قبل كتلة النص. |
shannon-1.6-pro، shannon-coder-1 | في الردود المبثوثة وفي الردود على الطلبات التي تحمل tools، متى أنتج النموذج نص استدلال. |
على /v1/responses، يحمل الرد غير المبثوث العنصر reasoning لعائلة Shannon 3 وللنماذج المفتوحة الأوزان المستضافة.
قراءة البث
في البث يأتي نص الاستدلال أولاً، في دلتا مستقلة، وتتبعه الإجابة. اطبع الاثنين أو خزّنهما بشكل منفصل:
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?"}
]
}' الجزء الأول من نموذج مفتوح الأوزان مستضاف، استدلالاً كان أو إجابة، يحمل أيضاً delta.role: "assistant". البث
tokens الاستدلال والفوترة
في النماذج المفتوحة الأوزان المستضافة، tokens الاستدلال هي tokens مخرجات: تُحاسَب بسعر مخرجات النموذج، ويشملها عدد المخرجات أصلاً. ويبيّن usage حصة الاستدلال هنا:
| نقطة النهاية | الحقل | ملاحظة |
|---|---|---|
/v1/chat/completions | usage.completion_tokens_details.reasoning_tokens | مُضمَّنة أصلاً في completion_tokens. |
/v1/responses | usage.output_tokens_details.reasoning_tokens | مُضمَّنة أصلاً في output_tokens. |
/v1/messages | usage.output_tokens | الاستدلال والإجابة معاً. وليس لهذه الصيغة عدٌّ منفصل. |
- في النماذج المفتوحة الأوزان المستضافة يحدّ
max_tokensمن نص الإجابة. ولا تُحتسب tokens الاستدلال عليه. - ولأن الاستدلال يُحاسَب كمخرجات، فإن مستوى الجهد هو أيضاً إعداد للتكلفة:
offلا ينتج أي tokens استدلال. - تبلّغ نماذج Shannon عن
prompt_tokensوcompletion_tokensوtotal_tokens(وinput_tokensوoutput_tokensعلى/v1/messages) دون حصة للاستدلال، وتحاسب بسعر موحد واحد لكل token. النماذج والأسعار
الاستدلال في الطلب التالي
لا تحتاج إلى إعادة إرسال الاستدلال. فكتلة thinking أو عنصر reasoning في المحادثة التي ترسلها لا يُمرَّر إلى النموذج، ولذلك يمكن إعادة دور المساعد مع الاستدلال أو بدونه. وفي كتلة thinking الحقلان type وthinking؛ وليس فيها signature.
الأخطاء
| الحالة | النوع | الرسالة | متى |
|---|---|---|---|
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | تلقى نموذج مفتوح الأوزان مستضاف قيمة خارج القائمة، مثل xhigh. ولا يُخصم شيء من رصيدك. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | reasoning_effort ليس سلسلة نصية. |
أخطاء المصادقة والرصيد والخادم هي نفسها في كل طلب. معالجة الأخطاء