Kimi K3 Quickstart

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

---

Kimi K3 소개

Kimi K3는 Kimi의 가장 강력한 플래그십 모델로, 2.8조(Trillion) 파라미터를 갖추고 있습니다. Kimi Delta Attention (KDA) — 하이브리드 선형 어텐션 메커니즘 — 과 Attention Residuals (AttnRes) 를 기반으로 구축되었으며, 네이티브 시각 이해와 1M 토큰 컨텍스트 윈도우를 제공합니다. 3-조(Trillion) 파라미터급에서 세계 최초의 오픈소스 모델이며, 장기 코딩, 지식 작업, 추론 등 최첨단 지능 시나리오를 위해 설계되었습니다.

전체 벤치마크와 케이스 스터디는 기술 블로그에서 확인할 수 있습니다. Kimi는 현재 추론 파트너 및 오픈소스 메인테이너와 긴밀히 협력해 기술적 세부 사항을 조율하고 생태계 전반에 안정적으로 출시되도록 준비 중입니다. 전체 모델 가중치는 2026년 7월 27일까지 공개 예정이며, 아키텍처·학습·평가에 대한 자세한 내용은 Kimi K3 기술 보고서와 함께 공개됩니다.

3-조급 오픈소스 모델

Kimi K3는 2.8조 파라미터에 도달한 최초의 오픈소스 모델입니다. 이는 Kimi가 모델 스케일의 경계를 계속 밀어붙여 온 최신 결과로, 최근 12개월 중 9개월(2025/07–2026/07)에 걸쳐 Kimi 모델이 오픈소스 모델 스케일의 최전선을 유지해 왔습니다.

Kimi K3는 Kimi Delta Attention (KDA) 와 Attention Residuals (AttnRes) 를 기반으로 합니다. 두 아키텍처 개선 모두 더 긴 시퀀스와 더 깊은 모델에서 정보가 더 원활히 흐르도록 설계되었습니다. 또한 Mixture of Experts (MoE) 의 sparsity를 더욱 높여, Stable LatentMoE 프레임워크로 896개 expert 중 16개를 효율적으로 활성화합니다. 학습 방법론과 데이터 레시피 개선과 함께, 이러한 구조적 진보로 Kimi K3는 K2 대비 전체 스케일링 효율이 약 2.5배 높아, 컴퓨팅을 더 효과적으로 capability로 전환합니다.

Coding (코딩)

Kimi K3는 강력한 장기(long-horizon) 코딩 능력을 갖추고 있습니다. 최소한의 인간 감독만으로 장기간 실행되는 엔지니어링 작업을 지속할 수 있으며, 대규모 코드베이스를 이해하고 다루며, 터미널 도구를 조율할 수 있습니다.

Kimi K3는 또한 소프트웨어 엔지니어링과 시각적 추론을 결합한 작업에서도 탁월합니다. 스크린샷과 시각적 피드백을 활용해 게임 개발, 프론트엔드 엔지니어링, CAD 및 관련 시나리오의 워크플로우를 개선할 수 있습니다.

Knowledge work (지식 작업)

Kimi K3는 엔드투엔드 지식 작업에서 한 단계 더 발전했습니다. 공개 벤치마크를 넘어, Kimi K3 (max) 는 Kimi의 내부 평가에서도 일관된 향상을 보여줍니다. 이러한 평가는 실제 사용자-에이전트 협업 워크플로우에서 반복적으로 나타나는 작업 패턴과 과제를 반영합니다. Kimi K3는 프로덕션 지향 워크플로우 전반에서 일관된 이점을 보여주며, 이는 에이전틱 지식 작업 능력의 광범위한 개선을 시사합니다.

---

접근 요구사항

Kimi K3는 플래그십 모델로, 충전 완료 후 (최소 $1) 에 사용 가능합니다. 누적 충전 금액에 따라 계정 등급과 rate limit(동시성, RPM, TPM, TPD)이 결정됩니다 — 충전과 Rate Limit 참고.

---

시작하기

• Playground — 대화형으로 모델 성능 테스트
• API Key 발급

예제는 Python 3.9+ 와 OpenAI SDK가 필요합니다. SDK 설치와 클라이언트 초기화는 한 번만 하면, 이후 예제들에서 client를 재사용합니다.

