m1ngsama/robot_arm
1
0
Fork 0
mirror of https://github.com/m1ngsama/robot_arm.git synced 2026-03-25 19:53:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: rewrite README (bilingual) + restructure documentation

Browse source 
- README.md: comprehensive bilingual (CN+EN) rewrite
  Consolidates 使用说明书.md + 项目介绍文档.md into one document.
  Sections: overview, architecture, BOM, installation, quick start,
  voice commands, calibration, troubleshooting, technical notes,
  training reference, project structure.

- TRAINING.md: rename from lora.md; add bilingual header.
  Full QLoRA fine-tuning research notes preserved as-is.

- Delete: ck.md (dev journal), 使用说明书.md, 项目介绍文档.md
  All useful content merged into README.md.

- .gitignore: remove stale whitelist entries for deleted files.
This commit is contained in:
m1ngsama 2026-02-20 21:23:47 +08:00
parent 4eb716c8ad
commit 1d31dc5b96
6 changed files with 300 additions and 547 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored
View file

@ -45,7 +45,4 @@ temp_voice.wav
!voice_main.py !voice_main.py
!arm_main.py !arm_main.py
!whisper_main.py !whisper_main.py
!config.py !config.py
!项目介绍文档.md
!ck.md
!lora.md

472
README.md
View file

