Akagi：雀魂AI辅助工具从入门到精通实战指南

Akagi：雀魂AI辅助工具从入门到精通实战指南

【免费下载链接】AkagiA helper client for Majsoul项目地址: https://gitcode.com/gh_mirrors/ak/Akagi

一、认知破局：麻将AI辅助工具的技术原理与核心价值

麻将作为一种融合策略与概率的复杂博弈游戏，传统辅助工具往往局限于基础牌效计算，而Akagi通过深度学习与实时数据解析技术，构建了一套完整的智能决策支持系统。本章节将从技术本质层面揭示其工作原理，帮助用户建立对工具的科学认知。

1.1 实时对局分析的技术架构

Akagi采用三层架构实现麻将AI辅助功能：

• 数据采集层：通过mitm.py实现的本地代理服务（start_proxy方法）捕获雀魂游戏流量，使用websocket_message方法解析对局数据
• 决策引擎层：基于model.py中定义的卷积神经网络（MortalEngine类），对136张麻将牌的组合状态进行13维度评估
• 交互呈现层：通过gui.py构建的悬浮窗界面（draw_weight和draw_top3方法）实时展示决策建议

典型应用场景：在四麻对局中，当玩家面临立直听牌选择时，系统能在300ms内完成8种可能听牌组合的收益计算，并以热力图形式标注最优选择。

常见误区：部分用户认为AI决策完全依赖深度学习模型，实际上系统采用"规则+模型"混合决策机制，在简单场景（如明显的铳牌识别）使用预定义规则加速响应。

1.2 与传统辅助工具的技术差异

二、架构解析：核心模块的配置与实现

2.1 开发环境配置的技术要点

操作目标：在Linux系统构建完整的开发与运行环境
实施路径：

1. 克隆项目仓库：
   git clone https://gitcode.com/gh_mirrors/ak/Akagi && cd Akagi
2. 创建并激活虚拟环境：
   python -m venv venv && source venv/bin/activate
3. 安装依赖包（含版本约束）：
   pip install -r requirement.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
4. 生成协议文件：
   cd mahjong_soul_api/ms && python generate_proto_file.py

效果验证：执行python -c "import mitmproxy; print('mitmproxy installed')"无报错，且mahjong_soul_api/ms/protocol_pb2.py文件生成成功。

参数最佳实践：

• Python版本严格控制在3.8.10-3.9.7之间（3.10版本存在protobuf兼容性问题）
• mitmproxy建议使用7.0.4版本，8.x版本会导致websocket_message解析异常
• 依赖安装时添加--no-cache-dir参数避免缓存冲突：pip install --no-cache-dir -r requirement.txt

2.2 核心配置文件的深度解析

操作目标：通过config.json实现个性化功能配置
实施路径：