python3 -m pip install --upgrade 'openai>=1.0'

import os
from openai import OpenAI

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

---

기본 호출

Python

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Introduce Kimi K3 in one sentence."}],
)

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

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Introduce Kimi K3 in one sentence."}]
  }'

---

Thinking Effort (사고 강도)

K3는 항상 사고 모드가 활성화되어 있으며, 최상위 reasoning_effort 요청 필드로 사고 강도를 설정할 수 있습니다.

사고 강도 값: low, high, max 지원 (기본값 max). 자세한 사용법은 Thinking Effort 참고.

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
)

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

멀티턴 대화·도구 호출 시: API가 반환한 assistant 메시지 전체를 다음 요청에 그대로 추가하세요. content만 유지하지 마세요.

---

Streaming

스트리밍 응답은 reasoning_content와 최종 응답 content의 델타를 분리해 제공합니다. 자세한 내용은 Streaming Output 참고.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explain why the sky is blue."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

---

Vision Input

Vision 메시지는 content를 객체 배열로 전달해야 합니다 (직렬화된 문자열 X). 형식과 제한은 Vision Input 참고.

로컬 이미지

import base64
from pathlib import Path

image_data: str = base64.b64encode(Path("image.png").read_bytes()).decode()
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

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

비디오 파일

from pathlib import Path

video = client.files.create(file=Path("video.mp4"), purpose="video")
try:
    completion = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize this video."},
                ],
            }
        ],
    )
    print(completion.choices[0].message.content)
finally:
    client.files.delete(video.id)

---

Structured Output (구조화된 출력)

json_schema와 strict: true로 최종 message.content를 제약하세요. reasoning_content는 파싱하지 말고 content만 파싱하세요.

import json

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Lin is 28 years old. Extract the name and age."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

person: dict[str, object] = json.loads(
    completion.choices[0].message.content or "{}"
)
print(person)

자세한 내용은 Structured Output 참고.

---

Partial Mode (부분 모드)

messages 마지막에 partial=True인 assistant 메시지를 추가해 텍스트 접두어에서 이어서 생성합니다. 최종 결과를 표시할 때 그 접두어를 앞에 붙여주세요.

prefix: str = "Conclusion: "
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "In one sentence, explain why API compatibility matters."},
        {"role": "assistant", "content": prefix, "partial": True},
    ],
)

print(prefix + (completion.choices[0].message.content or ""))

자세한 내용은 Partial Mode 참고.

---

Custom Tools and tool_choice

첫 번째 턴에서 tool_choice="required"로 설정해 최소 하나의 도구 호출을 강제하세요. 모든 호출 실행 후, 완전한 assistant 메시지를 반환하고 각 호출에 대해 매칭되는 tool_call_id로 tool result를 추가하세요.

import json
from typing import Any

tools: list[dict[str, Any]] = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]
messages: list[Any] = [
    {"role": "user", "content": "What is the weather in San Francisco today?"}
]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)
assistant_message = first.choices[0].message
messages.append(assistant_message)

for tool_call in assistant_message.tool_calls or []:
    arguments: dict[str, str] = json.loads(tool_call.function.arguments)
    result: str = json.dumps(
        {"city": arguments["city"], "weather": "sunny", "temperature_c": 24}
    )
    messages.append(
        {"role": "tool", "tool_call_id": tool_call.id, "content": result}
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)
print(final.choices[0].message.content)

자세한 내용은 Tool Choice 참고.

---

Dynamic Tool Loading (동적 도구 로딩)

content 없이 완전한 도구 정의를 system 메시지에 두면, 그 메시지부터 도구가 사용 가능해집니다.

from typing import Any

dynamic_messages: list[dict[str, Any]] = [
    {"role": "user", "content": "Calculate 23 times 47."},
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "calculate",
                    "description": "Evaluate an arithmetic expression",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "expression": {
                                "type": "string",
                                "description": "The arithmetic expression to evaluate",
                            }
                        },
                        "required": ["expression"],
                    },
                },
            }
        ],
    },
]
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=dynamic_messages,
)

