简介这是一套基于YOLO11与DeepSORT联合实现的目标跟踪算法实战项目适合具备一定深度学习基础、希望快速落地目标检测与多目标跟踪应用的开发者。项目兼顾检测与跟踪两条主线利用YOLO11完成目标定位通过DeepSORT实现稳定跨帧轨迹关联可用于交通监控、安防巡检、人流统计等场景。资源共54个文件压缩包大小约27.92MB以29个Python脚本为核心涵盖模型加载、推理、跟踪逻辑与工具封装另含15个编译生成的pyc文件、2个PyTorch权重文件yolo11n.pt、yolo11s.pt、2个演示视频和3个Markdown教程文档方便对照流程调试和快速复现。YAML配置与LICENSE文件也一并包含结构清楚便于二次开发。目前已有462人学习下载。对想从零搭建YOLO11DeepSORT项目或参考完整工程结构的人来说这份资料能够提供可直接运行的源码、模型与配套说明减少环境搭建和算法联调中的弯路。1. 目标跟踪实战YOLO11DeepSORT 能把逐帧检测变成稳定 ID 轨迹做过视频检测的人应该都有同一种体验YOLO 把每一帧的行人、车辆都框出来了但你把几帧视频连起来看同一个人的编号一会儿是 3、一会儿是 17甚至完全消失又重新出现。这就是纯目标检测的局限——它不关心“谁是谁”只关心“哪里有目标”。而目标跟踪要回答的问题恰恰是这个框属于哪个目标、它上一帧在哪、下一帧会去哪。这份基于 YOLO11DeepSORT 实现的目标跟踪算法项目把检测和跟踪串成了一条完整链路YOLO11 负责每帧的检测框DeepSORT 负责给框分配稳定 ID 并维持轨迹。项目自带 test.mp4 测试视频、yolo11s.pt 和 yolo11n.pt 预训练权重、deep_sort_pytorch 跟踪核心包和流程教程解压后从命令行就能跑出一个带持续 ID 的跟踪视频。适合正在做课程设计、毕业设计或者刚接触多目标跟踪想做落地验证的从业者。2. 项目结构先拆开看track.py 与 deep_sort_pytorch 各管哪一段2.1 解压后的文件清单与角色分配拿到压缩包之后第一件事不是急着跑而是把目录结构捋清楚。这份工程解压后的核心文件如下文件 / 目录角色track.py程序主入口负责加载检测器、初始化跟踪器、逐帧推理并保存输出utils.py工具函数主要封装检测结果到跟踪器输入的转换逻辑test.mp4提供的测试视频用于快速验证效果weights / yolo11s.ptYOLO11s 预训练权重精度优先weights / yolo11n.ptYOLO11n 预训练权重速度优先deep_sort_pytorch /DeepSORT 跟踪核心实现封装了特征提取、级联匹配与轨迹管理inference /默认输出目录跑完后生成带跟踪框和 ID 的视频configs /跟踪器相关配置文件README.md项目说明与运行指引实际跑的时候你只需要直接操作track.py不需要改动deep_sort_pytorch内部的任何代码。这个包对你来说就是一个黑匣子你把检测框送进去它还给你带 ID 的轨迹。2.2 推理链路detection → feature → matching 三段式数据流整条推理链路的理解是调参的基础。YOLO11 每帧输出的是裸检测结果格式一般是(x1, y1, x2, y2, conf, cls)。DeepSORT 要的不是这个格式它需要的是(cx, cy, w, h)或(x1, y1, x2, y2)的边界框列表以及每个框对应的外观特征向量。utils.py里做的就是这个转换# utils.py 中检测结果到跟踪器输入的典型转换逻辑 def detections_to_deepsort(detections): 将 YOLO11 的检测结果转换为 DeepSORT 检测器可接受的格式。 参数: detections: list, 每项为 [x1, y1, x2, y2, conf, cls] 返回: bbox_xywh: list, 中心点 宽高格式的边界框 confs: list, 置信度 clss: list, 类别编号 bbox_xywh [] confs [] clss [] for det in detections: x1, y1, x2, y2, conf, cls det # 将左上右下坐标转为中心点 宽高 cx (x1 x2) / 2 cy (y1 y2) / 2 w x2 - x1 h y2 - y1 bbox_xywh.append([cx, cy, w, h]) confs.append(conf) clss.append(cls) return bbox_xywh, confs, clss这段转换是必须的。DeepSORT 内部的卡尔曼滤波预测的是目标中心点和宽高而不是角点坐标直接把 YOLO 的xyxy喂进去会导致状态更新错位。很多入门者在这里第一次翻车。转换完之后DeepSORT 做三件事第一对当前帧检测框提取外观特征向量第二把特征向量和已有轨迹的外观特征库做余弦相似度计算第三结合卡尔曼滤波预测位置执行级联匹配。匹配成功的检测框更新到对应轨迹上ID 保持不变没匹配上的检测框会尝试新建轨迹。这就是“先后帧之间能对得上是谁”的根本机制。2.3 两个模型权重的选型差异权重文件给了两个版本说明作者已经帮你想到了不同算力场景。yolo11n.pt是 nano 版模型规模最小yolo11s.pt是 small 版规模中等。以一般监控视频场景为例两者的差异比较如下对比项yolo11n.ptyolo11s.pt模型体积更小加载更快中等体积约为 n 的 2~3 倍推理速度更高适合无 GPU 或低算力环境相对慢一点但仍可实时检测精度对小目标和远距离目标略弱对遮挡、小目标更鲁棒适用场景快速验证、摄像头密集部署离线视频分析、对精度要求高的任务在track.py中通过--yolo-weights参数指定权重路径即可切换。我一般先用yolo11n.pt跑通流程确认链路没问题后再换yolo11s.pt跑正式视频这样能节省不少调试时间。有一个容易被忽略的细节换yolo11s.pt之后检测分数分布会变原来的置信度阈值不一定合适后面避坑章节会细说。3. 跑通第一个 demotrack.py 的命令行入口与配置方式3.1 命令行参数与典型启动方式先别改任何代码直接进项目根目录跑一次默认命令cd 解压后的项目目录 python track.py --source test.mp4 --yolo-weights weights/yolo11s.pt正常情况下控制台会陆续打印每帧的检测数量、跟踪 ID 列表和 FPS 信息程序结束后在inference/output目录下生成一个带跟踪框和 ID 的视频文件。这个命令的意思很直白用yolo11s.pt权重处理test.mp4中的每一帧把结果写到默认输出目录。track.py里比较常用的命令行参数还有这几个python track.py \ --source test.mp4 \ --yolo-weights weights/yolo11s.pt \ --conf-thres 0.25 \ --iou-thres 0.45 \ --device 0 \ --save-vid \ --show-vid参数含义如下--conf-thres是置信度阈值低于这个分数的检测框会被丢弃--iou-thres是 NMS 的 IoU 阈值控制同类别重叠框的抑制力度--device指定推理设备0表示第一张 GPUcpu表示纯 CPU 推理--save-vid保存输出视频--show-vid实时显示推理画面。如果只是想把跟踪结果存入文件--save-vid就够了没必要开显示窗口。3.2 输入输出路径与文件格式约定工程默认把test.mp4放在项目根目录输出写到inference/output目录。track.py里通常有一段类似的路径处理逻辑# track.py 中的默认输出目录设置 output_dir inference/output os.makedirs(output_dir, exist_okTrue) # 默认输出文件名与源视频名保持一致后缀改为 .mp4 output_path os.path.join( output_dir, os.path.basename(args.source).replace(.mp4, _tracked.mp4) )要注意两点第一inference目录存在但output子目录可能不存在代码里用os.makedirs(..., exist_okTrue)自动创建这是比较稳妥的写法第二输出视频的编码依赖 OpenCV 的VideoWriter能力如果系统里没装对应编码器最后生成的文件可能打不开。遇到这种情况把输出后缀从.mp4改成.avi或者换mp4v编码器能省很多事。如果你想处理自己的视频把参数换成自己的文件路径就行。常见做法是把视频放到项目根目录下一个名为data或videos的文件夹里然后指定相对路径避免在命令行里写一长串绝对路径。3.3 观察输出验证链路是否真正跑通程序跑完之后别直接关终端。先检查日志里有没有出现类似Track ID: 2, Frame: 57这样的输出——这说明检测结果已经进入了跟踪器并且被分配了 ID。然后用播放器打开输出视频重点观察同一个 ID 是否在连续帧中跟着同一个目标移动。更严谨一点的验证方法是做一次对照用相同的视频和参数分别跑yolo11n.pt和yolo11s.pt对比两者在同样场景下的框数量、ID 稳定程度和整体 FPS。如果 nano 版输出视频里目标框频繁抖动而 small 版明显更稳说明当前场景对检测精度有要求直接用 s 权重会更合适。这一步验证很有用它能帮你判断项目本身的跟踪逻辑是否正常排除“代码没问题但视频太难”的情况。4. DeepSORT 参数调优max_age、余弦阈值与特征缓冲区的取舍4.1 核心参数语义DeepSORT 的行为主要由几个参数决定。这些参数通常在deep_sort_pytorch/configs/deep_sort.yaml或track.py开头的配置字典里集中管理。四个最关键的参数是参数默认值参考作用max_cosine_distance0.2~0.3外观特征匹配阈值小于该值才认为属于同一目标nn_budget50~100每个轨迹保留的历史外观特征数量超出则淘汰旧特征max_age30~70轨迹在没有匹配时最多存活帧数超过则删除轨迹n_init1~3新轨迹需要连续匹配多少帧才被正式确认max_cosine_distance用大白话讲就是“长相多接近才算同一个人”。检测器每帧都会为目标提取一个特征向量和轨迹历史特征向量算余弦距离距离越小越相似。阈值设太大不同目标容易被误判成同一个阈值设太小同一个目标因为视角、姿态变化就会跟丢。max_age决定的是“跟丢了还能找回来多久”相当于给轨迹留了一截后悔药。目标被完全遮挡几帧后重现只要还在max_age范围内轨迹就能重新匹配上。n_init则决定新轨迹的确认门槛设成 1 时目标一出现就确认新 ID设成 3 时要连续 3 帧都匹配上才会确认能有效减少闪烁 ID。4.2 不同场景下的推荐参数组合用同一组参数打天下是不现实的你需要根据目标密度和运动特性来调。我总结的参考组合如下场景max_cosine_distancenn_budgetmax_agen_init稀疏行人1~5 人0.350301密集行人10 人以上0.2100503车辆跟踪车流稳定0.2580702强遮挡场景0.3100703在密集行人场景下把max_cosine_distance压低是为了防止不同人因衣服颜色相近、运动轨迹接近而互相抢占 ID。nn_budget调高能保留更多历史特征对长时间遮挡后的重识别有帮助但代价是内存占用上升帧率会略微下降。4.3 调参评估ID Switch 与 FPS 的取舍调参不能只靠肉眼感观要看两个硬指标ID Switch 次数和平均 FPS。ID Switch 指的是同一个目标在跟踪过程中 ID 发生跳变的次数。你可以自己写一个简单统计在track.py的输出信息里把每个 ID 的起始帧和结束帧记下来# 统计 ID Switch 的工具思路可以在 track.py 中嵌入 id_start_frame {} # key: id, value: 首次出现帧 id_last_frame {} # key: id, value: 最后出现帧 id_switch_count 0 # 在每次更新跟踪器结果后执行 for track in tracked_objects: tid track[track_id] frame current_frame_index if tid not in id_start_frame: id_start_frame[tid] frame elif frame id_last_frame.get(tid, -1) 1: # 同一 ID 在中断后又出现视为一次跳变 id_switch_count 1 id_last_frame[tid] frame这里有一个容易犯的错ID 从画面完全离开再回来算不算 Switch严格来说不算这是轨迹生命周期结束后的新轨迹。只有同一目标连续出现在画面中 ID 却变了才算是真正的 Switch。调参时如果发现 ID Switch 很多优先怀疑max_cosine_distance和n_init的设置先把n_init提到 3 再看效果。整体原则是先保 FPS再调 ID 稳定性否则一个跑 20 帧的跟踪程序在实时场景里没有意义。5. 避坑指南YOLO11DeepSORT 实战里的五个翻车现场5.1 GPU 环境看着正常实际却在 CPU 上跑现象nvidia-smi能看到显卡PyTorch 也装的是 GPU 版但推理时 GPU 占用率极低CPU 满载。原因track.py里指定了--device cuda但检测器模型加载后没有调用.to(device)或者输入帧张量没有搬到 GPU 上推理实际发生在 CPU 端。解决在track.py模型初始化后强制加一行验证代码# 确认模型在所选设备上 import torch print(CUDA available:, torch.cuda.is_available()) print(Using device:, device) model.to(device) # 在推理循环里 frame_tensor frame_tensor.to(device)从那以后我开跑前都会强制走一遍这段校验否则后面花在调参上的时间全部白费。5.2 检测框正常ID 却频繁跳动现象输出视频里每帧都有框但同一个行人的 ID 在 3 和 7 之间来回变甚至每帧都变。原因最常见的是n_init设成了 1新轨迹确认门槛太低目标稍微抖动一下就被当作新目标另一种可能是max_cosine_distance设置过大不同目标的外观特征互相干扰。解决先把n_init改成 3让跟踪器连续确认几帧后再分配正式 ID。再把max_cosine_distance从 0.3 降到 0.2 观察效果。如果还是跳检查utils.py里坐标转换时xyxy和xywh是否混用——这个问题隐蔽但破坏力极大。5.3 换了自定义视频跟踪结果全为空现象test.mp4跑得好好的换成自己录的视频后输出视频里一个框都没有。原因自己视频里的目标距离远、尺寸小默认conf-thres 0.25直接把这些低分检测框丢弃了。更麻烦的是这些目标在一帧里可能偶尔被检测到、下一帧又消失DeepSORT 根本没法建立稳定轨迹。解决先把置信度阈值降到 0.1 单独跑一次检测看目标框是否出现。如果出现了再把conf-thres逐步从 0.1 调到 0.15、0.2找到既能抓到目标又不会引入大量误检的下限。也可以用--classes 0之类的参数只保留行人或车辆类别排除背景干扰。5.4 权重文件损坏导致加载崩溃现象运行到torch.load时抛出类似EOFError或unexpected end of data的错误。原因yolo11s.pt或yolo11n.pt下载不完整或者下载工具把文件截断了。这类权重文件加载不出错才怪。解决先对比压缩包里的权重文件和解压后的文件大小确认字节数一致。再单独用 PyTorch 加载验证import torch # 验证权重文件是否可正常加载 ckpt torch.load(weights/yolo11s.pt, map_locationcpu) print(Loaded keys:, list(ckpt.keys())[:5])如果加载失败不要犹豫删除文件重新下载。调参调了半天发现是权重坏了属于最容易让人心态崩掉的坑。5.5 输出视频打不开或文件损坏现象程序正常跑完inference/output下也有输出文件但播放器提示“无法渲染此文件”。原因OpenCV 的VideoWriter写入mp4时依赖mp4v或avc1编码器系统缺少对应编码库时就会生成一个看着有大小但实际不可用的文件。解决把输出文件后缀改为.avi或者显式设置编码器为mp4v。改动很小但能省掉一整个下午的折腾。如果你需要在网页里直接播放最后再单独用 FFmpeg 把.avi转成.mp4即可。6. 验证与进阶把在线视频推理改成实时流并给出评估指标离线视频验证完成后接下来最值得做的事是把这个工程改造成支持摄像头实时流的版本。思路是把--source从视频文件路径改成摄像头索引号然后逐帧读取、逐帧跟踪、逐帧显示。# 将 track.py 的输入源扩展为摄像头实时流的关键片段 import cv2 # 当 --source 为整数时视为摄像头索引 source 0 if args.source.isdigit() else args.source cap cv2.VideoCapture(source) while True: ret, frame cap.read() if not ret: break # 1. YOLO11 检测 results model(frame) detections preprocess_detections(results) # 2. 更新 DeepSORT 跟踪器 tracked_objects deepsort_update(detections, frame) # 3. 绘制跟踪框与 ID 标签 for obj in tracked_objects: x1, y1, x2, y2, track_id obj cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, str(track_id), (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.imshow(YOLO11 DeepSORT Real-time Tracking, frame) if cv2.waitKey(1) 0xFF ord(q): break这段代码的要点在于source的判别输入是字符串数字时 OpenCV 会识别成摄像头索引输入是路径时按视频文件处理。将检测结果送入deepsort_update之前仍然要做一次xyxy到xywh的转换这里的格式错误同样会让 ID 乱跳不能因为换了输入源就忽略前期的数据清洗。实时跑通之后评估效果不能只看画面“顺不顺眼”。建议给工程加两个指标平均帧处理耗时和 ID Switch 次数。前者反映检测器与跟踪器的综合性能后者反映跟踪稳定性。我一般会在循环里用time.time()统计每一帧的推理耗时帧间取移动平均ID Switch 则用第 4 章中给出的思路统计。数值出来后再回头调整conf-thres和max_cosine_distance让指标朝着可接受的方向变动而不是靠感觉乱试。这份工程本身做得比较完整从离线视频到实时流只差一点改造量很适合作为入门项目把整条链路摸透。在实战里走过一遍你才会真正理解 DeepSORT 的级联匹配和 YOLO11 的检测结果是如何协作的——只看源码不动手永远停留在概念层。我的习惯是拿到任何跟踪类项目先跑通它自带的 demo再替换数据验证泛化性最后补上指标统计这三步走完才算真正把这份源码吃透。希望帮到你。本文还有配套的精品资源点击获取