HiAPI API로 kimi-k3.1-pro 호출하는 방법: curl, Python과 바로 실행 가능한 요청

왜 집계 API로 kimi-k3.1-pro를 호출해야 하는가

모든 모델 통합에는 같은 숨은 비용이 따릅니다. 첫날은 흥미롭고, 두 번째 달은 유지보수입니다. kimi-k3.1-pro를 애플리케이션에 직접 연결하면 해당 제공자의 인증 방식, 오류 의미론, 할당량 모델, 릴리스 주기를 함께 물려받게 됩니다. 단일 모델 프로토타입에서는 문제가 없습니다. 하지만 두 번째 모델, 두 번째 환경, 또는 특정 엔드포인트에 문제가 생겼을 때 쓸 폴백 경로를 원하는 순간 마찰이 됩니다.

집계 API는 이런 차이를 하나의 계약으로 수렴시킵니다. HiAPI는 kimi-k3.1-pro를 OpenAI 호환 요청 형태로 제공하므로, 여기서 작성하는 클라이언트 코드는 일회용이 아닙니다. 모델 식별자만 바꾸면 동일한 요청 구조를 플랫폼의 다른 모델에도 그대로 쓸 수 있습니다. 같은 헤더, 같은 메시지 배열, 같은 스트리밍 래퍼입니다.

구체적으로 kimi-k3.1-pro에는 세 가지 실질적 의미가 있습니다:

• 단일 자격 증명 표면. 계속 늘어나는 여러 제공자 계정 대신 API Key 하나와 기본 URL 하나만 관리하면 됩니다.
• 예측 가능한 페이로드. 요청과 응답 스키마가 모델 간에 안정적으로 유지되므로 파싱, 재시도, 로깅 계층을 한 번만 작성하면 됩니다.
• 낮은 마이그레이션 비용. 이후 특정 워크로드에 다른 모델이 더 적합하다면 변경은 전송 계층 코드 재작성이 아니라 페이로드 안의 문자열 하나입니다.

이 가이드의 나머지는 통합 그 자체입니다: 요청 해부, 그대로 복사할 수 있는 curl 호출, 동등한 Python 클라이언트, 그리고 운영 환경에서 흔히 가장 문제가 되는 두 기능인 스트리밍과 도구 호출, 마지막으로 오류 문제 해결 체크리스트입니다.

시작하기 전에 준비할 것

• 프로젝트에서 비밀 키를 보관하는 곳에 저장한 HiAPI API Key.
• HiAPI 콘솔에서 확인한 계정의 API 기본 URL. 아래 모든 예제는 https://api.hiapi.ai/v1을 자리표시자 기본 주소로 사용합니다. 배포 전에 콘솔에서 실제 호스트를 확인하세요.
• kimi-k3.1-pro의 모델 식별자 문자열. 콘솔의 모델 목록에서 그대로 복사하세요. 식별자는 대소문자를 구분합니다.
• 첫 테스트용 curl, 그리고 클라이언트 예제용으로 requests 라이브러리가 설치된 Python 3.9+.

요청 형태: 엔드포인트, 헤더와 모델 파라미터

모든 대화 호출은 동일한 해부 구조를 따릅니다. 각 부분을 한 번만 제대로 이해하면 이후 필드별로 디버깅할 필요가 없습니다.

엔드포인트

대화 완성은 기본 URL 아래 단일 경로에 있습니다:

POST {BASE_URL}/chat/completions

이 가이드의 모든 예제에 필요한 유일한 엔드포인트입니다. 스트리밍과 도구 호출은 별도 엔드포인트가 아니라 동일한 요청 본문 위의 옵션입니다.

헤더

실제로 작동하는 헤더는 두 개뿐입니다:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

키는 Authorization 헤더에 Bearer 접두사와 함께 넣습니다. URL, 쿼리 파라미터, 요청 본문에 넣지 마세요. 이 세 가지 방식 모두 키를 로그와 오류 보고서로 유출시킵니다. Content-Type은 명시적으로 설정하세요. 일부 HTTP 클라이언트는 이를 추론하지 않습니다.

실제로 중요한 요청 본문 필드

최소 요청 본문에는 의미 있는 필드가 네 개 있습니다:

