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-cn-beijing.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 v3.6.0在Hopper GPU（如H20）上存在WGMMA（Warp Group Matrix Multiply-Accumulate）代码生成Bug。在RS WGMMA路径中缺少寄存器同步指令，导致_hstu_attn_bwd内核在autotuning阶段出现非法内存访问。

解决方法： 安装修复后的Triton wheel：

pip install --force-reinstall --no-deps "https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/triton/triton-3.6.0%2B565c08520-cp311-cp311-linux_x86_64.whl"