四人帮神经网络 AI v3

一个用于玩四人帮纸牌游戏（中国爬牌游戏）的神经网络模型。

模型描述

该模型通过从专家策略演示中进行模仿学习来预测最优出牌。它使用自定义架构，包含牌注意力机制来捕捉不同牌区之间的关系。

架构

• 牌注意力：对4个牌区（手牌、已出牌、当前轮次、对手估算）进行多头自注意力
• 残差块：3个带有LayerNorm和GELU激活的残差MLP块
• 双头：分离的策略头（40个动作）和声明头（二进制）
• 参数：约92万个可训练参数

输入编码（328个特征）

输出

• action_logits：(batch, 40) 每个动作的logits（动作0 = 过）
• declare_prob：(batch, 1) 声明最后一张牌的概率（"Carte!"）

使用方法

快速开始（完整示例）

from huggingface_hub import hf_hub_download
import torch
import sys

# 下载所有必要的文件
for filename in ["modeling_gangoffour.py", "game_utils.py", "rules.py", "config.json", "model.safetensors"]:
    hf_hub_download(repo_id="quintana42/gang-of-four-neural", filename=filename, local_dir="./model")

sys.path.insert(0, "./model")
from modeling_gangoffour import GangOfFourNet
from game_utils import Card, GameEncoder, decode_action

# 加载模型
model = GangOfFourNet.from_pretrained("./model")
model.eval()

# 从字符串表示解析你的手牌
hand = Card.parse_hand("1G 3R 5Y 7G 10R Dragon")
print(f"Hand: {[str(c) for c in hand]}")

# 定义有效出牌（在实际游戏中，来自游戏规则）
valid_plays = [
    [],           # 过
    [hand[0]],    # 出1G
    [hand[1]],    # 出3R
    [hand[2]],    # 出5Y
]

# 编码游戏状态
encoder = GameEncoder()
state, ordered_plays = encoder.encode_simple(
    hand=hand,
    valid_plays=valid_plays,
    is_leading=True,  # 我们领先（没有要击败的轮次）
)

# 运行推理
state_tensor = torch.tensor(state).unsqueeze(0)
mask_tensor = torch.tensor(state[256:296]).unsqueeze(0)

with torch.no_grad():
    logits, declare_prob = model(state_tensor, mask_tensor)

# 解码结果
action_idx = logits.argmax(dim=1).item()
chosen_play = decode_action(action_idx, ordered_plays)

if chosen_play is None:
    print("Model chose: PASS")
else:
    print(f"Model chose: {[str(c) for c in chosen_play]}")
print(f"Declare last card probability: {declare_prob.item():.3f}")

牌的表示法

使用简单的字符串表示法解析牌：

from game_utils import Card

# 单张牌
card = Card.parse("5G")       # 5绿色
card = Card.parse("10R")      # 10红色
card = Card.parse("1M")       # 多色1
card = Card.parse("Dragon")   # 龙
card = Card.parse("PhoenixG") # 凤凰绿色

# 多张牌
hand = Card.parse_hand("1G 3R 5Y Dragon PhoenixY")

牌索引映射

64张牌映射到索引0-63：

数字牌公式：(rank - 1) * 6 + color_idx * 2 + copy 其中color_idx：绿色=0，黄色=1，红色=2

动作编码

动作根据有效出牌动态编码：

• 动作0：总是过（PASS）
• 动作1-39：按（长度，等级和，颜色和）排序的有效出牌

编码器返回的ordered_plays列表将动作索引映射到实际出牌。

生成有效出牌

使用rules.py根据游戏规则生成有效出牌：

from game_utils import Card
from rules import get_valid_plays, get_combination_type, can_beat

# 你的手牌和要击败的轮次
hand = Card.parse_hand("4G 4Y 4R 4G 7R 7Y 10G")
trick = Card.parse_hand("6G 6R")  # 一对6

# 获取所有合法出牌
valid_plays = get_valid_plays(hand, trick_to_beat=trick)

for play in valid_plays:
    if play:
        combo_type = get_combination_type(play)
        print(f"{combo_type}: {[str(c) for c in play]}")
    else:
        print("PASS")
# 输出：
#   pair: ['7R', '7Y']
#   gang_of_four: ['4G', '4Y', '4R', '4G']  # 四张同点数可以击败任何牌！
#   PASS

# 检查特定出牌是否击败轮次
play = Card.parse_hand("8G 8Y")
print(can_beat(play, trick))  # True

rules.py中的关键函数：

• get_valid_plays(hand, trick_to_beat) - 获取所有合法出牌
• get_combination_type(cards) - 识别组合（单张、对子、四张等）
• can_beat(play, trick) - 检查出牌是否合法击败轮次
• get_all_combinations(hand) - 从手牌获取所有可能的组合

使用from_pretrained

from modeling_gangoffour import GangOfFourNet

# 从Hugging Face Hub加载
model = GangOfFourNet.from_pretrained("quintana42/gang-of-four-neural")

# 或从本地目录加载
model = GangOfFourNet.from_pretrained("./my_local_model")

# 使用GPU
model = GangOfFourNet.from_pretrained("quintana42/gang-of-four-neural", device="cuda")

保存你自己的模型

# 训练后
model.save_pretrained("./my_trained_model")

示例

Web顾问（WASM）

一个使用ONNX Runtime Web的完整浏览器示例：

gang-of-four-web-advisor

特性：

• 100%客户端（初次加载后可离线运行）
• 使用带有WebAssembly推理的ONNX模型
• 完整的JavaScript规则实现
• 无框架，原生JS

训练

该模型通过从专家启发式策略进行模仿学习来训练：

• 数据集：约50万个游戏状态-动作对
• 训练：动作使用交叉熵损失，声明使用BCE
• 优化器：AdamW（lr=1e-3，weight_decay=0.01）
• 轮次：50轮，带有早停（patience=10）

游戏规则

四人帮是一个类似于大老二/提楚的中国爬牌游戏：

• 牌组：64张牌（1-10数字在3种颜色×2张，加上龙和2只凤凰）
• 目标：最先清空手牌
• 组合：单张、对子、三张、顺子、同花、葫芦、同花顺、四张（4张或更多相同点数）
• 计分：剩余牌扣分；先到100分者输

文件

• config.json - 模型配置
• model.safetensors - 模型权重（safetensors格式）
• modeling_gangoffour.py - 带有from_pretrained支持的模型代码
• game_utils.py - 编码/解码工具（Card, GameEncoder, decode_action）
• rules.py - 游戏规则（get_valid_plays, can_beat, get_combination_type）

要求

torch>=2.0.0
safetensors>=0.4.0
huggingface_hub>=0.20.0

引用

@misc{gangoffour-neural,
  author = {quintana42},
  title = {Gang of Four Neural AI},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/quintana42/gang-of-four-neural}
}

许可证

MIT许可证