TEN Framework 中 StepFun 多模态实时语音 Agent 扩展 stepfun_mllm_python 接入指南

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本篇技术指南围绕 TEN Framework 开源仓库中的stepfun_mllm_python扩展展开讲解如何将 StepFun阶跃星辰新一代多模态实时模型默认step-1o-audio以 WebSocket Realtime 协议的方式接入语音 Agent 应用实现语音进、语音出voice-to-voice与文本处理的端到端能力。读完本文你将掌握该扩展的完整配置项语义、manifest 属性契约、数据/命令接口、底层消息协议与源码实现路径并能够参照仓库中的 stepfun-demo 示例搭建可运行的多模态语音助手。扩展概览一个与 OpenAI Realtime 协议对齐的多模态语音扩展stepfun_mllm_python位于 ai_agents/agents/ten_packages/extension/stepfun_mllm_python 目录是一个标准的 TEN Framework Python 扩展extension版本号为0.2.2。从 extension.py 的类定义可以看到它继承自AsyncMLLMBaseExtension并在注释中明确说明其设计目标StepFun realtime provider, API-compatible with OpenAIRealtime2Extension: same public methods, same server event mapping → send_server_* APIs这意味着该扩展在 TEN 生态中扮演的是 MLLM多模态大模型Provider 的角色对外暴露与 OpenAI Realtime 扩展一致的公共方法与服务端事件映射凡是遵循ten_ai_base中mllm-interface约定的上游节点如转写模块、主控逻辑都可以无差别地对接 StepFun。核心特性按照 README.md 的说明该扩展提供三大特性StepFun 多模态集成支持将 StepFun 多模态模型用于语音到语音voice to voice以及文本处理高度可配置可通过属性灵活定制 API Key、模型、提示词、temperature 等参数异步队列处理基于 asyncio 的实时消息处理支持任务取消与优先级调度配合服务端 VAD 实现打断/优先响应。API 契约manifest 属性定义与默认值该扩展的 API 定义在 manifest.json 的api.property.properties中默认值则在 property.json 中给出。下表汇总了两者的完整对应关系PropertyType默认值Descriptionapi_keystring${env:STEPFUN_API_KEY}用于向 StepFun 认证的 API Keytemperaturefloat0.9采样温度值越高随机性越强modelstringstep-1o-audio模型标识符max_tokensint2048生成的最大 token 数system_messagestring未在 property.json 中设置见prompt发送给模型的默认系统消息voicestringlinjiajiejieStepFun 模型说话的语音如alloy、echo、shimmer等server_vadbooltrue是否启用 StepFun 服务端 VADlanguagestringen模型回复使用的语言如en-US、zh-CN等dumpboolfalse是否启用音频 dump 用于调试需要注意README 中的属性表描述的是接口语义而 manifest.json 中的 schema 是 TEN 运行时实际校验与注入的依据两者存在轻微差异如system_message在 schema 中以prompt字段出现。实际生效的完整配置集合以源码中StepFunRealtimeConfig数据类为准详见下文配置解析一节。数据接口Data Out扩展向图graph下游节点输出的数据消息NamePropertyTypeDescriptiontext_datatextstring输出的文本数据命令接口Command OutNameDescriptionflush刷新当前状态后给出响应音频帧接口Audio Frame In / OutNameDirectionDescriptionpcm_frameIn语音处理的音频帧输入用户语音pcm_frameOut语音处理后的音频帧输出模型语音配置解析从 property.json 到 StepFunRealtimeConfig扩展在on_init阶段通过ten_env.get_property_to_json(None)读取全部属性并用 Pydantic 的model_validate_json校验生成StepFunRealtimeConfig。完整配置字段及其默认值定义在 extension.pydataclass class StepFunRealtimeConfig(BaseModel): base_url: str wss://api.stepfun.com api_key: str path: str /v1/realtime model: str step-1o-audio language: str en prompt: str temperature: float 0.5 max_tokens: int 1024 voice: str linjiajiejie server_vad: bool True audio_out: bool True sample_rate: int 24000 # VAD tuning vad_type: Literal[server_vad, semantic_vad] server_vad vad_eagerness: Literal[low, medium, high, auto] auto vad_threshold: float 0.5 vad_prefix_padding_ms: int 300 vad_silence_duration_ms: int 500 dump: bool False dump_path: str 各字段核心语义base_urlpathWebSocket 服务地址默认拼接为wss://api.stepfun.com/v1/realtime模型名通过查询参数?model...附加见 connection.pysample_rate输入输出音频采样率默认 24000 Hz扩展的input_audio_sample_rate()与synthesize_audio_sample_rate()均直接返回该值extension.py即整个图链路统一按 24 kHz PCM 处理vad_type/vad_eagerness/vad_threshold/vad_prefix_padding_ms/vad_silence_duration_msVAD 调优参数。服务端 VAD 模式server_vad下阈值、语音前填充默认 300ms与静音判定时长默认 500ms会被组装进session.update请求extension.pyaudio_out是否输出音频模态。为false时session.update会设置modalities [text]实现纯文本对话模式extension.pyprompt即 README 中system_message对应的实际实现字段作为 session 的instructions下发extension.pylanguage通过InputAudioTranscription(language...)注入输入音频转写的目标语言extension.py。若api_key为空扩展会在on_init阶段直接抛出ValueError(api_key is required)拒绝启动extension.py因此部署时必须提供有效的 StepFun API Key。依赖与运行环境manifest.json 声明了两个系统依赖ten_runtime_python版本0.11TEN 运行时 Python 绑定ten_ai_base版本0.7提供AsyncMLLMBaseExtension基类与MLLMClientMessageItem、MLLMServerFunctionCall、MLLMServerInputTranscript等结构化消息类型。Python 侧依赖见 requirements.txt 与 pyproject.toml要求 Python 3.10依赖aiohttp3.14.1WebSocket 客户端、pydantic2.13.4配置校验与pydub0.25.1。运行机制WebSocket Realtime 协议与事件循环扩展的运行核心是 extension.py 中的start_connection()客户端事件循环整体链路可概括为建立连接RealtimeApiConnection用aiohttp.ClientSession.ws_connect连接base_url path ?model...并在请求头携带Authorization: Bearer api_keyconnection.py会话建立收到session.created后标记connectedTrue、缓存session_id随后发送session.update注入 prompt、tools、VAD 参数、语音与转写语言并在session.updated到达后向上游广播mllm_server_session_ready用户语音上行send_audio()将收到的AudioFrame二进制按 PCM16 编码为 Base64封装为input_audio_buffer.append事件发送connection.py服务端事件分发listen()异步迭代 WebSocket 消息经parse_server_message按type字段反序列化为 30 余种 dataclass 事件struct.py再交由match message:模式匹配分发处理输出事件上抛文本流response.text.delta/response.audio_transcript.delta累积为response_transcript通过send_server_output_text输出mllm_server_output_transcriptfinalFalse结束事件则补发 finalTrue音频流response.audio.delta中的 Base64 数据解码后经send_server_output_audio_data以 PCM 帧形式输出extension.py打断与 VAD收到input_audio_buffer.speech_started且server_vadtrue时发送mllm_server_interrupted中断当前生成并为未完成的转写追加[interrupted]标记后以 finalTrue 收尾extension.py断线重连事件循环异常退出后调用_handle_reconnect()以 1 秒退避延时重新start_connection()extension.py。客户端 → 服务端消息类型struct.py 定义了完整的客户端上行消息集合均由ClientToServerMessage派生并自动生成event_idUUIDinput_audio_buffer.append/commit/clear音频缓冲区操作conversation.item.create创建用户/助手/函数调用输出消息项response.create触发模型生成含cancel_previous取消上一轮生成session.update更新会话参数conversation.item.truncate/delete截断或删除对话项。服务端 → 客户端事件分类下行事件在 struct.py 中按EventType枚举组织主要分为会话生命周期session.created、session.updated、error输入语音转写conversation.item.input_audio_transcription.delta / completed / failed响应流response.created / done、response.text.delta / done、response.audio_transcript.delta / done、response.audio.delta / doneVAD / 轮流input_audio_buffer.speech_started / speech_stopped、input_audio_buffer.committed / cleared工具调用response.function_call_arguments.delta / done其他response.output_item.added / done、rate_limits.updated。序列化时to_json会剔除值为None的字段保证上行报文精简struct.py。工具集成将外部工具接入 StepFun 多模态模型该扩展完整实现了 MLLM 工具调用链路README 中注释掉的 Tool Support 特性在源码中已有落地工具注册上游节点通过send_client_register_tool()注册LLMToolMetadata工具被缓存到available_tools并触发session.updateextension.py会话工具清单_update_session()将工具元数据转换为{type: function, name, description, parameters}结构并根据是否存在工具设置tool_choice为auto或noneextension.py工具调用回传收到response.function_call_arguments.done后通过send_server_function_call向上游广播mllm_server_function_call含 call_id、函数名与 JSON 参数结果回填上游执行完成后调用send_client_function_call_output()将结果封装为conversation.item.createfunction_call_output类型回传模型extension.py。以仓库中的 stepfun-demo 为例property.jsonweatherapi_tool_python通过tool_register命令向main_control注册天气工具main_control再将mllm_server_function_call等消息与 v2v即 stepfun_mllm_python相连形成模型发起工具调用 → 主控路由 → 工具执行 → 结果回填模型的闭环。端到端实战基于 stepfun-demo 的图编排示例仓库在 ai_agents/agents/examples/stepfun-demo 提供了完整可运行的示例其 tenapp/property.json 定义了名为voice_assistant_realtime的预置图predefined graph。核心节点与连接如下音频输入输出agora_rtc声网 RTC 负责采集/播放通过pcm_frame音频帧与扩展互通流 ID 适配streamid_adapter在 RTC 与扩展之间做流标识转换主控main_control消费mllm_server_input_transcript、mllm_server_output_transcript、mllm_server_session_ready、mllm_server_interrupted、mllm_server_function_call等数据消息MLLM 核心v2v节点即stepfun_mllm_python扩展配置如下与扩展默认 property.json 完全一致{ api_key: ${env:STEPFUN_API_KEY}, temperature: 0.9, model: step-1o-audio, max_tokens: 2048, voice: linjiajiejie, language: en, server_vad: true, history: 10, enable_storage: false, base_url: wss://api.stepfun.com }图中的音频帧连接property.json形成两条关键通路上行agora_rtc→streamid_adapter→v2v用户语音送入 StepFun 模型下行v2v→agora_rtc模型合成语音回放给用户。配置中使用${env:STEPFUN_API_KEY}形式从环境变量注入密钥这是 TEN 生态推荐的密钥管理方式——密钥不出现在配置文件中且支持${env:VAR|default}的默认值语法。调试建议开启 verbose 日志RealtimeApiConnection的verbose参数开启后会在日志中打印双向 WebSocket 消息smart_str会将delta/audio长字段截断到 128 字符避免日志被音频数据刷屏connection.py音频 dump设置dump: true与dump_path可将输入输出音频落盘用于排查采集/回放问题观察会话事件日志中Session created、Session updated、Resp created、Resp done含 usage token 统计等关键节点均打点输出可作为运行状态的风向标转写失败排查conversation.item.input_audio_transcription.failed事件会携带错误详情并以log_warn记录可据此确认language参数是否与服务端支持的语言一致。小结stepfun_mllm_python是一个与 OpenAI Realtime 协议对齐的异步多模态扩展通过 manifest.json 声明属性契约、property.json 提供默认值、extension.py 承载事件循环与 TEN 消息桥接、realtime/connection.py 与 realtime/struct.py 实现 WebSocket 协议编解码。将其作为图中的一个v2v节点配合音频帧通路与mllm_server_*数据消息即可快速构建基于 StepFun 多模态模型的实时语音 Agent并复用 TEN 生态中现成的 RTC、工具与主控组件。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 集成 StepFun 实时语音模型stepfun-demo 语音 Agent 演示项目实战指南TEN Framework 集成 StepFun 实时语音模型stepfun demo 语音 Agent 演示项目实战指南 本文以 ai_agents/age人工智能AI Agent多模态语音AI 应用深入解析 TEN Framework 的 main_python 扩展语音 AI Agent 的中央控制中枢深入解析 TEN Framework 的 main_python 扩展语音 AI Agent 的中央控制中枢 导读 main_python 是 TEN F人工智能AI Agent多模态语音AI 应用TEN Framework 实战main_python 扩展如何编排多说话人语音 Agent 会话TEN Framework 实战main_python 扩展如何编排多说话人语音 Agent 会话 本篇文章以 TEN Framework 的 speaker人工智能AI Agent多模态语音AI 应用上一篇如何用OpenCore Legacy Patcher让老Mac焕发新生终极兼容性优化指南下一篇OpenFGA SDK全攻略Java、Node.js、Go、Python、.NET五语言快速上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考