Перейти до вмісту
Зусилля міркування

Зусилля міркування

Нове

Модель, що міркує, повертає текст міркувань поряд із відповіддю в окремому полі. На хостованих open-weight моделях одне поле запиту задає, наскільки глибоко модель міркує перед відповіддю.

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, а токени міркувань у 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 Так —
Кожна хостована open-weight модель Так Так

Це прапорці capabilities.reasoning і capabilities.reasoning_effort, які GET /v1/models повідомляє для кожного id. Відповідь містить текст міркувань, лише якщо модель його створила. Моделі та ціни

Задання зусилля

Кожен ендпоінт має своє написання зусилля. Усі вони вибирають один із тих самих чотирьох рівнів.

Поле Тип За замовчуванням Опис Застосовують
reasoning_effort string high /v1/chat/completions. Наскільки глибоко модель міркує перед відповіддю: off, low, medium або high. Хостовані open-weight моделі
reasoning object | string /v1/chat/completions. Те саме значення, що й {"effort": "low"}, або просто рядок. Якщо надіслано обидва поля, діє reasoning_effort. Хостовані open-weight моделі
reasoning.effort string high /v1/responses. Записується як об'єкт {"effort": "low"}. Хостовані open-weight моделі
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} або {"type": "disabled"}. Бюджет вибирає один з рівнів; див. таблицю нижче. Хостовані open-weight моделі
{
  "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 вибирає один з рівнів вище; це не окремий ліміт токенів. 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}
  }
}

Де шукати, за моделями:

Моделі Де надходить текст
Хостовані open-weight моделі На кожному ендпоінті, зі стрімінгом чи без. Запит із зусиллям 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 і хостованих open-weight моделей.

Читання стріму

У стрімі спершу йде текст міркувань в окремих дельтах, потім відповідь. Виводьте або зберігайте їх окремо:

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

Перший чанк хостованої open-weight моделі, міркування чи відповідь, також містить delta.role: "assistant". Стримінг

Токени міркувань і тарифікація

На хостованих open-weight моделях токени міркувань — це вихідні токени: вони тарифікуються за ціною виходу моделі, і кількість виходу їх уже включає. Частку міркувань тут показує 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 Міркування та відповідь разом. Цей формат не має окремого підрахунку.
  • На хостованих open-weight моделях max_tokens обмежує текст відповіді. Токени міркувань до нього не зараховуються.
  • Оскільки міркування тарифікуються як вихід, рівень зусилля є також налаштуванням вартості: off не створює токенів міркувань.
  • Моделі Shannon повідомляють prompt_tokens, completion_tokens і total_tokens (input_tokens та output_tokens на /v1/messages) без частки міркувань і тарифікують одну плоску ціну за токен. Моделі та ціни

Міркування в наступному запиті

Міркування не обов'язково надсилати назад. Блок thinking або елемент reasoning у розмові, яку ви надсилаєте, не передається моделі, тож хід асистента можна повертати з ним або без нього. Блок thinking має два поля, type і thinking; поля signature у нього немає.

Помилки

Статус Тип Повідомлення Коли
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Хостована open-weight модель отримала значення поза списком, наприклад xhigh. З вашого балансу нічого не списується.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort не є рядком.

Помилки автентифікації, балансу та сервера такі самі, як для кожного запиту. Обробка помилок