Kimi K3 API 전환 검수 목록

첫 호출이 성공해도 바로 운영 트래픽을 옮기면 안 됩니다. 2026년 7월 28일 기준 이번 주에는 기존 공식 API를 기준선으로 고정하고, 먼저 계약 테스트와 그림자 트래픽을 끝낸 뒤 저위험 작업만 단계적으로 전환해야 합니다. 아직 출시 상태나 기능 문서가 명확하지 않은 후보는 가격을 추정하지 말고 대기 목록에 두어야 합니다.

이 글은 이미 Kimi K3 공식 API를 쓰면서 보조 공급자를 추가하려는 에이전트 팀을 위한 글입니다. 다른 모델에서 Kimi K3로 바꾸려는 플랫폼 엔지니어는 도구 호출과 구조화된 응답을 먼저 확인해야 합니다. 비용, 안정성, 데이터 처리를 책임지는 기술 책임자는 아래 조건을 그대로 출시 서명표로 사용할 수 있습니다.

마지막 업데이트: 2026년 7월 28일. 모델 공개 상태와 기능은 Moonshot AI의 공식 모델 문서, Kimi API 시작 문서, Fireworks 공식 모델 페이지, Together AI 공식 모델 페이지를 기준으로 확인했습니다.

전환 전 기준선 고정

전형적인 실패는 이렇습니다. 일반 문장은 정상적으로 반환됩니다. 그러나 에이전트가 도구를 호출하는 순간 reasoning_content가 사라지고, 다음 차례에 필요한 전체 보조 메시지가 전달되지 않습니다. 결과적으로 함수 인자는 비어 있거나, 같은 작업이 재시도되어 두 번 실행됩니다.

Kimi K3는 사고 내용을 항상 사용하는 모델이며, 여러 차례 대화와 도구 호출에서는 이전 보조 메시지를 그대로 다시 전달해야 합니다. content만 복사하는 방식은 공식 API에서도 안정적인 다중 차례 처리 방식이 아닙니다.

먼저 현재 운영값을 별도 문서에 고정합니다.

Kimi K3 공식 문서는 OpenAI 형식과의 호환, 스트리밍, 시각 입력, 도구 호출, JSON 모드를 안내합니다. 그러나 호환 형식이라는 말만으로 각 공급자의 오류 객체, 사용량 필드, 도구 호출 순서까지 같다고 가정하면 안 됩니다.

후보 상태도 같은 날짜에 따로 적습니다.

Fireworks 페이지에는 Kimi K3가 준비 완료 상태이며 서버리스 호출, 함수 호출, 이미지 입력이 지원된다고 표시되어 있습니다. 서버리스 단가는 입력, 캐시 입력, 출력 순서로 공개되어 있지만, 이 글에서는 실제 업무 비용을 대신한다고 보지 않습니다.

Together AI 페이지에는 Kimi K3의 모델 식별자와 API 예제가 노출되어 있지만, 출시 안내 문구가 변경될 수 있으므로 문서와 실제 계정 호출을 함께 확인해야 합니다. 공식 페이지에 표시된 모델 이름은 moonshotai/Kimi-K3입니다.

계약 테스트 항목

Kimi K3 API 공급자 변경에 필요한 기능

첫 접속에서는 답변 품질을 평가하지 않습니다. 인터페이스가 기존 코드의 기대와 같은지 확인합니다. 최소 요청은 다음 순서로 구성합니다.

1. 새 인증 키가 환경 변수로만 주입되는지 확인합니다.
2. 후보별 모델 식별자를 설정 파일에서 분리합니다.
3. 일반 응답과 스트리밍 응답을 각각 호출합니다.
4. 종료 이유, 사용량, 요청 식별자를 저장합니다.
5. 잘못된 키, 잘못된 모델, 제한 초과, 시간 초과 응답을 일부러 발생시킵니다.
6. 도구 호출과 구조화된 응답을 별도 테스트합니다.

export MODEL_PROVIDER="fireworks"
export MODEL_NAME="accounts/fireworks/models/kimi-k3"

curl -sS "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_NAME"'",
    "messages": [
      {"role": "user", "content": "두 문장으로 답하세요."}
    ],
    "stream": false
  }'

출력 예시는 특정 공급자의 실제 응답을 뜻하지 않습니다. 아래처럼 팀이 비교할 필드를 정해 두는 것이 목적입니다.

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "content": "답변 본문"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

