FAQ

Q1: CUDA版本冲突

报错信息：

ImportError: /root/miniconda3/envs/tzrec/lib/python3.10/site-packages/torch/lib/../../nvidia/cusparse/lib/libcusparse.so.12: undefined symbol: __nvJitLinkAddData_12_1, version libnvJitLink.so.12

原因： 环境里面已经有了不同版本的cuda。

解决方法： 清空环境变量LD_LIBRARY_PATH即可，通过设置LD_LIBRARY_PATH=来使用当前conda环境的cuda。

---

Q2: 缺少libidn

报错信息：

libidn.so.11: cannot open shared object file: No such file or directory

原因： 系统中缺少libidn.so库文件。

解决方法： Centos运行yum install libidn来安装所需的库；Ubuntu可以下载https://tzrec.oss-accelerate.aliyuncs.com/third_party/libidn11_1.33-2.2ubuntu2_amd64.deb，apt-get install ./libidn11_1.33-2.2ubuntu2_amd64.deb来安装。

---

Q3: 未检测到GPU

报错信息：

libnvidia-ml.so.1: cannot open shared object file: No such file or directory

原因： 系统未检测到GPU。

解决方法： 请确保在具备GPU支持的环境中运行该命令。可以通过nvidia-smi命令是否能正常运行来判断是否在GPU环境中。如果是在容器环境中，可以检查容器启动命令中是否包含--gpus all。

---

Q4: 训练命令多卡参数与GPU卡数不匹配

报错信息：

RuntimeError: CUDA error: invalid device ordinal
CUDA kernel errors might be asynchronously reported at some other API call, so the stacktrace below might be incorrect.
For debugging consider passing CUDA_LAUNCH_BLOCKING=1.
Compile with `TORCH_USE_CUDA_DSA` to enable device-side assertions.

原因： 训练使用的是多卡配置，而环境可能只有单卡或无法找到指定的CUDA设备。

解决方法： 请确保训练代码中使用的GPU卡数--nproc-per-node与执行环境中的可用GPU卡数相匹配。

---

Q5: pipeline.config文件未找到

报错信息：

FileNotFoundError: [Errno 2] No such file or directory: 'experiments/multi_tower_din_taobao_local/pipeline.config'

原因： pipeline.config文件未找到，可能是训练任务未正常运行导致。

解决方法： 检查pipeline.config文件是否存在于指定路径。

---

Q6: 离线预测报 RuntimeError: KeyError: batch_size

报错信息：

Trackback of TorchScript, original code (most recent all last):
def forward(self, data : typing_Dict[str,torch.Tensor], device: device = 'cpu') -> typing_Dict[str,torch.Tensor]:
     device_1 = device
     getitem = data['batch_size']
               ~~~~~~~~~~~~~~~~~ <--- HERE
     item = getitem.item(); getitem = None
RuntimeError: KeyError: batch_size

原因： 离线预测不能支持INPUT_TILE模式导出的模型

解决方法： 去掉这个INPUT_TILE环境变量，另外导出个模型

---

Q7: 如何解决FG训练任务错误日志无法在dlc日志中显示的问题

原因： GLOG日志默认存储在/tmp目录下

解决方法： 可以在训练时设置环境变量GLOG_logtostderr=1

---

Q8: 如何解决mc读session失效问题

报错信息：

pyarrow.lib.ArrowInvalid: Expected to read 538970747 metadata bytes, but only read 122

原因： 这是因为链接mc的session过期失效了，目前session过期时间为1天

解决方法： 升级torcheasyrec版本>=0.7.5

---

Q9: SEQUENCE特征的特征组配置问题

报错信息：

in _regroup_keyed_tensors  KeyError: 'YOU SEQUENCE FEATURE NAME'

原因： 将序列特征配置在了group_type为DEEP的特征组里，序列是三维的tensor，普通特征是两维的tensor，无法拼到一起。

解决方法： 将sequence特征放在group_type为SEQUENCE的组里

---

Q10: Dataloader OOM(out-of-memory)

报错信息：

RuntimeError: DataLoader worker (pid 1327) is killed by signal: Killed.

原因： Dataloader OOM(out-of-memory) 导致 dataloader进程被系统kill。

解决方法： 减少data_config中的batch_size或者num_workers

---

Q11: 离线预测写表报schema不对

报错信息：

Write data failed - The data stream you provided was not well-formed or did not validate against schema. WriteRecordBatch failed. Data invalid: ODPS-0010000:InvalidArgument:table: xxx, partitions: [] int64 is not equal to stringODPS-0422224: RequestId: xxx
Tag: TUNNEL Endpoint: http://dt.cn-shanghai-vpc.maxcompute.aliyun-inc.com

原因： 离线预测输出表已存在，并且schema不正确

解决方法： 删除已存在的输出表或修改输出表名

---

Q11: fbgemm的embedding lookup op的EmbeddingBoundsCheck error

报错信息： fbgemm的embedding lookup op报错：

EmbeddingBoundsCheck (VBE false): (at least one) Out of bounds access for batch: 12, table: 2, bag element: 0, idx: 3, num_rows: 3, indices_start: 1815, indices_end: 1816, T: 244, B: 67, b_t: 1955. Setting idx to zero.

