{"id":13794011,"url":"https://github.com/NeymarL/ChineseChess-AlphaZero","last_synced_at":"2025-05-12T20:31:29.567Z","repository":{"id":37405636,"uuid":"119518960","full_name":"NeymarL/ChineseChess-AlphaZero","owner":"NeymarL","description":"Implement AlphaZero/AlphaGo Zero methods on Chinese chess.","archived":false,"fork":false,"pushed_at":"2023-03-24T22:26:39.000Z","size":1204220,"stargazers_count":1133,"open_issues_count":25,"forks_count":348,"subscribers_count":49,"default_branch":"distributed","last_synced_at":"2025-04-09T10:03:07.355Z","etag":null,"topics":["alphazero","chinese-chess","deep-learning","reinforcement-learning"],"latest_commit_sha":null,"homepage":"https://cczero.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NeymarL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-01-30T10:13:29.000Z","updated_at":"2025-04-09T01:36:23.000Z","dependencies_parsed_at":"2023-01-21T13:16:16.775Z","dependency_job_id":"8f9352cd-f90c-41bd-a53e-db6fc105e97e","html_url":"https://github.com/NeymarL/ChineseChess-AlphaZero","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeymarL%2FChineseChess-AlphaZero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeymarL%2FChineseChess-AlphaZero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeymarL%2FChineseChess-AlphaZero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeymarL%2FChineseChess-AlphaZero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeymarL","download_url":"https://codeload.github.com/NeymarL/ChineseChess-AlphaZero/tar.gz/refs/heads/distributed","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253816755,"owners_count":21968877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alphazero","chinese-chess","deep-learning","reinforcement-learning"],"created_at":"2024-08-03T23:00:34.667Z","updated_at":"2025-05-12T20:31:24.536Z","avatar_url":"https://github.com/NeymarL.png","language":"Python","funding_links":[],"categories":["Open-Source Projects","Python"],"sub_categories":["Chinese Chess Projects"],"readme":"# 中国象棋Zero（CCZero）\n\n\u003ca href=\"https://cczero.org\"\u003e\n  \u003cimg src=\"https://cczero.org/zero2.png\" alt=\"App Icon\" /\u003e\n\u003c/a\u003e\n\n## About\n\nChinese Chess reinforcement learning by [AlphaZero](https://arxiv.org/abs/1712.01815) methods.\n\nThis project is based on these main resources:\n1. DeepMind's Oct 19th publication: [Mastering the Game of Go without Human Knowledge](https://www.nature.com/articles/nature24270.epdf?author_access_token=VJXbVjaSHxFoctQQ4p2k4tRgN0jAjWel9jnR3ZoTv0PVW4gB86EEpGqTRDtpIz-2rmo8-KG06gqVobU5NSCFeHILHcVFUeMsbvwS-lxjqQGg98faovwjxeTUgZAUMnRQ).\n2. The **great** Reversi/Chess/Chinese chess development of the DeepMind ideas that @mokemokechicken/@Akababa/@TDteach did in their repo: https://github.com/mokemokechicken/reversi-alpha-zero, https://github.com/Akababa/Chess-Zero, https://github.com/TDteach/AlphaZero_ChineseChess\n3. A Chinese chess engine with gui: https://github.com/mm12432/MyChess\n\n\n## Help to train\n\nIn order to build a strong chinese chess AI following the same type of techniques as AlphaZero, we need to do this with a distributed project, as it requires a huge amount of computations.\n\nIf you want to join us to build the best chinese chess AI in the world:\n\n* For instructions, see [wiki](https://github.com/NeymarL/ChineseChess-AlphaZero/wiki)\n* For live status, see https://cczero.org\n\n![elo](elo.png)\n\n\n## Environment\n\n* Python 3.6.3\n* tensorflow-gpu: 1.3.0\n* Keras: 2.0.8\n\n\n## Modules\n\n### Reinforcement Learning\n\nThis AlphaZero implementation consists of two workers: `self` and  `opt`.\n\n* `self` is Self-Play to generate training data by self-play using BestModel.\n* `opt` is Trainer to train model, and generate new models.\n\nFor the sake of faster training, another two workers are involved:\n\n* `sl` is Supervised learning to train data crawled from the Internet.\n* `eval` is Evaluator to evaluate the NextGenerationModel with the current BestModel.\n\n### Built-in GUI\n\nRequirement: pygame\n\n```bash\npython cchess_alphazero/run.py play\n```\n\n**Screenshots**\n\n![board](screenshots/board.png)\n\nYou can choose different board/piece styles and sides, see [play with human](#play-with-human).\n\n\n## How to use\n\n### Setup\n\n### install libraries\n```bash\npip install -r requirements.txt\n```\n\nIf you want to use CPU only, replace `tensorflow-gpu` with `tensorflow` in `requirements.txt`.\n\nMake sure Keras is using Tensorflow and you have Python 3.6.3+.\n\n### Configuration\n\n**PlayDataConfig**\n\n* `nb_game_in_file, max_file_num`: The max game number of training data is `nb_game_in_file * max_file_num`.\n\n**PlayConfig, PlayWithHumanConfig**\n\n* `simulation_num_per_move` : MCTS number per move.\n* `c_puct`: balance parameter of value network and policy network in MCTS.\n* `search_threads`: balance parameter of speed and accuracy in MCTS.\n* `dirichlet_alpha`: random parameter in self-play.\n\n### Full Usage\n\n```\nusage: run.py [-h] [--new] [--type TYPE] [--total-step TOTAL_STEP]\n              [--ai-move-first] [--cli] [--gpu GPU] [--onegreen] [--skip SKIP]\n              [--ucci] [--piece-style {WOOD,POLISH,DELICATE}]\n              [--bg-style {CANVAS,DROPS,GREEN,QIANHONG,SHEET,SKELETON,WHITE,WOOD}]\n              [--random {none,small,medium,large}] [--distributed] [--elo]\n              {self,opt,eval,play,eval,sl,ob}\n\npositional arguments:\n  {self,opt,eval,play,eval,sl,ob}\n                        what to do\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --new                 run from new best model\n  --type TYPE           use normal setting\n  --total-step TOTAL_STEP\n                        set TrainerConfig.start_total_steps\n  --ai-move-first       set human or AI move first\n  --cli                 play with AI with CLI, default with GUI\n  --gpu GPU             device list\n  --onegreen            train sl work with onegreen data\n  --skip SKIP           skip games\n  --ucci                play with ucci engine instead of self play\n  --piece-style {WOOD,POLISH,DELICATE}\n                        choose a style of piece\n  --bg-style {CANVAS,DROPS,GREEN,QIANHONG,SHEET,SKELETON,WHITE,WOOD}\n                        choose a style of board\n  --random {none,small,medium,large}\n                        choose a style of randomness\n  --distributed         whether upload/download file from remote server\n  --elo                 whether to compute elo score\n```\n\n### Self-Play\n\n```\npython cchess_alphazero/run.py self\n```\n\nWhen executed, self-play will start using BestModel. If the BestModel does not exist, new random model will be created and become BestModel. Self-play records will store in `data/play_record` and BestMode will store in `data/model`.\n\noptions\n\n* `--new`: create new BestModel\n* `--type mini`: use mini config, (see `cchess_alphazero/configs/mini.py`)\n* `--gpu '1'`: specify which gpu to use\n* `--ucci`: whether to play with ucci engine (rather than self play, see `cchess_alphazero/worker/play_with_ucci_engine.py`)\n* `--distributed`: run self play in distributed mode which means it will upload the play data to the remote server and download latest model from it\n\n**Note1**: To help training, you should run `python cchess_alphazero/run.py --type distribute --distributed self` (and do not change the configuration file `configs/distribute.py`), for more info, see [wiki](https://github.com/NeymarL/ChineseChess-AlphaZero/wiki/For-Developers).\n\n**Note2**: If you want to view the self-play records in GUI, see [wiki](https://github.com/NeymarL/ChineseChess-AlphaZero/wiki/View-self-play-games-in-GUI).\n\n### Trainer\n\n```\npython cchess_alphazero/run.py opt\n```\n\nWhen executed, Training will start. The current BestModel will be loaded. Trained model will be saved every epoch as new BestModel.\n\noptions\n\n* `--type mini`: use mini config, (see `cchess_alphazero/configs/mini.py`)\n* `--total-step TOTAL_STEP`: specify total step(mini-batch) numbers. The total step affects learning rate of training.\n* `--gpu '1'`: specify which gpu to use\n\n**View training log in Tensorboard**\n\n```\ntensorboard --logdir logs/\n```\n\nAnd access `http://\u003cThe Machine IP\u003e:6006/`.\n\n### Play with human\n\n**Run with built-in GUI**\n\n```\npython cchess_alphazero/run.py play\n```\n\nWhen executed, the BestModel will be loaded to play against human.\n\noptions\n\n* `--ai-move-first`: if set this option, AI will move first, otherwise human move first.\n* `--type mini`: use mini config, (see `cchess_alphazero/configs/mini.py`)\n* `--gpu '1'`: specify which gpu to use\n* `--piece-style WOOD`: choose a piece style, default is `WOOD`\n* `--bg-style CANVAS`: choose a board style, default is `CANVAS`\n* `--cli`: if set this flag, play with AI in a cli environment rather than gui\n\n**Note**: Before you start, you need to download/find a font file (`.ttc`) and rename it as `PingFang.ttc`, then put it into `cchess_alphazero/play_games`. I have removed the font file from this repo because it's too big, but you can download it from [here](http://alphazero.52coding.com.cn/PingFang.ttc).\n\nYou can also download Windows executable directly from [here](https://pan.baidu.com/s/1uE_zmkn0x9Be_olRL9U9cQ). For more information, see [wiki](https://github.com/NeymarL/ChineseChess-AlphaZero/wiki/For-Non-Developers#%E4%B8%8B%E6%A3%8B).\n\n**UCI mode**\n\n```\npython cchess_alphazero/uci.py\n```\n\nIf you want to play in general GUIs such as '冰河五四', you can download the Windows executable [here](https://share.weiyun.com/5cK50Z4). For more information, see [wiki](https://github.com/NeymarL/ChineseChess-AlphaZero/wiki/For-Non-Developers#%E4%B8%8B%E6%A3%8B).\n\n### Evaluator\n\n```\npython cchess_alphazero/run.py eval\n```\n\nWhen executed, evaluate the NextGenerationModel with the current BestModel. If the NextGenerationModel does not exist, worker will wait until it exists and check every 5 minutes.\n\noptions\n\n* `--type mini`: use mini config, (see `cchess_alphazero/configs/mini.py`)\n* `--gpu '1'`: specify which gpu to use\n\n### Supervised Learning\n\n```\npython cchess_alphazero/run.py sl\n```\n\nWhen executed, Training will start. The current SLBestModel will be loaded. Tranined model will be saved every epoch as new SLBestModel.\n\n*About the data*\n\nI have two data sources, one is downloaded from https://wx.jcloud.com/market/packet/10479 ; the other is crawled from http://game.onegreen.net/chess/Index.html (with option --onegreen).\n\noptions\n\n* `--type mini`: use mini config, (see `cchess_alphazero/configs/mini.py`)\n* `--gpu '1'`: specify which gpu to use\n* `--onegreen`: if set the flag, `sl_onegreen` worker will start to train data crawled from `game.onegreen.net`\n* `--skip SKIP`: if set this flag, games whoses index is less than `SKIP` would not be used to train (only valid when `onegreen` flag is set)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeymarL%2FChineseChess-AlphaZero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeymarL%2FChineseChess-AlphaZero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeymarL%2FChineseChess-AlphaZero/lists"}