UCI協議
以下用法按 official Pikafish 的提交 1c66b9b 核對。命令如何啟動和結束一次搜尋,另見 引擎執行與通訊。
一次完整分析怎樣交接?
以下是介面依次傳送的命令示例。先等 uciok,再設定選項;收到 readyok 後設置局面並開始分析:
uci
setoption name Threads value 2
isready
position startpos moves b0c2 b9c7
go movetime 1000b0c2、b9c7 分別是紅黑馬從初始位置走出。引擎建立這兩步的歷史,再按一秒步時搜尋,過程中輸出 info,結束輸出 bestmove。介面根據 bestmove 落子,並在下一次分析前傳送更新後的 position。
如果使用 go infinite,結束時傳送 stop 並等待 bestmove。等待期間繼續讀取標準輸出,才能讓執行緒完成交接;換局面或改選項放在本次搜尋結束之後。
quit
請求停止搜尋並退出引擎。若搜尋仍在進行,會先等待工作執行緒收尾,期間可能還有搜尋結果或 bestmove 輸出。
ucinewgame
進行新的一局時,介面應向引擎傳送 ucinewgame 指令以清除置換表和搜尋歷史等。該指令不負責設定開局局面,仍需傳送 position。執行可能需要一段時間,介面可在之後使用 isready 確認前面的處理已完成。若原有搜尋尚未結束,應先發送 stop 並等待 bestmove。
setoption
設定引擎選項,用法:
setoption name <id> [value <x>]其中,<id> 是 UCI 選項名,<x> 是你要設定的值。
例如介面要將引擎的執行緒數設定為 16,可傳送:
setoption name Threads value 16某些選項,如 Clear Hash(清空置換表),可省略 value 直接使用,例如:
setoption name Clear Hash關於 UCI 選項,詳見「UCI選項」頁面,這裡不再贅述。
修改選項前應先結束搜尋。部分設定會輸出 info string 等狀態資訊;未知選項或無效設定也可能產生提示,不能依賴「完全沒有輸出」。
isready
用於確認引擎能夠應答,收到後輸出 readyok。搜尋期間也可回覆,因此 readyok 不代表搜尋已經結束;結束搜尋應使用 stop 並等待 bestmove。
uci
用於獲取引擎相關資訊(如名稱、作者、UCI 選項等)。下面是舊版的輸出示例,具體選項、預設值和範圍應以正在使用的引擎輸出為準:
id name Pikafish 2024-02-18
id author the Pikafish developers (see AUTHORS file)
option name Debug Log File type string default
option name Threads type spin default 1 min 1 max 1024
option name Hash type spin default 16 min 1 max 33554432
option name Clear Hash type button
option name Ponder type check default false
option name MultiPV type spin default 1 min 1 max 128
...
uciok其中,uciok 是必需的。如果介面輸入 uci 後,沒有接收到引擎輸出的 uciok,那麼介面會認為該程式不是 UCI 引擎。
position fen
給引擎輸入 FEN 局面。
例如:
position fen 3k1a3/4a4/5n3/9/9/9/9/9/9/4KR3 w或者在此基礎上加上 movelist(歷史著法):
position fen 5a3/3ka4/5n3/9/9/9/9/9/9/4K1R2 w - - 0 1 moves g0f0 d8d9注意
本頁核對的 Pikafish 版本需要 position 字首,不能直接傳送裸 FEN。座標著法的列為 a 至 i,行為 0 至 9。附帶歷史著法有助於引擎判斷重複、長將和長捉;只有最後一張 FEN 不能還原完整歷史。
成功設定通常沒有直接回復;局面或歷史著法出錯時,當前實現會輸出 CRITICAL ERROR 並退出。
position startpos
設定當前局面為起始局面(rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w)。也可在後面附加 moves 和歷史著法;需要保留 position 字首。
成功設定通常沒有直接回復;非法歷史著法會導致錯誤輸出並退出。
go
讓引擎分析當前的局面(當前局面可通過 position 指令設定)。
可以加入以下參數:
searchmoves <move1> <move2> ... <movei>:指定搜尋的走法(介面「變招」功能需要使用該參數),在當前解析器中必須放在本行其他參數之後。UCI 協議中沒有banmoves指令(這是 UCCI 協議中的)。infinite:無限制分析(直到傳送stop)。ponder:後臺思考。wtime,btime:紅方和黑方剩下的時間(ms)。winc,binc:紅方和黑方的加秒(ms)。movestogo:用於多少時間走多少步的時間制,告訴引擎獲得新的時間還剩多少步,在中國象棋裡面一般不會用到。depth:指定層數。nodes:指定搜尋的節點數。mate:找到指定步數內的決定性勝負距離時停止搜尋;不只限於己方獲勝。movetime:指定步時(ms)。perft:統計到指定層數的合法走法路徑數;一層是一方走一步,不執行正常評分搜尋。
輸入 go 後,引擎將搜尋當前局面並輸出搜尋結果。達到對應的限制或使用者傳送 stop 指令後,引擎即終止搜尋。
go infinite 需用 stop 結束;後臺思考在預計著法命中時用 ponderhit 轉為正常搜尋。普通搜尋收尾後會輸出 bestmove,go perft 則輸出路徑統計。詳見 搜尋生命週期。
d
輸出當前的局面、局面 FEN、key 資訊和將軍資訊。該指令供引擎開發除錯使用。
eval
輸出當前局面的評估資訊。該指令供引擎開發除錯使用。
export_net
匯出權重,可指定檔名。
flip
上下翻轉棋盤,並交換紅黑棋子和行棋方,主要用於檢查評估的對稱性。
compiler
輸出編譯器及引擎指令集資訊。
bench
當前版本另有 speedtest 測速命令,工具用途與區別見 執行診斷。
