# 航天质检智能体

**Repository Path**: ybli_code/space-agent

## Basic Information

- **Project Name**: 航天质检智能体
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 航天质检缺陷检测智能体系统

基于 YOLO 深度学习模型的 PCB 缺陷检测智能体系统，支持语音交互、实时检测和机械臂联动。

## 功能特性

- **实时缺陷检测**：基于 YOLO11 模型，支持 6 种 PCB 缺陷类型检测
- **语音交互**：支持语音指令输入，智能语音播报检测结果
- **机械臂联动**：检测到缺陷后自动调度机械臂进行分拣
- **Web 控制面板**：现代化航天风格 UI，实时视频流显示
- **MCP 服务架构**：模块化设计，支持分布式部署
- **多服务发现**：自动发现局域网内的 MCP 服务

## 缺陷类型

| 缺陷类型 | 英文名称 | 描述 |
|---------|---------|------|
| 缺孔 | missing_hole | PCB 板上缺少应有的钻孔 |
| 鼠咬 | mouse_bite | 板边边缘出现不规则缺口 |
| 开路 | open_circuit | 电路线路断裂 |
| 短路 | short | 不应连接的线路发生短路 |
 | 毛刺 | spur | 线路边缘出现的多余铜刺 |
| 杂铜 | spurious_copper | 板面上出现的多余铜箔 |

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Web 前端 (React + Vite)                │
│                    http://localhost:5173                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    后端 API (FastAPI)                        │
│                    http://localhost:8000                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 智能体管理   │  │ MCP 服务发现 │  │ 视频流服务  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Vision MCP    │ │   Servo MCP     │ │   LLM 服务      │
│  (缺陷检测)      │ │  (机械臂控制)    │ │  (智能对话)     │
│  Port: 8001     │ │  Port: 8002     │ │  SiliconFlow   │
└─────────────────┘ └─────────────────┘ └─────────────────┘
        │                   │
        ▼                   ▼
┌─────────────────┐ ┌─────────────────┐
│  YOLO11 模型    │ │   舵机/机械臂    │
│  (best.pt)      │ │   (GPIO控制)    │
└─────────────────┘ └─────────────────┘
```

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+
- 摄像头设备（可选）

### Windows 安装指南

#### 1. 安装必要软件

| 软件 | 版本要求 | 下载地址 |
|-----|---------|---------|
| Python | 3.10+ | https://www.python.org/downloads/ |
| Node.js | 18+ | https://nodejs.org/ |
| Git | 最新版 | https://git-scm.com/download/win |

**Python 安装注意事项：**
- 安装时务必勾选 "Add Python to PATH"
- 安装完成后打开命令提示符验证：`python --version`

**Node.js 安装：**
- 下载 LTS 版本
- 验证安装：`node --version` 和 `npm --version`

#### 2. 克隆项目

打开命令提示符或 PowerShell：
```cmd
git clone https://gitee.com/ybli_code/space-agent.git
cd space-agent
```

#### 3. 创建虚拟环境

```cmd
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

#### 4. 安装前端依赖

```cmd
cd src\web_ui
npm install
cd ..\..
```

#### 5. 配置环境变量

```cmd
copy .env.example .env
```

编辑 `.env` 文件，填入 `SILICONFLOW_API_KEY`

#### 6. 启动服务

```cmd
start_all_services.bat
```

#### 7. 访问系统

- 控制面板：http://localhost:5173
- API 文档：http://localhost:8000/docs

#### 8. 停止服务

```cmd
stop_all_services.bat
```

**Windows 注意事项：**
- 摄像头功能正常支持
- 如遇到权限问题，请以管理员身份运行命令提示符

### Linux/macOS 安装指南

#### 1. 克隆项目
```bash
git clone https://gitee.com/ybli_code/space-agent.git
cd space-agent
```

#### 2. 创建虚拟环境并安装依赖
```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

#### 3. 安装前端依赖
```bash
cd src/web_ui
npm install
cd ../..
```

#### 4. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env 文件，填入 SILICONFLOW_API_KEY
```

### 启动服务

**Linux/macOS**
```bash
./start_all_services.sh
```

**Windows**
```cmd
start_all_services.bat
```

