本文旨在让大家更轻松、更灵活地使用 RWKV Runner 的 API 。

此章节会列出 RWKV Runner 每个 API 的作用、请求主体的参考结构、有哪些必需和可选字段。

那么，让我们先从一些 RWKV 模型的基础知识开始吧！

RWKV 模型解码参数（预备知识）

你可能注意到了，很多 RWKV 部署/体验工具都支持调整 Temperature、Top_P 等 RWKV 模型解码参数。

这些主要解码参数对应的效果如下：

续写小说和对话这一类需要创造性的任务，需要高 Temperature + 低 Top_P 的参数组合，可以尝试以下四种参数搭配：

• Temperature 1.2 ，Top_P 0.5
• Temperature 1.4 ，Top_P 0.4
• Temperature 1.4 ，Top_P 0.3
• Temperature 2 ，Top_P 0.2

举个例子，续写小说可以尝试将 Temperature 设为 2 （ Temperature 增加会提高文采，但逻辑会下降），然后将 Top_P 设为 0.1 ~ 0.2 （Top_P 越低，逻辑能力越强），这样生成的小说内容逻辑和文采都很好。

完成相对机械的任务，例如材料问答、文章摘要等，则可将参数设为：

• Temperature 1 ，Top_P 0.2
• Temperature 1 ，Top_P 0.1
• Temperature 1 ，Top_P 0

举个例子，如果你正在执行像关键词提取之类的机械任务，不需要模型进行任何开放性思考，则可以将 Temperature 设为 1 ，Top_P、Presence penalty、Frequency Penalty 都设为 0 。

现在，你应该对 RWKV 模型最主要的四个解码参数有所了解了，现在我们开始了解 RWKV Runner 的所有 API 具体用法！

Completions (续写) API

RWKV Runner 的续写 API 分为聊天续写和基础续写两种，其中聊天续写 API 拥有“role - 角色”参数，因此支持角色扮演等进阶任务。

/chat/completions

v1/chat/completions 和 /chat/completions 是相同的 API，用于 RWKV 的聊天续写模式，也就是和模型对话。

API 地址：（post）http://127.0.0.1:8000/chat/completions

必需参数

• "messages": 消息对象列表，包含两个元素：
  • "content": 提供给模型的 prompt ，即对话内容
  • "role": 扮演的角色名称，可以从"user", "assistant" 和 "system"选一个。

因此，聊天 API 的基础请求主体如下：

{
    "messages": [
    {
      "content": "hello",
      "role": "user"
    }
    ]
}

可选参数

下面列出了聊天续写 API 的所有可选参数：

/completions

/completions和 v1/completions是相同的续写 API，对应的是 RWKV Runner 的基础续写模式，也就是让模型接着你的 prompt 继续生成内容。

API 地址：（post）http://127.0.0.1:8000/completions

必需参数

• "prompt": 你提供给模型的续写 prompt 。

因此，聊天 API 的基础请求主体如下：

{
 "prompt": "那一天，人们又想起来被暴雨支配的恐惧..."
}

可选参数

下面列出了续写 API 的所有可选参数：

参考的停止词：

["\n\nUser", "\n\nQuestion", "\n\nQ", "\n\nHuman", "\n\nBob", "\n\nAssistant", "\n\nAnswer", "\n\nA", "\n\nBot", "\n\nAlice"]

Embeddings API

RWKV Runner 的 Embeddings API 还停留在 RWKV-4，未针对 RWKV5/6 架构更新，因此不建议使用。

Configs（配置类） API

/switch-model

这个 API 用于切换并重新部署 RWKV 模型。

API 地址：（post）http://127.0.0.1:8000/switch-model

必需字段

• "model":用于切换 RWKV 模型，填 RWKV 模型文件的路径，如 model/xxx.pth
• "strategy"：模型部署的方法，如"cuda fp16" 。不同的 strategy 需要的性能也不一样，参考下表：

可选字段

• "customCuda"：是否启用自定义 cuda 算子，不建议修改
• "deploy"：是否启用服务器部署模式，启用服务器部署模式会屏蔽掉/switch-model、 /exit和其他有风险的 API
• "tokenizer"：指定使用的 RWKV 分词器路径，不建议修改

