API 用法

以下接口适用于 RWKV Runner v1.9.12。

默认地址：http://127.0.0.1:8000
交互式 OpenAPI：启动后访问 http://127.0.0.1:8000/docs
上游路由源码：backend-python/routes

/switch-model、/exit、State Cache 和部分 MIDI 文件写入端点属于管理接口。开启 deploy 后，这些接口会返回 403；不要把未受保护的 Runner 管理端口直接暴露到公网。

当前端点总览

类别	方法与路径	说明
生成	`POST /v1/chat/completions`	OpenAI 风格聊天补全
生成	`POST /v1/completions`	文本续写
向量	`POST /v1/embeddings`	RWKV 文本向量
模型	`GET /v1/models`	获取模型列表
模型	`GET /v1/models/{model_id}`	获取指定模型
配置	`POST /switch-model`	加载 `.pth` 或 `.gguf`，并为 `.pth` 选择 RWKV Pip 或 Albatross
配置	`POST /update-config`	更新默认解码参数或 State
配置	`GET /status`	后端状态、PID 与设备名称
Albatross	`GET /albatross/profile`	性能计数；查询参数 `reset=true` 可读取后重置
Albatross	`POST /albatross/profile/reset`	重置性能计数
State Cache	`POST /enable-state-cache`	启用前缀状态缓存
State Cache	`POST /disable-state-cache`	禁用并清空状态缓存
State Cache	`POST /reset-state`	重置 State Cache
文件	`POST /file-to-text`	上传并解析 `.txt` 或 `.pdf`
MIDI	`POST /text-to-midi`、`/midi-to-text`	文本与 MIDI 互转
MIDI	`POST /txt-to-midi`、`/midi-to-wav`、`/text-to-wav`	服务器文件转换，部署模式下禁用
根路由	`GET /`、`POST /exit`	健康检查与关闭后端

解码参数

聊天补全、文本续写和 /update-config 共用以下参数。请求中的值会覆盖 Runner 当前默认配置。

字段	类型与范围	作用
`max_tokens`	integer，`1..102400`	最大生成 token 数
`temperature`	number，`0..3`	采样温度
`top_p`	number，`0..1`	核采样累计概率
`top_k`	integer，`0..100`	候选 token 数
`presence_penalty`	number，`-2..2`	出现惩罚
`frequency_penalty`	number，`-2..2`	频率惩罚
`penalty_decay`	number，`0.99..0.999`	惩罚随距离衰减
`global_penalty`	boolean	是否把输入 prompt 计入惩罚
`state`	string	State-tuned 文件路径

聊天补全

POST/v1/chat/completions

支持普通或 SSE 流式输出、工具调用、原始消息和助手前缀补全。

请求主体application/json至少提供一条消息。

messagesarray<Message>必填

按顺序排列的 system、user、assistant 或 tool 消息。

收起子字段

rolestring必填

system、user、assistant 或 tool。

contentstring | null必填

消息正文；工具调用的 assistant 消息可以为 null。

namestring可选

可选消息名称。

rawboolean可选

system、user、assistant 消息是否按原始文本处理。

默认值：false

prefixboolean可选

仅用于最后一条 assistant 消息，让模型续写已有助手前缀。

默认值：false

tool_callsarray<ToolCall>可选

assistant 发起的函数调用。

tool_call_idstring可选

tool 消息所响应的调用 ID。

modelstring | null可选

当前实现始终使用已加载模型。

默认值：rwkv

streamboolean可选

为 true 时返回 text/event-stream，并以 [DONE] 结束。

默认值：false

stopstring | array<string> | null可选

停止字符串；RWKV 文本模型还会补入用户和助手角色停止词。

stop_token_idsarray<integer> | null可选

按 token ID 停止生成。

toolsarray<Tool> | null可选

OpenAI 风格函数工具定义。

tool_choicenone | auto | required | object可选

工具选择策略或指定函数。

默认值：auto

user_namestring | null可选

覆盖内部用户角色名。

assistant_namestring | null可选

覆盖内部助手角色名。

