Kimi K3: 기능, 벤치마크, API, 그리고 5가지 실습 예제

오픈 모델 경쟁은 2026년 7월 16일 Moonshot AI가 1백만 토큰 컨텍스트 윈도우와 네이티브 비전을 갖춘 2.8조 파라미터 모델 Kimi K3를 공개하면서 다시 움직였습니다. 이는 Moonshot이 출시한 가장 큰 오픈 모델로, 규모 면에서 Kimi K2를 크게 넘어섰고, 최초로 3조 파라미터급에 도달했다고 설명한 모델입니다.

런치 스토리, 아키텍처 심층 분석, 벤치마크 차트, Claude와 GPT 및 기타 중국 연구소와의 비교, Moonshot 자체의 한계 목록까지 모두 보고 싶다면 Kimi K3 블로그 게시물에서 모두 다룹니다. 이 튜토리얼은 실습 중심으로, 접근 방법과 실제 사용 시 동작을 다룹니다. API를 통한 네 가지 예제(실제 토큰 사용량과 비용 포함)와 kimi.com 웹 앱에서의 두 가지 예제를 차례로 보여 드립니다. 함께 살펴보면 K3가 다음을 어떻게 처리하는지 알 수 있습니다:

• 도구 호출과 엄격한 JSON 반환
• 툴 정의의 온더플라이 로딩
• 자동 캐싱으로 장기 컨텍스트 비용 절감
• 스크린샷 읽기와 레이아웃 수정
• 하나의 프롬프트로 인터랙티브 대시보드 구축

네 가지 API 예제는 2026년 7월 17일 kimi-k3 모델로 실행했으며, 콜드 런에서 약 11센트가 들었습니다. 캐싱이 작동한 뒤에는 몇 센트 수준으로 줄었습니다.

Kimi K3에 접근하는 방법

가장 빠른 사용 방법은 kimi.com입니다. 웹 앱과 모바일 앱에서 일반 에이전트 작업에 Kimi K3가 별도 설정 없이 구동됩니다.

리포트나 대시보드처럼 무거운 작업에는 데스크톱 앱인 Kimi Work가 있습니다.

터미널에서 작업한다면, Kimi Code는 npm에서 @moonshot-ai/kimi-code로 설치하는 코딩 에이전트입니다. /model 명령으로 모델을 선택합니다. Kimi Code에서 K3를 사용하려면 유료 멤버십이 필요하며, 1백만 토큰 전체 윈도우는 더 높은 요금제가 필요합니다.

이 튜토리얼은 원시 API와 웹 앱에 초점을 맞추지만, 원하시면 터미널 에이전트도 사용할 수 있습니다.

다만 K3가 형제 모델들을 대체하는 것은 아닙니다. 아래 표는 현재 라인업의 구성을 보여줍니다.

간단히 말해 코드, 도구, 문서, 이미지를 혼합해 다루거나 정말로 1백만 토큰 윈도우가 필요하다면 K3부터 시작하는 것이 좋습니다. 반면, 순수한 코드 생성에서 컨텍스트보다 속도가 더 중요하다면 kimi-k2.7-code가 여전히 합리적인 선택입니다. 최신 모델이 항상 최선은 아닙니다.

Kimi K3 API 설정

API는 OpenAI SDK와 호환되므로, 이전에 사용해봤다면 거의 새로울 것이 없습니다. Python 3.9 이상과 API 키가 필요합니다.

1단계: API 키 생성

먼저 Kimi 플랫폼에 로그인한 뒤 콘솔의 API Keys 페이지를 엽니다. 키를 생성해 한 번 복사해 안전한 곳에 보관하세요. 다시 볼 수 없습니다. 호출을 위해서는 계정에 소액의 잔액이 필요하며, 이 튜토리얼 전체에 몇 달러면 충분합니다.

Kimi K3 API 키 생성. 이미지: 작성자.

2단계: SDK 설치

다음으로 OpenAI SDK를 환경에 설치합니다. 한 줄이면 됩니다.

python -m pip install --upgrade "openai>=1.0"

이 명령은 이후 예제에서 사용할 클라이언트 라이브러리를 가져오며, Kimi 전용으로 설치할 것은 없습니다.

3단계: 키 저장 및 클라이언트 초기화

코드에 키를 붙여 넣는 대신 환경 변수에서 읽어오는 것이 좋습니다. 셸이나 .env 파일에 MOONSHOT_API_KEY를 설정한 뒤, 클라이언트를 Moonshot의 기본 URL로 지정합니다.

import os
from openai import OpenAI

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

표준 OpenAI 설정과 다른 점은 base_url과 모델 이름(kimi-k3) 두 가지뿐입니다. 이대로면 호출할 준비가 끝났습니다.

4단계: 첫 호출 만들기

이제 첫 요청입니다. 모델에게 자기소개를 부탁했더니, 작은 솔직함의 순간이 나왔습니다.

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

