키미 케이쓰리 리즈닝 에포트 선택 가이드

간단한 코드 수정까지 오래 걸리고, 모든 요청의 토큰 사용량이 비슷하게 높다면 reasoning_effort를 맥스로 고정했을 가능성이 큽니다.

이번 주에는 짧고 바로 검증할 수 있는 작업을 로우, 여러 파일과 일반 도구 호출을 하이, 장기 계획과 실패 비용이 큰 작업만 맥스로 나누십시오. 키미 케이쓰리는 공식 기본값이 맥스이므로, 키미 케이쓰리 에이피아이를 운영할 때는 작업별 설정과 성공한 작업 하나의 비용을 함께 기록해야 합니다. 공식 키미 케이쓰리 저장소의 설정 안내도 먼저 확인하십시오.

이 글은 키미 케이쓰리 에이피아이로 코드 에이전트, 연구 보조 도구, 다중 도구 워크플로를 개발하는 사람을 위한 안내입니다. 모든 요청을 가장 높은 추론 강도로 실행하지 않으면서 품질, 응답 시간, 토큰 비용을 함께 관리하려는 팀에 적합합니다.

마지막 업데이트: 2026년 8월 2일
데이터 확인: 공식 빠른 시작 안내, 공식 추론 강도 안내, 공식 저장소를 대조했습니다. 특정 작업의 품질과 지연 시간 차이는 실행 환경에 따라 달라지므로 일반적인 성능 수치로 단정하지 않습니다.

기본값과 세 가지 설정

공식 키미 케이쓰리 안내에 따르면 모델은 추론을 항상 사용하며, 최상위 요청 필드인 reasoning_effort에 low, high, max 중 하나를 넣어 강도를 선택합니다. 값을 생략하면 기본값은 맥스입니다. 공식 모델 사용 예제에서 필드 위치와 허용 값을 확인할 수 있습니다.

• 로우는 짧은 보완, 형식 변환, 단순 설명, 작은 범위의 코드 수정에 적합합니다. 결과를 스키마 검사, 정규식, 단위 테스트처럼 빠르게 확인할 수 있을 때 우선 검토합니다.
• 하이는 여러 파일을 읽고 수정하거나, 몇 차례 도구를 호출하거나, 테스트 명령을 실행하는 일반적인 코드 에이전트 작업의 출발점입니다.
• 맥스는 긴 계획, 여러 단계의 연구, 복잡한 의존성 해결, 실패 복구 비용이 큰 자동화에 남겨두는 편이 안전합니다.

추론 내용이 길다고 최종 답변의 품질이 자동으로 높아지는 것은 아닙니다. 결과가 요구사항을 충족했는지, 도구 호출이 끝까지 이어졌는지, 테스트가 통과했는지, 사람이 다시 고친 부분이 얼마나 되는지를 함께 평가해야 합니다.

주의: 기본값이 맥스라는 사실은 공식 문서로 확인할 수 있습니다. 그러나 특정 프로젝트에서 로우가 하이보다 빠르거나, 맥스가 더 높은 성공률을 보인다고 미리 단정할 수는 없습니다. 같은 요청과 같은 검증 절차로 직접 비교해야 합니다.

짧은 요청은 로우부터 검증합니다

짧은 요청은 결과의 범위가 좁고 성공 여부를 바로 확인할 수 있습니다. 변수명 규칙 변경, 문서 형식 변환, 한 함수의 작은 수정, 입력값 설명이 대표적입니다.

이런 요청에 맥스를 고정하면 다음과 같은 운영 문제가 생길 수 있습니다.

• 단순 결과에도 대기 시간이 길어질 수 있습니다.
• 출력 토큰과 추론 내용이 불필요하게 늘어날 수 있습니다.
• 실패가 드물어도 반복 호출에서 토큰 비용이 누적될 수 있습니다.
• 사용자가 기다리지 못해 같은 요청을 다시 보낼 수 있습니다.

