사용 가이드
Kimi K3 응답 처리 실전: 완전한 JSON, 스트리밍 중단과 재시도 경계
이 페이지에서
먼저 두 가지 응답 경로를 구분하자
같은 Kimi K3 API라도 받게 되는 것은 완전히 다른 두 가지일 수 있습니다. 하나의 완전한 JSON 응답이거나, 순서대로 도착하는 스트리밍 데이터 청크의 연속입니다. 전자는 '질문 하나에 답 하나'를 전달하는 문서 배송이고, 후자는 '생성하면서 동시에 푸시'하는 증분 시퀀스입니다. 많은 응답 처리 버그의 원인은 파싱을 잘못 작성한 것이 아니라, 처음부터 자신이 어느 경로에 서 있는지 파악하지 못한 것입니다.
두 경로는 동일한 요청 프로토콜(openai_chat_completions, 계약 버전 2)을 공유하며, 차이는 소비 방식에 집중됩니다:
- 비스트리밍: 요청이 반환되면 완전한 응답 본문을 받게 되며, 본문, 추론 내용, 사용량이 모두 그 안에 있으므로 한 번에 읽으면 됩니다.
- 스트리밍: 선택 모드로 활성화되며, 서버가 chunk를 계속 푸시하고 최종적으로 SSE의
[DONE]마커로 스트림을 종료합니다. 중간에 수십에서 수백 개의 청크를 받을 수도 있고, 도중에 끊길 수도 있습니다.[DONE]은 스트림이 끝났다는 것만 의미하며, 내용이 완전하다는 뜻은 아닙니다.
이것을 먼저 확인해야 뒤의 모든 논의가 의미를 갖습니다. 비즈니스 경로에 두 가지 호출이 동시에 존재한다면(예: 백그라운드 배치 처리와 프런트엔드 대화가 하나의 래퍼를 공유), '콜백이 있는지' 같은 암묵적 판단으로 구분하지 말고 클라이언트에서 경로를 명시적으로 표시하는 것이 좋습니다. 그렇지 않으면 리팩터링 시 역직렬화 실패의 지뢰가 매설됩니다.
간단한 판단 규칙: 사용자에게 글자 단위로 보여줘야 하거나 출력이 길어질 수 있다면 스트리밍을 사용하고, 구조화된 결과를 한 번에 받아 이후 DB 저장이나 2차 가공을 해야 한다면 비스트리밍을 사용합니다. 두 경로의 파싱 코드는 분리해서 작성하고, 공유하는 것은 요청 구성과 오류 매핑 부분뿐이어야 합니다.

