SwiftOpenAI Realtime API完整教程10分钟构建低延迟语音对话智能体【免费下载链接】SwiftOpenAIThe most complete open-source Swift package for interacting with OpenAIs public API.项目地址: https://gitcode.com/gh_mirrors/sw/SwiftOpenAISwiftOpenAI 是目前最完整的开源 Swift 包用于与 OpenAI 公共 API 交互其中 Realtime API 支持让你在 iOS / macOS / watchOS 应用中构建低延迟、可双向实时打断的语音对话智能体Voice Agent。本教程带你用 10 分钟理解并跑通 SwiftOpenAI Realtime API 的核心流程建立 WebSocket 会话 → 实时推流麦克风音频 → 播放模型语音回复 → 调用本地函数工具。一、SwiftOpenAI Realtime API 是什么为什么需要它传统的录音 → 识别 → 大模型 → TTS → 播放流水线链路长、延迟高用户说话时还必须等模型说完。而 OpenAI Realtime API 通过WebSocket 双向音频流直接收发原始 PCM 音频配合语义 VADVoice Activity Detection自动轮次检测可以做到能力说明️ 双向音频流麦克风音频实时上行模型音频流式下行播放✂️ 实时打断用户一开口立即停止模型播放barge-in 语义 VAD基于语义判断说完没而非单纯静音阈值 Function Calling会话中调用本地函数查时间、查业务数据 双向字幕用户与助手侧均提供实时转录文本SwiftOpenAI 已把这套能力封装为开箱即用的 Swift 接口核心入口位于 OpenAIService.swift 的realtimeSession(model:configuration:)方法底层会话管理在 OpenAIRealtimeSession.swift。二、准备工作3 个前置条件开始前请确认以下条件都满足系统版本iOS 15、macOS 12 或 watchOS 9麦克风权限在Info.plist中添加描述键keyNSMicrophoneUsageDescription/key stringWe need access to your microphone for voice conversations with AI/stringAPI Key需要一个有 Realtime 模型访问权限的 OpenAI API Key 如果项目还没引入 SwiftOpenAI可以在仓库页面克隆源码仓库地址https://gitcode.com/gh_mirrors/sw/SwiftOpenAI完整可运行示例位于 RealtimeExample.swift其说明文档在 README.md。三、10 分钟快速上手建立实时语音会话整个流程只有 3 步。第 1 步创建服务与会话用工厂方法创建服务然后传入模型与会话配置realtimeSession会返回一个OpenAIRealtimeSession对象内部已完成 WebSocket 连接let service OpenAIServiceFactory.service(apiKey: your-api-key) let session try await service.realtimeSession( model: Model.gptRealtime21.value, // 最新的语音智能体模型 configuration: configuration // 会话配置下一步讲解 )推荐模型一览定义于 Model.swiftSwift 枚举模型 ID定位gptRealtime21gpt-realtime-2.1最新实时推理模型推荐gptRealtime21Minigpt-realtime-2.1-mini低成本轻量版gptRealtimeWhispergpt-realtime-whisper语音转写专用第 2 步上行——把麦克风音频推给模型用 SDK 自带的AudioController开启录音与播放双模式将每块 PCM 缓冲 Base64 编码后追加到服务端音频缓冲区let audioController try await AudioController(modes: [.playback, .record]) Task { let micStream try audioController.micStream() for await buffer in micStream { if let base64Audio AudioUtils.base64EncodeAudioPCMBuffer(from: buffer) { await session.sendMessage( OpenAIRealtimeInputAudioBufferAppend(audio: base64Audio)) } } }第 3 步下行——流式播放模型语音消费会话的receiver事件流收到音频增量就播放、收到语音开始事件就打断本地播放Task { for await message in session.receiver { switch message { case .responseAudioDelta(let itemID, _, let audio): audioController.playPCM16Audio(base64String: audio, itemID: itemID) case .inputAudioBufferSpeechStarted: // 用户开口 → 打断 audioController.interruptPlayback() default: break } } }三步完成一个可打断、低延迟的语音对话智能体就跑起来了。四、关键配置详解让智能体更聪明会话行为几乎全部由OpenAIRealtimeSessionConfiguration控制源码见 OpenAIRealtimeSessionConfiguration.swift。几个最值得关注的字段instructions系统提示词。官方建议语气自然、回答简短例如You are a concise realtime voice assistant.voice模型音色如alloy、echo、shimmer示例中用了marinturnDetection轮次检测。配置为.semanticVAD(...)后由服务端语义判断用户是否说完并可用interruptResponse: true开启实时打断inputAudioTranscription开启后服务端会把用户语音实时转成文字方便渲染字幕toolstoolChoice注册函数工具并控制调用策略auto / none / required / 指定函数reasoning为gpt-realtime-2.1这类实时推理模型设置推理强度示例 App 中的完整配置可以参照 RealtimeConversationProvider.swift。五、进阶语音对话中的 Function CallingRealtime 会话里让模型调用你本地的函数比如查询天气、读取订单只需两个动作注册工具在会话配置中通过RealtimeTool.function声明函数名、描述和 JSON Schema 参数回传结果收到.responseFunctionCallArgumentsDone事件后执行本地函数用OpenAIRealtimeFunctionCallOutput把输出发回最后在response.done后发送OpenAIRealtimeResponseCreate()让模型基于结果继续作答。参数类型定义在 OpenAIRealtimeFunctionCallOutput.swift 与 OpenAIRealtimeResponseCreate.swift。六、常见问题排查清单遇到连不上、没声音、不能打断时按这个清单逐项检查✅API Key确认 Key 有 Realtime 模型的访问权限连接秒断多半是鉴权失败✅模型选择使用Model.gptRealtime21.value最新语音智能体模型✅麦克风权限确认用户已授予macOS 沙盒 App 还需开启 outgoing network connections 与 audio input✅单一音频引擎录音和播放必须挂在同一个AudioController上——分开的音频图会让回声消除拿不到模型音频做参考导致自己打断自己✅事件缓冲SDK 会从会话建立时刻起缓冲事件先建会话、再装麦克风 tap就不会丢session.created/session.updated更多工程化细节事件规则、reducer 设计、启动看门狗见示例文档 RealtimeDemo/README.md。七、总结本文带你用 SwiftOpenAI Realtime API 走通了低延迟语音对话智能体的完整链路realtimeSession一行建立 WebSocket 实时会话micStreamInputAudioBufferAppend完成音频上行receiver事件流完成音频下行、打断与字幕通过OpenAIRealtimeSessionConfiguration调优音色、VAD 与工具调用。配合示例代码 RealtimeExample.swift你可以在 10 分钟内拥有一个会听、说、打断、调函数的语音智能体。【免费下载链接】SwiftOpenAIThe most complete open-source Swift package for interacting with OpenAIs public API.项目地址: https://gitcode.com/gh_mirrors/sw/SwiftOpenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考