ARmahjongAssist (AR麻将助手)

麻将，作为一门融合了概率、心理与记忆的艺术，在数字化浪潮中正迎来全新的辅助形态。ARmahjongAssist 项目应运而生，它巧妙结合了 RayNeo AR 眼镜 的沉浸式显示能力与 本地化 AI 的强大算力，构建了一套完全运行在本地网络中的麻将辅助系统。

无需将敏感的手牌图像上传至云端，无需担心网络延迟影响决策，ARmahjongAssist 通过 YOLOv8 进行毫秒级手牌识别，利用 Local LLM 理解复杂场况，并将最佳切牌建议实时投射在你的眼前。这不仅是一个辅助工具，更是一次关于隐私计算与边缘智能的完美实践。

核心特性：隐私优先，本地智能

完全本地化 (Fully Local)

• 隐私至上： 所有的图像识别均在本地服务器通过 ONNX Runtime 运行，手牌照片绝不离开你的局域网，彻底杜绝隐私泄露风险。
• 极致低延迟： 摒弃了云端 API 的网络往返时间，从拍照到显示建议，全程在局域网内完成，确保实战中的即时响应。

自然语言语音交互

• 意图理解： 集成 FasterWhisper 进行高精度语音转文本，结合 LLM (如 Qwen) 强大的语义理解能力。
• 场况感知： 只需口头描述“下家打过两张西风”，系统即可理解并更新场况，甚至帮你计算“绝张”概率，解放双手与大脑。

一键 Docker 部署

• 标准化环境： 提供完整的 docker-compose 配置，屏蔽了 Python 环境、依赖库和模型配置的复杂性，一键启动后端服务，开箱即用。

项目架构：端云协同的典范

本项目采用经典的 Client-Server 架构，分工明确，高效协同。

1. 客户端 (Client) - 运行于 RayNeo AR 眼镜

• 平台： Android (Min SDK 31, Target SDK 36)
• 核心职责：
  • 图像采集： 调用眼镜摄像头拍摄清晰的手牌照片（默认分辨率 1200x800，自动分割暗牌与副露）。
  • 数据通信： 通过 HTTP 将图像上传至局域网服务器。
  • AR 渲染： 接收服务器返回的 JSON 数据（切牌建议、鸣牌提示），并以悬浮窗形式叠加在现实视野中。
  • 交互控制： 支持触控操作（单击拍照、三击开始/结束局、滑动录音）。

2. 服务端 (Server) - 运行于本地 PC/服务器

• 技术栈： Python 3.9+ / FastAPI / ONNX Runtime / YOLOv8
• 核心引擎：
  • 视觉识别： 加载本地量化后的 YOLOv8 模型，精准识别 34 种麻将牌及花牌。
  • 牌理分析： 内置专业麻将库，计算向听数、进张数、期望值，输出科学打法。
  • 大模型集成： 通过 OpenAI 兼容接口连接本地 LLM (如 LM Studio/Ollama)，处理语音指令和复杂逻辑推理。

快速开始：5 分钟搭建你的私人助手

前置准备

1. Docker 环境： 安装 Docker Desktop (含 Docker Compose)。
2. 大模型服务： 推荐本地运行 LM Studio 或 Ollama，加载 Qwen-4B 或类似轻量模型，并开启 Server 模式。

第一步：部署后端服务

# 1. 克隆项目
git clone https://github.com/fAres4s/ARmahjongAssist.git
cd ARmahjongAssist

# 2. 配置环境变量
cd server
cp .env.example .env
# 编辑 .env 文件，填入你的 LLM 地址 (注意 Docker 网络配置)
# 例如：LLM_BASE_URL=http://host.docker.internal:1234/v1
#       LLM_MODEL=qwen/qwen3-4b-2507

# 3. 启动服务
cd ..
docker-compose up -d --build

服务启动后，API 将运行在 http://localhost:8000。

第二步：配置并运行 Android 客户端

1. 环境准备： 安装 Android Studio Ladybug+ 及 JDK 17+。连接 RayNeo 眼镜（需开启 USB 调试）。
2. 修改 IP 地址：
   • 获取你电脑的局域网 IP (如 192.168.1.100)。
   • 打开 app/src/main/java/com/example/ai_assist/MainActivity.kt。
   • 修改 baseUrl 为你的电脑 IP：.baseUrl("http://192.168.1.100:8000/")。
3. 编译运行： 点击 Android Studio 的 Run 按钮，应用将自动安装至眼镜。
   • 注意：眼镜需连接同一 Wi-Fi 才能通信。

第三步：实战操作指南

• 开始/结束对局： 三击眼镜右侧触控区域。
• 识别手牌： 每局开始后，单击触控区拍照，屏幕即刻显示建议。
• 语音输入： 向后滑动镜腿开启录音，口述场况（如“庄家立直”），松手停止。
• 查看建议： 最佳切牌将以高亮形式直接叠加在手牌上方。

进阶调试：YOLO 参数可视化调优

为了适应不同光线和桌布环境，项目内置了 YOLO Debug Tool。

1. 访问工具： 浏览器打开 http://localhost:8000/static/yolo_debug.html。
2. 上传测试图： 上传实际拍摄的手牌照片（建议 1200x400 裁剪图）。
3. 动态调整： 实时拖动 Confidence Threshold (置信度) 和 IoU Threshold (重叠阈值) 滑块。
4. 永久生效： 找到最佳参数后，修改 server/.env 文件：

   YOLO_CONF_THRESHOLD=0.54
   YOLO_IOU_THRESHOLD=0.85
   

   重启服务：docker-compose restart backend。