rwkv_lightning 批量推理教程
rwkv_lightning 是基于 Albatross、PyTorch 和 FastAPI 的 RWKV 批量推理后端。它原生支持 NVIDIA CUDA 与 AMD ROCm，并提供批量补全、OpenAI 风格聊天、State Cache、FIM 等 HTTP API。
实测在单张 RTX 5090 上进行 960 路并发推理时，吞吐量可以达到 10000+ token/s。
- 项目地址：RWKV-Vibe/rwkv_lightning
- 上游 API 文档：rwkv_lightning_api_doc.md
安装依赖
先克隆仓库并进入项目目录，再按显卡平台安装 PyTorch 和服务依赖。
git clone https://github.com/RWKV-Vibe/rwkv_lightning.git
cd rwkv_lightningpip install torch torchvision --index-url https://download.pytorch.org/whl/cu132
pip install fastapi pydantic ninja numpypip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.2
pip install fastapi pydantic ninja numpy启动服务
先选择与模型文件相匹配的推理引擎。普通 .pth 模型使用 FP16；GemLite 与 CUTLASS 需要先按上游仓库中的量化说明转换模型，二者的模型文件不能混用。
python app.py \
--model-path /path/to/model \
--inference-engine fp16 \
--port 8000 \
--password rwkv7_7.2bpython app.py \
--model-path /path/to/model-gemlite-int8 \
--inference-engine gemlite \
--port 8000 \
--password rwkv7_7.2bpython app.py \
--model-path /path/to/model-w8a16 \
--inference-engine cutlass \
--port 8000 \
--password rwkv7_7.2b| 参数 | 是否必需 | 默认值 | 说明 |
|---|---|---|---|
--model-path | 是 | 无 | 模型路径，可以带或不带 .pth 后缀 |
--inference-engine / --backend | 否 | fp16 | 可选 fp16、gemlite 或 cutlass |
--port | 否 | 8000 | HTTP 服务端口 |
--password | 否 | 不启用 | API 密码；省略后不校验密码 |
服务固定监听 0.0.0.0。终端出现 Uvicorn 启动信息后，可以运行仓库自带的测试脚本：
bash ./test/test_curl.sh如果服务需要暴露到公网，请启用密码并在反向代理或防火墙中限制访问。/v1/models 与 /translate/v1/batch-translate 当前不校验服务密码，不能只依赖应用层鉴权保护这两个端点。
API 文档
默认地址为 http://127.0.0.1:8000。所有 POST 请求都需要发送 Content-Type: application/json。普通端点通过请求主体中的 password 鉴权；/openai/v1/* 还支持 Authorization: Bearer <password>。
端点速览
| 方法 | 路径 | 用途 | 流式响应 |
|---|---|---|---|
GET | /v1/models | 查询当前加载的模型 | 否 |
POST | /v1/chat/completions | 原生多 prompt 批量补全 | 可选 |
POST | /v2/chat/completions | 使用 V2 采样器批量补全 | 可选 |
POST | /translate/v1/batch-translate | 批量翻译 | 否 |
POST | /FIM/v1/batch-FIM | FIM 批量补全 | 可选 |
POST | /big_batch/completions | 超大 batch 补全 | 始终流式 |
POST | /state/chat/completions | 单分支 State 会话补全 | 可选 |
POST | /multi_state/chat/completions | 可分叉的 State 会话补全 | 可选 |
POST | /state/status | 查询三级 State Cache | 否 |
POST | /state/delete | 删除 State Cache | 否 |
GET | /openai/v1/models | OpenAI 风格模型列表 | 否 |
POST | /openai/v1/chat/completions | OpenAI 风格单路聊天补全 | 可选 |
原生生成参数
下表适用于原生补全、State、FIM 等端点；专用端点只会读取与自身有关的字段。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | string | rwkv7 | 仅作为响应标签，不会切换已经加载的模型 |
contents | string[] | [] | prompt 数组 |
max_tokens | integer | 8192 | 每条结果最多生成的 token 数 |
stop_tokens | string[] | ["\nUser:"] | 文本停止序列；不是整数 token ID |
temperature | number | 1.0 | 采样温度 |
top_k | integer | 50 | Top-K |
top_p | number | 0.6 | Top-P |
alpha_presence | number | 2.0 | Presence repetition penalty |
alpha_frequency | number | 0.2 | Frequency repetition penalty |
alpha_decay | number | 0.996 | 重复惩罚衰减 |
stream | boolean | false | 是否返回 SSE |
chunk_size | integer | 4 | 流式输出累计多少 token 后刷新一次 |
password | string | null | null | 普通端点的 JSON 鉴权凭据 |
查询模型
GET
/v1/models返回当前已经加载的模型。此端点当前不校验密码。
成功响应200application/json
objectstring始终返回固定为 list。
dataarray<Model>始终返回当前服务加载的模型列表。
收起子字段
idstring始终返回模型文件名。
objectstring始终返回固定为 model。
owned_bystring始终返回固定为 rwkv_lightning。
原生 V1 批量补全
POST
/v1/chat/completions输入 contents 数组并按位置返回多条结果。它不是 OpenAI messages 接口。
请求主体application/json
contentsarray<string>必填批量 prompt；每个元素对应一条 choice。
modelstring可选响应中的模型标签。
默认值：
rwkv7max_tokensinteger可选每条结果最多生成的 token 数。
默认值：
8192stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperaturenumber可选采样温度。
默认值：
1.0top_kinteger可选Top-K。
默认值：
50top_pnumber可选Top-P。
默认值：
0.6alpha_presencenumber可选Presence repetition penalty。
默认值：
2.0alpha_frequencynumber可选Frequency repetition penalty。
默认值：
0.2alpha_decaynumber可选重复惩罚衰减。
默认值：
0.996streamboolean可选为 true 时返回 SSE，并以 [DONE] 结束。
默认值：
falsechunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json非流式结构；流式请求返回 SSE。
idstring始终返回固定为 rwkv7-batch。
objectstring始终返回固定为 chat.completion。
modelstring始终返回请求中的模型标签。
choicesarray<Choice>始终返回按 contents 位置排列的生成结果。
收起子字段
indexinteger始终返回对应 contents 中的下标。
messageobject始终返回助手消息。
收起子字段
rolestring始终返回固定为 assistant。
contentstring始终返回生成文本。
finish_reasonstring始终返回当前为 stop。
原生 V2 批量补全
POST
/v2/chat/completions请求与响应结构和 V1 相同，但使用 V2 batch sampler，并采用不同的默认采样参数。
请求主体application/json
contentsarray<string>必填批量 prompt。
modelstring可选响应中的模型标签。
默认值：
rwkv7max_tokensinteger可选每条结果最多生成的 token 数。
默认值：
8192stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperaturenumber可选采样温度。
默认值：
1.0top_kinteger可选V2 默认 Top-K。
默认值：
500top_pnumber可选V2 默认 Top-P。
默认值：
0.5alpha_presencenumber可选Presence repetition penalty。
默认值：
1.0alpha_frequencynumber可选Frequency repetition penalty。
默认值：
0.1alpha_decaynumber可选重复惩罚衰减。
默认值：
0.99streamboolean可选是否返回 SSE。
默认值：
falsechunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json结构与 V1 相同，非流式 id 为 rwkv7-batch-v2。
idstring始终返回固定为 rwkv7-batch-v2。
objectstring始终返回固定为 chat.completion。
modelstring始终返回请求中的模型标签。
choicesarray<Choice>始终返回生成结果；字段结构与 V1 相同。
批量翻译
POST
/translate/v1/batch-translate兼容沉浸式翻译的自定义 API。此端点当前不校验服务密码。
请求主体application/json
source_langstring可选源语言代码。auto 目前不会运行独立语言检测器。
默认值：
autotarget_langstring必填目标语言代码，例如 zh-CN 或 en。
text_listarray<string>必填需要翻译的文本数组。
placeholdersarray<string> | null可选Schema 接受此字段，但当前翻译路由尚未使用。
默认值：
null成功响应200application/json
translationsarray<Translation>始终返回与 text_list 按位置对应的翻译结果。
收起子字段
detected_source_langstring始终返回报告的源语言；source_lang=auto 时当前固定为 en。
textstring始终返回翻译后的文本。
FIM 批量补全
POST
/FIM/v1/batch-FIM面向 RWKV-7 G1c 系列模型的 Fill-In-the-Middle 接口，按位置配对 prefix 与 suffix。
请求主体application/json
prefixarray<string>必填中间缺失内容之前的文本数组。
suffixarray<string>必填中间缺失内容之后的文本数组；应与 prefix 等长。
modelstring可选响应中的模型标签。
默认值：
rwkv7max_tokensinteger可选每条结果最多生成的 token 数。
默认值：
8192temperaturenumber可选采样温度。
默认值：
1.0top_kinteger可选Top-K。
默认值：
50top_pnumber可选Top-P。
默认值：
0.6alpha_presence / alpha_frequency / alpha_decaynumber可选重复惩罚参数，默认值见上方公共参数表。
streamboolean可选是否返回 SSE。
默认值：
falsechunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json流式请求使用通用 batch SSE 格式。
idstring始终返回固定为 rwkv7-batch。
objectstring始终返回固定为 FIM.completion。
modelstring始终返回请求中的模型标签。
choicesarray<Choice>始终返回按 prefix 与 suffix 配对位置返回的补全文本。
prefix 与 suffix 当前通过 zip 配对，长度不一致时多出的元素会被忽略。FIM 路由固定使用空停止序列，因此请求中的 stop_tokens 不生效。
超大 batch 补全
POST
/big_batch/completions面向尽可能大的并行 batch，只使用 temperature 采样，并始终返回 SSE。
请求主体application/json
contentsarray<string>必填批量 prompt。
max_tokensinteger可选每条结果最多生成的 token 数。
默认值：
8192stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperaturenumber可选唯一生效的采样参数。
默认值：
1.0chunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200text/event-stream即使 stream=false，此端点也始终返回 SSE。
choices[].indexinteger始终返回对应 contents 中的输入下标。
choices[].delta.contentstring始终返回该输入本次新增的文本。
[DONE]sentinel始终返回全部生成结束后的终止事件。
单分支 State 会话
POST
/state/chat/completions为一个稳定的 session_id 保存并复用 RWKV State。每次请求只能包含一个 prompt。
请求主体application/json
session_idstring必填稳定且唯一的会话标识；后续请求使用同一值继续会话。
contentsarray<string>必填必须且只能包含一个 prompt。
modelstring可选响应中的模型标签。
默认值：
rwkv7max_tokensinteger可选最多生成的 token 数。
默认值：
8192stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperature / top_k / top_pnumber可选采样参数，默认值见上方公共参数表。
alpha_presence / alpha_frequency / alpha_decaynumber可选重复惩罚参数，默认值见上方公共参数表。
streamboolean可选是否返回 SSE。
默认值：
falsechunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json非流式结构与 V1 相同；流式请求使用通用 batch SSE。
idstring始终返回固定为 rwkv7-batch。
objectstring始终返回固定为 chat.completion。
modelstring始终返回请求中的模型标签。
choicesarray<Choice>始终返回当前会话的生成结果。
不要并发写入同一个 session_id。首次请求会创建零 State，后续请求会读取并更新同一 State；复用已有 State 时，服务会在没有前导空行的 prompt 前自动补上两个换行。
可分叉的 State 会话
POST
/multi_state/chat/completions在一个会话下保存多个可分叉的对话节点；每次成功生成都会返回新的 dialogue_idx。
请求主体application/json
session_idstring必填会话主标识。
dialogue_idxinteger必填要继续的对话节点；根节点使用 0。
默认值：
0contentsarray<string>必填必须且只能包含一个 prompt。
modelstring可选响应中的模型标签。
默认值：
rwkv7max_tokensinteger可选最多生成的 token 数。
默认值：
8192stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperature / top_k / top_pnumber可选采样参数，默认值见上方公共参数表。
alpha_presence / alpha_frequency / alpha_decaynumber可选重复惩罚参数，默认值见上方公共参数表。
streamboolean可选是否返回 SSE。
默认值：
falsechunk_sizeinteger可选流式输出的刷新粒度。
默认值：
4passwordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json非流式响应直接返回新节点；流式响应会在 [DONE] 前发送新节点元数据。
idstring始终返回固定为 rwkv7-multi-state。
objectstring始终返回固定为 chat.completion。
modelstring始终返回请求中的模型标签。
choicesarray<Choice>始终返回生成结果。
dialogue_idxinteger始终返回本次生成后创建的新节点编号。
非零 dialogue_idx 必须已经存在，否则返回 404。若要从旧节点分叉，继续传入该旧节点的编号；服务会为新回复分配另一个编号，并将 State 保存为 <session_id>:<new_dialogue_idx>。
查询 State Cache
POST
/state/status返回 VRAM、RAM 与 SQLite 三级缓存中的会话数量和明细。
请求主体application/json
passwordstring | null可选服务启用密码后必须提供；未启用密码时可发送空对象。
默认值：
null成功响应200application/json
statusstring始终返回成功时为 success。
total_sessionsinteger始终返回缓存中的会话总数。
l1_cache_countinteger始终返回VRAM 中的会话数。
l2_cache_countinteger始终返回RAM 中的会话数。
database_countinteger始终返回SQLite 中的会话数。
sessionsarray<Session>始终返回会话缓存明细。
收起子字段
session_idstring始终返回会话或分支标识。
cache_levelstring始终返回L1 (VRAM)、L2 (RAM) 或 Database (Disk)。
last_updatedstring始终返回内存标识或数据库更新时间。
timestampnumber始终返回Unix 时间戳。
删除 State Cache
POST
/state/delete删除指定会话；可同时删除该会话的全部分支。
请求主体application/json
session_idstring必填要删除的会话标识。
delete_prefixboolean可选为 true 时同时删除所有 <session_id>:* 分支。
默认值：
falsepasswordstring | null可选服务启用密码后必须提供。
默认值：
null成功响应200application/json
statusstring始终返回成功时为 success。
messagestring始终返回删除结果说明。
未找到404application/json未找到精确会话且 delete_prefix=false 时返回。
statusstring始终返回固定为 not_found。
messagestring始终返回未找到的会话说明。
OpenAI 风格模型列表
GET
/openai/v1/models返回与 /v1/models 相同的核心列表结构，并在服务启用密码时执行 Bearer 鉴权。
请求头
AuthorizationstringHEADER可能返回服务启用密码后填写 Bearer <password>。
成功响应200application/json
objectstring始终返回固定为 list。
dataarray<Model>始终返回当前服务加载的模型列表。
收起子字段
idstring始终返回模型文件名。
objectstring始终返回固定为 model。
owned_bystring始终返回固定为 rwkv_lightning。
OpenAI 风格聊天补全
POST
/openai/v1/chat/completions面向 OpenAI 客户端的单 choice 文本聊天接口，支持普通响应与 SSE。
请求头
AuthorizationstringHEADER可能返回服务启用密码后填写 Bearer <password>；也可以改用请求主体中的 password。
请求主体application/jsonmessages、system 或 contents 至少需要提供一段有效文本。
messagesarray<Message>可选推荐使用的文本消息列表。
收起子字段
rolesystem | developer | user | assistant必填消息角色。
contentstring | array<TextPart>必填消息文本；数组中当前只读取 type=text 的部分。
systemstring | null可选额外系统提示；会与 system、developer 消息合并。
默认值：
nullcontentsarray<string>可选不使用 messages 时，可将第一项作为 user 文本。
默认值：
[]modelstring可选当前不会切换已经加载的模型。
默认值：
rwkv7max_tokensinteger可选最多生成的 token 数。
默认值：
4096stop_tokensarray<string>可选文本停止序列。
默认值：
["\nUser:"]temperaturenumber可选采样温度。
默认值：
1.0top_kinteger可选Top-K。
默认值：
20top_pnumber可选Top-P。
默认值：
0.6alpha_presencenumber可选Presence repetition penalty。
默认值：
1.0alpha_frequencynumber可选Frequency repetition penalty。
默认值：
0.1alpha_decaynumber可选重复惩罚衰减。
默认值：
0.996enable_thinkboolean可选为 true 时让 prompt 以 Assistant: <think 结尾。
默认值：
falseuse_prefix_cacheboolean可选是否复用匹配的 prompt 前缀 State。
默认值：
truestreamboolean可选是否返回 OpenAI 风格 SSE。
默认值：
falsechunk_sizeinteger | null可选默认流式为 1，非流式为 16。
默认值：
nullpasswordstring | null可选Bearer header 的替代鉴权方式。
默认值：
null成功响应200application/json非流式响应；流式请求返回 chat.completion.chunk。
idstring始终返回随机生成的 chatcmpl-* 标识。
objectstring始终返回非流式为 chat.completion。
createdinteger始终返回Unix 时间戳。
modelstring始终返回当前加载的模型文件名。
choicesarray<Choice>始终返回当前只返回一个 choice。
收起子字段
indexinteger始终返回固定为 0。
messageobject始终返回助手消息。
收起子字段
rolestring始终返回固定为 assistant。
contentstring始终返回生成文本。
finish_reasonstring始终返回推理层返回的结束原因。
usageobject始终返回非流式 token 用量。
收起子字段
prompt_tokensinteger始终返回输入 token 数。
completion_tokensinteger始终返回输出 token 数。
total_tokensinteger始终返回输入与输出 token 总数。
当前 OpenAI 风格端点只处理文本形式的 system、developer、user 与 assistant 消息，不支持图片、音频、工具调用或结构化输出。use_prefix_cache 是自动复用匹配的 prompt 前缀，与显式 session_id 的 State 会话不同。
流式响应与常见错误
原生 V1、V2、State、FIM 和 big-batch 使用项目自有的轻量 SSE 格式；只有 /openai/v1/chat/completions 返回 OpenAI 风格的 ID、role chunk 和结束原因。两种流式响应都以 data: [DONE] 结束。
| HTTP 状态码 | 常见原因 |
|---|---|
400 | 请求 batch 超过 prefill 上限、缺少 session_id / dialogue_idx，或 JSON 无效 |
401 | 服务启用了密码，但凭据缺失或错误 |
404 | State 或对话分支不存在 |
422 | FastAPI / Pydantic 字段校验失败 |
499 | 非流式请求完成前客户端已经断开连接 |
500 | 推理或服务内部错误 |
客户端断开连接后，服务会取消排队或正在运行的生成。流式请求在 prefill 队列阶段超出 batch 上限时，错误也可能以 SSE data: 事件返回。
鸣谢
感谢 Triang-jyed-driung 提供的 Rapid-Sampling 内核，它还包含兼容 ROCm 的原生 HIP 内核。
这份文档对您有帮助吗？
粤公网安备44030002010697号