这两年玩围棋AI绕不开KataGo。很多人一开始接触围棋AI是从老版Leela Zero、GNU Go或者早期权重开始的后来AlphaGo论文公开各类开源实现井喷但真正沉淀下来、既能下棋又能做局面分析、还支持让子棋劣势分析的KataGo算是最顺手的那一个。这次记录的是我自己从零开始装KataGo的完整过程从环境准备、源码编译、模型权重下载到接上Lizzie这样的图形界面全程踩坑实录。想自己装一套本地围棋AI来复盘、练棋、或者跑批量棋谱分析的朋友这篇文章可以直接照着抄。如果你是第一次接触KataGo安装我也把每个环节为什么要这么做的逻辑一并写清楚不光是给命令还得让你知道哪一步踩坑了怎么回头。1. 项目整体认知与安装路线选型1.1 KataGo是什么为什么选择它KataGo是一个开源围棋AI引擎基于AlphaGo/AlphaZero的思路做了大量改进。比起早期的一些开源引擎它的几个优势非常明显权重体系完整小到1B大到40B参数都有现成模型可以下练棋、复盘、跑棋谱分析都能找到合适档位。支持GTP协议和分析模式analysis可以同时输出多分支候选点、胜率、目差和后续变化图这对人类复盘特别友好。让子棋优势极其突出被让子之后的胜率评估做得比很多同类引擎靠谱我这个水平用它让子棋训练效果很直接。而且KataGo至今仍然在更新社区活跃代码结构清晰对普通用户来说装好就能用对想二次开发的人来说也留了足够的接口。选择它作为本地围棋AI解决方案基本不存在“装完就废弃”的问题。1.2 安装路线对比与方案取舍KataGo的安装路线大概分三派第一派是直接下载别人打包好的发行版。这条最省事适合只想马上用、不想碰编译的人。但缺点也很明显发行版不一定跟上最新代码某些特性比如部分后端加速、自带的调试工具可能被阉割而且一旦CUDA版本和显卡驱动不匹配出问题后你连自己修的门都摸不到。第二派是源码编译。这需要安装Git、CMake、C编译环境再针对性选CUDA或OpenCL后端。好处是能拿到最新特性编译参数全在自己手里出了问题排查思路非常清晰。我自己选的是这条路线虽然第一次编译踩了不少坑但装完之后整个框架在脑子里是通的后面对接Lizzie、Sabaki或者其他前端都特别顺。第三派是用Docker镜像跑预编译环境。好处是干净不污染本机坏处是GPU直通和图形界面映射要额外配置对新手来说反而比源码编译更复杂。如果不是有明确的隔离需求我不建议第一台机器就用Docker。综合来看源码编译是理解KataGo安装全流程的最佳路径也是这篇文章主要走的路线。硬件层面如果实在没有NVIDIA显卡OpenCL后端也能跑我在后面会单独说明。2. 环境准备与依赖安装2.1 摸清硬件底细编译和运行KataGo之前先搞清楚手里机器的底牌。NVIDIA GPU用户确认显卡型号、显存大小、当前驱动版本并确认驱动能支持的目标CUDA版本。无NVIDIA GPU但有集成显卡或AMD显卡的用户走OpenCL后端性能比CUDA低不少但小权重棋力仍然能打日常复盘够用。纯CPU用户KataGo也有纯CPU后端但速度感人建议只用来验证安装是否成功真拿它做分析会等到怀疑人生。我当时机器的配置是Windows 10 RTX 20606G显存这个级别的显卡跑15B权重已经完全够用40B权重也能跑但速度会慢一些。显存低于4G的话建议优先考虑2B或者6B权重大爷卡跑大模型只会让你怀疑自己到底装没装成功。检查驱动和CUDA支持情况Windows下直接在命令行敲nvidia-smi看到右上角有“CUDA Version”字样就说明驱动正常且列出了当前驱动支持的最高CUDA版本。这一步非常关键因为后面编译CUDA后端时本地装的CUDA Toolkit版本不能高于驱动支持的版本。简单说这就是“图纸能画到几楼你手里有多少砖”的关系。2.2 Python环境Miniconda一把梭KataGo核心引擎是C写的但下载权重、跑脚本、配合数据分析时Python绕不开。为了避免把系统Python搞得一团乱我强烈建议装Miniconda它能帮你创建互相隔离的Python环境。去官网下载Windows安装包一路下一步即可。安装过程中有一个“Add Miniconda to PATH”的选项建议勾上否则后续要在终端里找到conda命令还要多配一次环境变量。装好后打开新的终端创建一个专门跑KataGo相关脚本的环境conda create -n katago python3.10 -y conda activate katago这里用Python 3.10不是必须的但它是目前兼容性比较稳的一个版本。KataGo仓库里有些辅助脚本用到了比较新的语法特性3.8以下容易报奇怪错误3.10实测下来最省心。2.3 Git与编译工具链KataGo源码要从GitHub拉取所以Git是刚需。Windows下安装Git时我会额外留意两个点安装过程中路径选择尽量用默认的“Git from the command line and also from 3rd-party software”选项这样会让git命令直接进入系统PATH。不要把仓库克隆到带中文名的路径下也别放在桌面某些C编译工具链对非ASCII路径会直接罢工。编译工具链这一步Windows和Linux差别比较大。Windows用户需要安装Visual Studio Build Tools不用装完整版Visual Studio只要里面的“使用C的桌面开发”工作负载。装完之后要打开“x64 Native Tools Command Prompt for VS 20XX”这个终端用它来继续后面的编译操作否则编译器不会被自动识别。Linux用户相对简单Debian/Ubuntu系执行sudo apt update sudo apt install -y build-essential cmake gitCMake版本建议不低于3.16太老的版本可能在配置阶段报出一些莫名其妙的错误。3. 源码编译与核心组件实现3.1 拉取源码环境就绪后开始拉KataGo源码。git clone https://github.com/lightvector/KataGo.git cd KataGo仓库不大几秒钟就能拉下来。如果你对稳定性和兼容性比较敏感可以切到最新release分支如果就是想尝鲜用默认的master分支也行。我自己用的是master分支写这篇文章时最新版本是1.15.x系列编译和运行都没有遇到大问题。拉完代码后建议先把仓库结构大概看一眼。KataGo的子目录组织得比较清晰cpp/是核心引擎主目录编译目标文件在这下面。python/是辅助脚本和一些自对弈训练脚本。weights/通常不放权重权重需要单独下载。docs/里有一些命令行参数说明遇到问题可以翻。3.2 编译引擎的关键参数KataGo的编译是用CMake完成的而不是传统的Makefile这就意味着你要先让CMake根据当前环境生成一批构建文件。Windows CUDA后端的编译命令大致如下在之前的x64 Native Tools终端里cd cpp cmake -B build -DCMAKE_BUILD_TYPERelease -DBUILD_TESTINGoff -DUSE_BACKENDCUDA cmake --build build -j 8注意几个参数的含义-DCMAKE_BUILD_TYPEReleaseRelease模式才会做优化Debug模式编译出来的引擎速度惨不忍睹千万别图方便跳过。-DBUILD_TESTINGoff关闭测试构建能显著缩短编译时间。-DUSE_BACKENDCUDA指定CUDA后端。如果你没有NVIDIA GPU改成-DUSE_BACKENDOPENCL如果连OpenCL都没有可以改成-DUSE_BACKENDEIGEN不过性能会低到只适合验证流程。-j 8后面的数字是并行编译的线程数通常设置为CPU核心数或线程数。我的机器是8线程所以填8。内存紧张的话并行数太高容易导致编译中途被杀这时降低数字就好。第一次编译需要大概10到20分钟取决于机器性能中间会跑出一堆编译日志。期间最容易出现的错误是“找不到CUDA”这时打开cmake -B build ...之前先确认本机的CUDA Toolkit已经安装并且nvcc命令能正常调用nvcc --version如果提示找不到命令去CUDA官网下载对应版本的Toolkit重新装上。装的时候默认路径是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x千万不要改动这个路径否则CMake自动探测会失败。Linux用户同样可用上面两条命令唯一区别是确保cmake、g都装上NVIDIA用户额外装好nvidia-driver和cuda-toolkit即可。编译成功会在cpp/build/下生成一个katago.exeWindows或katagoLinux文件。可以用这个命令验证./build/katago.exe version如果打印出版本信息说明引擎本体已经通了。3.3 下载网络权重引擎相当于围棋AI的身体而网络权重才是它的“棋感”和“算路”。KataGo官方在GitHub的Release页面里放了一系列训练好的模型权重文件名通常是kata1-...-sXXXX...dXXXX...的.bin.gz格式你不需要解压引擎直接能读gzip压缩格式。权重选择上我按用途整理了一个参考表权重规模文件名特征适合场景显存需求2Bkata1-2b系列CPU/旧显卡快速验证、弱机复盘1GB以内6Bkata1-6b系列入门显卡日常自带分析2GB~4GB15Bkata1-15b系列中高端显卡稳妥选择综合性价比高4GB~6GB20Bkata1-20b系列拥有大显存GPU的分析需求6GB~8GB40Bkata1-40b系列强算力平台、深度分析8GB以上我选择的15B权重文件大概500MB左右下载后用默认目录存放到KataGo/weights/下方便后续路径引用。下载地址直接找GitHub release页面里Assets区域选.bin.gz结尾的文件就行。不需要HTTP代理普通网络基本能拖下来。如果被限速可以换浏览器多线程下载工具效果立竿见影。4. GUI客户端对接与首次运行4.1 命令行先验证引擎图形界面之前先用命令行验证引擎和权重能不能正常配合工作。在cpp/build/目录下执行./katago.exe gtp -model ../../weights/kata1-xxxx.bin.gz -config gtp_cfg.txt如果本地没有现成的gtp_cfg.txtKataGo默认配置也能跑。看到控制台输出GTP ready或者类似信息说明引擎已经加载完毕正在等待对弈指令。接着用简单命令试探一下boardsize 9 clear_board play B D4 play W Q16 genmove B如果引擎返回一个合法落子坐标比如C5说明整条链路引擎 权重 GTP交互已经全部打通。我习惯在这里先跑一局9路盘让引擎跟自己对弈确认不会中途崩溃再进图形界面。还有一种更直接的测试方式是使用analysis模式./katago.exe analysis -model ../../weights/kata1-xxxx.bin.gz -analysis cfg进入交互模式后可以逐手分析当前局面输出的JSON里包含胜率、目差和候选点。这一步验证的是引擎计算速度它会把每个候选点的访问量列出来我会优先查看visits数值是否在快速增长。如果数值卡住不动说明后端GPU加速没有真正生效可能是CUDA环境问题也可能是编译时后端选择错了。4.2 Lizzie配置命令行用得再顺日常复盘和看棋谱还是图形界面舒服。目前最主流的KataGo前端是Lizzie它本来是给Leela Zero设计的后来对KataGo也做了完整适配。Lizzie需要Java运行环境先去官网装一个JDK或者JRE版本建议11以上。然后从Lizzie的GitHub release下载打包版本解压后得到一个Lizzie目录。开启Lizzie后在界面上找到引擎设置把Engine Command设置为KataGo的可执行文件路径...\KataGo\cpp\build\katago.exeEngine Parameters处填gtp -model C:/path/to/kata1-xxx.bin.gz -config C:/path/to/gtp_cfg.txt注意路径分隔符用正斜杠或正确转义Windows下直接复制路径容易因为反斜杠问题导致引擎加载失败。曾经在这里卡了半小时后来发现是配置文件路径里的反斜杠把参数解析搞乱了。改成正斜杠之后一切正常别在这类小地方浪费人生。设置好后Lizzie会自动启动引擎并显示“Engine started”。之后你在棋盘上摆变化图右侧会实时显示胜率和目差鼠标悬停到候选点上能看到变化的后续棋谱。还有一个实用技巧在Lizzie的config.txt里把analyze-save-interval调短一些这样你在打谱过程中它自动保存的分析图密度更高复盘时能找到关键转折点的连续变化。4.3 Sabaki等其他前端除了Lizzie还有一款叫Sabaki的界面也可以连接KataGo。Sabaki本身是通用SGF编辑器支持对接GTP引擎在“Engines”里添加引擎路径和参数后就能使用。它比Lizzie更轻量适合只想快速看棋谱、不想开太重界面的场景。另外KataGo官方的Python包katago也提供了一些可视化辅助但多数还是以命令行和脚本为主。对普通用户来说Lizzie和Sabaki二选一即可别贪多。5. 常见问题与排查技巧实录5.1 编译阶段典型问题我把整个安装过程中最容易踩的坑整理成一个速查表遇到问题先对着查症状可能原因解决办法CMake报找不到CUDACUDA Toolkit装了但路径未加入系统变量重装CUDA到默认路径或在CMake参数中手动指定-DCUDAToolkit_ROOT...编译时提示C编译器版本过低VS Build Tools未安装完整C工作负载重新安装VS Build Tools勾选“使用C的桌面开发”编译速度极慢甚至中途卡死-j并行数太高导致内存溢出调低并行数比如-j 4编译通过但katago version无输出可能后端编译成了CPU或OpenCL版本确认CMake配置里-DUSE_BACKENDCUDA生效重编一次运行时报缺少cudnn64_8.dll之类权重推理依赖cuDNN下载对应版本的cuDNN解压后把.dll放进CUDA的bin目录内存溢出这个问题我在编译20B权重的辅助文件时碰到过一次并行线程直接打到16结果编译器进程被系统杀了。换成-j 8后稳定通过所以不要盲目追求并行数。5.2 运行阶段典型问题症状可能原因解决办法引擎启动后秒退权重路径错误、配置文件缺失先命令行手动运行确认路径无误再交界面工具权重加载报Parse error下载的文件不完整检查文件大小重新下载Lizzie界面显示不了分析引擎参数没传对或引擎进程未启动回到4.2节检查参数配置文件中路径两端需要加双引号跑一段时间后速度变慢可能是显存过热降频观察GPU温度清理积灰降低权重规模OpenCL后端但程序报找不到platform缺少显卡厂商的OpenCL运行库安装对应显卡驱动、AMD或NVIDIA完整版驱动即可让子棋分析时引擎几乎只走一个点检查是否用了过小的权重且KataGo默认策略可能偏向保守调整配置文件里的分析参数比如提高playoutDoubling或使用更大权重引擎秒退这种看起来最吓人的问题实际排查思路其实很朴素先把GUI撤掉用命令行原样启动看看终端报什么错。绝大多数路径错误、缺文件、参数格式错误都会在命令行里原形毕露。我在这块的经验是任何和图形界面有关的问题第一反应永远是用命令行复现一遍。5.3 通用避坑心得最后分享几条折腾过程中沉淀下来的经验路径里不要带中文和空格。不少C程序对路径编码处理得很暴力中文目录名轻则让权重加载失败重则让整体环境变量解析错乱。宁可目录名丑一点也别给它加戏。配置文件不要放在桌面。某些环境权限策略会导致桌面文件读取异常我第一次就栽在把gtp_cfg.txt放在桌面上了。权重文件不需要解压。看到.bin.gz就直接丢给引擎它自己会处理压缩。手贱解压了反而可能导致引擎读不了二进制格式。安装CUDA后一定要重启一次系统。部分显卡驱动需要重启才能完整加载环境变量不然nvidia-smi可能正常但实际API调用全挂。引擎和前端版本要匹配。Lizzie老版本对KataGo新版本的GTP输出解析不够好如果信号接上了但分析框空白先试试升级Lizzie到最新版。分析模式的visits不一定要拉到几千。日常复盘开到300到500 visits已经很能说明问题再往上对普通棋友来说只是自我感动还白白消耗显卡寿命。我个人在实际操作中的体会是KataGo的安装表面上看是个典型“下载源码—编译—下权重—接前端”的流水线但真正让你走顺的反而是对每一步背后逻辑的理解。比如为什么要选CUDA而不是OpenCL为什么编译一定要选Release为什么权重直接扔给引擎不用解压这些事想明白了以后不管是在Windows上重装还是在Linux服务器上部署你都有能力快速复现而不用再去翻第二遍教程。如果你打算长期用它来复盘和练棋建议装完之后再多做一件事用KataGo跑一遍自己最近输得最痛的一盘棋把关键胜负处逐一分析那种感觉就像终于有人能一针见血地告诉你“这手棋错在哪了”。这也是我最终愿意花一下午把KataGo从头到尾装完的最大动力。