大家好，今天我们带来 RWKV Runner API 的详细用法。

本文会列出 RWKV Runner 每一个 API 的作用、请求主体的参考结构、必需字段和可选字段等内容，帮助大家更轻松、更灵活地调用 RWKV Runner 的 API 。

如果你还不了解 RWKV Runner ，我们建议你从 RWKV 中文官网- RWKV Runner 简介开始阅读。

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

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

你可能注意到了，很多 RWKV 部署/体验工具都支持调整 Temperature、Top_P、Presence penalty 和 Frequency Penalty 等 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 的聊天续写模式，也就是和模型对话。

必需参数

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

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

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

注意，上面是一个最简单的聊天续写请求，如果你希望控制模型的创作风格、回答的最大字数等细节，请按需添加以下参数：

可选参数

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

/completions

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

必需参数

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

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

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

可选参数

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

RWKV Runner 默认使用 \n\nUser 作为停止词，如果你希望修改默认的模型停止词，则可以指定 stop 字段（一个字符串或者是一个字符串列表）。可参考以下停止词：

["\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 模型。

必需字段

• "model":用于切换 RWKV 模型，填 RWKV 模型文件的路径
• "strategy"：模型部署的方法，如"cuda fp16" 。

可选字段

/update-config

/update-config API 用于用于更新模型默认配置，或者说缺省参数，包括解码参数、是否挂载 state 文件等。

当调用续写 API （ /chat/completions 或者 /completions） 且没有传递参数时，将使用 /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 及运行设备的状态，比如运行状态、进程 ID 、GPU 型号。 参考的

**响应结构： **

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

RWKV Runner 状态码：0 是模型离线，2 是模型正在载入，3 是模型正常工作中

MIDI 相关 API

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

/text-to-midi

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

必需字段

• "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）。

必需字段

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

参考的响应结构：

{ 
    "text": " p:24:a p:2a:a " 
}

/txt-to-midi

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

必需字段

• "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 与 RWKV 模型无关，且需要先安装 fluidsynth 。

必需字段

• "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)。

必需字段

• "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 查询参数

• 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

State 缓存相关 API 没有请求主体，下面是几个 State API 的作用：

• /disable-state-cache：禁用 state 缓存
• /enable-state-cache：启用 state 缓存
• /reset-state-cache：重置 state 设置

有关 State 文件是什么，以及它的详细用法，请参考RWKV State 介绍文章。

常见疑问

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

本地启动 RWKV Runner 并启动一个模型，你将可以在 http://localhost:8000/docs 中查看 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 架构进行重构，因此会报错。

更多 RWKV Runner 及 API 使用问题，欢迎加入 QQ 群交流：

• RWKV Runner 交流群：818930736
• RWKV 模型交流群：224287095