AViD推理部署实战：Gradio交互Demo与单图检测代码完整解析指南

AViD推理部署实战：Gradio交互Demo与单图检测代码完整解析指南

【免费下载链接】AViDFramework that enables fine-tuning of vision-language grounding models on custom datasets项目地址: https://gitcode.com/gh_mirrors/avid1/AViD

AViD 是一个基于 Grounding DINO 的视觉-语言定位（vision-language grounding）微调与推理部署框架，支持在自定义数据集上微调开放词汇目标检测模型。本文带你从零跑通它的两个官方推理入口：Gradio 交互 Demo 与单图检测脚本，逐行看懂核心推理代码，并掌握 box_threshold、text_threshold 等关键参数的调法，新手也能快速把模型部署成可交互的检测服务。

一、AViD 是什么：可微调的开放词汇检测框架

传统检测器只能识别预设类别（如 COCO 80 类），而 AViD 继承 Grounding DINO 的能力：你输入一句自然语言（如 "a cat on the sofa"），它就能在图中把cat和sofa都框出来。在此之上，AViD 补齐了三件事：

• 微调流水线：在自定义数据集上训练（如服装电商图），支持 LoRA 参数高效训练（默认只训练约 2% 参数）
• EMA 稳定化：微调时保留预训练知识，避免灾难性遗忘
• 可选的短语级 NMS：去除同一物体的冗余框

整体架构采用"视觉编码器 + 文本编码器 + Transformer 融合"的经典布局：

二、两个推理入口，按场景选

打开demo/目录就能看到项目的两个官方推理入口：

入口文件	适用场景	特点
demo/gradio_app.py	交互式演示、快速验证	浏览器网页操作，拖动阈值滑块实时调参
demo/inference_on_a_image.py	批量/脚本化检测	命令行一键出图，结果保存到磁盘

两个脚本共用同一套核心推理逻辑，都封装在 groundingdino/util/inference.py 中（predict+annotate两个函数），理解一次即可融会贯通。

三、Gradio 交互 Demo：3 分钟搭一个开放词汇检测网页

3.1 模型加载：自动下载权重

demo/gradio_app.py启动时先做三件事：编译 CUDA 扩展、安装gradio、加载模型。核心在load_model_hf函数：

config_file = "groundingdino/config/GroundingDINO_SwinT_OGC.py" ckpt_repo_id = "ShilongLiu/GroundingDINO" ckpt_filename = "groundingdino_swint_ogc.pth" model = load_model_hf(config_file, ckpt_repo_id, ckpt_filename)

它做了三件事：

1. 用SLConfig.fromfile读取 SwinT 配置文件，build_model构建网络结构
2. 通过hf_hub_download自动下载官方 SwinT 权重（首次运行较慢）
3. clean_state_dict清洗状态字典后加载，strict=False容忍个别键不匹配

3.2 推理主流程：一张图到检测框只需 4 步

点击 Run 按钮后触发run_grounding函数，完整流程只有 4 步：

init_image = input_image.convert("RGB") # 1. 统一为 RGB image_tensor = image_transform_grounding(init_image)[1] # 2. Resize→ToTensor→Normalize boxes, logits, phrases = predict(model, image_tensor, # 3. 模型推理 grounding_caption, box_threshold, text_threshold, device='cpu') annotated = annotate(image_source=np.asarray(image_pil), # 4. 画框 boxes=boxes, logits=logits, phrases=phrases)

其中predict（定义于 groundingdino/util/inference.py）的内部逻辑是本文最值得逐行看的部分：

outputs = model(image[None], captions=[caption]) logits = outputs["pred_logits"].sigmoid()[0] # (nq, 256)：每个查询对每个词元的置信度 boxes = outputs["pred_boxes"][0] # (nq, 4)：归一化 cxcywh 框 mask = logits.max(dim=1)[0] > box_threshold # 按最高词元分过滤低置信框

过滤后的每个 logit 向量再交给get_phrases_from_posmap：把置信度超过text_threshold的词元连起来，解码成短语（如 "shirt (0.80)"）。最后annotate用 supervision 库把框、短语、置信度一并绘制到原图上。

3.3 界面布局与启动命令

UI 用经典左右两栏：左侧是图片上传框 + "Detection Prompt" 文本框 + 两个阈值滑块（默认 0.25）；右侧是结果图。启动只需一行：

python demo/gradio_app.py --share

--share会生成一个临时公网链接，方便在没有浏览器的服务器上演示。例如上传下面这张图，输入提示词 "cat, dog, pet bed"，即可看到开放词汇定位效果：

