Snowiki
로그인회원가입

azosi · 2026.7.28 23:53 · 조회 1

Kimi MoonPalace

상위 문서: ← Kimi Debugging and operations 출처: Kimi API Platform 공식 문서 — MoonPalace - Moonshot AI's Kimi API Debugging Tool 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

MoonPalace(월궁/월궁)는 Moonshot AI가 제공하는 API 디버깅 도구입니다. 주요 기능:

  • 크로스 플랫폼 지원:
    • Mac
    • Windows
    • Linux
  • 사용이 쉬움 — 시작 후 base_url을 http://localhost:9988로 교체하기만 하면 디버깅 시작
  • 완전한 요청 캡처 — 네트워크 오류 발생 시의 "사고 현장"까지 포함
  • 빠른 검색·조회 — request_id와 chatcmpl_id로 요청 정보 빠르게 검색·조회
  • BadCase 구조화 보고 데이터 원클릭 내보내기 — Kimi 모델 성능 향상에 기여

코드 작성·디버깅 단계에서 API "공급자"로 MoonPalace를 사용할 것을 권장합니다. Kimi LLM에서 예기치 못한 출력이 발생하면 MoonPalace로 요청 상세 내역을 내보내 Moonshot AI에 제출해 모델 개선에 기여할 수 있습니다.

1. 설치 방법

go 명령으로 설치

go 툴체인이 설치되어 있다면 다음 명령으로 MoonPalace 설치:

$ go install github.com/MoonshotAI/moonpalace@latest

위 명령은 컴파일된 바이너리를 $GOPATH/bin/에 설치. moonpalace 명령으로 설치 확인:

$ moonpalace
MoonPalace is a command-line tool for debugging the Moonshot AI HTTP API.

Usage:
  moonpalace [command]

Available Commands:
  cleanup     Cleanup Moonshot AI requests.
  completion  Generate the autocompletion script for the specified shell
  export      export a Moonshot AI request.
  help        Help about any command
  inspect     Inspect the specific content of a Moonshot AI request.
  list        Query Moonshot AI requests based on conditions.
  start       Start the MoonPalace proxy server.

Flags:
  -h, --help      help for moonpalace
  -v, --version   version for moonpalace

Use "moonpalace [command] --help" for more information about a command.

moonpalace 바이너리를 찾을 수 없으면 $GOPATH/bin/을 $PATH 환경 변수에 추가.

Releases 페이지에서 다운로드

Releases 페이지에서 플랫폼에 맞는 미리 컴파일된 바이너리 다운로드:

  • moonpalace-linux
  • moonpalace-macos-amd64 (Intel Mac)
  • moonpalace-macos-arm64 (Apple Silicon)
  • moonpalace-windows.exe

$PATH에 포함된 디렉터리에 배치하고 moonpalace로 이름 변경 후 실행 권한 부여.

2. 사용법

서비스 시작

$ moonpalace start --port <PORT>

--port 파라미터는 MoonPalace가 리스닝할 로컬 포트 지정. 기본값 9988. 시작 성공 시 다음 출력:

[MoonPalace] 2024/07/29 17:00:29 MoonPalace Starts -> change base_url to "http://127.0.0.1:9988/v1"

표시된 주소로 base_url 교체. 기본 포트 사용 시 base_url=http://127.0.0.1:9988/v1. 커스텀 포트 사용 시 표시된 주소로 교체.

디버깅 중 항상 같은 api_key를 사용하려면 --key 파라미터로 MoonPalace 기본 api_key 설정. 매 요청마다 api_key를 수동 설정할 필요 없음. MoonPalace가 Kimi API 요청 시 --key로 설정한 api_key를 자동 추가.

base_url을 올바르게 설정하고 Kimi API를 성공적으로 호출하면 MoonPalace가 다음을 출력:

$ moonpalace start --port <PORT>
[MoonPalace] 2024/07/29 17:00:29 MoonPalace Starts -> change base_url to "http://127.0.0.1:9988/v1"
[MoonPalace] 2024/07/29 21:30:53 POST   /v1/chat/completions 200 OK
[MoonPalace] 2024/07/29 21:30:53   - Request Headers: 
[MoonPalace] 2024/07/29 21:30:53     - Content-Type:   application/json
[MoonPalace] 2024/07/29 21:30:53   - Response Headers: 
[MoonPalace] 2024/07/29 21:30:53     - Content-Type:   application/json
[MoonPalace] 2024/07/29 21:30:53     - Msh-Request-Id: c34f3421-4dae-11ef-b237-9620e33511ee
[MoonPalace] 2024/07/29 21:30:53     - Server-Timing:  7134
[MoonPalace] 2024/07/29 21:30:53     - Msh-Uid:        cn0psmmcp7fclnphkcpg
[MoonPalace] 2024/07/29 21:30:53     - Msh-Gid:        enterprise-tier-5
[MoonPalace] 2024/07/29 21:30:53   - Response: 
[MoonPalace] 2024/07/29 21:30:53     - id:                cmpl-12be8428ebe74a9e8466a37bee7a9b11
[MoonPalace] 2024/07/29 21:30:53     - prompt_tokens:     1449
[MoonPalace] 2024/07/29 21:30:53     - completion_tokens: 158
[MoonPalace] 2024/07/29 21:30:53     - total_tokens:      1607
[MoonPalace] 2024/07/29 21:30:53   New Row Inserted: last_insert_id=15

MoonPalace는 명령줄 로그 형태로 요청 상세 출력 (로그 영구 보존이 필요하면 stderr를 파일로 리다이렉트).

로그의 Response Header Msh-Request-Id 값은 검색/내보내기 명령의 --requestid 파라미터에 해당. Response의 id는 --chatcmpl, last_insert_id는 --id에 해당.

