From eaa8b9a1325baa19333a13127838b583ab895d66 Mon Sep 17 00:00:00 2001
From: whisper11111111111 <1819033498@qq.com>
Date: Tue, 10 Feb 2026 23:41:06 +0800
Subject: [PATCH] Add usage manual and replication guide

---
 使用说明书.md | 100 +++++++++++++++++++++++++++++++++++++
 复刻指南.md   | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 236 insertions(+)
 create mode 100644 使用说明书.md
 create mode 100644 复刻指南.md

diff --git a/使用说明书.md b/使用说明书.md
new file mode 100644
index 0000000..80b71f4
--- /dev/null
+++ b/使用说明书.md
@@ -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 产生的"向右向右向右"等重复幻觉。
+- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
+- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。
diff --git a/复刻指南.md b/复刻指南.md
new file mode 100644
index 0000000..d8e21df
--- /dev/null
+++ b/复刻指南.md
@@ -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`。