print(completion.choices[0].message.tool_calls)

주의사항

• name, description, parameters 정의를 빠짐없이 포함할 것
• 선언은 messages의 그 위치부터 적용됨
• 이후 요청 기록에 이 메시지를 유지할 것 (서버는 보관하지 않음)

자세한 내용은 Dynamic Tool Loading 참고.

---

1M Context and Automatic Caching (1M 컨텍스트와 자동 캐싱)

새 요청이 prefix cache에 도달하려면 직전 요청의 prompt 토큰이 256을 초과해야 합니다. 직전 요청이 256 미만이면 캐시되지 않고 폐기됩니다. 자세한 내용은 Context Caching 참고.

정규 모델 요청에 대해 컨텍스트 캐싱은 자동으로 동작합니다. cache ID, TTL, 추가 파라미터가 필요 없습니다. 긴 prefix를 변경하지 말고 그대로 두면, 이후 요청이 자동으로 cache hit을 시도합니다.

from pathlib import Path

knowledge: str = Path("knowledge-base.md").read_text(encoding="utf-8")

for question in ["Summarize the key conclusions.", "List three implementation risks."]:
    completion = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {"role": "system", "content": knowledge},
            {"role": "user", "content": question},
        ],
    )
    print(completion.choices[0].message.content)

자세한 내용은 Context Caching 참고.

---

Official Tools (공식 도구)

공식 도구는 Formula를 통해 통합됩니다.

1. Formula /tools 엔드포인트에서 도구 정의 가져오기
2. Chat Completions의 tools 필드에 정의 추가
3. 모델이 tool_calls를 반환하면 각 함수 이름과 인자를 Formula /fibers 엔드포인트에 제출
4. 완전한 assistant 메시지와 Fiber 출력을 대응되는 tool 메시지로 추가
5. 모델이 최종 답변을 반환할 때까지 Chat Completions를 다시 호출

자세한 클라이언트/API 계약은 Official Tools 참고. 웹 검색은 업데이트 중이므로 가까운 시일 내 사용을 권장하지 않습니다.

---

Important Limits (주요 제한)

• 사고 강도는 최상위 reasoning_effort 요청 필드로 설정하며 low, high, max (기본 max) 지원. K3는 항상 사고 모드 활성화.
• max_completion_tokens 기본값은 131072이며 최대 1048576까지 설정 가능
• temperature=1.0, top_p=0.95, n=1, presence_penalty=0, frequency_penalty=0은 고정값 — 요청에 포함하지 마세요
• 멀티턴 대화·도구 호출 시 assistant 메시지 전체를 변경 없이 그대로 반환
• Vision 입력은 공개 이미지 URL을 지원하지 않음. base64 또는 ms://<file-id> 사용, content는 객체 배열이어야 함
• 웹 검색은 업데이트 중이므로 가까운 시일 내 프로덕션 워크플로우에 권장하지 않음

---

FAQ

Q. Kimi K3 요금은 어떻게 되나요?

Kimi K3는 1M 토큰 컨텍스트를 제공하며 균일한 종량제(pay-as-you-go) 가격을 사용합니다 — 컨텍스트 길이에 따른 차등 없음. 입력(cache hit/miss별 요금 구분)과 출력 모두 균일한 per-token 가격이 적용됩니다. Kimi K3 가격 참고.

Q. Kimi K3의 chain-of-thought를 끌 수 있나요?

끌 수 없습니다 — K3는 항상 사고합니다. 사고가 너무 오래 걸린다면 reasoning_effort를 low로 설정해 사고 강도를 낮추세요. Thinking Effort 참고.

---

Model Pricing

토큰 가격 상세는 Model Pricing 참고.

---

관련 문서

문서	설명
Thinking Effort	reasoning_effort 설정
Vision Input	이미지·비디오 전송
Structured Output	엄격한 JSON Schema
Partial Mode	접두어에서 이어 생성
Tool Choice	모델의 도구 호출 제어
Dynamic Tool Loading	도구 정의를 동적 주입
Tool Calling Best Practices	도구 호출 기능 조합
Official Tools	Formula 도구 통합
Kimi K3 Pricing	입력·출력 가격

---

변경 이력

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