1. 复制配置模板：cp config.json.example config.json
2. 关键参数配置：

   { "proxy_port": 8088, // 代理端口，建议设置8080-65535间未占用端口 "analysis_depth": 2, // 分析深度：1(快速)、2(平衡)、3(深度) "action_delay": { // 操作延迟设置，模拟人类反应 "min": 800, // 最小延迟(ms)：500-1500 "max": 1200 // 最大延迟(ms)：建议比min大300-500 }, "model_enabled": true, // AI模型开关 "overlay_transparency": 0.7 // 悬浮窗透明度：0.5-0.9 }

效果验证：启动应用后检查日志文件logs/akagi.log，确认包含"Configuration loaded successfully"条目。

常见误区：将analysis_depth盲目设置为3会导致决策延迟增加至500ms以上，建议普通配置电脑保持默认值2。

三、实战进阶：从基础使用到性能优化

3.1 AI模型部署与优化策略

操作目标：实现本地AI模型的高效部署与性能调优
实施路径：

1. 获取模型文件并放置于指定目录：
   cp ~/Downloads/mortal_v2.pth mjai/bot/mortal.pth
2. 修改模型配置文件：
   sed -i 's/"model_enabled": false/"model_enabled": true/' config.json
3. 性能优化配置（创建mhm/config.py优化参数）：

   MODEL_OPTIMIZATION = { "enable_amp": True, # 启用混合精度计算 "enable_quick_eval": True, # 启用快速评估模式 "batch_size": 4, # 推理批次大小：2-8 "device": "auto" # 设备选择："auto"|"cpu"|"cuda" }

效果验证：启动应用后，通过nvidia-smi观察GPU内存占用应低于1.5GB，模型加载时间不超过3秒。

典型应用场景：在配置较低的笔记本电脑上，通过设置device": "cpu"和batch_size": 2，可将模型推理延迟控制在300ms内。

3.2 多场景适配方案

Akagi通过模块化设计支持多种使用场景，核心适配配置如下：

场景一：竞技模式（高延迟容忍，追求决策精度）

• 配置文件修改：
  sed -i 's/"analysis_depth": 2/"analysis_depth": 3/' config.json
• 启动命令：python main.py --mode competitive

场景二：快速匹配（低延迟优先）

• 配置文件修改：
  sed -i 's/"enable_quick_eval": false/"enable_quick_eval": true/' mhm/config.py
• 启动命令：python main.py --mode quick

场景三：观战分析（后台模式）

• 配置文件修改：
  sed -i 's/"overlay_enabled": true/"overlay_enabled": false/' config.json
• 启动命令：python main.py --mode observer

验证方法：不同模式下检查日志中的"Mode: XXX"和"Analysis depth: X"字段是否正确。

四、生态构建：社区贡献与版本演进

4.1 社区贡献指南

Akagi项目采用模块化架构设计，欢迎开发者从以下方向贡献代码：

插件开发：基于mhm/hook/框架开发自定义功能，如：

• 创建新的aider.py钩子实现特定牌型的策略优化
• 扩展skins.py实现自定义界面主题

贡献流程：

1. Fork项目仓库并创建特性分支：git checkout -b feature/your-feature
2. 提交遵循PEP8规范的代码：flake8 your_code.py
3. 创建Pull Request，描述功能实现与测试方法

贡献案例：玩家@mahjonglover贡献的"七对子优化插件"已被合并至主分支，通过修改libriichi_helper.py中的meta_to_recommend方法，将七对子听牌概率计算准确率提升了12%。

4.2 版本演进与特性路线图

主要版本特性：

• v1.0：基础牌效分析与决策建议
• v2.0：引入深度学习模型（model.py的MortalEngine）
• v3.0：支持多场景适配与性能优化
• v4.0：新增战术数据库与复盘分析功能

未来路线图：

1. 实时多人协作分析（计划v4.2）
2. 移动端适配（计划v5.0）
3. 自定义模型训练框架（计划v5.5）

版本升级方法：
git pull origin main && pip install --upgrade -r requirement.txt

五、风险控制：安全使用与问题排查

5.1 账号安全防护策略

操作目标：确保使用过程中的账号安全
实施路径：

1. 启用随机操作延迟：
   sed -i 's/"action_delay": {}/"action_delay": {"min": 800, "max": 1500}/' config.json
2. 定期清理缓存数据：
   rm -rf cache/* && rm -rf logs/*.log
3. 配置证书信任（仅首次使用）：
   mitmdump --ssl-insecure -s mitm.py

验证方法：检查settings.json中的"security_mode"是否为"enhanced"。

5.2 常见技术问题排查

问题场景1：代理连接失败

• 错误表现：日志显示"Proxy start failed: Address already in use"
• 解决步骤：
  1. 查找占用端口进程：lsof -i :8080
  2. 终止冲突进程：kill -9 <PID>
  3. 修改配置文件端口：sed -i 's/"proxy_port": 8080/"proxy_port": 8088/' config.json

问题场景2：模型推理异常

• 错误表现：日志出现"RuntimeError: CUDA out of memory"
• 解决步骤：
  1. 修改mhm/config.py："batch_size": 2
  2. 禁用GPU加速："device": "cpu"
  3. 清理内存：python -c "import torch; torch.cuda.empty_cache()"

通过本文档的系统学习，读者不仅能够掌握Akagi的基础使用方法，更能深入理解其技术原理与优化策略，实现从工具使用者到技术实践者的转变。项目持续迭代的特性与开放的社区生态，也为进阶用户提供了广阔的探索空间。

【免费下载链接】AkagiA helper client for Majsoul项目地址: https://gitcode.com/gh_mirrors/ak/Akagi