완전한 JSON 파싱: 본문, 추론 내용, 구조화 필드
비스트리밍 응답은 OpenAI Chat Completions의 응답 본문 형식을 따르지만, 쉽게 간과되는 점이 하나 있습니다. 본문과 추론 내용은 서로 다른 필드라는 것입니다.
본문은 표준 메시지 내용 위치에 있고, Kimi K3의 추론 과정은 reasoning_content 필드로 전달됩니다. 즉, 파싱 계층은 최소한 세 가지를 해야 합니다:
- 메시지 내용에서 사용자 대상 최종 답변을 가져옵니다;
reasoning_content가 존재하는지 판단하고, 존재할 경우 로그로 남길지, 사용자에게 보여줄지, 아니면 그냥 버릴지 결정합니다;usage를 별도로 저장하여 과금 및 쿼터 정산에 사용합니다.
reasoning_content를 본문으로 표시하는 것은 흔한 사고입니다. 이것은 디버깅과 설명 가능성 시나리오를 대상으로 하므로, 제품 문구나 고객 응대 답변에 그대로 들어가면 어조와 내용 모두 적절하지 않습니다. 올바른 방법은 디버그 로그나 '추론 과정 보기' 같은 선택적 진입점 등 독립된 소비 경로를 부여하는 것입니다.
구조화 출력 활용 방법
이 계약은 response_format 파라미터와 jsonObject 구조화 출력 기능을 지원합니다. 모델에 JSON 객체 반환을 요구하여 취약한 정규식 추출 계층을 없앨 수 있습니다. 하지만 두 가지 전제를 분명히 해야 합니다. jsonObject 기능이 JSON Schema 모드를 지원한다는 뜻은 아니며, 구조화 출력도 '반드시 성공'을 보장하지 않습니다.
응답이 정상적으로 완료되고 내용이 완전한 경우에만 JSON 파싱을 시도하세요. 파싱 후에도 세 가지 실패를 처리해야 합니다:
- 파싱 실패: 반환 내용이 유효한 JSON이 아니거나, 필드가 누락되었거나, 타입이 맞지 않습니다. 이때 원본 문자열을 상위 비즈니스에 그대로 던지지 말고 폴백 분기로 진입해야 합니다.
- Schema 검증 실패: JSON 문법은 유효하지만 선언한 구조와 맞지 않습니다.
jsonObject는 JSON Schema 수준의 제약을 보장하지 않으므로, 비즈니스 측에서 필드, 타입, 필수 항목을 직접 검증해야 합니다. - 잘림: 출력 길이가 해당 모델의 출력 token 상한(131072)에 도달하면
finish_reason이length일 수 있고, JSON이 중간에 끝날 수 있습니다.length를 JSON 완전 성공으로 간주해서는 안 됩니다. 불완전한 JSON 파서는 오류를 내지만, 더 위험한 경우는 '간신히 파싱 성공'하여 절반의 객체를 들고 비즈니스 로직을 계속 실행하는 것입니다.
JSON 문법 유효성만 의존하지 말고, 파싱 후 비즈니스 필드 완전성과 근거 검증 단계를 추가하는 것이 좋습니다. 컨텍스트 윈도우는 1000000이므로 긴 문서 시나리오에서 입력은 병목이 아니지만, 출력 잘림은 여전히 실재하는 경계입니다.

스트리밍 읽기: [DONE], finish_reason, 사용량
스트리밍 모드에서 서버는 chunk를 순서대로 푸시하며, SSE의 네트워크 종료 마커는 [DONE]입니다. 이 문장은 평범하게 들리지만 자주 오해됩니다. [DONE]은 이 스트림이 끝났다는 것만 의미하며, 생성 성공이나 내용 완전성을 의미하지 않습니다.
종료 상태를 판단하려면 각 chunk의 choices[].finish_reason을 봐야 합니다. 현재 프런트엔드는 finish_reason이 비어 있지 않은지로 종료 상태를 식별합니다. [DONE]을 받았더라도 finish_reason이 없으면 여전히 중단으로 간주해야 합니다. 스트림 내 error 프레임은 이번 요청이 실패했음을 나타냅니다.
스트림은 여러 상태로 끝날 수 있습니다:
- 정상 완료:
finish_reason이 성공 종료 상태이고 이후[DONE]을 받으면, 누적 내용을 완전한 결과로 볼 수 있습니다; - 길이 잘림:
finish_reason=length, 출력이 길이 상한으로 잘려 내용이 불완전할 수 있으므로 JSON 완전 성공으로 볼 수 없습니다; - 기타 비성공 사유: 콘텐츠 필터링 등은 별도로 처리해야 하며 정상 완료로 간주할 수 없습니다;
- 중도 단절: 연결 종료, 타임아웃, 또는 스트림 내
error프레임 수신. 이때는 일부 내용만 있으므로 실패 또는 미완료로 표시해야 합니다.
마지막 경우는 '받은 만큼만 쓰는' 형태로 작성되기 쉽습니다. 채팅 표시에는 허용될 수 있지만(사용자가 반쯤 온 문장을 보고 다시 보낼 수 있음), DB 저장, 과금, 다운스트림 작업 트리거에는 잘못된 데이터입니다. 완전성 판단 기준은 [DONE]만 보지 말고 '성공 종료 상태 finish_reason을 받았는가'로 삼으세요.
사용량은 스트림 종료 후 집계
스트리밍 모드에서 usage는 finish_reason 이후의 choices:[] 프레임에 나타날 수 있습니다. 클라이언트는 스트림 전체를 읽은 뒤 사용량을 집계해야 하며, [DONE] 자체가 usage를 담는다고 보장할 수 없습니다.
이로 인해 두 가지 직접적인 코딩 제약이 생깁니다:
- 첫 chunk에서 과금이나 쿼터 정산을 하지 마세요. 그 시점에는 최종 출력이 얼마나 길지도 모르고 사용량 필드도 얻을 수 없습니다.
- 중간 chunk에서 사용량을 누적하지 말고,
[DONE]을 사용량 운반체로 취급하지 마세요. 중간 chunk에는 신뢰할 수 있는 사용량 데이터가 없으며, 어떤 '추정'도 최종값과 차이가 납니다.
올바른 순서는 스트리밍 중에는 텍스트와 상태 누적만 담당하고, 스트림을 다 읽은 뒤 choices:[] 프레임에서 사용량을 집계하여 한 번 정산을 완료하는 것입니다. 스트림이 중도에 끊겼고 이미 사용자에게 내용을 보여줬다면 이번 호출의 사용량 상태는 알 수 없습니다. 기본값 0이나 추정값으로 기록하지 말고 '미완료' 상태 플래그가 필요합니다.
또한 내부 메타데이터와 네트워크 필드를 구분해야 합니다. response.stream.terminal=done, response.usage.delivery=final_chunk 같은 것은 플랫폼 내부 메타데이터 태그이며, SSE 네트워크 필드도 아니고 클라이언트가 매칭해야 할 종료 문자열도 아닙니다. 클라이언트는 [DONE], finish_reason, error 프레임, usage 필드 자체에만 의존해야 합니다.
또 다른 실무 디테일: 텍스트를 누적할 때 문자열을 반복 연결하지 말고 리스트에 추가한 뒤 join하세요. 긴 출력에서는 성능 차이가 뚜렷합니다.

