5 分钟搭一个实时高尔夫挥杆教练：Vision-Agents 的 YOLO 姿态检测 + 实时多模态 LLM

5 分钟搭一个实时高尔夫挥杆教练Vision-Agents 的 YOLO 姿态检测 实时多模态 LLM【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents想做一个边看你挥杆、边开口点评的语音视觉智能体吗开源框架 Vision-Agentsagents-core/里有一类很实用的组合拳用轻量 CV 处理器YOLO 姿态检测在本地实时给视频叠加骨骼标注再把处理后的画面喂给支持视频输入的实时 LLMGemini Realtime / OpenAI Realtime由模型语音播报改进建议。本文以 examples/02_golf_coach_example/ 为主线带你从整条数据链路讲到源码机制读完你能把这套处理器 实时视觉 LLM模式改造成健身、康复或体育训练场景的自己的版本。先看清链路一次挥杆点评经过哪些环节把 golf_coach_example.py 跑起来后一帧画面和一句反馈是这样流动的入轨浏览器摄像头视频经 Stream 边缘网络getstream.Edge()进入通话Agent 为每条视频轨订阅并包上VideoForwarder见 agents.py 中_on_track_added本地姿态检测YOLOPoseProcessoryolo_pose_processor.py从共享 forwarder 按自己设定的 fps 抽帧在线程池里跑 YOLO pose 推理画出关键点、骨骼连线和高亮手腕写入自己的输出轨QueuedVideoTrack实时 LLM 看视频gemini.Realtime(fps3)通过watch_video_track()接收处理器输出轨带骨骼标注的画面逐帧转 PNG 后以Blob形式发给 Gemini Live APIgemini_realtime.py 的_send_video_frame语音闭环实时 LLM 内部同时处理语音识别与语音合成——Agent在_validate_configuration里检测到 Realtime LLM 后会自动置空stt/tts/turn_detection并给出警告所以示例里根本不需要单独的 STT/TTS 插件输出模型按 golf_coach.md 中的人格设定苏格兰口音、有点毒舌开口点评经边缘网络播回通话。换句话说这个架构的分工是便宜的模型在本地做逐帧像素级工作贵的大模型只看它需要看的语义信息——LLM 看到的画面里骨骼已经画好它不必自己从原始像素里推断身体姿态。快速上手装依赖、配 Key、一条命令运行前置条件Python ≥ 3.13pyproject.toml 声明requires-python 3.13三个 API KeyGemini实时 LLM、Stream音视频基础设施若改用 OpenAI Realtime 则再准备一个OPENAI_API_KEY安装示例目录自带 uv 工作区五个本地包都以 editable 路径指向仓库内源码cd examples/02_golf_coach_example uv sync配置在同目录新建.envGEMINI_API_KEYyour_gemini_key STREAM_API_KEYyour_stream_key STREAM_API_SECRETyour_stream_secret运行uv run golf_coach_example.py runAgent 会创建通话、在浏览器打开演示 UI 并加入先说一声你好然后等你挥杆入口逻辑在join_callagent.create_call→agent.join(call)→simple_response→agent.finish()。首次运行时 YOLO 权重文件不存在Ultralytics 会自动下载_load_model里有对应 warning 日志。核心走读Agent 装配与 YOLOPoseProcessor 参数整个入口只有两个函数。create_agent的装配方式值得逐行看agent Agent( edgegetstream.Edge(), # 低延迟音视频传输 agent_userUser(nameAI golf coach), instructionsRead golf_coach.md, # 语法内联 markdown 指令文件 llmgemini.Realtime(fps3), # 实时多模态 LLM3 帧/秒 processors[ultralytics.YOLOPoseProcessor(model_pathyolo26n-pose.pt)], )其中instructionsRead golf_coach.md并不是字面量提示词框架的指令解析器instructions.py会用filename模式匹配并把文件内容拼进完整指令这样可以把几百字的教练守则独立成文件维护。再看处理器本体。YOLOPoseProcessor继承VideoProcessorPublisher基类在 base_processor.py意味着它既吃入向轨、又吐输出轨。构造函数参数以源码签名为准参数默认值说明model_pathyolo26n-pose.ptYOLO 权重文件缺失时自动下载conf_threshold0.5关键点置信度阈值低于该值的点不画imgsz512推理输入尺寸当前调用处未启用源码中已注释devicecpuCPU / CUDA 推理max_workers24姿态推理线程池大小fps30处理器自身抽帧速率enable_hand_trackingTrue额外绘制 21 点手部骨架连线enable_wrist_highlightsTrue手腕关键点画红色大圆点并标注 R/L Wrist小提示插件 README 里写的max_workers默认值是 2与源码默认的 24 不一致以 yolo_pose_processor.py 为准。推理是 CPU 密集型任务源码用loop.run_in_executor丢进线程池执行并套了asyncio.wait_for(..., timeout12.0)——单帧超过 12 秒直接放弃并返回原帧保证视频管线不因一帧卡死。close()时会置_shutdown标志、移除帧处理器并关闭线程池。关键机制一条原始轨两个消费者谁优先这个示例最核心的设计藏在VideoForwarder的一对多分发里看两处源码就能理解处理器侧process_videoAgent 把入向轨的共享 forwarder 原样传进来处理器只注册一个_add_pose_and_add_frame回调self._video_forwarder shared_forwarder if shared_forwarder else VideoForwarder(...) self._video_forwarder.add_frame_handler(self._add_pose_and_add_frame, fpsfloat(self.fps), nameyolo)每个 handler 有独立的 fps 节流所以同一条原始轨可以被处理器按 30fps、LLM 按 3fps 各自消费互不阻塞。LLM 侧与优先级_setup_media_tracks会把处理器的输出轨注册进_active_video_tracks并标记priority2原始摄像头轨是priority0屏幕共享为 1见 agents.py。每当轨变化时_on_track_change会做两件事把所有VideoProcessor指向原始轨未经处理的然后把最高优先级轨——也就是带骨骼标注的处理结果——交给llm.watch_video_track()。推论很直接摄像头轨和标注轨都在场时Gemini 看的是标注版如果哪天你把processors列表清空LLM 会自动退回看原始画面。另外Realtime基类的fps默认只有 1realtime.py示例显式调到 3在响应速度和 token 成本之间取折中。自定义换 LLM、调帧率、改人设换 LLM 供应商gemini.Realtime(fps3)与openai.Realtime(fps3)接口兼容示例文件里就留了注释开关。两者都是 Realtime LLM都会自动禁用独立 STT/TTS。调帧率fps同时影响两处——LLM 每秒收到的画面数gemini_realtime.py的watch_video_track用它节流与成本。降到 1 更省提到 10 分析更细但费用更高。改教练人设编辑 golf_coach.md。文件前几行定义人格女性声音、苏格兰口音、略带毒舌、没看清就不评价后面是 12 节挥杆指南握杆、站位、挥杆序列、常见失误等。想改成健身或康复教练只需重写这份文件。换检测任务YOLOPoseProcessor换成ultralytics.YOLOProcessor(model_pathyolo11n.pt)可做通用物体检测换更重的 pose 权重或设置devicecuda提升推理速度关掉enable_hand_tracking可少画一半连线。加可观测性仓库还给了 golf_coach_with_metrics.py 变体——在 import vision_agents之前启动 Prometheus 服务端口 9464并挂上MetricsCollector运行后可在http://localhost:9464/metrics看到vlm.inferences、video.frames_processed、video.detections等实时指标。验证测试用例划定了哪些行为契约插件层测试在 test_ultralytics.py用仓库自带的挥杆图tests/test_assets/golf_swing.png驱动三个用例恰好对应YOLOPoseProcessor的三个入口 API测试用例入口断言的契约test_annotated_ndarrayadd_pose_to_ndarray输入 numpy 帧返回标注帧与pose数据persons列表test_annotated_image_outputadd_pose_to_imagePIL 进出尺寸保持不变test_annotated_frame_outputadd_pose_to_frameav.VideoFrame进出宽高一致且像素确实被修改标注生效值得注意的细节测试 fixture 用asyncio.to_thread构造处理器注释说明 YOLO 在__init__里会阻塞式检查系统版本close()保证线程池清理。如果你要基于这套模式开发这三个用例就是标注功能是否可用的最小验收标准。延伸把这套模式用到你自己的场景入门先看最简单的 examples/01_simple_agent_example/再回到本文的双组件结构examples/05_security_camera_example/ 展示了处理器 非实时 LLM 的异步分析路线可与本例的实时路线对照处理器抽象的完整定义在 agents-core/vision_agents/core/processors/VideoProcessor/VideoPublisher/VideoProcessorPublisher三种基类决定你能写哪类插件核心分发逻辑集中在 agents-core/vision_agents/core/agents/agents.py 的_on_track_change与VideoForwardervideo_forwarder.py改轨、换处理器、调 fps 都绕不开这两处。【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考