rai_finetune指南:用3步微调机器人具身数据,打造你的专属LLM
rai_finetune指南:用3步微调机器人具身数据,打造你的专属LLM
rai_finetune 是开源机器人智能体框架 RAI(Robotics Agentic Interface)中的微调模块,帮助你把机器人在真实任务中积累的具身交互数据,加工成标准训练集,并用 Unsloth 高效微调出一个懂自己机器人任务的专属 LLM。对于 RAI 新手来说,这是把"会调工具的通用大模型"升级为"只属于你的机器人助手"的完整路径:从数据提取、格式化到模型导出,全部一条命令线走通。
⚠️ 该模块目前标记为 Experimental(实验性),功能可能随时调整,但核心的"提取 → 格式化"数据流水线已经可以开箱使用。
RAI 本身是一个厂商无关的机器人智能体框架:它通过 ROS 2 工具让大模型执行复杂动作、运行自由接口、汇总日志、进行语音交互。而 rai_finetune 正是站在这些真实交互数据之上,帮你训练出更懂"现场"的模型。
微调流程图解:一条命令线走完 4 个阶段
rai_finetune 官方给出了清晰的系统组件图,整个流程分为三大阶段、四个环节:
| 阶段 | 做什么 | 关键工具 |
|---|---|---|
| ① 数据 | 从 Langfuse / LangSmith 提取机器人的对话与工具调用记录,格式化为 ChatML 训练数据 | extractors + formatters |
| ② 微调 | 加载基础模型(Qwen2.5、Llama 等),4-bit 量化 + LoRA 高效训练 | Unsloth Trainer |
| ③ 导出 | 合并 LoRA 权重、转 GGUF,打包成 Ollama 格式直接部署 | LoRA Merger / Ollama Converter |
其中 ① 数据流水线已可用;②③ 目前属于规划中的能力(源码中标注 To be implemented),这也是该模块被称为 Experimental 的原因。
一键搭建微调环境:3 个必做步骤
环境是新手最容易卡住的地方。rai_finetune 依赖 Unsloth,官方指定使用 Python 3.10(3.12+ 存在兼容问题),且指令面向 Linux。按下面三步操作即可:
1️⃣ 安装系统依赖
sudo apt update
sudo apt install -y libncurses5-dev libreadline-dev libsqlite3-dev libssl-dev zlib1g-dev build-essential
# 完整依赖清单见官方 README 的 "Install System Dependencies" 一节
2️⃣ 用 pyenv 安装 Python 3.10
curl https://pyenv.run | bash # 首次安装 pyenv
pyenv install 3.10
3️⃣ 用 uv 创建环境并激活
cd src/rai_finetune
pyenv local 3.10
uv sync --python 3.10
uv run pip install flash-attn --no-build-isolation
激活环境(后续所有 CLI 命令都需在激活状态下运行):
source src/rai_finetune/setup_finetune_shell.sh
💡 如果你计划把微调模型转换成 Ollama 格式,还需要额外编译 llama.cpp,获得其中的
llama-quantize量化工具(步骤详见 README.md 第 4 节)。
提取机器人交互数据:从 Langfuse 到训练集
RAI 的 LangChain 智能体在运行时会把每次对话、每次工具调用记录到可观测平台(如 Langfuse)。这些记录就是最宝贵的"具身数据"。
从 Langfuse 提取原始数据
python -m rai_finetune.data_cli extract langfuse \
--models "gpt-4o" \
--output langfuse_raw_data.jsonl \
--max-data-limit 5000
常用参数速查:
| 参数 | 作用 |
|---|---|
--models |
按模型名筛选(可重复传入多个) |
--start-time / --stop-time |
按 ISO 时间范围截取数据 |
--max-data-limit |
最多提取条数,默认 5000 |
--trace-id |
只看某一条完整调用链 |
--public-key / --secret-key |
Langfuse 密钥(建议改用环境变量 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY) |
如果你用的是 LangSmith,只需把子命令换成 extract langsmith,并加上 --api-key 和 --project-name 参数,同样输出标准化的 jsonl 原始数据。
格式化为 ChatML 训练数据
python -m rai_finetune.data_cli format \
--input langfuse_raw_data.jsonl \
--output langfuse_tc_data.jsonl \
--system-prompt "You are a specialized AI assistant for robotics and tool calling tasks."
这一步会:
- 只保留同时包含用户消息与工具调用的高质量样本;
- 把对话统一成 ChatML 的
messages结构,并替换成你指定的 system prompt——你的"专属人设"就在这句话里注入; - 输出遵循 OpenAI 推荐的微调数据格式,可直接对接 Unsloth。
微调与导出:从 LoRA 到 Ollama
微调环节由 Unsloth 负责:它用 4-bit 量化把基础模型(Qwen2.5、Llama 等)的显存占用压到最低,再叠加 LoRA 只训练少量适配器权重——消费级显卡也能跑起机器人领域微调。
训练产出的 LoRA 适配器会经过两个转换步骤落地:
- LoRA Merger:把适配器权重合并回基础模型,得到可独立部署的完整模型;
- Ollama Converter:导出 GGUF 格式并转成 Ollama 模型,直接在你的机器人主机上提供服务。
整个模块被刻意做成独立 Python 包(见 pyproject.toml),就是为了避免 Unsloth 需要的 Triton 版本与主框架中 whisper 等组件打架。
新手常见问题(FAQ)
| 问题 | 解决办法 |
|---|---|
| 为什么非要用 Python 3.10? | Unsloth 在 Python 3.12+ 存在 Dynamo 兼容问题,3.10 与 RAI 其余组件也最兼容 |
运行 CLI 报 Missing src/rai_finetune/.venv |
先执行 uv sync 创建环境,再 source src/rai_finetune/setup_finetune_shell.sh |
| 提取数据失败 | 检查 Langfuse 密钥与主机地址(--host,默认 http://localhost:3000)是否正确 |
| 训练数据为空 | 确认提取时用了 --type-filter GENERATION(默认值),且对话中确实存在工具调用 |
总结与延伸阅读
用三句话回顾整条 rai_finetune 微调路线:提取 Langfuse 里的机器人具身交互数据 → 格式化为带自定义 system prompt 的 ChatML 训练集 → 用 Unsloth + LoRA 微调后经 GGUF/Ollama 导出部署。
- 官方模块说明与全部参数:README.md
- CLI 命令入口:data_cli.py
- 数据提取基类(过滤器、字段清洗逻辑):base.py
- 工具调用数据格式化器:tool_calling.py
- ChatML 聊天模板:chat_template.py
- 训练依赖清单:pyproject.toml
建议先在 RAI 的 Langfuse 里积累足够多的真实工具调用记录,再按"提取 → 格式化 → 微调 → 导出"四步走一遍,你就能拥有一个真正懂自己机器人的专属 LLM。🤖


