能力标签

🤖 Agent 🔄 工作流 🔗 REST API 🧠 Claude ✨ GPT 🖥 本地 LLM

🛠

AI工具

LLMChess

基于 Python · 开源免费，本地部署，数据完全自主可控

英文名：llm_chess

⭐ 102 Stars 🍴 9 Forks 💻 Python 📄 Apache-2.0 🏷 AI 7.5分

7.5AI 综合评分

AIChessLLM

🌐 访问官网

✦ AI Skill Hub 推荐

经 AI Skill Hub 精选评估，LLMChess 获评「推荐使用」。这款AI工具在功能完整性、社区活跃度和易用性方面表现出色，AI 评分 7.5 分，适合有一定技术背景的用户使用。

📚 深度解析

LLMChess 是一款基于 Python 的开源工具，在 GitHub 上收获 0k+ Star，是AI、Chess、LLM领域中的优质开源项目。开源工具的最大优势在于代码完全透明，你可以审计每一行代码的安全性，也可以根据自身需求进行二次开发和定制。

**为什么要使用开源工具而非商业 SaaS？**
对于个人开发者和有隐私需求的用户，本地部署的开源工具意味着数据不离本机，不受第三方服务商的数据政策约束。同时，开源工具通常没有使用次数限制和月度费用，一次安装即可长期使用，对于高频使用场景的总拥有成本（TCO）远低于订阅制商业工具。

**安装与环境准备**
LLMChess 依赖 Python 运行环境。建议通过 pyenv（Python）或 nvm（Node.js）管理 Python 版本，避免全局环境污染。对于新手用户，推荐先创建虚拟环境（python -m venv venv && source venv/bin/activate），再安装依赖，这样即使出现问题也可以随时删除虚拟环境重新开始，不影响系统稳定性。

**社区与维护**
GitHub Issue 和 Discussion 是获取帮助的最快渠道。在提问前建议先检查 Closed Issues（已关闭的问题），大多数常见问题都已有解答。遇到 Bug 时，提供 pip list 的输出、完整错误堆栈和最小可复现示例，能显著提高开发者响应速度。AI Skill Hub 将持续追踪 LLMChess 的版本更新，及时通知重要功能变化。

📋 工具概览

LLMChess 是一款基于 Python 开发的开源工具，专注于 AI、Chess、LLM 等核心功能。作为 GitHub 开源项目，它拥有活跃的社区支持和持续的版本迭代，代码完全透明可审计，支持本地部署以保护数据隐私。无论是个人使用还是集成到企业工作流，都能提供稳定可靠的解决方案。

GitHub Stars

⭐ 102

开发语言

Python

支持平台

Windows / macOS / Linux

维护状态

轻量级项目，按需更新

开源协议

Apache-2.0

AI 综合评分

7.5 分

工具类型

AI工具

Forks

📖 中文文档

以下内容由 AI Skill Hub 根据项目信息自动整理，如需查看完整原始文档请访问底部「原始来源」。

📌 核心特色

开源免费，支持本地部署，数据完全自主可控
活跃的 GitHub 开源社区，持续迭代更新
提供详细文档和使用示例，新手友好
支持自定义配置，灵活适配不同使用环境
可作为基础组件集成进现有技术栈或进行二次开发

🎯 主要使用场景

本地部署运行，保护数据隐私，满足合规要求
自定义集成到现有系统，扩展技术栈能力
作为开源基础组件进行商业化二次开发

以下安装命令基于项目开发语言和类型自动生成，实际以官方 README 为准。

安装命令

# 方式一：pip 安装（推荐）
pip install llm_chess

# 方式二：虚拟环境安装（推荐生产环境）
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install llm_chess

# 方式三：从源码安装（获取最新功能）
git clone https://github.com/maxim-saplin/llm_chess
cd llm_chess
pip install -e .

# 验证安装
python -c "import llm_chess; print('安装成功')"

📋 安装步骤说明

访问 GitHub 仓库页面
按照 README 文档完成依赖安装
根据系统环境完成初始化配置
参考官方示例或文档开始使用
遇到问题可在 GitHub Issues 中查找解答

以下用法示例由 AI Skill Hub 整理，涵盖最常见的使用场景。

常用命令 / 代码示例

# 命令行使用
llm_chess --help

# 基本用法
llm_chess input_file -o output_file

# Python 代码中调用
import llm_chess

# 示例
result = llm_chess.process("input")
print(result)

以下配置示例基于典型使用场景生成，具体参数请参照官方文档调整。

配置示例

# llm_chess 配置文件示例（config.yml）
app:
  name: "llm_chess"
  debug: false
  log_level: "INFO"

# 运行时指定配置文件
llm_chess --config config.yml

# 或通过环境变量配置
export LLM_CHESS_API_KEY="your-key"
export LLM_CHESS_OUTPUT_DIR="./output"