응답은 추측하지 않겠다는 공손한 거절이었습니다. 모델은 자체 출시 이전에 학습되었기 때문에 Kimi K3에 대한 신뢰할 만한 정보가 없다며 Moonshot의 공지를 참고하라고 했습니다. 모델은 자기 자신에 대해 모른다는 유용한 상기였습니다. 방금 만든 API 호출 비용은 약 0.7센트입니다. 이 튜토리얼 내 모든 호출에 장황한 출력으로 비용이 늘지 않도록 max_completion_tokens 상한을 설정했습니다.

Kimi K3 첫 API 호출 출력. 이미지: 작성자.

예제 1: 스트리밍 추론과 최종 답변

K3는 항상 추론을 수행하며, API는 답변과는 별도 채널로 그 추론을 반환합니다. 스트리밍 시 각 청크에는 reasoning_content, 최종 content, 또는 둘 다가 담길 수 있어, 사고 과정과 답을 분리해 배치할 수 있습니다.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "A bat and a ball cost $1.10 together. The bat costs $1.00 more than the ball. How much is the ball?"}],
    max_completion_tokens=1200,
    stream=True,
    stream_options={"include_usage": True},
)

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)
    if delta.content:
        print(delta.content, end="", flush=True)

모델은 먼저 작업 과정을 스트리밍했습니다. 박쥐와 공 문제를 고전적인 인지 반성 테스트로 인식하고, 직관적인 오답인 $0.10을 지적한 뒤, 대수적으로 공이 $0.05라는 결론에 도달하고 $1.05와 $0.05가 합쳐 $1.10이 되는지 확인했습니다. 이 분리가 유용합니다. 실제 앱에서는 사용자에게는 content를 보여 주고 reasoning_content는 로그로 보관하는 것이 일반적입니다. 원시 추론을 프로덕션에 노출하는 경우는 드뭅니다. 이 호출은 출력 토큰 488개를 사용해 1센트 미만이 들었습니다.

추론 스트리밍 후 최종 답변. 이미지: 작성자.

예제 2: 구조화된 출력과 도구 호출

Kimi K3는 라인업에서 tool_choice="required"를 지원하는 모델로, 해당 턴에서 최소 한 번의 도구 호출을 강제할 수 있습니다. 추측 대신 답변 전에 데이터를 가져오게 하고 싶을 때 유용합니다. 여기서는 가격 조회와 재고 확인이라는 두 개의 모의 도구를 제공하고, 도구 호출을 강제한 뒤, 로컬에서 도구를 실행하고, response_format을 사용해 엄격한 JSON으로 결과를 요청했습니다.

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

for tool_call in assistant_message.tool_calls or []:
    args = json.loads(tool_call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": run_tool(tool_call.function.name, args)})

모델은 올바른 제품 코드로 두 도구를 모두 호출한 다음, 깔끔한 주문 요약을 JSON으로 반환했습니다. 기계식 키보드 5대, 개당 $89, 총 $445, 재고 플래그는 true로 설정되었습니다. 실무에서 중요한 두 가지 포인트가 있습니다. 도구 결과를 추가하기 전에 완전한 assistant 메시지를 대화에 다시 추가해야 하며, JSON을 파싱할 때는 reasoning 필드가 아닌 content만 사용해야 합니다. 두 번의 호출 비용은 합쳐서 1센트 미만이었습니다.

도구 호출과 구조화된 JSON 출력. 이미지: 작성자.

예제 3: 도구 동적 로딩

도구가 수십 개에 달하면, 매 요청마다 모든 정의를 보내는 것은 토큰 낭비이자 프롬프트를 어지럽힙니다. Kimi K3에서는 content가 없는 system 메시지에 tools 필드를 담아 대화 중간에 툴 정의를 주입할 수 있습니다. 그 시점부터 도구를 사용할 수 있으므로, 실제 필요해질 때까지 큰 도구 카탈로그를 캐시된 프리픽스 밖에 두게 됩니다.

messages = [
    {"role": "user", "content": "Convert 100 US dollars to euros at a rate of 0.92."},
    {"role": "system", "tools": [{
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert an amount from one currency to another",
            "parameters": {
                "type": "object",
                "properties": {"amount": {"type": "number"}, "rate": {"type": "number"}},
                "required": ["amount", "rate"],
            },
        },
    }]},
]
completion = client.chat.completions.create(model="kimi-k3", messages=messages)
print(completion.choices[0].message.tool_calls)

K3는 방금 로딩한 도구를 인식하고 의도대로 금액 100과 환율 0.92로 convert_currency를 호출했습니다. 한 가지 기억할 점은 서버가 이 정의를 보관해주지 않는다는 것입니다. 도구를 계속 사용하려면 이후 요청에도 해당 system 메시지를 재전송해야 합니다. 이 호출은 약 0.2센트로 세트 중 가장 저렴했습니다.

동적으로 로딩한 통화 도구 호출. 이미지: 작성자.

예제 4: 캐싱으로 장기 컨텍스트 비용 절감

