简介一套面向围棋AI开发学习者的完整源码前端采用ElectronVue构建桌面交互界面后端基于Python与PyTorch实现卷积神经网络与强化学习引擎适合对计算机博弈、深度学习实战感兴趣的中高级开发者参考。资源共86个文件压缩包仅1.41MB结构紧凑但覆盖完整。核心包含30个Python脚本负责CNN模型定义、训练、对弈与胜率检测等逻辑前端约18个JavaScript与6个Vue文件支撑棋盘渲染、交互事件与桌面壳通信另有EJS模板、Webpack配置、图标与Markdown文档等辅助文件方便二次构建与阅读。目前已有1356人学习下载。读者可从中获得完整的前后端联调范例、模型训练与推理脚本、棋盘逻辑与数据库设计以及tree search、anti-overfitting等关键实现适合快速理解AI围棋系统的工程化落地方式也可作为基于ElectronPython的AI应用开发参考。1. 当一个围棋 AI 桌面应用把 PyTorch 放进 zip如果你手上正好拿到一份“围棋 AI 软件源码”的压缩包打开后你大概率会看到两个完全不同的世界前端是 Electron 加 Vue 写的桌面棋盘界面后端是 Python 加 torch 训练好的神经网络模型。一个明显的问题是为什么一个棋类 AI 不干脆全部用 Python 写偏偏要套一层 Electron答案通常在发行形态上——面向普通用户的桌面软件需要窗口、菜单、棋盘交互甚至要接电子棋盘硬件而推理引擎这边PyTorch 生态成熟模型文件、落子算法都是现成的。两边各干各的再由应用层把棋盘坐标串起来。这篇文章就是顺着这个标题往下拆前端怎么搭骨架、怎么和串口棋盘通信后端怎么加载 torch 模型、怎么把 19 路棋盘变成张量最后怎么在打包和联调阶段踩掉最常见的坑。对 Vue 有基础、对 Python 有基础但没把两端拼成一个桌面软件的读者最合适。2. 架构与通信路线ElectronVue 驱动 Python 推理进程2.1 为什么 torch 不在 Electron 里面跑看到 Electron Vue Python torch 这种组合第一反应可能是“为什么不干脆用 ONNX Runtime 在 Node 里推理”。这个问题问得对但实际源码里很少这样改。原因有三点一是模型可能是 AlphaZero 风格的自定义结构里面有残差块、批归一化转 ONNX 时 BatchNorm 的 dynamic reshape 很容易出岔子二是训练代码是 Python 写的验证脚本、棋谱转特征的工具链都在 Python 侧把推理留在 torch 里能让模型版本和训练版本严格对齐三是 GPU 加速在 Node 侧没有官方支持torch 的 CUDA 生态才是主流。所以常见做法不是替换推理引擎而是让 Electron 应用把一个 Python 进程当“推理微服务”来调用。这就引出一个关键决策两端之间用什么协议通信。选型不需要花哨我一般会在三个方案里挑按项目复杂度从低到高排序。通信方式适用场景优点要注意的坑HTTP 接口Flask/FastAPI单机、每手棋计算时间在百毫秒到几秒前后端完全解耦Python 侧可独立测试curl 就能验证端口冲突、首次请求要等模型加载WebSocket需要实时推送胜率、思考过程、多客户端订阅双工通道适合流式输出断线重连、心跳保活要自己写子进程 stdio JSON随 Electron 应用一起分发不想暴露端口进程生命周期由 Electron 管理启动即拉起跨平台 spawn 参数差异、输出日志混杂这三条路线里HTTP 是最容易先跑通的也是大多数“源码包”默认的接入方式。只要 Python 服务监听 127.0.0.1 的某个端口Vue 侧用 axios 或者原生 fetch 就能发请求。如果你发现源码里用的是 WebSocket那多半是为了在界面上展示“AI 正在计算”的中间过程比如每 0.2 秒推送一次策略网络的候选点。选哪种不改变围棋 AI 的核心逻辑只改变两端对接的接口形状。2.2 棋盘数据的序列化标准前端把一次对弈局面交给后端后端返回落子坐标这个数据交换需要一个双方都认可的结构。常见的做法是传完整的棋盘状态而不是只传增量落子因为 torch 模型的特征输入一般需要最近若干手的历史信息。接口体一般长这样{ board: [[0,0,0,1,0,...],[],[]], color: 1, ko: null, last_move: [3, 15] }board用二维数组表示 19 路棋盘0 空、1 黑、-1 白color表示当前该谁下last_move用来判断打劫和禁着点。后端拿到之后要负责两件事一是把历史局面转成神经网络的输入张量二是用规则引擎算出合法落子集合把网络输出的禁着点概率全部清零。2.3 Python 服务的进程生命周期如果选择 HTTP 路线前端启动时怎么拉起 Python 服务是个细节问题处理不好会留下一堆僵尸进程。我见过最稳的方案是Electron 主进程在app.whenReady()之后用child_process.spawn启动 Python参数里带--port 8765等后端打印出listening on 127.0.0.1:8765再创建浏览器窗口。退出时在will-quit里调用proc.kill()。这里有个坑spawn的windowsHide: true在 Windows 上必须显式设置否则每次启动软件都会弹一个黑色控制台窗口。3. 前端实现Vue 组件、Electron 主进程与串口棋盘接入3.1 用 electron-vite 搭一个可调试的最小骨架这个标题涉及的前端部分最靠谱的工程化起点是 electron-vite。它把 main、preload、renderer 三块结构直接分好开发时热更新打包时自动处理资源路径。我习惯这样初始化npm create quick-start/electronlatest go-baduk -- --template vue cd go-baduk npm install npm run dev执行这条命令之后你会得到src/main、src/preload、src/renderer三个目录。main 目录放 Electron 主进程代码preload 目录暴露安全的桥接接口renderer 就是 Vue 应用本体。这里的核心设计是安全边界nodeIntegration要保持falseVue 渲染层不能直接碰 Node API所有需要主进程能力的操作都通过 preload 暴露。这样做不只是安全考虑更是为了调试时能在浏览器环境下跑通 Vue 组件而不依赖 Electron 的 Node 环境。3.2 通过 preload 桥接 Vue 与主进程围棋 AI 软件里最常见的 IPC 场景是Vue 组件里点击“落子”棋盘坐标要发给 Python 后端而后端跑完后把结果推回 Vue。这条链路可以不走主进程中转直接由 Vue 发起 HTTP 请求到 Python 服务但遇到串口数据比如电子棋盘传感器返回的信号就必须经过主进程因为serialport是 Node 原生模块在 renderer 里无法保证可用。preload 层的代码形态一般是这样// src/preload/index.js import { contextBridge, ipcRenderer } from electron contextBridge.exposeInMainWorld(api, { selectPort: () ipcRenderer.invoke(serial:list), openPort: (path, baudRate) ipcRenderer.invoke(serial:open, path, baudRate), onBoardData: (callback) { const listener (_event, data) callback(data) ipcRenderer.on(serial:data, listener) return () ipcRenderer.removeListener(serial:data, listener) } })对应的主进程里用ipcMain.handle注册serial:list和serial:open。Vue 组件里通过window.api.onBoardData订阅落子事件拿到坐标后再调用后端推理接口。这套桥接的好处是 Vue 侧代码不关心数据到底是从串口来的还是从鼠标点出来的统一走同一个onBoardData回调逻辑就非常干净。3.3 串口数据解析与粘包处理接入电子棋盘时历史棋盘的一手棋会从串口输出一行坐标字符串不同硬件格式不太一样我遇到比较多的是A1、T19这种字母加数字的格式末尾带\n。如果直接每次data事件都当成完整一行来解析打开棋盘电源瞬间的数据流会截断成两截出现乱码。标准解法是累积缓冲、按换行符切分// src/main/serial.js let buffer serialPort.on(data, (chunk) { buffer chunk.toString(utf8) let newlineIndex while ((newlineIndex buffer.indexOf(\n)) ! -1) { const line buffer.slice(0, newlineIndex).trim() buffer buffer.slice(newlineIndex 1) if (/^[A-T][0-9]{1,2}$/.test(line)) { mainWindow.webContents.send(serial:data, line) } } })这里的正则限定[A-T]而不是随意字母是为了过滤掉串口线上的噪声数据。坐标转成棋盘索引的算法也比较固定列字母用charCodeAt(0) - 65行号字符串转数字减 1得到[row, col]。注意字母I在围棋坐标里通常被跳过如果你拿到的是H之后直接J下标计算要加个特判。3.4 Vue 组件里组织对局状态与 AI 落子流程渲染层用 Vue 管理对局状态核心是一个响应式对象至少包含board、currentColor、gameOver、thinking。当用户落子或串口传来坐标之后提交到 store同时把thinking置为true然后向后端发起推理请求。典型的 Vue 3 组合式函数写法大概是// src/renderer/src/composables/useGame.js export function useGame() { const board ref(Array.from({ length: 19 }, () Array(19).fill(0))) const thinking ref(false) async function playAt(row, col) { if (board.value[row][col] ! 0 || thinking.value) return board.value[row][col] currentColor.value thinking.value true try { const { move } await window.api.requestMove(mapBoardToPayload(board.value, currentColor.value)) const [r, c] move board.value[r][c] currentColor.value * -1 } finally { thinking.value false } } return { board, playAt } }这段代码的要点是thinking标志位它同时承担两个职责防止 AI 计算过程中用户重复落子以及驱动界面的“AI 思考中”动画。头部加上这层状态管理后面要接 WebSocket 推送或者悔棋功能都只需要扩展这个组合式函数。4. 后端推理服务Python torch 加载模型并输出落子4.1 torch 环境安装CPU 与 GPU 版本怎么选这个标题下的源码包里通常不会附带 Python 环境装 torch 是跑起来的第一步。这里的热门坑就是版本选择。如果你只是为了在开发机上跑通推理CPU 版 torch 足够如果模型的批次较大或者对单步计算时间有要求比如读秒 5 秒内必须落子那就装 CUDA 版。# CPU 版本适合快速验证 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # CUDA 12.1 版本适合有 N 卡的用户 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121不要直接pip install torch不指定源那会拉到默认的 PyPI 包体体积大一倍还不一定带 CUDA 支持。装完验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())注意torch.cuda.is_available()返回False不代表 torch 坏了它只表示当前这轮推理走 CPU。对围棋 AI 来说真是瓶颈不在模型前向传播而在蒙特卡洛树搜索的模拟次数模型一次前向可能只要 20 毫秒搜索几百次模拟才花掉大部分时间。项目规模不大时CPU 版和 GPU 版在最终胜率上不会差太远。4.2 把 19 路棋盘构造成模型输入张量torch 模型的输入一般是[N, C, 19, 19]的浮点张量N是 batch sizeC是特征通道数具体是多少取决于模型设计。常见配置是 4 到 17 个通道当前玩家的子力分布、对手的子力分布、最近几手的历史、当前玩家是否为黑棋、以及全 1 或全 0 的常数平面帮助模型感知边界。实现时一般不能直接把二维 list 塞进torch.tensor要先把 board 里的 0/1/-1 分成两个平面def board_to_features(board, current_color): board: 19x19 list, 1 黑, -1 白, 0 空 current_color: 1 或 -1表示当前该谁下 返回: [17, 19, 19] 的 numpy 数组 # 把 board 按当前玩家视角归一化 planes np.zeros((17, 19, 19), dtypenp.float32) perspective board * current_color # 当前玩家视角1 己方-1 对方 planes[0] (perspective 1).astype(np.float32) planes[1] (perspective -1).astype(np.float32) # 补充历史信息和常数平面按模型定义决定用几个通道 for i in range(2, 17): planes[i] 1.0 if i % 2 0 else 0.0 return planes这个函数是整个前后端转化的核心源码包里的实现可能更复杂但基本思路是一样的把人类的棋谱表示变成网络的“视角”。实际使用中忘记做current_color乘上-1的视角归一化是最容易出的逻辑错模型会把黑白双方的下法完全学反。4.3 推理接口合法落子过滤与落子坐标映射后端服务的核心接口除了解析请求、调用模型之外最难的一步是把网络的策略输出和规则引擎结合。模型输出的 logits 形状是[1, 19*19 1]多出来的 1 通常代表“跳过一手”或“认输”源码包里不一定统一要仔细看模型定义。在拿到 logits 之后所有非法落子的位置要置为-inf再走 softmax这样 AI 永远不会建议把子下在已经有了棋子的地方masked_logits logits[:, :19*19].clone() for pos in illegal_positions: masked_logits[0, pos] -float(inf) probs torch.softmax(masked_logits, dim1) best_action int(torch.argmax(probs[0])) row, col best_action // 19, best_action % 194.4 启动一个最小可用的推理服务如果源码包里已经有 Flask 或 FastAPI 的入口文件直接按它的依赖列表来如果没有最小的服务也就三十行左右from flask import Flask, request, jsonify import torch app Flask(__name__) model None def load_model(path, devicecpu): global model model torch.load(path, map_locationdevice) model.eval() app.route(/api/move, methods[POST]) def api_move(): data request.get_json() board data[board] color data[color] # 构造特征和合法落子集合省略 with torch.no_grad(): logits, value model(features) # 过滤合法落子 best_action select_best_action(logits, legal_mask) return jsonify({move: [best_action // 19, best_action % 19], value: value.item()}) if __name__ __main__: load_model(model.pt) app.run(host127.0.0.1, port8765, threadedFalse)代码里强调threadedFalse是有原因的PyTorch 的推理不是严格线程安全的多线程模式下并发请求可能出现 CUDA 错误或者奇怪的段错误。性能不够就把 batch 做大而不是开线程。5. 进阶排错模型路径、torch 轮子与串口打包的三个实测技巧5.1 用一个 curl 验证整个后端链路拿到源码包先别急着点开 Electron 界面先把后端单独拉起来测一次。启动服务之后发一个真实的局面请求确认模型能出结果再联调前端curl -X POST http://127.0.0.1:8765/api/move \ -H Content-Type: application/json \ -d {board: [[0,0,0,...]], color: 1, legal: []}看返回是合法坐标还是报错。如果返回 500 且日志里提示size mismatch说明模型文件与当前代码的输入通道定义不一致多半是特征通道数写错了不是模型文件损坏。先验证后端再验证前端能省掉一半以上的联调时间。5.2 torch 模型加载的三个慢问题和版本兼容第一个坑是torch.load默认把 tensor 加载到保存时的设备上如果模型在 GPU 机器上训练而你的开发机只有 CPU必须指定map_locationcpu。第二个坑是模型文件里如果包含自定义的类定义比如网络结构写在model.py里torch.load会依赖这个类的定义在作用域中存在直接换台机器加载容易报ModuleNotFoundError。第三个坑是 Python 版本和 torch 轮子的对应关系Python 3.12 刚出时 torch 还没有对应轮子直接pip install torch会拉到旧版本。这种问题排查的第一步永远是看torch.__version__和python --version是否匹配。5.3 Electron 打包时 serialport 原生模块的处理最后到了把整个应用分发给别人的环节。serialport是原生模块打包时不能用纯 JS 的处理方式。我常用的做法是electron-builder里配置asarUnpack把serialport及其依赖从 asar 包中解出来否则运行时会在node_modules/serialport下找不到二进制文件。另外启动后如果发现渲染层能打开但串口列表为空先去系统设置里给终端或应用授予“蓝牙”和“USB 设备”权限命令行的 Electron 开发和桌面分发的权限模型不一样这个问题在 macOS 上特别明显。把这几点在配置里提前处理掉打包出来的产物才是真正能发给别人用的安装包。本文还有配套的精品资源点击获取
Electron+Vue+PyTorch：构建围棋AI桌面应用的完整实践
简介一套面向围棋AI开发学习者的完整源码前端采用ElectronVue构建桌面交互界面后端基于Python与PyTorch实现卷积神经网络与强化学习引擎适合对计算机博弈、深度学习实战感兴趣的中高级开发者参考。资源共86个文件压缩包仅1.41MB结构紧凑但覆盖完整。核心包含30个Python脚本负责CNN模型定义、训练、对弈与胜率检测等逻辑前端约18个JavaScript与6个Vue文件支撑棋盘渲染、交互事件与桌面壳通信另有EJS模板、Webpack配置、图标与Markdown文档等辅助文件方便二次构建与阅读。目前已有1356人学习下载。读者可从中获得完整的前后端联调范例、模型训练与推理脚本、棋盘逻辑与数据库设计以及tree search、anti-overfitting等关键实现适合快速理解AI围棋系统的工程化落地方式也可作为基于ElectronPython的AI应用开发参考。1. 当一个围棋 AI 桌面应用把 PyTorch 放进 zip如果你手上正好拿到一份“围棋 AI 软件源码”的压缩包打开后你大概率会看到两个完全不同的世界前端是 Electron 加 Vue 写的桌面棋盘界面后端是 Python 加 torch 训练好的神经网络模型。一个明显的问题是为什么一个棋类 AI 不干脆全部用 Python 写偏偏要套一层 Electron答案通常在发行形态上——面向普通用户的桌面软件需要窗口、菜单、棋盘交互甚至要接电子棋盘硬件而推理引擎这边PyTorch 生态成熟模型文件、落子算法都是现成的。两边各干各的再由应用层把棋盘坐标串起来。这篇文章就是顺着这个标题往下拆前端怎么搭骨架、怎么和串口棋盘通信后端怎么加载 torch 模型、怎么把 19 路棋盘变成张量最后怎么在打包和联调阶段踩掉最常见的坑。对 Vue 有基础、对 Python 有基础但没把两端拼成一个桌面软件的读者最合适。2. 架构与通信路线ElectronVue 驱动 Python 推理进程2.1 为什么 torch 不在 Electron 里面跑看到 Electron Vue Python torch 这种组合第一反应可能是“为什么不干脆用 ONNX Runtime 在 Node 里推理”。这个问题问得对但实际源码里很少这样改。原因有三点一是模型可能是 AlphaZero 风格的自定义结构里面有残差块、批归一化转 ONNX 时 BatchNorm 的 dynamic reshape 很容易出岔子二是训练代码是 Python 写的验证脚本、棋谱转特征的工具链都在 Python 侧把推理留在 torch 里能让模型版本和训练版本严格对齐三是 GPU 加速在 Node 侧没有官方支持torch 的 CUDA 生态才是主流。所以常见做法不是替换推理引擎而是让 Electron 应用把一个 Python 进程当“推理微服务”来调用。这就引出一个关键决策两端之间用什么协议通信。选型不需要花哨我一般会在三个方案里挑按项目复杂度从低到高排序。通信方式适用场景优点要注意的坑HTTP 接口Flask/FastAPI单机、每手棋计算时间在百毫秒到几秒前后端完全解耦Python 侧可独立测试curl 就能验证端口冲突、首次请求要等模型加载WebSocket需要实时推送胜率、思考过程、多客户端订阅双工通道适合流式输出断线重连、心跳保活要自己写子进程 stdio JSON随 Electron 应用一起分发不想暴露端口进程生命周期由 Electron 管理启动即拉起跨平台 spawn 参数差异、输出日志混杂这三条路线里HTTP 是最容易先跑通的也是大多数“源码包”默认的接入方式。只要 Python 服务监听 127.0.0.1 的某个端口Vue 侧用 axios 或者原生 fetch 就能发请求。如果你发现源码里用的是 WebSocket那多半是为了在界面上展示“AI 正在计算”的中间过程比如每 0.2 秒推送一次策略网络的候选点。选哪种不改变围棋 AI 的核心逻辑只改变两端对接的接口形状。2.2 棋盘数据的序列化标准前端把一次对弈局面交给后端后端返回落子坐标这个数据交换需要一个双方都认可的结构。常见的做法是传完整的棋盘状态而不是只传增量落子因为 torch 模型的特征输入一般需要最近若干手的历史信息。接口体一般长这样{ board: [[0,0,0,1,0,...],[],[]], color: 1, ko: null, last_move: [3, 15] }board用二维数组表示 19 路棋盘0 空、1 黑、-1 白color表示当前该谁下last_move用来判断打劫和禁着点。后端拿到之后要负责两件事一是把历史局面转成神经网络的输入张量二是用规则引擎算出合法落子集合把网络输出的禁着点概率全部清零。2.3 Python 服务的进程生命周期如果选择 HTTP 路线前端启动时怎么拉起 Python 服务是个细节问题处理不好会留下一堆僵尸进程。我见过最稳的方案是Electron 主进程在app.whenReady()之后用child_process.spawn启动 Python参数里带--port 8765等后端打印出listening on 127.0.0.1:8765再创建浏览器窗口。退出时在will-quit里调用proc.kill()。这里有个坑spawn的windowsHide: true在 Windows 上必须显式设置否则每次启动软件都会弹一个黑色控制台窗口。3. 前端实现Vue 组件、Electron 主进程与串口棋盘接入3.1 用 electron-vite 搭一个可调试的最小骨架这个标题涉及的前端部分最靠谱的工程化起点是 electron-vite。它把 main、preload、renderer 三块结构直接分好开发时热更新打包时自动处理资源路径。我习惯这样初始化npm create quick-start/electronlatest go-baduk -- --template vue cd go-baduk npm install npm run dev执行这条命令之后你会得到src/main、src/preload、src/renderer三个目录。main 目录放 Electron 主进程代码preload 目录暴露安全的桥接接口renderer 就是 Vue 应用本体。这里的核心设计是安全边界nodeIntegration要保持falseVue 渲染层不能直接碰 Node API所有需要主进程能力的操作都通过 preload 暴露。这样做不只是安全考虑更是为了调试时能在浏览器环境下跑通 Vue 组件而不依赖 Electron 的 Node 环境。3.2 通过 preload 桥接 Vue 与主进程围棋 AI 软件里最常见的 IPC 场景是Vue 组件里点击“落子”棋盘坐标要发给 Python 后端而后端跑完后把结果推回 Vue。这条链路可以不走主进程中转直接由 Vue 发起 HTTP 请求到 Python 服务但遇到串口数据比如电子棋盘传感器返回的信号就必须经过主进程因为serialport是 Node 原生模块在 renderer 里无法保证可用。preload 层的代码形态一般是这样// src/preload/index.js import { contextBridge, ipcRenderer } from electron contextBridge.exposeInMainWorld(api, { selectPort: () ipcRenderer.invoke(serial:list), openPort: (path, baudRate) ipcRenderer.invoke(serial:open, path, baudRate), onBoardData: (callback) { const listener (_event, data) callback(data) ipcRenderer.on(serial:data, listener) return () ipcRenderer.removeListener(serial:data, listener) } })对应的主进程里用ipcMain.handle注册serial:list和serial:open。Vue 组件里通过window.api.onBoardData订阅落子事件拿到坐标后再调用后端推理接口。这套桥接的好处是 Vue 侧代码不关心数据到底是从串口来的还是从鼠标点出来的统一走同一个onBoardData回调逻辑就非常干净。3.3 串口数据解析与粘包处理接入电子棋盘时历史棋盘的一手棋会从串口输出一行坐标字符串不同硬件格式不太一样我遇到比较多的是A1、T19这种字母加数字的格式末尾带\n。如果直接每次data事件都当成完整一行来解析打开棋盘电源瞬间的数据流会截断成两截出现乱码。标准解法是累积缓冲、按换行符切分// src/main/serial.js let buffer serialPort.on(data, (chunk) { buffer chunk.toString(utf8) let newlineIndex while ((newlineIndex buffer.indexOf(\n)) ! -1) { const line buffer.slice(0, newlineIndex).trim() buffer buffer.slice(newlineIndex 1) if (/^[A-T][0-9]{1,2}$/.test(line)) { mainWindow.webContents.send(serial:data, line) } } })这里的正则限定[A-T]而不是随意字母是为了过滤掉串口线上的噪声数据。坐标转成棋盘索引的算法也比较固定列字母用charCodeAt(0) - 65行号字符串转数字减 1得到[row, col]。注意字母I在围棋坐标里通常被跳过如果你拿到的是H之后直接J下标计算要加个特判。3.4 Vue 组件里组织对局状态与 AI 落子流程渲染层用 Vue 管理对局状态核心是一个响应式对象至少包含board、currentColor、gameOver、thinking。当用户落子或串口传来坐标之后提交到 store同时把thinking置为true然后向后端发起推理请求。典型的 Vue 3 组合式函数写法大概是// src/renderer/src/composables/useGame.js export function useGame() { const board ref(Array.from({ length: 19 }, () Array(19).fill(0))) const thinking ref(false) async function playAt(row, col) { if (board.value[row][col] ! 0 || thinking.value) return board.value[row][col] currentColor.value thinking.value true try { const { move } await window.api.requestMove(mapBoardToPayload(board.value, currentColor.value)) const [r, c] move board.value[r][c] currentColor.value * -1 } finally { thinking.value false } } return { board, playAt } }这段代码的要点是thinking标志位它同时承担两个职责防止 AI 计算过程中用户重复落子以及驱动界面的“AI 思考中”动画。头部加上这层状态管理后面要接 WebSocket 推送或者悔棋功能都只需要扩展这个组合式函数。4. 后端推理服务Python torch 加载模型并输出落子4.1 torch 环境安装CPU 与 GPU 版本怎么选这个标题下的源码包里通常不会附带 Python 环境装 torch 是跑起来的第一步。这里的热门坑就是版本选择。如果你只是为了在开发机上跑通推理CPU 版 torch 足够如果模型的批次较大或者对单步计算时间有要求比如读秒 5 秒内必须落子那就装 CUDA 版。# CPU 版本适合快速验证 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # CUDA 12.1 版本适合有 N 卡的用户 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121不要直接pip install torch不指定源那会拉到默认的 PyPI 包体体积大一倍还不一定带 CUDA 支持。装完验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())注意torch.cuda.is_available()返回False不代表 torch 坏了它只表示当前这轮推理走 CPU。对围棋 AI 来说真是瓶颈不在模型前向传播而在蒙特卡洛树搜索的模拟次数模型一次前向可能只要 20 毫秒搜索几百次模拟才花掉大部分时间。项目规模不大时CPU 版和 GPU 版在最终胜率上不会差太远。4.2 把 19 路棋盘构造成模型输入张量torch 模型的输入一般是[N, C, 19, 19]的浮点张量N是 batch sizeC是特征通道数具体是多少取决于模型设计。常见配置是 4 到 17 个通道当前玩家的子力分布、对手的子力分布、最近几手的历史、当前玩家是否为黑棋、以及全 1 或全 0 的常数平面帮助模型感知边界。实现时一般不能直接把二维 list 塞进torch.tensor要先把 board 里的 0/1/-1 分成两个平面def board_to_features(board, current_color): board: 19x19 list, 1 黑, -1 白, 0 空 current_color: 1 或 -1表示当前该谁下 返回: [17, 19, 19] 的 numpy 数组 # 把 board 按当前玩家视角归一化 planes np.zeros((17, 19, 19), dtypenp.float32) perspective board * current_color # 当前玩家视角1 己方-1 对方 planes[0] (perspective 1).astype(np.float32) planes[1] (perspective -1).astype(np.float32) # 补充历史信息和常数平面按模型定义决定用几个通道 for i in range(2, 17): planes[i] 1.0 if i % 2 0 else 0.0 return planes这个函数是整个前后端转化的核心源码包里的实现可能更复杂但基本思路是一样的把人类的棋谱表示变成网络的“视角”。实际使用中忘记做current_color乘上-1的视角归一化是最容易出的逻辑错模型会把黑白双方的下法完全学反。4.3 推理接口合法落子过滤与落子坐标映射后端服务的核心接口除了解析请求、调用模型之外最难的一步是把网络的策略输出和规则引擎结合。模型输出的 logits 形状是[1, 19*19 1]多出来的 1 通常代表“跳过一手”或“认输”源码包里不一定统一要仔细看模型定义。在拿到 logits 之后所有非法落子的位置要置为-inf再走 softmax这样 AI 永远不会建议把子下在已经有了棋子的地方masked_logits logits[:, :19*19].clone() for pos in illegal_positions: masked_logits[0, pos] -float(inf) probs torch.softmax(masked_logits, dim1) best_action int(torch.argmax(probs[0])) row, col best_action // 19, best_action % 194.4 启动一个最小可用的推理服务如果源码包里已经有 Flask 或 FastAPI 的入口文件直接按它的依赖列表来如果没有最小的服务也就三十行左右from flask import Flask, request, jsonify import torch app Flask(__name__) model None def load_model(path, devicecpu): global model model torch.load(path, map_locationdevice) model.eval() app.route(/api/move, methods[POST]) def api_move(): data request.get_json() board data[board] color data[color] # 构造特征和合法落子集合省略 with torch.no_grad(): logits, value model(features) # 过滤合法落子 best_action select_best_action(logits, legal_mask) return jsonify({move: [best_action // 19, best_action % 19], value: value.item()}) if __name__ __main__: load_model(model.pt) app.run(host127.0.0.1, port8765, threadedFalse)代码里强调threadedFalse是有原因的PyTorch 的推理不是严格线程安全的多线程模式下并发请求可能出现 CUDA 错误或者奇怪的段错误。性能不够就把 batch 做大而不是开线程。5. 进阶排错模型路径、torch 轮子与串口打包的三个实测技巧5.1 用一个 curl 验证整个后端链路拿到源码包先别急着点开 Electron 界面先把后端单独拉起来测一次。启动服务之后发一个真实的局面请求确认模型能出结果再联调前端curl -X POST http://127.0.0.1:8765/api/move \ -H Content-Type: application/json \ -d {board: [[0,0,0,...]], color: 1, legal: []}看返回是合法坐标还是报错。如果返回 500 且日志里提示size mismatch说明模型文件与当前代码的输入通道定义不一致多半是特征通道数写错了不是模型文件损坏。先验证后端再验证前端能省掉一半以上的联调时间。5.2 torch 模型加载的三个慢问题和版本兼容第一个坑是torch.load默认把 tensor 加载到保存时的设备上如果模型在 GPU 机器上训练而你的开发机只有 CPU必须指定map_locationcpu。第二个坑是模型文件里如果包含自定义的类定义比如网络结构写在model.py里torch.load会依赖这个类的定义在作用域中存在直接换台机器加载容易报ModuleNotFoundError。第三个坑是 Python 版本和 torch 轮子的对应关系Python 3.12 刚出时 torch 还没有对应轮子直接pip install torch会拉到旧版本。这种问题排查的第一步永远是看torch.__version__和python --version是否匹配。5.3 Electron 打包时 serialport 原生模块的处理最后到了把整个应用分发给别人的环节。serialport是原生模块打包时不能用纯 JS 的处理方式。我常用的做法是electron-builder里配置asarUnpack把serialport及其依赖从 asar 包中解出来否则运行时会在node_modules/serialport下找不到二进制文件。另外启动后如果发现渲染层能打开但串口列表为空先去系统设置里给终端或应用授予“蓝牙”和“USB 设备”权限命令行的 Electron 开发和桌面分发的权限模型不一样这个问题在 macOS 上特别明显。把这几点在配置里提前处理掉打包出来的产物才是真正能发给别人用的安装包。本文还有配套的精品资源点击获取