简介这是一份面向计算机视觉初学者与目标检测开发者的扑克牌识别数据集可用于训练模型同时识别牌面数字与花色适用于棋牌类应用、智能发牌、图像分类教学等场景。资源包共1003个文件包含501张jpg原始图像、501个txt标注文件以及1个yaml配置文件压缩包约11.82MB标注采用YOLO v11格式可直接接入主流检测框架进行训练与验证。据描述该数据集在测试中正确识别率可达99.3%覆盖多种牌面与花色组合样本命名清晰便于按类别划分训练集与验证集。目前已有762人学习下载适合需要快速搭建扑克牌检测基线、验证模型效果或进行数据增强实验的读者参考使用。1. 扑克牌识别数据集501 张原图与 99.3% 准确率背后的落地账做棋牌类视觉项目的人多半遇到过同一个尴尬模型在实验室里跑得挺欢一换到真实牌桌就翻车——反光、遮挡、牌面角度偏一点数字和花色就认错。这套扑克牌识别数据集就是冲着这个痛点来的501 张原始图按 YOLO v11 格式标注官方给出的正确识别率能到 99.3%。它解决的不是能不能检测到牌这种初级问题而是数字和花色能不能同时稳定识别这个真正卡住落地的环节。适合谁用做棋牌辅助工具、发牌机视觉、牌局记录仪、教学演示的开发者以及想拿一个干净的小规模多类别数据集练手 YOLO v11 训练流程的人。501 张不算多但胜在标注质量集中、类别定义清晰属于那种拿来就能跑通、跑通就能看到效果的资源而不是动辄几万张却要花一周清洗的烫手山芋。2. YOLO v11 标注格式拆解从文件名到标签的对应关系2.1 为什么这套数据用 YOLO v11 而不是 COCO先说选型理由。YOLO 系列的标注格式是一图一 txt每行class_id x_center y_center width height坐标全部归一化到 0~1。这套扑克牌数据走的就是这个格式好处很直接Ultralytics 的yolo命令直接吃不用写转换脚本训练配置里data.yaml指一下路径就能开跑。COCO 的 JSON 虽然信息更全带分割、关键点但对纯检测任务来说是过度设计解析还得引 pycocotools多一层依赖多一层坑。从项目正文给的文件名能看出标注流程的痕迹。像test_find_changes_by_template_no_match_png_jpg.rf.79a34afbf53dd8d6d2ed906317581bf1.jpg这种前缀test_find_changes_by_template_no_match说明它来自某个模板匹配的测试环节.rf.后面那串哈希是标注工具常见的是 Roboflow 导出自动加的去重标识。player_skdnsauehrfusefh_png_jpg.rf.a14a973a54a3b0b0402c378e1877cbf6.jpg里的player_前缀则指向牌局中的玩家视角图。这些命名不是随便起的它反映了数据采集时的场景分组——模板匹配测试图和玩家视角图混在一起训练时如果按前缀做分层抽样能避免某一类场景过拟合。2.2 目录结构与 data.yaml 的写法拿到数据集后标准目录长这样poker_dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── labels/ │ ├── train/ │ ├── val/ │ └── test/ └── data.yamldata.yaml是训练的入口配置写法如下# data.yaml path: ./poker_dataset # 数据集根目录 train: images/train # 训练集图片路径相对 path val: images/val # 验证集图片路径 test: images/test # 测试集图片路径 # 类别数数字 13 类 花色 4 类具体以实际标注为准 nc: 17 names: 0: ace 1: two 2: three 3: four 4: five 5: six 6: seven 7: eight 8: nine 9: ten 10: jack 11: queen 12: king 13: spade 14: heart 15: club 16: diamond这里有个关键点nc和names必须和标注文件里的class_id严格对应。如果标注时把数字和花色合并成一个类别比如红桃 A算一类那nc就是 52如果拆成数字和花色两个独立维度就是 17 类。从可识别数字和花色这个描述看更可能是拆开标注的因为合并成 52 类会让每类样本数骤降到个位数501 张图根本撑不住。拆成 17 类后每类平均有 29 张图虽然还是偏少但配合数据增强能凑合。提示改data.yaml前先用grep -r class labels/train/ | head看一眼实际标注的类别 ID 分布别照着模板硬填。2.3 标签文件校验三行脚本查归一化越界标注数据最常见的暗病是坐标越界——x_center或width超过 1训练时 YOLO 会直接报错或者静默丢弃。跑训练前花十秒校验一遍# check_labels.py import os import glob label_dir ./poker_dataset/labels/train bad_files [] for txt_path in glob.glob(os.path.join(label_dir, *.txt)): with open(txt_path, r) as f: for line_no, line in enumerate(f, 1): parts line.strip().split() if len(parts) ! 5: bad_files.append((txt_path, line_no, 字段数不对)) continue cls_id, x, y, w, h parts # 归一化坐标必须在 0~1 之间 for name, val in [(x, x), (y, y), (w, w), (h, h)]: v float(val) if v 0 or v 1: bad_files.append((txt_path, line_no, f{name}{v} 越界)) if bad_files: for bf in bad_files[:20]: print(bf) print(f共 {len(bad_files)} 处问题) else: print(标签校验通过)逻辑说明逐行读每个 txt先检查字段数是不是 5类别 4 个坐标再检查四个坐标值是否落在 0~1。参数上label_dir换成你的实际路径即可。如果输出一堆越界记录说明标注工具导出时坐标系搞错了比如用了像素坐标没归一化这种数据直接训练会浪费 GPU 时间。3. 用 Ultralytics 跑通训练从环境到 99.3% 的复现路径3.1 环境安装与版本对齐YOLO v11 在 Ultralytics 8.3.x 之后的版本里支持装的时候别用太老的包# 建议 Python 3.9 pip install ultralytics8.3.0 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121ultralytics这个包把训练、验证、导出全包了不用单独装 darknet 那套。CUDA 版本按自己显卡驱动选cu121对应 CUDA 12.130 系和 40 系卡都稳。装完跑一句yolo checks确认环境它会打印出 PyTorch 版本、CUDA 可用性、以及当前 ultralytics 版本。3.2 训练命令与关键参数一条命令开跑yolo detect train \ data./poker_dataset/data.yaml \ modelyolo11n.pt \ epochs150 \ imgsz640 \ batch16 \ lr00.01 \ patience30 \ projectruns/poker \ nameexp1逐个说参数。modelyolo11n.pt选的是 nano 版501 张图用大模型纯属浪费n 版参数量小、收敛快适合小数据集。epochs150是上限配合patience30做早停——30 轮验证集指标不涨就停避免过拟合。imgsz640是输入分辨率扑克牌在图中占比通常不小640 够用如果牌面很小比如整张桌子远景可以提到 1280但显存翻倍。batch16是 8G 显存的安全值12G 以上可以拉到 32。lr00.01是初始学习率小数据集别设太大否则前期震荡。训练过程中重点看mAP50和mAP50-95两个指标。99.3% 这个数字大概率指的是mAP50IoU 阈值 0.5 时的平均精度因为扑克牌检测框比较规整IoU 容易做高。如果mAP50到 0.99 但mAP50-95只有 0.7 左右说明框的位置精度还有提升空间可以试试加mosaic0关掉马赛克增强让模型更关注单张图的细节。3.3 数据增强配置小数据集的救命稻草501 张图直接训过拟合几乎是必然。Ultralytics 默认开了 mosaic、mixup、HSV 增强但默认参数不一定适合扑克牌。建议在命令行里显式调几个yolo detect train \ data./poker_dataset/data.yaml \ modelyolo11n.pt \ epochs150 \ imgsz640 \ batch16 \ hsv_h0.015 \ hsv_s0.7 \ hsv_v0.4 \ degrees15 \ translate0.1 \ scale0.5 \ fliplr0.5 \ mosaic1.0 \ mixup0.1hsv_h0.015是色调扰动幅度扑克牌红黑分明色调别动太大0.015 足够。hsv_s0.7和hsv_v0.4分别调饱和度和亮度模拟不同光照。degrees15允许旋转 15 度牌桌视角偏一点能扛住。fliplr0.5水平翻转概率注意扑克牌翻转后数字会镜像但花色对称性不同红桃翻转还是红桃黑桃翻转还是黑桃所以翻转对花色识别无害对数字识别可能引入噪声——如果发现数字类别混淆严重把fliplr降到 0.2。mosaic1.0是四图拼接小数据集必备但训练后期建议关掉mosaic0让模型适应单图分布。3.4 验证与推理确认 99.3% 是不是真的训练完先跑验证yolo detect val \ modelruns/poker/exp1/weights/best.pt \ data./poker_dataset/data.yaml \ imgsz640 \ conf0.25 \ iou0.5conf0.25是置信度阈值低于这个的检测框不算数。iou0.5是 NMS 的 IoU 阈值重叠超过 50% 的框会被合并。验证输出会打印每个类别的 precision、recall、mAP重点看数字类和花色类有没有明显短板——如果某个花色比如梅花的 recall 特别低说明该类样本太少得补数据。推理单张图yolo detect predict \ modelruns/poker/exp1/weights/best.pt \ source./test_image.jpg \ conf0.3 \ saveTrue结果图存在runs/detect/predict/下框上会标类别和置信度。拿几张没参与训练的牌桌图试如果数字和花色都能框对那 99.3% 这个数字在你的场景下就站得住。4. 避坑与排查501 张图训练时最容易翻车的五件事4.1 现象训练 loss 不降mAP 一直卡在 0.1 以下原因data.yaml里的nc和实际标注类别数对不上或者names顺序错了。YOLO 不会报错但会把所有类别当同一类学loss 自然降不下去。解决跑一句python -c import glob; idsset(); [ids.update([int(l.split()[0]) for l in open(f)]) for f in glob.glob(labels/train/*.txt)]; print(sorted(ids))打印出实际用到的 class_id 集合和data.yaml的names逐一对齐。多一个少一个都改。4.2 现象验证集 mAP 很高但拿新图推理全是错框原因训练集和验证集来自同一批场景比如都是模板匹配图模型学到了场景特征而不是牌面特征。项目正文里那些test_find_changes_by_template_no_match前缀的图如果全堆在训练集验证集又抽的是同类图指标就是虚的。解决按文件名前缀做分层抽样确保player_前缀的图在训练集和验证集里都有。手动分也行写个脚本按前缀分组再按 8:2 切。4.3 现象花色识别准数字识别差或者反过来原因数字和花色的视觉特征差异大模型容量不够时会出现偏科。nano 版模型对细粒度分类A 和 4 的差异确实吃力。解决换yolo11s.pt或yolo11m.pt试一轮参数量上去了细粒度分类会好。另一个办法是把数字和花色拆成两个检测头分别训但这就得改模型结构了成本高先试换模型。4.4 现象训练到 50 轮左右 mAP 突然掉下去原因学习率没降下来模型在最优解附近震荡。默认余弦退火策略在 150 轮下可能后期才降但早停 patience 设太小的话会在掉下去之前就停了。解决把patience提到 50或者显式加cos_lrTrue让学习率按余弦曲线降。如果已经掉了从best.pt恢复训练yolo detect train resume modelruns/poker/exp1/weights/last.pt。4.5 现象推理时同一张牌被框了两次原因NMS 的iou阈值设太高比如 0.9重叠框没被合并。扑克牌检测框通常比较紧凑两个框重叠超过 0.5 就该合并。解决推理时把iou降到 0.5 甚至 0.45。如果还不行检查是不是标注时同一张牌标了两个框——用校验脚本查labels/里有没有同一张图同一位置出现两行几乎相同的坐标。5. 进阶技巧用 TTA 和类别平衡把 99.3% 再往上顶一顶训练跑通之后如果想把准确率从 99.3% 再往上推有两个不费劲但有效的招。第一个是 TTA测试时增强推理时把图翻转、缩放几次综合多次结果yolo detect predict \ modelruns/poker/exp1/weights/best.pt \ source./test_image.jpg \ augmentTrue \ conf0.3augmentTrue会开 TTA代价是推理速度慢 2~3 倍但 mAP 通常能涨 0.5~1 个点。对离线分析场景比如牌局回放完全值得对实时发牌机就得权衡了。第二个是类别平衡。501 张图里某些牌比如大小王如果标了的话可能只有几张训练时会被淹没。Ultralytics 支持在data.yaml里给每个类别配权重但更简单的做法是过采样——把稀有类别的图复制几份到训练集文件名加_dup后缀避免覆盖。我一般会先跑一遍yolo detect val看每个类别的 recallrecall 低于 0.8 的类别就补图补到该类至少 30 张。还有一个容易被忽略的点验证集和测试集的划分。501 张图如果按 8:1:1 切测试集只有 50 张统计意义太弱。我习惯按 7:1.5:1.5 切测试集留 75 张左右跑出来的 99.3% 才更有说服力。切完之后一定确认三个集合里数字和花色的分布大致均匀别出现测试集里全是红桃这种乌龙。从那以后我每次拿到新数据集第一件事不是急着训而是先跑标签校验脚本、再看类别分布、最后按前缀分层切分——这三步走完再开 GPU能省下大量返工时间。希望这套扑克牌数据集和上面的流程能帮你把棋牌视觉项目的第一公里跑顺。本文还有配套的精品资源点击获取