계약 테스트에서 특히 놓치기 쉬운 부분은 네 가지입니다.

• 스트리밍 중간에 연결이 끊겼을 때 마지막 조각을 정상적으로 닫는지 확인합니다.
• 도구 인자의 자료형이 문자열로 바뀌지 않는지 확인합니다.
• 병렬 도구 호출의 순서와 호출 식별자가 보존되는지 확인합니다.
• 잘못된 구조화 응답이 왔을 때 자동 재시도가 작업을 다시 실행하지 않는지 확인합니다.

공급자별 도구 호출 구현은 Fireworks의 공식 함수 호출 안내처럼 별도 문서로 확인해야 합니다. 같은 요청 형식을 사용하더라도 병렬 호출, 인자 검증, 오류 반환 방식이 다를 수 있기 때문입니다.

Kimi K3 공식 문서에는 사고 수준을 low, high, max로 지정하는 요청 필드와 보조 메시지를 보존하는 다중 차례 사용 방식이 안내되어 있습니다. 공급자가 같은 필드를 받더라도 실제 응답의 보존 방식은 반드시 직접 검증해야 합니다.

Kimi K3 도구 호출 전환 검수

도구 호출은 단순한 텍스트 비교가 아닙니다. 다음 업무를 별도 사례로 만듭니다.

• 조회 도구 하나를 호출하는 작업
• 서로 독립된 도구 두 개를 동시에 호출하는 작업
• 도구 오류 뒤 다른 도구로 회복하는 작업
• 도구 결과를 구조화된 최종 응답으로 변환하는 작업
• 같은 대화에서 두 번째 도구 호출을 수행하는 작업

판정값은 성공과 실패만 기록하지 않습니다. 도구 이름, 인자 자료형, 호출 횟수, 종료 이유, 최종 응답 형식, 재시도 횟수를 함께 저장합니다. 하나라도 기존 에이전트의 의미와 달라지면 텍스트 호출이 성공했더라도 전환 불가입니다.

그림자 트래픽 검증

계약 테스트를 통과한 뒤에는 실제 업무의 일부를 복제합니다. 후보 결과는 사용자에게 보이지 않게 하고, 현재 공식 API의 결과만 사용자에게 전달합니다.

테스트 묶음은 팀의 실제 작업으로 구성해야 합니다. 코드 변경, 긴 문서 요약, 화면 이미지 분석, 구조화된 추출, 여러 도구를 거치는 에이전트 작업을 섞습니다. 공개 벤치마크 점수는 모델의 참고 자료일 뿐이며, 팀의 오류율이나 완료율을 대신하지 못합니다. Moonshot AI의 모델 카드에도 코드, 도구, 시각 작업별 평가가 나뉘어 있으므로 단일 점수로 운영 적합성을 결정해서는 안 됩니다.

그림자 요청에는 다음 식별자를 붙입니다.

shadow_id
source_provider
candidate_provider
task_type
prompt_version
tool_schema_version
result_hash
failure_reason
replay_condition

비교할 항목은 다음과 같습니다.

1. 최종 작업 완료 여부
2. 구조화된 출력의 파싱 성공 여부
3. 여러 차례 대화에서 상태 유지 여부
4. 도구 호출의 누락과 중복 여부
5. 스트리밍 중단과 시간 초과 여부
6. 입력과 출력 토큰의 실제 사용량
7. 민감 정보가 로그에 남는지 여부

실패 샘플은 삭제하지 말고 재현 조건과 함께 보관합니다. 예를 들어 “긴 문서에서 실패”라고만 쓰지 말고, 문서 크기, 도구 수, 사고 수준, 스트리밍 여부, 재시도 횟수를 함께 기록해야 다음 단계의 승인 근거가 됩니다.

단계 전환과 되돌리기

단계 전환은 전체 트래픽 비율보다 업무 위험도로 시작합니다. 내부 테스트, 읽기 전용 조회, 비중요 문서 정리처럼 실패해도 외부 상태를 바꾸지 않는 작업부터 옮깁니다. 결제, 계정 변경, 코드 배포, 외부 메시지 발송은 원래 공급자에 남겨 둡니다.

다음 조건 목록으로 선택합니다.

