문서 색인
전체 문서 색인을 가져오려면: https://docs.aihubmix.com/llms.txt
이 파일을 사용하여 추가 탐색 전에 사용 가능한 모든 페이지를 확인하세요.

2026년 7월 Kimi K3 가이드: reasoning_effort max, 사고 이력, 동적 도구 로딩, 구조화된 출력, 자동 캐싱, 부분 접두사 및 비전 입력.

이 문서에서는 Kimi K3의 새로운 매개변수 및 사용 노트를 다룹니다. AIHubMix에서 K3는 채팅 완성, 응답 및 Claude 호환 메시지 API를 통해 사용할 수 있습니다. 또한: Moonshot 공식 플랫폼 문서를 참조하세요.

각 섹션의 "검증된" 결론 및 샘플 응답은 2026-07-17에 AIHubMix API(채팅 완성 / 응답 / 메시지)를 통해 실제 호출에서 가져온 것입니다.

1. 모델 사양 개요

검증됨: 두 stop 제한이 검증되었으며, 이를 초과하면 400 오류가 반환됩니다; 메시지 API는 stop_sequences에 대해 동일한 검증을 적용합니다.

❗ 중지 시퀀스에 도달하면 메시지 API는 Anthropic 의미론을 따르지 않습니다: 테스트에서 stop_reason은 "end_turn" (대신 "stop_sequence"), stop_sequence는 null이며, 중지 단어 이전의 가시 텍스트는 비어 있을 수 있습니다. 이러한 두 필드를 사용하여 잘림을 감지하는 클라이언트는 주의해야 합니다.

# 6개의 항목으로 중지 / 33바이트 항목 -> HTTP 400
"잘못된 요청: 중지 배열이 너무 깁니다. 최대 길이 5의 배열이 예상되지만 길이 6의 배열이 대신 제공되었습니다."
"잘못된 요청: 중지 시퀀스는 32를 초과할 수 없지만 대신 33이 제공되었습니다."

2. 사고 모드: reasoning_effort는 max만 지원합니다.

K3의 사고는 기본적으로 켜져 있으며, reasoning_effort는 단일 수준만 지원합니다: "max".

다중 턴 대화에서는 사고 이력을 그대로 전달해야 합니다: Moonshot의 공식 문서에 따라 K3는 사고를 보존하여 훈련되었으므로 다중 턴 대화에서는 이전 어시스턴트 메시지를 완전하고 수정되지 않은 상태로 전달해야 합니다 (사고 내용 포함). 사고 이력이 누락되면 출력 품질이 불안정해집니다. 세션 관리 프레임워크나 프록시 레이어를 사용하는 경우 사고 내용이 잘리지 않고 전달되는지 확인하세요.

사고 내용은 응답의 `reasoning_content` 필드에 반환됩니다; 다중 턴 대화에서는 이전 어시스턴트 메시지(사고 내용 포함)를 그대로 전달해야 합니다.

```text theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "달팽이가 10미터 깊이의 우물 바닥에 있습니다. 매일 3미터 올라가지만 매일 밤 2미터 미끄러집니다. 정상에 도달하는 데 며칠이 걸릴까요?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```

```text theme={null}
# 다중 턴: 이전 어시스턴트 메시지를 그대로 전달
messages = [
    {"role": "user", "content": "프랑스의 수도는 어디인가요?"},
    {"role": "assistant", "content": "파리입니다.", "reasoning_content": "<이전 응답의 reasoning_content>"},
    {"role": "user", "content": "인구는요?"},
]
```

> **검증됨**: 응답은 `reasoning_content`를 반환합니다; 이전 어시스턴트 메시지(사고 내용 포함)를 그대로 전달한 후, 후속 턴은 정상적으로 응답합니다.

사고 내용은 `reasoning` 출력 항목으로 반환됩니다; 다중 턴 대화에서는 이전 턴의 출력 항목(`reasoning` + `message`)을 그대로 `input`에 추가해야 합니다.

```text theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="한 단어로 대답하세요: 프랑스의 수도는?",
)

# 관찰된 response.output 항목 유형: ["reasoning", "message"]; 텍스트: "파리"
# 다중 턴: input = [첫 번째 사용자 메시지] + response.output + [다음 사용자 메시지]
# 관찰된 두 번째 턴 응답: "베를린"
```

