Kimi Thinking Models

상위 문서: ← Kimi Core workflows 출처: Kimi API Platform 공식 문서 — Thinking Models 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

사고 모델은 최종 답변 전에 사고 토큰을 사용해 "생각" — 문제 분해, 단계 계획, 대안 평가. 사고 과정은 응답의 reasoning_content 필드에 반환됩니다. 복잡한 추론·코드 생성·다단계 도구 호출에서 성능을 개선하지만, 지연 시간과 토큰 사용량이 증가합니다.

1. 사고 모델 선택

모델	사고 모드	Preserved Thinking	사고 강도 설정
`kimi-k3`	항상 ON	항상 ON	최상위 `reasoning_effort`: `"low"` / `"high"` / `"max"` (기본 `"max"`)
`kimi-k2.7-code`	항상 ON	항상 ON	`thinking` 파라미터 불필요 (항상 사고)
`kimi-k2.6`	기본 ON (비활성화 가능)	지원 (선택)	`thinking.type`: `"enabled"`(기본) / `"disabled"`, `thinking.keep`: `null` / `"all"`
`kimi-k2.5`	기본 ON (비활성화 가능)	미지원	`thinking.type`: `"enabled"`(기본) / `"disabled"`

요청 파라미터 비교:

필드	kimi-k3	kimi-k2.7-code	kimi-k2.6	kimi-k2.5
`reasoning_effort`	`"low"` / `"high"` / `"max"` (기본 `"max"`)	미지원	미지원	미지원
`thinking.type`	—	`"enabled"`만 (`"disabled"` 에러)	`"enabled"`(기본) / `"disabled"`	`"enabled"`(기본) / `"disabled"`
`thinking.keep`	—	`"all"`만 (다른 값 에러)	`null`(기본) / `"all"`	없음 (미지원)

벤치마크 테스트 시 benchmark best practice 참고.

2. 기본 호출

kimi-k3 호출

kimi-k3는 Preserved Thinking이 항상 ON이며 thinking 파라미터를 전달할 필요 없음. model만 설정하고 선택적으로 Reasoning Effort로 최상위 reasoning_effort 조정:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "√2가 무리수임을 증명해줘"}],
)

message = completion.choices[0].message
if hasattr(message, "reasoning_content"):
    print(getattr(message, "reasoning_content"))
print(message.content)

멀티턴 대화·도구 호출에서는 API가 반환한 assistant 메시지 전체(reasoning_content 포함)를 messages에 그대로 전달 — Preserved Thinking 참고. 자세한 K3 사용법은 Kimi K3 Quickstart 참고.

kimi-k2.7-code 호출: `thinking` 파라미터 불필요

kimi-k2.7-code는 kimi-k2.6과 동일한 사고 메커니즘(reasoning_content, 다단계 도구 호출, 스트리밍 등)을 공유. 차이는 thinking 파라미터뿐. thinking을 전달하지 마세요 — model만 바꾸면 모델이 항상 reasoning_content 출력. Preserved Thinking이 항상 ON이므로, 모든 assistant 메시지의 reasoning_content를 messages에 그대로 유지.

kimi-k2.6 호출: 기본적으로 사고 출력

kimi-k2.6는 사고가 기본 활성화되어 있어, thinking 파라미터 없이도 추론 콘텐츠 출력. (비활성화나 Preserved Thinking은 아래 참고)

3. 사고 동작 제어

K3: `reasoning_effort`로 사고 강도 조정

kimi-k3는 항상 사고하며 thinking 파라미터를 지원하지 않음. 최상위 reasoning_effort로 조정 ("low" / "high" / "max", 기본 "max"). 자세한 사용법은 Reasoning Effort 참고.

kimi-k2.6: `thinking` 파라미터

kimi-k2.6은 thinking 파라미터의 두 하위 필드로 사고 제어:

thinking.type: "enabled"(기본) / "disabled" — 사고 ON/OFF
thinking.keep: null(기본, 이전 턴 사고 무시) / "all"(Preserved Thinking 활성화)

4. 응답에서 `reasoning_content` 읽기

OpenAI SDK의 ChoiceDelta와 ChatCompletionMessage는 reasoning_content를 직접 제공하지 않음 → hasattr(obj, "reasoning_content")로 확인, getattr(obj, "reasoning_content")로 값 가져오기
다른 프레임워크 / HTTP API 직접 호출 시 content와 같은 레벨에서 직접 접근
스트리밍(stream=True)에서 reasoning_content는 항상 content보다 먼저 등장
reasoning_content의 토큰도 max_tokens로 제어됨 — reasoning_content + content 토큰 합이 max_tokens 이하여야 함

5. 다단계 도구 호출 설정

kimi-k2.7-code와 사고를 활성화한 kimi-k2.6은 다단계 도구 호출에 걸친 깊은 추론을 수행. 반드시 다음 규칙을 따르세요:

단일 작업 내 모든 reasoning_content를 컨텍스트에 유지하고 요청에 함께 전송
max_tokens >= 16000 설정
temperature 설정 금지 (모델 수정 불가)
스트리밍 활성화 (stream=True)