먼저 로우로 실행한 뒤 다음 조건에서 하이로 올리십시오.

• 형식 검사가 실패했습니다.
• 코드 범위가 예상보다 커졌습니다.
• 추가 파일이나 도구를 확인해야 합니다.
• 같은 요청의 재시도가 반복됩니다.

단순 설명은 사람이 바로 읽고 판단할 수 있지만, 코드 수정은 짧아 보여도 테스트 실패가 숨어 있을 수 있습니다. 로우를 쓰더라도 자동 검증은 유지해야 합니다.

여러 파일 작업은 하이부터 시작합니다

여러 파일을 읽고 수정하는 코드 에이전트는 하이를 기본 출발점으로 두는 편이 좋습니다. 이 작업에서는 저장소 탐색, 의존성 확인, 파일 수정, 테스트 실행, 제한적인 도구 호출이 필요합니다.

하이로 실행한 뒤 다음 항목을 기록하십시오.

• 최종 결과가 요구사항을 충족했는지
• 필요한 도구 호출이 모두 완료됐는지
• 테스트 명령이 실제로 실행됐는지
• 사람이 수정한 파일이나 코드가 있었는지
• 재시도와 시간 초과가 발생했는지
• 입력과 출력에 사용된 토큰이 얼마나 되는지

하이에서 테스트가 통과하고 사람의 수정도 적다면 맥스로 올리지 않습니다. 반대로 계획이 계속 바뀌거나 도구 호출이 중간에 끊기거나 테스트 실패 원인을 찾지 못하면 맥스를 별도 경로로 사용합니다.

코드 에이전트는 추론 강도만 바꿔서는 안정성을 평가하기 어렵습니다. 저장소 권한, 실행 명령, 네트워크 접근, 테스트 환경도 함께 고정해야 합니다. 에이전트 개발 모드 선택 가이드처럼 실행 방식과 환경을 함께 점검하십시오.

긴 계획은 맥스로 격리합니다

장기 연구, 여러 단계의 데이터 분석, 복잡한 의존성 해결, 외부 도구를 순서대로 사용하는 자동화는 맥스를 고려할 수 있는 영역입니다. 다만 맥스를 전역 설정으로 두기보다 실패 비용이 큰 작업만 별도 경로로 보내야 합니다.

맥스 경로에서는 다음을 확인하십시오.

• 계획 단계와 실행 단계를 분리했는지
• 중간 결과를 저장하는지
• 도구 오류 뒤 작업을 재개할 수 있는지
• 완료 조건이 명확한지
• 실패 시 사람이 승인할 지점이 있는지

키미 케이쓰리는 보존된 추론 기록을 사용하는 대화 구조를 요구합니다. 다중 대화와 도구 호출에서는 이전 assistant 메시지를 content만 복사하지 말고, 반환된 메시지 전체를 다음 messages에 다시 넣어야 합니다. 여기에는 reasoning_content와 tool_calls가 포함됩니다. 공식 도구 호출 문서는 assistant 메시지와 도구 결과를 순서대로 보존하는 방법을 설명합니다.

도구 호출의 구조도 확인해야 합니다. 모델이 tool_calls를 반환하면 각 호출에 대응하는 도구 결과와 tool_call_id를 다시 전달해야 합니다. 이 순서가 어긋나면 추론 강도와 관계없이 다음 단계가 실패할 수 있습니다. 공식 도구 사용 문서를 기준으로 메시지 로그를 점검하십시오.

실시간 요청과 배치 작업의 분리

사용자가 화면 앞에서 기다리는 기능은 답변 품질만으로 평가하면 안 됩니다. 첫 응답 조각이 도착하는 시점, 전체 답변이 끝나는 시점, 사용자가 다시 요청하는지까지 확인해야 합니다.

실시간 요청에서는 다음 로그를 남기십시오.

• 요청 전송 시각
• 첫 응답 조각 도착 시각
• 첫 도구 호출 시작 시각
• 최종 답변 완료 시각
• 사용자의 재요청 여부

