Xiangqi-R1: LLM for Chinese Chess Reasoning

• Xiangqi-R1 is a 7B-parameter large language model specialized for spatial reasoning in Chinese chess, achieving an 18% improvement in move legality and a 22% boost in analysis accuracy.
• It employs a rigorous three-stage training pipeline—legal move prediction, strategic annotation, and reinforcement learning with GRPO—to seamlessly integrate rule compliance with strategic evaluation.
• The model leverages extensive game records, engine annotations via Pikafish, and reward decomposition to precisely calibrate legal moves, analysis quality, and formatted output.

Searching arXiv for Xiangqi-R1 and closely related Xiangqi research. Xiangqi-R1 is a 7B-parameter LLM specialized for spatial strategic reasoning in Chinese chess (Xiangqi). Trained from Qwen-2.5-7B-Instruct in three stages—legal move prediction, strategic annotation incorporation, and reinforcement learning with Group Relative Policy Optimization (GRPO)—it is designed to analyze a board position, produce a legal move, and supply structured reasoning under Xiangqi’s unusually rigid spatial constraints. The system is presented as a domain-specific response to the observation that general-purpose LLMs remain unreliable on rule-heavy board-game reasoning, especially on tasks requiring simultaneous legality, evaluation, and move quality; relative to Doubao-Pro-1.5-Think, the reported gains are an 18% rise in move legality and a 22% boost in analysis accuracy (Chen et al., 16 Jul 2025).

1. Benchmark role and problem formulation

Xiangqi-R1 is framed around Xiangqi as a benchmark for spatial strategic reasoning rather than as a conventional search engine. The motivating claim is that Xiangqi exposes deficiencies that may be obscured on broader language benchmarks or on international chess alone, because it is fully observable and deterministic while remaining highly constrained by board geometry and piece-specific rules (Chen et al., 16 Jul 2025).

Several rule features are central to that framing. Xiangqi is played on a $9\times 10$ board; it includes a river boundary, $3\times 3$ palaces, the “facing kings” rule, and asymmetric movement restrictions such as elephants not crossing the river, knights being blockable, cannons capturing only by jumping exactly one piece, and kings and guards being confined to the palace. In the paper’s terminology, competence therefore consists not merely in emitting plausible move text, but in carrying out a sequence of operations: interpret the board correctly, analyze the situation, and output a legal move (Chen et al., 16 Jul 2025).

This formulation is narrower than full engine play and broader than move legality alone. The model is evaluated both on move suggestion and on position analysis. Move quality is stratified into legality, “good” moves, and engine-best moves; analysis quality is treated as a classification problem over 3-class and 5-class situation labels derived from engine evaluations. A plausible implication is that Xiangqi-R1 is intended as a probe of whether an LLM can internalize domain structure strongly enough to support both symbolic compliance and strategic judgment in the same output channel.

2. Data curation, normalization, and engine annotation

The training corpus is built from public open-source Xiangqi game records. The raw collection contains 182,342 games in PGN format, which are parsed and converted to FEN with the cchess library. The resulting examples are organized as $(\text{FEN}, \text{Move})$, $(\text{FEN}, \text{Move}, \text{Comment})$, or $$(\text{FEN}, \text{Move}, \text{Comment}, \text{Score})$$ depending on the training stage (Chen et al., 16 Jul 2025).

A notable filtering rule is asymmetric with respect to game outcome. The authors keep moves made by the winning side in decisive games, keep both sides’ moves in drawn games, and exclude the losing side’s moves in decisive games. Commentary is additionally cleaned: only comments related to Xiangqi are retained, and irrelevant or sensitive content is removed using DeepSeek-V3. The paper also restricts commentary-bearing samples to moves judged high-quality by engine evaluation (Chen et al., 16 Jul 2025).

Pikafish is the engine used for evaluation and annotation, with search depth fixed at 25 plies. A move is labeled as a GoodMove when its engine value after play is within $\sigma_{\text{good}} = 100$ centipawns of the best move. Position labels are similarly derived from engine values, with $\sigma_s = 100$ and $\sigma_l = 800$, yielding either a 5-class scheme—significant/slight advantage for Red or Black, plus balanced—or a 3-class simplification formed by merging slight and clear advantage into a single advantage class (Chen et al., 16 Jul 2025).

Stage	Sample structure	Size
Stage 1	$(\text{FEN}, \text{Move})$	5,109,543
Stage 2	annotated samples with commentary	52,913
Stage 3	annotated samples with commentary and engine scores	52,800

The test set contains 2,800 high-quality samples. The scale disparity between Stage 1 and Stages 2–3 is consequential: the first stage supplies broad legal-move supervision, whereas later stages inject denser strategic signals and engine-linked reward structure. This suggests a deliberate curriculum from rule acquisition to strategic calibration.