参考的请求主体：

{
"customCuda":false,"
deploy":false,
"model":"models/RWKV-4-World-3B-v1-20230619-ctx4096.pth",
"strategy":"cuda fp16",
"tokenizer":""
}

/update-config

这个 API 用于更新 RWKV Runner 的模型配置，包括解码参数、是否挂载 state 文件等。

API 地址：（post）http://127.0.0.1:8000/update-config

可选字段

参考的请求主体：

{
  "frequency_penalty": 1,
  "global_penalty": false,
  "max_tokens": 1000,
  "penalty_decay": 0.996,
  "presence_penalty": 0,
  "state": "models/",
  "temperature": 1,
  "top_p": 0.3
}

/status

这个 API 用于获取 RWKV Runner 运行的设备状态，比如 GPU 型号等。

API 地址：（get）http://127.0.0.1:8000/status

参考的响应结构：

{
    "status": 3, # 模型工作的状态码
    "pid": 34776, # 模型的进程ID（Process ID）
    "device_name": "NVIDIA GeForce RTX 3080 Laptop GPU" #模型工作的 GPU 型号
}

MIDI 相关 API

RWKV Runner 的 MIDI API 用于处理 midi 乐谱文件（.mid），比如文本转 MIDI 、MIDI 转 WAV 音频文件等。

/text-to-midi

这个 API 用于将 MIDI 格式的文本（text）转换为 MIDI 乐谱文件(.mid)。

API 地址：（post）http://127.0.0.1:8000/text-to-midi

必需字段

• "text": 提供给模型的 MIDI 乐谱文本，即 MIDI 乐谱内容。

参考的请求主体：

{
  "text": "p:24:a p:2a:a p:31:a p:39:a p:3b:a p:45:a b:26:a g:3e:a g:3e:a g:42:a g:42:a g:45:a g:45:a pi:3e:a pi:42:a pi:45:a t14 p:24:0 p:2a:0 p:31:0 p:39:0 p:3b:0 p:45:0 t2 p:2a:a p:3b:a p:45:a t14 p:2a:0 p:3b:0 p:45:0 b:26:0 g:3e:0"
}

/midi-to-text

这个 API 用于将 MIDI 乐谱文件(.mid) 转换为 MIDI 格式的文本（text）。

API 地址：（post）http://127.0.0.1:8000/midi-to-text

必需字段

• file_data：提供给模型的 MIDI 乐谱文件，也可以是 string($binary) - 字符串格式的二进制数据。

参考的响应结构：

{
"text": "<start> p:24:a p:2a:a <end>"
}

/txt-to-midi

这个 API 用于将 MIDI 内容的文本文件（.txt）转换为 MIDI 乐谱文件(.mid)。

API 地址：（post）http://127.0.0.1:8000/txt-to-midi

必需字段

• "midi/sample.mid": 转化完毕的 MIDI 文件保存路径
• "midi/sample.txt"：需要转化的 TXT 文件路径

参考的请求主体

{
  "midi_path": "midi/sample.mid",
  "txt_path": "midi/sample.txt"
}

/midi-to-wav

这个 API 用于将 MIDI 乐谱文件(.mid) 转换为 WAV 音频文件(.wav)。

API 地址：（post）http://127.0.0.1:8000/midi-to-wav

必需字段

• "midi_path": 需要转换的 MIDI 文件路径
• "wav_path": WAV 文件保存路径

可选字段

• "sound_font_path"：影响 MIDI 音色和合成参数的 SoundFont 文件路径

参考的请求主体

{
  "midi_path": "midi/sample.mid",
  "sound_font_path": "assets/default_sound_font.sf2",
  "wav_path": "midi/sample.wav"
}

/text-to-wav

这个 API 用于将 MIDI 乐谱文本（text）转换为 WAV 音频文件(.wav)。

API 地址：（post）http://127.0.0.1:8000/text-to-wav

必需字段

• "text": 提供给模型的 MIDI 乐谱文本，即 MIDI 乐谱内容。
• "wav_name": 转化后返回的 WAV 文件名称

可选字段

• "sound_font_path"：影响 MIDI 音色和合成参数的 SoundFont 文件路径

参考的请求主体