💡 小技巧：提示词用英文逗号分隔多个短语，句末会自动补句号（preprocess_caption处理），无需手动加。

四、单图检测脚本：命令行一次出图

适合集成进流水线或批量处理，对应demo/inference_on_a_image.py。

4.1 图片预处理：标准三步变换

load_image函数返回两个版本——原图 PIL（用于画结果）和张量（喂给模型）：

transform = T.Compose([ T.RandomResize([800], max_size=1333), # 短边 800 T.ToTensor(), T.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]) # ImageNet 均值方差 ])

这套变换与训练时完全一致，推理部署时不要改动，否则精度会明显下降。

4.2 核心输出函数与可视化

get_grounding_output与 Demo 中的predict逻辑一致（过滤 + 短语解码），但多了一个token_spans高级模式：可以精确指定"只检测词句中第几到第几个词元"，例如对 "a cat and a dog" 只检测 "cat" 时传[[[2, 5]]]。

plot_boxes_to_image负责画框，两个容易踩坑的细节：

box = box * torch.Tensor([W, H, W, H]) # 归一化坐标 → 像素坐标 box[:2] -= box[2:] / 2 # cxcywh → xyxy box[2:] += box[:2]

模型输出的框是中心点+宽高、且已归一化，必须先放大到原图尺寸、再转成左上右下格式才能画。

4.3 运行命令

python demo/inference_on_a_image.py \ --config_file groundingdino/config/GroundingDINO_SwinT_OGC.py \ --checkpoint_path path/to/groundingdino_swint_ogc.pth \ --image_path your/image.jpg \ --text_prompt "shirt .bag .pants" \ --output_dir outputs

输出目录会生成raw_image.jpg（原图）和pred.jpg（带框结果）。无显卡环境加--cpu-only即可，如检测一只猫：

五、关键阈值调参：框太少还是框太多？

两个阈值是最常被问到的调参点，直接影响推理部署效果：

参数	作用	调低	调高
box_threshold（默认 0.25~0.35）	过滤低置信检测框	召回更多候选框，误报变多	只留高置信框，可能漏检
text_threshold（默认 0.2~0.25）	决定哪些词元被连成短语	短语更长（如 "the shirt"）	短语更短，可能拆词

经验值：快速演示用 0.25/0.25；生产环境建议从 0.35/0.2 起步，再对着自己的业务图微调。test.py中还内置了按短语分组的 NMS（apply_nms_per_phrase，IoU 默认 0.3），可进一步去除同一物体的重复框。

六、微调前后的真实效果：视觉-语言定位对比

以下两张图来自仓库内置的服装示例（红框为预测，绿框为标注）：微调前模型对 "shirt / pants / bag" 的框又松又偏、置信度低（0.3x 左右）；微调后框紧贴目标，shirt 置信度升到 0.80，pants 达 0.69：

微调前——检测框漂移明显，视觉-语言对齐不佳：

微调后——框紧贴服装目标，视觉-语言定位精度显著提升：

这正是 AViD 的价值：LoRA 只训练约 2% 参数，mAP@0.5 即可从 0.5x 提升到 0.8x~0.9x 区间（见 README 性能表），而推理部署方式与微调前完全相同，无需改代码。

七、部署常见问题速查

• 首次运行编译慢：gradio_app.py 启动时会执行setup.py build develop编译 MsDeformAttn CUDA 算子，属正常现象；CPU 环境设置TORCH_CUDA_ARCH_LIST或直接用推理脚本加--cpu-only
• 权重在哪：Demo 自动从 Hugging Face 拉取groundingdino_swint_ogc.pth；微调后模型则通过 configs/test_config.yaml 中model.weights_path指定，用test.py或evaluate.py推理
• 微调模型加载：groundingdino/util/inference.py的load_model支持use_lora=True，会自动合并 LoRA 权重（merge_and_unload），加载后推理接口不变
• 阈值报 "No boxes found"：把两个阈值都下调到 0.1 试试，多半是提示词与图中物体不匹配

总结

AViD 的推理部署门槛并不高：Gradio Demo 一条命令起网页，单图脚本一行命令出结果，两者共用predict+annotate这套核心逻辑。抓住"预处理三步 → sigmoid 过滤 box_threshold → 词元解码 text_threshold → 坐标还原画框"这条主线，再结合微调前后对比调参，你就完全掌握了这个视觉-语言定位框架的部署全流程。

【免费下载链接】AViDFramework that enables fine-tuning of vision-language grounding models on custom datasets项目地址: https://gitcode.com/gh_mirrors/avid1/AViD