KataGo 常用指令

本文介紹 KataGo 嘅兩種主要操作模式：GTP 協議同 Analysis Engine，以及常用指令嘅詳細說明。

GTP 協議介紹

GTP（Go Text Protocol）係圍棋程式之間通訊嘅標準協議。大多數圍棋 GUI（如 Sabaki、Lizzie）都使用 GTP 同 AI 引擎溝通。

啟動 GTP 模式

katago gtp -model /path/to/model.bin.gz -config /path/to/config.cfg

GTP 協議基本格式

[id] command_name [arguments]

id：可選嘅指令編號，用嚟追蹤回應
command_name：指令名稱
arguments：指令參數

回應格式：

=[id] response_data     # 成功
?[id] error_message     # 失敗

基本範例

1 name
=1 KataGo

2 version
=2 1.15.3

3 boardsize 19
=3

4 komi 7.5
=4

5 play black Q16
=5

6 genmove white
=6 D4

常用 GTP 指令

程式資訊

指令	說明	範例
`name`	攞程式名稱	`name` → `= KataGo`
`version`	攞版本號	`version` → `= 1.15.3`
`list_commands`	列出所有支援嘅指令	`list_commands`
`protocol_version`	GTP 協議版本	`protocol_version` → `= 2`

棋盤設定

# 設定棋盤大細（9、13、19）
boardsize 19

# 設定貼目
komi 7.5

# 清除棋盤
clear_board

# 設定規則（KataGo 擴充）
kata-set-rules chinese    # 中國規則
kata-set-rules japanese   # 日本規則
kata-set-rules tromp-taylor

落子相關

# 落子
play black Q16    # 黑棋落喺 Q16
play white D4     # 白棋落喺 D4
play black pass   # 黑棋虛手

# 畀 AI 落一手
genmove black     # 生成黑棋嘅一手
genmove white     # 生成白棋嘅一手

# 撤銷
undo              # 撤銷一手

# 設定手數限制
kata-set-param maxVisits 1000    # 設定最大搜索次數

局面查詢

# 顯示棋盤
showboard

# 攞當前落子方
kata-get-player

# 攞分析結果
kata-analyze black 100    # 分析黑棋，搜索 100 次

規則相關

# 攞當前規則
kata-get-rules

# 設定規則
kata-set-rules chinese

# 設定讓子
fixed_handicap 4     # 標準讓四子位置
place_free_handicap 4  # 自由讓子

KataGo 擴充指令

KataGo 喺標準 GTP 之外提供好多擴充指令：

kata-analyze

即時分析當前局面：

kata-analyze [player] [visits] [interval]

參數：

player：分析邊方（black/white）
visits：搜索次數
interval：報告間隔（centiseconds，1/100 秒）

範例：

kata-analyze black 1000 100

輸出：

info move Q3 visits 523 winrate 0.5432 scoreMean 2.31 scoreSelfplay 2.45 prior 0.1234 order 0 pv Q3 R4 Q5 ...
info move D4 visits 312 winrate 0.5123 scoreMean 1.82 scoreSelfplay 1.95 prior 0.0987 order 1 pv D4 C6 E3 ...
...

輸出欄位說明：

欄位	說明
`move`	著點
`visits`	搜索訪問次數
`winrate`	勝率（0-1）
`scoreMean`	預期目數差
`scoreSelfplay`	自我對弈預期目數
`prior`	神經網絡嘅先驗機率
`order`	排名順序
`pv`	主要變化（Principal Variation）

kata-raw-nn

攞原始神經網絡輸出：

kata-raw-nn [symmetry]

輸出包含：

Policy 機率分佈
Value 預測
領地預測等

kata-debug-print

顯示詳細嘅搜索資訊，用嚟除錯：

kata-debug-print move Q16

棋力調整

# 設定最大訪問次數
kata-set-param maxVisits 100      # 較弱
kata-set-param maxVisits 10000    # 較強

# 設定思考時間
kata-time-settings main 60 0      # 每方 60 秒
kata-time-settings byoyomi 30 5   # 讀秒 30 秒 5 次

Analysis Engine 使用

Analysis Engine 係 KataGo 提供嘅另一種操作模式，使用 JSON 格式通訊，更適合程式化使用。

啟動 Analysis Engine

katago analysis -model /path/to/model.bin.gz -config /path/to/config.cfg

基本使用流程

你嘅程式 ──JSON請求──> KataGo Analysis Engine ──JSON回應──> 你嘅程式

請求格式

每個請求係一個 JSON 物件，必須佔一行：

{
  "id": "query1",
  "moves": [["B","Q16"],["W","D4"],["B","Q4"]],
  "rules": "chinese",
  "komi": 7.5,
  "boardXSize": 19,
  "boardYSize": 19,
  "analyzeTurns": [2]
}

請求欄位說明

