docs: 添加英文版模型卡 README_en.md
- 保留相同的 YAML 元数据 - 完整的英文模型说明 - 与中文版内容对应
This commit is contained in:
TTDXQ
parent
cabd63252b
commit
6d03adb1ae
251
README_en.md
Normal file
251
README_en.md
Normal file
@ -0,0 +1,251 @@
|
||||
---
|
||||
license: apache-2.0
|
||||
datasets:
|
||||
- pjura/mahjong_board_states
|
||||
language:
|
||||
- zh
|
||||
base_model:
|
||||
- unsloth/Qwen3-4B-Instruct-2507
|
||||
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` is a Riichi Mahjong domain model fine-tuned from `unsloth/Qwen3-4B-Instruct-2507` with QLoRA.
|
||||
|
||||
It is designed for 4-player Riichi Mahjong discard recommendation: given round information, hand tiles, calls, visible tiles, tile-efficiency, and defense signals, the model outputs the single best discard tile for the current state.
|
||||
|
||||
The current version is mainly intended for tool integration. The output is a single tile text only, without explanation.
|
||||
|
||||
## Model Features
|
||||
|
||||
- **Task**: 4-player Riichi Mahjong discard recommendation
|
||||
- **Base Model**: `unsloth/Qwen3-4B-Instruct-2507`
|
||||
- **Fine-tuning**: `QLoRA`
|
||||
- **Training Framework**: `Unsloth`
|
||||
- **Release Format**: `GGUF (F16)`
|
||||
- **Inference**: `llama.cpp`
|
||||
- **Maintainer**: `TTDXQ`
|
||||
|
||||
## Scope
|
||||
|
||||
This model targets 4-player Riichi Mahjong without red dora. The current version focuses only on discard recommendation. It does not provide full-game planning, yaku/score analysis, or detailed offense-defense explanations.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Discard recommendation only
|
||||
- No full-game planning
|
||||
- No yaku, point calculation, or detailed strategic explanation
|
||||
- Not guaranteed for competitive or real-match performance
|
||||
- For research and learning purposes only
|
||||
|
||||
## Prohibited Uses
|
||||
|
||||
This model must not be used for:
|
||||
|
||||
- cheating
|
||||
- game automation or plug-ins
|
||||
- account boosting or ghost-playing
|
||||
- real-money gambling assistance
|
||||
|
||||
## Input and Output
|
||||
|
||||
### Input Format
|
||||
|
||||
The model input is a structured natural-language game-state description. Example:
|
||||
|
||||
```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%
|
||||
场上已见牌信息
|
||||
各玩家副露信息:本家副露：无, 下家副露：无, 对家副露：无, 上家副露：无
|
||||
各玩家牌河信息:本家：无, 下家：无, 对家：无, 上家：无
|
||||
|
||||
[任务]
|
||||
根据当前情景，选择一张最应该打出的手牌。
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
The output is strictly a single tile text without any prefix like "discard" and without explanation. Example:
|
||||
|
||||
```text
|
||||
白
|
||||
```
|
||||
|
||||
## How to Use
|
||||
|
||||
### Inference with llama.cpp
|
||||
|
||||
```bash
|
||||
llama-server -m Qwen3-4B-Instruct-2507-mahjong-alpha.gguf -c 2048
|
||||
```
|
||||
|
||||
### Python Inference Example
|
||||
|
||||
```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"
|
||||
)
|
||||
|
||||
# Prepare input
|
||||
input_text = "[情景分析]\n- 牌局: 东一局，你是庄家 (第1巡，牌墙余69张)。\n..."
|
||||
|
||||
# Inference
|
||||
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) # Output: 白
|
||||
```
|
||||
|
||||
## Dataset
|
||||
|
||||
The training data uses the 2018 subset of `pjura/mahjong_board_states`. This dataset originates from Tenhou.net gameplay records, with each record containing 511 data points covering game basics, dora indicators, player hand tiles, calls, discard piles, and discard decisions.
|
||||
|
||||
### Data Processing
|
||||
|
||||
The raw data was converted into human-readable natural language descriptions, with calculated turn numbers, actual dora, and simplified risk assessment. Sample distribution by turn:
|
||||
|
||||
- Turns 1-3: 15%
|
||||
- Turns 4-6: 20%
|
||||
- Turns 7-12: 35%
|
||||
|
||||
A total of `192000` samples were used, with no general instruction data or self-built data mixed in.
|
||||
|
||||
- Train: `192000`
|
||||
- Validation: `2000`
|
||||
- Test: sampled as needed from 2019 data
|
||||
- Train / validation / test are fully non-overlapping
|
||||
|
||||
### Dataset Citation
|
||||
|
||||
```bibtex
|
||||
@dataset{mahjong_board_states,
|
||||
title = {MahJong Board States Dataset},
|
||||
author = {Patrick Jura},
|
||||
year = {2024},
|
||||
url = {https://huggingface.co/datasets/pjura/mahjong_board_states}
|
||||
}
|
||||
```
|
||||
|
||||
## Training Details
|
||||
|
||||
### Model Configuration
|
||||
- Base Model: `unsloth/Qwen3-4B-Instruct-2507`
|
||||
- Training Precision: `4bit`
|
||||
- Fine-tuning Method: `QLoRA`
|
||||
- Framework: `Unsloth`
|
||||
- Max Sequence Length: `2048`
|
||||
|
||||
### LoRA Parameters
|
||||
- Rank: `128`
|
||||
- Alpha: `256`
|
||||
- Target Modules: All
|
||||
|
||||
### Training Hyperparameters
|
||||
- Learning Rate: `1e-4`
|
||||
- LR Scheduler: `cosine`
|
||||
- Batch Size: `64`
|
||||
- Per-device Batch: `2`
|
||||
- Gradient Accumulation Steps: `32`
|
||||
- Training Steps: `3000`
|
||||
- Warmup Steps: `300`
|
||||
- Random Seed: `3407`
|
||||
- Load Best Checkpoint: Yes
|
||||
|
||||
### Training Time
|
||||
- Total Duration: ~16.44 hours
|
||||
|
||||
## Evaluation Results
|
||||
|
||||
### Comparison with Dataset Actions
|
||||
|
||||
Inference parameters: Temperature=0.1, Top_P=0.1
|
||||
|
||||
**Metrics Explanation:**
|
||||
- Score: Max 500 points (1 point per correct sample, 0 for incorrect)
|
||||
- Full-match Rate: Samples where all 3 tests matched the dataset
|
||||
- Zero-score Rate: Samples where all 3 tests disagreed with the dataset
|
||||
|
||||
#### Tile-Efficiency Test
|
||||
|
||||
| Model | Method | Score | Full-match Rate | Zero-score Rate |
|
||||
|-------|--------|-------|----------------|-----------------|
|
||||
| Qwen3-4B | Prompt Engineering | 50.21 | 6.60% | 86.13% |
|
||||
| Qwen3-4B | Fine-tuned | 229.66 | 45.87% | 53.93% |
|
||||
| DeepSeek-V3.2 | Prompt Engineering | 181.66 | 21.40% | 46.33% |
|
||||
|
||||
#### Defense Test
|
||||
|
||||
| Model | Method | Score | Full-match Rate | Zero-score Rate |
|
||||
|-------|--------|-------|----------------|-----------------|
|
||||
| Qwen3-4B | Prompt Engineering | 53.55 | 6.17% | 84.43% |
|
||||
| Qwen3-4B | Fine-tuned | 239.89 | 47.93% | 52.00% |
|
||||
| DeepSeek-V3.2 | Prompt Engineering | 172.00 | 16.00% | 46.80% |
|
||||
|
||||
#### Comprehensive Test
|
||||
|
||||
| Model | Method | Score | Full-match Rate | Zero-score Rate |
|
||||
|-------|--------|-------|----------------|-----------------|
|
||||
| Qwen3-4B | Prompt Engineering | 53.44 | 0.60% | 84.40% |
|
||||
| Qwen3-4B | Fine-tuned | 233.33 | 46.53% | 53.20% |
|
||||
| DeepSeek-V3.2 | Prompt Engineering | 179.44 | 18.07% | 44.93% |
|
||||
|
||||
### Comparison with Mortal
|
||||
|
||||
Inference parameters: Temperature=0.6, Top_P=0.95
|
||||
|
||||
#### Test 1: All Turn Data
|
||||
|
||||
- Samples: 3000
|
||||
- Top-1 Accuracy: **50.73%**
|
||||
- Top-3 Accuracy: **83.37%**
|
||||
|
||||
#### Test 2: Excluding Early Turns
|
||||
|
||||
- Valid Samples: 3000
|
||||
- Top-1 Accuracy: **48.70%**
|
||||
- Top-3 Accuracy: **79.20%**
|
||||
|
||||
> Note: Mortal is one of the strongest open-source Riichi Mahjong AIs currently available
|
||||
|
||||
## Repository Links
|
||||
|
||||
- GitHub: https://github.com/ttdxq/Qwen3-4B-Instruct-2507-mahjong-alpha
|
||||
- Hugging Face: https://huggingface.co/TTDXQ/Qwen3-4B-Instruct-2507-mahjong-alpha
|
||||
|
||||
## License
|
||||
|
||||
This model follows the Apache License 2.0.
|
||||
|
||||
The training data comes from `pjura/mahjong_board_states`, which is licensed under `CC BY 4.0`. Please preserve the required attribution and citation when using it.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Thanks to the following open-source resources:
|
||||
|
||||
- `unsloth/Qwen3-4B-Instruct-2507`
|
||||
- `pjura/mahjong_board_states`
|
||||
- `Mortal`
|
||||
Loading…
Reference in New Issue
Block a user