사고 내용은 기본 `thinking` 콘텐츠 블록으로 반환됩니다; 다중 턴 대화에서는 이전 어시스턴트 콘텐츠 블록(사고 블록 포함)을 그대로 전달해야 합니다.

```text theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "한 단어로 대답하세요: 프랑스의 수도는?"}
    ],
)

# 관찰된 response.content 블록 유형: ["thinking", "text"]; 텍스트: "파리"
# 다중 턴: 응답.content를 어시스턴트 메시지로 그대로 전달
```

3. 샘플링 매개변수는 고정되어 있습니다

K3의 샘플링 매개변수는 공급업체에 의해 고정되어 있습니다: temperature 1.0, top_p 0.95, n 1, presence_penalty / frequency_penalty 0. 공식 권장 사항은 요청에서 이러한 매개변수를 생략하는 것입니다.

참고: 고정 샘플링 값은 공식 사양의 일부이며 응답 신호에서 검증할 수 없습니다; 공식 권장 사항을 따르고 이러한 매개변수를 생략하세요.

4. 도구 호출 및 동적 도구 로딩

tools는 최대 128개의 도구를 지원합니다; tool_choice는 도구 호출을 강제하거나 비활성화하는 것을 지원합니다. K3는 또한 동적 도구 로딩을 지원합니다: 시스템 메시지의 tools 필드를 통해 대화 중간에 새로운 도구를 주입할 수 있습니다 (채팅 API에 특정한 메시지 형태).

`tool_choice`는 `auto` / `none` / `required`를 지원합니다; `required`는 모델이 도구를 호출하도록 강제합니다. 동적 도구 로딩: 도구 주입 시스템 메시지는 `content`가 없으며, 주입된 도구는 후속 턴에 적용되며, 메시지는 모든 요청에 다시 포함되어야 합니다.

```text theme={null}
messages = [
    {"role": "system", "content": "당신은 유용한 어시스턴트입니다."},
    {"role": "user", "content": "안녕하세요."},
    {"role": "assistant", "content": "안녕하세요, 어떻게 도와드릴까요?"},
    # 대화 중간에 새로운 도구 주입: 도구 필드만, 내용 없음
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "현재 시간을 가져옵니다.",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "지금 몇 시인가요?"},
]
```

```text theme={null}
# tool_choice="required"와 프롬프트 "안녕하세요" -> 모델이 도구 호출을 강제합니다.
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]
```

> **검증됨**: `tool_choice: "required"`는 관련 없는 프롬프트에 대해서도 도구 호출을 강제하며; `"none"`은 도구 호출을 억제합니다; `content` 없이 시스템 메시지를 통해 대화 중간에 주입된 도구는 정상적으로 호출될 수 있습니다.

도구 정의는 평면 구조를 사용하며 (`name`이 최상위 수준에 있음); 호출 강제화 또한 `tool_choice: "required"`를 사용하며, 호출은 `function_call` 출력 항목으로 반환됩니다. 동적 도구 로딩 지원은 진행 중입니다; 현재로서는 모든 도구를 최상위 `tools` 매개변수에 선언해야 합니다.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="안녕하세요",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "도시의 날씨를 가져옵니다.",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# 관찰된 출력: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}
```

도구는 Anthropic 형식을 사용하며 (`input_schema`); `tool_choice: {"type": "any"}`로 호출을 강제하고 `{"type": "none"}`으로 호출을 비활성화합니다. ❗ **Kimi K3의 공식 메시지 (Anthropic 호환) 엔드포인트는 동적 도구 로딩을 지원하지 않습니다**: 테스트에서 주입 메시지는 200을 반환하지만 주입된 도구는 효과가 없습니다 (모델이 호출할 수 없습니다). 모든 도구를 최상위 `tools` 매개변수에 선언하세요.

```text theme={null}
response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "도시의 날씨를 가져옵니다.",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "안녕하세요"}],
)