짧고 즉시 검증할 수 있는 요청은 로우부터 검토합니다. 여러 파일을 확인해야 하지만 사용자가 잠시 기다릴 수 있다면 하이를 선택합니다. 맥스는 사용자가 계속 화면을 보고 있지 않아도 되는 백그라운드 작업으로 보내는 편이 낫습니다.

반면 문서 일괄 처리, 정기 분석, 야간 연구 에이전트는 한 번의 응답 시간보다 성공한 작업 하나의 비용이 중요합니다. 입력 토큰, 출력 토큰, 추론 내용, 재시도, 시간 초과, 실패 복구, 캐시 적중을 한 묶음으로 계산하십시오. 공식 에이피아이 개요에서도 요청 실패 시 오류 유형과 메시지를 확인할 수 있으므로, 실패 비용을 별도 로그로 남기는 것이 좋습니다.

자동 라우팅 조건

다음 조건을 초기 라우팅 규칙으로 사용하십시오.

• 검증이 즉시 가능하고 수정 범위가 작으면 로우를 선택합니다. 형식 검사나 테스트가 실패하면 하이로 재실행합니다.
• 여러 파일을 다루고 도구 호출이 필요하지만 실패를 되돌릴 수 있으면 하이에서 시작합니다. 테스트 실패나 도구 누락이 반복되면 맥스로 올립니다.
• 긴 계획이 필요하고 실패 비용이 크면 맥스를 선택합니다. 가능한 경우 비동기 실행과 사람 승인 단계를 함께 둡니다.
• 사용자가 즉시 답을 기다리면 로우 또는 하이를 우선합니다. 맥스는 백그라운드 경로로 분리합니다.
• 재시도로 낭비되는 토큰과 시간이 커지면 한 단계 높은 강도를 시험합니다. 단순히 한 번의 토큰 사용량이 적다는 이유로 로우를 계속 유지하지 않습니다.
• 자동 검증이 어렵다면 맥스로 올리는 대신 승인 단계를 추가합니다. 추론 강도만으로 품질을 보장할 수는 없습니다.

수동 덮어쓰기 기능도 남겨야 합니다. 운영자가 특정 요청을 맥스로 보내거나, 장애 상황에서 즉시 로우로 낮출 수 있어야 합니다. 라우터가 잘못 분류했을 때 빠르게 복구할 수 있는 우회 경로도 필요합니다.

배포 전 점검 목록

• [ ] 요청에 reasoning_effort를 직접 지정했습니까?
• [ ] 값을 생략할 때 기본값이 맥스라는 점을 확인했습니까?
• [ ] 로우, 하이, 맥스별 성공 조건을 정의했습니까?
• [ ] 최종 답변과 도구 호출 완결성을 모두 기록합니까?
• [ ] 추론 내용의 길이를 품질 점수로 사용하지 않습니까?
• [ ] 입력, 출력, 추론 관련 사용량을 분리해 기록합니까?
• [ ] 재시도와 시간 초과를 성공 작업 비용에 포함합니까?
• [ ] 다중 대화에서 assistant 메시지 전체를 보존합니까?
• [ ] 하이에서 맥스로 올리는 조건이 문서화되어 있습니까?
• [ ] 운영자가 강도를 수동으로 덮어쓸 수 있습니까?
• [ ] 소량 트래픽으로 회귀 검사를 먼저 진행했습니까?

이번 주에는 짧은 코드 수정, 여러 파일을 다루는 일반 작업, 실패 비용이 큰 장기 작업을 대표 사례로 정하십시오. 각 사례를 로우, 하이, 맥스로 실행하고 성공 여부, 전체 소요 시간, 토큰 사용량, 재시도, 사람의 수정량을 저장하십시오. 이 기록이 쌓인 뒤 팀의 운영 기본값을 결정해야 합니다.

자주 묻는 설정 판단

