## 当CV模型-图像分类2.0进行模型训练时，模型训练报错[rank6]: UnboundLocalError: local variable 'avg' referenced before assignment时


## 一、先搞懂报错核心原因


这么说吧，`UnboundLocalError`的本质不是 CV 模型本身的问题，而是代码里的 “逻辑覆盖不全”：

你代码中后续要使用`avg`变量（比如打印平均损失、返回平均准确率），但`avg`只在**有数据的分支**里赋值（比如训练循环执行时）；当 rank6 节点的训练批次为空（比如分布式数据分片时，该 rank 分到的样本数为 0），赋值`avg`的逻辑没触发，后续引用`avg`就会直接报错。

在图像分类 2.0 模型训练中，这个问题最常出现在两个场景：


1. **训练循环无数据**：rank6 的 dataloader 为空（总样本数不能被 rank 数整除，最后一个 rank 没样本），计算平均损失 / 准确率的循环没执行，`avg`未赋值；

2. **条件分支覆盖不全**：`avg`仅在`if`分支（比如 “有预测结果”）里赋值，`else`分支没赋值，却在后续直接引用。


## 二、分步解决：先定位，再修复


### 步骤 1：定位报错的具体代码行


先看报错堆栈（关键！），比如报错日志会显示：


 


```
[rank6]: UnboundLocalError: local variable 'avg' referenced before assignment
File "train.py", line 289, in train_one_epoch
    logger.info(f"Rank {rank} epoch {epoch} avg acc: {avg_acc}")
```


 


这就明确了：`train_one_epoch`函数的 289 行引用了`avg_acc`，但这个变量可能没赋值。

### 步骤 2：分析图像分类训练中最典型的错误逻辑


咱们不妨看看图像分类训练里，计算平均指标的常见错误代码（这也是你大概率踩坑的地方）：


 


```
def train_one_epoch(model, dataloader, criterion, optimizer, rank):
    losses = []
    correct = 0
    total = 0
    # 训练循环：若dataloader为空，这个循环完全不执行
    for images, labels in dataloader:
        # 前向传播（图像分类核心逻辑）
        outputs = model(images)
        loss = criterion(outputs, labels)
        losses.append(loss.item())
        
        # 计算准确率
        _, preds = torch.max(outputs, 1)
        correct += (preds == labels).sum().item()
        total += labels.size(0)
        
        # 反向传播
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
    
    # 问题1：若循环没执行，sum(losses)/len(losses)不会执行，avg_loss未赋值
    avg_loss = sum(losses) / len(losses)
    # 问题2：若total=0，correct/total会除以0，且avg_acc未赋值
    avg_acc = correct / total
    
    # 引用未赋值的avg_loss/avg_acc，rank6无数据时直接报错
    print(f"Rank {rank} avg loss: {avg_loss}, avg acc: {avg_acc}")
    return avg_loss, avg_acc
```


 


### 步骤 3：修复代码（核心！确保 avg 在所有场景下有赋值）


核心修复思路：**初始化 avg 为默认值 + 加条件判断避免空数据 / 除以 0**，修复后的代码如下（可直接替换）：


 


```
def train_one_epoch(model, dataloader, criterion, optimizer, rank):
    losses = []
    correct = 0
    total = 0
    # 修复1：初始化avg变量，避免未赋值（关键！）
    avg_loss = 0.0
    avg_acc = 0.0
    
    for images, labels in dataloader:
        outputs = model(images)
        loss = criterion(outputs, labels)
        losses.append(loss.item())
        
        _, preds = torch.max(outputs, 1)
        correct += (preds == labels).sum().item()
        total += labels.size(0)
        
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
    
    # 修复2：加条件判断，仅当有数据时计算平均值
    if len(losses) > 0:
        avg_loss = sum(losses) / len(losses)
    else:
        # 空数据时记录日志，方便排查
        print(f"[Rank {rank}] Warning: 无训练数据，avg_loss设为0.0")
    
    # 修复3：避免除以0，同时处理空数据
    if total > 0:
        avg_acc = correct / total
    else:
        print(f"[Rank {rank}] Warning: 无有效样本，avg_acc设为0.0")
    
    # 此时avg_loss/avg_acc必有值，不会报错
    print(f"Rank {rank} avg loss: {avg_loss}, avg acc: {avg_acc}")
    return avg_loss, avg_acc
```


 


### 步骤 4：分布式训练额外处理（针对 rank6 无数据的根因）


rank6 节点无数据的本质是**分布式采样器分片不均**，可以在构建 dataloader 时补充配置，从根源避免空数据：


 


```
from torch.utils.data.distributed import DistributedSampler

# 构建分布式采样器（图像分类训练的标准配置）
train_sampler = DistributedSampler(
    train_dataset,  # 你的图像分类训练数据集
    num_replicas=world_size,  # rank总数（比如8）
    rank=rank,  # 当前rank
    drop_last=True  # 核心！丢弃最后一个不完整批次，避免某rank无数据
)

# 构建dataloader
train_dataloader = torch.utils.data.DataLoader(
    train_dataset,
    batch_size=batch_size,  # 批次大小
    sampler=train_sampler,  # 使用分布式采样器
    num_workers=4,  # 数据加载线程
    pin_memory=True  # 加速GPU数据传输
)
```


 


- `drop_last=True`：会丢弃总样本数不能被`num_replicas×batch_size`整除的最后一个批次，确保每个 rank 的 dataloader 都有数据；

- 若不想丢弃样本：可以给数据集补充 “dummy 样本”（比如复制最后几个样本），让总样本数能被整除。


## 三、额外避坑点（CV 图像分类 2.0 训练专属）


1. **验证集 / 测试集同样要处理**：不仅训练循环，验证 / 测试阶段计算 avg 指标时，也要按上述方式初始化 + 条件判断，避免 eval 阶段报同样的错；

2. **分布式指标同步**：若需要跨 rank 同步 avg 指标（比如求所有 rank 的平均损失），空数据的 rank 用 0 值填充，再用`torch.distributed.all_reduce`同步；

3. **日志打印要明确**：给空数据的 rank 加日志（比如`[Rank 6] 无训练数据`），方便后续排查数据分片问题。


## 总结一下下


1. **核心问题**：`avg`变量仅在有数据的分支赋值，rank6 节点无数据导致未赋值，触发`UnboundLocalError`；

2. **修复关键**：先初始化`avg`为默认值（如 0.0），再通过条件判断避免空列表 / 除以 0；

3. **分布式兜底**：设置`DistributedSampler(drop_last=True)`，避免某 rank 的 dataloader 为空。

这么说吧，UnboundLocalError的本质不是 CV 模型本身的问题，而是代码里的 “逻辑覆盖不全”：

记一次图像分类排错

人工智能

算法

CV模型训练报错UnboundLocalError: local variable 'avg' referenced before assignment，核心原因是代码逻辑覆盖不全，当rank6节点无数据时avg变量未赋值。解决方法：初始化avg为默认值，增加条件判断避免空数据/除以0，并设置DistributedSampler(drop_last=True)确保每个rank都有数据。

数据分片

V模型

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

CV模型训练报错UnboundLocalError: local variable 'avg' referenced before assignment，核心原因是代码逻辑覆盖不全，当rank6节点无数据时avg变量未赋值。解决方法：初始化avg为默认值，增加条件判断避免空数据/除以0，并设置DistributedSa...

记一次图像分类排错-腾讯云开发者社区-腾讯云

记一次图像分类排错

记一次图像分类排错

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