{
    "sound_font_path":"assets/default_sound_font.sf2",
    "text":"p:24:a p:2a:a p:31:a",
    "wav_name":"sample"
}

文件处理 API

文件处理 API 目前只有 /file-to-text，用于解析上传的 PDF/txt 文件。

API 地址：（post）http://127.0.0.1:8000/file-to-text?file_name=233.PDF&file_encoding=utf-8

API 查询参数

• file_name（必需参数）：指定需要解析的文件名称，如 ?file_name=233.PDF 。这里必须正确填写你上传的文件类型后缀（.txt 或者 .pdf），因为 PDF 文件需要特殊处理。
• file_encoding：指定需要解析的文件编码，如 &file_encoding=utf-8

必需字段

• file_data：类型 *string($binary)，即上传一个 txt / PDF 文件或二进制数据

MISC API

这部分 API 主要用于兼容 OpenAI API ，以便开发者能将 RWKV 模型用在 ChatGPT 客户端中。

State Cache 相关 API

/disable-state-cache

这个 API 用于禁用 state 缓存

API 地址：（post）http://127.0.0.1:8000/disable-state-cache

/enable-state-cache

这个 API 用于启用 state 缓存

API 地址：（post）http://127.0.0.1:8000/enable-state-cache

/reset-state-cache

这个 API 用于重置 state 缓存设置

API 地址：（post）http://127.0.0.1:8000/reset-state-cache

有关 State 文件是什么，以及它的详细用法，请参考此文章 (opens in a new tab)。

Root API

/exit

这个 API 用于退出 RWKV Runner 的后端进程。

API 地址：（post）http://127.0.0.1:8000/exit

此 API 及后续 API 请求通常无法获得任何响应，因为进程已被关闭。

/

此 API 用于检查 RWKV Runner 服务是否在工作状态。

API 地址：（get）http://127.0.0.1:8000/

如果你已经打开了 WebUI，会得到以下返回：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta content="width=device-width, initial-scale=1.0" name="viewport" />
    <title>RWKV-Runner</title>
    <link href="/assets/logo.png" rel="icon" type="image/x-icon">
    <script type="module" crossorigin src="/assets/index.js"></script>
    <link rel="modulepreload" crossorigin href="/assets/vendor.js">
    <link rel="modulepreload" crossorigin href="/assets/pdfjs-dist.js">
    <link rel="modulepreload" crossorigin href="/assets/uuid.js">
    <link rel="stylesheet" href="/assets/index.css">
</head>
<body>
    <div id="root"></div>
</body>
</html>

在浏览器中访问 http://127.0.0.1:8000/ (opens in a new tab) ，可以访问 WebUI 。

如果你得到以下返回，意味着服务正在运行，但未打开 WebUI：

{
    "Hello": "World!"
}

API 并发压力测试

ab -p body.json -T application/json -c 20 -n 100 -l http://127.0.0.1:8000/chat/completions

请求主体：

{"messages": [{"role": "user","content": "Hello"}]}

API 常见问题

问题1：我要去哪里查看 RWKV Runner 的 API 文档？

本地启动 RWKV Runner 并启动一个模型，你将可以在 http://localhost:8000/docs (opens in a new tab) 中查看 RWKV Runner 的 API 文档。

问题2： deploy 模式下，哪些 API 会因“危险权限”而被屏蔽？

在部署模式下，一切会影响服务器系统和硬件的 API 都会被屏蔽掉，这是为了安全起见。

比如：/switch-model 、 /exit 以及 State Cache 相关的 API 都会被屏蔽。

问题3：为什么我本地部署 RWKV Runner 就默认开启了 deploy 模式？

在 RWKV Runner 中，如果你勾选了 “启用 WebUI“ ，那么默认开启了 deploy 模式。

你可以通过关闭此选项，来解除部署模式，进而使用一些危险权限的 API 。

问题4 ：为什么 RWKV Runner 的 embaddings API 用不了？

截至目前（2023-07-05，RWKV Runner V 1.8.4） 不建议使用 RWKV Runner 文档中提供的 embaddings API 。

文档中的 embaddings API 目前停留在 RWKV-4，未针对 RWKV5/6 架构进行重构，因此会报错。