1. 从零搭建 YOLOv8 人体检测项目数据集准备与训练踩坑记录行人检测这件事说简单也简单yolov8n.pt直接推理就能框出人说难也难真要做到遮挡场景不漏检、密集人群不粘连、夜间逆光不误报就得自己准备数据集、微调模型、再配一套能落地的界面。我这次做的项目目标很明确一套能在 Windows 和 Linux 上跑起来的 YOLOv8 人体检测与行人识别系统带 PyQt5 图形界面支持图片、文件夹、视频、摄像头四种输入训练和推理流程全部打通最后再通过 TaoToken 的统一 API 通道把推理服务接出去方便后续做多端调用。这套东西适合谁如果你是刚学完 YOLOv8 官方教程、想找一个完整工程练手的同学或者你手头有个安防监控、人数统计的小需求不想从零写界面那这个项目结构可以直接拿去改。核心检索词就三个YOLOv8 人体检测、PyQt5 可视化界面、行人识别训练流程。下面我按实际搭建顺序讲每一步都给可复制的命令和配置。先说环境。我实测下来比较稳的组合是 Python 3.10 PyTorch 2.1 ultralytics 8.1.x。装的时候注意ultralytics 会自动拉 torch但如果你机器上有 CUDA建议先手动装对应版本的 torch不然它可能给你装 CPU 版训练时你会发现 loss 降得慢得离谱。命令如下conda create -n yolov8_ped python3.10 -y conda activate yolov8_ped pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics8.1.0 opencv-python pyqt5装完先验证一下 GPU 是否可用import torch print(torch.cuda.is_available(), torch.cuda.get_device_name(0))如果输出True和你的显卡型号说明环境没问题。这一步踩过的坑是有些同学用 pip 装完 torch 后cuda.is_available()返回 False多半是驱动版本和 CUDA 版本不匹配去 NVIDIA 官网对一下驱动支持的 CUDA 上限就行。数据集这块行人检测常用的公开集有 CrowdHuman、Caltech Pedestrian、CityPersons。我这次用的是 CrowdHuman 的一个子集加上自己标注的一部分监控截图总共约 8000 张。YOLO 格式的目录结构必须严格按下面来不然训练时会报找不到标签dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/每张图对应一个同名.txt内容格式是类别 x_center y_center width height坐标全部归一化到 0-1。行人检测通常只有一个类别所以类别 id 就是 0。比如一张图里有两个行人标签文件长这样0 0.5096721233576642 0.352838390077821 0.3947600423357664 0.31825755058365757 0 0.3124501233576642 0.552838390077821 0.2147600423357664 0.41825755058365757标注工具我用的是 labelImg导出时选 YOLO 格式即可。注意一点如果图片里有大量小目标行人建议把img_size设到 960 或 1280640 会丢很多细节。数据集划分比例我一般用 8:2验证集至少留 500 张不然 mAP 波动很大看不出真实效果。训练配置文件我单独写了一个pedestrian.yaml放在项目根目录path: ./dataset train: images/train val: images/val nc: 1 names: [person]然后启动训练。我实测下来YOLOv8n 在 8000 张图上跑 100 epoch单卡 3060 大概 2 小时出头yolo detect train datapedestrian.yaml modelyolov8n.pt epochs100 batch16 imgsz640 lr00.001 patience20这里有几个参数值得说。patience20是早停验证集 20 轮不提升就停省时间。lr00.001是初始学习率如果你用预训练权重微调这个值比较合适如果从yolov8n.yaml从头训可以调到 0.01。batch16看显存3060 12G 跑 640 没问题跑 1280 就得降到 8。训练过程中你会看到三类 lossbox_loss定位损失、cls_loss分类损失、dfl_loss动态特征损失。正常情况下三个都应该是下降趋势。如果cls_loss一直不降多半是标签类别写错了如果box_loss震荡厉害检查一下标注框有没有越界或者宽高为 0 的情况。训练完成后结果都在runs/detect/train/下。重点看三个文件results.png是 loss 和 mAP 曲线weights/best.pt是最佳权重confusion_matrix.png是混淆矩阵。我这次跑下来 mAP0.5 到了 0.91mAP0.5:0.95 在 0.63 左右对于行人单类检测来说够用了。如果 mAP0.5 低于 0.85建议先别急着调模型回头查数据集标注质量十有八九是标注问题。2. TaoToken 统一 API 通道接入前的准备工作模型训好了本地推理也跑通了接下来要解决的是怎么让别的系统也能调用这个检测能力。传统做法是自己写个 Flask 服务但涉及到多模型切换、Key 管理、限流这些事维护成本不低。我这次用的是 TaoToken 的统一 API 通道它把模型调用统一成一个入口你只需要拿一个 Key就能通过标准接口访问推理服务省去了自己搭网关的麻烦。先说清楚 TaoToken 是什么、能做什么。它是一个面向开发者的模型 API 聚合平台提供统一的 Key 和 API 地址支持对话模型、代码模型等多种能力调用。对于这个行人检测项目来说它的价值在于你可以把 YOLOv8 的推理结果或者相关的文本处理逻辑通过统一接口接出去比如检测到行人后自动生成告警描述、调用视觉理解模型做二次确认等。适合谁用适合不想自己维护多套 API 对接、希望一个 Key 走通的开发者。前置准备分三步。第一步注册并登录 TaoToken 官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步进入控制台创建 API Key控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第三步把 Key 保存到环境变量里别硬编码在代码中。创建 Key 的时候注意TaoToken 的 Key 一般以sk-开头复制后只显示一次丢了就得重新生成。我建议在项目根目录建一个.env文件TAOTOKEN_API_KEYsk-你的实际key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里用python-dotenv读取import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(TAOTOKEN_API_KEY) base_url os.getenv(TAOTOKEN_BASE_URL) print(base_url)这里要强调一个点Base URL 是https://taotoken.net/api不要加 UTM 参数也不要自己拼/v1之类的路径具体路径以官方文档为准。文档地址在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入前先扫一眼接口说明避免路径写错导致 404。如果你用的是 Claude Code 这类编码工具TaoToken 也提供了对应的接入方式入口在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不过对于这个行人检测项目我们主要用的是通用 API 通道下面第三节会给完整的配置片段。还有一个准备工作是确认你的网络能正常访问 API 地址。我实测下来直接在 Python 里发一个最简单的请求就能验证import requests headers { Authorization: fBearer {api_key}, Content-Type: application/json } resp requests.get(f{base_url}/models, headersheaders, timeout10) print(resp.status_code, resp.text[:200])如果返回 200说明 Key 和地址都没问题。如果返回 401检查 Key 是否复制完整如果返回 404检查 Base URL 是否写成了https://taotoken.net/api而不是别的路径。这一步别跳过很多后续报错都是因为前置没验证。3. 可复制的配置片段YOLOv8 推理服务对接 TaoToken这一节给可直接复制的配置。我按三种场景来Python 脚本调用、JSON 配置文件、以及 PyQt5 界面里的设置项。所有片段里的 Base URL、Key、Model ID 三件套都写全你替换成自己的就行。先说 Python 侧的配置。我建了一个config.py把 TaoToken 相关参数集中管理# config.py import os from dotenv import load_dotenv load_dotenv() TAOTOKEN_CONFIG { base_url: https://taotoken.net/api, api_key: os.getenv(TAOTOKEN_API_KEY, ), model_id: gpt-4o-mini, # 按实际可用模型填写 timeout: 30, max_retries: 3 } YOLO_CONFIG { weights: runs/detect/train/weights/best.pt, conf_threshold: 0.25, iou_threshold: 0.45, img_size: 640 }注意model_id这一项不同平台可用的模型名称不一样具体以 TaoToken 文档里的模型列表为准。我写gpt-4o-mini只是示例你接入前先去文档页确认。然后是 JSON 配置文件适合给 PyQt5 界面读取用户可以在界面上改{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-替换成你的key, model_id: gpt-4o-mini, timeout: 30 }, yolo: { weights: runs/detect/train/weights/best.pt, conf: 0.25, iou: 0.45, imgsz: 640 }, ui: { save_dir: ./outputs, show_labels: true, line_width: 2 } }把这个存成settings.jsonPyQt5 启动时加载。界面上可以放几个输入框让用户改conf和iou改完写回 JSON。接下来是实际的 API 调用封装。我写了一个taotoken_client.py用requests发请求带重试逻辑# taotoken_client.py import requests import time from config import TAOTOKEN_CONFIG class TaoTokenClient: def __init__(self, configNone): self.cfg config or TAOTOKEN_CONFIG self.base_url self.cfg[base_url].rstrip(/) self.headers { Authorization: fBearer {self.cfg[api_key]}, Content-Type: application/json } def chat(self, messages, modelNone): url f{self.base_url}/chat/completions payload { model: model or self.cfg[model_id], messages: messages, temperature: 0.3 } last_err None for attempt in range(self.cfg[max_retries]): try: resp requests.post( url, headersself.headers, jsonpayload, timeoutself.cfg[timeout] ) if resp.status_code 200: return resp.json() last_err fHTTP {resp.status_code}: {resp.text[:200]} except requests.RequestException as e: last_err str(e) time.sleep(1.5 * (attempt 1)) raise RuntimeError(fTaoToken 调用失败: {last_err})这个类可以直接在 PyQt5 的检测回调里用。比如检测到行人后把检测结果拼成一段文字调用chat生成告警描述client TaoTokenClient() messages [ {role: system, content: 你是一个安防告警助手根据检测结果生成简短描述。}, {role: user, content: 画面中检测到 3 个行人位置在画面左侧和中央置信度分别为 0.92、0.88、0.85。} ] result client.chat(messages) print(result[choices][0][message][content])如果你用的是 Cline 或者 MCP 类的工具做辅助开发配置方式类似核心还是 Base URL、Key、Model ID 三件套。Cline 的 MCP 配置里把 API 地址填https://taotoken.net/apiKey 填你的sk-开头字符串模型名按文档填。Codex 的auth.json也是同样逻辑三个字段对齐就行。PyQt5 界面里我建议把 TaoToken 配置做成一个独立的设置对话框用户点设置按钮弹出填完保存到settings.json。这样即使换 Key 也不用改代码。界面主逻辑里检测按钮触发 YOLO 推理推理完把结果传给 TaoToken 客户端做二次处理整个链路就通了。4. 验证请求与成功结果从本地推理到 API 连通性测试配置写完了得验证两件事一是 YOLOv8 本地推理是否正常二是 TaoToken API 是否连通。这两步分开测别混在一起不然出问题不好定位。先测本地推理。写一个test_yolo.pyfrom ultralytics import YOLO import cv2 model YOLO(runs/detect/train/weights/best.pt) results model(test_images/pedestrian_01.jpg, conf0.25, saveTrue) for r in results: boxes r.boxes print(f检测到 {len(boxes)} 个目标) for box in boxes: cls_id int(box.cls[0]) conf float(box.conf[0]) xyxy box.xyxy[0].tolist() print(f 类别{cls_id}, 置信度{conf:.3f}, 坐标{[round(v,1) for v in xyxy]}) save_path results[0].save_dir / results[0].path.name img cv2.imread(str(save_path)) cv2.imshow(Detection, img) cv2.waitKey(0) cv2.destroyAllWindows()跑通后你应该看到终端打印出检测到的目标数量和坐标同时弹出一张带框的图。如果图里人框得很准说明权重没问题。如果框歪了或者漏检先调conf参数从 0.25 降到 0.15 试试再不行就得回头查训练数据。然后测 TaoToken API 连通性。写一个test_taotoken.pyfrom taotoken_client import TaoTokenClient client TaoTokenClient() messages [ {role: user, content: 请回复连通性测试成功} ] try: result client.chat(messages) content result[choices][0][message][content] print(API 返回:, content) print(连通性验证通过) except Exception as e: print(验证失败:, e)成功的话终端会打印出模型返回的内容。我实测下来正常情况下 2 秒内就有响应。如果超时先检查网络再检查base_url是否写对。注意base_url结尾不要带斜杠代码里已经做了rstrip(/)处理但你自己拼 URL 的时候要注意。两个测试都通过后做一次联合验证用 YOLO 检测一张图把检测结果转成文字发给 TaoToken 生成描述最后把描述显示在 PyQt5 界面的文本框里。这一步跑通说明整条链路没问题。联合验证的代码片段from ultralytics import YOLO from taotoken_client import TaoTokenClient model YOLO(runs/detect/train/weights/best.pt) client TaoTokenClient() results model(test_images/crowd.jpg, conf0.25) boxes results[0].boxes count len(boxes) prompt f画面中检测到 {count} 个行人。 if count 0: confs [round(float(b.conf[0]), 2) for b in boxes] prompt f置信度分别为 {confs}。请生成一句简短的安防告警描述。 resp client.chat([{role: user, content: prompt}]) print(resp[choices][0][message][content])跑通后你会看到类似检测到 5 个行人建议关注画面中央区域这样的输出。到这一步YOLOv8 人体检测 PyQt5 界面 TaoToken API 接入的完整闭环就打通了。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列我实际遇到过的报错和解决办法。你按报错信息对号入座就行。401 Unauthorized。这个最常见九成是 Key 问题。先检查.env里的TAOTOKEN_API_KEY是不是完整的sk-开头字符串有没有多余空格。然后检查请求头是不是Authorization: Bearer sk-xxx注意Bearer后面有一个空格。如果 Key 确认没问题还是 401去控制台看看 Key 是不是被禁用或者过期了。控制台地址在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去重新生成一个再试。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或者端口不对。解决办法是检查环境变量HTTP_PROXY和HTTPS_PROXY如果不需要代理就清掉unset HTTP_PROXY unset HTTPS_PROXYWindows 上用set HTTP_PROXY清空。清完重启终端再跑。注意这里说的是本地开发环境的代理配置问题不是让你去搞什么网络工具纯粹是排查环境变量干扰。reading choices 报错。这个一般出现在解析 API 返回时result[choices]取不到值。原因通常是返回结构和你预期的不一样。先打印完整返回看看import json print(json.dumps(result, ensure_asciiFalse, indent2))如果返回里有error字段按错误信息处理。如果choices是空列表可能是模型没返回内容检查messages格式对不对必须是[{role: user, content: ...}]这种结构。还有一种情况是model_id填错了平台找不到对应模型返回结构里就没有choices。OAuth 相关报错。如果你用的是 Claude Code 或者类似工具接入可能会遇到 OAuth 认证失败。这种情况检查两点一是工具里的 API 地址是不是填的https://taotoken.net/api二是认证方式选的是 API Key 而不是 OAuth。有些工具默认走 OAuth 流程你需要手动切到 Key 模式。Claude Code 的接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 照着配就行。YOLO 侧常见报错。FileNotFoundError: labels/train/xxx.txt说明标签文件缺失或者路径不对检查pedestrian.yaml里的path是不是指向数据集根目录。CUDA out of memory就把batch调小或者把imgsz从 640 降到 416。No module named ultralytics说明环境没激活conda activate yolov8_ped再跑。PyQt5 界面卡死。检测视频或摄像头时如果在主线程里跑推理界面会卡住。解决办法是把推理放到QThread里通过信号槽更新界面。这个坑我踩过改成多线程后流畅很多。排查顺序建议先确认本地 YOLO 推理正常再确认 TaoToken 单独调用正常最后测联合链路。哪一步出问题就查哪一步别跳步。6. 长期编码与 Agent 场景用 Coding Plan 把检测能力接进工作流项目跑通之后如果你打算长期迭代比如加目标追踪、行人再识别、异常行为分析那单次调用 API 的方式就不太够用了。这时候可以考虑 TaoToken 的 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它适合长期编码和 Agent 类场景简单说就是你把检测服务当成一个工具让编码助手或者 Agent 在开发过程中直接调用省去反复手动测试的环节。具体到这个项目你可以这样用把 YOLOv8 的推理封装成一个函数注册到 Agent 的工具列表里然后让 Agent 根据你的自然语言指令去调用。比如你说帮我测一下 test_images 文件夹里所有图片的检测结果把漏检的挑出来Agent 就会自动遍历文件夹、调用推理、对比结果、生成报告。这比你自己写脚本快得多。接入方式还是老三样Base URL 填https://taotoken.net/apiKey 填你的sk-开头字符串Model ID 按文档填。Coding Plan 的配置和普通 API 调用基本一致区别在于它针对长上下文和工具调用做了优化适合多轮交互。如果你只是想快速验证模型效果不想写代码可以用模型对话入口地址在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 直接在网页上试。不过对于行人检测这种需要传图的任务还是走 API 更灵活。最后给一个实用建议把settings.json里的conf和iou做成可调参数不同场景用不同值。比如安防监控场景conf可以设 0.3 减少误报人数统计场景conf设 0.15 减少漏检。这个参数没有万能值得根据你的实际画面调。我一般会准备三套配置high_recall.json、balanced.json、high_precision.json切换着用。项目结构建议保持清晰yolov8_pedestrian/ ├── dataset/ ├── runs/detect/train/weights/best.pt ├── config.py ├── settings.json ├── taotoken_client.py ├── main.py ├── ui_main.py ├── test_yolo.py └── test_taotoken.py这样后续加功能的时候改哪块一目了然。训练新权重就替换best.pt换 API Key 就改.env调界面就动ui_main.py互不影响。