From cabd63252b8f9079f9e0163912f929ed49455c47 Mon Sep 17 00:00:00 2001 From: TTDXQ Date: Sun, 15 Mar 2026 23:36:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=A8=A1=E5=9E=8B?= =?UTF-8?q?=E5=8D=A1=EF=BC=8C=E8=A1=A5=E5=85=85=E5=AE=8C=E6=95=B4=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=E8=AF=B4=E6=98=8E=E4=B8=8E=E8=AF=84=E6=B5=8B=E7=BB=93?= =?UTF-8?q?=E6=9E=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 保留原有 YAML 元数据（license, datasets, language, base_model, tags） - 补充完整的模型描述、使用方法、评测结果 - 添加 GitHub 和 Hugging Face 仓库链接 - 添加完整的训练信息和数据处理说明 - 中英双语版本 --- README.md | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 243 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 87c3db9..39e634a 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,246 @@ language: - zh base_model: - unsloth/Qwen3-4B-Instruct-2507 ---- \ No newline at end of file +tags: +- riichi-mahjong +- game-ai +- qwen +- qwen3 +- mahjong +- discard-recommendation +- gguf +pipeline_tag: text-generation +--- + +# Qwen3-4B-Instruct-2507-mahjong-alpha + +`Qwen3-4B-Instruct-2507-mahjong-alpha` 是一个基于 `unsloth/Qwen3-4B-Instruct-2507` 进行 QLoRA 微调的立直麻将垂直模型，面向四麻弃牌建议任务。 + +模型可根据输入的场次信息、手牌、副露、牌河、牌效与防守信息，输出当前最应打出的一张牌。 + +当前版本主要面向工具集成场景，推理输出为单张牌文本，不包含解释信息。 + +## 模型特点 + +- **任务**：四麻立直麻将弃牌建议 +- **基座模型**：`unsloth/Qwen3-4B-Instruct-2507` +- **微调方式**：`QLoRA` +- **训练框架**：`Unsloth` +- **发布格式**：`GGUF (F16)` +- **推理方式**：`llama.cpp` +- **维护者**：`TTDXQ` + +## 适用范围 + +本模型面向四麻场景，不含赤宝牌。当前版本专注于"弃牌建议"这一单一任务，不提供完整对局规划，也不提供役种、打点或详细攻防解释。 + +## 使用限制 + +- 仅支持弃牌建议 +- 不支持完整对局规划 +- 不支持役种、打点、进攻防守解释 +- 不保证竞赛或实战效果 +- 仅供研究与学习使用 + +## 禁止用途 + +禁止将本模型用于： + +- 作弊 +- 外挂 +- 代打 +- 真钱赌博辅助 + +## 模型输入输出 + +### 输入格式 + +模型输入为结构化自然语言局面描述。示例： + +```text +[情景分析] +- 牌局: 东一局，你是庄家 (第1巡，牌墙余69张)。 +- 状态: 当前排名 1/4 (与一位差 0)。 +- 宝牌: 5万 +- 各玩家分数: 你有 25分, 下家: 25分, 对家: 25分, 上家: 25分。 +- 你的手牌: 1万 5万 7万 3筒 5筒 6筒 8筒 8筒 3索 5索 8索 南 白 发 +- 牌效: 5 向听，进张 82 张。 +- 防御： + 最安全牌放铳率：11.3% + 平均放铳率：18.5% + 最危险牌放铳率：25.9% +场上已见牌信息 +各玩家副露信息:本家副露：无, 下家副露：无, 对家副露：无, 上家副露：无 +各玩家牌河信息:本家：无, 下家：无, 对家：无, 上家：无 + +[任务] +根据当前情景，选择一张最应该打出的手牌。 +``` + +### 输出格式 + +模型输出严格为"单张牌文本"，不带"打"字，不带解释。例如： + +```text +白 +``` + +## 使用方法 + +### llama.cpp 推理 + +```bash +llama-server -m Qwen3-4B-Instruct-2507-mahjong-alpha.gguf -c 2048 +``` + +### Python 推理示例 + +```python +from transformers import AutoModelForCausalLM, AutoTokenizer + +model = AutoModelForCausalLM.from_pretrained( + "TTDXQ/Qwen3-4B-Instruct-2507-mahjong-alpha" +) +tokenizer = AutoTokenizer.from_pretrained( + "TTDXQ/Qwen3-4B-Instruct-2507-mahjong-alpha" +) + +# 准备输入 +input_text = "[情景分析]\n- 牌局: 东一局，你是庄家 (第1巡，牌墙余69张)。\n..." + +# 推理 +inputs = tokenizer(input_text, return_tensors="pt") +outputs = model.generate(**inputs, max_new_tokens=10) +result = tokenizer.decode(outputs[0], skip_special_tokens=True) +print(result) # 输出: 白 +``` + +## 数据集 + +训练数据使用 `pjura/mahjong_board_states` 的 2018 年部分数据。该数据集来源于天风麻将的游玩记录，每条数据包含 511 个数据点，涵盖游戏基础信息、宝牌指示牌、视角玩家手牌、玩家副露、牌河信息、玩家舍牌、弃牌决策等。 + +### 数据处理 + +将原始数据转换为便于阅读的自然语言描述形式，并根据数据计算出巡目数、实际宝牌、简易放铳参考等信息。根据巡目调整样本比例： + +- 1~3 巡：15% +- 4~6 巡：20% +- 7~12 巡：35% + +最终使用 `192000` 条样本，未混入通用指令数据或自建数据。 + +- 训练集：`192000` +- 验证集：`2000` +- 测试集：`2019 年数据按需抽取` +- 训练 / 验证 / 测试：完全互不重叠 + +### 数据集引用 + +```bibtex +@dataset{mahjong_board_states, + title = {MahJong Board States Dataset}, + author = {Patrick Jura}, + year = {2024}, + url = {https://huggingface.co/datasets/pjura/mahjong_board_states} +} +``` + +## 训练信息 + +### 模型配置 +- 基础模型：`unsloth/Qwen3-4B-Instruct-2507` +- 训练加载精度：`4bit` +- 微调方式：`QLoRA` +- 训练框架：`Unsloth` +- Max sequence length：`2048` + +### LoRA 参数 +- Rank：`128` +- Alpha：`256` +- 目标模块：全部 + +### 训练超参数 +- Learning rate：`1e-4` +- LR scheduler：`cosine` +- Batch size：`64` +- 单卡批次：`2` +- 梯度累积步数：`32` +- Training steps：`3000` +- Warmup steps：`300` +- Random seed：`3407` +- 加载最优检查点：是 + +### 训练时间 +- 总时长：约 16.44 小时 + +## 评测结果 + +### 与数据库弃牌动作对比 + +推理参数：Temperature=0.1, Top_P=0.1 + +**评测指标说明**： +- 得分：满分 500 分（每个样本正确得 1 分，错误得 0 分） +- 样本全对率：3 次测试均与测试集结果一致的样本占全部样本的比例 +- 样本零分率：3 次测试均与测试集结果不符的样本占全部样本的比例 + +#### 牌效测试 + +| 模型 | 方法 | 得分 | 样本全对率 | 样本零分率 | +|------|------|------|------------|------------| +| Qwen3-4B | 提示词工程 | 50.21 | 6.60% | 86.13% | +| Qwen3-4B | 微调 | 229.66 | 45.87% | 53.93% | +| DeepSeek-V3.2 | 提示词工程 | 181.66 | 21.40% | 46.33% | + +#### 防守测试 + +| 模型 | 方法 | 得分 | 样本全对率 | 样本零分率 | +|------|------|------|------------|------------| +| Qwen3-4B | 提示词工程 | 53.55 | 6.17% | 84.43% | +| Qwen3-4B | 微调 | 239.89 | 47.93% | 52.00% | +| DeepSeek-V3.2 | 提示词工程 | 172.00 | 16.00% | 46.80% | + +#### 综合测试 + +| 模型 | 方法 | 得分 | 样本全对率 | 样本零分率 | +|------|------|------|------------|------------| +| Qwen3-4B | 提示词工程 | 53.44 | 0.60% | 84.40% | +| Qwen3-4B | 微调 | 233.33 | 46.53% | 53.20% | +| DeepSeek-V3.2 | 提示词工程 | 179.44 | 18.07% | 44.93% | + +### 与 Mortal 对比 + +推理参数：Temperature=0.6, Top_P=0.95 + +#### 测试1：全部巡目数据 + +- 样本数：3000 +- Top-1 准确率：**50.73%** +- Top-3 准确率：**83.37%** + +#### 测试2：去除早巡数据 + +- 有效样本数：3000 +- Top-1 准确率：**48.70%** +- Top-3 准确率：**79.20%** + +> 注：Mortal 是当前开源最强的立直麻将 AI 之一 + +## 仓库链接 + +- GitHub：https://github.com/ttdxq/Qwen3-4B-Instruct-2507-mahjong-alpha +- Hugging Face：https://huggingface.co/TTDXQ/Qwen3-4B-Instruct-2507-mahjong-alpha + +## License + +本模型遵循 Apache License 2.0 许可证。 + +训练数据来自 `pjura/mahjong_board_states`，其许可证为 `CC BY 4.0`，使用时请保留相应署名与引用。 + +## Acknowledgements + +感谢以下开源资源： + +- `unsloth/Qwen3-4B-Instruct-2507` +- `pjura/mahjong_board_states` +- `Mortal`