Chuyển đến nội dung
Mức độ suy luận

Mức độ suy luận

Mới

Model có suy luận trả về văn bản suy luận bên cạnh câu trả lời, trong một trường riêng. Trên các model open-weight hosted, một trường yêu cầu đặt mức độ model suy luận sâu trước khi trả lời.

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)

Phản hồi mang văn bản suy luận trong reasoning_content, câu trả lời trong content, và các token suy luận trong 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}
  }
}

Những model nào suy luận

Model Trả về văn bản suy luận Áp dụng trường effort
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 Có —
Mọi model open-weight hosted Có Có

Đây là các cờ capabilities.reasoning và capabilities.reasoning_effort mà GET /v1/models báo cáo cho từng id. Phản hồi chỉ mang văn bản suy luận khi model có tạo ra. Model và giá

Đặt mức effort

Mỗi endpoint có cách viết effort riêng. Tất cả đều chọn một trong cùng bốn mức.

Trường Loại Mặc định Mô tả Áp dụng bởi
reasoning_effort string high /v1/chat/completions. Model suy luận sâu đến đâu trước khi trả lời: off, low, medium hoặc high. Các model open-weight hosted
reasoning object | string /v1/chat/completions. Cùng giá trị đó dưới dạng {"effort": "low"} hoặc một chuỗi trần. Khi cả hai trường được gửi, reasoning_effort được ưu tiên. Các model open-weight hosted
reasoning.effort string high /v1/responses. Được viết dưới dạng đối tượng {"effort": "low"}. Các model open-weight hosted
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} hoặc {"type": "disabled"}. Ngân sách chọn một trong các mức; xem bảng bên dưới. Các model open-weight hosted
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Giá trị Cũng được chấp nhận Tác dụng
off none, minimal Không suy luận. Phản hồi không mang văn bản suy luận.
low Suy luận ngắn gọn.
medium default Độ sâu trung bình.
high max Mức sâu nhất. Đây là mức của yêu cầu không gửi giá trị nào.
  • Giá trị được đọc không phân biệt chữ hoa và chữ thường.
  • Giá trị default nghĩa là medium. Bỏ trường này nghĩa là high.
  • Các model Shannon (shannon-*) tự đặt độ sâu trong mỗi yêu cầu; GET /v1/models báo cáo reasoning_effort: false cho chúng.

Ngân sách thinking trên /v1/messages

Trên /v1/messages, trường thinking chọn mức. budget_tokens chọn một trong các mức ở trên; nó không phải là giới hạn token riêng. adaptive được đọc như enabled.

Bạn gửi Mức
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} với n đến 2,048 low
n từ 2,049 đến 8,192 medium
n lớn hơn, hoặc enabled không có budget_tokens high
Không có trường thinking high

Văn bản suy luận xuất hiện ở đâu

Văn bản suy luận luôn tách biệt với câu trả lời. Mỗi định dạng có chỗ riêng cho nó:

Endpoint Không streaming Streaming
/v1/chat/completions choices[0].message.reasoning_content: một chuỗi, hoặc null khi model không tạo ra phần nào. Các chunk có choices[0].delta.reasoning_content, trước các chunk có delta.content.
/v1/responses Một mục output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} trước mục message. Không có mục nào khi không có suy luận. response.output_item.added với một mục reasoning, rồi các sự kiện response.reasoning_summary_text.delta và một response.reasoning_summary_text.done.
/v1/messages Một khối nội dung đầu tiên {"type": "thinking", "thinking": "…"}, rồi đến khối text. Không có khối thinking khi không có suy luận. Một khối nội dung thinking: content_block_start, các sự kiện content_block_delta với thinking_delta, content_block_stop. Khối văn bản theo sau.
{
  "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}
  }
}

Nơi cần xem, theo từng model:

Model Văn bản xuất hiện ở đâu
Các model open-weight hosted Trên mọi endpoint, có streaming hay không. Yêu cầu với effort off, hoặc với response_format / text.format, được trả lời mà không có văn bản suy luận.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro Trên mọi endpoint, có streaming hay không, bất cứ khi nào model tạo ra văn bản suy luận.
shannon-2-lite, shannon-2-pro /v1/chat/completions, không streaming: trong message.reasoning_content. Có streaming, trong yêu cầu không có tools hoặc response_format: stream mang các dòng chú thích : thinking trong khi model suy luận, rồi đến các chunk câu trả lời. /v1/messages, có streaming: một khối thinking trước khối văn bản.
shannon-1.6-pro, shannon-coder-1 Trong các phản hồi streaming và trong phản hồi cho các yêu cầu mang tools, bất cứ khi nào model tạo ra văn bản suy luận.

Trên /v1/responses, phản hồi không streaming mang mục reasoning cho dòng Shannon 3 và các model open-weight hosted.

Đọc một stream

Trong stream, văn bản suy luận đến trước, trong các delta riêng, rồi câu trả lời theo sau. Hãy in hoặc lưu hai phần riêng biệt:

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 đầu tiên của model open-weight hosted, dù là suy luận hay câu trả lời, cũng mang delta.role: "assistant". Truyền phát

Token suy luận và thanh toán

Trên các model open-weight hosted, token suy luận là token đầu ra: chúng được tính phí theo giá đầu ra của model, và số đếm đầu ra đã bao gồm chúng. usage hiển thị phần suy luận ở đây:

Endpoint Trường Ghi chú
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Đã được tính trong completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Đã được tính trong output_tokens.
/v1/messages usage.output_tokens Suy luận và câu trả lời gộp chung. Định dạng này không có số đếm riêng.
  • Trên các model open-weight hosted, max_tokens giới hạn văn bản câu trả lời. Token suy luận không được tính vào giới hạn này.
  • Vì suy luận được tính phí như đầu ra, mức effort cũng là một cài đặt chi phí: off không tạo ra token suy luận nào.
  • Các model Shannon báo cáo prompt_tokens, completion_tokens và total_tokens (input_tokens và output_tokens trên /v1/messages) không tách phần suy luận, và tính phí một mức giá phẳng cho mỗi token. Model và giá

Suy luận trong yêu cầu tiếp theo

Bạn không cần gửi lại phần suy luận. Một khối thinking hoặc một mục reasoning trong cuộc hội thoại bạn gửi sẽ không được chuyển cho model, nên một lượt của assistant có thể được gửi lại có hoặc không có nó. Khối thinking có hai trường type và thinking; nó không có signature.

Lỗi

Trạng thái Loại Thông báo Khi nào
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Một model open-weight hosted nhận giá trị nằm ngoài danh sách, ví dụ xhigh. Không có gì bị trừ khỏi số dư của bạn.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort không phải là chuỗi.

Lỗi xác thực, số dư và server giống như với mọi yêu cầu. Xử lý lỗi