추론 effort
새로운추론하는 모델은 답변 옆의 별도 필드에 추론 텍스트를 반환합니다. 호스팅 오픈 웨이트 모델에서는 요청 필드 하나로 모델이 답변 전에 얼마나 깊이 추론할지 정합니다.
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?"}
]
}'응답은 추론 텍스트를 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 | 예 | — |
| 모든 호스팅 오픈 웨이트 모델 | 예 | 예 |
GET /v1/models가 id마다 보고하는 플래그 capabilities.reasoning과 capabilities.reasoning_effort입니다. 모델이 추론을 생성했을 때만 응답에 추론 텍스트가 포함됩니다. 모델 및 가격
강도 설정
엔드포인트마다 강도의 표기가 다릅니다. 모두 같은 네 가지 수준 중 하나를 선택합니다.
| 필드 | 유형 | 기본값 | 설명 | 적용 대상 |
|---|---|---|---|---|
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?"}]
}{
"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?"}]
}| 값 | 함께 허용되는 값 | 효과 |
|---|---|---|
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 |
n이 2,048 이하인 {"type": "enabled", "budget_tokens": n} | low |
n이 2,049에서 8,192 | medium |
더 큰 n, 또는 budget_tokens 없는 enabled | high |
thinking 필드 없음 | high |
추론 텍스트가 도착하는 위치
추론 텍스트는 항상 답변과 분리되어 있습니다. 형식마다 고유한 위치가 있습니다.
| 엔드포인트 | 스트리밍 아님 | 스트리밍 |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content: 문자열이며, 모델이 추론을 생성하지 않았으면 null입니다. | choices[0].delta.reasoning_content가 있는 청크가 delta.content가 있는 청크보다 먼저 옵니다. |
/v1/responses | message 항목 앞에 output 항목 {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]}이 옵니다. 추론이 없으면 이 항목도 없습니다. | reasoning 항목이 있는 response.output_item.added, 그다음 response.reasoning_summary_text.delta 이벤트들과 response.reasoning_summary_text.done 하나입니다. |
/v1/messages | 첫 콘텐츠 블록 {"type": "thinking", "thinking": "…"}, 그다음 text 블록입니다. 추론이 없으면 thinking 블록도 없습니다. | thinking 콘텐츠 블록: content_block_start, thinking_delta가 있는 content_block_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}
}
}{
"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
}
}모델별로 확인할 위치:
| 모델 | 텍스트가 도착하는 위치 |
|---|---|
| 호스팅 오픈 웨이트 모델 | 모든 엔드포인트에서 스트리밍 여부와 관계없이 제공됩니다. 강도가 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에서 스트리밍이 아닌 응답은 Shannon 3 계열과 호스팅 오픈 웨이트 모델에 대해 reasoning 항목을 포함합니다.
스트림 읽기
스트림에서는 추론 텍스트가 별도의 델타로 먼저 오고, 답변이 뒤따릅니다. 둘을 따로 출력하거나 저장하세요.
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 answerimport 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?"}
]
}'호스팅 오픈 웨이트 모델의 첫 청크는 추론이든 답변이든 delta.role: "assistant"도 담고 있습니다. 스트리밍
추론 토큰과 청구
호스팅 오픈 웨이트 모델에서 추론 토큰은 출력 토큰입니다. 모델의 출력 가격으로 청구되며 출력 수에 이미 포함되어 있습니다. 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는 답변 텍스트를 제한합니다. 추론 토큰은 여기에 포함되지 않습니다. - 추론은 출력으로 청구되므로 강도 수준은 비용 설정이기도 합니다.
off는 추론 토큰을 생성하지 않습니다. - Shannon 모델은 추론 몫 없이
prompt_tokens,completion_tokens,total_tokens(/v1/messages에서는input_tokens와output_tokens)를 보고하며, 토큰당 단일 가격으로 청구합니다. 모델 및 가격
다음 요청에서의 추론
추론을 다시 보낼 필요는 없습니다. 보내는 대화 안의 thinking 블록이나 reasoning 항목은 모델에 전달되지 않으므로, assistant 턴은 포함하든 하지 않든 되돌려 보낼 수 있습니다. 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가 문자열이 아닙니다. |
인증, 잔액, 서버 오류는 다른 모든 요청과 같습니다. 오류 처리