openai-agents-python 语音模型提供器深度指南OpenAIVoiceModelProvider原理、配置与实战【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAIVoiceModelProvider是 openai-agents-python 语音模块agents.voice中面向 OpenAI 官方语音模型STT 语音转文本、TTS 文本转语音的默认模型提供器负责把模型名解析成可实际调用的STTModel与TTSModel实例。本指南以 docs/ref/voice/models/openai_provider.md 中渲染的OpenAIVoiceModelProviderAPI 文档为主线结合其底层源码与测试系统讲解该提供器的构造参数、客户端管理、默认模型、流式语音会话原理以及如何在VoicePipeline中完成配置与接入。读完本文你将能独立配置 OpenAI 语音流水线、定制 STT/TTS 模型与参数并理解其内部客户端复用与懒加载机制。一、提供器的定位语音流水线中的模型工厂在 openai-agents-python 中语音能力围绕VoicePipeline展开它是一个三阶段流水线语音转文本STT将输入的音频转成文字运行你的业务代码通常是 Agent 工作流文本转语音TTS把工作流产出文本再合成音频。该流水线的完整说明见 docs/voice/pipeline.md 与 docs/voice/quickstart.md。其中第 1、3 步需要的模型并不是直接写死在流水线里的而是通过一个模型提供器Model Provider按名称动态创建——这正是OpenAIVoiceModelProvider的职责。提供器的抽象接口定义在 src/agents/voice/model.py 中VoiceModelProvider抽象基类定义get_stt_model(model_name)与get_tts_model(model_name)两个工厂方法STTModel语音转文本模型的抽象接口提供transcribe()一次性转写与create_session()流式会话两个能力TTSModel文本转语音模型的抽象接口提供run()方法产出 PCM 音频字节流。OpenAIVoiceModelProvider正是VoiceModelProvider的 OpenAI 官方实现完整源码位于 src/agents/voice/models/openai_model_provider.py并在 src/agents/voice/init.py 中被导出为公开 API。在 src/agents/voice/pipeline_config.py 中VoicePipelineConfig.model_provider的默认工厂函数就是OpenAIVoiceModelProvider也就是说不显式配置模型提供器时语音流水线默认就走 OpenAI 官方模型。二、构造参数详解OpenAIVoiceModelProvider的构造函数全部为关键字参数keyword-only签名如下源码见 openai_model_provider.pyfrom agents.voice import OpenAIVoiceModelProvider provider OpenAIVoiceModelProvider( api_keysk-..., # OpenAI API Key缺省时使用全局默认 Key base_urlNone, # 自定义 API 端点如代理或兼容网关 openai_clientNone, # 直接传入现成的 AsyncOpenAI 客户端 organizationNone, # OpenAI organization projectNone, # OpenAI project agent_registrationNone, # Agent 注册配置可选 )各参数含义与行为如下表参数类型默认行为说明api_keystr \| None使用全局默认 Key未提供时懒加载阶段会调用_openai_shared.get_default_openai_key()取全局默认 Keybase_urlstr \| NoneOpenAI 官方端点可用于对接代理、网关或兼容 OpenAI 协议的服务openai_clientAsyncOpenAI \| None自动创建传入后优先使用该客户端此时不能再传api_key/base_url/organization/projectorganizationstr \| None无OpenAI 组织 IDprojectstr \| None无OpenAI 项目 IDagent_registrationOpenAIAgentRegistrationConfig \| dict \| None无Agent 注册配置解析为ResolvedOpenAIAgentRegistrationConfig后可通过provider.agent_registration属性访问参数冲突校验传入openai_client时的约束源码在构造函数中做了显式校验一旦传入了openai_client若同时提供api_key、base_url、organization、project中的任意一个会抛出UserError异常消息为 Dont provide api_key, base_url, organization, or project if you provide openai_client。对应测试位于 tests/voice/test_openai_model_provider.py其中test_voice_provider_rejects_client_with_conflicting_args覆盖了五种冲突组合。该测试注释明确指出这是一个针对 issue #3808 的回归测试此前该校验用的是裸assert在python -O优化模式下会被剥离导致冲突参数被静默忽略改用UserError后即使优化模式也能正常拦截。三、客户端管理与懒加载原理1. 懒加载不调用就不创建客户端构造OpenAIVoiceModelProvider时并不会立刻创建AsyncOpenAI客户端真正的客户端创建发生在_get_client()方法中openai_model_provider.py。源码注释解释了原因如果没有设置 API Key直接执行AsyncOpenAI()会抛错懒加载可以让你在未配置 Key 的情况下安全地构造 provider 对象。_get_client()的解析顺序若构造时传入了openai_client直接复用否则检查是否显式提供了api_key/base_url/organization/project中的任意一个has_explicit_client_options未提供显式选项时优先使用全局默认客户端_openai_shared.get_default_openai_client()全局默认客户端为空或提供了显式选项时才新建AsyncOpenAI(...)其中api_key缺省时回退到全局默认 Keyget_default_openai_key()并挂载共享 HTTP 客户端。全局默认客户端与 Key 的注册/读取函数位于 src/agents/models/_openai_shared.pyset_default_openai_client(client)/get_default_openai_client()、set_default_openai_key(key)/get_default_openai_key()。这意味着你可以在应用启动时用set_default_openai_client(...)配置一次全局客户端此后所有OpenAIVoiceModelProvider()不传任何客户端参数都会自动复用。2. 共享 HTTP 客户端连接池复用模块级函数shared_http_client()openai_model_provider.py维护一个全局httpx2.AsyncClientDefaultAsyncHttpx2Client并在_get_client()新建AsyncOpenAI时通过http_clientshared_http_client()注入。源码注释明确说明设计动机如果每次请求都新建 HTTP 客户端就无法共享连接池导致更差的延迟和资源占用。因此所有由 provider 创建的客户端共享同一个底层连接池。测试test_voice_provider_shared_http_client_uses_httpx2断言shared_http_client()返回的确实是httpx2.AsyncClient实例。3. 全局默认客户端的边界处理test_voice_provider_preserves_falsy_default_client与test_voice_provider_explicit_options_override_default_client均在 tests/voice/test_openai_model_provider.py进一步验证了两个边界即使全局默认客户端对象的__bool__返回Falsefalsy_get_client()也应返回该对象本身而不是误判为空转而新建客户端只要显式传入了api_key/base_url/organization/project包括空字符串这类 falsy 值就必须覆盖全局默认客户端并新建客户端且各参数原样透传。四、默认模型与模型工厂方法OpenAIVoiceModelProvider定义了两个默认模型常量openai_model_provider.pyDEFAULT_STT_MODEL gpt-4o-transcribe DEFAULT_TTS_MODEL gpt-4o-mini-tts两个工厂方法的逻辑openai_model_provider.py方法返回类型行为get_stt_model(model_name)OpenAISTTModel传入model_name则用之否则使用gpt-4o-transcribeget_tts_model(model_name)OpenAITTSModel传入model_name则用之否则使用gpt-4o-mini-tts两个方法都复用同一个AsyncOpenAI客户端实例来自_get_client()并分别构造 src/agents/voice/models/openai_stt.py 中的OpenAISTTModel与 src/agents/voice/models/openai_tts.py 中的OpenAITTSModel。五、STT 模型实现一次性转写与流式会话1. 一次性转写transcribe()OpenAISTTModel.transcribe()openai_stt.py调用 OpenAI 音频转录接口response await self._client.audio.transcriptions.create( modelself.model, fileinput.to_audio_file(), promptsettings.prompt or None, # 提示词引导模型 languagesettings.language or None, # 音频语言 temperaturesettings.temperature or None, ) return response.text它接收AudioInput完整音频见 src/agents/voice/input.py适用于无需端点检测的场景预录音频、按讲即按 push-to-talk。2. 流式会话create_session()create_session()返回OpenAISTTTranscriptionSessionopenai_stt.py面向StreamedAudioInput走 WebSocket 实时转写。其内部机制值得展开会话配置_configure_session()通过session.update事件下发配置openai_stt.py包括type: transcription、音频格式audio/pcm、采样率24000以及转写配置模型名、语言、提示词、关键词和轮次检测配置轮次检测turn detection默认值为{type: semantic_vad}语义 VAD见 openai_stt.py用于判断说话人何时说完一句话事件处理监听session.created/transcription_session.created事件确认连接就绪超时 10 秒再等待session.updated/transcription_session.updated确认配置生效收到conversation.item.input_audio_transcription.completed或旧版input_audio_transcription_completed事件即产出转写文本超时控制EVENT_INACTIVITY_TIMEOUT 1000毫秒内无新事件则视为会话结束所有超时都基于单调时钟monotonic()计算避免系统时间调整干扰。3. STT 设置项STTModelSettingssrc/agents/voice/model.py支持以下字段字段类型说明promptstr \| None给模型的转写指令languagestr \| None音频语言一次性转写用temperaturefloat \| None采样温度turn_detectiondict \| None流式输入的轮次检测配置缺省为{type: semantic_vad}languageslist[str] \| None流式输入可选语言列表仅gpt-transcribe/gpt-live-transcribe支持优先级高于languagekeywordslist[str] \| None用于引导转写的关键词/短语同样仅上述流式模型支持六、TTS 模型实现流式 PCM 音频合成OpenAITTSModel.run()openai_tts.py使用with_streaming_response流式合成音频并以 1024 字节分块产出response self._client.audio.speech.with_streaming_response.create( modelself.model, voicesettings.voice or DEFAULT_VOICE, # 默认 ash inputtext, response_formatpcm, # 固定 PCM 格式 speedsettings.speed if settings.speed is not None else omit, extra_body{instructions: settings.instructions}, )关键点默认音色DEFAULT_VOICE ashopenai_tts.py输出格式固定response_formatpcm供下游播放器直接消费语速speed取值区间为 0.254.0未设置时通过omit省略参数指令通过extra_body{instructions: ...}控制语气与朗读风格。TTSModelSettingssrc/agents/voice/model.py支持字段类型默认值说明voiceTTSVoice \| None模型默认音色内置音色或自定义音色 IDbuffer_sizeint120流式输出的最小音频块大小dtypenpt.DTypeLikenp.int16返回音频的数据类型transform_dataCallable \| NoneNone音频数据后处理变换函数instructionsstr预设句子朗读提示控制语气的指令text_splitterCallable基于句子的切分器提前切分文本不等整段生成speedfloat \| NoneNone语速0.254.0内置音色TTSVoice类型src/agents/voice/model.py包括alloy、ash、ballad、coral、echo、fable、onyx、nova、sage、shimmer、verse、marin、cedar也支持传入自定义音色对象{id: ...}。七、在 VoicePipeline 中配置与实战VoicePipelineConfigsrc/agents/voice/pipeline_config.py中model_provider默认即为OpenAIVoiceModelProvider。你可以通过两种方式定制方式一覆盖model_providerfrom agents.voice import ( OpenAIVoiceModelProvider, SingleAgentVoiceWorkflow, VoicePipeline, VoicePipelineConfig, ) provider OpenAIVoiceModelProvider( api_keysk-..., base_urlhttps://your-gateway.example.com/v1, # 对接兼容端点 ) pipeline VoicePipeline( workflowSingleAgentVoiceWorkflow(agent), configVoicePipelineConfig(model_providerprovider), )方式二通过stt_settings/tts_settings定制模型行为VoicePipelineConfig还支持stt_settings与tts_settings接受STTModelSettings/TTSModelSettings实例或等价字典__post_init__中会自动做配置强制转换例如指定语言与关键词引导转写、自定义音色与语速config VoicePipelineConfig( stt_settings{ languages: [zh], # 流式转写目标语言 keywords: [OpenAI], # 引导关键词 }, tts_settings{ voice: nova, speed: 1.1, instructions: Speak in a friendly, warm tone., }, )运行与消费结果的方式与标准流水线一致完整示例见 docs/voice/quickstart.mdresult await pipeline.run(audio_input) # audio_input 为 AudioInput 或 StreamedAudioInput async for event in result.stream(): if event.type voice_stream_event_audio: player.write(event.data) # 播放音频块 elif event.type voice_stream_event_error: pass若需要动态指定模型名可调用 provider 的工厂方法直接取得模型再自行注入业务逻辑stt provider.get_stt_model(gpt-4o-transcribe) tts provider.get_tts_model(gpt-4o-mini-tts) transcript await stt.transcribe(audio_input, settingsstt_settings) async for chunk in tts.run(transcript, settingstts_settings): ... # 消费 PCM 音频块八、可观测性转写与合成过程中的 Tracing语音模型的调用全程接入 tracing 体系OpenAISTTModel.transcribe()与流式会话内部均创建transcription_span见 openai_stt.py 与_start_turn/_end_turn记录模型名、温度、语言、关键词、提示词、轮次检测配置并可在开启敏感数据开关时写入转写结果与 PCM 音频base64敏感度由trace_include_sensitive_data与trace_include_sensitive_audio_data两个开关控制对应VoicePipelineConfig中同名配置项关闭时span 中不落提示词、关键词、转写文本与音频内容仅保留模型与格式元数据音频缓冲区的收集逻辑也做了性能优化仅当音频 tracing 开启时才保留整轮 PCM 缓冲区用于回填 span避免无谓内存占用见 openai_stt.py 注释。九、接口契约与演进保障OpenAIVoiceModelProvider作为公开 API被纳入仓库的发布契约released API contract体系tests/test_released_api_contract.py 与 tests/fixtures/released_api_contract.json 中登记了该符号防止发布时接口被意外破坏tests/voice/test_openai_model_provider.py 覆盖参数冲突校验、共享 HTTP 客户端类型、falsy 默认客户端、显式参数覆盖全局默认客户端等关键行为。总结OpenAIVoiceModelProvider是 openai-agents-python 语音能力中模型解析环节的默认实现与核心入口它以工厂模式将模型名映射为OpenAISTTModel/OpenAITTSModel通过懒加载、共享 HTTP 客户端与全局默认客户端机制降低资源开销并保持配置灵活同时以VoicePipelineConfig.model_provider为默认值深度融入语音流水线。理解其构造参数约束、客户端解析顺序与底层 STT/TTS 模型行为是构建生产级语音应用实时对话、流式转写、TTS 合成的前提。如需继续深入可进一步阅读 docs/voice/pipeline.md流水线配置与结果消费及 docs/voice/quickstart.md端到端语音示例。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 16:08:42 · 阅读 1.2k openai-agents-python 语音模型提供器深度指南：`OpenAIVoiceModelProvider` 原理、配置与实战
openai-agents-python 语音模型提供器深度指南OpenAIVoiceModelProvider原理、配置与实战【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAIVoiceModelProvider是 openai-agents-python 语音模块agents.voice中面向 OpenAI 官方语音模型STT 语音转文本、TTS 文本转语音的默认模型提供器负责把模型名解析成可实际调用的STTModel与TTSModel实例。本指南以 docs/ref/voice/models/openai_provider.md 中渲染的OpenAIVoiceModelProviderAPI 文档为主线结合其底层源码与测试系统讲解该提供器的构造参数、客户端管理、默认模型、流式语音会话原理以及如何在VoicePipeline中完成配置与接入。读完本文你将能独立配置 OpenAI 语音流水线、定制 STT/TTS 模型与参数并理解其内部客户端复用与懒加载机制。一、提供器的定位语音流水线中的模型工厂在 openai-agents-python 中语音能力围绕VoicePipeline展开它是一个三阶段流水线语音转文本STT将输入的音频转成文字运行你的业务代码通常是 Agent 工作流文本转语音TTS把工作流产出文本再合成音频。该流水线的完整说明见 docs/voice/pipeline.md 与 docs/voice/quickstart.md。其中第 1、3 步需要的模型并不是直接写死在流水线里的而是通过一个模型提供器Model Provider按名称动态创建——这正是OpenAIVoiceModelProvider的职责。提供器的抽象接口定义在 src/agents/voice/model.py 中VoiceModelProvider抽象基类定义get_stt_model(model_name)与get_tts_model(model_name)两个工厂方法STTModel语音转文本模型的抽象接口提供transcribe()一次性转写与create_session()流式会话两个能力TTSModel文本转语音模型的抽象接口提供run()方法产出 PCM 音频字节流。OpenAIVoiceModelProvider正是VoiceModelProvider的 OpenAI 官方实现完整源码位于 src/agents/voice/models/openai_model_provider.py并在 src/agents/voice/init.py 中被导出为公开 API。在 src/agents/voice/pipeline_config.py 中VoicePipelineConfig.model_provider的默认工厂函数就是OpenAIVoiceModelProvider也就是说不显式配置模型提供器时语音流水线默认就走 OpenAI 官方模型。二、构造参数详解OpenAIVoiceModelProvider的构造函数全部为关键字参数keyword-only签名如下源码见 openai_model_provider.pyfrom agents.voice import OpenAIVoiceModelProvider provider OpenAIVoiceModelProvider( api_keysk-..., # OpenAI API Key缺省时使用全局默认 Key base_urlNone, # 自定义 API 端点如代理或兼容网关 openai_clientNone, # 直接传入现成的 AsyncOpenAI 客户端 organizationNone, # OpenAI organization projectNone, # OpenAI project agent_registrationNone, # Agent 注册配置可选 )各参数含义与行为如下表参数类型默认行为说明api_keystr \| None使用全局默认 Key未提供时懒加载阶段会调用_openai_shared.get_default_openai_key()取全局默认 Keybase_urlstr \| NoneOpenAI 官方端点可用于对接代理、网关或兼容 OpenAI 协议的服务openai_clientAsyncOpenAI \| None自动创建传入后优先使用该客户端此时不能再传api_key/base_url/organization/projectorganizationstr \| None无OpenAI 组织 IDprojectstr \| None无OpenAI 项目 IDagent_registrationOpenAIAgentRegistrationConfig \| dict \| None无Agent 注册配置解析为ResolvedOpenAIAgentRegistrationConfig后可通过provider.agent_registration属性访问参数冲突校验传入openai_client时的约束源码在构造函数中做了显式校验一旦传入了openai_client若同时提供api_key、base_url、organization、project中的任意一个会抛出UserError异常消息为 Dont provide api_key, base_url, organization, or project if you provide openai_client。对应测试位于 tests/voice/test_openai_model_provider.py其中test_voice_provider_rejects_client_with_conflicting_args覆盖了五种冲突组合。该测试注释明确指出这是一个针对 issue #3808 的回归测试此前该校验用的是裸assert在python -O优化模式下会被剥离导致冲突参数被静默忽略改用UserError后即使优化模式也能正常拦截。三、客户端管理与懒加载原理1. 懒加载不调用就不创建客户端构造OpenAIVoiceModelProvider时并不会立刻创建AsyncOpenAI客户端真正的客户端创建发生在_get_client()方法中openai_model_provider.py。源码注释解释了原因如果没有设置 API Key直接执行AsyncOpenAI()会抛错懒加载可以让你在未配置 Key 的情况下安全地构造 provider 对象。_get_client()的解析顺序若构造时传入了openai_client直接复用否则检查是否显式提供了api_key/base_url/organization/project中的任意一个has_explicit_client_options未提供显式选项时优先使用全局默认客户端_openai_shared.get_default_openai_client()全局默认客户端为空或提供了显式选项时才新建AsyncOpenAI(...)其中api_key缺省时回退到全局默认 Keyget_default_openai_key()并挂载共享 HTTP 客户端。全局默认客户端与 Key 的注册/读取函数位于 src/agents/models/_openai_shared.pyset_default_openai_client(client)/get_default_openai_client()、set_default_openai_key(key)/get_default_openai_key()。这意味着你可以在应用启动时用set_default_openai_client(...)配置一次全局客户端此后所有OpenAIVoiceModelProvider()不传任何客户端参数都会自动复用。2. 共享 HTTP 客户端连接池复用模块级函数shared_http_client()openai_model_provider.py维护一个全局httpx2.AsyncClientDefaultAsyncHttpx2Client并在_get_client()新建AsyncOpenAI时通过http_clientshared_http_client()注入。源码注释明确说明设计动机如果每次请求都新建 HTTP 客户端就无法共享连接池导致更差的延迟和资源占用。因此所有由 provider 创建的客户端共享同一个底层连接池。测试test_voice_provider_shared_http_client_uses_httpx2断言shared_http_client()返回的确实是httpx2.AsyncClient实例。3. 全局默认客户端的边界处理test_voice_provider_preserves_falsy_default_client与test_voice_provider_explicit_options_override_default_client均在 tests/voice/test_openai_model_provider.py进一步验证了两个边界即使全局默认客户端对象的__bool__返回Falsefalsy_get_client()也应返回该对象本身而不是误判为空转而新建客户端只要显式传入了api_key/base_url/organization/project包括空字符串这类 falsy 值就必须覆盖全局默认客户端并新建客户端且各参数原样透传。四、默认模型与模型工厂方法OpenAIVoiceModelProvider定义了两个默认模型常量openai_model_provider.pyDEFAULT_STT_MODEL gpt-4o-transcribe DEFAULT_TTS_MODEL gpt-4o-mini-tts两个工厂方法的逻辑openai_model_provider.py方法返回类型行为get_stt_model(model_name)OpenAISTTModel传入model_name则用之否则使用gpt-4o-transcribeget_tts_model(model_name)OpenAITTSModel传入model_name则用之否则使用gpt-4o-mini-tts两个方法都复用同一个AsyncOpenAI客户端实例来自_get_client()并分别构造 src/agents/voice/models/openai_stt.py 中的OpenAISTTModel与 src/agents/voice/models/openai_tts.py 中的OpenAITTSModel。五、STT 模型实现一次性转写与流式会话1. 一次性转写transcribe()OpenAISTTModel.transcribe()openai_stt.py调用 OpenAI 音频转录接口response await self._client.audio.transcriptions.create( modelself.model, fileinput.to_audio_file(), promptsettings.prompt or None, # 提示词引导模型 languagesettings.language or None, # 音频语言 temperaturesettings.temperature or None, ) return response.text它接收AudioInput完整音频见 src/agents/voice/input.py适用于无需端点检测的场景预录音频、按讲即按 push-to-talk。2. 流式会话create_session()create_session()返回OpenAISTTTranscriptionSessionopenai_stt.py面向StreamedAudioInput走 WebSocket 实时转写。其内部机制值得展开会话配置_configure_session()通过session.update事件下发配置openai_stt.py包括type: transcription、音频格式audio/pcm、采样率24000以及转写配置模型名、语言、提示词、关键词和轮次检测配置轮次检测turn detection默认值为{type: semantic_vad}语义 VAD见 openai_stt.py用于判断说话人何时说完一句话事件处理监听session.created/transcription_session.created事件确认连接就绪超时 10 秒再等待session.updated/transcription_session.updated确认配置生效收到conversation.item.input_audio_transcription.completed或旧版input_audio_transcription_completed事件即产出转写文本超时控制EVENT_INACTIVITY_TIMEOUT 1000毫秒内无新事件则视为会话结束所有超时都基于单调时钟monotonic()计算避免系统时间调整干扰。3. STT 设置项STTModelSettingssrc/agents/voice/model.py支持以下字段字段类型说明promptstr \| None给模型的转写指令languagestr \| None音频语言一次性转写用temperaturefloat \| None采样温度turn_detectiondict \| None流式输入的轮次检测配置缺省为{type: semantic_vad}languageslist[str] \| None流式输入可选语言列表仅gpt-transcribe/gpt-live-transcribe支持优先级高于languagekeywordslist[str] \| None用于引导转写的关键词/短语同样仅上述流式模型支持六、TTS 模型实现流式 PCM 音频合成OpenAITTSModel.run()openai_tts.py使用with_streaming_response流式合成音频并以 1024 字节分块产出response self._client.audio.speech.with_streaming_response.create( modelself.model, voicesettings.voice or DEFAULT_VOICE, # 默认 ash inputtext, response_formatpcm, # 固定 PCM 格式 speedsettings.speed if settings.speed is not None else omit, extra_body{instructions: settings.instructions}, )关键点默认音色DEFAULT_VOICE ashopenai_tts.py输出格式固定response_formatpcm供下游播放器直接消费语速speed取值区间为 0.254.0未设置时通过omit省略参数指令通过extra_body{instructions: ...}控制语气与朗读风格。TTSModelSettingssrc/agents/voice/model.py支持字段类型默认值说明voiceTTSVoice \| None模型默认音色内置音色或自定义音色 IDbuffer_sizeint120流式输出的最小音频块大小dtypenpt.DTypeLikenp.int16返回音频的数据类型transform_dataCallable \| NoneNone音频数据后处理变换函数instructionsstr预设句子朗读提示控制语气的指令text_splitterCallable基于句子的切分器提前切分文本不等整段生成speedfloat \| NoneNone语速0.254.0内置音色TTSVoice类型src/agents/voice/model.py包括alloy、ash、ballad、coral、echo、fable、onyx、nova、sage、shimmer、verse、marin、cedar也支持传入自定义音色对象{id: ...}。七、在 VoicePipeline 中配置与实战VoicePipelineConfigsrc/agents/voice/pipeline_config.py中model_provider默认即为OpenAIVoiceModelProvider。你可以通过两种方式定制方式一覆盖model_providerfrom agents.voice import ( OpenAIVoiceModelProvider, SingleAgentVoiceWorkflow, VoicePipeline, VoicePipelineConfig, ) provider OpenAIVoiceModelProvider( api_keysk-..., base_urlhttps://your-gateway.example.com/v1, # 对接兼容端点 ) pipeline VoicePipeline( workflowSingleAgentVoiceWorkflow(agent), configVoicePipelineConfig(model_providerprovider), )方式二通过stt_settings/tts_settings定制模型行为VoicePipelineConfig还支持stt_settings与tts_settings接受STTModelSettings/TTSModelSettings实例或等价字典__post_init__中会自动做配置强制转换例如指定语言与关键词引导转写、自定义音色与语速config VoicePipelineConfig( stt_settings{ languages: [zh], # 流式转写目标语言 keywords: [OpenAI], # 引导关键词 }, tts_settings{ voice: nova, speed: 1.1, instructions: Speak in a friendly, warm tone., }, )运行与消费结果的方式与标准流水线一致完整示例见 docs/voice/quickstart.mdresult await pipeline.run(audio_input) # audio_input 为 AudioInput 或 StreamedAudioInput async for event in result.stream(): if event.type voice_stream_event_audio: player.write(event.data) # 播放音频块 elif event.type voice_stream_event_error: pass若需要动态指定模型名可调用 provider 的工厂方法直接取得模型再自行注入业务逻辑stt provider.get_stt_model(gpt-4o-transcribe) tts provider.get_tts_model(gpt-4o-mini-tts) transcript await stt.transcribe(audio_input, settingsstt_settings) async for chunk in tts.run(transcript, settingstts_settings): ... # 消费 PCM 音频块八、可观测性转写与合成过程中的 Tracing语音模型的调用全程接入 tracing 体系OpenAISTTModel.transcribe()与流式会话内部均创建transcription_span见 openai_stt.py 与_start_turn/_end_turn记录模型名、温度、语言、关键词、提示词、轮次检测配置并可在开启敏感数据开关时写入转写结果与 PCM 音频base64敏感度由trace_include_sensitive_data与trace_include_sensitive_audio_data两个开关控制对应VoicePipelineConfig中同名配置项关闭时span 中不落提示词、关键词、转写文本与音频内容仅保留模型与格式元数据音频缓冲区的收集逻辑也做了性能优化仅当音频 tracing 开启时才保留整轮 PCM 缓冲区用于回填 span避免无谓内存占用见 openai_stt.py 注释。九、接口契约与演进保障OpenAIVoiceModelProvider作为公开 API被纳入仓库的发布契约released API contract体系tests/test_released_api_contract.py 与 tests/fixtures/released_api_contract.json 中登记了该符号防止发布时接口被意外破坏tests/voice/test_openai_model_provider.py 覆盖参数冲突校验、共享 HTTP 客户端类型、falsy 默认客户端、显式参数覆盖全局默认客户端等关键行为。总结OpenAIVoiceModelProvider是 openai-agents-python 语音能力中模型解析环节的默认实现与核心入口它以工厂模式将模型名映射为OpenAISTTModel/OpenAITTSModel通过懒加载、共享 HTTP 客户端与全局默认客户端机制降低资源开销并保持配置灵活同时以VoicePipelineConfig.model_provider为默认值深度融入语音流水线。理解其构造参数约束、客户端解析顺序与底层 STT/TTS 模型行为是构建生产级语音应用实时对话、流式转写、TTS 合成的前提。如需继续深入可进一步阅读 docs/voice/pipeline.md流水线配置与结果消费及 docs/voice/quickstart.md端到端语音示例。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考