Rizzo Flow快速上手:4条命令搭建本地LLM决策服务,新手10分钟跑通
Rizzo Flow快速上手:4条命令搭建本地LLM决策服务,新手10分钟跑通
Rizzo Flow 是一个开源、100% 本地运行的 LLM 决策服务:把非结构化状态(文本或 JSON)输入,直接输出带概率的类型化决策——是/否、多选项选择、量表评分、数值估计——而且不生成任何一个 token。它复现了 TypeSafe Jev 的编程模型,但跑在你自己的硬件上,接口与 Jev 兼容,改一个 URL 就能把现有代码指到 localhost。
下面这份新手教程,带你用 4 条命令 在 10 分钟内跑通整个服务。
为什么叫"System One":不生成 token 的决策
普通 LLM 做分类要一个字一个字"写"出答案,慢、还可能写坏 JSON。而 Rizzo Flow 的思路是:答案的信息在一次前向传播后就已存在——就是模型对每个候选答案字母分配的概率。
它的流程可以概括为四步(细节见 src/rizzo_flow/engine.py):
- 每个问题都变成单选题:每个候选答案映射为一个字母(A、B、C…),每题最多 26 个选项;
- 状态只处理一次:state 放在 prompt 开头,预填充一次后所有问题共享 KV 缓存;
- 只读答案字母的 logits:不采样、不生成;
- 纯 Python 把 logits 变成类型化输出:softmax、期望值、弃权策略、经过 schema 校验的 JSON 响应。
参考基准上,一次短决策约 50 ms(Q8_0,RTX 5060 Ti),GPU 显存约 5.6 GiB。
环境准备:先装好 Python 和 uv
开始之前确认三样东西:
- Python ≥ 3.11
- git
- uv(Rust 编写的 Python 包管理器,一条命令装好依赖)
💡 无需编译任何东西,也不需要安装任何 GPU 工具包——
rizzo download会自动挑选对应你机器的 llama.cpp 预构建包并校验 sha256。
4条命令快速开始:本地LLM决策服务搭建步骤
macOS、Windows、Linux 通用以下四条命令(项目支持 NVIDIA、AMD、Intel 和 Apple GPU,也支持纯 CPU):
第 1 条:克隆仓库并进入目录
git clone https://gitcode.com/gh_mirrors/ri/rizzo-flow && cd rizzo-flow
第 2 条:同步 Python 依赖(几秒,只有 4 个小包)
uv sync --locked
第 3 条:下载模型和运行时(唯一慢的一步,中断可断点续传)
uv run rizzo download
这一步会下载 llama.cpp 运行时(约 570 MB,取决于后端)和默认的 Rizzo Flow 4B Q8_0 微调权重(约 4.4 GB,存放在 models/)。急着看效果可以用 uv run rizzo download --size 1.7b 拿 1.8 GB 的小模型。
第 4 条:启动服务
uv run rizzo serve
模型加载约 10 秒,服务默认监听 http://127.0.0.1:8017。
打开 Playground:第一次获得类型化决策
服务起来后,浏览器打开 http://127.0.0.1:8017/playground:
- 从 Examples… 菜单挑一个示例(或自己写 state 和问题);
- 点 Run,右侧立即得到概率条、计时(round-trip / 推理 / 预填充 / 微批次数)和"0 个生成 token"的统计,还能一键复制等价的 cURL;
- 界面支持 IT / EN 双语切换,页面上方徽标显示当前回答的权重和精度。
不想开服务?一次性的离线运行也行:
uv run rizzo decide examples/ticket.json
仓库里还有几个现成示例可直接用:examples/ticket.json(客服工单)、examples/house.json(房产估价)、examples/numeric.json(数值读数)。
直接调用 API:Jev 兼容接口怎么请求
Rizzo Flow 提供两套接口,完整请求/响应格式见 request.schema.json 和 response.schema.json,交互式文档在 http://127.0.0.1:8017/docs:
- Jev 兼容接口
POST /v1/systemone:请求与 TypeSafe 公开 API 同形,支持noul(是/否)、choice(多选一)、score(量表)三种类型; - 原生接口
POST /v1/decisions:多支持numeric(带锚点的数值估计),且四种类型都可弃权(证据不足时明确说"无法判断")。
一条典型的 curl 请求:
curl http://127.0.0.1:8017/v1/systemone \
-H 'Content-Type: application/json' \
-d '{"state": "Help! My payouts have been failing for 3 days.", "model": "rizzo-latest",
"questions": {"is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"}}}'
响应直接是结构化 JSON:is_urgent 返回 noul: 0.99998,同时给出每个选项的概率、confidence 和 usage(output_tokens 恒为 0)。一次请求里问多个问题是它的精髓:所有问题共享同一份 state 的 KV 缓存,8 个是/否问题的总耗时远低于 8 次独立调用。
硬件怎么选:4B 还是 1.7B 模型
rizzo download 会根据你的机器自动挑后端:NVIDIA → CUDA、AMD/Intel → Vulkan、Mac Apple Silicon → Metal、无 GPU → CPU。运行 uv run rizzo devices 可查看运行时实际看到的设备。
| 参数 | 说明 |
|---|---|
--size 4b(默认) |
推荐,精度最高;Q8_0 约 4.4 GB,另有 Q4_K_M 2.6 GB、BF16 8.2 GB |
--size 1.7b |
快约 2 倍但精度明显更低,适合先跑通看看 |
--quant |
量化档位,默认 q8_0;q4_k_m 省显存约 1.7 GiB |
--device |
auto(默认)/ cuda / vulkan / metal / cpu |
--ctx |
每个问题的 token 上限,默认 8192(模型原生支持 1M 上下文) |
默认权重是官方 LoRA 微调版(为类型化决策专门训练,概率分布形态明显更好);--weights base 可切回原始 Spark-X2.5 权重。
彩蛋演示:让 LLM 实时玩贪吃蛇
服务还内置了一个贪吃蛇页面:http://127.0.0.1:8017/snake。蛇的每一步移动都是一次真实的 POST /v1/decisions 请求——棋盘状态作为 state,合法移动作为 choice 问题,候选格子上实时画出概率。实测约 150 ms/步、5.5 步/秒,全程 0 生成 token。
下一步:常用资源清单
- 内置示例与基准数据:examples/、benchmarks/
- 请求/响应 schema:request.schema.json、response.schema.json
- 训练与校准细节(意大利语):docs/training.md、docs/prompt-lab.md
- 基准脚本与评测:training/、scripts/
- 已提交的评测报告(含 logits 与权重哈希,可复算):results/README.md
📌 小结:克隆 → uv sync --locked → uv run rizzo download → uv run rizzo serve,四条命令即可在本地获得一个不生成 token 的 LLM 决策服务。概率默认未经校准,用于生产前建议在自有数据上做一次 rizzo calibrate 温度校准。