**单独启动服务**
```bash
# 启动视觉 MCP 服务
./start_vision_mcp.sh

# 启动伺服 MCP 服务
./start_servo_mcp.sh

# 启动后端 API
uvicorn src.web_api.main:app --host 0.0.0.0 --port 8000

# 启动前端 UI
cd src/web_ui && npm run dev
```

### 停止服务

**Linux/macOS**
```bash
./stop_all_services.sh
```

**Windows**
```cmd
stop_all_services.bat
```

### 摄像头启动服务

**Linux/macOS**
```bash
pip install -r requirements_camera.txt
./start_camera.sh
```

**Windows**
```cmd
pip install -r requirements_camera.txt
start_camera.bat
```

### 访问地址

| 服务 | 地址 | 说明 |
|-----|------|------|
| 控制面板 | http://localhost:5173 | Web UI |
| API 文档 | http://localhost:8000/docs | Swagger UI |
| Vision MCP | http://localhost:8001 | 视觉检测服务 |
| Servo MCP | http://localhost:8002 | 机械臂控制服务 |

### Windows 打包为 EXE

**打包步骤**
```cmd
# 1. 安装打包依赖
pip install pyinstaller

# 2. 运行打包脚本
build_windows.bat
```

**打包输出**
- 输出目录：`dist\DefectDetector\`
- 可执行文件：`dist\DefectDetector\DefectDetector.exe`

**使用方法**
1. 复制 `dist\DefectDetector` 文件夹到目标电脑
2. 编辑 `.env` 文件配置 API 密钥
3. 双击运行 `DefectDetector.exe`

**注意事项**
- 打包后的程序约 500MB-1GB（包含 Python 运行时和所有依赖）
- 首次启动可能需要几秒钟初始化
- 需要确保 `best.pt` 模型文件存在

## 深度学习技术原理

### YOLO 目标检测算法

本项目采用 **YOLO (You Only Look Once)** 系列目标检测算法，具体使用 **Ultralytics YOLO11** 版本。

#### 核心原理

YOLO 将目标检测视为单次回归问题，将图像分割成 S×S 网格，每个网格负责预测：

1. **边界框 (Bounding Box)**：包含目标的矩形区域
   - 中心坐标 (x, y)
   - 宽度和高度 (w, h)
   - 置信度分数

2. **类别概率**：目标属于各类别的概率分布

#### 网络架构

```
输入图像 (640×640×3)
        │
        ▼
┌───────────────────┐
│    Backbone       │  CSPDarknet 特征提取
│   (特征提取网络)   │  - 卷积层 + 批归一化 + SiLU激活
└───────────────────┘  - CSP 结构增强梯度流
        │
        ▼
┌───────────────────┐
│      Neck         │  PANet 特征融合
│   (特征融合网络)   │  - 多尺度特征金字塔
└───────────────────┘  - 自顶向下 + 自底向上路径
        │
        ▼
┌───────────────────┐
│      Head         │  解耦检测头
│   (检测头)        │  - 分类分支 + 回归分支
└───────────────────┘  - Anchor-free 设计
        │
        ▼
   检测结果输出
   - 边界框坐标
   - 类别概率
   - 置信度分数
```

#### 损失函数

YOLO11 使用复合损失函数：

```
Loss = λ_box × L_box + λ_cls × L_cls + λ_dfl × L_dfl

其中：
- L_box: 边界框回归损失 (CIoU Loss)
- L_cls: 分类损失 (BCE Loss)
- L_dfl: 分布焦点损失 (Distribution Focal Loss)
```

#### 训练数据集

本项目使用 PCB 缺陷检测数据集，包含 6 种缺陷类型：

```yaml
# data.yaml 配置
nc: 6  # 类别数量
names: ['missing_hole', 'mouse_bite', 'open_circuit', 'short', 'spur', 'spurious_copper']
```

#### 推理流程

```python
from ultralytics import YOLO

# 加载模型
model = YOLO("best.pt")

# 执行推理
results = model(image, conf=0.25)

# 解析结果
for result in results:
    boxes = result.boxes      # 边界框
    classes = result.names    # 类别名称
    confidences = result.probs # 置信度
