DETR Document Table Detection on Ascend NPU

1. 简介

本文档记录 TahaDouaji/detr-doc-table-detection 在 Ascend 910B3 NPU 环境下的适配与验证结果。

该模型基于 DETR（DEtection TRansformer，Facebook Research）架构，使用 ResNet-50 作为 backbone，在 ICDAR2019 数据集上微调，用于文档图像中的表格检测。模型支持检测有边框（bordered）和无边框（borderless）两种类型的表格。

DETR 是一种端到端的目标检测模型，将检测任务视为集合预测问题，无需锚框、NMS 等后处理步骤，简化了检测流程。

本仓库提供：

• inference.py：NPU 推理脚本，支持单张/批量图片表格检测
• eval.py：精度与性能评测脚本
• log.txt：评测运行日志

相关获取地址：

• 权重下载地址（HuggingFace）：https://huggingface.co/TahaDouaji/detr-doc-table-detection
• 镜像加速：https://hf-mirror.com

参考文档：

• https://arxiv.org/abs/2005.12872（DETR 论文）
• https://huggingface.co/docs/transformers/model_doc/detr

2. 验证环境

• NPU：Ascend 910B3，1 逻辑卡
• 模型架构：DetrForObjectDetection（ResNet-50 backbone）
• 编码器层数：6
• 解码器层数：6
• 注意力头数：8
• 隐藏层维度：256
• 查询数：100
• 参数量：约 41M
• 检测类别：1（table）

3. 推理启动

启动前可先检查 NPU 可用性：

python3 -c "import torch; print(f'NPU available: {torch.npu.is_available()}')"

环境准备：

# 安装依赖（timm 是 DETR 的 ResNet backbone 所需）
pip install torch torch_npu transformers timm Pillow

# 设置 NPU 可见设备
export ASCEND_RT_VISIBLE_DEVICES=0

已验证通过的推理命令：

单张图片检测：

python inference.py --image path/to/document.jpg

批量检测：

python inference.py --image-dir path/to/images/

调整检测阈值：

python inference.py --image doc.jpg --threshold 0.3

CPU 推理（参考基准）：

python inference.py --device cpu --image doc.jpg

输出格式：

{
  "model": "TahaDouaji--detr-doc-table-detection",
  "device": "npu:0",
  "num_images": 1,
  "inference_time_seconds": 0.25,
  "results": [
    {
      "image": "document.jpg",
      "detections": [
        {
          "box": [50.12, 80.34, 400.56, 300.78],
          "score": 0.9821,
          "label": "table"
        }
      ]
    }
  ]
}

边界框格式：[x1, y1, x2, y2]（左上角和右下角坐标，单位：像素）。

4. Smoke 验证

python inference.py --image test_images/doc_with_table.jpg

预期输出：

• 返回 JSON 格式结果
• detections 数组包含检测到的表格边界框
• 每个检测包含 box、score、label 字段
• 推理时间约 0.2-0.3s（NPU）

验证结果：

• 推理在 NPU 上正常完成
• 可检测到图像中的表格区域
• 输出 JSON 格式正确
• 坐标在图像尺寸范围内

5. 性能参考

测试条件：4 张文档图片，threshold=0.5。

注：DETR 模型计算量较大（backbone + transformer encoder-decoder），NPU 加速效果显著。CPU 推理需 4 秒以上，NPU 仅需约 0.24 秒。

6. 精度评测

精度评测采用检测框一致率和坐标误差作为指标。

结论：NPU 与 CPU 检测到相同的表格区域，边界框坐标差异最大仅 0.48 像素（远小于 1 像素），精度通过验证。

7. 注意事项

1. timm 依赖：DETR 的 ResNet backbone 依赖 timm 库，需提前安装（pip install timm）。
2. 输入分辨率：模型将输入图片自动缩放，保持宽高比，最长边不超过 800 像素。
3. 检测阈值：默认置信度阈值为 0.5，可通过 --threshold 参数调整。阈值越低，召回越高但可能引入误检。
4. DETR 特点：端到端检测，无需锚框和 NMS，但计算量较大，适合需要高质量检测的场景。
5. 边界框格式：输出为 [x1, y1, x2, y2] 绝对坐标，可直接用于在图像上绘制检测框。
6. 单类检测：该模型仅检测 "table" 一个类别，如需检测其他文档元素需使用其他模型。