TensorFlow Object Detection API 环境配置与踩坑记录

1. 环境背景

本项目采用 TensorFlow Object Detection API 进行鸟类目标检测训练，使用 SSD-MobileNet 系列模型进行迁移学习。

硬件环境

• GPU：NVIDIA A10 × 2
• Driver Version：550.67
• CUDA Runtime：12.4

软件环境

Ubuntu 22.04
Python 3.10
TensorFlow 2.14.1
Keras 2.14.x
tf-slim 1.1.0
protobuf 3.20.x

模型

ssd_mobilenet_v2_fpnlite_320x320_coco17_tpu-8

---

2. TensorFlow Models 版本选择

错误现象

训练启动时出现：

ModuleNotFoundError: No module named 'tf_keras'

或者：

ImportError:
cannot import name 'tensor'
from tensorflow.python.framework

原因分析

新版 TensorFlow Models 仓库已经依赖：

import tensorflow as tf, tf_keras

而 TensorFlow 2.10 环境中并不存在：

tf_keras

导致导入失败。

解决方案

方案一：升级 TensorFlow

pip install tensorflow==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.case
control_flow_ops.cond

而 tf-slim 仍然调用这些接口。

---

修改文件

/data/tf213_env/lib/python3.10/site-packages/tf_slim/data/tfexample_decoder.py

找到：

from tensorflow.python.ops import control_flow_ops

添加：

import tensorflow as tf

if not hasattr(control_flow_ops, "case"):
    control_flow_ops.case = tf.case

if not hasattr(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
True

---

4. 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 -name libdevice.10.bc

结果为空。

说明：

系统只有 NVIDIA Driver
没有 CUDA Toolkit

---

6. 安装 CUDA Toolkit

Ubuntu 22.04：

sudo apt update

sudo apt install nvidia-cuda-toolkit

---

验证安装

ptxas

find /usr -name ptxas

输出：

/usr/bin/ptxas

libdevice

find /usr -name libdevice.10.bc

输出：

/usr/lib/nvidia-cuda-toolkit/libdevice/libdevice.10.bc

---

7. 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

导致路径不匹配。

---

解决方案

设置：

export XLA_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

添加：

export XLA_FLAGS="--xla_gpu_cuda_data_dir=/usr/lib/nvidia-cuda-toolkit"

执行：

source ~/.bashrc

---

9. 最终可用环境

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-8

---

10. 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. 故障排查顺序

后续训练失败建议按以下顺序检查：

1. TensorFlow 是否识别 GPU；
2. CUDA Toolkit 是否安装；
3. ptxas 是否存在；
4. libdevice.10.bc 是否存在；
5. XLA_FLAGS 是否正确配置；
6. tf-slim 兼容性补丁是否生效；
7. TFRecord 是否正常；
8. label_map 是否正确；
9. pipeline.config 参数是否正确；
10. 学习率与 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