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/AViDAViD 是一个基于 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 中predictannotate两个函数理解一次即可融会贯通。三、Gradio 交互 Demo3 分钟搭一个开放词汇检测网页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)它做了三件事用SLConfig.fromfile读取 SwinT 配置文件build_model构建网络结构通过hf_hub_download自动下载官方 SwinT 权重首次运行较慢clean_state_dict清洗状态字典后加载strictFalse容忍个别键不匹配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, devicecpu) annotated annotate(image_sourcenp.asarray(image_pil), # 4. 画框 boxesboxes, logitslogits, phrasesphrases)其中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(dim1)[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_size1333), # 短边 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中还内置了按短语分组的 NMSapply_nms_per_phraseIoU 默认 0.3可进一步去除同一物体的重复框。六、微调前后的真实效果视觉-语言定位对比以下两张图来自仓库内置的服装示例红框为预测绿框为标注微调前模型对 shirt / pants / bag 的框又松又偏、置信度低0.3x 左右微调后框紧贴目标shirt 置信度升到 0.80pants 达 0.69微调前——检测框漂移明显视觉-语言对齐不佳微调后——框紧贴服装目标视觉-语言定位精度显著提升这正是 AViD 的价值LoRA 只训练约 2% 参数mAP0.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_loraTrue会自动合并 LoRA 权重merge_and_unload加载后推理接口不变阈值报 No boxes found把两个阈值都下调到 0.1 试试多半是提示词与图中物体不匹配总结AViD 的推理部署门槛并不高Gradio Demo 一条命令起网页单图脚本一行命令出结果两者共用predictannotate这套核心逻辑。抓住预处理三步 → 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考