POST 재시도가 무료 멱등이 아닌 이유
많은 재시도 로직은 이렇게 작성됩니다: 요청이 타임아웃 예외를 던지면 잡아서 잠시 기다린 뒤 다시 보냅니다. 이 글은 대화 완성 같은 POST 생성 작업의 의미만 다룹니다. 이런 재시도는 중복 과금과 중복 부작용을 일으킬 수 있으며, 무료 멱등으로 취급해서는 안 됩니다.
이유는 단순합니다. 타임아웃은 클라이언트의 판단이지 서버의 약속이 아닙니다. 이쪽 타이머가 울릴 때 요청은 이미 서버에 완전히 도착했을 수 있고, 추론이 시작되었거나, 심지어 완료되어 과금까지 되었을 수 있으며, 다만 응답이 돌아오는 길에 유실된 것일 수 있습니다. 클라이언트는 예외 유형만으로 두 상황을 구분할 수 없습니다:
- 요청이 서버에 도착하지 않았다면 재시도는 두 번째 실행을 만들지 않습니다;
- 요청이 이미 접수되어 효과를 냈다면 재시도는 두 번째 호출입니다.
대화 완성의 '효과'에는 보통 token 소비와 과금, 그리고 응답을 기반으로 비즈니스 측에서 트리거하는 동작(DB 쓰기, 폼 제출, 메시지 발송)이 포함됩니다. 결과가 불확실한 POST를 재생하는 것은 이런 부작용을 두 번 수행하는 것과 같습니다. 이것은 이론적 위험이 아닙니다. 네트워크 지터, 게이트웨이 타임아웃, 중간 장비에 의한 연결 리셋은 모두 이런 모호한 상태를 꾸준히 만들어냅니다.
더 골치 아픈 것은 완전한 5xx 응답, 타임아웃, 연결 끊김, JSON 파싱 실패 모두 요청이 생성되지 않았거나 과금되지 않았거나 부작용이 없었다는 것을 증명하지 못한다는 점입니다. 보이는 오류는 이번에 클라이언트가 사용 가능한 결과를 얻지 못했다는 것만 말해줍니다.
따라서 재시도의 올바른 전제는 '오류가 났다'가 아니라 '이번 요청이 확실히 실행되지 않았다'입니다. 재시도 코드를 작성하기 전에 이 질문에 먼저 답하세요. 답할 수 없다면 자동 재생하지 마세요.
재시도 경계 설정: 어떤 경우에 재생할 수 있는가
재시도를 하나의 통합된 for retry in range(3)으로 작성하기보다 등급 표로 만드는 것이 더 신뢰할 만합니다. 다음은 오류 유형별 처리 전략입니다.
명확히 미실행, 재시도 가능
- 연결 수립 실패(DNS 실패, 연결 거부): 요청이 서버에 도달하지 않은 것이 분명하므로 명확히 미전송이며, 재시도는 두 번째 실행을 만들지 않습니다.
- 속도 제한 응답(예: 429): API 문서나 응답 의미가 실행 전 거부를 명확히 보장할 때만 그 의미에 따라 백오프 재시도합니다. 429나 기타 상태 코드만으로 미실행 또는 미과금을 추론해서는 안 됩니다. 백오프에는 무작위 지터를 넣어 여러 클라이언트가 동시에 재시도하지 않도록 하세요.
- API가 명확히 제공하고 서버가 실제 사용하는 중복 제거 메커니즘: API 문서에 명확히 설명되어 있고 서버가 실제로 이를 근거로 중복 제거할 때만 그 의미에 따라 재시도할 수 있습니다. 클라이언트가 직접 생성한 요청 식별자는 추적 용도일 뿐이며, 어떤 요청 헤더나 필드가 멱등 효과를 가진다고 가정해서는 안 됩니다.
결과 불명, 명시적 처리 필요
- 타임아웃: 가장 위험한 범주입니다. 타임아웃은 요청이 실행되지 않았음을 증명하지 못하므로, 다시 보내면 새로운 유료 생성이 발생할 수 있습니다. 클라이언트가 직접 생성한 요청 식별자는 추적에만 사용할 수 있으며, 서버가 중복 제거 메커니즘을 명확히 지원하고 실제 사용할 때만 중복 추론과 중복 과금을 방지할 수 있습니다. 비즈니스 측 중복 제거는 최대한 중복 다운스트림 작업을 막을 뿐, 모델이 다시 생성하고 과금하는 것을 막지는 못합니다. 서버의 중복 제거 의미를 확인할 수 없다면 자동 재생하지 말고 사용자에게 오류를 보고하거나 수동/비동기 보상 프로세스로 전환하세요.
- 완전한 5xx 응답: 응답 본문이 완전히 읽히더라도 미생성, 미과금, 부작용 없음을 증명하지 못합니다. 명확히 미실행이거나 API 문서가 서버가 중복 제거 식별자로 실제 중복 제거를 수행한다고 명확히 설명한 경우에만 재시도하고, 그렇지 않으면 결과 불명으로 처리하세요.
- 응답 파싱 실패: JSON 파싱 실패와 Schema 검증 실패를 포함합니다. 요청이 이미 성공하고 과금되었을 수 있으며, 파싱 실패는 미생성을 증명하지 못합니다. 재시도는 중복 과금과 중복 부작용을 일으킬 수 있으므로, 명시적으로 알 수 없는 결과로 표시하고 기록하여 사후 사용량 대조에 활용하는 것이 좋습니다.
- 스트리밍 중 연결 끊김 또는 스트림 내
error프레임 수신: 이전에 푸시된 내용은 새 결과와 이어 붙일 수 없으며, 재생은 완전히 새로운 생성으로 간주됩니다.
자동 재시도 금지
- 요청 파라미터 오류(4xx 중 파라미터류 오류): 몇 번 재시도해도 결과가 같으며 오류만 증폭됩니다.
- 콘텐츠 검토류 거부: 재생해도 결론이 바뀌지 않습니다.
- '적용되었는지'를 확정할 수 없고 서버 중복 제거 의미도 없는 모든 경우.
경계를 코드에 반영하기
두 가지 엔지니어링 제약을 고정할 가치가 있습니다. 재시도 횟수에 상한을 두고(보통 1~2회면 충분), 명확히 미전송이거나 API 문서가 실행 전 거부를 명확히 보장하는 경우에만 적용하세요. 매 재시도마다 요청 식별자, 오류 유형, 소요 시간을 기록해야 합니다. '몇 번 재시도했는가'가 사용량 청구서와 장애 대응 경로를 직접 좌우하기 때문입니다. 스트리밍 요청의 재시도에는 추가로 주의할 점이 있습니다. 연결이 중도에 끊긴 뒤 재생하면 완전히 새로운 유료 생성이 발생하며, 이전에 푸시된 내용은 새 결과와 이어 붙일 수 없습니다.
아직 모델 선정 단계라면 먼저 Kimi K3 모델 페이지에서 계약 세부 사항을 확인한 뒤 재시도 전략의 세분화 수준을 결정하세요.
실무 체크리스트
앞선 규칙을 리뷰 시 하나씩 대조할 수 있는 체크리스트로 정리합니다:
- 클라이언트가 암묵적 판단이 아니라 스트리밍과 비스트리밍 두 소비 경로를 명시적으로 구분하는가?
- 비스트리밍 파싱이 본문과
reasoning_content를 분리 처리하며,reasoning_content가 사용자에게 보이는 문구로 직접 들어가지 않는가? usage가 별도로 저장되고 비즈니스 기록과 연결 가능한가?- 구조화 출력을 응답이 정상 완료되고 내용이 완전한 뒤에만 파싱하며, 파싱 실패, Schema 검증 실패, 비즈니스 및 근거 검증 실패,
finish_reason=length에 대해 독립적인 폴백이 있는가? - 스트리밍 읽기가
[DONE]만 기다리지 않고finish_reason비어 있지 않음으로 종료 상태를 식별하는가? [DONE]을 스트림 종료 마커로만 취급하고,finish_reason이 없으면 중단으로 표시하는가?- 사용량을 스트림을 다 읽은 뒤
choices:[]프레임에서 집계하며,[DONE]이 usage를 담는다고 가정하지 않는가? - 스트림 내
error프레임을 정상 종료가 아니라 실패로 식별하는가? - 재시도를 오류 유형별로 등급화하고, 명확히 미전송이거나 API 문서가 실행 전 거부를 명확히 보장하는 경우에만 적용하는가?
- 타임아웃, 연결 끊김, 완전한 5xx, JSON 파싱 실패를 '결과 불명'으로 명시적으로 처리하며, 재시도 안전성을 약속하지 않는가?
- 재시도 횟수에 상한이 있고, 매 재시도에 사용량 대조에 쓸 수 있는 로그가 있는가?
- 스트리밍 중단 후 재생을 이어쓰기가 아닌 새로운 생성으로 간주하는가?
이 체크리스트를 한 번에 모두 충족할 필요는 없지만, 각 항목은 실제로 발생하는 온라인 문제에 대응합니다. 먼저 finish_reason 종료 상태 판단 기준과 재시도 경계 두 가지를 처리하면 효과가 가장 직접적입니다.
관련 글
모든 아티클 보기 →-
사용 가이드
Nano Banana 기본 버전 텍스트-이미지 가이드: 화면 비율, 여백, 프롬프트 활용법
작업 인터페이스의 aspect_ratio와 prompt 필드로 배너와 소셜 카드에 구도가 명확한 이미지를 생성합니다
-
사용 가이드
GLM 5.3 구조화 추출 실전: 모든 JSON 필드에 원문 근거를 부여하기
JSON 객체 모드로 필드 추출하기 — 결측값, 인용, 비즈니스 검증으로 오류를 저장 전에 차단
-
사용 가이드
MiniMax Music 3 단편 곡 제작 가이드: 가사, 섹션 태그, 편곡 브리프를 어떻게 분리해 작성할까
현재 계약의 두 필수 입력을 기준으로 재현 가능한 단편 곡 요청을 설계하다