기본값을 그대로 사용해도 되나요

개발 초기에는 가능하지만 운영 기본값으로는 주의해야 합니다. 공식 기본값이 맥스이므로 요청에서 값을 생략하면 가장 높은 추론 강도로 실행될 수 있습니다. 먼저 작업 유형을 분류하고 짧고 검증 가능한 요청에는 로우를 명시하십시오. 설정을 바꾼 뒤에는 응답 시간뿐 아니라 성공률과 재시도까지 비교해야 합니다.

추론 강도가 토큰 비용을 높이나요

추론 강도가 비용을 고정된 배수로 결정한다고 보면 안 됩니다. 실제 비용은 입력 문맥, 출력 길이, 추론 내용, 재시도, 실패 복구, 캐시 적중에 영향을 받습니다. 같은 업무를 반복해 성공한 작업 하나에 들어간 전체 토큰과 운영 시간을 계산하십시오. 단일 호출의 토큰 수만 비교하면 잘못된 결론을 내릴 수 있습니다.

코드 에이전트는 하이와 맥스 중 무엇을 써야 하나요

여러 파일 수정과 일반 도구 호출은 하이에서 시작하는 편이 좋습니다. 테스트 실패나 계획 변경이 반복되거나 한 번의 실패를 되돌리기 어렵다면 맥스로 올립니다. 배포 설정, 데이터 삭제, 보안 변경처럼 영향 범위가 큰 작업은 맥스와 사람 승인을 묶을 수 있습니다. 그래도 테스트와 승인 절차는 별도로 유지해야 합니다.

자동 전환은 어떤 신호로 만드나요

작업 분류, 검증 가능성, 실패 비용, 허용 지연 시간을 함께 사용하십시오. 테스트 실패, 도구 호출 누락, 계획 반복은 상향 신호입니다. 짧은 입력, 빠른 형식 검사, 반복적인 대량 요청은 하향 신호입니다. 라우터의 오분류에 대비해 강제 지정과 즉시 중단 기능을 제거하지 마십시오.

운영 환경까지 포함한 마지막 판단

로컬 맥에서 장시간 에이전트를 실행하면 절전, 네트워크 변경, 권한 팝업, 터미널 종료, 저장 공간 부족이 작업을 끊을 수 있습니다. 야간 배치나 반복 테스트에서는 모델 설정과 별개로 실행 환경이 측정 결과를 흔들 수 있습니다.

원격 맥 환경은 세션과 개발 도구를 일정하게 유지하기 쉽습니다. 같은 저장소와 같은 테스트 명령을 반복 실행해야 한다면 설정 비교에도 도움이 됩니다. 다만 장기간 고정 부하가 필요하거나 물리 장치 연결이 필수라면 직접 장비를 운영하는 편이 더 적합할 수 있습니다. 일시적인 테스트와 팀 공용 검증이라면 원격 맥 개발 환경 구성 사례를 참고하십시오.

현재 로컬 방식은 세션 중단, 권한 문제, 장시간 실행의 불안정성 때문에 키미 케이쓰리 설정 비교가 매번 달라질 수 있습니다. Hashvps의 원격 맥 환경을 이용하면 격리된 개발 세션에서 같은 대표 작업을 반복하고 로그를 남기기 쉽습니다. 로우, 하이, 맥스 중 어떤 값을 생산 기본값으로 둘지 아직 확신이 없다면, 먼저 원격 환경에서 작업별 기록을 확보한 뒤 결정하는 방식이 더 안전합니다.

이번 주에는 격리된 원격 개발 환경에서 대표 작업을 다시 실행하십시오. 각 강도의 로그를 보존하고, 성공한 작업 하나의 비용과 재시도까지 비교한 뒤 생산 기본값을 정하십시오. સ્થાનિક 맥에서 지속 실행이 어렵다면 원격 맥 개발 환경 구성 사례처럼 실행 환경부터 분리해 검증하는 편이 좋습니다.