Vision-Agents 接入 Inworld AI路由器 LLM/VLM、TTS-2 语音合成与 WebRTC 实时对话实战【免费下载链接】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-AgentsVision-Agents 的 Inworld AI 插件为语音与视觉 Agent 提供了三条能力通道通过 Inworld Realtime Router 代理 OpenAI / Anthropic / Google 等多上游的LLM/VLM 路由器、基于 TTS-2 模型的流式语音合成以及基于 WebRTC 的全双工实时语音对话。读完本文你将掌握该插件的安装方式、inworld.LLM/inworld.VLM的路由参数调优、TTS-2 自然语言导控steering标记语法以及如何用inworld.Realtime搭建低延迟语音 Agent。插件总览vision-agents-plugins-inworld是 Vision-Agents 官方插件体系中的一员仓库位于 plugins/inworld提供三个核心能力模块LLM / VLM通过 Inworld Realtime Router 代理 OpenAI、Anthropic、Google 等上游模型支持自动选路auto-selection、故障回退fallback与流量拆分traffic splitting走 OpenAI 兼容的/v1/chat/completions端点TTS高质量的流式文本转语音默认采用 InworldTTS-2模型research preview支持自然语言导控、100 语言与高质量即时声音克隆Realtime基于 WebRTCUDP 原生 Opus的语音到语音speech-to-speech对话面向低延迟语音 Agent 场景。四个公开入口类统一从vision_agents.plugins导出见 插件init.pyLLM、VLM、TTS、Realtime。安装与密钥配置uv add vision-agents[inworld] # 或直接安装插件包 uv add vision-agents-plugins-inworld安装后从 Inworld Portal 获取 API Key并写入环境变量export INWORLD_API_KEYyour_inworld_api_key所有组件都支持两种注入方式环境变量INWORLD_API_KEY或在构造时显式传入api_key参数。从源码看llm.py 与 tts.py 均采用api_key or os.getenv(INWORLD_API_KEY)的优先级策略TTS 与 Realtime 在两者都缺失时直接抛出ValueError提示配置错误。LLM / VLMInworld Realtime Router 文本与视觉对话inworld.LLM与inworld.VLM命中 Inworld 的 OpenAI 兼容/v1/chat/completions端点源码中基地址为https://api.inworld.ai/v1见 llm.py因此天然支持 OpenAI 的函数调用tools协议底层是对 openai 插件ChatCompletionsLLM/ChatCompletionsVLM的薄封装llm.py、vlm.py。model 参数的三种形态路由器的model参数接受inworld/router-id—— 在 Inworld 门户中配置的路由器 IDprovider/model-id—— 直接指定上游供应商与模型例如openai/gpt-4o-mini、google-ai-studio/gemini-2.5-flashauto—— 由 Inworld 服务端自动选路可配合sort_by决定排序维度。LLM 最小示例低延迟路由 回退链from vision_agents.plugins import inworld # Lowest-latency routing with a small fallback chain llm inworld.LLM( modelauto, sort_by[latency], ttft_timeout500ms, fallback_models[openai/gpt-4o-mini, google-ai-studio/gemini-2.5-flash], )VLM 视觉示例帧走 image_url视觉能力通过 OpenAI 标准的image_url内容片段把缓冲的视频帧发给路由后的上游视觉模型from vision_agents.plugins import inworld # Vision over the router (frames sent as image_url content). # Tuned for low-latency video QA: small frames, short buffer, fast fallback. vlm inworld.VLM( modelauto, sort_by[latency], ttft_timeout500ms, fallback_models[google-ai-studio/gemini-2.5-flash, openai/gpt-4o-mini], fps1, frame_buffer_seconds3, frame_width512, frame_height384, )端到端示例分别位于 example/inworld_llm_example.py语音 Agent与 example/inworld_vlm_example.py视频问答 Agent。后者演示了把inworld.VLM作为 Agent 大脑、配合deepgram.STT()与inworld.TTS()搭建看着摄像头回答口语问题的完整 Agent。底层实现路由参数如何进入请求体LLM/VLM构造后路由参数会被build_extra_body()llm.py组装成extra_body随每次请求发送。映射关系如下fallback_models→body[models]回退链ignore_models→body[ignore]从 auto 选路中排除sort_by→body[sort]排序维度数组ttft_timeout→body[fallback][ttft_timeout]metadata→body[metadata]web_search/web_search_options→body[web_search]/body[web_search_options]extra_body原始逃生舱→ 最后合并覆盖上述字段。而compression_aggressiveness不走 extra_body而是通过inject_compression()llm.py把{compression: {aggressiveness: x}}就地注入到消息列表的第一条system消息上。值得注意的一个工程细节Inworld 网关对低于 500ms 的ttft_timeout会返回 502Upstream server unavailable而不是参数校验错误。为避免第一次请求就遭遇 502 风暴插件在客户端做了前置校验llm.py构造时ttft_timeout低于 500ms 会直接抛出ValueError错误信息清晰说明原因。路由参数详解fallback_models有序列表主模型失败时按顺序尝试。ignore_models从auto选路中排除的模型列表。sort_by可选值price、latency、throughput、intelligence、math、coding传入多个维度时按顺序作为主键与平局决胜tiebreaker排序。ttft_timeout首 token 超时后切换回退模型Inworld 网关下限为300ms插件强制下限为500ms500ms、1s等格式由ttft_timeout_to_ms()正则解析llm.py。metadata自由格式字典供路由器的 CEL 表达式做条件路由例如{tier: premium}。web_search/web_search_options可选的上游网页搜索 grounding。compression_aggressiveness0–1Inworld 对系统消息的提示词压缩强度可削减输入 token、降低长提示的 TTFT。extra_body原始逃生舱最后合并进请求体覆盖上述辅助参数。tools_max_rounds多跳工具调用的最大轮数默认 3见 llm.py。缓存OpenAI / DeepSeek / Gemini-2.5 上游的隐式提示缓存是自动的无需任何代码。显式缓存Anthropic / Google 的 cache_control是逐消息的需要在消息内容里自行添加cache_control块例如{type: text, text: ..., cache_control: {type: ephemeral}}路由器定义本身router ID、A/B 变体、流量权重都在 Inworld 门户中配置超出本插件职责范围。为视频 QA 调低延迟VLM 专项视频问答的延迟主要由输入 token帧的代价远高于文本与上游选路决定。README 与 example/inworld_vlm_example.py 给出的默认起点如下frame_width512, frame_height384—— 相比 800×600 默认值减少约 4 倍字节数对常规问答场景准确率损失可忽略同时降低 JPEG 编码成本、请求带宽与上游输入 token 成本frame_buffer_seconds3搭配fps1—— 每个请求只带最近 3 帧。更长的缓冲会以平方级膨胀输入 token却对短时域问题毫无帮助sort_by[latency]ttft_timeout500ms 快速视觉模型的回退链如google-ai-studio/gemini-2.5-flash、openai/gpt-4o-mini—— 在某个供应商降级时仍能维持可预期的 TTFT。何时选择哪种方案语音 Agent→inworld.RealtimeWebRTC 全双工延迟最低。对于 STT→LLM→TTS 流水线文本路由器无法在延迟上胜过全双工音频。文本 Agent、STT→LLM→TTS 流水线、视频问答→inworld.LLM/inworld.VLM。LLM 示例中还演示了一个客户端侧的轮换选路技巧RotatingInworldLLM子类example/inworld_llm_example.py在每轮对话随机挑选主模型并把其余模型作为该轮回退模拟门户中的加权变体路由同时通过edge.send_custom_event把router.model广播给前端做可视化。TTS流式语音合成与 TTS-2 自然语言导控插件默认使用 InworldTTS-2模型目前处于 research preview相比上一代inworld-tts-1.5-*新增了自然语言导控、100 语言15 个 GA、90 实验性与高质量即时声音克隆。基础用法与参数from vision_agents.plugins import inworld # Defaults to model_idinworld-tts-2, voice_idSarah tts inworld.TTS() # Or specify explicitly tts inworld.TTS( api_keyyour_inworld_api_key, voice_idAshley, model_idinworld-tts-2, temperature1.1, )TTS 选项api_keyInworld AI API Key默认读取INWORLD_API_KEY环境变量voice_id语音默认Sarah同时支持Dennis、Ashley、Olivia、Clive以及自定义/克隆语音model_idinworld-tts-2默认、inworld-tts-1.5-max、inworld-tts-1.5-mini。inworld-tts-1与inworld-tts-1-max已被 Inworld 废弃请迁移到inworld-tts-2或inworld-tts-1.5-*temperature0–2默认 1.1源码中还有sample_rate默认 16000 Hz、speaking_rate0.5–1.5 倍速None 表示服务端默认、auto_mode是否由 Inworld 决定最优 flush 行为默认 True、apply_text_normalization文本归一化开关等进阶项见 tts.py。流式音频的底层实现InworldTTS基于wss://api.inworld.ai/tts/v1/voice:streamBidirectional的双向 WebSockettts.pystreaming True每次合成通过create→send_text→flush_context→close_context的上下文协议完成音频按PCMLINEAR1616-bit分块返回每个分块自包含、在流式场景下可干净解码无需额外配置。实现上还有几个值得注意的健壮性细节60 秒保活循环KEEPALIVE_INTERVAL_SECONDS 60仅在存在活跃上下文时发送空send_text避免Context not found污染下一次合成的接收流tts.py连接断开自动重连stream_audio()捕获WebSocketException/OSError后重置连接并重发tts.py按contextId过滤陈旧帧丢弃已关闭上下文的迟到音频遇到max contexts limit reached时自动重置 WebSockettts.pystop_audio()通过递增 generation 与发送close_context立即终止在途合成且避免重复关闭上下文触发服务端错误帧。集成测试覆盖了文本转音频与流式中途停止后继续合成两条路径tests/test_tts.py可作为接入参考。Steering 导控TTS-2TTS-2 接受与文本内联的自然语言舞台指示natural-language stage directions而非固定枚举标签。把指示放在方括号内、置于其作用段之前text ( [whisper in a hushed style] I have to tell you something. [laugh] Just kidding! [say with force] Now lets get to work. ) async for chunk in await tts.stream_audio(text): ...Steering 覆盖发音articulation、语调intonation、音量、音高、音域、语速与嗓音风格并支持[laugh]、[breathe]、[clear throat]、[sigh]、[cough]、[yawn]等非语言声音。组合多个维度如[whisper in a hushed style]、[say playfully and very fast]比裸单词标签效果更好。完整参考见 Inworld 的 steering 文档与 prompting 指南。配套的 example/inworld-audio-guide.md 是一份可直接用作系统提示的TTS-2 音频标记规则包含分层指示示例[say sadly with deliberate pauses in a low voice and hushed style] Im sorry, that didnt work.八类导控维度情感[say excitedly]、发音[say with force]、语调[say with a falling pitch]、音量[very quiet]、音高[say in a low tone]、音域[say playfully]、语速[very fast]、嗓音风格[whisper in a hushed style]非语言声音的插入位置规则[laugh]放在真正有趣的内容之后、[clear throat]放在更正或重要声明之前、[sigh]表达无奈/如释重负/共情每条回复 0–2 个即可响应生成五条规则有情感转变就带头放一个导控、非语言声音内联插入、导控与内容匹配、组合维度获得更细腻表现、保持克制短回复不超过 3 个标签关键警告[happy]/[sad]/[whispering]是 TTS-1 的写法对 TTS-2 无效要写成[say happily]、[say sadly]、[whisper in a hushed style]不要组合矛盾方向[whisper][very loud]也不要让导控与内容冲突在哀悼场景用[say excitedly]会显得讽刺。Agent 示例完整的inworld.TTS()接入示例位于 example/inworld_tts_example.py它把inworld.TTS()接入 Stream 边缘 Agent配合 Deepgram STT、Gemini LLM 与智能打断检测。关键点在于系统提示里写入Read inworld-audio-guide.md让 LLM 学会在回复中自动输出 TTS-2 steering 标签从而让输出开口即带表现力。RealtimeWebRTC 全双工语音对话inworld.Realtime通过 Inworld Realtime API 实现低延迟语音到语音对话。该传输使用WebRTCUDP、原生 Opus延迟低于 WebSocket 方案但要求配套 WebRTC 能力的边缘传输——示例中与getstream.Edge()配对使用。最小 Agent 示例from vision_agents.core import Agent, User from vision_agents.plugins import getstream, inworld, smart_turn agent Agent( edgegetstream.Edge(), agent_userUser(nameMy Agent, idagent), llminworld.Realtime( modelopenai/gpt-4o-mini, voiceDennis, instructionsYou are a friendly voice assistant., ), turn_detectionsmart_turn.TurnDetection(), )Realtime 参数model供应商前缀模型 ID例如openai/gpt-4o-mini默认、google-ai-studio/gemini-2.5-flash或inworld/router-id指定 Inworld 路由器voice音频回复的语音默认DennisClive、Olivia及自定义语音也支持api_keyInworld API Key默认读取INWORLD_API_KEYinstructions系统提示词realtime_session进阶逃生舱——传入完整的RealtimeSessionCreateRequestParam以设置主参数未暴露的会话字段自定义打断检测、tool_choice等force_tool_calling跳过计划是否允许工具调用的 REST 预检见下方说明。底层连接原理从 rtc_manager.py 可以看出 Realtime 的完整握手链路预取 ICE/TURN 服务器Inworld 的媒体中继位于 NAT 之后ICE 候选中是私网 IP没有服务端下发的 TURN 凭据无法建立连接因此connect()首先 GEThttps://api.inworld.ai/v1/realtime/ice-servers拉取 TURN/STUNrtc_manager.py建连并交换 SDP创建RTCPeerConnection、注册名为oai-events的有序数据通道、加入上行音频轨然后 POST 本地 SDP offer 到https://api.inworld.ai/v1/realtime/callsrtc_manager.py数据通道下发 session.updateInworld 服务器会忽略信令体session对象中的大部分字段model、voice、instructions、tools 均回退默认配置必须在数据通道打开后通过session.update事件应用。inworld_realtime.py 中的connect()正是发送session.update并等待session.updated确认超时 10 秒后才返回保证调用方拿到的是完全配置好的会话。事件处理采用防御性.get()读取而非严格的 pydantic 校验因为 Inworld 的事件 schema 存在漂移例如response.done用text/audio而 OpenAI 期望input_text/output_text用户转写事件缺少usage字段见 inworld_realtime.py 的注释说明。注册工具realtime inworld.Realtime() realtime.register_function(descriptionGet the current weather for a city.) async def get_weather(city: str) - str: return fIts sunny in {city}.工具遵循 OpenAI 函数调用 schema。Inworld Realtime API 与 OpenAI Realtime API 协议兼容注册的函数走同一条response.function_call_arguments.done路径执行工具参数分片argument_parts汇聚后由parse_tool_arguments解析并执行结果通过conversation.item.createfunction_call_outputresponse.create回传触发模型续说inworld_realtime.py。插件还内置了一个聪明的计划预检Inworld 的 Realtime API 在工具受限的计划下会对每个响应静默返回server_error导致 Agent 完全无法回复。_plan_supports_tool_calling()用一次携带占位工具的 REST 预检400 且消息含Tool calling is currently restricted来探测计划权限受限时自动剥离工具保住会话可用性inworld_realtime.py。若你确认计划支持工具例如刚充值可用force_tool_callingTrue跳过预检。完整的 Realtime 示例见 example/inworld_realtime_example.py深夜脱口秀主持人快速问答场景以及带工具调用的 example/inworld_realtime_tools_example.py。注意事项v1 仅支持 WebRTCWebSocket 传输可能后续加入Inworld Realtime API 目前不支持视频输入——watch_video_track()在源码中是显式 no-opinworld_realtime.py。依赖与运行要求插件要求 Python 3.10核心依赖见 pyproject.tomlhttpx0.28.1websockets14.0aiortc1.9openai[realtime]2.26,3同时依赖vision-agents与vision-agents-plugins-openaiLLM/VLM 封装的基础运行各示例前需要设置的环境变量INWORLD_API_KEY必须STREAM_API_KEY/STREAM_API_SECRET接入getstream.Edge()必需DEEPGRAM_API_KEY使用deepgram.STT()的语音示例必需集成测试位于 plugins/inworld/tests其中test_llm.py、test_realtime.py、test_tts.py均以INWORLD_API_KEY存在为前提缺失时自动 skip可作为回归验证与行为参考。【免费下载链接】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），仅供参考