从 OpenCV 模板匹配到 YOLO：TFT 截图识别模块的一次升级

摘要在前几篇文章中项目已经完成了 TFT 阵容顾问的资源构建、英雄识别、装备识别和截图路由层。旧方案主要依赖 tft_screen_capture.py通过 OpenCV 完成六边形边框检测、HSV 直方图粗筛、灰度 NCC 模板匹配等流程。这套方案的优点是实现清晰、依赖轻、CPU 即可运行但随着识别场景变复杂它的上限也逐渐暴露出来截图来源不统一、边框颜色变化、英雄头像缩放、UI 遮挡、无框截图等情况都会影响识别稳定性。因此本阶段项目开始引入新的识别引擎tft_yolo_clip.py。它采用 YOLO CLIP 的双阶段思路将原来“靠规则找位置、靠模板猜身份”的流程升级为“YOLO 负责定位CLIP 负责识别”。一、旧方案已经解决了什么旧版本截图识别链路主要集中在 tft_screen_capture.py 中。整体流程可以概括为截图↓判断截图类型↓检测英雄候选框↓裁剪英雄头像区域↓HSV 直方图粗筛↓灰度 NCC 精匹配↓输出英雄、星级、装备、站位这个方案不是简单的模板匹配而是经过多轮工程优化的结果。例如模板图片不是手动维护而是由 tft_fetch_assets.py 从赛季数据库中构建。英雄 PNG 的透明区域会合成到中性灰背景避免透明像素变成黑色影响匹配。英雄识别不是全库暴力匹配而是先用 HSV 直方图筛出候选再用零均值 NCC 精筛。棋盘图、横排结算图、全局阵容表、战绩回顾图会先通过 detect_screenshot_mode() 分流。所以旧方案的价值在于它把截图识别从“能跑”推进到了“有工程结构”。二、为什么仍然需要切换到 YOLOOpenCV 方案的核心假设是截图中存在可解释的视觉规律。例如棋盘模式里英雄通常位于带颜色边框的六边形格子中所以可以通过 HSV 范围检测青色、紫色、金色、蓝色边框。但真实截图并不总是这么理想。当截图来自不同分辨率、不同客户端、不同页面甚至头像区域没有明显边框时旧方案就会遇到几个问题问题OpenCV 方案的表现边框颜色变化HSV 阈值需要重新调头像缩放不同模板匹配分数下降UI 图标干扰需要继续补过滤规则无明显六边形边框候选框可能检测不到新赛季英雄变化模板库和阈值都要维护也就是说旧方案的问题不是某一行代码写得不好而是方法本身依赖太多人工规则。当规则越来越多时系统会从“可解释”慢慢变成“难维护”。这就是引入 YOLO 的原因。三、迁移的核心思路先拆开“定位”和“识别”旧方案中“找到英雄在哪里”和“判断英雄是谁”是强绑定的。例如检测六边形边框 → 裁剪头像 → 模板匹配如果第一步边框检测失败后面的英雄识别也就没有机会执行。新方案把问题拆成两个阶段截图↓YOLO 检测英雄位置↓裁剪英雄区域↓CLIP 判断英雄身份↓输出结构化结果这里最重要的变化是YOLO 不需要知道边框是什么颜色它只需要学习“英雄头像区域长什么样”。而 CLIP 不依赖本地模板图片逐像素相似它通过图像和文本之间的语义相似度来判断候选英雄。这让整个识别链路从“像素规则”开始转向“目标检测 语义识别”。四、当前新增的 YOLOCLIP 模块本阶段新增的核心文件是tft_yolo_clip.py它的定位是一个新的截图识别引擎而不是直接删除旧的 OpenCV 方案。原因很实际旧方案已经支持装备识别、截图路由、Web 上传入口等功能直接替换风险较高。因此当前更合理的做法是并行引入新引擎先验证 YOLO 的检测能力再逐步接入主流程。当前模块中的关键配置包括YOLO_MODEL_PATH Path(./tft_yolo_models/tft_champion_det.pt) CLIP_MODEL_NAME ViT-B/32 DETECT_CONF 0.25 IOU_THRESHOLD 0.45 CLIP_THRESHOLD 0.50其中DETECT_CONF 控制 YOLO 检测框的置信度IOU_THRESHOLD 用于去除重复框CLIP_THRESHOLD 控制英雄语义识别的最低相似度tft_yolo_models/ 用来存放后续训练得到的检测模型。五、YOLO 在这里主要解决“英雄在哪里”新模块中的 detect_heroes_yolo() 负责检测英雄候选框。它不再扫描 HSV 边框也不再依赖六边形轮廓而是让 YOLO 直接输出 bounding box。这一步的意义很大旧方案识别的是“边框”再推断里面有英雄新方案识别的是“英雄区域”本身。这会让识别更适合处理以下场景无边框或弱边框截图英雄头像尺寸变化棋盘、结算、回顾等不同截图版式UI 颜色变化后续接入真实游戏截图。当然当前如果只使用预训练 yolov8n.pt检测效果不会理想因为通用 YOLO 没有专门学过 TFT 英雄头像。因此后续仍需要准备截图数据并训练专用模型。六、CLIP 在这里主要解决“这个英雄是谁”YOLO 检测到框以后系统会裁剪每个英雄区域然后交给 CLIP 做分类。项目中不是只给 CLIP 一个英雄名字而是为每个英雄构造多种文本提示a photo of Draven champion from Teamfight Tacticsthe League of Legends character DravenDraven from TFT gamehero portrait of Draven这种设计比单纯写一个 Draven 更稳因为 CLIP 比较的是图像和文本描述之间的语义相似度多提示模板可以提高匹配鲁棒性。同时英雄列表会优先从 tft_champion_db.json 中读取而不是完全写死。这一点延续了前面项目的数据驱动思路赛季数据更新以后识别候选集合也可以跟着更新。七、这次迁移不是推翻旧方案而是重新划分职责我觉得这次升级最关键的技术理解不是“YOLO 比 OpenCV 高级”而是识别系统的职责重新划分了。旧方案更像是OpenCV 同时负责定位、过滤、识别、部分后处理新方案开始变成YOLO负责目标定位CLIP负责身份识别OpenCV继续负责星级、装备等局部规则Converter负责羁绊与阵容摘要RAG Agent负责策略分析这样做的好处是每个模块的边界更清楚。例如星级检测依然适合用 OpenCV因为星星颜色和位置比较固定装备识别后续可以继续模板匹配也可以训练单独的装备检测模型英雄位置检测则更适合交给 YOLO。这不是把传统视觉方法全部丢掉而是把它们放到更合适的位置上。八、当前阶段的技术进度目前项目已经完成了 YOLOCLIP 引擎的基础骨架新增 tft_yolo_clip.py支持 YOLO 检测英雄框支持 CLIP 对裁剪头像做零样本识别支持 yolo_clip、yolo_only、clip_only 三种模式保留星级检测逻辑预留装备识别扩展入口提供训练配置生成与命令行入口。运行方式示例python tft_yolo_clip.py screenshot.png --mode yolo_clip --debug如果只想看 YOLO 框检测结果可以使用python tft_yolo_clip.py screenshot.png --detect-only九、总结从 OpenCV 模板匹配迁移到 YOLO并不是简单换一个库也不是把代码改成深度学习版本。这次变化的核心是项目对截图识别问题的理解变了。旧方案证明了整条链路可以跑通资源构建、模板加载、英雄识别、装备识别、截图分流、阵容分析都已经形成闭环。新方案则开始解决旧方案的上限问题减少手工视觉规则提高对复杂截图的适应能力并为后续真实游戏截图识别打基础。当前项目正处在一个比较关键的阶段OpenCV 方案仍然是稳定 fallbackYOLOCLIP 则是下一代识别引擎的雏形。