企业官网建设流程全解析

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.8+
• PyTorch ≥1.7
• Pillow ≥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", size=15) # 使用微软雅黑字体

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', encoding='gbk') as f: data = yaml.safe_load(f)

训练参数建议：

3.2 验证集指标可视化

修改metrics.py确保中文标签正确显示：

# 添加在文件开头 import matplotlib matplotlib.rc('font', family='SimHei') # 设置统计图表的中文字体

4. 部署与检测实战

4.1 检测脚本修改

在detect.py中需要做以下调整：

# 修改权重加载路径 parser.add_argument('--weights', nargs='+', type=str, default='runs/train/exp/weights/best.pt', help='model.pt path(s)')

常见检测问题排查：

1. 中文显示为方框：

   • 确认字体文件路径正确
   • 检查系统是否安装对应字体

2. 标签编码错误：

   • 确保所有文件使用统一编码(GBK或UTF-8)
   • 在Python文件开头添加# -*- coding: utf-8 -*-

3. 性能下降：

   • 中文标签不会影响模型精度
   • 检查是否误修改了模型结构

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版本冲突，在实际生产环境中表现稳定。