📑 README 深度解析真实文档完整度 49/100 查看 GitHub 原文 →

以下内容由系统直接从 GitHub README 解析整理，保留代码块、表格与列表结构。

LLM Chess: Benchmarking Reasoning and Instruction-Following in LLMs

LLM Chess is a benchmark that evaluates Large Language Models (LLMs) on their reasoning and instruction-following abilities in an agentic setting. LLMs engage in multi-turn dialogs to play chess against opponents like a Random Player or the Komodo Dragon chess engine. This setup tests both strategic reasoning (chess skill) and protocol adherence (sustained interaction without errors).

Key insights from the benchmark: - Early models (2024) struggled with basic instruction following, often hallucinating illegal moves or failing dialogs. - Advanced reasoning models (e.g., o1, o3, o4-mini) in 2025 saturated random-based evaluations, prompting the addition of Dragon as a stronger opponent for Elo anchoring. - Metrics separate chess skill (Win/Loss, Elo) from durability (Game Duration), revealing trade-offs in model capabilities.

See the live leaderboard for rankings and the NeurIPS FoRLM 2025 paper for full details.

Installation and Setup

1. Clone the repository:

   git clone https://github.com/maxim-saplin/llm_chess.git
   cd llm_chess

2. Create a virtual environment (recommended):

   # Using uv (recommended)
   uv sync

3. Install dependencies:

   # Already handled by `uv sync` above

4. Configure LLMs: - Copy .env.sample to .env and add your API keys. - Suffixes like _W (white) and _B (black) distinguish configs for multi-LLM setups. - Supports Azure OpenAI chat completions (MODEL_KIND=azure), Azure OpenAI Responses API (MODEL_KIND=azure_responses), OpenAI, Anthropic, Google, Groq, and local models via Autogen. - For local models, ensure Ollama or LM Studio is running.

5. Chess Engines (optional, for stronger opponents): - Komodo Dragon: Download binaries from komodochess.com and place in dragon/. Set llm_chess.dragon_path. - Stockfish: Install via brew install stockfish (macOS) or equivalent. Set llm_chess.stockfish_path (default: /opt/homebrew/bin/stockfish).

Sample Dialog (Single Move)

Example with GPT-4o Mini (Black):

Proxy (to Player_Black):
You are a professional chess player and you play as black. Now is your turn to make a move. Before making a move you can pick one of the following actions:
- 'get_current_board' to get the schema and current status of the board
- 'get_legal_moves' to get a UCI formatted list of available moves
- 'make_move <UCI formatted move>' when you are ready to complete your turn (e.g., 'make_move e2e4')
Respond with the action.

Player_Black (to Proxy):
get_current_board

Proxy (to Player_Black):
♜ ♞ ♝ ♛ ♚ ♝ ♞ ♜
♟ ♟ ♟ ♟ ♟ ♟ ♟ ♟
· · · · · · · ·
· · · · · · · ·
· · · · · · · ·
· · · · · · · ·
♙ ♙ ♙ ♙ ♙ ♙ ♙ ♙
♖ ♘ ♗ ♕ ♔ ♗ ♘ ♖


Player_Black (to Proxy):
get_legal_moves

Proxy (to Player_Black):
a7a6, b7b6, c7c6, d7d6, e7e6, f7f6, g7g6, h7h6, a7a5, b7b5, c7c5, d7d5, e7e5, f7f5, g7g5, h7h5

Player_Black (to Proxy):
make_move e7e5

Proxy (to Player_Black):
Move made, switching player

Configurations

Edit globals in llm_chess.py or pass via run_multiple_games.py:

Provider choice comes from MODEL_KIND_W / MODEL_KIND_B in .env.
Use azure for classic Azure chat-completions deployments.
Use azure_responses for Azure deployments that require the Responses API. Keep AZURE_OPENAI_ENDPOINT_* at the resource root such as https://your-resource.openai.azure.com; the runtime will normalize it to the Responses base path automatically.

white_player_type / black_player_type: RANDOM_PLAYER, LLM, CHESS_ENGINE_DRAGON, CHESS_ENGINE_STOCKFISH.
enable_reflection: Enable "reflect" action for strategic thinking (extra tokens).
use_fen_board: Use FEN notation instead of Unicode board (default: False).
max_game_moves: Max moves (default: 200).
Per-move LLM limits:
max_llm_turns: Max dialog turns (default: 10).
max_failed_attempts: Max errors before loss (default: 3).
throttle_delay_moves: API delay (default: 1s) to avoid rate limits.

References

Libraries: chess (board rules), Autogen (agents/dialogs), Stockfish/Dragon (engines).
Data: Logs in _logs/; analysis in data/.
Notes/Changelog: docs/notes.md for updates, model tiers, and insights.
License: MIT (see LICENSE).
Contribute: Fork, PR improvements to setup, agents, or analysis.

For issues or questions, open a GitHub issue.