Langkau ke kandungan
Usaha penaakulan

Usaha penaakulan

baru

Model 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)

Balasan membawa teks penaakulan dalam reasoning_content, jawapan dalam content, dan token penaakulan dalam 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}
  }
}

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?"}]
}
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 default bermaksud medium. Tidak menyertakan medan bermaksud high.
  • Model Shannon (shannon-*) menetapkan kedalamannya sendiri dalam setiap permintaan; GET /v1/models melaporkan reasoning_effort: false untuknya.

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}
  }
}

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

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_tokens mengehadkan teks jawapan. Token penaakulan tidak dikira terhadapnya.
  • Oleh sebab penaakulan dibilkan sebagai output, tahap usaha juga merupakan tetapan kos: off tidak menghasilkan token penaakulan.
  • Model Shannon melaporkan prompt_tokens, completion_tokens dan total_tokens (input_tokens dan output_tokens pada /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