mirror of
https://github.com/m1ngsama/robot_arm.git
synced 2026-03-25 19:53:49 +00:00
Add usage manual and replication guide
This commit is contained in:
whisper11111111111
parent
bb85c3266b
commit
eaa8b9a132
2 changed files with 236 additions and 0 deletions
100
使用说明书.md
Normal file
100
使用说明书.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
# 机械臂语音控制系统使用指南 v1.0
|
||||
|
||||
## 一、系统简介
|
||||
本系统是一套基于多模态大模型的具身智能控制方案，能够让用户通过**自然语言**直接指挥机械臂完成抓取、搬运、运动控制等任务。系统集成了 Whisper 语音识别、DeepSeek 语义理解、YOLOv8 视觉定位以及自动化运动控制算法。
|
||||
|
||||
---
|
||||
|
||||
## 二、快速开始
|
||||
|
||||
### 2.1 启动程序
|
||||
请确保已连接好 USB 摄像头和 ESP32 控制板（串口默认为 COM3），然后在终端运行：
|
||||
|
||||
```powershell
|
||||
python voice_main.py
|
||||
```
|
||||
|
||||
程序启动流程：
|
||||
1. **连接机械臂**：尝试通过 COM3 连接 ESP32，如失败将进入仿真模式。
|
||||
2. **加载模型**：依次加载 YOLOv8s（视觉）、Faster-Whisper（语音）和 DeepSeek（语义解析）。
|
||||
3. **打开界面**：弹出摄像头实时画面窗口 `Voice Robot Control`。
|
||||
|
||||
### 2.2 界面交互与快捷键
|
||||
|
||||
| 按键 | 功能描述 |
|
||||
|:---|:---|
|
||||
| **SPACE (空格)** | **主要的交互键**。按住开始录音说话，松开即结束录音并开始识别指令。 |
|
||||
| **C 键** | **进入/退出标定模式**。用于重新校准摄像头坐标与机械臂坐标的映射关系。 |
|
||||
| **R 键** | **手动复位**。强制让机械臂回到初始等待位置 (120, 0, 60)。 |
|
||||
| **O 键** | **手动松开**。强制张开夹爪 (Open)。 |
|
||||
| **Q 键** | **退出程序**。安全关闭摄像头、释放显存并断开串口连接。 |
|
||||
|
||||
---
|
||||
|
||||
## 三、语音指令说明
|
||||
|
||||
您可以用自然的中文直接说话，系统支持多种指令类型。
|
||||
|
||||
### 3.1 物品抓取与搬运 (视觉定位)
|
||||
系统会自动在画面中寻找物体（如削笔刀、盒子等），并根据您的指令操作。
|
||||
|
||||
- **抓取指令**：
|
||||
- "把削笔刀抓起来"
|
||||
- "抓住那个盒子"
|
||||
- **抬起指令**（支持指定高度）：
|
||||
- "把削笔刀抬起5厘米"
|
||||
- "将零件举高10公分"
|
||||
- *注意：系统会自动将“公分”换算为厘米，“两”换算为2。*
|
||||
|
||||
### 3.2 空间运动控制 (无目标)
|
||||
您可以像驾驶员一样指挥机械臂上下左右移动，**支持中文数字**。
|
||||
|
||||
- **精确移动**：
|
||||
- "向上三厘米"
|
||||
- "向左移动四米米" (兼容“米米”等语音误识别)
|
||||
- "往前伸10厘米"
|
||||
- **模糊移动** (不指定数值)：
|
||||
- 假如您只说 "向左"、"抬起"、"往下"，系统将**默认移动 5厘米**。
|
||||
|
||||
### 3.3 动作交互
|
||||
- **点头**："点头" —— 机械臂会在当前位置上下以 3cm 幅度快速往复运动三次。
|
||||
- **摇头**："摇头" —— 机械臂会在当前位置左右以 3cm 幅度快速往复运动三次。
|
||||
|
||||
### 3.4 放置与复位
|
||||
- **放下**：
|
||||
- 说 "放下" 或 "放到桌面上"。
|
||||
- **智能特性**：无论当前机械臂在多高，它会自动计算距离桌面的高度，精准降落到桌面 (Z=-15mm) 并松开夹爪。
|
||||
- **复位**：
|
||||
- 说 "复位"、"回到原点" 或 "归位"，机械臂将回到初始安全姿态。
|
||||
|
||||
---
|
||||
|
||||
## 四、标定教程 (C键)
|
||||
如果发现机械臂抓不准物体，说明摄像头位置变动了，需要重新标定。
|
||||
|
||||
1. **按 `C` 键**：进入标定模式，屏幕左上角显示 `CALIBRATION MODE`。
|
||||
2. **依次点击4个点**：请在画面中依次点击以下四个位置（假设机械臂原点在正下方）：
|
||||
- **P1**: 左上方 (对应现实坐标 x=90, y=90)
|
||||
- **P2**: 右上方 (对应现实坐标 x=200, y=90)
|
||||
- **P3**: 右下方 (对应现实坐标 x=200, y=-90)
|
||||
- **P4**: 左下方 (对应现实坐标 x=90, y=-90)
|
||||
3. **完成**：点完第4个点后，系统会自动计算映射矩阵并立即生效，无需重启。
|
||||
|
||||
---
|
||||
|
||||
## 五、故障排除
|
||||
|
||||
| 问题现象 | 可能原因 | 解决方法 |
|
||||
|:---|:---|:---|
|
||||
| **按空格没反应** | 程序焦点不在画面窗口上 | 请点击一下摄像头的画面窗口，确保它被激活。 |
|
||||
| **语音识别乱码** | 麦克风噪音过大或语速过快 | 请在安静环境下，语速适中，按住空格等0.5秒再说话。 |
|
||||
| **"未找到目标"** | YOLO没检测到物体 | 调整物体角度，确保护光照充足；或者物体不在训练类别中。 |
|
||||
| **抓取位置偏离** | 摄像头被移动过 | 请按 `C` 键重新进行四点标定。 |
|
||||
| **无法连接串口** | ESP32未插入或端口占线 |检查 USB 线，确认设备管理器中端口号是否为 COM3。 |
|
||||
|
||||
---
|
||||
|
||||
## 六、高级特性
|
||||
- **防幻觉机制**：系统会自动过滤 Whisper 产生的"向右向右向右"等重复幻觉。
|
||||
- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
|
||||
- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。
|
||||
136
复刻指南.md
Normal file
136
复刻指南.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
# 项目复刻指南 (Replication Guide)
|
||||
|
||||
本指南详细介绍了如何从零开始复刻“智能语音机械臂”项目，包括硬件准备、环境搭建、以及**最关键的三个AI模型（语音、视觉、大脑）的获取与训练方法**。
|
||||
|
||||
## 1. 硬件准备 (Hardware)
|
||||
|
||||
* **机械臂**: 也就是本项目中的 `RobotArmUltimate`。
|
||||
* 要求：支持串口通信（Serial），使用标准舵机控制协议。
|
||||
* 连接：USB连接电脑，需确认串口号（代码默认为 `COM3`，请在 `arm_main.py` 或 `voice_main.py` 中修改）。
|
||||
* **摄像头**: USB免驱网络摄像头。
|
||||
* 安装位置：固定在机械臂前方或上方，确保能覆盖工作台面。
|
||||
* **麦克风**: 任意USB麦克风或电脑内置麦克风。
|
||||
* **计算设备**: 建议配备 NVIDIA 显卡的 Windows/Linux 电脑（用于加速 YOLO 和 LLM 推理）。
|
||||
|
||||
## 2. 软件环境搭建 (Software)
|
||||
|
||||
### 2.1 基础环境
|
||||
1. 安装 **Python 3.10+**。
|
||||
2. 安装 **CUDA** (如果你有NVIDIA显卡)，建议版本 11.8 或 12.x，以便使用 `torch` 的 GPU 版本。
|
||||
3. 克隆本项目代码。
|
||||
|
||||
### 2.2 依赖安装
|
||||
请在终端运行以下命令安装所需库：
|
||||
|
||||
```bash
|
||||
# 基础工具
|
||||
pip install numpy opencv-python pyserial sounddevice scipy
|
||||
|
||||
# AI 模型相关 (PyTorch, Ultralytics, Transformers)
|
||||
# 注意：PyTorch 请去官网 https://pytorch.org/ 根据你的 CUDA 版本安装对应的命令
|
||||
pip install torch torchvision torchaudio
|
||||
|
||||
# 视觉与大模型
|
||||
pip install ultralytics transformers accelerate peft bitsandbytes
|
||||
|
||||
# 语音识别
|
||||
pip install openai-whisper
|
||||
```
|
||||
|
||||
## 3. 三大核心模型获取与训练指南 (Model Training)
|
||||
|
||||
本项目包含三个核心 AI 模块，请分别按照以下步骤准备。
|
||||
|
||||
### 3.1 👂 语音听觉 (Whisper)
|
||||
* **作用**: 将你的语音指令转为文字。
|
||||
* **获取方法**:
|
||||
* **无需训练**。代码使用了 OpenAI 的 `whisper` 模型。
|
||||
* 首次运行时，程序会自动下载模型权重（如 `base` 或 `small` 模型）。
|
||||
* 代码位置：`whisper_main.py` 中的 `RobotEar` 类。
|
||||
|
||||
### 3.2 👁️ 视觉感知 (YOLOv8)
|
||||
* **作用**: 识别桌面上的物体（如：削笔刀、盒子、零件）并定位其像素坐标。
|
||||
* **获取方法**: **需要训练** (Custom Training)。
|
||||
* **详细步骤**:
|
||||
1. **数据采集**:
|
||||
* 打开摄像头，拍摄你的桌面上不同摆放位置的物体图片（建议 100-300 张）。
|
||||
2. **数据标注**:
|
||||
* 使用 `LabelImg` 或 `Roboflow` 等工具进行标注。
|
||||
* 类别名称必须与可以被语音识别到的名称对应（如：`part`, `box` 等）。
|
||||
* *注意：本项目目前默认将所有目标映射为 `part` 进行抓取，但训练时建议区分不同类别。*
|
||||
3. **模型训练**:
|
||||
* 确保你安装了 `ultralytics`。
|
||||
* 准备 `data.yaml` 文件，指定 `train` 和 `val` 图片路径及类别名称。
|
||||
* 运行训练命令：
|
||||
```bash
|
||||
yolo detect train model=yolov8s.pt data=data.yaml epochs=100 imgsz=640
|
||||
```
|
||||
4. **模型部署**:
|
||||
* 训练完成后，会在 `runs/detect/train/weights/` 下生成 `best.pt`。
|
||||
* 将 `best.pt` 复制到项目根目录，并在 `voice_main.py` 中修改加载路径：`self.model = YOLO('best.pt')`。
|
||||
|
||||
### 3.3 🧠 逻辑大脑 (LLM + LoRA)
|
||||
* **作用**: 将自然语言（例如“把那个红色的块拿起来”）翻译成机器能读懂的 JSON 指令（`{"action": "pick", ...}`）。
|
||||
* **获取方法**: **基于开源大模型进行微调 (Fine-tuning)**。
|
||||
* **详细步骤**:
|
||||
1. **基座模型准备**:
|
||||
* 建议下载 Qwen1.5-1.8B, Llama-3-8B 或 ChatGLM3-6B 等适合本地运行的模型。
|
||||
2. **构建数据集**:
|
||||
* 参考项目中的 `robot_train.json` 文件。
|
||||
* 格式（Alpaca 格式）：
|
||||
```json
|
||||
[
|
||||
{
|
||||
"instruction": "向左移动一厘米",
|
||||
"input": "",
|
||||
"system": "你是机械臂JSON转换器...",
|
||||
"output": "[{\"action\": \"move_inc\", \"axis\": \"y\", \"value\": 10}]"
|
||||
}
|
||||
]
|
||||
```
|
||||
* 你需要编写大量类似的 "中文指令 -> JSON" 对照数据，覆盖抓取、移动、摇头等场景。
|
||||
3. **微调 (Fine-tuning)**:
|
||||
* 本项目集成了 **LLaMA-Factory** 框架（见 `LLaMA-Factory/` 目录）。
|
||||
* 使用 LLaMA-Factory 进行 LoRA 微调：
|
||||
```bash
|
||||
cd LLaMA-Factory
|
||||
# 示例微调命令 (需根据实际显存调整参数)
|
||||
llamafactory-cli train \
|
||||
--stage sft \
|
||||
--do_train \
|
||||
--model_name_or_path /path/to/base_model \
|
||||
--dataset robot_train \
|
||||
--template qwen \
|
||||
--finetuning_type lora \
|
||||
--output_dir ../saves/lora_adapter \
|
||||
--per_device_train_batch_size 4 \
|
||||
--gradient_accumulation_steps 4 \
|
||||
--lr_scheduler_type cosine \
|
||||
--logging_steps 10 \
|
||||
--save_steps 100 \
|
||||
--learning_rate 5e-5 \
|
||||
--num_train_epochs 5.0
|
||||
```
|
||||
4. **模型加载**:
|
||||
* 训练完成后，你将获得一个 LoRA 权重文件夹（如 `saves/lora_adapter`）。
|
||||
* 在 `voice_main.py` 的 `RobotBrain` 类中，将 `model_path` 指向你的 LoRA 文件夹路径（代码中默认为 `D:\lora\2`）。
|
||||
* *代码不仅加载了 LoRA，还通过 `AutoModelForCausalLM` 自动合并加载了基座模型（前提是 LoRA 的配置文件里记录了基座模型路径）。*
|
||||
|
||||
## 4. 运行与标定 (Run & Calibration)
|
||||
|
||||
1. **连接硬件**: 插入摄像头和机械臂 USB。
|
||||
2. **启动程序**:
|
||||
```bash
|
||||
python voice_main.py
|
||||
```
|
||||
3. **手眼标定 (Hand-Eye Calibration)**:
|
||||
* **无论摄像头怎么动，都需要重新标定**。
|
||||
* 在程序运行画面中，按下键盘 **`C`** 键进入标定模式。
|
||||
* 此时画面会提示依次点击 4 个点（左上、右上、右下、左下）。
|
||||
* 请用鼠标在画面中点击机械臂实际能够到达的这 4 个对应的矩形区域角点（对应机械臂坐标 `(90,90), (200,90), (200,-90), (90,-90)`）。
|
||||
* 点击完第 4 个点后，系统会自动计算变换矩阵，至此标定完成。
|
||||
|
||||
## 5. 使用方法
|
||||
* 按住 **空格键** 说话（如：“把那个零件拿起来”，“向左两厘米”）。
|
||||
* 松开空格键，机械臂将自动执行动作。
|
||||
* 更多快捷键和指令说明请参考 `使用说明书.md`。
|
||||
Loading…
Reference in a new issue