欄位	必須	說明
`id`	係	查詢識別碼，用嚟對應回應
`moves`	否	棋步序列 `[["B","Q16"],["W","D4"]]`
`initialStones`	否	初始棋子 `[["B","Q16"],["W","D4"]]`
`rules`	係	規則名稱
`komi`	係	貼目
`boardXSize`	係	棋盤闊度
`boardYSize`	係	棋盤高度
`analyzeTurns`	否	要分析嘅手數（0-indexed）
`maxVisits`	否	覆蓋設定檔嘅 maxVisits

回應格式

{
  "id": "query1",
  "turnNumber": 2,
  "moveInfos": [
    {
      "move": "D16",
      "visits": 1234,
      "winrate": 0.5678,
      "scoreMean": 3.21,
      "scoreStdev": 15.4,
      "scoreLead": 3.21,
      "prior": 0.0892,
      "order": 0,
      "pv": ["D16", "Q10", "R14"]
    }
  ],
  "rootInfo": {
    "visits": 5000,
    "winrate": 0.5234,
    "scoreLead": 2.1,
    "scoreSelfplay": 2.3
  },
  "ownership": [...],
  "policy": [...]
}

回應欄位說明

moveInfos 欄位

欄位	說明
`move`	著點座標
`visits`	嗰個著點嘅搜索訪問次數
`winrate`	勝率（0-1，對當前落子方）
`scoreMean`	預期最終目數差
`scoreStdev`	目數標準差
`scoreLead`	當前領先目數
`prior`	神經網絡先驗機率
`order`	排名（0 = 最佳）
`pv`	主要變化序列

rootInfo 欄位

欄位	說明
`visits`	總搜索訪問次數
`winrate`	當前局面勝率
`scoreLead`	當前領先目數
`scoreSelfplay`	自我對弈預期目數

ownership 欄位

一維陣列，長度為 boardXSize × boardYSize，每個值喺 -1 到 1 之間：

-1：預測為白方領地
+1：預測為黑方領地
0：未定/邊界

進階查詢選項

攞領地圖

{
  "id": "ownership_query",
  "moves": [...],
  "rules": "chinese",
  "komi": 7.5,
  "boardXSize": 19,
  "boardYSize": 19,
  "analyzeTurns": [10],
  "includeOwnership": true
}

攞 Policy 分佈

{
  "id": "policy_query",
  "moves": [...],
  "rules": "chinese",
  "komi": 7.5,
  "boardXSize": 19,
  "boardYSize": 19,
  "analyzeTurns": [10],
  "includePolicy": true
}

限制報告嘅著法數量

{
  "id": "limited_query",
  "moves": [...],
  "rules": "chinese",
  "komi": 7.5,
  "boardXSize": 19,
  "boardYSize": 19,
  "analyzeTurns": [10],
  "maxMoves": 5
}

分析特定著法

{
  "id": "specific_moves",
  "moves": [...],
  "rules": "chinese",
  "komi": 7.5,
  "boardXSize": 19,
  "boardYSize": 19,
  "analyzeTurns": [10],
  "allowMoves": [["B","Q16"],["B","D4"],["B","Q4"]]
}

完整範例：Python 整合

import subprocess
import json