@ -1,200 +1,310 @@
# 🤖 智能语音具身智能机械臂 (Voice-Controlled Embodied AI Robot Arm) # 智能语音机械臂 / Voice-Controlled Robot Arm
> 🚀 **桌面级具身智能 (Embodied AI) 最佳实践**：构建“耳-脑-眼-手”全链路闭环控制系统。 基于"耳-脑-眼-手"全链路闭环的具身智能系统，运行于消费级硬件，完全离线。
本项目实现了一套运行在消费级笔记本（RTX 3060, 6GB）上的**全栈离线具身智能系统**。通过多模态模型融合，打通了从自然语言到物理动作的最后壁垒： *A full-stack embodied AI system — voice in, physical action out — running entirely offline on consumer hardware.*
* **听 (Listen)**：集成 **Faster-Whisper**，支持抗噪中文语音指令输入；
* **想 (Think)**：部署微调后的 **DeepSeek/Qwen 大语言模型**，具备极强的复杂语义理解与逻辑推理能力；
* **看 (See)**：结合 **YOLOv8 机器视觉** 与单应性矩阵手眼标定，实现亚毫米级目标定位；
* **动 (Act)**：自研 **D-H 逆运动学** 求解器与平滑轨迹规划算法，精准驱动机械臂执行抓取、搬运等任务。
无需联网，低成本复刻，满足边缘计算与隐私安全需求。
> **关键词**: `Embodied AI`, `Robot Arm`, `Voice Control`, `LLM`, `DeepSeek`, `YOLOv8`, `Whisper`, `Fine-tuning`, `Inverse Kinematics`
## ✨ 项目亮点
* **👂 听 (Listen)**: 使用 **Faster-Whisper** 进行本地语音识别，支持抗噪与谐音纠错。
* **🧠 想 (Think)**: 基于 **DeepSeek/Qwen** 大模型微调 (LoRA)，将自然语言能够解析为结构化的 JSON 动作指令。
* **👁️ 看 (Look)**: 结合 **YOLOv8** 视觉识别与手眼标定系统，实现精准的物体定位。
* **💪 动 (Move)**: 自研 **D-H 逆运动学算法** 与 S-Curve 速度规划，保证机械臂在 ESP32 控制下的平滑运动。
--- ---
## 🛠️ 技术栈总览 ## 系统简介 / Overview
| 模块 | 技术方案 | 作用 | | 能力 | 实现 | Capability |
| :--- | :--- | :--- | |:---|:---|:---|
| **语音识别** | **Faster-Whisper** (Base) | 离线语音转文本，支持流式输入 | | **听** | Faster-Whisper，本地中文语音识别 | Speech-to-text (Chinese, local) |
| **语义理解** | **LLM (DeepSeek/Qwen) + LoRA** | 指令意图解析，泛化复杂语序 | | **想** | DeepSeek-R1-1.5B + QLoRA 微调，自然语言→JSON | LLM + rule engine, NL→JSON actions |
| **视觉感知** | **YOLOv8s** + OpenCV | 目标检测与坐标映射 (Homography) | | **看** | YOLOv8s 目标检测 + 单应性矩阵手眼标定 | Object detection + hand-eye calibration |
| **运动控制** | **Python (IK)** + **ESP32 (C++)** | 逆解算与底层 PWM 舵机驱动 | | **动** | D-H 逆运动学 + S-Curve 轨迹规划，ESP32 驱动 | IK solver + smooth trajectory → ESP32 PWM |
| **训练框架** | **LLaMA-Factory** | 高效微调大模型指令跟随能力 |
硬件总成本 **¥317**，GPU 需求 RTX 3060 6GB（推理 <4GB 显存，延迟 <200ms）。
*Total hardware cost ¥317 (~$45 USD). Requires an NVIDIA GPU for LLM inference.*
--- ---
# 📖 项目复刻指南 (Replication Guide) ## 系统架构 / Architecture
本指南详细介绍了如何从零开始复刻本项目，包括硬件准备、环境搭建、以及**最关键的三个AI模型（语音、视觉、大脑）的获取与训练方法**。 ```
麦克风 / Microphone
## 1. 硬件准备 (Hardware) │
▼
### 1.1 项目物料清单 (BOM) & 成本 ┌──────────────────┐
│ Faster-Whisper │ 语音识别 (STT) — 中文语音 → 文本
本项目硬件成本极低，总花费约 **¥317**。以下是基于实际采购发票的详细清单： └────────┬─────────┘
│ "把削笔刀抬起5厘米"
| 序号 | 物品名称 | 规格/型号 | 数量 | 单价 (CNY) | 总费用 (CNY) | 备注 | ▼
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | ┌──────────────────┐
| 1 | 3D打印机械臂 | 教具/机械臂 (散件) | 1 个 | 71.00 | 71.00 | 包含亚克力/PLA结构件 | │ 规则解析引擎 │ 简单指令直接匹配（松开 / 复位 / 方向移动）
| 2 | ESP32开发板 | WiFi+蓝牙双核 MCU | 1 件 | 18.71 | 18.71 | 主控核心 | │ (Regex engine) │ 命中 → 直接生成 JSON，跳过 LLM
| 3 | ESP32配件 | (接插件/扩展板) | 1 件 | 4.55 | 4.55 | 辅助连接 | └────────┬─────────┘
| 4 | 工业摄像头 | USB免驱 / 广角 | 1 个 | 61.00 | 61.00 | 机器视觉输入 | │ 未命中（含物体名的复杂指令）
| 5 | 数字舵机 | MG996R (金属齿轮) | 5 个 | 26.54 | 132.70 | 大扭矩驱动 | ▼
| 6 | 稳压电源 | 6V 6A | 1 个 | 29.00 | 29.00 | 舵机供电 | ┌──────────────────┐
| **总计** | | | | | **¥316.96** | **高性价比** | │ DeepSeek-R1-1.5B │ QLoRA 微调推理
│ (QLoRA, FP16) │ 自然语言 → 结构化 JSON 指令
### 1.2 硬件连接说明 └────────┬─────────┘
│ [{"action": "lift", "target": "part", "height": 50}]
### 1.2 硬件连接说明 ▼
┌──────────────────┐
* **机械臂**: 也就是本项目中的 `RobotArmUltimate`。 │ YOLOv8s │ 实时检测目标物体
* 要求：支持串口通信（Serial），使用标准舵机控制协议。 │ + Homography │ 像素坐标 → 机械臂工作坐标 (mm)
* 连接：USB连接电脑，需确认串口号（代码默认为 `COM3`，请在 `arm_main.py` 或 `voice_main.py` 中修改）。 └────────┬─────────┘
* **摄像头**: USB免驱网络摄像头。 │ (rx=170, ry=3)
* 安装位置：固定在机械臂前方或上方，确保能覆盖工作台面。 ▼
* **麦克风**: 任意USB麦克风或电脑内置麦克风。 ┌──────────────────┐
* **计算设备**: 建议配备 NVIDIA 显卡的 Windows/Linux 电脑（用于加速 YOLO 和 LLM 推理）。 │ 运动控制引擎 │ D-H 逆运动学 + S-Curve 插值
│ arm_main.py │ 平滑轨迹 → 串口 → ESP32 → 舵机
### 1.3 固件烧录 (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 模块，请分别按照以下步骤准备。 ## 硬件清单 / Bill of Materials
### 3.1 👂 语音听觉 (Whisper) 总计 **¥317** / ~$45 USD
* **作用**: 将你的语音指令转为文字。
* **获取方法**:
* **无需训练**。代码使用了 OpenAI 的 `whisper` 模型。
* 首次运行时，程序会自动下载模型权重（如 `base` 或 `small` 模型）。
* 代码位置：`whisper_main.py` 中的 `RobotEar` 类。
### 3.2 👁️ 视觉感知 (YOLOv8) | # | 物品 | 规格 | 数量 | 单价 | 合计 |
* **作用**: 识别桌面上的物体（如：削笔刀、盒子、零件）并定位其像素坐标。 |:--|:---|:---|:--:|---:|---:|
* **获取方法**: **需要训练** (Custom Training)。 | 1 | 3D 打印机械臂（散件） | 教具级，含亚克力/PLA 结构件 | 1 | ¥71 | ¥71 |
* **详细步骤**: | 2 | ESP32 开发板 | WiFi+蓝牙双核 MCU | 1 | ¥19 | ¥19 |
1. **数据采集**: | 3 | ESP32 配件 | 接插件/扩展板 | 1 | ¥5 | ¥5 |
* 打开摄像头，拍摄你的桌面上不同摆放位置的物体图片（建议 100-300 张）。 | 4 | USB 工业摄像头 | 免驱，广角，1280×720 | 1 | ¥61 | ¥61 |
2. **数据标注**: | 5 | 数字舵机 MG996R | 金属齿轮，高扭矩 | 5 | ¥27 | ¥133 |
* 使用 `LabelImg` 或 `Roboflow` 等工具进行标注。 | 6 | 稳压电源 | 6V 6A，舵机专用 | 1 | ¥29 | ¥29 |
* 类别名称必须与可以被语音识别到的名称对应（如：`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) **硬件连接 / Wiring**
* **作用**: 将自然语言（例如“把那个红色的块拿起来”）翻译成机器能读懂的 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) - **ESP32 串口引脚**：X→14, Y→4, Z→5, B→18, 夹爪→23
- **电源**：舵机与 ESP32 分开供电（外部 6V/6A），防浪涌
- **摄像头**：USB，固定于机械臂前方，覆盖整个工作台面
- **串口**：USB 连接 ESP32，默认 `COM3`，可通过环境变量 `ROBOT_PORT` 修改
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. 使用方法 ## 安装 / Installation
* 按住 **空格键** 说话（如：“把那个零件拿起来”，“向左两厘米”）。
* 松开空格键，机械臂将自动执行动作。 ### 1. 烧录固件 / Flash Firmware
* 更多快捷键和指令说明请参考 `使用说明书.md`。
Arduino IDE 2.x，开发板选 "ESP32 Dev Module"：
```bash
# 打开 main.ino，选择正确串口，上传
# Open main.ino, select port, Upload
```
### 2. Python 环境 / Python Setup
Python 3.10+，CUDA 11.8 或 12.x（推荐）。
```bash
# 1. PyTorch（先去 pytorch.org 选对应 CUDA 版本）
# Visit pytorch.org to install the correct CUDA build first
# 2. 其余依赖 / Other dependencies
pip install -r requirements.txt
```
### 3. 配置 / Configure
所有可调参数集中在 `config.py`，支持环境变量覆盖：
```bash
# 修改串口（Windows COM 号 / Linux /dev/ttyUSB0）
# Change serial port
ROBOT_PORT=COM5 python voice_main.py
# 修改模型路径 / Change model paths
LLM_MODEL_PATH=D:\models\my_lora python voice_main.py
YOLO_MODEL_PATH=runs/best.pt python voice_main.py
```
默认值见 `config.py`，无需修改代码。
*Default values are in `config.py`; no code changes needed for standard tuning.*
### 4. 模型准备 / Models
**语音 (Whisper)**：无需准备，首次运行自动下载 `base` 模型。
*Auto-downloaded on first run.*
**视觉 (YOLO)**：需自行训练，50 张样本即可迁移学习：
```bash
# 用 LabelImg 或 Roboflow 标注你的物体，然后：
yolo detect train model=yolov8s.pt data=data.yaml epochs=100 imgsz=640
# 产出 runs/detect/train/weights/best.pt → 复制到项目根目录
# Copy runs/detect/train/weights/best.pt to project root
```
**大模型 (LLM)**：需要对 DeepSeek-R1-1.5B 或 Qwen1.5-1.8B 进行 LoRA 微调。
*Requires LoRA fine-tuning. See [`TRAINING.md`](TRAINING.md) for the complete guide.*
训练数据格式（Alpaca）：
```json
{
"instruction": "把削笔刀抬起5厘米",
"input": "",
"system": "你是机械臂JSON转换器...",
"output": "[{\"action\": \"lift\", \"target\": \"part\", \"height\": 50}]"
}
```
---
## 快速上手 / Quick Start
```bash
python voice_main.py
```
启动后依次加载：机械臂串口 → YOLO 模型 → Whisper → LLM，弹出摄像头窗口。
*On startup: serial → YOLO → Whisper → LLM → camera window.*
**键盘快捷键 / Keyboard Shortcuts**
| 按键 | 功能 | Function |
|:---|:---|:---|
| **SPACE（按住）** | 录音，松开即识别 | Hold to record, release to recognize |
| **C** | 进入 / 退出手眼标定模式 | Toggle hand-eye calibration mode |
| **R** | 手动复位到原始姿态 | Manual reset to home position |
| **O** | 强制张开夹爪 | Force open gripper |
| **Q** | 退出程序 | Quit |
---
## 语音指令 / Voice Commands
所有指令用普通中文说话即可，无需特殊格式。
*Speak natural Chinese. No special syntax required.*
**抓取与搬运（需视觉定位）**
```
"把削笔刀抓起来"
"抓住那个盒子"
"把削笔刀抬起5厘米"
"将零件举高10公分"
```
**空间运动控制（精确移动）**
```
"向上三厘米" → Z 轴 +30mm
"向左移动四毫米" → Y 轴 +4mm
"往前伸10厘米" → X 轴 +100mm
```
**模糊移动**（不指定数值，默认 5cm）
```
"向左" "抬起" "往下"
```
**动作交互**
```
"点头" → 当前位置上下往复 3 次（幅度 3cm）
"摇头" → 当前位置左右往复 3 次（幅度 3cm）
"放下" → 降至桌面高度（Z=-15mm）并松开夹爪
"复位" → 回到初始安全姿态 [120, 0, 60] mm
"松开" → 张开夹爪，不移动
```
**语音兼容性**
系统内置谐音纠错：`"零米"→"厘米"`, `"小笔刀"→"削笔刀"`, `"电头"→"点头"` 等。
*Built-in homophone correction for common Whisper mishearings.*
---
## 手眼标定 / Hand-Eye Calibration
摄像头移动后必须重新标定。按 **C** 键进入标定模式：
```
依次点击 4 个角点 / Click 4 corner points in order:
P1 (左上) ←→ 机械臂坐标 (90, 90)
P2 (右上) ←→ 机械臂坐标 (200, 90)
P3 (右下) ←→ 机械臂坐标 (200, -90)
P4 (左下) ←→ 机械臂坐标 (90, -90)
```
点完第 4 个点后，单应性矩阵立即更新，无需重启。
*Homography matrix updates instantly after the 4th click. No restart needed.*
---
## 故障排除 / Troubleshooting
| 现象 | 原因 | 解决 |
|:---|:---|:---|
| 按空格无反应 | 窗口焦点不在摄像头画面 | 点击一下摄像头窗口 |
| 语音识别乱码 | 麦克风噪声 / 语速过快 | 安静环境，语速适中，按住空格 0.5s 再说话 |
| "未找到目标" | YOLO 未检测到物体 | 调整物体角度、光照；检查物体是否在训练类别中 |
| 抓取位置偏离 | 摄像头被移动 | 按 **C** 重新四点标定 |
| 无法连接串口 | ESP32 未插入 / 端口号不对 | 检查设备管理器，修改 `ROBOT_PORT` 环境变量 |
| 机械臂启动剧烈抖动 | 五路舵机同时上电浪涌 | 已在固件中处理（阶梯式上电），若仍出现检查电源容量 |
---
## 核心技术要点 / Technical Notes
以下是开发过程中解决的关键工程问题，供复刻者参考。
**D-H 逆运动学**
长度 130mm 的 L4 连杆导致几何解析法在水平移动时产生 40° 轨迹偏移。最终采用 Scipy SLSQP 数值优化器，加入 `Pitch=-90°` 姿态约束（抓手始终垂直地面），彻底解决非线性偏移。
*The 130mm L4 link caused ~40° path deviation with geometric IK. Solved by Scipy SLSQP numerical optimization with a Pitch=-90° constraint (end-effector always perpendicular to table).*
**S-Curve + 多层减震**
MG996R 在长力臂下惯性震动严重。减震流水线：倾斜补偿 → 移动平均滤波（deque）→ 速度限制 → EMA 阻尼 → 死区过滤。
*MG996R servos vibrate badly with a long lever arm. Solution: 5-layer damping pipeline — tilt correction → moving average (deque) → speed cap → EMA damping → dead-zone filter.*
**双通道解析架构**
简单指令（松开、复位、方向移动）走正则规则引擎，微秒级响应，且避免大模型将"向下三厘米"误判为 `lift`。只有含物体名的复杂指令才交给 LLM（延迟 <200ms）。
*Simple commands (release/reset/directional) bypass the LLM entirely via a regex engine (microseconds). Complex commands with object names go to the LLM (<200ms). This prevents the common failure mode of "move down 3cm" being misclassified as a lift action.*
**Pre-filling 截断**
DeepSeek-R1 的推理模型默认会输出思维链（`<think>...</think>`）。通过手动追加 `<｜Assistant｜>` 标签进行 Pre-filling，强制模型跳过思考过程直接输出 JSON，实现 100% 格式遵循率。
*DeepSeek-R1 defaults to outputting a chain-of-thought. Pre-filling with `<｜Assistant｜>` forces the model to skip the thinking phase and output JSON directly, achieving 100% format compliance.*
**Whisper 反幻觉**
三道防线：① 音频首尾静音裁剪；② `condition_on_previous_text=False`；③ 重复模式正则检测（去除"向右向右向右..."类幻觉）。
**工程坑：System Prompt 对齐**
训练与推理的 System Prompt 必须完全一致，否则模型输出偏移（如输出 500mm 而非 50mm）。已在代码注释中标注警告。
---
## 大模型训练 / LLM Training
约 500 条领域数据，QLoRA 微调 DeepSeek-R1-1.5B，Loss 收敛至 0.0519，格式错误率 0%。
完整训练流程见 [`TRAINING.md`](TRAINING.md)，包括：QLoRA 超参数配置、GGUF vs Transformers 方案对比、Pre-filling 推理方案详解、实验结果。
---
## 项目结构 / Project Structure
```
robot_arm/
├── README.md 本文档 / This file
├── TRAINING.md 大模型 LoRA 微调研究笔记 / LLM fine-tuning notes
├── requirements.txt Python 依赖 / Dependencies
├── config.py 硬件与运动参数（支持环境变量覆盖）/ Hardware & motion constants
│
├── main.ino ESP32 固件，LEDC PWM 舵机控制 / ESP32 firmware
├── arm_main.py 机械臂运动学核心：D-H IK + S-Curve / Kinematics & control
├── whisper_main.py 语音识别封装 / ASR wrapper
└── voice_main.py 主程序：语音→LLM→视觉→控制 / Main app orchestrator
```
---
## 关键数据 / Key Specs
| 指标 | 值 |
|:---|:---|
| 硬件成本 | ¥317 |
| GPU 需求 | RTX 3060 6GB（推理 <4GB 显存） |
| 推理延迟 | <200ms（LLM），<50ms（规则引擎） |
| 训练数据量 | ~500 条 |
| 格式错误率 | 0% |
| 运行模式 | 完全离线 / Fully offline |

