YOLOv5中文标签实战从数据标注到部署避坑指南在目标检测领域YOLOv5因其出色的性能和易用性广受欢迎。然而当我们需要在检测结果中显示中文标签时往往会遇到各种坑——从字体渲染问题到Pillow库版本冲突。本文将带你完整走通中文标签从训练到部署的全流程特别是针对常见的FreeTypeFont object has no attribute getsize错误提供不降级Pillow的终极解决方案。1. 中文标签数据准备与环境配置中文标签训练的第一步是正确处理数据集和配置文件。与英文标签不同中文需要特别注意编码问题和字体支持。数据集yaml文件配置要点# 中文标签示例 (data/custom.yaml) train: ../datasets/custom/images/train val: ../datasets/custom/images/val nc: 3 # 类别数量 names: [行人, 汽车, 自行车] # 必须使用中文关键注意事项文件编码必须为UTF-8或GBK需在代码中对应处理避免使用生僻字或特殊符号标签名称应当简洁明确环境准备清单Python 3.8PyTorch ≥1.7Pillow ≥9.0 (无需降级)中文字体文件推荐使用思源黑体或微软雅黑提示将字体文件(.ttf)放置在项目根目录下便于代码中直接引用绝对路径2. 核心代码修改与中文支持实现中文标签显示需要修改YOLOv5的多个核心文件以下是关键修改点2.1 plots.py 修改方案在utils/plots.py中添加以下代码段# 添加在文件开头 import matplotlib.pyplot as plt plt.rcParams[font.sans-serif] [SimHei] # 设置中文字体 plt.rcParams[axes.unicode_minus] False # 解决负号显示问题修改Annotator类的字体初始化部分# 修改前 font ImageFont.load_default() # 修改后 font ImageFont.truetype(msyh.ttc, size15) # 使用微软雅黑字体2.2 解决Pillow版本冲突问题当遇到FreeTypeFont object has no attribute getsize错误时无需降级Pillow可采用以下替代方案# 在plots.py中找到使用getsize的地方替换为以下代码 try: text_width, text_height font.getsize(text) # 旧版Pillow except AttributeError: left, top, right, bottom font.getbbox(text) # 新版Pillow text_width right - left text_height bottom - top这种方法兼容Pillow 9.0版本同时不影响训练流程。3. 训练与验证流程优化3.1 训练脚本调整修改train.py以正确处理中文标签# 在数据加载部分确保使用正确编码 with open(yaml_file, r, encodinggbk) as f: data yaml.safe_load(f)训练参数建议参数推荐值说明--batch16根据显存调整--epochs100中文任务可能需要更多epoch--img-size640保持默认--datadata/custom.yaml指向你的中文配置文件3.2 验证集指标可视化修改metrics.py确保中文标签正确显示# 添加在文件开头 import matplotlib matplotlib.rc(font, familySimHei) # 设置统计图表的中文字体4. 部署与检测实战4.1 检测脚本修改在detect.py中需要做以下调整# 修改权重加载路径 parser.add_argument(--weights, nargs, typestr, defaultruns/train/exp/weights/best.pt, helpmodel.pt path(s))常见检测问题排查中文显示为方框确认字体文件路径正确检查系统是否安装对应字体标签编码错误确保所有文件使用统一编码(GBK或UTF-8)在Python文件开头添加# -*- coding: utf-8 -*-性能下降中文标签不会影响模型精度检查是否误修改了模型结构4.2 跨平台部署建议在不同系统上部署时注意Linux系统可能需要额外安装中文字体sudo apt install fonts-wqy-zenhei # 文泉驿正黑Docker部署时确保容器内包含中文字体文件在实际项目中我们发现将字体文件直接打包到Docker镜像是最可靠的做法。创建一个包含微软雅黑字体的Dockerfile示例FROM pytorch/pytorch:1.9.0-cuda11.1-cudnn8-runtime RUN apt-get update apt-get install -y fonts-wqy-zenhei COPY msyh.ttc /usr/share/fonts/ WORKDIR /app COPY . . CMD [python, detect.py]这种方案既解决了字体问题又避免了Pillow版本冲突在实际生产环境中表现稳定。