# NaviGlass Server 🤖👓

<div align="center">

**面向视障人士的智能导航与辅助系统 - 服务器端**

基于 FastAPI + YOLO 分割 + 多模态 AI 的高性能 Python 服务端

[功能特性](#功能特性) • [技术栈](#技术栈) • [快速开始](#快速开始) • [系统架构](#系统架构)

</div>

---

## ⚠️ 声明

本项目仅供学习交流，请勿直接用于视障人群实际场景。

---

## ✨ 功能特性

### 🚶 盲道导航
- YOLO 实时分割 + Lucas-Kanade 光流稳定
- 智能方向引导（左转/右转/直行）
- 障碍物检测 + 自动避障

### 🚦 过马路辅助
- 斑马线检测与对齐引导
- 红绿灯状态识别 (HSV + YOLO)

### 🔍 物品查找
- YOLO-E 开放词汇检测 + ByteTrack 追踪
- MediaPipe 手部引导

### 🎙️ 智能语音交互
- 实时语音识别 + 多模态对话 + TTS 语音播报

---

## 🔧 技术栈

### 核心框架
| 组件 | 技术 | 说明 |
|------|------|------|
| 语言 | Python 3.9+ | - |
| Web 框架 | **FastAPI** | 高性能异步 Web 框架 |
| 服务器 | **Uvicorn** | 基于 uvloop 的 ASGI 服务器 |
| 通信 | **WebSocket** | 音视频实时双向传输 |

### AI 交互管道
| 组件 | 技术 | 说明 |
|------|------|------|
| 大语言模型 | **GLM-4.6v-Flash** | 智谱 AI (zai-sdk)，支持多模态视觉 |
| 语音识别 | **SenseVoiceSmall** | FunASR 本地部署，高精度中文 |
| 语音活动检测 | **Silero VAD** | PyTorch 实现，含 300ms 环形缓冲 |
| 语音合成 | **EdgeTTS** | 微软 Edge TTS，免费且自然 |

### 计算机视觉
| 组件 | 技术 | 说明 |
|------|------|------|
| 目标检测/分割 | **Ultralytics YOLO11** | 检测 + 语义分割 |
| 推理加速 | **TensorRT** | FP16 半精度，.engine 格式 |
| 图像编解码 | **PyTurboJPEG** | 比 OpenCV 快 2-3 倍 |
| 手势识别 | **MediaPipe** | 手部检测与追踪 |

### 高性能计算
| 组件 | 技术 | 说明 |
|------|------|------|
| GPU 计算 | **CUDA** | PyTorch + RTX 3090 |
| 数学加速 | **Numba JIT** | NumPy 矩阵运算加速 |
| 并发模型 | **AsyncIO + Threading** | WebSocket 高并发 |
| GPU 调度 | **Semaphore** | 2-4 槽位并行推理 |

---

## 💻 系统要求

| 组件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| GPU | RTX 3060 (CUDA 11.8+) | RTX 3090 |
| 内存 | 8GB | 16GB+ |
| Python | 3.9 | 3.10 |

### API 密钥

| 服务 | 环境变量 | 申请地址 |
|------|---------|---------|
| 智谱 AI | `GLM_API_KEY` | https://open.bigmodel.cn/ |
| 阿里云 (可选) | `DASHSCOPE_API_KEY` | https://dashscope.console.aliyun.com/ |

---

## 🚀 快速开始

### 1. 安装依赖

```bash
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt
```

### 2. 下载模型

将模型放入 `model/` 目录：

| 模型 | 用途 |
|------|------|
| `yolo-seg.pt` | 盲道分割 |
| `yoloe-11l-seg.pt` | 障碍物/开放词汇检测 |
| `yolo11l-seg-indoor.engine` | 室内导盲 (20类) |
| `SenseVoiceSmall/` | 语音识别 |

> 模型下载: https://www.modelscope.cn/models/archifancy/AIGlasses_for_navigation

### 3. 配置环境

编辑 `.env`：

```bash
CUDA_VISIBLE_DEVICES=0
AIGLASS_DEVICE=cuda:0
AIGLASS_YOLO_IMGSZ=480
GLM_API_KEY=your_key
```

### 4. 启动

```bash
python app_main.py
```

访问 http://localhost:8081

---

## 🏗️ 系统架构

```
┌────────────────────────────────────────────────┐
│              FastAPI 主服务                     │
│   app_main.py (WebSocket/HTTP 路由)            │
└────┬───────────────┬───────────────┬───────────┘
     │               │               │
┌────▼────┐    ┌─────▼─────┐   ┌─────▼─────┐
│SenseVoice│    │GLM-4.6v   │   │ EdgeTTS   │
│ 本地ASR  │    │ 多模态LLM │   │ 语音合成   │
└─────────┘    └───────────┘   └───────────┘
     │               │               │
┌────▼───────────────▼───────────────▼───────────┐
│            NavigationMaster 状态机              │
│  IDLE / CHAT / BLINDPATH / CROSSING / SEARCH   │
└────┬───────────────┬───────────────┬───────────┘
     │               │               │
┌────▼────┐    ┌─────▼─────┐   ┌─────▼─────┐
│ 盲道导航 │    │ 过马路    │   │ 物品查找  │
│blindpath│    │crossstreet│   │ yolomedia │
└─────────┘    └───────────┘   └───────────┘
     │               │               │
┌────▼───────────────▼───────────────▼───────────┐
│          YOLO 模型层 (TensorRT FP16)            │
└────────────────────────────────────────────────┘
```

---

## 📁 核心模块

| 模块 | 文件 | 功能 |
|------|------|------|
| 主入口 | `app_main.py` | FastAPI + WebSocket |
| 语音识别 | `sensevoice_asr.py` | SenseVoice 本地 ASR |
| 语音合成 | `edge_tts_client.py` | EdgeTTS |
| 多模态 LLM | `glm_client.py` | GLM-4.6v-Flash |
| 状态机 | `navigation_master.py` | 导航模式管理 |
| 盲道导航 | `workflow_blindpath.py` | 盲道检测 + 避障 |
| 过马路 | `workflow_crossstreet.py` | 斑马线 + 红绿灯 |
| 物品查找 | `yolomedia.py` | 开放词汇检测 |

---

## 📡 WebSocket 端点

| 端点 | 用途 | 数据格式 |
|------|------|---------|
| `/ws/camera` | 摄像头推流 | Binary (JPEG) |
| `/ws/viewer` | 浏览器订阅 | Binary (JPEG) |
| `/ws_audio` | 音频传输 | Binary (PCM16) |
| `/ws_ui` | UI 状态 | JSON |

---

## 🎙️ 语音指令

| 类型 | 指令示例 |
|------|---------|
| 导航 | "开始导航"、"停止导航" |
| 过马路 | "帮我过马路" |
| 物品 | "帮我找一下红牛" |
| 对话 | 任意问题 → AI 回答 |

---

## 🔗 相关文档

- [客户端代码](../NaviGlassClient/) - Avaota F1 (V821 RISC-V)
- [开发日志](../Docs/DevLogs/) - Day 1 ~ Day 25
- [技术栈详情](../Docs/服务器技术栈.md)

---

## 📄 许可证

MIT License
