تخطَّ إلى المحتوى
جهد الاستدلال

جهد الاستدلال

جديد

النموذج الذي يستدل يعيد نص استدلاله بجانب الإجابة، في حقل مستقل. وفي النماذج المفتوحة الأوزان المستضافة يحدد حقل طلب واحد مدى عمق استدلال النموذج قبل أن يجيب.

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)

يحمل الرد نص الاستدلال في reasoning_content، والإجابة في content، وtokens الاستدلال في 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}
  }
}

أي النماذج تستدل

النموذج يعيد نص الاستدلال يطبّق حقل الجهد
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?"}]
}
القيمة مقبول أيضاً الأثر
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}
  }
}

أين تنظر، لكل نموذج:

النماذج أين يصل النص
النماذج المفتوحة الأوزان المستضافة على كل نقطة نهاية، مع البث أو بدونه. والطلب بجهد 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

الجزء الأول من نموذج مفتوح الأوزان مستضاف، استدلالاً كان أو إجابة، يحمل أيضاً 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 ليس سلسلة نصية.

أخطاء المصادقة والرصيد والخادم هي نفسها في كل طلب. معالجة الأخطاء