8
lora.md → TRAINING.md
View file

@ -1,3 +1,11 @@
# 大模型训练笔记 / LLM Fine-Tuning Notes
> DeepSeek-R1-1.5B + QLoRA 微调，实现机械臂指令解析 · ~500 条数据 · Loss 0.0519 · 格式错误率 0%
>
> *QLoRA fine-tuning of DeepSeek-R1-1.5B for robot arm command parsing. ~500 samples, loss 0.0519, 0% format error rate.*
---
# 基于 DeepSeek-R1-1.5B 微调的轻量级具身智能指令解析系统研究 # 基于 DeepSeek-R1-1.5B 微调的轻量级具身智能指令解析系统研究
## 1. 项目背景与摘要 (Abstract) ## 1. 项目背景与摘要 (Abstract)

77
ck.md
View file

@ -1,77 +0,0 @@
根据我们的全部聊天记录，我为你复盘并总结了整个项目的开发全过程。这个过程记录了你如何从零开始，一步步解决硬件抖动、数学建模错误、视觉偏差、以及大模型理解力不足等核心问题，最终实现了一个能够“听得懂指令、看得见物体、抓得准目标”的具身智能系统。
---
# 具身智能机械臂系统开发全过程总结
## 一、 硬件基础与底层调优 (Hardware Foundation)
这是项目的第一阶段，重点在于打通 ESP32 对 MG996R 大功率舵机的稳定控制。
* **技术栈**：ESP32-WROOM-32, MG996R 舵机, 6V 6A 外部直流电源。
* **遇到的问题与迭代**：
1. **引脚冲突**：发现 D2 引脚连通蓝灯且作为启动配置脚，导致底座舵机初始化失败；D19 等引脚在多轴联动时失效。
* **解决**：重新分配引脚（X:14, Y:4, Z:5, B:18, G:23/13），避开冲突。
2. **掉电重启 (Brownout)**：5 个舵机同时启动产生的浪涌电流导致 ESP32 电压跌落，蓝灯熄灭死机。
* **解决**：编写**阶梯式上电代码**，让电机按顺序间隔 0.5s~1.5s 依次激活；并在软件中临时禁用 Brownout 探测器。
3. **硬件极性反向**：发现不同关节的舵机安装方向不一致（顺时针 vs 逆时针）。
* **解决**：在驱动层建立逻辑映射，对小臂（Z）和手腕（B）采用**互补数映射**（`180 - 角度`），统一了数学模型与物理执行。
## 二、 运动学建模的演进 (Kinematics Evolution)
这是项目最核心的数学攻坚阶段，解决了“爪尖走斜线”的毕设难题。
* **技术迭代路径**：
1. **初级阶段 (几何解析法)**：尝试用简单的三角函数加减法。
* **失败表现**：由于 L4 (130mm) 极长，手腕补偿跟不上，控制 X 轴移动时，爪尖走出了 40 度的斜坡。
2. **进阶阶段 (解析公式法)**：参考手写笔记进行 $K_1, K_2$ 矢量分解。
* **失败表现**：模型与物理零位有 90 度相位差，导致坐标系定义混乱。
3. **终极阶段 (D-H 参数建模 + 数值解法)**：
* **建模**：建立了标准 **D-H 参数表**，定义 90 度为“笔直向天”姿态（坐标 0,0,315）。
* **算法**：舍弃死板公式，采用 **Scipy 的数值优化器 (SLSQP)**。通过最小化目标点与当前点的欧氏距离，自动寻找最优舵机解。
* **姿态锁定**：在解算中加入 `Pitch=-90` 约束，强制让长达 13cm 的抓手垂直地面，从而彻底**消除了非线性路径偏移，实现了完美的水平直线移动**。
## 三、 视觉感知与手眼标定 (Perception & Calibration)
让机械臂拥有“空间感”，将摄像头画面的像素点转化为物理坐标。
* **关键技术**：
1. **目标检测**：从 `YOLO-World`（开放词汇）切换到**自定义训练的 YOLOv8s**。
* **优化**：针对特定目标（销笔刀/零件）采集 50 张样本进行迁移学习，识别率从“忽隐忽现”提升到 90% 以上。
2. **手眼标定**：采用**单应性矩阵 (Homography)**。
* **交互式标定**：实现了按 `C` 键在视频窗口点击 4 个参考点（P1-P4）即可实时更新矩阵的功能，解决了摄像头移位导致的精度丢失。
3. **镜像修正**：针对 USB 摄像头水平镜像问题，采用 `cv2.flip` 翻转，并配合数学修正公式 `ry = Center*2 - ry_raw` 确保画面动作与物理方向完全一致。
## 四、 认知层：语义理解与减震优化 (Intelligence & Refinement)
实现“具身智能”，让机械臂能理解人类指令并优雅地执行。
* **多模态技术**：
1. **语音识别 (STT)**：使用本地 **Faster-Whisper (Base)**。
* **迭代**：从固定时长录音改为**按空格开始/结束录音**，并加入 `initial_prompt` 关键词引导，解决了识别出乱码（“轻轻轻轻”）的问题。
2. **语义解析 (LLM)**：通过 **Ollama** 部署 **DeepSeek-R1-1.5B**。
* **提示词工程**：使用 **Few-Shot Prompting**（少样本提示），让模型学会“销笔刀 -> box -> robot”的标签转换，并自动计算“厘米到毫米”的单位换算。
3. **减震系统 (Damping System)**：
* 针对 MG996R 剧烈震动，实现了 **S-Curve (余弦插值)** 轨迹规划。
* 引入 **EMA 移动平均滤波** 和 **阻尼系数**，实现了“慢起、匀移、慢停”，极大减轻了长力臂带来的惯性晃动。
## 五、 项目最终形态 (Final Integration)
最终代码集成了以下功能流：
1. **启动**：摄像头实时预览，显示标定红圈、中心基准及目标坐标。
2. **标定**：按 `C` 交互式重标，确保精度。
3. **交互**：空格触发录音，大模型解析意图输出 JSON 列表。
4. **执行**：
* **Pick**：视觉定位后，执行“预备-下潜-抓取-提起”平滑序列。
* **Move_inc**：基于坐标记忆，实现“向上提5cm”等增量操作。
---
## 项目技术总结表
| 模块 | 关键技术 | 解决的毕设难题 |
| :--- | :--- | :--- |
| **控制层** | 32位 PWM / 阶梯启动 / 互补数映射 | 解决大功率电机掉电、死机及极性相反问题 |
| **算法层** | D-H 参数建模 / 数值逆解 (IK) | 解决 L4 长连杆引起的轨迹非线性斜移 |
| **规划层** | S-Curve 插值 / EMA 滤波器 | 解决廉价舵机在长力臂下的剧烈震动 |
| **感知层** | YOLOv8 / Homography / 交互标定 | 解决从图像像素到物理空间的精准映射 |
| **认知层** | Faster-Whisper / DeepSeek / 正则解析 | 解决非结构化自然语言到机器人动作的映射 |
---
**总结结论**：本项目通过**“硬件补偿+数学建模+深度学习”**的多层深度耦合，将一台由普通 3D 打印件和廉价舵机组成的机械臂，提升到了具备**高精度轨迹跟踪**和**语义智能交互**能力的工业级原型水平。