system_namestring | null可选

覆盖内部系统角色名。

presystemboolean可选

是否在开头插入默认系统提示。

默认值：false

max_tokens / temperature / top_p / top_knumber可选

见上方公共解码参数。

presence_penalty / frequency_penalty / penalty_decaynumber可选

见上方公共解码参数。

global_penalty / stateboolean | string可选

见上方公共解码参数。

成功响应200application/json非流式响应；流式请求返回 chat.completion.chunk。

objectstring始终返回

非流式为 chat.completion，流式为 chat.completion.chunk。

modelstring始终返回

当前模型名称。

choicesarray<object>始终返回

生成结果；普通响应使用 message，流式响应使用 delta。

usageobject可能返回

仅非流式响应包含 token 用量。

示例

curl -X POST http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "rwkv",
"messages": [
  { "role": "system", "content": "回答要简洁" },
  { "role": "user", "content": "用一句话介绍 RWKV" }
],
"max_tokens": 200,
"temperature": 1,
"top_p": 0.3,
"stream": false
}'

curl -X POST http://127.0.0.1:8000/v1/chat/completions \-H 'Content-Type: application/json' \-d '{"model": "rwkv","messages": [  { "role": "system", "content": "回答要简洁" },  { "role": "user", "content": "用一句话介绍 RWKV" }],"max_tokens": 200,"temperature": 1,"top_p": 0.3,"stream": false}'

函数调用只在 RWKV 文本模型路径启用。模型生成的 arguments 仍需由调用方进行 JSON 校验、参数白名单校验和权限控制。

文本续写

POST/v1/completions

让当前模型从 prompt 继续生成。prompt 接受字符串或字符串数组，但当前源码只处理数组中的第一项。

请求主体application/json

promptstring | array<string> | null必填

续写起始文本。空值会被替换为换行符；数组当前只使用第一项。

modelstring | null可选

当前实现始终使用已加载模型。

默认值：rwkv

streamboolean可选

是否返回 SSE。

默认值：false

stopstring | array<string> | null可选

停止字符串。

stop_token_idsarray<integer> | null可选

停止 token ID。

解码参数object fields可选

支持全部公共解码参数。

成功响应200application/json

objectstring始终返回

text_completion。

choices[].textstring始终返回

生成文本。

choices[].finish_reasonstring始终返回

通常为 stop。

usageobject可能返回

prompt_tokens、completion_tokens 与 total_tokens。

示例

curl -X POST http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{
"prompt": "那一天，人们又想起了被暴雨支配的恐惧……",
"max_tokens": 300,
"temperature": 1,
"top_p": 0.3,
"stream": false
}'

curl -X POST http://127.0.0.1:8000/v1/completions \-H 'Content-Type: application/json' \-d '{"prompt": "那一天，人们又想起了被暴雨支配的恐惧……","max_tokens": 300,"temperature": 1,"top_p": 0.3,"stream": false}'

Embeddings

POST/v1/embeddings

使用当前加载的 RWKV Pip 模型读取文本对应的内部状态表示；不支持 Albatross 和 llama.cpp / GGUF 后端。

请求主体application/json

inputstring | array<string> | array<array<integer>> | null必填

单条文本、多条文本，或 text-embedding-ada-002 tokenizer 的 token ID 数组。

modelstring | null可选

当前实现始终使用已加载模型。

默认值：rwkv

encoding_formatstring可选

省略时返回 JSON 数值数组；设为 base64 时返回 float32 数据的 Base64 编码。当前校验器不接受显式传入 null。

fast_modeboolean可选

旧版快速计算路径。当前 RWKV-7 后端缺少该路径依赖的属性，设为 true 会导致请求失败，请保持 false。

默认值：false

成功响应200application/json

dataarray<embedding>始终返回

每项包含 index 与 embedding。embedding 的维度由模型内部状态决定，不保证是扁平向量。

modelstring始终返回

实际模型名称。

usageobject始终返回

prompt_tokens 与 total_tokens。

示例

curl -X POST http://127.0.0.1:8000/v1/embeddings \
-H 'Content-Type: application/json' \
-d '{
"input": ["RWKV is an RNN", "RWKV 可以线性时间推理"],
"model": "rwkv",
"fast_mode": false
}'

curl -X POST http://127.0.0.1:8000/v1/embeddings \-H 'Content-Type: application/json' \-d '{"input": ["RWKV is an RNN", "RWKV 可以线性时间推理"],"model": "rwkv","fast_mode": false}'

这里的 embeddings 是 Runner 对模型内部状态的封装，不能直接假定为 OpenAI 风格的定长一维向量。使用 RWKV Runner 1.9.12 和 rwkv7-g1i-1.5b-20260805-ctx16384.pth 实测时，每条输入返回的数组形状为 32 × 64 × 64。如果准备写入向量数据库，请先在目标模型上确认维度、归一化方式和相似度计算方法。

模型与运行状态

GET/v1/models

列出模型

返回服务当前声明的模型列表。

成功响应200application/json

objectstring始终返回

固定为 list。

dataarray<Model>始终返回

模型条目数组。

模型详情

GET /v1/models/{model_id}route

按 ID 获取指定模型。

GET/status

读取 Runner 状态

用于监控模型加载状态和后端进程。

成功响应200application/json

statusinteger始终返回

0：离线，2：加载中，3：正常工作。

pidinteger始终返回

后端进程 ID。

device_namestring始终返回

第一张 GPU 的名称；未检测到 GPU 时为 CPU。

管理与配置

POST/switch-model

加载或切换模型

加载由 RWKV Pip 或 Albatross 运行的 .pth 模型，或加载由 llama.cpp 运行的 .gguf 模型。部署模式下不可调用。

请求主体application/json

modelstring必填

模型文件路径；空字符串表示卸载。`.gguf` 自动走 llama.cpp。

strategystring必填

RWKV Pip 使用设备/精度语法；Albatross 使用 albatross workers=N batch=N；GGUF 使用 cpu|cuda 上下文长度。

tokenizerstring | null可选

自定义 tokenizer 路径。

customCudaboolean可选

是否启用 RWKV 自定义 CUDA 算子。

默认值：false

deployboolean可选

成功加载后永久开启当前进程的部署模式。

默认值：false

后端选择规则

*.ggufllama.cpp

文件扩展名优先，自动进入 llama.cpp；Strategy 第二项为上下文长度，默认 8192。

albatrossRWKV-7 batch backend

Strategy 以 albatross 开头时，同一份 .pth 模型改由 Albatross 加载；workers 默认 1，batch 默认 32。

其他 Strategyconfigured RWKV backend

进入服务启动时选定的 RWKV Pip、rwkv.cpp 或 WebGPU 后端。

响应200 / 400 / 403 / 500

successstring可能返回

成功返回 JSON 字符串 success。

403error可能返回

当前进程已处于部署模式。

500error可能返回

模型加载失败。

示例

curl -X POST http://127.0.0.1:8000/switch-model \
-H 'Content-Type: application/json' \
-d '{
"model": "models/rwkv7-g1-2.9b.pth",
"strategy": "cuda fp16",
"tokenizer": "",
"customCuda": true,
"deploy": false
}'

curl -X POST http://127.0.0.1:8000/switch-model \-H 'Content-Type: application/json' \-d '{"model": "models/rwkv7-g1-2.9b.pth","strategy": "cuda fp16","tokenizer": "","customCuda": true,"deploy": false}'

/switch-model 会等模型加载完成后再返回结果。首次加载较大的模型、编译自定义算子或只使用 CPU 时，耗时可能超过普通 HTTP 客户端的默认超时。客户端超时不等于服务端已经停止加载：先查看 Runner 日志，并通过 /status 确认状态；status 仍为 2 时不要重复提交加载请求。

POST/update-config

更新默认生成配置

字段均可选；新值会在下一次生成时应用。State 路径会立即尝试加载。

请求主体application/json

max_tokensinteger可选

1..102400。

temperaturenumber可选

0..3。

