From 1d31dc5b96ccd5e78868561ee4280e0aecf31d4d Mon Sep 17 00:00:00 2001 From: m1ngsama Date: Fri, 20 Feb 2026 21:23:47 +0800 Subject: [PATCH] docs: rewrite README (bilingual) + restructure documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- .gitignore | 5 +- README.md | 472 +++++++++++++++++++++++++---------------- lora.md => TRAINING.md | 8 + ck.md | 77 ------- 使用说明书.md | 101 --------- 项目介绍文档.md | 184 ---------------- 6 files changed, 300 insertions(+), 547 deletions(-) rename lora.md => TRAINING.md (96%) delete mode 100644 ck.md delete mode 100644 使用说明书.md delete mode 100644 项目介绍文档.md diff --git a/.gitignore b/.gitignore index 8ef71f5..2f8e740 100644 --- a/.gitignore +++ b/.gitignore @@ -45,7 +45,4 @@ temp_voice.wav !voice_main.py !arm_main.py !whisper_main.py -!config.py -!项目介绍文档.md -!ck.md -!lora.md \ No newline at end of file +!config.py \ No newline at end of file diff --git a/README.md b/README.md index 4afaea4..f8868b5 100644 --- a/README.md +++ b/README.md @@ -1,200 +1,310 @@ -# 🤖 智能语音具身智能机械臂 (Voice-Controlled Embodied AI Robot Arm) +# 智能语音机械臂 / Voice-Controlled Robot Arm -> 🚀 **桌面级具身智能 (Embodied AI) 最佳实践**：构建“耳-脑-眼-手”全链路闭环控制系统。 +基于"耳-脑-眼-手"全链路闭环的具身智能系统，运行于消费级硬件，完全离线。 -本项目实现了一套运行在消费级笔记本（RTX 3060, 6GB）上的**全栈离线具身智能系统**。通过多模态模型融合，打通了从自然语言到物理动作的最后壁垒： -* **听 (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 控制下的平滑运动。 +*A full-stack embodied AI system — voice in, physical action out — running entirely offline on consumer hardware.* --- -## 🛠️ 技术栈总览 +## 系统简介 / Overview -| 模块 | 技术方案 | 作用 | -| :--- | :--- | :--- | -| **语音识别** | **Faster-Whisper** (Base) | 离线语音转文本，支持流式输入 | -| **语义理解** | **LLM (DeepSeek/Qwen) + LoRA** | 指令意图解析，泛化复杂语序 | -| **视觉感知** | **YOLOv8s** + OpenCV | 目标检测与坐标映射 (Homography) | -| **运动控制** | **Python (IK)** + **ESP32 (C++)** | 逆解算与底层 PWM 舵机驱动 | -| **训练框架** | **LLaMA-Factory** | 高效微调大模型指令跟随能力 | +| 能力 | 实现 | Capability | +|:---|:---|:---| +| **听** | Faster-Whisper，本地中文语音识别 | Speech-to-text (Chinese, local) | +| **想** | DeepSeek-R1-1.5B + QLoRA 微调，自然语言→JSON | LLM + rule engine, NL→JSON actions | +| **看** | YOLOv8s 目标检测 + 单应性矩阵手眼标定 | Object detection + hand-eye calibration | +| **动** | D-H 逆运动学 + S-Curve 轨迹规划，ESP32 驱动 | IK solver + smooth trajectory → ESP32 PWM | + +硬件总成本 **¥317**，GPU 需求 RTX 3060 6GB（推理 <4GB 显存，延迟 <200ms）。 + +*Total hardware cost ¥317 (~$45 USD). Requires an NVIDIA GPU for LLM inference.* --- -# 📖 项目复刻指南 (Replication Guide) +## 系统架构 / Architecture -本指南详细介绍了如何从零开始复刻本项目，包括硬件准备、环境搭建、以及**最关键的三个AI模型（语音、视觉、大脑）的获取与训练方法**。 - -## 1. 硬件准备 (Hardware) - -### 1.1 项目物料清单 (BOM) & 成本 - -本项目硬件成本极低，总花费约 **¥317**。以下是基于实际采购发票的详细清单： - -| 序号 | 物品名称 | 规格/型号 | 数量 | 单价 (CNY) | 总费用 (CNY) | 备注 | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| 1 | 3D打印机械臂 | 教具/机械臂 (散件) | 1 个 | 71.00 | 71.00 | 包含亚克力/PLA结构件 | -| 2 | ESP32开发板 | WiFi+蓝牙双核 MCU | 1 件 | 18.71 | 18.71 | 主控核心 | -| 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** | **高性价比** | - -### 1.2 硬件连接说明 - -### 1.2 硬件连接说明 - -* **机械臂**: 也就是本项目中的 `RobotArmUltimate`。 - * 要求：支持串口通信（Serial），使用标准舵机控制协议。 - * 连接：USB连接电脑，需确认串口号（代码默认为 `COM3`，请在 `arm_main.py` 或 `voice_main.py` 中修改）。 -* **摄像头**: USB免驱网络摄像头。 - * 安装位置：固定在机械臂前方或上方，确保能覆盖工作台面。 -* **麦克风**: 任意USB麦克风或电脑内置麦克风。 -* **计算设备**: 建议配备 NVIDIA 显卡的 Windows/Linux 电脑（用于加速 YOLO 和 LLM 推理）。 - -### 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 +``` +麦克风 / Microphone + │ + ▼ +┌──────────────────┐ +│ Faster-Whisper │ 语音识别 (STT) — 中文语音 → 文本 +└────────┬─────────┘ + │ "把削笔刀抬起5厘米" + ▼ +┌──────────────────┐ +│ 规则解析引擎 │ 简单指令直接匹配（松开 / 复位 / 方向移动） +│ (Regex engine) │ 命中 → 直接生成 JSON，跳过 LLM +└────────┬─────────┘ + │ 未命中（含物体名的复杂指令） + ▼ +┌──────────────────┐ +│ DeepSeek-R1-1.5B │ QLoRA 微调推理 +│ (QLoRA, FP16) │ 自然语言 → 结构化 JSON 指令 +└────────┬─────────┘ + │ [{"action": "lift", "target": "part", "height": 50}] + ▼ +┌──────────────────┐ +│ YOLOv8s │ 实时检测目标物体 +│ + Homography │ 像素坐标 → 机械臂工作坐标 (mm) +└────────┬─────────┘ + │ (rx=170, ry=3) + ▼ +┌──────────────────┐ +│ 运动控制引擎 │ D-H 逆运动学 + S-Curve 插值 +│ arm_main.py │ 平滑轨迹 → 串口 → ESP32 → 舵机 +└──────────────────┘ ``` -## 3. 三大核心模型获取与训练指南 (Model Training) +--- -本项目包含三个核心 AI 模块，请分别按照以下步骤准备。 +## 硬件清单 / Bill of Materials -### 3.1 👂 语音听觉 (Whisper) -* **作用**: 将你的语音指令转为文字。 -* **获取方法**: - * **无需训练**。代码使用了 OpenAI 的 `whisper` 模型。 - * 首次运行时，程序会自动下载模型权重（如 `base` 或 `small` 模型）。 - * 代码位置：`whisper_main.py` 中的 `RobotEar` 类。 +总计 **¥317** / ~$45 USD -### 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')`。 +| # | 物品 | 规格 | 数量 | 单价 | 合计 | +|:--|:---|:---|:--:|---:|---:| +| 1 | 3D 打印机械臂（散件） | 教具级，含亚克力/PLA 结构件 | 1 | ¥71 | ¥71 | +| 2 | ESP32 开发板 | WiFi+蓝牙双核 MCU | 1 | ¥19 | ¥19 | +| 3 | ESP32 配件 | 接插件/扩展板 | 1 | ¥5 | ¥5 | +| 4 | USB 工业摄像头 | 免驱，广角，1280×720 | 1 | ¥61 | ¥61 | +| 5 | 数字舵机 MG996R | 金属齿轮，高扭矩 | 5 | ¥27 | ¥133 | +| 6 | 稳压电源 | 6V 6A，舵机专用 | 1 | ¥29 | ¥29 | -### 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 的配置文件里记录了基座模型路径）。* +**硬件连接 / Wiring** -## 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. 使用方法 -* 按住 **空格键** 说话（如：“把那个零件拿起来”，“向左两厘米”）。 -* 松开空格键，机械臂将自动执行动作。 -* 更多快捷键和指令说明请参考 `使用说明书.md`。 +## 安装 / Installation + +### 1. 烧录固件 / Flash Firmware + +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 的推理模型默认会输出思维链（`...`）。通过手动追加 `<｜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 | diff --git a/lora.md b/TRAINING.md similarity index 96% rename from lora.md rename to TRAINING.md index 6db3060..8c7e3ba 100644 --- a/lora.md +++ b/TRAINING.md @@ -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 微调的轻量级具身智能指令解析系统研究 ## 1. 项目背景与摘要 (Abstract) diff --git a/ck.md b/ck.md deleted file mode 100644 index c4e2229..0000000 --- a/ck.md +++ /dev/null @@ -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 打印件和廉价舵机组成的机械臂，提升到了具备**高精度轨迹跟踪**和**语义智能交互**能力的工业级原型水平。 \ No newline at end of file diff --git a/使用说明书.md b/使用说明书.md deleted file mode 100644 index 21d60bd..0000000 --- a/使用说明书.md +++ /dev/null @@ -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 产生的"向右向右向右"等重复幻觉。 -- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。 -- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。 diff --git a/项目介绍文档.md b/项目介绍文档.md deleted file mode 100644 index f4503b5..0000000 --- a/项目介绍文档.md +++ /dev/null @@ -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. **工程鲁棒性**：从硬件防浪涌、舵机减震到语音去幻觉，每一层都有针对性的容错机制