이 예제는 1백만 토큰 윈도우가 실용적으로 쓰이는 경우입니다. 컨텍스트 캐싱은 캐시 ID나 TTL을 관리할 필요 없이 자동입니다. 큰 프리픽스를 전송하고, 이후 요청에서도 바이트 단위까지 동일하게 유지하면, 반복되는 부분이 캐시 미스 요율 대신 캐시 히트 요율로 청구됩니다. 차이를 가시화하기 위해 약 33,000 토큰의 지식 베이스를 사용해 이에 관한 질문을 했습니다.

knowledge = Path("knowledge_base.md").read_text(encoding="utf-8")
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": knowledge},
        {"role": "user", "content": "What is the rated payload of the Atlas robot?"},
    ],
    max_completion_tokens=600,
)

처음 프리픽스를 보냈을 때는 캐시되지 않아, 약 33,000 입력 토큰에 9.9센트가 들었습니다. 프리픽스가 한 번 기록된 뒤에는 동일한 요청에서 32,512개 프리픽스 토큰 전부가 캐시에 적중해 약 1.1센트로 떨어졌습니다. 거의 9배 하락입니다. 이는 가격 차이 때문입니다. 캐시된 입력은 백만 토큰당 $0.30, 캐시되지 않은 입력은 $3.00입니다. 한 가지 겪은 특이점은 캐시 기록이 비동기라는 점입니다. 바로 연속 호출하면 히트가 나타나지 않고, 이후 요청에서 반영됩니다. 그래서 스크립트를 1분 간격으로 두 번 실행하면 먼저 미스, 그다음 히트를 볼 수 있습니다.

캐시 미스 대비 캐시 히트 비용. 이미지: 작성자.

예제 5: 스크린샷에서 레이아웃 버그 찾기

비전은 K3에 네이티브로 내장되어 있으며, API로도 깔끔하게 사용할 수 있습니다. 다만 공개 이미지 URL은 받을 수 없습니다. 이미지를 base64 데이터 URL로 보내고, 메시지 content를 객체 배열로 만들어 이미지 파트와 텍스트 파트를 함께 보냅니다. 일부러 레이아웃 버그를 넣은 작은 대시보드를 렌더링해 스크린샷을 저장하고, K3에게 무엇이 문제인지 물었습니다.

의도적으로 버그를 넣은 대시보드. 이미지: 작성자.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("broken_dashboard.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": "List the layout and alignment problems you can see, and give a short CSS fix for each."},
        ],
    }],
    max_completion_tokens=3500,
)
print(completion.choices[0].message.content)

K3는 이미지를 잘 읽었습니다. 행보다 낮게 앉아 이웃과 겹치는 카드, 숫자 위에 얹힌 배지(가려진 3,910을 5,910으로 오독했는데, 그 자체로 버그를 증명합니다), 마지막 카드 앞의 들쭉날쭉한 간격, 위 카드로 피어오르는 막대, 막대 위에 겹치는 툴팁 등을 잡아냈고, 카드를 하나의 그리드로 모으는 것처럼 각 항목에 짧은 CSS 수정을 제안했습니다. 다만 거의 보이지 않는 저대비 부제는 놓쳤습니다. 즉, 비전은 미세한 디테일보다는 눈에 띄는 요소를 더 잘 잡아냅니다. 이 호출 비용은 약 2센트였습니다.

Kimi K3의 한계

API 예제들은 전반적으로 잘 작동했지만, 놀라지 않도록 알아둘 만한 거친 면도 있습니다. 대부분은 직접 겪었습니다.

• 현재는 reasoning_effort="max"만 제공되어, 비용 절감을 위해 사고 강도를 낮출 수 없습니다.

• 샘플링 설정이 고정입니다. temperature, top_p 및 페널티 값은 잠겨 있으므로, 튜닝 대신 요청에서 생략하세요.

• 출력이 길어지면 비용이 커질 수 있습니다. 예제처럼 max_completion_tokens을 제한하고, 에이전트 루프는 반드시 검증하세요.

• API에서는 공개 이미지 URL을 지원하지 않으므로, 비전 기능에는 base64나 업로드 파일을 사용할 계획을 세우세요.

치명적인 문제는 아니지만, 모델 사용 방식을 규정합니다. 특히 출력 비용을 가장 주의 깊게 보겠습니다.

결론

실행해 본 결과, 두 가지가 두드러졌습니다. 도구 호출과 구조화된 출력은 재시도가 필요 없었고, 캐싱은 예상보다 중요했습니다. 같은 긴 프리픽스를 재사용하면 큰 요청도 다시 보내기 저렴해졌기 때문입니다. 따라서 리포지토리 단위 분석, 반복적인 장기 컨텍스트 호출, 멀티모달 엔지니어링에는 K3가 합리적인 기본값입니다. 반면, 빠르고 저렴한 채팅이나 정밀한 샘플링 제어가 필요하다면 더 작은 모델이 쉬운 선택입니다. 앞서 언급한 오픈 웨이트와 라이선스 세부사항은 7월 27일 릴리스 이후 더 명확해질 것입니다.

이 예제들이 사용하는 패턴에 대한 더 많은 배경은 Developing AI Systems with the OpenAI API 코스에서 다루며, Python에서 함수 호출과 외부 도구 연계를 설명합니다.