企业官网建设流程全解析

Vision-Agents 实战：用 Decart 插件把实时视频风格化接入语音 Agent

【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Stream's edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents

视频会议里，AI 智能体如果能直接重绘你的摄像头画面——你说一句"换成吉卜力动画风"，画面立刻跟着变；再补一句"给我穿件外套"，就是一次虚拟试装——整个通话不用切场景。这就是 Vision-Agents 的 Decart 插件要解决的事：它把 Decart 的生成式实时重绘 API 接进框架的处理器链路，RestylingProcessor接管用户视频轨道，把帧发给 Decart 重绘，再把结果发回通话，智能体还可以通过对话随时改风格、换参考图。

插件内部把 WebSocket 连接、帧队列、断线重连这些脏活都封装好了，业务代码只需要回答一个问题：什么时候、换成什么风格。本文从安装开始，讲完参数配置、对话换风格的实战写法，再拆开它的帧流转与容错逻辑，最后给一份避坑清单。

最快安装与启动：两行代码挂载实时重绘

插件要求 Python 3.10+，依赖vision-agents核心库和decart>=0.0.34,<0.0.36官方 SDK（见 plugins/decart/pyproject.toml）。装法二选一：

uv add "vision-agents[decart]" # 或者 uv add vision-agents-plugins-decart

能跑起来的最小例子：

from vision_agents.core import User, Agent from vision_agents.plugins import getstream, gemini, decart styled = decart.RestylingProcessor( initial_prompt="Studio Ghibli animation style", ) agent = Agent( edge=getstream.Edge(), agent_user=User(name="Studio Bot"), instructions="Be helpful", llm=gemini.Realtime(), processors=[styled], )

关键挂载点只有一个：processors=[styled]。用户加入通话并发布视频轨道时，框架自动走处理链路，你不需要手动管连接和帧搬运。RestylingProcessor继承自 base_processor.py 里的VideoProcessorPublisher，同时扮演两个角色：作为VideoProcessor接收原始轨道（实现process_video/stop_processing），作为VideoPublisher把重绘后的轨道发回通话（实现publish_video_track）。

插件必须拿到 Decart API Key，两种给法：环境变量DECART_API_KEY，或构造参数api_key="..."。源码里是"先取参数、再回退环境变量"，两者都没有时构造函数直接抛ValueError，所以别指望延迟到运行时才发现缺 key。

参数默认值说明：哪些不用动，哪些必须改

RestylingProcessor.__init__的全部参数（见 decart_restyling_processor.py）：

三个值得单独说清楚的行为：

• enhance是 prompt 的一部分，不是本地开关。连接时它和initial_prompt、initial_image一起装进ModelState下发；之后每次update_state也会带它（见 decart_restyling_processor.py 的_connect_to_decart与update_state）。
• initial_image支持五种形态：bytes、本地文件路径、http(s) URL、data URI、base64 字符串。源码里ImageInput = bytes | str | Path，字符串形式由 SDK 解析。
• width/height决定的是输出端：DecartVideoTrack按这个尺寸收帧，尺寸不符的帧会被自动缩放，而不是改模型输入。

实战：让 Agent 用一句话换风格、换服装

想让风格跟着对话走，就把更新接口注册成 LLM 工具（function calling，即让模型在对话中主动调用你定义的函数）：

@llm.register_function(description="把视频换成指定风格") async def apply_style(style_text: str) -> str: await styled.update_prompt(style_text) return "done"

update_prompt是update_state的快捷方式，只管 prompt。要同时换 prompt 和参考图，用update_state——一次调用把两项打包下发，画面不会出现"风格变了、服装没变"的中间态：

await styled.update_state( prompt="A person in a leather jacket", image="https://example.com/jacket-ref.png", )

完整可运行的"虚拟试装助手"在 plugins/decart/example/decart_example.py：COSTUMES字典预置了服装条目，每条对应一段 prompt 加一张参考图 URL；LLM 优先调change_costume(name)换预设服装，查不到再走change_outfit(description, image_url)的自由描述路径——有参考图 URL 就update_state，没有就退化成纯 prompt 的update_prompt。运行方式与所需 API Key 见 plugins/decart/example/README.md，uv run decart_example.py run起一个带浏览器演示页的通话。

两点补充：update_state要求prompt和image至少给一个，否则抛ValueError；如果此刻还没连上 Decart，调用会静默返回（不报错，但也不生效）。

帧是怎么流转的，断线后靠什么自愈

数据流按顺序走五步：

1. 用户发布视频轨道，框架回调process_video存入当前轨道，触发首次连接；连接进行中有_connecting标志加锁，重复调用不会二次建连。
2. RealtimeClient.connect通过 WebSocket 连上 Decart Realtime API，随连接下发初始状态（prompt +enhance+ 参考图），并注册connection_change与error两个事件。
3. Decart 开始回传重绘流后，_on_remote_stream回调启动收帧协程，循环recv()拉帧。
4. 每帧经DecartVideoTrack.add_frame做尺寸校验后写入一个容量为 2 的最新帧队列（VideoLatestNQueue），尺寸不符先缩放。
5. 通话侧从DecartVideoTrack.recv()取帧：最多等 33 毫秒（约 30fps 一帧的周期），超时就回吐上一帧并刷新 PTS，保证画面平稳不卡顿。

容错与清理同样有明确设计（实现见 decart_video_track.py）：

• 轨道构造时先生成一张深色占位帧，重绘帧没到达之前画面不黑。
• _should_reconnect只认两类"可恢复"错误：websockets.ConnectionClosedError，以及错误消息里含 "connection" / "disconnect" / "timeout" 的DecartSDKError。_on_error据此启动重连协程；_processing_loop再每秒轮询一次做兜底，事件驱动加轮询双保险。
• 参与者离开触发stop_processing断开连接；Agent 关闭时close()依次断开 Decart 连接、停止轨道、取消收帧/处理/重连三个后台协程、关闭DecartClient，不留悬挂任务。

⚠️ 重连只覆盖连接类错误。invalid api key这类配置错误不会触发自愈，得改完 key 重启进程。

避坑清单

• 部署场景统一用DECART_API_KEY环境变量注入，密钥别写进代码；
• update_state在未连接时是静默 no-op——想生效就得在用户加入、连接建立之后再调用；
• 参考图用本地路径时，路径相对运行目录解析，容器挂载点要对得上；
• width/height只影响发布端的缩放，别指望靠它改变模型输出分辨率；
• set_mirror只更新处理器本地的mirror标志，镜像表现取决于调用方如何使用该值，插件本身不会替你翻转画面。

【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Stream's edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents