RWKV-Runner 中文使用教程

一、项目速览

入门 · 1 分钟版

RWKV Runner 是一个针对 RWKV 大模型 的一站式管理工具。它的核心卖点是全自动化：你不需要懂 Python 环境配置、CUDA 安装、模型下载这些繁琐流程，下载一个 8MB 的可执行文件，启动后就能直接聊天。

它是什么：一个带图形界面的 RWKV 模型启动器 + 管理面板，同时提供与 OpenAI API 完全兼容的接口
它解决什么问题：让普通开发者/爱好者能在本地跑一个开源大模型，而不用折腾命令行和依赖地狱。装上就能用，用完就能关
谁最该用：想体验本地大模型但不想碰 Linux 服务器、想用 RWKV 替代 ChatGPT 但不想被 API 调用的开发者，以及需要离线部署推理服务的团队

一句话判断：如果你「想用大模型但不想折腾环境」，RWKV Runner 是目前门槛最低的本地方案之一。

二、核心功能与架构

进阶 · 推荐细读

RWKV Runner 的结构很清晰：一个 前端界面（Wails 桌面应用）+ 后端推理服务（Python FastAPI）。两者可以合在一起跑，也能拆开——后端部署在服务器上，前端只当客户端用。

RWKV Runner 架构示意图

核心能力拆解：

全自动模型管理：你只需要选择模型版本（比如 RWKV-4 1.5B、7B 或 14B），Runner 会自动从 Hugging Face 下载并加载，不需要手动找模型文件
OpenAI 兼容 API：启动后本地会开一个 http://127.0.0.1:8000 的服务，接口格式与 OpenAI 的 Chat Completions 完全一致。这意味着你现有的 ChatGPT 客户端、脚本、插件都可以直接连上来用
一键切换模型：在设置页面切换不同大小的模型，后台会自动卸载旧模型、加载新模型，不需要重启服务
自定义加速内核：默认启用自定义 CUDA 内核加速，能显著降低显存占用并提升推理速度。如果遇到输出乱码，可以关闭该选项

作者视角补充：如果你想把 Runner 部署到服务器上给团队用，注意它默认的 max_tokens 上限是 102400，极端情况下单次请求会吃掉大量显存。建议根据实际场景在 backend-python/utils/rwkv.py 里调低这个值。

三、动手实践

入门

环境准备

方式一：直接下载桌面版（推荐）

去 Releases 页面下载对应系统的安装包（Windows 有 exe，macOS 有 dmg，Linux 有 AppImage）。安装后直接启动，界面会自动引导你选择模型并下载。

方式二：源码运行（适合开发者）

# 克隆仓库
git clone https://github.com/josStorer/RWKV-Runner
cd RWKV-Runner

# 启动后端推理服务（需要 Python 3.8+）
python ./backend-python/main.py

启动后访问 http://127.0.0.1:8000 可以看到 API 文档。要加载模型，调用 /switch-model 接口：

# 加载一个 1.5B 参数的 RWKV 模型（自动下载）
curl -X POST "http://127.0.0.1:8000/switch-model" \
  -H "Content-Type: application/json" \
  -d '{"model": "/path/to/your/model.pth"}'

最小可运行示例

启动服务后，用 Python 调用 OpenAI 格式的 API：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000",  # RWKV Runner 的地址
    api_key="sk-no-key-required"         # 本地服务不需要 key
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 RWKV"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

如果你没有安装 openai 库，先装：

pip install openai

运行后你会看到模型返回的中文回答。注意：第一次启动时会自动下载模型文件（约 1-7GB 不等），取决于你选的模型大小。

常见踩坑

显存不足：1.5B 模型需要约 3GB 显存，7B 需要 14GB。如果你用 CPU 推理（没有 NVIDIA 显卡），启动时会很慢，建议选最小的模型
输出乱码：如果看到乱码或重复输出，去配置界面关闭「Use Custom CUDA kernel to Accelerate」，或者升级显卡驱动
Windows Defender 报毒：这是误报，可以下载 v1.3.7 版本并允许自动更新，或者添加排除项

RWKV Runner 的聊天界面截图

作者视角补充：我专门测过「输出乱码」这个坑，原因其实不是 CUDA 内核本身有 bug，而是特定 GPU 架构（比如老款 GTX 系列）与自定义内核的兼容性不够好。如果你用 RTX 30/40 系列基本不会遇到。

四、进阶玩法

深入 · 老手可选

作为 API 网关使用

RWKV Runner 的 API 兼容性意味着你可以把它接入任何 OpenAI 生态工具。比如用 chatgpt-next-web 或者 Lobe Chat 这类前端：

# 以 Docker Compose 部署 Lobe Chat 为例
services:
  lobe-chat:
    image: lobehub/lobe-chat
    environment:
      OPENAI_API_KEY: sk-no-key-required
      OPENAI_PROXY_URL: http://host.docker.internal:8000  # RWKV Runner 的地址
    ports:
      - "3210:3210"

这样你在浏览器里用 Lobe Chat 聊天，背后实际跑的是本地的 RWKV 模型。

服务端部署方案

如果你想把 Runner 部署在远程服务器上，可以参考项目里的 deploy-examples 目录。一个典型的方案是用 Nginx 做反向代理并限制请求大小：

server {
    listen 443 ssl;
    server_name your-api-domain.com;

    client_max_body_size 10m;  # 限制请求体大小，防止滥用

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

注意：公开部署时一定要加 API 网关限流，否则恶意用户提交超长 prompt 会耗尽显存。

RWKV Runner 的配置页面截图

五、判断与建议