1. 多分类任务里CrossEntropyLoss 到底在算什么如果你正在用 PyTorch 做图像分类、文本意图识别或者任何“N 选一”的任务大概率绕不开nn.CrossEntropyLoss。它是什么一句话把模型输出的原始分数logits和真实类别标签做对比算出一个差距值训练的目标就是让这个值越来越小。它适合谁适合所有刚接触多分类、被 loss 不下降折磨过、或者想搞清楚weight、ignore_index、reduction这几个参数到底改了什么的同学。很多人第一次用会踩一个坑以为要自己先softmax再送进损失函数。其实 PyTorch 的CrossEntropyLoss内部已经把log_softmax和NLLLoss合并了你直接喂 logits 就行。这个设计不只是省事更重要的是数值稳定——分开算容易在指数运算时溢出合并后框架用 log-sum-exp 技巧规避了这个问题。从数学上看单个样本的损失就是-log(模型对正确类别的预测概率)。假设三分类真实标签是“鸟”索引 2模型给的概率是[0.1, 0.2, 0.7]那损失就是-log(0.7) ≈ 0.357。如果模型更自信地给[0.05, 0.05, 0.9]损失降到-log(0.9) ≈ 0.105。反过来如果模型把“狗”当成正确答案[0.1, 0.7, 0.2]损失就飙到-log(0.2) ≈ 1.609。所以它本质上是一个“惩罚错误信心”的裁判。但实际训练里光知道公式不够。类别不均衡时小类样本的 loss 会被大类淹没有些样本标签是填充的-100或者自定义的忽略值不该参与计算还有reduction选错导致梯度尺度不对。这些问题不解决loss 曲线就会像心电图一样乱跳或者干脆躺平不动。下面我会先讲清楚 TaoToken 在整条链路里的位置再给出一份可以直接复制的配置和验证脚本。2. 前置准备用 TaoToken 统一管理模型调用通道在写训练脚本之前先解决一个工程问题你的代码里可能会调用多个模型服务——比如用大模型做数据增强、用 embedding 模型做特征、或者用 coding 助手生成训练代码。如果每个服务都单独配一套 Key 和地址维护起来很痛苦。TaoToken 的思路是提供一个统一的 API 通道你只需要在配置文件里写一份settings.json就能让不同工具走同一个入口。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 基础地址是 https://taotoken.net/api 注意这个地址后面不加 UTM 参数直接用于代码里的base_url。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制出来保存好。这个 Key 就是后面settings.json里的核心凭证。如果你还没决定用哪个模型做辅助任务可以先在模型对话页面试一下效果确认响应正常再写进配置。注意不要把 Key 硬编码在训练脚本里也不要把settings.json提交到公开仓库。建议用环境变量或者本地私有配置文件。对于长期做编码和 Agent 任务的同学Coding Plan 提供了更稳定的额度方案适合需要反复调用模型生成代码、调试脚本的场景。接入文档里有完整的参数说明和示例遇到报错可以先查文档。3. 可复制配置CrossEntropyLoss 参数与 settings.json 骨架先看损失函数本身的配置。下面这段代码定义了一个带类别权重和忽略索引的CrossEntropyLoss适用于类别不均衡且存在填充标签的多分类任务。import torch import torch.nn as nn # 假设 5 分类类别 0 样本很少给它更高权重 class_weights torch.tensor([2.0, 1.0, 1.0, 1.0, 1.0]) criterion nn.CrossEntropyLoss( weightclass_weights, # 每个类别的缩放系数缓解不均衡 ignore_index-100, # 标签为 -100 的样本不参与 loss 计算 reductionmean # 对 batch 内所有有效样本求平均 )三个参数逐个拆weight接收一个长度为num_classes的张量。它会在计算每个样本 loss 时乘以对应类别的权重。比如类别 0 权重是 2.0那类别 0 的样本 loss 会被放大两倍梯度也会相应变大模型会更关注这个类。注意权重需要和类别索引对齐顺序错了会起反效果。ignore_index默认是-100。在 NLP 的 padding 场景或者分割任务里无效位置的标签通常设成这个值损失函数会自动跳过它们。如果你自定义了忽略值比如-1就要显式传进去。reduction有三个选项none返回每个样本的 loss形状和 batch 一致sum把所有样本 loss 加起来mean取平均。大多数训练用mean但如果你要自己做样本级加权或者梯度累积可能会用none再手动处理。接下来是 TaoToken 的settings.json骨架。这个文件可以放在项目根目录训练脚本读取它来初始化模型客户端。{ taotoken: { base_url: https://taotoken.net/api, api_key: 你的_API_KEY, default_model: gpt-4o-mini, timeout: 30 }, training: { batch_size: 32, learning_rate: 1e-3, num_epochs: 10, num_classes: 5 } }读取配置的代码可以这样写import json with open(settings.json, r, encodingutf-8) as f: config json.load(f) base_url config[taotoken][base_url] api_key config[taotoken][api_key] num_classes config[training][num_classes]这样你的训练脚本和模型调用就解耦了。换 Key 或者换模型只需要改 JSON不用动 Python 代码。4. 验证请求一次前向 反向确认 loss 与梯度正常回传配置写好了怎么确认CrossEntropyLoss真的在工作最直接的办法是构造一个极小的张量跑一次前向和反向看 loss 数值和梯度是否符合预期。import torch import torch.nn as nn torch.manual_seed(42) # 模拟 batch45 分类的 logits logits torch.randn(4, 5, requires_gradTrue) # 真实标签其中最后一个样本设为 ignore_index targets torch.tensor([0, 2, 4, -100]) criterion nn.CrossEntropyLoss(ignore_index-100, reductionmean) loss criterion(logits, targets) print(floss {loss.item():.4f}) loss.backward() print(flogits.grad shape {logits.grad.shape}) print(flogits.grad[0] {logits.grad[0]})运行后你会看到类似输出loss 1.8321 logits.grad shape torch.Size([4, 5]) logits.grad[0] tensor([ 0.1234, -0.0456, ...])关键检查点有三个。第一loss 是一个标量不是 NaN 也不是 Inf。如果出现 NaN通常是 logits 里有极端值或者权重设置不合理。第二logits.grad的形状和logits一致说明梯度成功回传到了输入。第三被忽略的样本索引 3对应的梯度应该全为 0因为ignore_index把它排除了。如果你想进一步确认weight的效果可以把权重改成[10.0, 1.0, 1.0, 1.0, 1.0]重新跑一次观察类别 0 的梯度是否明显变大。这个对比能帮你直观理解权重的作用。在真实训练循环里验证动作可以嵌入到第一个 epoch 的前几个 stepfor step, (inputs, targets) in enumerate(dataloader): outputs model(inputs) loss criterion(outputs, targets) if step 0: print(ffirst step loss: {loss.item():.4f}) assert not torch.isnan(loss), loss is NaN! optimizer.zero_grad() loss.backward() optimizer.step()如果第一个 step 的 loss 在log(num_classes)附近比如 5 分类约 1.609说明初始化正常。如果远大于这个值可能是 logits 尺度太大或者标签对不上。5. 本篇常见错排查loss 不下降、类别不均衡、维度不匹配5.1 loss 完全不下降一直卡在同一个值最常见的原因是标签类型不对。CrossEntropyLoss要求 target 是LongTensor形状是(batch,)每个值在[0, num_classes-1]范围内。如果你传了 one-hot 编码或者 float 类型框架可能不报错但计算结果是错的。检查方法print(targets.dtype) # 应该是 torch.int64 print(targets.shape) # 应该是 torch.Size([batch_size]) print(targets.min(), targets.max()) # 应该在 [0, num_classes-1]另一个原因是学习率太大导致 loss 震荡后卡住。可以先把学习率降到1e-4试试。5.2 类别不均衡导致小类完全学不到如果某个类别的样本数只有其他类的十分之一模型会倾向于全部预测成大类因为这样 loss 也能降得比较低。这时候weight参数就派上用场了。计算权重的常用方法是取类别频率的倒数from collections import Counter label_counts Counter(train_labels) total sum(label_counts.values()) weights [total / (num_classes * label_counts[i]) for i in range(num_classes)] class_weights torch.tensor(weights, dtypetorch.float32)把class_weights传给CrossEntropyLoss小类的 loss 会被放大梯度更新更积极。但权重也不要设得太极端否则训练容易不稳定。可以先从sqrt缩放开始试。5.3 维度不匹配报错典型报错信息是Expected target size [32, 5], got [32]或者Target 5 is out of bounds。前者通常是因为你误用了BCEWithLogitsLoss的 target 格式后者是标签值超出了类别数。检查num_classes和标签最大值是否一致。如果数据集标签从 1 开始编号记得减 1 映射到 0 起始。5.4 验证集 loss 比训练集高很多这不一定是 CrossEntropyLoss 的问题但和它相关。如果训练 loss 持续下降而验证 loss 上升说明过拟合了。可以加 dropout、weight decay或者用reductionmean配合早停。另外确认验证时模型处于eval()模式且没有误传ignore_index导致有效样本被跳过。5.5 梯度为 None 或全零如果loss.backward()之后logits.grad是 None检查logits是否设置了requires_gradTrue以及计算图是否被意外断开。如果梯度全零可能是weight里对应类别权重为 0或者所有样本都被ignore_index忽略了。6. 把 Key 和损失函数串起来下一步做什么到这里你已经有了可复制的CrossEntropyLoss配置、TaoToken 的settings.json骨架以及一次完整的前向反向验证。接下来可以把这套配置放进真实的训练脚本里先跑一个 epoch 观察 loss 曲线。如果 loss 正常下降但速度慢优先调学习率和权重如果 loss 震荡检查 batch size 和标签质量。需要创建新的 API Key 或者查看额度直接进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档里有完整的参数说明和错误码对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你想让模型帮你生成数据增强代码或者调试训练脚本模型对话页面可以直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实操建议每次改完weight或ignore_index都重新跑一遍第 4 节的小张量验证确认 loss 和梯度符合预期再上完整训练。这个习惯能帮你省下大量排查时间。