• 도구 호출, 구조화된 출력, 다중 차례 상태가 모두 기존과 같으면 저위험 업무에 후보 공급자를 적용합니다.
• 일반 문장은 같지만 도구 인자나 종료 이유가 다르면 후보를 그림자 모드에만 둡니다.
• 후보의 출시 상태, 제한 정책, 데이터 처리 조건이 문서로 확인되지 않으면 공식 API를 주 공급자로 유지합니다.
• 후보 장애 시 자동 되돌리기가 검증되고 중복 실행 방지가 있으면 주 공급자와 보조 공급자의 이중 경로를 허용합니다.
• 시간 초과, 빈 응답, 스트리밍 중단이 반복되면 트래픽을 늘리지 않고 기존 경로로 되돌립니다.
• 비용은 낮지만 재시도와 출력 증가가 설명되지 않으면 가격 우위만으로 출시 승인하지 않습니다.

되돌리기는 단순히 주소를 바꾸는 기능이 아닙니다. 현재 요청의 재실행 가능 여부를 판단해야 합니다. 이미 외부 도구가 실행된 뒤 응답만 끊겼다면 자동 재시도는 위험합니다. 요청 식별자와 도구 실행 기록을 확인한 뒤 재개 또는 중단을 선택해야 합니다.

모델 API 주 경로와 보조 경로를 함께 운영할 계획이라면 모델 API 장애 전환 설정을 확인할 수 있는 도움말에서 실행 환경의 비밀값 관리와 접속 조건도 함께 점검하는 편이 안전합니다.

첫 주 운영 비용과 데이터 검토

공개 단가는 비교의 출발점일 뿐입니다. 첫 주에는 입력 토큰, 캐시 입력, 출력 토큰, 실패 재시도, 중단된 긴 작업, 로그 저장, 라우팅 코드 유지 비용을 합산합니다.

Fireworks 공식 모델 페이지는 입력, 캐시 입력, 출력 단가를 공개하고 있습니다. Together AI 역시 모델 페이지에 입력과 출력 단가를 표시하고 있지만, 출시 상태와 실제 계정 조건이 바뀔 수 있으므로 표의 공란을 예측값으로 채우면 안 됩니다.

운영 기록에는 다음을 포함합니다.

• 업무 유형별 평균 입력과 출력 사용량
• 실패 요청의 재시도 횟수
• 도구 호출이 포함된 요청의 전체 비용
• 캐시가 실제로 적용된 요청의 비율
• 장시간 요청의 중단 원인
• 공급자별 로그 보존과 데이터 처리 지역
• 장애 전환 뒤 중복 작업이 발생했는지 여부

민감한 문서나 고객 자료를 그림자 트래픽에 넣을 때는 탈식별화 범위와 삭제 시점을 정합니다. “기업용”, “안전한 인프라” 같은 홍보 문구만으로 승인하지 말고, 약관과 개인정보 처리 문서를 직접 확인해야 합니다. SpinMac의 개인정보 처리 안내도 개발 환경에서 테스트 데이터를 다룰 때 함께 참고할 수 있습니다.

출시 서명표

최종 결정은 세 가지 중 하나로 남겨야 합니다.

출시 후에도 검수는 끝나지 않습니다. 모델 식별자, 공급자 구현, 제한 정책, 가격이 바뀌면 같은 테스트 묶음을 다시 실행해야 합니다. 특히 Kimi K3처럼 긴 사고 과정과 도구 호출을 사용하는 모델은 단순한 문장 회귀 테스트만으로는 조용한 기능 저하를 잡기 어렵습니다.

현재 방식과 클라우드 맥 기반 검수 환경을 비교하면, 개인 장비만으로 긴 그림자 테스트를 반복할 때는 절전, 동시 실행 수, 개발 환경 차이, 지속적 통합 작업 중단이 병목이 되기 쉽습니다. 반면 클라우드 맥은 고정된 개발 환경과 원격 실행 지점을 만들기 쉽고, 테스트 기간에 필요한 만큼만 빌릴 수 있습니다. 다만 장기간 일정한 고부하를 유지하거나 물리 장치가 필요한 팀이라면 직접 장비를 운영하는 편이 더 합리적일 수 있습니다.

공급자 검수를 마친 뒤에도 로컬 환경이 부족해 회귀 테스트를 이어가기 어렵다면, SpinMac의 클라우드 맥 환경과 요금 안내에서 필요한 기간과 개발 환경을 먼저 확인해 보십시오. 운영 트래픽을 옮기기 전에 계약 테스트, 그림자 요청, 되돌리기 시험을 반복할 임시 환경이 필요한 경우에 특히 잘 맞습니다.