docs: rewrite README (bilingual) + restructure documentation

- 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.
2026-03-25 19:53:49 +00:00 · 2026-02-20 21:23:47 +08:00 · 2026-02-20 21:23:47 +08:00 · 1d31dc5b96
commit 1d31dc5b96
parent 4eb716c8ad
6 changed files with 300 additions and 547 deletions
--- a/.gitignore
+++ b/.gitignore
@ -46,6 +46,3 @@ temp_voice.wav
 !arm_main.py
 !whisper_main.py
 !config.py
-!项目介绍文档.md
-!ck.md
-!lora.md
--- 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

-| 模块 | 技术方案 | 作用 |
+| 能力 | 实现 | Capability |
 |:---|:---|:---|
-| **语音识别** | **Faster-Whisper** (Base) | 离线语音转文本，支持流式输入 |
-| **语义理解** | **LLM (DeepSeek/Qwen) + LoRA** | 指令意图解析，泛化复杂语序 |
-| **视觉感知** | **YOLOv8s** + OpenCV | 目标检测与坐标映射 (Homography) |
-| **运动控制** | **Python (IK)** + **ESP32 (C++)** | 逆解算与底层 PWM 舵机驱动 |
-| **训练框架** | **LLaMA-Factory** | 高效微调大模型指令跟随能力 |
+| **听** | 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
+
+| # | 物品 | 规格 | 数量 | 单价 | 合计 |
+|:--|:---|:---|:--:|---:|---:|
+| 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 |
+
+**硬件连接 / Wiring**
+
+- **ESP32 串口引脚**：X→14, Y→4, Z→5, B→18, 夹爪→23
+- **电源**：舵机与 ESP32 分开供电（外部 6V/6A），防浪涌
+- **摄像头**：USB，固定于机械臂前方，覆盖整个工作台面
+- **串口**：USB 连接 ESP32，默认 `COM3`，可通过环境变量 `ROBOT_PORT` 修改
+
+---
+
+## 安装 / Installation
+
+### 1. 烧录固件 / Flash Firmware
+
+Arduino IDE 2.x，开发板选 "ESP32 Dev Module"：

-### 3.2 👁️ 视觉感知 (YOLOv8)
-*   **作用**: 识别桌面上的物体（如：削笔刀、盒子、零件）并定位其像素坐标。
-*   **获取方法**: **需要训练** (Custom Training)。
-*   **详细步骤**:
-    1.  **数据采集**: 
-        *   打开摄像头，拍摄你的桌面上不同摆放位置的物体图片（建议 100-300 张）。
-    2.  **数据标注**:
-        *   使用 `LabelImg` 或 `Roboflow` 等工具进行标注。
-        *   类别名称必须与可以被语音识别到的名称对应（如：`part`, `box` 等）。
-        *   *注意：本项目目前默认将所有目标映射为 `part` 进行抓取，但训练时建议区分不同类别。*
-    3.  **模型训练**:
-        *   确保你安装了 `ultralytics`。
-        *   准备 `data.yaml` 文件，指定 `train` 和 `val` 图片路径及类别名称。
-        *   运行训练命令：
 ```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
 ```
-    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 格式）：
+**大模型 (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": "向左移动一厘米",
+  "instruction": "把削笔刀抬起5厘米",
  "input": "",
  "system": "你是机械臂JSON转换器...",
-                "output": "[{\"action\": \"move_inc\", \"axis\": \"y\", \"value\": 10}]"
+  "output": "[{\"action\": \"lift\", \"target\": \"part\", \"height\": 50}]"
 }
-            ]
 ```
-        *   你需要编写大量类似的 "中文指令 -> 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)
+---
+
+## 快速上手 / Quick Start

-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`。
+启动后依次加载：机械臂串口 → 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 |
--- a/TRAINING.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)
--- a/ck.md
+++ b/ck.md
@ -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 打印件和廉价舵机组成的机械臂，提升到了具备**高精度轨迹跟踪**和**语义智能交互**能力的工业级原型水平。
--- a/使用说明书.md
+++ b/使用说明书.md
@ -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 产生的"向右向右向右"等重复幻觉。
- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。
--- a/项目介绍文档.md
+++ b/项目介绍文档.md
@ -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. **工程鲁棒性**：从硬件防浪涌、舵机减震到语音去幻觉，每一层都有针对性的容错机制