ShogiArena

USI将棋エンジンの対局、比較、チューニングを、一つの実行環境で管理します。

ShogiArenaは、トーナメント、GSPRT、SPSA、自己対局による棋譜生成に対応しています。 対局の実行だけでなく、設定の検証、棋譜と統計の保存、異常の診断、Webダッシュボードでの監視までを同じrunとして記録します。

ドキュメント | クイックスタート | PyPI | 変更履歴

ダッシュボード

https://github.com/user-attachments/assets/1cdebe23-b1a9-4d8e-91c0-f56ca970b569

進行中の対局、順位表、棋譜、エンジン設定、SPRT、SPSAの更新状況をリアルタイムに確認できます。 完了したrunも同じ画面で開き直せます。

用途

各runには設定、エンジン情報、棋譜、SQLite DB、再開状態が保存されます。 v1.1.0以降はcompletion_status.jsonも保存されるため、正常完了、SPRTの早期決着、利用者による停止、安全装置による停止を区別できます。

インストール

Python 3.11以上と、実行するUSI将棋エンジンが必要です。

pip install shogiarena
shogiarena --version

Windows x86_64、Linux x86_64／arm64、macOS Intel／Apple Silicon向けのwheelを提供しています。 AVX2版のrsshogiへ差し替える場合は、インストールガイドを参照してください。

実行platformの対応範囲は次のとおりです。

Remote workerはworker-bundleでwheel、lock、manifestからimmutable bundleを生成します。 別のuv projectの仮想環境へインストールした場合も、bundle sourceにはinstalled ShogiArena distributionを使います。 既配置engineや評価ファイルを使う場合は、preplaced-mapで実行時と同じlogical IDとSHA-256 mappingを生成できます。

shogiarena worker-bundle build --output worker-bundle.zip
shogiarena worker-bundle preplaced-map \
  --engine engine-a /local/engine-a /opt/engines/engine-a \
  --resource engine-a /local/eval /opt/eval/engine-a

Remote設定とcas／preplaced運用はリモート実行ガイドを参照してください。

出力先とエンジン配置先を初期化する場合は、次のコマンドを実行します。

shogiarena config init
shogiarena config show

config initは必須ではありません。 {output_dir}と{engine_dir}のプレースホルダー、artifact repository、共有キャッシュを使う場合に設定してください。

最初のトーナメント

ローカルのUSIエンジンを二つ登録し、10局のround-robinを実行します。

まず、エンジンごとに設定ファイルを作ります。

engine_a.yaml:

name: "Engine A"
engine_path: "/path/to/engine_a"
options:
  Threads: 2
  USI_Hash: 256

engine_b.yaml:

name: "Engine B"
engine_path: "/path/to/engine_b"
options:
  Threads: 2
  USI_Hash: 256

次に、二つのエンジンを参照するtournament.yamlを作ります。

experiment_name: "first_tournament"

engines:
  - engine_path: "engine_a.yaml"
  - engine_path: "engine_b.yaml"

tournament:
  scheduler: "round_robin"
  games_per_pair: 10
  num_parallel: 2

rules:
  time_control:
    time_ms: 10000
    increment_ms: 100

dashboard:
  enabled: true
  api_port: 8080

実行前に--dry-runで設定を検証します。

shogiarena run tournament tournament.yaml --dry-run
shogiarena run tournament tournament.yaml

実行中はhttp://localhost:8080でダッシュボードを開けます。 設定項目の意味とrunディレクトリの構成は、クイックスタートにまとめています。

実行モード

設定テンプレートはexamples/configsにあります。 PyPIの配布物には含まれないため、必要な場合はGitHubから取得してください。

保存したrunを調べる

ダッシュボードは実行中だけでなく、保存済みのrunにも利用できます。

shogiarena dashboard serve --run-dir /path/to/run

対局結果を端末、JSON、CSVへ集計できます。

shogiarena results summary /path/to/run
shogiarena results summary /path/to/run --format json
shogiarena results summary /path/to/run --format csv

v1.1.0以降の測定結果を採用する前に、completion_status.jsonのstatusとtermination_reasonを確認してください。 ShogiArena自身の停滞が疑われる時間切れと、原因を断定できない時間切れは無効局として記録され、EloとSPRTの標本から除外されます。

Pythonから使う

公開APIからUSIエンジンを起動し、局面を探索できます。

import asyncio

from shogiarena.engine import UsiThinkRequest, create_engine


async def main() -> None:
    async with await create_engine("engine_a.yaml") as engine:
        result = await engine.think(
            sfen="startpos",
            request=UsiThinkRequest(movetime=5_000),
        )
        print(result.bestmove)


asyncio.run(main())

保存先を指定してトーナメントを実行する場合は、shogiarena.tournamentを使います。

import asyncio

from shogiarena.tournament import run_tournament


async def main() -> None:
    result = await run_tournament(
        "tournament.yaml",
        run_dir="runs/example",
    )
    print(result)


asyncio.run(main())

安定した公開面は、CLI、公開設定schema、shogiarena.engine、shogiarena.tournamentの通常利用向けAPIです。 shogiarena.compositionの高度なrunner／storage組み立てAPIはprovisionalであり、1.xでも変更される場合があります。 shogiarena._coreは内部実装なので直接importしないでください。

ドキュメント

• インストール
• 最初のトーナメント
• トーナメント
• SPRT／SPSA
• エンジン設定
• ダッシュボード
• Pythonライブラリ
• CLIリファレンス
• トラブルシューティング

開発

このリポジトリの開発環境はuvで管理します。

git clone https://github.com/nyoki-mtl/ShogiArena.git
cd ShogiArena
uv sync
make check

変更を送る前にコントリビュートガイドを確認してください。

ライセンス

ShogiArenaはMIT Licenseで公開しています。