原因： 第2个embedding table只有3行embedding（num_rows: 3)，但是传入的id是3（idx: 3），越界了

解决方法： 只通过报错日志很难直接确定第2个embedding table是关联哪一个特征。需设置环境变量LOG_LEVEL=INFO或LOG_LEVEL=DEBUG重新执行训练命令，可以看到训练日志中包含如下内容[TBE=xxx] Contents: ['id_3_emb', 'lookup_2_emb', 'lookup_3_emb', ...，就可以得知lookup_3这个特征的输入值存在问题需要进一步检查输入数据。

---

Q12: CUDA initialization error

报错信息：

>>> torch.cuda.is_available()
/opt/conda/lib/python3.11/site-packages/torch/cuda/__init__.py:129: UserWarning: CUDA initialization: Unexpected error from cudaGetDeviceCount(). Did you run some cuda functions before calling NumCudaDevices() that might have already set an error? Error 804: forward compatibility was attempted on non supported HW (Triggered internally at /pytorch/c10/cuda/CUDAFunctions.cpp:109.)
  return torch._C._cuda_getDeviceCount() > 0
False

原因： 部分显卡（如：RTX系列的）与torcheasyrec cuda镜像中的cuda-compat library不兼容

解决方法： 在运行命令前增加环境变量LD_LIBRARY_PATH=，例如

LD_LIBRARY_PATH= torchrun --master_addr=localhost --master_port=32555 \
    --nnodes=1 --nproc-per-node=2 --node_rank=0 \
    -m tzrec.train_eval \
    --pipeline_config_path multi_tower_din_taobao_local.config

---

Q13: kv特征的key包含":"导致报错

报错信息：

[rank0]: Original Traceback (most recent call last):
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/torch/utils/data/_utils/worker.py", line 349, in _worker_loop
[rank0]:     data = fetcher.fetch(index)  # type: ignore[possibly-undefined]
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/torch/utils/data/_utils/fetch.py", line 42, in fetch
[rank0]:     data = next(self.dataset_iter)
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/tzrec/datasets/dataset.py", line 311, in __iter__
[rank0]:     yield self._build_batch(input_data)
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/tzrec/datasets/dataset.py", line 376, in _build_batch
[rank0]:     sampled = self._sampler.get(input_data)
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/tzrec/datasets/sampler.py", line 423, in get
[rank0]:     features = self._parse_nodes(nodes)
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/tzrec/datasets/sampler.py", line 323, in _parse_nodes
[rank0]:     feature = _to_arrow_array(feature, attr_type)
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/tzrec/datasets/sampler.py", line 160, in _to_arrow_array
[rank0]:     items = kv_list.take(list(range(1, len(kv_list), 2))).cast(
[rank0]:             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank0]:   File "pyarrow/array.pxi", line 1000, in pyarrow.lib.Array.cast
[rank0]:   File "/opt/conda/lib/python3.11/site-packages/pyarrow/compute.py", line 405, in cast
[rank0]:     return call_function("cast", [arr], options, memory_pool)
[rank0]:            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank0]:   File "pyarrow/_compute.pyx", line 590, in pyarrow._compute.call_function
[rank0]:   File "pyarrow/_compute.pyx", line 385, in pyarrow._compute.Function.call
[rank0]:   File "pyarrow/error.pxi", line 155, in pyarrow.lib.pyarrow_internal_check_status
[rank0]:   File "pyarrow/error.pxi", line 92, in pyarrow.lib.check_status
[rank0]: pyarrow.lib.ArrowInvalid: Failed to parse string: 'false}' as a scalar of type float

原因： kv特征的key包含":"导致报错

解决方法： 检查特征表string类型字段是否包含":"，进行数据清洗。

---

Q14: 版本升级后序列特征vocab_list行为变化

问题描述： 从0.9.x或1.0.3-1.1.4升级后，序列特征（如SequenceIdFeature）的vocab_list首元素发生变化。

原因： 在1.0.3版本中，SequenceIdFeature被合并到IdFeature（通过设置sequence_length），但IdFeature的proto default_value默认值为""，与原SequenceIdFeature的默认值"0"不同，导致vocab_list首元素从"0"变为""。1.1.5版本修复了此问题。

升级指南：

• 1.0.2及更早版本（含0.9.x）用户： 可直接升级到1.0.18或1.1.5+，序列特征的default_value行为与旧版本一致，无需额外修改。