3. Model architecture and three-stage training pipeline

Xiangqi-R1 is initialized from Qwen-2.5-7B-Instruct and trained in a multi-stage manner. Stage 1 is fine-tuning for legal move prediction on 5,109,543 board–move pairs. Inputs are expressed as board state in FEN or BoardStr, and outputs are moves in ICCS/CFF-like move notation. The resulting model, SFT-Stage1-7B, is reported to reach $\text{legal@1} = 0.9221$, indicating that the model usually outputs a valid move on the test set after this stage (Chen et al., 16 Jul 2025).

Stage 2 incorporates strategic annotations. Using 52,913 samples with expert commentary, the training objective expands from move generation to analysis-plus-move recommendation. This stage is intended to improve position evaluation and natural-language strategic explanation. The paper notes that analysis improves substantially over Stage 1, while pure move accuracy can drop somewhat because the output task becomes harder: the model must connect board state, evaluation, move choice, and reasoning in a single response (Chen et al., 16 Jul 2025).

Stage 3 applies reinforcement learning through GRPO, initialized from the Stage 2 model. The training data for this stage consist of 52,800 samples with precomputed engine evaluations for all legal moves. GRPO is described operationally rather than through a full formal derivation: for each state, a group of candidate outputs is sampled; rewards are computed for each output; group-relative advantages are formed; and the policy is updated while a KL regularizer keeps it close to the Stage 2 reference policy. The stated purpose is to improve both performance and stability (Chen et al., 16 Jul 2025).

The three-stage organization is central to the identity of Xiangqi-R1. The first stage teaches rule compliance, the second stage introduces strategic semantics through commentary, and the third stage sharpens the alignment between analysis, format, and move quality under engine-informed reinforcement learning. In that respect, Xiangqi-R1 is neither a pure imitation model nor a pure self-play agent.

4. Reinforcement learning objective, reward decomposition, and implementation

The reinforcement-learning stage uses a three-part reward: Move Reward, Analysis Reward, and Format Reward. The Move Reward is multi-level and depends on legality, “good” status, and equality with the engine-best move. Its indicators are $3\times 3$0, $3\times 3$1, and $3\times 3$2, with the reward described as the sum of legality, quality, and optimality components (Chen et al., 16 Jul 2025).

The Analysis Reward is binary: it is 1 when the model’s situation analysis matches the engine’s assessment and 0 otherwise. The Format Reward is also binary and requires the response to separate reasoning and final answer using <Think>...</Think> and <Answer>...</Answer>. The paper states that if the format is wrong, move and analysis rewards cannot be properly assigned, so the overall reward becomes zero. This makes format correctness a gating condition for the other objectives (Chen et al., 16 Jul 2025).

The reward design is explicitly justified as a stabilization mechanism. Move reward enforces legality and move quality; analysis reward trains position judgment; format reward reduces noisy outputs and makes reward assignment tractable. The authors characterize the resulting signal as more interpretable and more conducive to reasoning stability. A plausible implication is that the RL phase is used less for discovering game-theoretic novelty than for calibrating a structured response policy under decomposed supervision.

The reported implementation uses 4× NVIDIA A6000 GPUs, BF16 mixed precision, gradient checkpointing, DeepSpeed ZeRO-2, CPU offloading, LoRA fine-tuning, and the TRL library for GRPO. Hyperparameters reported for all stages include learning rate $3\times 3$3, LoRA rank 16, LoRA alpha 32, LoRA dropout 0.1, rollout 8, and maximum generation length 2048 tokens at evaluation (Chen et al., 16 Jul 2025).

5. Evaluation protocol, quantitative results, and ablations

The evaluation separates move suggestion from situation analysis. Move metrics are top-$3\times 3$4 sampling-based: legal@$3\times 3$5, good@$3\times 3$6, and best@$3\times 3$7, where “good” denotes a move within 100 centipawns of the best move. Analysis metrics are 3-class@$3\times 3$8 and 5-class@$3\times 3$9. The paper evaluates analysis only when the model also produces a valid move, on the grounds that invalid move generation indicates inadequate board understanding for meaningful analysis (Chen et al., 16 Jul 2025).

Baselines are divided into direct-answer models and reasoning models. The direct-answer set includes Qwen-2.5-7B-Instruct, Doubao-Lite, DeepSeek-V3, and Doubao-Pro-1.5. The reasoning set includes R1-Distill-Qwen-7B, DeepSeek-R1, and Doubao-Pro-1.5-Think. Against this backdrop, Xiangqi-R1 reports the following main results: $(\text{FEN}, \text{Move})$0, $(\text{FEN}, \text{Move})$1, $(\text{FEN}, \text{Move})$2, $(\text{FEN}, \text{Move})$3, $(\text{FEN}, \text{Move})$4, $(\text{FEN}, \text{Move})$5, $(\text{FEN}, \text{Move})$6, $(\text{FEN}, \text{Move})$7, $(\text{FEN}, \text{Move})$8, and $(\text{FEN}, \text{Move})$9 (Chen et al., 16 Jul 2025).