```

### 模型性能优化

1. **模型量化**：支持 INT8 量化，减少模型大小和推理延迟
2. **ONNX 导出**：支持导出为 ONNX 格式，便于跨平台部署
3. **TensorRT 加速**：支持 NVIDIA GPU 加速推理

### 检测结果后处理

```python
# 非极大值抑制 (NMS)
def nms(boxes, scores, iou_threshold=0.5):
    """
    去除重叠的检测框，保留最优结果
    """
    keep = []
    order = scores.argsort()[::-1]
    while order.size > 0:
        i = order[0]
        keep.append(i)
        ious = compute_iou(boxes[i], boxes[order[1:]])
        inds = np.where(ious <= iou_threshold)[0]
        order = order[inds + 1]
    return keep
```

## MCP 服务接口

### Vision MCP (视觉检测服务)

| 工具名称 | 参数 | 返回值 | 说明 |
|---------|------|--------|------|
| detect_image | image_path, threshold | defects[], visualization | 检测图片中的缺陷 |
| load_model | model_name | loaded, model_id | 加载指定模型 |
| get_model_info | - | name, classes, version | 获取当前模型信息 |

### Servo MCP (机械臂控制服务)

| 工具名称 | 参数 | 返回值 | 说明 |
|---------|------|--------|------|
| move_servo | angle, duration | ok, angle | 控制舵机转动到指定角度 |
| run_sequence | sequence_name | ok, sequence | 执行预设动作序列 |
| emergency_stop | - | ok | 紧急停止 |
| get_state | - | angle, busy, mock_mode | 获取舵机状态 |

## 项目结构

```
缺陷检测智能体开发/
├── src/
│   ├── web_api/           # 后端 API 服务
│   │   ├── main.py        # FastAPI 应用入口
│   │   └── agent_service.py  # 智能体管理逻辑
│   ├── web_ui/            # 前端 React 应用
│   │   └── src/
│   │       └── App.tsx    # 主界面组件
│   ├── vision-mcp/        # 视觉检测 MCP 服务
│   │   └── server.py      # YOLO 检测服务
│   ├── servo-mcp/         # 机械臂控制 MCP 服务
│   │   └── server.py      # 舵机控制服务
│   └── agent/             # 智能体核心逻辑
├── best.pt                # YOLO 训练模型
├── data.yaml              # 数据集配置
├── start_all_services.sh  # 启动所有服务
├── stop_all_services.sh   # 停止所有服务
├── requirements.txt       # Python 依赖
└── .env.example           # 环境变量模板
```

## API 端点

| 端点 | 方法 | 说明 |
|-----|------|------|
| `/status` | GET | 获取系统状态 |
| `/camera/toggle` | POST | 开关摄像头 |
| `/algorithm/toggle` | POST | 开关算法服务 |
| `/trigger/{action}` | POST | 手动触发机械臂动作 |
| `/mcp/discover` | GET | 发现 MCP 服务 |
| `/mcp/add` | POST | 添加 MCP 服务 |
| `/video_feed` | GET | 实时视频流 (MJPEG) |
| `/agent/chat` | POST | 与智能体对话 |
| `/voice/command` | POST | 语音指令处理 |

## 配置说明

### 环境变量

```bash
# .env 文件
SILICONFLOW_API_KEY=your_api_key      # SiliconFlow API 密钥
SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
SILICONFLOW_MODEL=Pro/zai-org/GLM-4.7  # LLM 模型
```

### 模型配置

```yaml
# data.yaml
train: ../train/images
val: ../valid/images
test: ../test/images
nc: 6
names: ['missing_hole', 'mouse_bite', 'open_circuit', 'short', 'spur', 'spurious_copper']
```

## 开发指南

### 添加新的缺陷类型

1. 更新 `data.yaml` 中的 `names` 列表
2. 重新训练 YOLO 模型
3. 更新 `agent_service.py` 中的 `DEFECT_NAMES` 常量

### 自定义机械臂动作

在 `src/servo-mcp/server.py` 中添加新的动作序列：

```python
@mcp.tool()
def run_custom_sequence() -> str:
    """执行自定义动作序列"""
    move_servo(45, 500)   # 转到45度，耗时500ms
    move_servo(90, 500)   # 转到90度
    move_servo(0, 500)    # 归位
    return "Custom sequence completed"
```

## 许可证

本项目仅供学习和研究使用。