当前位置：首页 > news >正文

别再降级Pillow了！YOLOv5 7.0中文标签训练与显示完整避坑指南（附字体配置）

news 2026/6/3 10:28:07

YOLOv5中文标签实战：从训练到显示的完整解决方案

在计算机视觉领域，YOLOv5因其高效和易用性成为目标检测的热门选择。然而，当开发者尝试使用中文标签进行训练和检测时，往往会遇到一系列棘手问题。本文将深入剖析这些问题的根源，并提供一套完整的解决方案，帮助您在不破坏系统兼容性的前提下实现中文标签的完美显示。

1. 中文标签训练的基础配置

实现中文标签训练的第一步是确保数据标注文件的正确配置。与英文标签不同，中文标签需要特别注意文件编码和字体支持问题。

关键配置文件修改：

YAML文件调整
确保data.yaml中的类别名称直接使用中文，例如：
```
names: ['行人', '汽车', '自行车', '摩托车']
```

编码问题处理
修改utils/general.py中的yaml_load函数，指定正确的编码方式：

def yaml_load(file): with open(file, errors='ignore', encoding='gbk') as f: return yaml.safe_load(f)

训练脚本适配
在train.py中，确保读取YAML文件时不会因中文导致解析错误：
```
data_dict = yaml_load(data)
```

提示：使用GBK编码而非UTF-8是因为部分系统环境下，UTF-8可能无法正确处理中文字符，而GBK具有更好的兼容性。

2. 绘图模块的中文支持改造

YOLOv5的检测结果显示依赖于utils/plots.py文件中的绘图功能。要实现中文标签显示，需要进行以下关键修改：

字体系统配置：

在plots.py文件开头添加Matplotlib的中文显示配置：

import matplotlib.pyplot as plt plt.rcParams['font.sans-serif'] = ['SimHei'] # 设置中文字体 plt.rcParams['axes.unicode_minus'] = False # 解决负号显示问题

Annotator类改造：

字体路径指定
修改Annotator类中的字体设置，使用绝对路径指向中文字体文件：
```
font = ImageFont.truetype('/path/to/your/chinese_font.ttf', size=font_size)
```
Pillow模式切换
将pil参数默认值改为True，确保使用Pillow进行文字渲染：
```
def __init__(self, im, line_width=None, font_size=None, pil=True):
```

常见问题解决方案：

问题现象	原因分析	解决方案
中文显示为方框	系统缺少中文字体	安装SimHei字体或指定有效字体路径
标签位置偏移	字体度量计算错误	使用正确的`getsize`替代方法
训练时正常但检测时报错	Pillow版本兼容性问题	采用下文介绍的getsize替代方案

3. 解决Pillow高版本的getsize属性问题

当升级到Pillow 9.0+版本后，原有的getsize方法已被弃用，直接降级Pillow会导致其他功能异常。以下是安全可靠的解决方案：

getsize替代方案：

在plots.py中找到使用getsize的位置，替换为新的API调用方式：

# 旧代码（已废弃） text_width, text_height = font.getsize(text) # 新代码（兼容各版本） left, top, right, bottom = font.getbbox(text) text_width = right - left text_height = bottom - top

版本兼容性处理：

建议添加版本判断逻辑，使代码适应不同Pillow版本：

try: # 尝试新API bbox = font.getbbox(text) text_width = bbox[2] - bbox[0] text_height = bbox[3] - bbox[1] except AttributeError: # 回退到旧API text_width, text_height = font.getsize(text)

注意：绝对不要随意降级Pillow到10.0以下版本，这会导致YOLOv5其他功能（如数据增强）出现兼容性问题。

4. 检测阶段的中文标签显示优化

完成训练后，在检测阶段需要确保权重文件和配置的正确加载，以实现中文标签的完美显示。

检测脚本关键修改点：

权重文件指定
修改detect.py中的parse_opt函数，确保加载正确的中文标签训练结果：
```
parser.add_argument('--weights', nargs='+', type=str, default='runs/train/exp/weights/best.pt')
```

标签显示验证
在运行检测前，可以添加简单的验证代码检查中文显示是否正常：

test_text = "中文测试" test_font = ImageFont.truetype("SimHei.ttf", 20) print(test_font.getbbox(test_text)) # 验证字体度量计算

性能优化技巧：

将字体文件预加载到内存，避免重复IO操作
对常用标签文本进行缓存，减少字体度量计算开销
在多GPU环境下，确保每个进程都能正确访问字体资源

5. 实战中的常见问题与调试技巧

即使按照上述步骤配置，在实际部署中仍可能遇到各种环境相关问题。以下是几个典型问题的解决方案：

字体文件找不到的解决方法：

将字体文件放在项目根目录下
使用绝对路径指定字体位置
在Docker环境中，确保字体文件被正确挂载

跨平台兼容性处理：

不同操作系统下字体处理方式略有差异，建议添加平台判断：

import platform if platform.system() == 'Linux': font_path = '/usr/share/fonts/truetype/simhei.ttf' elif platform.system() == 'Windows': font_path = 'C:/Windows/Fonts/simhei.ttf' else: font_path = 'SimHei.ttf'

训练与检测的一致性检查：