• model — kimi-k3.1-pro 식별자. 필수입니다. 정확히 일치해야 하므로 첫 시도에서 가장 틀리기 쉬운 필드입니다.
• messages — 순서가 있는 객체 배열로, 각 객체에는 role(system, user 또는 assistant)과 content가 있습니다. 필수이며 비어 있으면 안 됩니다. 순서가 곧 대화 기록입니다. 모델은 이 배열만 보고 그 외에는 보지 않습니다.
• stream — 불리언이며 기본값은 false입니다. true이면 응답이 단일 JSON 본문이 아니라 서버 전송 이벤트로 도착합니다. 별도 섹션이 있습니다.
• temperature — 선택적 샘플링 제어. 낮은 값은 더 결정적인 출력을, 높은 값은 더 많은 변화를 만듭니다. 사용 사례별로 한 번 값을 정하고 그대로 두세요. 요청마다 조정하지 마세요.

통합이 성숙해지면 추가할 수 있는 선택적 필드:

• max_tokens — 생성 길이 상한. 비용과 지연의 가드레일로 사용할 수 있습니다. 입력이 아니라 출력을 제한합니다.
• tools — 도구 정의 배열. 뒤에서 자세히 설명합니다.
• tool_choice — 모델이 제공한 도구를 호출할지, 어떻게 호출할지 제어합니다.
• stop — 생성을 종료하는 하나 이상의 시퀀스.

예상해야 하는 응답

비스트리밍 응답은 choices 배열에 최소 하나의 항목이 있는 JSON 객체를 반환합니다. 그 항목에는 role과 content가 있는 message 객체, 그리고 생성이 왜 멈췄는지 알려주는 finish_reason이 있습니다. 콘텐츠가 완전하다고 가정하지 말고 항상 finish_reason에 따라 분기하세요. 잘린 응답에도 콘텐츠는 있지만 완전한 답은 아닙니다.

문자열화된 응답이 아니라 그 구조에 맞춰 파서를 작성하세요. 그러면 플랫폼에서 모델을 어떻게 바꾸든 살아남습니다.

실행 가능한 curl 요청

여기서 시작하세요. 유효한 응답이 돌아오면 키, 기본 URL, 모델 식별자가 모두 올바르며 이후 문제는 자격 증명이 아니라 코드에 있습니다.

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "system", "content": "당신은 간결한 기술 도우미입니다."},
      {"role": "user", "content": "멱등 키가 무엇인지 두 문장으로 설명하세요."}
    ],
    "temperature": 0.3,
    "max_tokens": 256
  }'

각 필드 설명

• -sS는 curl의 진행 표시를 조용히 하되 오류는 여전히 노출합니다. 두 번째 S가 없으면 실패한 요청이 조용히 종료되어 디버깅 라운드를 낭비할 수 있습니다.
• 환경 변수는 키가 셸 기록이나 터미널 스크롤백 버퍼에 남지 않게 합니다. 셸 프로필 또는 로드된 .env에서 HIAPI_BASE_URL과 HIAPI_API_KEY를 export하세요.
• 요청 본문을 작은따옴표로 감싸기는 페이로드에 작은따옴표가 없는 한 POSIX 셸에서 올바릅니다. 작은따옴표가 필요해지면 본문을 파일로 옮기고 -d @body.json으로 전달하세요. JSON 형식 오류처럼 보이는 따옴표 버그를 피할 수 있습니다.
• system 메시지는 선택 사항이지만 포함할 가치가 있습니다. 어조와 출력 형식을 고정하는 가장 간편한 장소입니다.
• max_tokens는 이 예제에서 의도적으로 보수적입니다. 스모크 테스트의 지연과 비용을 동시에 제한합니다.

결과 해석

성공한 호출은 HTTP 200과 JSON 본문을 반환합니다. 계속하기 전에 세 가지를 확인하세요:

1. choices가 비어 있지 않은 배열인지.
2. choices[0].message.content에 실제 답이 들어 있는지.
3. choices[0].finish_reason이 길이 제한에 의한 잘림이 아니라 정상 완료 값인지.

응답 본문이 오류 객체라면 문제 해결 섹션으로 넘어가세요. 오류 메시지는 보통 구체적인 문제 필드를 지적합니다.

재현성 팁

그 curl 호출을 저장소의 셸 스크립트로 저장하세요. 실시간 API에 대한 한 줄 명령 스모크 테스트는 "내 통합이 깨졌다"와 "내 계정이나 키가 바뀌었다"를 구분하는 가장 빠른 방법입니다. 뭔가 이상해 보일 때마다 먼저 이것을 실행하세요.

같은 요청을 Python으로 작성하기