# 관찰됨: stop_reason "tool_use"; 내용에는 get_weather를 호출하는 tool_use 블록이 포함되어 있습니다.
```

5. 구조화된 출력

구조화된 출력은 모델이 주어진 JSON 스키마에 엄격하게 부합하는 콘텐츠를 반환하도록 합니다.

`response_format`은 `json_schema`와 `strict` 모드를 지원합니다.

```text theme={null}
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "파리는 프랑스의 수도입니다. 도시 이름을 추출하세요."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# 관찰된 응답 내용: {"city":"파리"}
```

> **검증됨**: 출력은 스키마에 부합하는 유효한 JSON입니다.

구조화된 출력은 `text.format`을 통해 선언됩니다.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="파리는 프랑스의 수도입니다. 도시 이름을 추출하세요.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# 관찰된 출력 텍스트: {"city":"파리"}
```

❗ **Kimi K3의 공식 메시지 (Anthropic 호환) 엔드포인트는 구조화된 출력을 지원하지 않습니다**: 구조화된 출력 필드는 조용히 무시되며 — 요청은 HTTP 200을 반환하고 자유 형식 텍스트를 반환하며 오류나 대체 알림이 없고, 다운스트림 JSON 파싱이 실패합니다. 구조화된 출력이 필요할 경우, 채팅 완성 또는 응답 API를 사용하세요.

6. 컨텍스트 캐싱은 자동입니다

K3의 컨텍스트 캐싱은 자동으로 활성화되며, 매개변수가 필요하지 않습니다. 반복되는 긴 접두사가 캐시에 도달하면, 적중 수는 사용량에 보고됩니다 (필드 이름은 API에 따라 다릅니다). 캐시 가격은 모델 페이지에서 확인하세요.

```text theme={null} # 동일한 긴 접두사로 두 번째 호출의 사용량 "prompt_tokens_details": {"cached_tokens": 1536} ```

> **검증됨**: 동일한 긴 접두사로 두 번째 요청은 `usage.prompt_tokens_details.cached_tokens`에서 적중을 보고합니다.

```text theme={null} # 동일한 긴 지침으로 두 번째 응답 호출의 사용량 "input_tokens_details": {"cached_tokens": 1536} ``` ```text theme={null} # 동일한 긴 시스템 프롬프트로 두 번째 메시지 호출의 사용량 "cache_read_input_tokens": 1536 ```

7. partial 접두사 완성

접두사 완성은 모델이 주어진 접두사에서 계속 생성하도록 하며, 코드 완성 및 형식 제어 출력에 적합합니다.

마지막 어시스턴트 메시지에 `"partial": true`를 전달하세요.

```text theme={null}
messages = [
    {"role": "user", "content": "바다에 대한 하이쿠를 작성하세요."},
    {"role": "assistant", "content": "파도가 거품으로 접어들고,", "partial": True},
]

# 접두사: "파도가 거품으로 접어들고,"  ->  모델이 반환하는 계속
# 소금이 공중에 떠다니고—
# 달이 조수를 집으로 끌어옵니다.
```

> **검증됨**: 주어진 접두사에서 생성이 계속되며 반복되지 않습니다.

접두사를 `input` 배열의 마지막 어시스턴트 메시지로 전달하세요; `partial` 매개변수는 필요하지 않습니다.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "바다에 대한 하이쿠를 작성하세요."},
        {"role": "assistant", "content": "파도가 거품으로 접어들고,"},
    ],
)

# 관찰된 계속: "소금이 공중에 떠다니고 / 달이 조수를 집으로 끌어옵니다."
```

동일한 기능은 프로토콜의 기본 어시스턴트 프리필을 사용하여 달성할 수 있으며, `partial` 매개변수가 필요하지 않습니다 — 접두사를 마지막 어시스턴트 메시지로 전달하세요.

```text theme={null}
response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "바다에 대한 하이쿠를 작성하세요."},
        {"role": "assistant", "content": "파도가 거품으로 접어들고,"},
    ],
)

# 관찰된 계속: "소금 바람이 갈매기의 울음소리를 실어 나릅니다— / 조수가 끌어당깁니다 ..."
```

8. 비전 입력

이미지는 base64로 전달됩니다; 콘텐츠 블록 형식은 API에 따라 다릅니다.

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "이 이미지의 주요 색상은 무엇인가요? 한 단어로."}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,"}}, ], } ]

# 관찰된 응답 내용: "빨강"  (입력: 64x64 단색 빨간색 PNG)
```

