RWKV Runner 超详细 API 指南
大家好，今天我们带来 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 就像给模型喂镇静剂，优先考虑前 n% 概率质量的结果。如设置成 0.1 则考虑前 10% , 生成内容质量更高但更保守。如设置成 1 ，则考虑所有质量结果，内容质量降低但更多样。 Presence penalty 存在惩罚，根据“新 token 在至今的文本中是否出现过”来对其进行惩罚。值越大，模型涉及新话题的可能性越高。 Frequency Penalty 频率惩罚，根据“新 token 在至今的文本中出现的频率/次数”来进行惩罚。值越大，模型重复相同短语/句子的可能性越低。 max_tokens 模型生成文本时的最大 token 数。如果你在对外提供服务，建议限制单个请求的 max_tokens，太高可能导致极端情况下单个响应消耗大量的服务器资源。 续写小说和对话这一类需要创造性的任务，需要高 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 的所有可选参数： 参数名称 类型 参数解释 max_tokens integer 生成文本的最大token数，最大 102400，对外部署时建议限制文本长度。 temperature number 解码参数之一，具体效果参考前文，范围[0, 3] top_p number 解码参数之一，具体效果参考前文，范围 [0, 1] presence_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] frequency_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] penalty_decay number 频率的衰减参数，范围 [0.99, 0.999]，不建议修改 top_k integer 模型生成内容的候选词数量，范围 [0, 25] 不建议修改 global_penalty boolean 是否应用全局惩罚，不建议修改 state string 指定使用的 RWKV state 文件路径 model string | null 指定使用的 RWKV 模型路径 stream boolean 是否以流模式生成文本。 stop string | array | null 指定生成文本时的停止词。 user_name string | null 聊天模式的用户名，不建议修改 assistant_name string | null 聊天模式的助手名，不建议修改 system_name string | null 聊天模式的系统名，不建议修改 /completions /completions和 v1/completions是相同的续写 API，对应的是 RWKV Runner 的基础续写模式，也就是让模型接着你的 prompt 继续生成内容。 必需参数 "prompt": 你提供给模型的续写 prompt 。 因此，聊天 API 的基础请求主体如下： { "prompt": "那一天，人们又想起来被暴雨支配的恐惧..." } 可选参数 下面列出了续写 API 的所有可选参数： 参数名称 类型 参数解释 max_tokens integer 生成文本的最大token数，最大 102400，对外部署时建议限制文本长度。 temperature number 解码参数之一，具体效果参考前文，范围[0, 3] top_p number 解码参数之一，具体效果参考前文，范围 [0, 1] presence_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] frequency_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] penalty_decay number 频率的衰减参数，范围 [0.99, 0.999]，不建议修改 top_k integer 模型生成内容的候选词数量，范围 [0, 25] 不建议修改 global_penalty boolean 是否应用全局惩罚，不建议修改 state string 指定使用的 RWKV state 文件路径 model string | null 指定使用的 RWKV 模型路径 stream boolean 是否以流模式生成文本。 stop string | array | null 指定生成文本时的停止词。 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" 。 可选字段 参数名称 类型 参数解释 model string | null 指定使用的 RWKV 模型路径 strategy string 驱动 RWKV 模型的方法 tokenizer string | nulls 指定使用的 RWKV 分词器路径，不建议修改 customCuda boolean 是否启用自定义 cuda 算子，如果是比较新的 Nvidia 显卡，建议改成 true deploy boolean 是否启用部署模式，启用部署模式会屏蔽掉会屏蔽掉/switch-model、 /exit和其他有风险的 API /update-config /update-config API 用于用于更新模型默认配置，或者说缺省参数，包括解码参数、是否挂载 state 文件等。 当调用续写 API （ /chat/completions 或者 /completions） 且没有传递参数时，将使用 /update-config 设置的默认参数。 可选字段 参数名称 类型 参数解释 max_tokens integer 生成文本的最大token数，最大 102400，对外部署时建议限制文本长度。 temperature number 解码参数之一，具体效果参考前文，范围[0, 3] top_p number 解码参数之一，具体效果参考前文，范围 [0, 1] presence_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] frequency_penalty number 解码参数之一，具体效果参考前文，范围 [-2, 2] penalty_decay number 频率的衰减参数，范围 [0.99, 0.999]，不建议修改 top_k integer 模型生成内容的候选词数量，范围 [0, 25] 不建议修改 global_penalty boolean 是否应用全局惩罚，不建议修改 state string 指定使用的 RWKV state 文件路径 参考的请求主体： { "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
