SAZ2 自己対局教師データ（rsshogi.sazpack）

rsshogi.sazpack は SAZ2 形式の自己対局教師データを読み書きするモジュールである。 現行形式は version 4 であり、読み込み関数は他の版を ValueError として拒否する。 SAZ2 は各対局の初期局面（32 バイトの PackedSfen）、終局結果、終局理由、入玉ルールに加えて、各手番における探索ルート、対局結果、ネットワーク生出力の WDL（勝、分、敗）分布、候補手ごとの Policy 重みと訪問数、詰み手数や残り手数などの探索テレメトリをコンパクトなバイナリとして保持する。

from rsshogi.sazpack import (
    SazGame,
    SazPolicyEntry,
    SazPosition,
    SazWdl,
    decode_sazpack,
    decode_sazpack_file,
    write_sazpack,
    write_sazpack_file,
)

データクラス

SazWdl

SazWdl(win: int, draw: int, loss: int) -> SazWdl

手番側視点での勝ち（win）、引き分け（draw）、負け（loss）の重みを uint16（0..=65535）で保持するクラスである。 SAZ2 バイナリへ書き出す際、win + draw + loss == 65535（量子化スケール合計）を満たす必要がある。

SazPolicyEntry

SazPolicyEntry(
    mv: Move | Move32 | int | str,
    prior: int,
    raw_prior: int,
    visits: int,
    lower: int,
    upper: int,
) -> SazPolicyEntry

探索における 1 つの候補手の Policy 重み、訪問数、および結果区間（Outcome Bound）を保持するクラスである。 コンストラクタの mv には Move、Move32、int（0..=65535）、または USI 文字列を渡すことができ、mv プロパティからは正規化された USI 文字列として取得できる。

lower と upper は lower <= upper を満たす必要がある。

SazPosition

SazPosition(
    played: Move | Move32 | int | str,
    root_wdl: SazWdl,
    outcome_wdl: SazWdl,
    raw_wdl: SazWdl,
    raw_mate: int,
    raw_moves_left: int,
    plies_left: int,
    requested_visits: int,
    target_weight_milli: int,
    exploration_flags: int,
    policy: Sequence[SazPolicyEntry],
    mate: int | None = None,
) -> SazPosition

対局内の 1 局面分の着手と自己対局教師データを保持するクラスである。

SazGame

SazGame(
    stem: str | bytes | bytearray,
    game_result: GameResult | int | str,
    termination_reason: int,
    entering_king_rule: int,
    positions: Sequence[SazPosition],
) -> SazGame

1 対局分の SAZ2 データを保持するクラスである。 コンストラクタの stem には初期局面の SFEN 文字列、または 32 バイトの PackedSfen（bytes / bytearray）を指定できる。

termination_reason と entering_king_rule のコード一覧

8 と 9 の終局局面には合法手が残る。 8 は敗者側が投了した終局を表し、評価値の閾値で手番側（最後に記録された局面の手番）の負けを確定させる自己対局の打ち切りを含む。 9 は投了を伴わない宣言であり、引き分けを宣言した場合の game_result は GameResult.DRAW_BY_ADJUDICATION になる。

シリアライズとデシリアライズ関数

write_sazpack および write_sazpack_file は、WDL 分布と Policy 重みの合計値（65535）を検証し、違反がある場合は ValueError を送出する。 SazGame に初期局面を SFEN 文字列で渡す場合は構築時に解析するが、32 バイトの PackedSfen を渡す場合は長さだけを確認する。 読み書き時に盤面を再生する検証は行わないため、着手の合法性、候補手の重複、勝敗上下限の大小関係、終局結果と終局理由の整合性は利用側で確認する。

from rsshogi.record import GameResult
from rsshogi.sazpack import (
    SazGame,
    SazPolicyEntry,
    SazPosition,
    SazWdl,
    decode_sazpack,
    write_sazpack,
)

wdl = SazWdl(win=40000, draw=5535, loss=20000)
policy = [
    SazPolicyEntry("7g7f", prior=45000, raw_prior=42000, visits=120, lower=0, upper=2),
    SazPolicyEntry("2g2f", prior=20535, raw_prior=23535, visits=80, lower=0, upper=2),
]
position = SazPosition(
    played="7g7f",
    root_wdl=wdl,
    outcome_wdl=SazWdl(65535, 0, 0),
    raw_wdl=wdl,
    raw_mate=0,
    raw_moves_left=80,
    plies_left=75,
    requested_visits=200,
    target_weight_milli=1000,
    exploration_flags=1,
    policy=policy,
    mate=None,
)
game = SazGame(
    stem="lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL b - 1",
    game_result=GameResult.BLACK_WIN,
    termination_reason=0,
    entering_king_rule=3,
    positions=[position],
)

blob = write_sazpack([game])
restored = decode_sazpack(blob)
assert restored[0].positions[0].played == "7g7f"
assert len(restored[0].positions[0].policy) == 2

関連項目

• Policy ラベル変換（rsshogi.policy）
• 盤面管理（Board）
• 棋譜管理（Record / GameResult）
• 棋譜フォーマット一覧