101
使用说明书.md
View file

@ -1,101 +0,0 @@
# 机械臂语音控制系统使用指南 v1.0
## 一、系统简介
本系统是一套基于多模态大模型的具身智能控制方案，能够让用户通过**自然语言**直接指挥机械臂完成抓取、搬运、运动控制等任务。系统集成了 Whisper 语音识别、DeepSeek 语义理解、YOLOv8 视觉定位以及自动化运动控制算法。
---
## 二、快速开始
### 2.1 启动程序
1. **硬件准备**：插入 USB 摄像头，连接 ESP32 控制板（请确保已烧录 `main.ino` 固件，其串口默认为 COM3）。
2. **运行命令**：在终端输入：
```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 产生的"向右向右向右"等重复幻觉。
- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。

184
项目介绍文档.md
View file

@ -1,184 +0,0 @@
# 基于多模态融合的具身智能机械臂控制系统
## 一、项目概述
本项目构建了一套完整的**具身智能（Embodied AI）机械臂控制系统**，实现了"语音下达指令 → 大模型语义解析 → 视觉定位目标 → 机械臂精准执行"的全链路闭环。系统在消费级硬件（RTX 3060 Laptop, 6GB 显存）上完成全部推理，无需联网，满足边缘部署需求。
### 核心能力
| 能力 | 描述 |
|:---|:---|
| **听** | 本地语音识别（Faster-Whisper），实时将中文语音转文本 |
| **想** | 微调大模型（DeepSeek-R1-1.5B + QLoRA），将自然语言解析为结构化 JSON 指令 |
| **看** | 目标检测（YOLOv8s）+ 单应性矩阵标定，像素坐标精准映射到机械臂坐标系 |
| **动** | D-H 运动学建模 + S-Curve 轨迹规划，实现平滑、无抖动的机械臂运动 |
---
## 二、系统架构
```
语音输入 (麦克风)
│
▼
┌──────────────────┐
│ Faster-Whisper │ 语音识别 (STT)
│ (Base, CUDA) │ 中文语音 → 文本
└────────┬─────────┘
│ "把削笔刀抬起5厘米"
▼
┌──────────────────┐
│ 规则解析引擎 │ 简单指令直接匹配（松开/复位/方向移动）
│ (正则匹配) │ ──命中──→ 直接生成 JSON
└────────┬─────────┘
│ 未命中（含物体名的复杂指令）
▼
┌──────────────────┐
│ DeepSeek-R1-1.5B │ 微调大模型推理
│ (QLoRA微调+FP16) │ 自然语言 → JSON 指令
└────────┬─────────┘
│ [{"action": "lift", "target": "part", "height": 50}]
▼
┌──────────────────┐
│ YOLOv8s 目标检测 │ 实时检测目标物体位置
│ + 单应性矩阵标定 │ 像素坐标 → 机械臂坐标
└────────┬─────────┘
│ 目标坐标 (rx=170, ry=3)
▼
┌──────────────────┐
│ 运动控制引擎 │ D-H 逆运动学 + S-Curve 插值
│ (ESP32 + MG996R) │ 平滑轨迹规划 → 舵机执行
└──────────────────┘
```
---
## 三、核心技术详解
### 3.1 语音识别 — Faster-Whisper
- **模型**：Faster-Whisper Base，CUDA FP16 加速
- **交互方式**：按住空格键录音，松开后识别
- **反幻觉优化**：
- 音频首尾静音裁剪，过滤空白段触发的重复幻觉
- 设置 `condition_on_previous_text=False`，防止上下文依赖导致的"向右向右向右..."循环
- 后处理纠错引擎：谐音修正（"零米"→"厘米"、"小笔刀"→"削笔刀"）+ 重复模式检测与去除
### 3.2 语义解析 — 微调大模型 + 规则引擎双通道
#### 微调大模型
| 项目 | 详情 |
|:---|:---|
| **基座模型** | DeepSeek-R1-Distill-Qwen-1.5B |
| **微调方法** | QLoRA（4-bit NF4 量化训练，FP16 推理） |
| **训练框架** | LLaMA-Factory |
| **训练数据** | ~500 条垂直领域样本（中文指令 → JSON） |
| **训练结果** | Loss 收敛至 0.0519，格式错误率 0% |
| **推理延迟** | < 200ms (RTX 3060) |
| **显存占用** | < 4GB (FP16) |
**关键技术点**：
1. **Prompt 对齐**：推理时的 System Prompt 必须与训练数据完全一致，否则模型输出偏移
2. **Pre-filling 截断**：手动追加 `<｜Assistant｜>` 标签，跳过模型的思考链（CoT），直接输出 JSON
3. **确定性解码**：`do_sample=False` 贪婪搜索，确保相同输入永远产生相同输出
#### 规则解析引擎（前置拦截）
对简单指令（纯方向移动/松开/复位）直接走**正则匹配**，不经过大模型：
- 避免模型将"向下三厘米"误判为 `lift`
- 响应更快（微秒级 vs 毫秒级）
- 只有包含物体名称的复杂指令（如"把削笔刀抬起5厘米"）才交给大模型处理
### 3.3 视觉感知 — YOLOv8 + 手眼标定
| 项目 | 详情 |
|:---|:---|
| **检测模型** | YOLOv8s（自定义训练，50 张样本迁移学习） |
| **空间映射** | 单应性矩阵（Homography），4 点标定 |
| **交互标定** | 按 `C` 键实时点击标定点，支持摄像头移位后重新校准 |
| **镜像修正** | `cv2.flip` + 数学补偿公式 $r_y = C_{center} \times 2 - r_{y_{raw}}$ |
### 3.4 运动控制 — D-H 建模 + 减震系统
| 项目 | 详情 |
|:---|:---|
| **运动学** | D-H 参数建模 + Scipy SLSQP 数值逆解 |
| **姿态约束** | Pitch = -90°，强制抓手垂直地面 |
| **轨迹规划** | S-Curve 余弦插值（慢起 → 匀移 → 慢停） |
| **信号滤波** | EMA 移动平均 + 阻尼系数，抑制长力臂惯性震动 |
| **硬件适配** | 阶梯式上电（防浪涌）、互补数映射（统一电机极性） |
### 3.5 硬件平台
| 组件 | 型号/规格 |
|:---|:---|
| **主控** | ESP32-WROOM-32 |
| **舵机** | MG996R × 5（大扭矩金属齿轮） |
| **电源** | 6V / 6A 外部直流电源 |
| **GPU** | NVIDIA RTX 3060 Laptop (6GB VRAM) |
| **摄像头** | USB 广角摄像头 (1280×720) |
---
## 四、技术栈总览
```
┌─────────────────────────────────────────────────┐
│ 应用层 │
│ voice_main.py（主程序） │
│ 语音交互 · 指令调度 · 状态管理 │
├────────────┬────────────┬───────────┬────────────┤
│ 语音识别 │ 语义解析 │ 视觉感知 │ 运动控制 │
│ │ │ │ │
│ Faster- │ DeepSeek │ YOLOv8s │ D-H IK │
│ Whisper │ R1-1.5B │ + Homog- │ + S-Curve │
│ (Base) │ (QLoRA) │ raphy │ + EMA │
│ │ + 规则引擎 │ │ │
├────────────┴────────────┴───────────┴────────────┤
│ 框架层 │
│ PyTorch · Transformers · OpenCV · Ultralytics │
│ SoundDevice · Scipy · NumPy │
├──────────────────────────────────────────────────┤
│ 硬件层 │
│ RTX 3060 (CUDA) · ESP32 · MG996R · USB Camera │
└──────────────────────────────────────────────────┘
```
---
## 五、指令支持与示例
| 语音指令 | 解析结果 (JSON) | 执行动作 |
|:---|:---|:---|
| "把削笔刀抬起5厘米" | `[{"action":"lift","target":"part","height":50}]` | 视觉定位 → 抓取 → 抬起 50mm |
| "向左移动3厘米" | `[{"action":"move_inc","axis":"y","value":30}]` | Y 轴正方向移动 30mm |
| "向下移动2厘米" | `[{"action":"move_inc","axis":"z","value":-20}]` | Z 轴负方向移动 20mm |
| "松开" | `[{"action":"release"}]` | 张开夹爪 |
| "回到原位" | `[{"action":"reset"}]` | 复位至初始姿态 |
---
## 六、关键问题与解决方案
| 问题 | 原因 | 解决方案 |
|:---|:---|:---|
| 舵机上电瞬间 ESP32 死机 | 5 路电机同时启动，浪涌电流导致掉电 | 阶梯式上电，间隔 0.5~1.5s 依次激活 |
| 机械臂移动轨迹走斜线 | 长连杆 (L4=130mm) 导致非线性偏移 | D-H 建模 + Pitch=-90° 姿态约束 + 数值逆解 |
| 机械臂剧烈抖动 | MG996R 响应过快 + 长力臂惯性 | S-Curve 插值 + EMA 滤波 + 阻尼系数 |
| Whisper 输出"向右向右向右..." | 静音段触发重复幻觉 | 音频裁剪 + `condition_on_previous_text=False` + 后处理去重 |
| "向下三厘米"被模型解析为 lift | 模型泛化不足，混淆方向移动与抬起 | 规则引擎前置拦截简单指令 |
| Ollama 推理输出废话/思维链 | GGUF 模板对齐失败 | 改用原生 Transformers + Pre-filling 截断 |
| 5 厘米输出 500 而非 50 | 推理 Prompt 与训练 Prompt 不一致 | 严格对齐 System Prompt |
---
## 七、项目结论
本项目通过**"硬件补偿 + 数学建模 + 深度学习"**的多层深度耦合，在消费级硬件上实现了完整的具身智能系统：
1. **数据质量 > 模型规模**：仅 500 条高质量训练数据，1.5B 小模型即可在垂直领域达到 100% 格式遵循率
2. **双通道解析架构**：规则引擎处理简单指令（快速、确定性），大模型处理复杂指令（灵活、语义理解），兼顾速度与智能
3. **全栈离线运行**：语音识别、语义解析、视觉检测、运动控制全部在本地完成，显存占用 < 4GB，满足边缘部署需求
4. **工程鲁棒性**：从硬件防浪涌、舵机减震到语音去幻觉，每一层都有针对性的容错机制