[MoonPalace] 2024/08/05 19:06:19   it seems that your max_tokens value is too small, please set a larger value

스트리밍이 아닐 때(stream=False) MoonPalace가 적절한 max_tokens 값을 제안.

반복 콘텐츠 출력 감지 활성화

MoonPalace는 반복 콘텐츠 출력 감지 기능 제공. 모델이 max_tokens 도달 전 특정 단어/문장/공백을 계속 출력하는 경우를 말하며, moonshot-v1-128k 같은 비싼 모델에서 추가 토큰 비용을 유발. MoonPalace는 --detect-repeat 옵션을 제공:

$ moonpalace start --port <PORT> --detect-repeat --repeat-threshold 0.3 --repeat-min-length 20

--detect-repeat 활성화 후 MoonPalace가 반복 콘텐츠를 감지하면 Kimi LLM 출력을 중단하고 다음 메시지 로그:

[MoonPalace] 2024/08/05 18:20:37   it appears that there is an issue with content repeating in the current response

--detect-repeat는 스트리밍 모드(stream=True)에서만 출력을 중단. 비스트리밍 모드에는 적용되지 않음.

MoonPalace의 차단 동작은 --repeat-threshold와 --repeat-min-length 파라미터로 조정:

  • --repeat-threshold: 반복 콘텐츠 허용 한도. 임계값이 높을수록 허용도가 낮아져 반복 콘텐츠가 더 빨리 차단. 범위 0 ≤ threshold ≤ 1
  • --repeat-min-length: 반복 콘텐츠 감지를 시작할 최소 글자 수. 예: --repeat-min-length=100은 출력이 100 UTF-8 글자 초과 시 감지 시작

강제 스트리밍 출력 활성화

--force-stream 옵션으로 모든 /v1/chat/completions 요청을 스트리밍 출력 모드로 강제:

$ moonpalace start --port <PORT> --force-stream

MoonPalace가 요청 파라미터의 stream 필드를 True로 설정. 응답 수신 시 호출자가 stream을 설정했는지 여부로 응답 포맷 자동 결정:

  • 호출자가 stream=True 설정 → 스트리밍 포맷 그대로 반환 (MoonPalace 추가 처리 없음)
  • 호출자가 stream 미설정 또는 stream=False → MoonPalace가 모든 스트리밍 데이터 청크를 완전한 completion 구조로 연결해 반환

호출자(개발자)에게 --force-stream 활성화는 Kimi API 응답 내용에 영향을 주지 않습니다. 원래 코드 로직으로 디버깅·실행 가능. 즉, 활성화해도 어떤 것도 변경·파괴하지 않습니다. 안전하게 활성화하세요.

왜 필요한가?

비스트리밍 요청 시나리오(stream=False)에서 중간 게이트웨이/프록시 서버가 read_header_timeout이나 read_timeout을 설정해, Kimi API 서버가 응답을組み立て하는 동안 (응답·헤더가 아직 안 온 상태) 게이트웨이가 연결을 끊어 Connection Error/Timeout을 일으키는 것으로 가설.

--force-stream로 비스트리밍 요청을 스트리밍으로 변환. 모든 데이터 청크 수신 후 완전한 completion 응답 구조로組み立て해 반환. MoonPalace가 이미 Kimi API 서버와 연결·스트리밍 수신을 시작해 응답을 받았기 때문에 Connection Error/Timeout을 다소 줄일 수 있습니다.

요청 조회

MoonPalace 시작 후 MoonPalace를 거치는 모든 요청은 $HOME/.moonpalace/moonpalace.sqlite에 기록. 직접 DB에 연결해 조회하거나, CLI 사용:

$ moonpalace list
+----+--------+-------------------------------------------+--------------------------------------+---------------+---------------------+
| id | status | chatcmpl                                  | request_id                           | server_timing | requested_at        |
+----+--------+-------------------------------------------+--------------------------------------+---------------+---------------------+
| 15 | 200    | cmpl-12be8428ebe74a9e8466a37bee7a9b11     | c34f3421-4dae-11ef-b237-9620e33511ee | 7134          | 2024-07-29 21:30:53 |
...

list는 가장 최근 요청을 표시. id/chatcmpl/request_id 검색 + status/server_timing/requested_at 등. 특정 요청을 보려면 inspect 사용:

# 다음 세 명령은 같은 요청 정보를 조회
$ moonpalace inspect --id 13
$ moonpalace inspect --chatcmpl chatcmpl-2e1aa823e2c94ebdad66450a0e6df088
$ moonpalace inspect --requestid c07c118e-4dae-11ef-b423-62db244b9277

기본적으로 body는 미출력. body 포함 출력:

$ moonpalace inspect --chatcmpl chatcmpl-2e1aa823e2c94ebdad66450a0e6df088 --print request_body,response_body

요청 내보내기

예상치 못한 결과가 있거나 Moonshot AI에 보고하려면 export 명령으로 특정 요청 내보내기:

$ moonpalace export \
    --id 13 \
    --chatcmpl chatcmpl-2e1aa823e2c94ebdad66450a0e6df088 \
    --requestid c07c118e-4dae-11ef-b423-62db244b9277 \
    --good/--bad \
    --tag "code" --tag "python" \
    --directory $HOME/Downloads/

id/chatcmpl/requestid 중 하나만 선택해 특정 요청 조회. --good/--bad는 Good Case/Bad Case 표시. --tag는 관련 태그 추가. --directory는 저장 경로.

개발자는 Github Issues로 Good/Bad Case 제출을 권장. 요청 정보를 공개하고 싶지 않으면 기업 위챗/이메일 등 다른 경로로 제출.

메일: api-feedback@moonshot.cn

변경 이력

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

댓글

아직 댓글이 없습니다.

댓글을 작성하려면 로그인이 필요합니다.