实时手语识别与语音合成平台 — 让无声的表达被听见。
端到端的实时手语翻译与语音合成系统。用户通过摄像头实时采集或上传视频文件输入手语，系统自动识别手势词汇、翻译为自然中文语句，并合成为可播放的语音。
graph LR
A[摄像头/视频] --> B[MediaPipe 手部关键点检测]
B --> C[CSL Transformer 时序分类]
C --> D[Token 序列]
D --> E[Qwen2-0.5B 翻译 / Mock 映射表]
E --> F[自然中文语句]
F --> G[pyttsx3 TTS]
G --> H[语音播放]
B -.->|降级| I[启发式几何规则]
E -.->|降级| J[Mock 映射表]
G -.->|降级| K[CosyVoice2]
- 实时手语识别：WebSocket 摄像头帧推流，MediaPipe + CSL Transformer 逐帧分类
- 大模型翻译：Qwen2-0.5B-Instruct 将词汇序列重组为通顺中文句子
- 离线 TTS：pyttsx3 本地语音合成，无需网络
- 自动降级：模型权重缺失时自动切换启发式规则，系统不崩溃
- 双模式输入：摄像头实时流 + 视频文件上传
- 翻译历史：SQLite 持久化存储，支持回放、删除
- 预训练权重：仓库内置手语识别权重，克隆即可用
| 手语 | 对不起 | 你 | 去 | 很 | 上次 | 会 | 大家 | 喜欢 | 面包 | | 一起 | 我 | 吃 | 为什么 | 谢谢 | 开心 | 祝 | 帮助 | 请 | 问 | | 快点 | 没关系 | 谁 | 在 | 想要 | | | | | |
模型训练支持自定义词汇表，可扩展任意新手势。
| 层级 | 技术 | 说明 |
|---|---|---|
| Web 框架 | FastAPI + Uvicorn | 异步 REST + WebSocket |
| 实时通信 | WebSocket | 摄像头帧推流，双向消息 |
| 手部检测 | MediaPipe | 21 点手部关键点实时提取（CPU 30fps+） |
| 时序分类 | CSL Transformer Encoder | 4 层 8 头自注意力 + 可学习位置编码 |
| 文本翻译 | Qwen2-0.5B-Instruct | 指令微调模型，词汇 → 自然语句 |
| 语音合成 | pyttsx3 | Windows SAPI5 离线 TTS，支持性别切换 |
| 数据存储 | SQLite | 翻译历史 CRUD |
| 前端 | 原生 HTML/CSS/JS | 零框架依赖 |
- Strategy 模式：
SignLanguageModel/TextTranslateModel抽象接口，工厂函数创建实例，替换实现时业务代码零改动 - Facade 模式：
RealSignLanguageModel组合 MediaPipe + CSL 子系统 - 降级容错：每层模型不可用时自动切换备选方案（神经网络 → 启发式规则、Qwen2 → Mock 映射表、pyttsx3 → CosyVoice2）
- Python 3.10+
- PyTorch 2.5+（建议根据显卡安装对应 CUDA 版本：pytorch.org）
- 摄像头（实时模式需要）
# 克隆
git clone https://github.com/pzzzwww/Sign-Language-Translation.git
cd Sign-Language-Translation
# 安装依赖
pip install -r requirements.txt
# 启动服务（预训练权重已在仓库中）
python -m uvicorn src.backend.main:app --host 0.0.0.0 --port 8008浏览器访问 **http://localhost:8008**，点击"开始采集"，摄像头前比划手势即可。
Qwen2-0.5B 首次启动自动下载（约 1GB）。如不想下载，修改
src/config.py中TRANSLATION_MODE = "mock"。
python scripts/collect_data.py每个手势录 20-50 段，采集时故意变换角度、距离、速度以提升泛化能力。
python scripts/train_csl.py训练参数可在命令行覆盖：
python scripts/train_csl.py --epochs 60 --batch 16 --lr 5e-4训练自动完成：滑动窗口切分 → 数据增强 → 类别加权/过采样 → 训练 → 早停 → 混淆矩阵。
├── src/
│ ├── backend/main.py # FastAPI 应用入口
│ ├── api/routes.py # REST API 路由
│ ├── websocket/handler.py # WebSocket 连接管理 + 实时识别
│ ├── config.py # 集中配置
│ ├── interfaces/ # 抽象接口（Strategy 模式）
│ │ ├── sign_language_model.py # SignLanguageModel 抽象基类
│ │ └── text_translate_model.py # TextTranslateModel 抽象基类
│ ├── models/
│ │ ├── __init__.py # 工厂函数 + 单例缓存
│ │ ├── sign_language_model/ # 手语识别模型
│ │ │ ├── mediapipe_detector.py # MediaPipe 手部关键点检测
│ │ │ ├── csl_recognizer.py # CSL Transformer 时序分类器
│ │ │ └── real_recognizer.py # 组合识别器（MediaPipe + CSL）
│ │ └── text_model/ # 文本翻译模型
│ │ ├── qwen2_translate_model.py # Qwen2-0.5B 词汇重组
│ │ └── mock_model.py # 轻量降级翻译（映射表 + 模板）
│ ├── services/ # 业务服务层
│ │ ├── sign_service.py # 手语识别服务（摄像头管理、帧缓冲）
│ │ ├── translate_service.py # Token → 中文翻译（支持 qwen/mock 模式）
│ │ ├── speech_service.py # pyttsx3 离线 TTS
│ │ ├── cosyvoice_tts.py # CosyVoice2 TTS（可选，自动降级）
│ │ ├── history_service.py # SQLite 翻译历史 CRUD
│ │ ├── video_service.py # 视频下载 + 抽帧
│ │ └── database.py # 数据库连接管理
│ └── utils/
│ └── frame_processor.py # 帧预处理工具
├── scripts/
│ ├── collect_data.py # 手势数据采集
│ ├── train_csl.py # CSL Transformer 训练
│ ├── export_onnx.py # ONNX 模型导出
│ └── gradio_app.py # Gradio 演示
├── frontend/
│ ├── index.html
│ └── static/
│ ├── css/style.css
│ └── js/main.js
├── data/gestures/ # 训练数据目录
├── requirements.txt
└── README.md
双入口设计：
- WebSocket
/ws/stream— 摄像头实时推流。客户端发送 base64 JPEG 帧，服务端逐帧分类，每个连接维护独立的StreamHandler识别会话 - REST API
/api/*— 视频文件上传、翻译、TTS、历史记录 CRUD
模型懒加载：首次调用时自动初始化，全应用单例共享，避免重复加载模型到显存。
翻译模式切换：config.TRANSLATION_MODE 控制：
"qwen"（默认）— Qwen2-0.5B-Instruct，大模型推理"mock"— 零依赖映射表，不加载模型，始终可用
| 方法 | 端点 | 说明 |
|---|---|---|
GET |
/api/health |
健康检查 |
GET |
/api/status |
模型加载状态 |
POST |
/api/translate |
词汇列表 → 翻译句子 |
POST |
/api/tts |
文本 → WAV 音频 |
POST |
/api/process-video |
上传视频 → 识别翻译 |
GET |
/api/history |
翻译历史列表 |
DELETE |
/api/history/{id} |
删除历史记录 |
| action | 说明 |
|---|---|
start_capture |
启动摄像头推流 |
stop |
停止摄像头 |
recognize |
执行识别 + 翻译 |
process_frame |
发送单帧（base64 JPEG） |
confirm_translate |
确认翻译文本 |
generate_audio |
生成语音 |
所有配置集中在 src/config.py：
| 配置项 | 默认值 | 说明 |
|---|---|---|
TRANSLATION_MODE |
"qwen" |
翻译模式：qwen / mock |
CAMERA_FPS |
12 |
采集帧率 |
CSL_INPUT_DIM |
126 |
输入维度（双手 126 / 单手 63） |
CSL_CONFIDENCE_THRESHOLD |
0.55 |
置信度阈值 |
CSL_STABILITY_THRESHOLD |
5 |
连续 N 帧一致才确认 |
CSL_COOLDOWN_FRAMES |
30 |
确认后冷却帧数，防止重复输出 |
REALTIME_RECOGNIZE_INTERVAL |
12 |
每隔 N 帧做一次识别，减少计算压力 |
Q: 摄像头打不开？
A: 修改 src/config.py 中 CAMERA_INDEX，Windows 通常为 0 或 1。
Q: 模型加载很慢？
A: 首次启动 Qwen2 需下载约 1GB。设置 TRANSLATION_MODE = "mock" 可跳过。
Q: 手语识别不准？ A: 采集更多数据重新训练（每类至少 50 个样本，变换角度、距离、速度）。
Q: 语音合成没有声音？
A: pyttsx3 依赖系统 TTS 引擎。Windows 使用 SAPI5，Linux 需 apt install espeak。