The headline comparative claim is an 18% improvement in legal@1 and a 22% improvement in 3-class@1 relative to Doubao-Pro-1.5-Think. The broader interpretation offered by the paper is that larger general models remain weak on legal move generation and high-quality analysis, whereas domain-specialized training yields better performance even at 7B parameters (Chen et al., 16 Jul 2025).

Ablation studies isolate the reward components. Removing $(\text{FEN}, \text{Move}, \text{Comment})$0 reduces legal@1 from 0.9521 to 0.8736 and best@1 from 0.1814 to 0.1296. Removing $(\text{FEN}, \text{Move}, \text{Comment})$1 lowers 3-class@1 from 0.6286 to 0.4846 and 5-class@1 from 0.6104 to 0.4446. Removing both move and analysis rewards weakens performance across nearly all metrics, which the authors interpret as evidence of synergy among the reward terms (Chen et al., 16 Jul 2025).

Further analysis examines positions with 5 to 32 pieces. Opening positions are easier, middlegame positions are harder, and endgames are especially difficult for analysis. Legal@1 remains consistently high around 0.95, whereas best@1 declines in more complex middlegame regions and analysis accuracy declines as piece count decreases. Piece-type analysis shows better performance on pawns and rooks, and worse performance on kings and elephants; the king is described as especially difficult because legality depends on palace constraints, the face-to-face king rule, and check conditions, with a lowest success rate around 0.859, although the model still achieves over 95% overall success across piece types after training (Chen et al., 16 Jul 2025).

6. Relation to other Xiangqi AI and computational-complexity research

Xiangqi-R1 occupies a distinct position within recent Xiangqi research. It is not a search-based engine in the AlphaZero sense, nor a direct analogue of search-free policy/value systems aimed at competitive ladder play. A separate paper, "Mastering Chinese Chess AI (Xiangqi) Without Search" (Chen et al., 2024), also uses the designation Xiangqi-R1 for a Chinese Chess AI trained without tree search. That system combines supervised learning and reinforcement learning, uses a ViT backbone, incorporates explicit legality features for both sides, and reports top-0.1% human-ladder strength together with QPS more than $(\text{FEN}, \text{Move}, \text{Comment})$2 higher than MCTS-based systems and more than $(\text{FEN}, \text{Move}, \text{Comment})$3 higher than AlphaBeta-based systems. The overlap in naming is therefore terminological rather than methodological (Chen et al., 2024).

Other contemporary Xiangqi systems are organized around search. "Deep Reinforcement Learning Xiangqi Player with Monte Carlo Tree Search" (Yilmaz et al., 18 Jun 2025) describes an AlphaZero-like policy-value network plus MCTS, initialized by supervised pretraining on 141,484 games and 11,683,480 total moves. "JiangJun: Mastering Xiangqi by Tackling Non-Transitivity in Two-Player Zero-Sum Games" (Li et al., 2023) combines MCTS with Policy Space Response Oracles to approximate a maximum-entropy Nash equilibrium over a policy population, motivated by empirical non-transitivity in Xiangqi and reporting a 99.41% win rate against human players in a WeChat mini program. Relative to these systems, Xiangqi-R1 is best understood as an LLM-centered reasoning model whose outputs are judged by legality and strategic analysis rather than by full-engine matchplay alone (Yilmaz et al., 18 Jun 2025, Li et al., 2023).

The broader theoretical backdrop also supports the use of Xiangqi as a demanding reasoning domain. "A Note on Hardness Frameworks and Computational Complexity of Xiangqi and Janggi" proves that Xiangqi is EXPTIME-complete through constructive gadget reductions in generalized settings (Zhang, 2019). More specifically, "King Chasing Problem in Chinese Chess is NP-hard" shows that a natural restricted subproblem of generalized Xiangqi—continuous checking until eventual mate—is NP-hard by reduction from 3-SAT (Li et al., 2 Apr 2026). These results concern formalized decision versions of generalized Xiangqi rather than the training protocol of Xiangqi-R1, but they reinforce the view that the game’s tactical motifs and spatial constraints support computationally rich structure.

Taken together, the surrounding literature situates Xiangqi-R1 within a heterogeneous research landscape. Search-based systems emphasize lookahead and equilibrium robustness; no-search engines emphasize throughput and competitive play; complexity-theoretic work emphasizes hardness in generalized formulations. Xiangqi-R1 contributes a different axis: domain-specialized LLM training for legality, analysis, and structured reasoning under strict spatial rules (Chen et al., 16 Jul 2025).