> **검증됨**: base64 이미지 입력이 작동하며, 모델이 테스트 이미지를 올바르게 설명합니다.

```text theme={null} input = [ { "role": "user", "content": [ {"type": "input_text", "text": "이 이미지의 주요 색상은 무엇인가요? 한 단어로."}, {"type": "input_image", "image_url": "data:image/png;base64,"}, ], } ]

# 관찰된 출력 텍스트: "빨강"
```

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "이 이미지의 주요 색상은 무엇인가요? 한 단어로."}, {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}}, ], } ]

# 관찰된 응답 텍스트: "빨강"
```

9. 검증된 참조: 긴 단일 호출 작업의 대기 시간 및 사용량

K3의 사고는 최대 수준으로 고정되어 있으므로 복잡한 작업에 대한 단일 요청은 일반 모델보다 상당히 오래 걸립니다. 단일 파일 HTML 게임 생성 작업(참조 이미지와 함께 한 프롬프트로, 반복 없이 한 번에 생성됨)에서 측정된 데이터: 단일 요청은 2,541초(약 42분) 걸렸으며, 74,994개의 완성 토큰 중 54,486개(73%)가 사고 토큰이었고, 최종 출력은 직접 실행 가능한 코드 1,275줄이었으며, finish_reason은 stop였습니다.

클라이언트 측 권장 사항:

• 클라이언트 타임아웃을 분 단위 이상으로 설정하고, 긴 작업에는 스트리밍을 선호하세요;
• max_completion_tokens에 충분한 여유를 두세요 — 이 경우 사고만으로 54,486 토큰이 소모되었습니다.

10. 기능 × API 지원 매트릭스

아래 표의 모든 셀은 2026-07-17에 AIHubMix 프로덕션 API에 대한 실제 호출을 통해 검증되었습니다; 각 셀은 해당 API에 대한 매개변수 / 필드 구문을 보여줍니다.

자주 묻는 질문

K3는 AIHubMix에서 어떤 API를 지원하나요?
채팅 완성 (/v1/chat/completions), 응답 (/v1/responses), 및 Claude 호환 메시지 API (/v1/messages)입니다.

사고를 비활성화하거나 줄일 수 있나요?
아니요. K3의 사고는 기본적으로 켜져 있으며, reasoning_effort는 단일 "max" 수준만 지원합니다.

왜 reasoning_content를 다중 턴 대화에서 전달해야 하나요?
K3는 사고를 보존하여 훈련되었으므로 Moonshot은 이전 어시스턴트 메시지를 완전하고 수정되지 않은 상태로 전달해야 합니다. 사고 이력이 누락되면 출력 품질이 불안정해집니다.

stop 매개변수의 제한은 무엇인가요?
최대 5개의 중지 시퀀스, 각 시퀀스는 32바이트를 초과할 수 없습니다; 어느 한 제한을 초과하면 400 오류가 반환됩니다.

메시지 API는 구조화된 출력을 지원하나요?
❗ 아니요. Kimi K3의 공식 메시지 (Anthropic 호환) 엔드포인트는 구조화된 출력 필드를 조용히 무시합니다 (200을 반환하고 자유 형식 텍스트를 반환하며 오류가 없습니다). 구조화된 출력을 위해서는 채팅 완성에서 response_format을 사용하거나 응답에서 text.format을 사용하세요.

왜 K3의 단일 요청이 그렇게 오래 걸리나요?
K3의 사고는 최대 수준으로 고정되어 있으며, 사고 토큰이 복잡한 작업에서 큰 비율을 차지합니다 (측정된 경우에서 완성 토큰의 73%). 클라이언트 타임아웃을 분 단위 이상으로 설정하고 스트리밍을 사용하세요.

가격 및 실시간 상태는 Kimi K3 모델 페이지를 참조하세요; 더 많은 모델은 모델 갤러리를 방문하세요.

마지막 업데이트: 2026-07-17