완전한 예제: 일일 뉴스 리포트 생성 — 모델이 date, web_search 같은 공식 도구를 순차 호출, 전체 과정에서 깊은 추론을 보여줌:

import os
import json
import httpx
import openai


class FormulaChatClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.api_key = api_key
        self.openai = openai.Client(base_url=base_url, api_key=api_key)
        self.httpx = httpx.Client(base_url=base_url, headers={"Authorization": f"Bearer {api_key}"}, timeout=30.0)
        self.model = "kimi-k2.6"

    def get_tools(self, formula_uri):
        r = self.httpx.get(f"/formulas/{formula_uri}/tools")
        r.raise_for_status()
        return r.json().get("tools", [])

    def call_tool(self, formula_uri, function, args):
        r = self.httpx.post(f"/formulas/{formula_uri}/fibers", json={"name": function, "arguments": json.dumps(args)})
        r.raise_for_status()
        fiber = r.json()
        if fiber.get("status") == "succeeded":
            return fiber["context"].get("output") or fiber["context"].get("encrypted_output")
        return fiber.get("error") or "Unknown tool error"

    def close(self):
        self.httpx.close()


# 초기화 + 도구 로드 (생략 — 위 [K3 Quickstart](./875)의 FormulaChatClient 예시와 동일)

messages = [{"role": "system", "content": "You are Kimi, a professional news analyst..."}]
messages.append({"role": "user", "content": "오늘의 기술/경제/사회 뉴스 리포트를 작성해줘"})

for iteration in range(10):
    completion = client.openai.chat.completions.create(model=client.model, messages=messages, max_tokens=1024*32, tools=all_tools)
    message = completion.choices[0].message
    if hasattr(message, "reasoning_content"):
        print(f"--- Round {iteration+1} reasoning ---")
        print(getattr(message, "reasoning_content")[:300])
    messages.append(message)  # <-- reasoning_content 보존
    if not message.tool_calls:
        print("--- Final answer ---")
        print(message.content)
        break
    for tc in message.tool_calls:
        result = client.call_tool(tool_to_uri[tc.function.name], tc.function.name, json.loads(tc.function.arguments))
        messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

6. Preserved Thinking (턴 간 사고 보존)

Preserved Thinking은 멀티턴 대화에서 이전 턴의 reasoning_content를 다음 요청에 함께 전달해 현재 턴의 추론에서 이전 사고 사슬을 이어갈 수 있게 함.

kimi-k2.6의 경우 thinking.keep 파라미터로 제어:

값	동작
`null` / 생략 (기본)	이전 `reasoning_content` 무시. 컨텍스트 짧고 비용 낮음
`"all"`	이전 `reasoning_content` 완전히 보존

thinking.keep은 이전 턴의 reasoning_content에만 영향. 현재 턴의 사고 생성/출력은 thinking.type이 제어. keep: "all"은 type: "enabled"와 함께 사용 권장.

kimi-k2.7-code는 Preserved Thinking이 항상 ON이라 끌 수 없음. thinking.keep 생략 또는 "all" 전달 시 항상 "all"로 처리 (다른 값은 에러). 이 모델 사용 시 모든 이전 assistant 메시지의 reasoning_content를 messages에 그대로 유지해야 함.

keep: "all" 사용 시, 모든 이전 assistant 메시지의 reasoning_content를 messages에 그대로 유지. 가장 간단한 방법은 이전 API 호출의 assistant 메시지를 그대로 다시 추가.

import os
import openai

client = openai.Client(base_url="https://api.moonshot.ai/v1", api_key=os.getenv("MOONSHOT_API_KEY"))

messages = [
    {"role": "system", "content": "You are Kimi."},
    {"role": "user", "content": "첫 번째 질문..."},
    {"role": "assistant", "reasoning_content": "<이전 reasoning>", "content": "<이전 답변>"},
    {"role": "user", "content": "분석을 이어서 다음 단계를 유도해줘"},
]

response = client.chat.completions.create(
    model="kimi-k2.6",
    messages=messages,
    stream=True,
    extra_body={"thinking": {"type": "enabled", "keep": "all"}},
)

⚠️ reasoning_content는 토큰 소비에 포함. Preserved Thinking 활성화 시 이전 사고 콘텐츠가 컨텍스트 윈도우를 계속 차지하고 그만큼 과금.

7. 자주 묻는 질문

Q1. 왜 reasoning_content를 유지해야 하나요?

다단계 추론(특히 도구 호출)의 연속성을 보장. API가 반환한 완전한 assistant 메시지를 messages에 그대로 전달. K3는 멀티턴·도구 호출 루프에서 필수. K2.x의 턴 간 보존은 모델별 thinking.keep 동작에 따름: kimi-k2.6은 기본 보존 안 함, kimi-k2.7-code는 항상 보존.

Q2. reasoning_content가 추가 토큰을 소모하나요?

네, reasoning_content는 입력/출력 토큰 할당량에 포함. 자세한 가격은 Pricing 참고.

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 Thinking Models 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거