Gemma Translator

Gemma Translator 是一个开源项目，实现在 Raspberry Pi 5 (8GB) 上完全离线的双向语音翻译。系统由 Google Gemma 4 (gemma4-e2b) 通过 LiteRT-LM 驱动文本翻译，Moonshine 负责语音识别（STT）与合成（TTS），所有推理均在设备端完成，无需联网。

项目包含为480×320小屏优化的复古终端风格Web UI、Python API服务器及一键部署脚本，支持横向（单人操作）与纵向（双人独立）两种键盘模式。硬件需Pi 5 8GB、麦克风、扬声器及显示屏；软件依赖Python 3.10+、Node.js 18+，提供setup.sh/download_model.sh/start.sh/deploy-pi.sh自动化流程，并含3D打印外壳STL文件。

核心架构与离线能力保障

全栈本地化设计

关键离线验证点

• ✅ 模型下载后存储于本地，运行时不检查更新
• ✅ Web UI生产模式使用frontend/dist/静态文件，无运行时fetch
• ✅ API服务器仅监听localhost:3000，防火墙可禁用外网
• ⚠️ 首次download_model.sh需联网，后续完全隔离

部署流程与硬件适配要点

四步标准化部署

# 1. 赋予脚本执行权限
chmod +x setup.sh download_model.sh start.sh deploy-pi.sh

# 2. 创建虚拟环境并安装依赖
./setup.sh

# 3. 下载Gemma4模型并导入LiteRT（需联网一次）
./download_model.sh

# 4. 启动服务（开发/生产模式）
./start.sh          # 开发：Vite热重载 @ localhost:5173
./start.sh --prod   # 生产：静态UI + API @ localhost:3000

树莓派专用信息亭部署

./deploy-pi.sh

该脚本自动完成：

• 安装Debian音频包与Python venv
• 构建生产版前端资源
• 注册systemd服务gemma-translator.service
• 配置LXDE autostart，Chromium以kiosk模式启动指向http://localhost:3000
• 开机自启，全屏无地址栏，适合嵌入式设备

硬件兼容性清单

双模键盘交互设计与使用场景

横向模式（Landscape）——单人主导

• 适用场景：柜台服务、导游讲解、一人协助双方沟通
• 操作逻辑：Space切换主动通道 → Z按住录音 → ←→切换语言
• 视觉反馈：主动通道四角高亮；录音时反色提示
• 优势：单手操作，焦点明确，防误触

纵向模式（Vertical）——双人平等

• 适用场景：面对面会谈、会议桌两侧、自助翻译站
• 操作逻辑：Z/X分别录音；←→控制人1语言；−/+控制人2语言
• 视觉反馈：无高亮，依赖物理位置区分
• 优势：双方自主控制，无需协调焦点

通用安全机制

• 🔒 输入框聚焦时快捷键自动禁用，防止编辑API端点等配置时误触发录音
• 🔒 录音期间语言旋转锁定，避免中途切语种导致转录错乱
• 💾 键盘模式选择持久化至localStorage，重启保持用户偏好
• 🚫 当前版本不支持触控操作，纯键盘驱动确保信息亭可靠性

已知限制与优化方向

性能边界

• Gemma4翻译延迟约2–5秒/句（Pi 5），长段落需分段输入
• Moonshine STT对非英语口音敏感度较高，建议清晰发音
• TTS语速固定，暂不支持动态调节
• 并发处理单通道，双人同时说话会丢失一方输入

扩展可能性

• 🎙️ 添加VAD（语音活动检测）实现自动端点，替代按住说话
• 🌐 支持更多语言对（当前依赖Gemma4训练数据覆盖）
• 📱 增加移动端 companion app 作为远程麦克风/扬声器
• ⚡ 探索ONNX Runtime或TensorFlow Lite进一步加速推理
• 🖥️ 适配更大屏幕布局，支持三通道或字幕显示

故障排查优先级

1. 服务未启动 → 检查start.sh日志，确认venv激活与端口占用
2. 模型加载失败 → 验证download_model.sh完整性，重跑导入步骤
3. 音频无声 → arecord -l / aplay -l 确认设备索引，检查PulseAudio配置
4. UI空白 → 生产模式需先npm run build，开发模式检查Vite进程
5. systemd未自启 → systemctl status gemma-translator 查看错误码