MoonshotAI/moonpalace

MoonshotAI/moonpalace

Description: MoonPalace（月宫）是由 Moonshot AI 月之暗面提供的 API 调试工具。

Language: Go

License: GPL-3.0

Stars: 255

Forks: 11

Open issues: 7

Created: 2024-07-30T08:53:36Z

Pushed: 2024-12-30T21:17:27Z

Default branch: main

Fork: no

Archived: no

README:

MoonPalace - Moonshot AI 月之暗面 Kimi API 调试工具

MoonPalace（月宫）是由 Moonshot AI 月之暗面提供的 API 调试工具。它具备以下特点：

• 全平台支持：
• [x] Mac
• [x] Windows
• [x] Linux；
• 简单易用，启动后将 base_url 替换为 http://localhost:9988 即可开始调试；
• 捕获完整请求，包括网络错误时的“事故现场”；
• 通过 request_id、chatcmpl_id 快速检索、查看请求信息；
• 一键导出 BadCase 结构化上报数据，帮助 Kimi 完善模型能力；

我们推荐在代码编写和调试阶段使用 MoonPalace 作为你的 API “供应商”，以便能快速发现和定位关于 API 调用和代码编写过程中的各种问题，对于 Kimi 大模型各种不符合预期的输出，你也可以通过 MoonPalace 导出请求详情并提交给 Moonshot AI 以改进 Kimi 大模型。

安装方式

使用 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 版本的 Mac
• moonpalace-windows.exe

请根据自己的平台下载对应的二进制（可执行）文件，并将二进制（可执行）文件放置在已被包含在环境变量 $PATH 中的目录中，将其更名为 moonpalace，最后为其赋予可执行权限。

使用方式

启动服务

使用以下命令启动 MoonPalace 代理服务器：

$ moonpalace start --port

MoonPalace 会在本地启动一个 HTTP 服务器，--port 参数指定 MoonPalace 监听的本地端口，默认值为 9988。当 MoonPalace 启动成功时，会输出：

[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，如果你使用了自定义的端口，请将 base_url 替换为显示的地址。

额外的，如果你想在调试时始终使用一个调试的 `api_key`，你可以在启动 MoonPalace 时使用 `--key` 参数为 MoonPalace 设定一个默认的 `api_key`，这样你就可以不用在请求时手动设置 `api_key`，MoonPalace 会帮你在请求 Kimi API 时添加你通过 `--key` 设定的 `api_key`。

如果你正确设置了 base_url，并成功调用 Kimi API，MoonPalace 会输出如下的信息：

$ moonpalace start --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 Headers 中的 Msh-Request-Id 字段的值对应下文中检索请求、导出请求中的 --requestid 参数的值，Response 中的 id 对应 --chatcmpl 参数的值，last_insert_id 对应 --id 参数的值。

使用 config.yaml 进行配置

在 $HOME/.moonpalace/ 目录下新建配置文件 config.yaml，即可对 moonpalace start 命令进行配置，免去每次启动时输入复杂命令的烦恼。

配置文件的格式如下：

start:
port: 8080 # 对应 --port 命令行参数
key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 对应 --key 命令行参数
detect-repeat: # 对应 --detect-repeat 命令行选项
threshold: 0.5 # 对应 --repeat-threshold 命令行参数
min-length: 100 # 对应 --repeat-min-length 命令行参数
force-stream: true # 对应 --force-stream 命令行选项
auto-cache:
min-bytes: 4096 # 对应 --cache-min-bytes 命令行选项
ttl: 90 # 对应 --cache-ttl 命令行选项
cleanup: 86400 # 对应 --cache-cleanup 命令行选项

注意：当命令行参数与 `config.yaml` 配置文件参数同时出现时，会优先使用命令行参数。

自动缓存功能

MoonPalace 提供了自动缓存功能，你可以通过 --auto-cache 参数启用自动缓存功能，并搭配 --cache-min-bytes/--cache-ttl/--cache-cleanup 参数调节缓存的各项参数：

$ moonpalace start --port --auto-cache --cache-min-bytes 4096 --cache-ttl 90 --cache-cleanup 86400

--cache-min-bytes 参数指定了当调用 /chat/completions 接口时，请求的内容大小超过 --cache-min-bytes 设定的值时，将会自动启用缓存：

1. 若当前请求内容不匹配任何已经创建的缓存时，创建一个新的缓存，有效时间为 --cache-ttl 设定的值； 2. 若当前请求内容匹配了已经创建的缓存时，使用已创建的缓存，并刷新缓存有效时间，有效时间为 --cache-ttl 设定的值；

--cache-cleanup 参数指定了缓存何时被清除，若已经创建的缓存在 --cache-cleanup 设定的时间（秒）内没有被使用过，将会被 MoonPalace 清除。

内容被截断检测

MoonPalace 可以检测当前 Kimi 大模型输出的内容是否被截断、或内容不完整（这一功能默认被启用）。当 MoonPalace 检测到输出的内容被截断或不完整时，会在日志中输出：

[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 提供了对 Kimi 大模型重复内容输出的检测功能。重复内容输出指的是：Kimi 大模型会重复不断地输出某一特定字词、句子以及空白字符，并且在达到 `max_tokens` 限制前不会停下来。在使用 moonshot-v1-128k 等费用较高的模型时，这种重复输出会导致额外的 Tokens 费用消耗，因此 MoonPalace 提供了 --detect-repeat 选项以启用重复内容输出检测，如下所示：

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

启用 --detect-repeat 选项后，MoonPalace 会在检测到 Kimi 大模型的重复内容输出行为时，中断 Kimi 大模型输出，并在日志中输出：

[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 会中断 Kimi 大模型的输出，非流式输出场合不适用。_

你可以使用 --repeat-threshold/--repeat-min-length 参数来调整 MoonPalace 的阻断行为：

• --repeat-threshold 参数用于设置 MoonPalace 对重复内容的容忍度，越高的 threshold 表示容忍度越低，重复内容将更快被阻断，0 --force-stream

MoonPalace 会将请求参数中的 `stream` 字段设置为 `True`，并在获得响应时，自动根据调用方是否设置了 `stream` 来决定响应的格式：

* 如果调用方已经设置 `stream=True`，则按照流式输出的格式返回，MoonPalace 不对响应做特殊处理；
* 如果调用方没有设置 `stream` 的值，或设置了 `stream=False`，MoonPalace…