Kimi Tool Choice

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

tools로 도구가 선언되면 모델이 자체적으로 이번 턴에 도구 호출이 필요한지 결정합니다. tool_choice 파라미터는 이 동작을 명시적으로 제어 — 강제 호출, 완전 금지, 기본값 유지 중 선택.

1. 도구 호출 강제: "required"

워크플로가 도구 경로를 반드시 거쳐야 할 때(예: 필수 검색, 필수 DB 조회) 사용 — 모델이 메모리에서 답하는 것을 허용하지 않음:

{
  "tool_choice": "required"
}

모델은 이번 턴에 최소 하나의 도구를 호출해야 합니다. 요청에 호출 가능한 도구가 최소 하나 선언되어 있어야 함. 전형적인 사용은 tool-search 패턴 — 첫 턴에 "required"로 강제해 모델이 search_tools를 호출하게 한 뒤, 검색 후 "auto"로 복귀 — 자세한 내용은 Kimi K3 API Tool Calling Best Practices 참고.

2. 도구 호출 금지: "none"

요청이 평문 답변만 필요하고 모델이 도구를 잘못 트리거하지 않도록 할 때 사용:

{
  "tool_choice": "none"
}

모델이 평문으로 답변하고 tool_calls를 생성하지 않아, 지연 시간과 토큰 소비가 줄어듦.

3. 모델 위임: "auto" (기본)

tool_choice를 생략하는 것은 "auto"와 동일 — 모델이 컨텍스트를 보고 도구 호출 여부를 결정. 일반 대화에 적합.

4. 특정 도구 강제: 함수 객체 전달

세 enum 값 외에 tool_choice는 함수 객체도 받아, 특정 도구 호출을 강제할 수 있음:

{
  "tool_choice": {"type": "function", "function": {"name": "get_weather"}}
}

⚠️ 사고 모드가 활성화된 상태에서 특정 도구 강제는 현재 호환되지 않음 — 사고 ON일 때 400 에러(tool_choice 'specified' is incompatible with thinking enabled) 반환.

5. 전체 요청 예시

날씨 도구를 선언하고 tool_choice: "required"로 강제 호출하는 예시:

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": "What is the weather like in Beijing today?"},
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get the current weather for a given city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "City name"}
                    },
                    "required": ["city"],
                },
            },
        }
    ],
    # 최소 하나의 도구 호출 강제 — 생략 시 기본 "auto"
    tool_choice="required",
)

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

6. 주의사항

• tool_choice는 요청 단위 파라미터 — 각 요청에 독립적으로 적용되며, 해당 생성의 도구 선택만 제약
• tool_choice 설정(또는 미설정)은 prefix cache를 무효화하지 않음 — 요청별로 자유롭게 조정 가능

7. 관련 문서

• Kimi K3 API Tool Calling Best Practices — 동적 로딩 + tool_choice + reasoning_effort 결합 패턴
• Dynamically Loaded Tools — 대규모 도구 인벤토리에서 필요할 때 도구 정의 주입
• Use Kimi API for Tool Calls — 전체 도구 호출 워크플로우와 예제
• Model Parameter Reference — tool_choice 모델별 지원

---

변경 이력

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