Python 버전은 지루해 보여야 합니다. 바로 그것이 목표입니다. 모든 흥미로운 결정(모델 식별자, 기본 URL, 타임아웃)은 각 호출 지점에 흩어지지 않고 구성에 있어야 합니다.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("HIAPI_MODEL", "kimi-k3.1-pro")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def chat(messages, temperature=0.3, max_tokens=512, timeout=60):
    payload = {
        "model": MODEL,
        "messages": messages,
        "temperature": temperature,
        "max_tokens": max_tokens,
    }
    resp = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=HEADERS,
        json=payload,
        timeout=timeout,
    )
    resp.raise_for_status()
    data = resp.json()
    choice = data["choices"][0]
    return choice["message"]["content"], choice.get("finish_reason")


if __name__ == "__main__":
    text, reason = chat([
        {"role": "system", "content": "당신은 간결한 기술 도우미입니다."},
        {"role": "user", "content": "멱등 키가 무엇인지 두 문장으로 설명하세요."},
    ])
    print(reason)
    print(text)

이렇게 구성한 이유

• data= 대신 json= — requests 라이브러리가 딕셔너리를 직렬화하고 콘텐츠 타입을 설정합니다. 수동 직렬화는 이스케이프 오류를 유발하기 쉽습니다.
• 항상 timeout=60 — 타임아웃 미설정은 워커 프로세스가 관리자에 의해 종료될 때까지 멈춰 있는 가장 흔한 원인입니다. 서비스의 모든 네트워크 호출에는 타임아웃을 설정해야 합니다.
• 파싱 전에 raise_for_status() — HTTP 계층 실패를 호출 지점에서 예외로 바꾸어 형식이 잘못된 응답 본문이 하류로 흘러가지 않게 합니다.
• MODEL은 환경에서 가져옴 — 모델을 전환할 때 바뀌는 것은 모델 식별자뿐입니다. 구성에 두면 전환이 코드 변경이 아니라 배포 변수가 됩니다.
• finish_reason 반환 — 호출자는 답이 잘렸는지 알아야 하는 경우가 거의 항상 있습니다.

모델 전반에서 재사용 가능하게 유지하기

chat(messages, ...)의 시그니처는 의도적으로 모델 특정 내용을 노출하지 않습니다. 나중에 더 저렴한 워크로드를 다른 모델로 라우팅하려면 명시적 모델 오버라이드 파라미터를 전달하거나 다른 MODEL로 두 번째 클라이언트 객체를 구성하세요. 전송, 헤더, 재시도 정책, 오류 처리는 모두 그대로 유지됩니다.

재시도에 대한 설명

chat() 내부에서 무작정 재시도하지 마세요. 해당 작업이 안전하게 반복 가능한지 아는 계층에서 재시도하세요. 실패한 완성은 보통 안전하지만 이미 하류에서 상태를 바꾼 요청은 안전하지 않습니다. 일시적 전송 실패와 속도 제한 응답에만 재시도하고, 상한이 있는 지수 백오프만 사용하세요.

클라이언트를 망가뜨리지 않고 스트리밍 응답 처리하기

스트리밍은 채팅 UI가 즉시 느껴지는지 아니면 10초 동안 빈 화면인지의 차이입니다. 응답이 더 이상 하나의 JSON 문서가 아니므로 통합 버그도 가장 많이 발생합니다.

활성화 방법

요청 본문에 "stream": true를 추가하세요. 요청의 다른 부분은 바뀌지 않습니다.