• 1.0.3至1.1.4用户： 升级到1.1.5+后，未显式设置default_value的序列特征的vocab_list首元素将从""变为"0"。如需保持与旧版本完全一致的行为，可通过显式设置default_bucketize_value来自行控制vocab_list。示例如下：

  旧版本（1.0.3-1.1.4）配置，未显式设置default_value时，内部自动生成的vocab_list为 ["", "<OOV>", "cat", "dog", "bird"]，其中index0为空字符串""，index1为"<OOV>"：

  feature_config {
    id_feature {
      feature_name: "item_id"
      expression: "item:item_id"
      embedding_dim: 16
      vocab_list: ["cat", "dog", "bird"]
      sequence_length: 50
      sequence_delim: ";"
    }
  }
  

  升级到1.1.5+后，如需保持与旧版本一致的vocab_list映射（即index0为""，index1为"<OOV>"），需将""和"<OOV>"手动加入vocab_list，并设置default_bucketize_value: 1：

  feature_config {
    id_feature {
      feature_name: "item_id"
      expression: "item:item_id"
      embedding_dim: 16
      vocab_list: ["", "<OOV>", "cat", "dog", "bird"]
      default_bucketize_value: 1
      sequence_length: 50
      sequence_delim: ";"
    }
  }
  

  设置default_bucketize_value后，系统不再自动在vocab_list前插入default_value和"<OOV>"，而是直接使用用户配置的vocab_list，OOV值将映射到default_bucketize_value指定的索引。

版本查询方式：

pip index versions tzrec -f http://tzrec.oss-accelerate.aliyuncs.com/release/nightly/repo.html --trusted-host tzrec.oss-accelerate.aliyuncs.com

---

Q15: Hopper GPU上HSTU注意力反向传播autotuning崩溃

报错信息：

File "/opt/conda/lib/python3.11/site-packages/triton/testing.py", line 150, in do_bench
    di.synchronize()
torch.AcceleratorError: CUDA error: an illegal memory access was encountered

原因： Triton 3.7.1 自带的 ptxas 12.8.93 在 Hopper（如 H20，sm_90）上会误编译 HSTU 的 WGMMA kernel：_hstu_attn_bwd 内核在 autotuning 阶段的共享内存访问越界（约 246 KiB，超出 H20 的 228 KiB 上限），触发非法内存访问（compute-sanitizer 下可见 Invalid __shared__ read）。该问题由 Triton release/3.7 分支的 commit 6c96454f2f 将内置 ptxas 从 12.9.86 降级到 12.8.93 引入；换用 ptxas 12.9.86 即可修复（与 MMA v3 代码生成、triton-lang/triton#9514 均无关——经 H20 实测单独打入 #9514 仍报越界）。

解决方法： 1.3.0 镜像已内置修复——将官方 triton 3.7.1 wheel 中的 backends/nvidia/bin/ptxas 替换为 12.9.86 后重新打包，默认即生效，无需 DISABLE_MMA_V3，也不损失 Hopper v3 性能。如需在其它环境手动安装该修复版 wheel：

pip install --force-reinstall --no-deps \
  https://tzrec.oss-accelerate.aliyuncs.com/third_party/triton/triton-3.7.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

---

Q16: DlrmHSTU/UltraHSTU AOTI sample-input autotune导出报错 _assert_scalar(u? <= K)

报错信息：

torch._inductor.exc.InductorError: RuntimeError: Runtime assertion failed for expression u0 <= 2002 on node 'le_5'
While executing %_assert_scalar_1 = call_function[target=torch.ops.aten._assert_scalar.default](args = (%le, "Runtime assertion failed for expression u0 <= 2002 on node 'le_5'"), kwargs = {})

原因： 开启AOTI_AUTOTUNE_WITH_SAMPLE_INPUTS=1后，AOTI在extract_autotune_inputs中通过torch.fx.Interpreter走一次sample-input图，会触达由torch.export插入的_assert_scalar(u_i <= K)节点。这里：

• u0/u2 是 max(uih_seq_lengths).item() / max(num_targets).item()等data-dependent unbacked SymInt（见tzrec/modules/gr/preprocessors.py:375-381）；

• tzrec/ops/utils.py:74 的 torch._check(max_len >= runtime_max_seq_len) 在 runtime_max_seq_len = max_uih_len + max_targets + max_contextual_seq_len（见preprocessors.py:283 + :325）替换之后，给出 sum 上界 u0 + u2 ≤ max_seq_len − max_contextual_seq_len；sympy 进一步用 u2 ≥ 1 推出 per-symbol 上界 u0 ≤ max_seq_len − max_contextual_seq_len − 1；

• PyTorch对unbacked SymInt的node.hint在创建时一次性赋值（约等于max_seq_len），后续torch._check只更新value-range而不回填hint；当hint大于 per-symbol 上界时 sample-input 走graph会触发 assert。

解决方法： 调大model_config.max_seq_len使派生上界跳过hint，同时通过新增的stu.scaling_seqlen把attention scaling分母固定为原max_seq_len，保持推理跟训练时计算完全一致。例：原max_seq_len: 2048、max_contextual_seq_len = 45，per-symbol 上界 2048 − 45 − 1 = 2002 被 hint=2048 打破；改为：

model_config {
  dlrm_hstu {
    hstu {
      stu {
        # ...其余字段不变...
        scaling_seqlen: 2048   # 与训练时相同；保持attention scaling
      }
    }
    max_seq_len: 2112          # 原2048 + 余量；新 per-symbol 上界 2112−45−1 = 2066 > hint
  }
}

具体余量需大于max_contextual_seq_len + 1（max_contextual_seq_len = contextual feature group的特征数）。