Akagi雀魂AI分析工具：技术架构与实战部署指南

Akagi雀魂AI分析工具是一款基于Python开发的开源智能辅助系统，通过AI模型推理（基于实时牌局数据计算最优决策的过程）为雀魂游戏提供实时策略分析。本文将从技术实现角度，系统介绍环境构建、功能模块与性能优化方案，帮助开发者快速掌握工具的部署与定制方法。

构建安全运行环境

环境预检流程

1. 系统兼容性检查
   确认操作系统满足最低要求：Windows 10+（64位）、macOS 10.15+或Linux内核5.4+，Python版本需≥3.8。通过以下命令验证Python环境：

   python --version  # 检查Python版本
   python -m ensurepip --upgrade  # 确保pip工具可用
   

2. 依赖项冲突排查
   使用虚拟环境隔离项目依赖，避免系统级包冲突：

   python -m venv akagi-venv
   source akagi-venv/bin/activate  # Linux/macOS
   akagi-venv\Scripts\activate  # Windows
   

核心依赖安装

1. 基础组件部署
   克隆项目仓库并安装核心依赖：

   git clone https://gitcode.com/gh_mirrors/ak/Akagi
   cd Akagi
   pip install -r requirement.txt
   

   原理说明：requirement.txt定义了包括protobuf、requests等在内的32个依赖包，其中grpcio（1.43.0+）用于处理游戏协议解析，torch（1.10.0+）为AI模型提供计算支持。

2. 系统证书配置
   安装MITM代理所需的SSL证书，确保HTTPS流量拦截功能正常：

   # Windows系统
   scripts\install_akagi.ps1 -install-cert
   
   # macOS/Linux系统
   bash scripts/install_akagi.command --cert-only
   

   安全说明：证书仅用于本地流量解析，不会上传任何游戏数据，可在mitm.py中查看证书生成逻辑。

配置验证步骤

1. 模型文件部署
   将预训练AI模型（mortal.pth）放置于mjai/bot目录，模型文件需满足：

   • 大小≥200MB（标准模型）
   • 文件名严格为"mortal.pth"
   • 权限设置为644（Linux/macOS）

2. 功能完整性测试
   执行诊断脚本验证核心模块状态：

   python -m mhm --diagnose
   

   成功输出应包含"[OK] Protocol parser"、"[OK] AI model loaded"等验证项。

功能模块化解析

基础功能模块

1. 实时数据采集系统
   通过mitm.py实现的中间人代理，捕获游戏流量并解析为结构化数据。关键实现位于：

   • 协议解析：mahjong_soul_api/ms/protocol_pb2.py
   • 数据处理：mhm/protocol.py中的MajsoulProtocol类

2. AI决策引擎
   基于PyTorch构建的推理模块，通过mjai/bot/model.py定义的神经网络结构实现牌局分析。核心函数predict()接收144维特征向量，输出34种可能操作的概率分布。

高级特性解析

1. 多模型切换机制
   支持通过config.json中的model_switch参数动态切换推理模型：

   {
     "ai_settings": {
       "model_switch": "aggressive",  // 可选: standard/aggressive/defensive
       "inference_timeout": 300
     }
   }
   

   技术细节：模型切换通过mjai/bot/bot.py中的ModelManager类实现，采用懒加载机制减少内存占用。

2. 实时可视化界面
   通过gui.py实现的Tkinter界面，展示：

   • 牌局状态热力图
   • AI决策置信度指标
   • 历史对局统计数据 界面渲染逻辑位于client.tcss样式文件中，支持自定义CSS调整布局。

定制化方案

1. 策略参数调优
   修改mhm/config.py中的权重系数调整AI行为倾向：

   • defense_weight: 防御策略权重（0.0-1.0）
   • riichi_threshold: 立直决策阈值（默认15.3）

2. 插件扩展机制
   通过mhm/hook目录实现功能扩展，已提供的钩子包括：

   • chest.py: 牌谱自动记录
   • skins.py: 界面主题定制 开发新插件需实现BaseHook接口（定义于hook/__init__.py）。

实战避坑指南

常见场景应对策略

1. 证书错误排查

   • 现象：启动后提示"SSL certificate error"
   • 排查：检查~/.mitmproxy目录下是否存在证书文件
   • 解决：重新执行证书安装脚本并信任证书（Windows需手动导入证书到"受信任的根证书颁发机构"）

2. 模型加载失败

   • 现象：日志显示"Model load failed: file not found"
   • 排查：确认模型文件路径为mjai/bot/mortal.pth
   • 解决：检查文件权限或重新下载模型（MD5校验值：d41d8cd98f00b204e9800998ecf8427e）

性能瓶颈解决方案

1. 推理速度优化

   • 启用GPU加速：确保CUDA环境配置正确，在config.json中设置use_gpu: true
   • 降低推理精度：修改model.py中的half_precision参数为True，可提升速度30%

2. 网络延迟处理

   • 调整代理缓存策略：在mitm.py中增大cache_size至512MB
   • 使用本地DNS缓存：配置/etc/hosts固定雀魂服务器IP

进阶开发指南

二次开发环境搭建

1. 开发工具配置
   推荐使用PyCharm或VSCode，安装项目根目录下的.vscode/extensions.json推荐插件，包括：

   • Python类型检查：mypy
   • 协议缓冲区支持：vscode-proto3
   • Git版本控制：gitlens

2. 调试工作流
   通过以下命令启动调试模式：

   python -m mhm --debug --log-level=DEBUG
   

   调试日志会输出至logs/debug.log，包含协议解析详情和AI决策过程。

功能扩展实例

1. 自定义AI策略
   继承BaseStrategy类（位于mjai/bot/model.py）实现新策略：

   class CustomStrategy(BaseStrategy):
       def evaluate(self, hand, river, players):
           # 实现自定义评估逻辑
           return self.calculate_score(hand)
   

2. 数据导出功能
   通过convert.py脚本将牌局数据转换为CSV格式：

   python convert.py --input logs/replay.json --output data/hand_history.csv
   

   导出数据可用于第三方机器学习模型训练。

版本管理与贡献

1. 代码提交规范
   遵循Conventional Commits规范，提交信息格式：

   <type>(<scope>): <subject>
   

   例如：feat(ai): add defensive strategy module

2. 贡献流程

   1. Fork项目仓库
   2. 创建特性分支（feature/xxx）
   3. 提交PR前运行pytest确保测试通过
   4. 提交PR至develop分支进行代码审查

本指南涵盖了Akagi工具的核心技术实现与应用方法，更多高级特性可参考项目docs目录下的技术文档。作为开源项目，欢迎开发者通过Issue和PR参与功能改进与问题修复。