with requests.post(
    f"{BASE_URL}/chat/completions",
    headers=HEADERS,
    json={"model": MODEL, "messages": messages, "stream": True},
    stream=True,
    timeout=120,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        chunk = line[len("data:"):].strip()
        if chunk == "[DONE]":
            break
        # chunk를 JSON으로 파싱하고 choices[0].delta.content를 읽습니다

실제로 도착하는 내용

응답 본문은 일련의 서버 전송 이벤트입니다. 각 이벤트는 작은 JSON 객체를 담은 data: 한 줄입니다. choices[0]에는 message 객체 대신 delta 객체가 있습니다. delta는 보통 content의 한 조각을 포함하지만 아무것도 포함하지 않을 수도 있습니다. 스트림은 센티널 줄 data: [DONE]로 끝납니다.

네 가지 규칙이 거의 모든 오류를 커버합니다:

1. 교체하지 말고 누적하세요. 각 delta는 한 조각입니다. delta.content를 버퍼에 추가하세요. 완전한 답은 모든 조각을 순서대로 이어 붙인 것입니다.
2. 빈 delta는 건너뛰세요. 첫 번째와 마지막 이벤트는 종종 콘텐츠가 없습니다. None이 추가되지 않게 하세요.
3. [DONE]을 데이터가 아니라 종료자로 취급하세요. 거기서 읽기를 멈추세요. 그 뒤 내용은 응답의 일부가 아닙니다.
4. finish_reason을 마지막으로 담은 이벤트에서 읽으세요. 스트리밍 모드에서는 완료 상태가 최상위 필드가 아니라 늦게 오는 delta에 나타납니다.

지적할 가치가 있는 함정

• 클라이언트 호출에서 stream=True를 잊는 것. 전체 스트림을 버퍼링된 한 덩어리로 받게 되어 원래 목적에 어긋나고, 매우 느린 비스트리밍 요청처럼 보입니다.
• 비스트리밍 기준으로 타임아웃을 설정하는 것. 긴 생성의 스트리밍 지속 시간은 짧은 요청보다 깁니다. 스트리밍 경로에 더 관대한 읽기 타임아웃을 주고, 선택한 간격 동안 바이트가 도착하지 않으면 중단하는 유휴 타이머도 고려하세요.
• 줄 단위로 파싱하면서 접두사를 확인하지 않는 것. 모든 줄이 데이터는 아닙니다. 빈 줄은 이벤트를 구분합니다. 무시하세요.
• delta에 content 키가 있다고 가정하는 것. 도구 호출 스트리밍은 delta에 다른 키를 넣습니다. 항상 방어적으로 읽으세요.
• 클라이언트 소비자를 잊는 것. 서버가 스트림을 버퍼에 쓰고 끝날 때만 출력하면 기술적으로는 스트리밍이지만 실제로는 아닙니다. 하류에서 조각이 도착하는 대로 렌더링되게 하세요.

스트리밍하지 말아야 할 때

배치 작업, 백그라운드 요약, 출력이 사람에게 보여지지 않고 프로그램에 의해 소비되는 모든 것은 보통 스트리밍하지 않는 편이 더 단순합니다. 비스트리밍 응답은 한 번만 파싱하면 되고 로깅하기 쉬우며 스키마 검증도 쉽습니다. 지연이 사용자에게 보이는 곳에서 스트리밍을 사용하세요. 기본값으로 스트리밍하지 마세요.

흐름에 도구 호출 추가하기

도구 호출은 모델이 답을 지어내는 대신 코드가 작업을 수행하도록 요청하게 합니다. 프로토콜은 두 라운드 대화입니다. 도구를 선언하고, 모델이 호출 요청으로 응답할 수 있으며, 이를 실행하고 결과를 다시 보냅니다.

도구 선언

요청에 tools 배열을 추가하세요. 각 항목은 함수 설명을 감쌉니다:

{
  "model": "kimi-k3.1-pro",
  "messages": [{"role": "user", "content": "리스본 날씨는 어때요?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "지정한 도시의 현재 날씨를 반환합니다.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "도시 이름"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

함수와 각 파라미터의 description은 장식이 아닙니다. 모델이 언제, 어떻게 도구를 호출할지 판단하는 유일한 안내입니다. 새 동료에게 설명을 쓰듯 작성하세요.

응답 루프

1. 요청을 보냅니다.
2. choices[0].finish_reason이 도구 호출임을 나타내면 choices[0].message.tool_calls를 읽습니다. 각 항목에는 id, 함수 name, arguments가 있습니다. arguments는 객체가 아니라 JSON으로 인코딩된 문자열입니다. 파싱하세요.
3. 코드에서 함수를 실행합니다. 파라미터를 처리하기 전에 검증하세요. 모델이 그럴듯하지만 필드가 빠지거나 타입이 틀린 페이로드를 생성할 수 있습니다.
4. 어시스턴트 메시지(tool_calls 포함)를 messages 배열에 추가합니다.
5. 역할이 tool이고 일치하는 tool_call_id를 가진 새 메시지를 추가하고, 결과를 content로 넣습니다.
6. 요청을 다시 보냅니다. 이제 모델이 도구 출력을 사용해 최종 답을 구성합니다.

4단계는 모두가 건너뛰는 단계이자 실제로 깨지는 단계입니다. 어시스턴트의 도구 호출 라운드 없이 도구 결과만 다시 보내면 대화에 떠 있는 참조가 생겨 모델이 자신이 무엇을 요청했는지에 대한 기록을 갖지 못합니다.

여러 호출 처리

응답에는 같은 라운드에 여러 도구 호출이 포함될 수 있습니다. 하나씩 실행하고 각 호출마다 자체 tool_call_id를 가진 tool 메시지를 반환하세요. 합치지 마세요.

호출 제어

tool_choice는 정책 레버입니다. auto는 모델이 결정하게 하고, 특정 도구를 요구하면 해당 도구 호출을 강제하며, 도구를 비활성화하면 직접 답하라고 지시합니다. 예산을 유지하세요. 도구가 계속 실패하는데 모델이 계속 재시도하면 도구 루프가 오래 실행될 수 있습니다. 자체 루프에서 반복 횟수를 제한하고, 상한에 도달하면 요청이 계속 이어지게 두지 말고 명확한 메시지를 반환하세요.

도구 출력을 신뢰할 수 없는 것으로 취급하기

모델은 도구 결과를 텍스트로 읽습니다. 결과는 작고 구조화되어 있으며 지시문을 포함하지 않게 유지하고, 파라미터는 여러분 쪽에서 검증하세요. 무제한 텍스트를 반환하는 도구는 비용 문제이자 정확성 위험입니다.

흔한 오류 문제 해결

대부분의 통합 실패는 다섯 가지 범주에 속합니다. 프롬프트를 바꾸기 전에 이 체크리스트를 따라가세요.

1. 인증과 권한 부여

• 증상: HTTP 상태가 401/403 범위.
• 확인: 키가 존재하고, 붙여넣을 때 앞뒤 공백이 없으며, 정확히 Bearer 접두사가 붙어 있는지.
• 확인: 기본 URL이 HiAPI 콘솔에 표시된 것과 일치하는지. 오래되었거나 잘못 붙여넣은 호스트는 혼란스러운 인증 오류를 만듭니다.
• 수정: 환경 변수를 다시 export한 뒤 코드를 건드리기 전에 curl 스모크 테스트를 다시 실행하세요.

2. 형식이 잘못된 페이로드

• 증상: 특정 필드를 지목하는 요청 검증 오류, 또는 파싱할 수 없는 응답 본문.
• 확인: 요청 본문이 유효한 JSON인지. 수동으로 구성했다면 빠른 json.tool 검증을 사용하고, 코드로 구성했다면 딕셔너리가 실수로 한 단계 더 중첩되지 않았는지 확인하세요.
• 확인: messages가 비어 있지 않고 각 항목에 role과 content가 있는지.
• 확인: role 값이 지원되는 집합에서 온 것인지. role: "human" 같은 오타는 일부 클라이언트에서 명백한 오류가 아니라 조용한 오류가 됩니다.
• 확인: tools 항목에 type: "function"과 중첩된 function 객체가 있는지. 평면화된 정의가 가장 흔한 도구 호출 오류입니다.

3. 모델 식별자

• 증상: 찾을 수 없음류 오류, 또는 해당 모델을 계정에서 사용할 수 없다는 메시지.
• 확인: 식별자를 콘솔에서 그대로 복사했는지. 대소문자와 구분자가 모두 중요합니다.
• 확인: 키에 대해 모델이 활성화되어 있는지. 식별자가 유효하더라도 계정이 호출할 수 없는 모델은 여전히 실패합니다.

4. 컨텍스트와 길이 제한

• 증상: 요청이 최대 컨텍스트를 초과했다는 오류, 또는 길이 관련 finish_reason으로 응답이 끝나는 경우.
• 확인: 시스템 프롬프트, 메시지 기록, 모든 도구 정의의 합계. 도구 스키마도 예산에 포함되며 쉽게 잊힙니다.
• 수정: 기록을 잘라내거나 이전 라운드를 요약하거나 작업을 나누세요. 출력 잘림의 경우 워크로드가 정말 더 필요하면 max_tokens를 높이고, 그렇지 않으면 상한을 유지하세요.

5. 속도 제한과 타임아웃

• 증상: 부하 상황의 속도 제한 상태, 또는 클라이언트 읽기 타임아웃.
• 확인: 재시도가 백오프 없이 발생하는지. 촘촘한 재시도 루프는 일시적 속도 제한을 지속적 속도 제한으로 바꿉니다.
• 수정: 응답이 안내하는 속도 제한 신호를 따르고, 지터가 있는 상한 지수 백오프를 사용하며, 키별 동시성을 제어하세요. 타임아웃의 경우 먼저 클라이언트 타임아웃 값을 확인하세요. 모델 생성 시간보다 짧은 클라이언트 제한은 정확히 이 증상을 만듭니다.

일반 디버깅 원칙

모든 실패에 네 가지를 기록하세요: HTTP 상태, 응답 본문, 모델 식별자, 그리고 stream 설정 여부. 이 네 가지가 대부분의 사고를 설명합니다. 그리고 curl 스모크 테스트를 최신 상태로 유지하세요. 이것은 통과하는데 애플리케이션이 실패한다면 문제가 자격 증명이 아니라 코드에 있음을 알 수 있습니다.

오류 메시지 읽기

집계 계층은 보통 어떤 필드가 거부를 초래했는지 명확히 알려줍니다. 프롬프트를 고치고 싶은 충동을 참으세요. 메시지를 읽고, 지목된 필드를 수정하고, 한 번 재시도하세요. 같은 오류가 계속되면 더 깊이 파기 전에 스모크 테스트로 요청을 검증하세요.

배포 전: 운영 체크리스트

"내 터미널에서 작동한다"와 "운영 환경에서 작동한다"의 차이는 대부분 아무도 적어 두지 않은 체크리스트입니다. 여기에 가져다 쓸 만한 목록이 있습니다.

구성과 비밀

• API 키는 비밀 관리자에 보관하고, 소스 제어에도 URL이나 로그 줄에도 절대 두지 않습니다. HTTP 클라이언트가 디버그 수준에서 Authorization 헤더를 출력할 수 없는지 확인하세요.
• 기본 URL과 모델 식별자는 코드베이스에 흩어진 상수가 아니라 구성입니다. 기본 URL은 콘솔과 대조해 확인하세요.
• 예정된 주기로 키를 교체하고, 팀원이 떠난 뒤에는 반드시 교체하세요. 클라이언트 코드는 변경 없이 교체된 키를 사용할 수 있어야 합니다.

요청 위생

• 모든 아웃바운드 호출에 명시적 타임아웃이 있으며, 스트리밍 경로에는 더 관대한 타임아웃과 유휴 중단 규칙이 있습니다.
• 모든 호출 경로에 max_tokens가 설정되어 있습니다. 무제한 생성은 무제한 청구입니다.
• 샘플링 설정은 사용 사례로 고정되어 문서화되어 있어 디버깅이 필요할 때 결과를 재현할 수 있습니다.

응답 처리

• 파서가 finish_reason에 따라 분기하고 잘림을 완전한 답이 아니라 별도 결과로 처리합니다.
• 스트리밍 누적이 짧은 응답과 긴 응답 모두, 그리고 조기 종료 응답에 대해 테스트되었습니다.
• 도구 호출 파라미터는 사용 전에 검증되고, 어시스턴트의 도구 호출 라운드는 항상 메시지 배열에 다시 포함됩니다.
• 도구 루프에 반복 상한과 명확한 실패 메시지가 있습니다.

실패 동작

• 재시도는 상한이 있고, 지터가 있는 상한 지수 백오프를 사용하며, 안전하게 반복 가능한 작업에만 적용됩니다.
• 속도 제한 응답을 따르며, 무작정 밀어붙이지 않습니다.
• 실패 시 상태, 응답 본문, 모델 식별자, stream 플래그를 기록합니다. 이 네 필드가 실제로 사고를 해결합니다.
• curl 스모크 테스트가 CI에서 또는 예정된 주기로 실행되어, 자격 증명이나 모델 변경을 고객이 아니라 대시보드에서 알게 됩니다.

비용과 용량

• 사용량이 어떻게 청구되는지 알고 있습니다. 플랫폼은 처리된 토큰으로 청구하므로 긴 프롬프트와 긴 생성 모두 중요합니다. 현재 요금은 콘솔의 가격 패널에서 확인하세요.
• 어떤 워크로드가 가장 큰 소비자인지, 그리고 그것이 전체 모델이 필요한지 더 가벼운 모델로 충분한지 알고 있습니다.
• 폴백 경로가 있습니다. 어떤 호출이 반복적으로 실패하면 애플리케이션이 조용히 멈추는 대신 눈에 띄게 성능이 저하됩니다.

마지막 질문

스스로 물어보세요. 이 통합을 작성하지 않은 사람이 이것을 관찰할 수 있는가. 팀의 개발자가 스모크 테스트, 오류 로그 필드, 구성을 읽고 실패를 진단하는 방법을 이해할 수 있다면 완료된 것입니다. 그렇지 않다면 체크리스트는 아직 끝나지 않은 것입니다.

실행 가능한 curl 호출, 재사용 가능한 Python 클라이언트, 이 체크리스트가 있으면 kimi-k3.1-pro는 단순히 연결된 것이 아니라 진정으로 통합된 것입니다.