class KataGoEngine:
    def __init__(self, katago_path, model_path, config_path):
        self.process = subprocess.Popen(
            [katago_path, 'analysis', '-model', model_path, '-config', config_path],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
        self.query_id = 0

    def analyze(self, moves, rules='chinese', komi=7.5):
        self.query_id += 1

        query = {
            'id': f'query_{self.query_id}',
            'moves': moves,
            'rules': rules,
            'komi': komi,
            'boardXSize': 19,
            'boardYSize': 19,
            'analyzeTurns': [len(moves)],
            'maxVisits': 500,
            'includeOwnership': True
        }

        # 發送查詢
        self.process.stdin.write(json.dumps(query) + '\n')
        self.process.stdin.flush()

        # 讀取回應
        response_line = self.process.stdout.readline()
        return json.loads(response_line)

    def close(self):
        self.process.terminate()


# 使用範例
engine = KataGoEngine(
    '/usr/local/bin/katago',
    '/path/to/model.bin.gz',
    '/path/to/config.cfg'
)

# 分析一個局面
result = engine.analyze([
    ['B', 'Q16'],
    ['W', 'D4'],
    ['B', 'Q4'],
    ['W', 'D16']
])

# 印出最佳著法
best_move = result['moveInfos'][0]
print(f"最佳著法：{best_move['move']}")
print(f"勝率：{best_move['winrate']:.1%}")
print(f"領先目數：{best_move['scoreLead']:.1f}")

engine.close()

完整範例：Node.js 整合

const { spawn } = require('child_process');
const readline = require('readline');

class KataGoEngine {
  constructor(katagoPath, modelPath, configPath) {
    this.process = spawn(katagoPath, [
      'analysis',
      '-model', modelPath,
      '-config', configPath
    ]);

    this.rl = readline.createInterface({
      input: this.process.stdout,
      crlfDelay: Infinity
    });

    this.queryId = 0;
    this.callbacks = new Map();

    this.rl.on('line', (line) => {
      try {
        const response = JSON.parse(line);
        const callback = this.callbacks.get(response.id);
        if (callback) {
          callback(response);
          this.callbacks.delete(response.id);
        }
      } catch (e) {
        console.error('Parse error:', e);
      }
    });
  }

  analyze(moves, options = {}) {
    return new Promise((resolve) => {
      this.queryId++;
      const id = `query_${this.queryId}`;

      const query = {
        id,
        moves,
        rules: options.rules || 'chinese',
        komi: options.komi || 7.5,
        boardXSize: 19,
        boardYSize: 19,
        analyzeTurns: [moves.length],
        maxVisits: options.maxVisits || 500,
        includeOwnership: true
      };

      this.callbacks.set(id, resolve);
      this.process.stdin.write(JSON.stringify(query) + '\n');
    });
  }

  close() {
    this.process.kill();
  }
}

// 使用範例
async function main() {
  const engine = new KataGoEngine(
    '/usr/local/bin/katago',
    '/path/to/model.bin.gz',
    '/path/to/config.cfg'
  );

  const result = await engine.analyze([
    ['B', 'Q16'],
    ['W', 'D4'],
    ['B', 'Q4']
  ]);

  console.log('最佳著法:', result.moveInfos[0].move);
  console.log('勝率:', (result.moveInfos[0].winrate * 100).toFixed(1) + '%');

  engine.close();
}

main();

座標系統

KataGo 使用標準嘅圍棋座標系統：

字母座標

   A B C D E F G H J K L M N O P Q R S T
. . . . . . . . . . . . . . . . . . . 19
. . . . . . . . . . . . . . . . . . . 18
. . . . . . . . . . . . . . . . . . . 17
. . . + . . . . . + . . . . . + . . . 16
. . . . . . . . . . . . . . . . . . . 15
...
. . . + . . . . . + . . . . . + . . .  4
. . . . . . . . . . . . . . . . . . .  3
. . . . . . . . . . . . . . . . . . .  2
. . . . . . . . . . . . . . . . . . .  1
   A B C D E F G H J K L M N O P Q R S T

注意：冇 I 呢個字母（避免同數字 1 混淆）。

座標轉換

def coord_to_gtp(x, y, board_size=19):
    """將 (x, y) 座標轉換為 GTP 格式"""
    letters = 'ABCDEFGHJKLMNOPQRST'
    return f"{letters[x]}{board_size - y}"

def gtp_to_coord(gtp_coord, board_size=19):
    """將 GTP 座標轉換為 (x, y)"""
    letters = 'ABCDEFGHJKLMNOPQRST'
    x = letters.index(gtp_coord[0].upper())
    y = board_size - int(gtp_coord[1:])
    return (x, y)

常見使用模式

對弈模式

# 啟動 GTP 模式
katago gtp -model model.bin.gz -config gtp.cfg

# GTP 指令序列
boardsize 19
komi 7.5
play black Q16
genmove white
play black Q4
genmove white
...

批次分析模式

# 分析一盤棋嘅所有著法
sgf_moves = parse_sgf('game.sgf')

for i in range(len(sgf_moves)):
    result = engine.analyze(sgf_moves[:i+1])
    winrate = result['rootInfo']['winrate']
    print(f"第 {i+1} 手: 勝率 {winrate:.1%}")

即時分析模式

使用 kata-analyze 進行即時分析：

kata-analyze black 1000 50

會每 0.5 秒輸出一次分析結果，直到達到 1000 次訪問。

效能調優

搜索設定

# 增加搜索量提高準確度
maxVisits = 1000

# 或使用時間控制
maxTime = 10  # 每手最多思考 10 秒

多執行緒設定

# CPU 執行緒數
numSearchThreads = 8

# GPU 批次處理
numNNServerThreadsPerModel = 2
nnMaxBatchSize = 16

記憶體設定

# 減少記憶體使用
nnCacheSizePowerOfTwo = 20  # 預設 23

下一步

了解指令使用之後，如果你想深入研究 KataGo 嘅實作，請繼續閱讀原始碼架構。

GTP 協議介紹​

啟動 GTP 模式​

GTP 協議基本格式​

基本範例​

常用 GTP 指令​

程式資訊​

棋盤設定​

落子相關​

局面查詢​

規則相關​

KataGo 擴充指令​

kata-analyze​

kata-raw-nn​

kata-debug-print​

棋力調整​

Analysis Engine 使用​

啟動 Analysis Engine​

基本使用流程​

請求格式​

請求欄位說明​

回應格式​

回應欄位說明​

moveInfos 欄位​

rootInfo 欄位​

ownership 欄位​

進階查詢選項​

攞領地圖​

攞 Policy 分佈​

限制報告嘅著法數量​

分析特定著法​

完整範例：Python 整合​

完整範例：Node.js 整合​

座標系統​

字母座標​

座標轉換​

常見使用模式​

對弈模式​

批次分析模式​

即時分析模式​

效能調優​

搜索設定​

多執行緒設定​

記憶體設定​

下一步​