mirror of
https://github.com/m1ngsama/robot_arm.git
synced 2026-03-26 04:03:49 +00:00
147 lines
7.1 KiB
Markdown
147 lines
7.1 KiB
Markdown
# 项目复刻指南 (Replication Guide)
|
||
|
||
本指南详细介绍了如何从零开始复刻“智能语音机械臂”项目，包括硬件准备、环境搭建、以及**最关键的三个AI模型（语音、视觉、大脑）的获取与训练方法**。
|
||
|
||
## 1. 硬件准备 (Hardware)
|
||
|
||
* **机械臂**: 也就是本项目中的 `RobotArmUltimate`。
|
||
* 要求：支持串口通信（Serial），使用标准舵机控制协议。
|
||
* 连接：USB连接电脑，需确认串口号（代码默认为 `COM3`，请在 `arm_main.py` 或 `voice_main.py` 中修改）。
|
||
* **摄像头**: USB免驱网络摄像头。
|
||
* 安装位置：固定在机械臂前方或上方，确保能覆盖工作台面。
|
||
* **麦克风**: 任意USB麦克风或电脑内置麦克风。
|
||
* **计算设备**: 建议配备 NVIDIA 显卡的 Windows/Linux 电脑（用于加速 YOLO 和 LLM 推理）。
|
||
|
||
### 1.1 固件烧录 (Firmware)
|
||
本项目包含下位机控制代码 `main.ino`，适用于 ESP32 开发板。
|
||
* **开发环境**: Arduino IDE 2.x
|
||
* **开发板管理器**: ESP32 by Espressif Systems (建议版本 3.0.0+)
|
||
* **烧录步骤**:
|
||
1. 使用 USB 数据线连接 ESP32 到电脑。
|
||
2. 打开 `main.ino` 文件。
|
||
3. 选择开发板型号（如 "ESP32 Dev Module"）和端口。
|
||
4. 上传代码。
|
||
5. 记下端口号（如 `COM3`），后续需在 `voice_main.py` 中配置。
|
||
|
||
## 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`。
|