Mức độ suy luận
MớiModel 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) 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?"}
]
}' 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:
{
"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?"}]
} {
"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?"}]
} | 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ị
defaultnghĩ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/modelsbáo cáoreasoning_effort: falsecho 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}
}
} {
"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
}
} 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 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?"}
]
}' 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_tokensgiớ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í:
offkhông tạo ra token suy luận nào. - Các model Shannon báo cáo
prompt_tokens,completion_tokensvàtotal_tokens(input_tokensvàoutput_tokenstrê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