top_pnumber可选

0..1。

top_kinteger可选

0..100。

presence_penaltynumber可选

-2..2。

frequency_penaltynumber可选

-2..2。

penalty_decaynumber可选

0.99..0.999。

global_penaltyboolean可选

是否把输入计入惩罚。

statestring可选

State-tuned 文件路径；空字符串表示不挂载。

成功响应200application/json

resultstring始终返回

JSON 字符串 success。

示例

curl -X POST http://127.0.0.1:8000/update-config \
-H 'Content-Type: application/json' \
-d '{
"max_tokens": 1000,
"temperature": 1,
"top_p": 0.3,
"top_k": 0,
"presence_penalty": 0,
"frequency_penalty": 1,
"penalty_decay": 0.996,
"global_penalty": false,
"state": ""
}'

curl -X POST http://127.0.0.1:8000/update-config \-H 'Content-Type: application/json' \-d '{"max_tokens": 1000,"temperature": 1,"top_p": 0.3,"top_k": 0,"presence_penalty": 0,"frequency_penalty": 1,"penalty_decay": 0.996,"global_penalty": false,"state": ""}'

文件、MIDI 与 State Cache

以下是 Runner 当前提供的文件、MIDI 与 State Cache 接口。面向公网部署时建议在网关中直接禁用管理和服务器文件路径接口。

路径	请求	响应与限制
`POST /file-to-text`	查询参数 `file_name`、`file_encoding`，multipart 字段 `file_data`	`{ pages: Document[] }`；仅 `.txt`、`.pdf`
`POST /text-to-midi`	`{ text }`	`audio/midi` 二进制
`POST /midi-to-text`	multipart 字段 `file_data`	`{ text }`
`POST /txt-to-midi`	`{ txt_path, midi_path }`	`"success"`；输出必须在 `midi/` 下；部署模式禁用
`POST /midi-to-wav`	`{ midi_path, wav_path, sound_font_path? }`	`"success"`；需安装 FluidSynth；部署模式禁用
`POST /text-to-wav`	`{ text, wav_name, sound_font_path? }`	`"success"`；部署模式禁用
`POST /enable-state-cache`	无	`"success"`；缺少 `cyac` 时返回 400
`POST /disable-state-cache`	无	`"success"`
`POST /reset-state`	无	`"success"`；缓存未启用时返回 400

错误处理与并发

模型未加载：生成和 Embeddings 返回 400 model not loaded。
空 messages 或空 Embeddings input：返回 400。
非 RWKV 后端调用 Embeddings：返回 400 model not support embedding。
当前路由会让 RWKV Pip、rwkv.cpp 和 WebGPU 的生成请求经过同一把生成锁；Albatross 请求不经过这把锁，而是交给自己的异步队列，调度器可将同时处理的请求组成批次。
流式调用应持续读取 SSE，直到收到 [DONE]，并在客户端断开时及时取消请求。
对外服务必须在反向代理处限制请求体、并发数、超时和 max_tokens。

历史与兼容接口

以下路径仅用于维护已有客户端，已从主接口说明中移出。新接入应使用右侧的当前规范路径；兼容路径可能在后续版本中删除。

历史或兼容路径	已确认版本状态	当前接口
`POST /chat/completions`	v1.9.12 仍兼容	`POST /v1/chat/completions`
`POST /completions`	v1.9.12 仍兼容	`POST /v1/completions`
`POST /embeddings`	v1.9.12 仍兼容	`POST /v1/embeddings`
`POST /v1/engines/text-embedding-ada-002/embeddings`	v1.9.12 仍兼容	`POST /v1/embeddings`
`POST /engines/text-embedding-ada-002/embeddings`	v1.9.12 仍兼容	`POST /v1/embeddings`
`GET /models`	v1.9.12 仍兼容	`GET /v1/models`
`GET /models/{model_id}`	v1.9.12 仍兼容	`GET /v1/models/{model_id}`
`GET /dashboard/billing/credit_grants`	v1.9.12 仍保留，仅用于历史客户端	无对应业务接口

On this page