TensorFlow Object Detection API 环境配置与踩坑记录
1. 环境背景
本项目采用 TensorFlow Object Detection API 进行鸟类目标检测训练，使用 SSD-MobileNet 系列模型进行迁移学习。
硬件环境
- GPU：NVIDIA A10 × 2
- Driver Version：550.67
- CUDA Runtime：12.4
软件环境
Ubuntu22.04Python3.10TensorFlow2.14.1 Keras2.14.x tf-slim1.1.0 protobuf3.20.x模型
ssd_mobilenet_v2_fpnlite_320x320_coco17_tpu-82. TensorFlow Models 版本选择
错误现象
训练启动时出现：
ModuleNotFoundError: No module named 'tf_keras'或者：
ImportError: cannot import name 'tensor' from tensorflow.python.framework原因分析
新版 TensorFlow Models 仓库已经依赖：
importtensorflowastf,tf_keras而 TensorFlow 2.10 环境中并不存在：
tf_keras导致导入失败。
解决方案
方案一：升级 TensorFlow
pipinstalltensorflow==2.14.1方案二：使用与 TensorFlow 2.10 匹配的 Models 仓库版本
推荐 TensorFlow 2.14 + 最新 Models 组合。
3. tf-slim 与 TensorFlow 2.14 不兼容
错误现象
AttributeError: module 'tensorflow.python.ops.control_flow_ops' has no attribute 'case'随后又出现：
AttributeError: module 'tensorflow.python.ops.control_flow_ops' has no attribute 'cond'原因分析
TensorFlow 2.14 删除了部分内部 API：
control_flow_ops.casecontrol_flow_ops.cond而 tf-slim 仍然调用这些接口。
修改文件
/data/tf213_env/lib/python3.10/site-packages/tf_slim/data/tfexample_decoder.py找到：
fromtensorflow.python.opsimportcontrol_flow_ops添加：
importtensorflowastfifnothasattr(control_flow_ops,"case"):control_flow_ops.case=tf.caseifnothasattr(control_flow_ops,"cond"):control_flow_ops.cond=tf.cond验证
python-c" from tensorflow.python.ops import control_flow_ops print(hasattr(control_flow_ops,'case')) print(hasattr(control_flow_ops,'cond')) "输出：
True True4. SSD训练时报 JIT Compilation Failed
错误现象
tensorflow.python.framework.errors_impl.UnknownError JIT compilation failed Loss/Encode_1/Log_1同时伴随：
libdevice not found at ./libdevice.10.bc Couldn't invoke ptxas --version误区
最开始容易误判为：
- TFRecord损坏
- Anchor配置错误
- pipeline.config配置错误
- 标注框异常
- num_classes设置错误
实际上均不是根因。
5. CUDA Toolkit 缺失问题
GPU检查
python-c" import tensorflow as tf print(tf.config.list_physical_devices('GPU')) "输出：
[PhysicalDevice(name='/physical_device:GPU:0', device_type='GPU')]说明 GPU 可正常识别。
查看 TensorFlow 编译信息
python-c" import tensorflow as tf print(tf.sysconfig.get_build_info()) "输出：
OrderedDict([('cuda_version','11.8'),('cudnn_version','8')])说明：
TensorFlow 2.14 需要 CUDA 11.8 Toolkit检查 CUDA Toolkit
检查 nvcc
nvcc--version输出：
Command 'nvcc' not found检查 libdevice
find/usr/local-namelibdevice.10.bc结果为空。
说明：
系统只有 NVIDIA Driver 没有 CUDA Toolkit6. 安装 CUDA Toolkit
Ubuntu 22.04：
sudoaptupdatesudoaptinstallnvidia-cuda-toolkit验证安装
ptxas
find/usr-nameptxas输出：
/usr/bin/ptxaslibdevice
find/usr-namelibdevice.10.bc输出：
/usr/lib/nvidia-cuda-toolkit/libdevice/libdevice.10.bc7. XLA 找不到 libdevice
错误现象
即使安装 Toolkit 后仍报：
libdevice not found at ./libdevice.10.bc原因分析
TensorFlow XLA 默认查找：
CUDA_HOME/nvvm/libdevice/libdevice.10.bc而 Ubuntu 软件包实际安装位置：
/usr/lib/nvidia-cuda-toolkit/libdevice/libdevice.10.bc导致路径不匹配。
解决方案
设置：
exportXLA_FLAGS="--xla_gpu_cuda_data_dir=/usr/lib/nvidia-cuda-toolkit"验证：
echo$XLA_FLAGS输出：
--xla_gpu_cuda_data_dir=/usr/lib/nvidia-cuda-toolkit重新训练即可正常运行。
8. 永久生效配置
写入：
~/.bashrc添加：
exportXLA_FLAGS="--xla_gpu_cuda_data_dir=/usr/lib/nvidia-cuda-toolkit"执行：
source~/.bashrc9. 最终可用环境
Ubuntu 22.04 Python 3.10 TensorFlow 2.14.1 Keras 2.14.x tf-slim 1.1.0 NVIDIA Driver 550.67 CUDA Runtime 12.4 CUDA Toolkit 11.5 GPU: NVIDIA A10 ×2 TensorFlow Models: models-master-new-bak Model: ssd_mobilenet_v2_fpnlite_320x320_coco17_tpu-810. SSD Bird Dataset 推荐配置
与 YOLOv8/YOLO11 训练策略对标：
num_classes: 1 batch_size: 16 fine_tune_checkpoint_type: "detection" use_bfloat16: false weight_decay: 0.0005 cosine_decay_learning_rate { learning_rate_base: 0.01 total_steps: 50000 warmup_learning_rate: 0.001 warmup_steps: 1000 }数据增强建议保留：
random_horizontal_flip {} random_adjust_brightness {} random_adjust_contrast {}鸟类检测不建议开启：
random_crop_image容易裁掉小目标。
11. 故障排查顺序
后续训练失败建议按以下顺序检查：
- TensorFlow 是否识别 GPU；
- CUDA Toolkit 是否安装；
- ptxas 是否存在；
- libdevice.10.bc 是否存在；
- XLA_FLAGS 是否正确配置；
- tf-slim 兼容性补丁是否生效；
- TFRecord 是否正常；
- label_map 是否正确；
- pipeline.config 参数是否正确；
- 学习率与 Batch Size 是否合理。
12. 本次踩坑总结
本次训练环境问题经历如下：
TensorFlow 2.10 ↓ tf_keras缺失 ↓ 升级 TensorFlow 2.14 ↓ tf-slim case/cond 不兼容 ↓ 手动补丁修复 ↓ 训练启动 ↓ JIT compilation failed ↓ 定位到 XLA ↓ 发现缺少 CUDA Toolkit ↓ 安装 nvidia-cuda-toolkit ↓ 配置 XLA_FLAGS ↓ 训练恢复正常最终确认：
- TFRecord 数据正常
- pipeline.config 正常
- SSD 模型正常
- 根因是 TensorFlow XLA 无法找到 libdevice.10.bc
链接
其他问题可参考官方连接，
https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/tf2.md https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/tf2_detection_zoo.md https://github.com/tensorflow/models/tree/master/research/object_detection
