# chess-ai-baseline

**Repository Path**: luzhihaoTestingLab/chess-ai-baseline

## Basic Information

- **Project Name**: chess-ai-baseline
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChessTransformer

基于 Transformer 的国际象棋 AI 模型，使用自监督学习从 PGN 棋谱中学习走棋策略（Policy）和局面评估（Value）。

## 项目结构

```
.
├── encoding.py          # 棋盘编码：将棋盘转为 (18, 8, 8) 张量
├── model.py             # Transformer 模型定义（Policy + Value 双头）
├── dataset.py           # 流式 PGN 数据集，支持 .bz2 压缩文件
├── train.py             # 训练脚本
├── play.py              # 命令行 AI 自弈脚本
├── web_viewer.py        # Flask Web 界面，支持 AI 自弈和人机对战
├── assets/              # PGN 棋谱数据（.pgn.bz2 格式）
└── models/              # 训练好的模型权重
```

## 环境要求

- Python 3.10+
- PyTorch 2.0+
- python-chess
- Flask（仅 Web 界面需要）
- numpy, tqdm

### 安装依赖

```bash
pip install torch python-chess flask numpy tqdm
```

## 快速开始

### 1. 准备数据

将 PGN 棋谱文件放入 `assets/` 目录。项目已包含 2020-2025 年 FICS 数据库的棋谱（`.pgn.bz2` 压缩格式，约 2000+ 分以上的对局），数据集会自动识别并建立索引。

### 2. 训练模型

```bash
python -m train --games 50000 --epochs 5 --batch-size 768
```

主要参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--games` | 50000 | 训练使用的对局数量 |
| `--epochs` | 5 | 训练轮数 |
| `--batch-size` | 768 | 批次大小 |
| `--lr` | 3e-4 | 学习率 |
| `--d-model` | 256 | Transformer 嵌入维度 |
| `--n-layers` | 6 | Transformer 层数 |
| `--file` | 自动检测 | 指定 PGN 文件路径 |
| `--resume` | 无 | 从 checkpoint 恢复训练 |
| `--device` | auto | 设备选择（auto/cpu/cuda） |

训练完成后模型默认保存为 `chess_model_YYYYMMDD_HHMMSS.pt`。

### 3. AI 自弈（命令行）

加载训练好的模型，观看 AI 双方对弈：

```bash
python -m play --model models/chess_model_20260614_130050.pt
```

参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--model` | chess_model.pt | 模型权重路径 |
| `--auto` | 否 | 自动播放模式 |
| `--delay` | 0.5 | 自动模式每步间隔（秒） |
| `--device` | auto | 设备选择 |

### 4. Web 界面

启动 Flask Web 服务，在浏览器中观看 AI 自弈或进行人机对战：

```bash
python web_viewer.py --model models/chess_model_20260614_130050.pt --port 5000
```

然后打开浏览器访问 `http://127.0.0.1:5000`。

功能：
- **AI 自弈模式**：观看模型双方对弈，支持逐步走棋和自动播放
- **人机对战模式**：选择执白或执黑，与 AI 对弈

## 模型架构

### 输入编码（18 通道）

| 通道 | 内容 |
|------|------|
| 0-5 | 白方棋子（兵、马、象、车、后、王） |
| 6-11 | 黑方棋子（兵、马、象、车、后、王） |
| 12 | 当前走棋方 |
| 13-16 | 王车易位权利（白王翼/白后翼/黑王翼/黑后翼） |
| 17 | 过路兵目标格 |

### 网络结构

- **Input Projection**：Conv2d 将 18 通道映射到 d_model 维度
- **Positional Encoding**：可学习的 8×8 位置编码
- **Transformer Encoder**：多层 Pre-LN Transformer（默认 6 层，8 头）
- **Policy Head**：通过空间外积（from/to embedding）生成 4096 个非升变走法 + 16384 个升变走法的 logits
- **Value Head**：MLP → Tanh，输出 [-1, +1] 的局面评估

### 损失函数

- Policy Loss：CrossEntropy（走法分类）
- Value Loss：MSE（局面评估回归）
- 总损失 = Policy Loss + Value Loss

## 输出维度

- **N_MOVES = 4096 + 64×64×4 = 20480**
  - 4096：非升变走法（64 起点 × 64 终点）
  - 16384：升变走法（64 起点 × 64 终点 × 4 种升变选择）