# 实现 AI 语音助手 (/zh-CN/ai/aigc/get-started/quick-start/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网提供 AIGCService SDK,借助三方 STT(语音转文字)、TTS(文本转语音)和 LLM(大型语言模型)的能力,能在 App 中实现语音识别、自然语言理解、智能对话等功能。 本文介绍 AI 语音助手场景的实现流程,以及如何集成 AIGCService SDK,并调用核心 API 来实现这个流程。 ## 实现流程 [#实现流程] AI 语音助手的实现流程如下图所示: ![语音助手实现流程](https://web-cdn.agora.io/docs-portal/img/aigc/diagram.svg) 上图中,采集和播放音频数据是使用声网 RTC SDK 的原始音频数据功能实现的。你也可以选用其他 RTC SDK 的相应功能实现。 ## 前提条件 [#前提条件-1] 开始前,请确保满足如下要求: - [Xcode](https://developer.apple.com/xcode/) 13 或以上版本。 - 已安装 Cocoapods。如尚未安装 Cocoapods,参考 [Getting Started](https://guides.cocoapods.org/using/getting-started.html#getting-started) 安装。 - iOS 10 或以上版本的移动设备。声网推荐使用真机运行项目,部分模拟机可能存在功能缺失或者性能问题。 - 参考[开通服务](/zh-CN/ai/aigc/get-started/enable-service)创建项目、获取 App ID、App 证书、临时 Token 并开通 AIGCService 服务。 ## 集成 SDK [#集成-sdk-1] 参考如下步骤获取 AIGCService SDK,并将 SDK 集成到你的项目中。 :::info[信息] 如果你本地尚无 iOS 项目,可以参考 Apple 官方文档 [Create a project](https://help.apple.com/xcode/mac/current/#/dev07db0e578) 创建。 ::: 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 2. 联系 sales@shengwang.cn 获取最新的 AIGCService SDK 版本号,打开 `Podfile` 文件,添加对 `AgoraAIGCService` 的引用: ```ruby platform :ios, '10.0' target 'Your App' do # x.y.z 替换为最新的 AIGCService SDK 版本号,例如 1.2.0 pod 'AgoraAIGCService', 'x.y.z' end ``` 3. 在终端内运行 `pod install` 命令安装声网 AIGCService,终端中会显示 `Pod installation complete!`。 4. 成功安装后,项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件,通过 **Xcode** 打开该文件进行后续操作。 ## 项目设置 [#项目设置-1] 点击项目的 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6), 添加以下属性: | key | type | value | | --- | --- | --- | | `Privacy - Microphone Usage Description` | String | 使用麦克风的目的,如 for using aigc service | ## 实现 AI 语音助手 [#实现-ai-语音助手-1] 下文展示如何在项目中集成 AIGCService 的核心 API,并实现发送音频数据、接收语言模型处理后的音频数据的逻辑。完整的 API 时序图可以参考 [API 时序图](#api-时序图-1)。 ### 1. 创建 AIGCService 实例 [#1-创建-aigcservice-实例-1] 调用 `create` 和 `initialize` 方法创建并初始化 AIGC 服务示例。你需要在 `initialize` 方法中通过 [`AgoraAIGCConfigure`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#aigcserviceconfig) 对服务实例进行配置。 ```swift service = AgoraAIGCService.create() let uid = "123"; let token = TokenBuilder.buildRtmToken(Config.appId, appCertificate: Config.certificate, userUuid: uid) let input = AgoraAIGCSceneMode(language: .ZH_CN, peechFrameBits: 16, speechFrameSampleRates: 16000, speechFrameChannels: 1) let output = AgoraAIGCSceneMode(language: .ZH_CN, speechFrameBits: 16, speechFrameSampleRates: 16000, speechFrameChannels: 1) let config = AgoraAIGCConfigure(appId: Config.appId, rtmToken: token, userId: uid, enableMultiTurnShortTermMemory: false, speechRecognitionFiltersLength: 10, input: input, output: output, enableLog: true, enableSaveLogToFile: true, userName: "小李", enableChatIdleTip: false, logFilePath: nil, noiseEnvironment: .normal, speechRecognitionCompletenessLevel: .normal) service.delegate = self service.initialize(config) ``` 初始化为耗时操作。完成初始化后,SDK 会触发 `onEventResultWithEvent(Initialize, Success)` 回调。 ### 2. 监听回调事件 [#2-监听回调事件-1] 除了 `onEventResultWithEvent` 回调外,你还需要注册如下回调,用来接收各语言模型返回的数据结果: - `onSpeech2TextWithRoundId`:回调语音转文字 (STT) 处理后的结果。 - `onLLMResultWithRoundId`:回调大语言模型 (LLM) 处理后的结果。 - `onText2SpeechResultWithRoundId`:回调文字转语音 (TTS) 处理后的结果。 - `onSpeechStateChange`:识别语音说话的状态。 ```swift // AIGCServiceDelegate func onEventResult(with event: AgoraAIGCServiceEvent, code: AgoraAIGCServiceCode, message: String?) { if event == .initialize, code == .initializeFail { print("====initializeFail") DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } // 添加你的处理逻辑 } return } if event == .initialize, code == .success { print("====initialize success") DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } // 添加你的处理逻辑 } return } } func onSpeech2Text(withRoundId roundId: String, result: NSMutableString, recognizedSpeech: Bool, code: AgoraAIGCServiceCode) -> AgoraAIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } func onLLMResult(withRoundId roundId: String, answer: NSMutableString, isRoundEnd: Bool, estimatedResponseTokens tokens: UInt, code: AgoraAIGCServiceCode) -> AgoraAIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } func onText2SpeechResult(withRoundId roundId: String, voice: Data, sampleRates: Int, channels: Int, bits: Int, code: AgoraAIGCServiceCode) -> AIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } ``` ### 3. 获取和设置参数 [#3-获取和设置参数-1] 该步骤允许用户根据场景需要,自定义 AIGC 服务的属性。具体步骤如下: 1. 调用 `getRoles` 获取 SDK 支持的所有 [`AgoraAIGCAIRole`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#airole),包括 AI 服务的名称、职业、性别等。 2. 调用 `setRoleWithId` 设置 SDK 使用的 `AgoraAIGCAIRole`。 3. 调用 `getServiceVendors` 获取所有 AI 服务商的信息,包含三种类型: - [`AgoraAIGCLLMVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#llmvendor):大语言模型 - [`AgoraAIGCSTTVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#sttvendor):语音转文字模型 - [`AgoraAIGCSTTVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ttsvendor):文字转语音模型 4. 调用 `setServiceVendor` 设置所使用的 AI 服务商。 ```swift func onEventResult(with event: AgoraAIGCServiceEvent, code: AgoraAIGCServiceCode, message: String?) { if event == .initialize, code == .initializeFail { print("====initializeFail") return } if event == .initialize, code == .success { print("====initialize success") DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } let roles = service.getRoles() self.service.setRoleWithId(roles!.first!.roleId) let vendors = service.getVendors() let vendor = AgoraAIGCServiceVendor(stt: vendors!.stt.last!, llm: vendors!.llm.first!, tts: vendors!.tts.last!) self.service.setServiceVendor(vendor) } return } } ``` ### 4. 开启 AIGCService [#4-开启-aigcservice-1] 完成初始化相关设置后,调用 `start` 方法开启服务。 ```swift service.start() ``` 该步骤也是耗时操作。完成开启服务后,会收到 `onEventResultWithEvent(Start, Success)` 回调。 ### 5. 发送接收到的数据 [#5-发送接收到的数据-1] 获取到用户发送的消息数据后,你需要将该数据发送给 `AgoraAIGCService`。AgoraAIGCService SDK 接收到数据后,会将数据发送给接入的各语言模型。 :::warning[注意] 该步骤需要在调用 `start` 开启服务后实现。 ::: 语音消息 文字消息 如果用户发送的是语音消息,进行如下步骤: 1. 采集本地用户发送的音频数据。如果你选用的是声网 RTC SDK,可以参考[音频原始数据](/zh-CN/realtime-media/rtc/build/audio/raw-audio-data),从 `onRecordAudioFrame` 回调中获取。 2. 获取到音频数据后,调用 [`pushSpeechDialogueWithData`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushspeechdialogue) 方法将数据发送给 `AgoraAIGCService`。 ```swift service.pushSpeechDialogue(with: data, vad: .unknow, isLastFrame: false) ``` 如果用户发送的是文字消息,你可以直接调用 [`pushTxtDialogue`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushtxtdialogue) 或者 [`pushMessagesToLlm`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushmessagestollm) 将数据发送给 `AgoraAIGCService`。 ```swift // 仅支持推送单条文字消息 service.pushTxtDialogue("你好", roundId: nil) // 支持推送多条消息(消息及其上下文语境) service.pushMessages(toLlm: "json string", extraInfoJson: nil, roundId: nil) ``` ### 6. 接收处理结果 [#6-接收处理结果-1] 各语言模型处理结束后,会将处理结果返回给 SDK。SDK 会触发如下回调,将处理结果发送给 App。 语音消息 文字消息 如果用户发送的是语音消息,需要监听如下回调: - [`onSpeech2TextWithRoundId`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onspeech2textresult) - [`onLLMResultWithRoundId`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onllmresult) - [`onText2SpeechResultWithRoundId`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ontext2speechresult) ```swift // 接收语音转文字的处理结果 func onSpeech2Text(withRoundId roundId: String, result: String, recognizedSpeech: Bool, code: AgoraAIGCServiceCode) -> AgoraAIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } // 接收大语言模型的处理结果 func onLLMResult(withRoundId roundId: String, answer: String, isRoundEnd: Bool, estimatedResponseTokens tokens: UInt, code: AgoraAIGCServiceCode) -> AgoraAIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } // 接收语音识别的处理结果 func onText2SpeechResult(withRoundId roundId: String, voice: Data, sampleRates: Int, channels: Int, bits: Int, code: AgoraAIGCServiceCode) -> AIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } ``` 如果用户发送的是文字消息,需要监听如下回调: - [`onLLMResultWithRoundId`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onllmresult) - [`onText2SpeechResultWithRoundId`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ontext2speechresult) ```swift // 接收大语言模型的处理结果 func onLLMResult(withRoundId roundId: String, answer: String, isRoundEnd: Bool, estimatedResponseTokens tokens: UInt, code: AgoraAIGCServiceCode) -> AgoraAIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } // 接收语音识别的处理结果 func onText2SpeechResult(withRoundId roundId: String, voice: Data, sampleRates: Int, channels: Int, bits: Int, code: AgoraAIGCServiceCode) -> AIGCHandleResult { DispatchQueue.main.async { [weak self] in guard let `self` = self else { return } if (code == .success) { // 添加你的正确处理逻辑 } else { // 添加你的错误处理逻辑 } } return .continue } ``` 接收到处理后的数据后,如果是文字消息,你可以直接回复给 App 用户;如果是语音消息,还需要播放获取到的音频数据。 :::info[信息] 如果你选用的是声网 RTC SDK,可以参考[音频原始数据](/zh-CN/realtime-media/rtc/build/audio/raw-audio-data),使用 `onPlaybackAudioFrame` 播放。 ::: ### 7. 停止 AIGCService [#7-停止-aigcservice-1] 无需使用 AI 语音助手后,你可以调用 `stop` 停止 `AIGCService` 实例。 :::warning[注意] 该步骤需要在调用 `start` 开启服务后实现。 ::: 停止服务为耗时操作。成功停止后,会收到 `onEventResultWithEvent(Stop, Success)` 回调。 ```swift service.stop() ``` ### 8. 销毁 AIGCService [#8-销毁-aigcservice-1] 成功停止服务后调用 `destroy` 销毁服务实例。 ```swift AgoraAIGCService.destroy() ``` 成功销毁后,会收到 `onEventResultWithEvent(Destroy, Success)` 回调。 ### API 时序图 [#api-时序图-1] 实现 AI 语音助手的 API 调用时序图如下。其中,实现步骤需要用到如下关键类: - `AgoraAIGCService` 类:提供 AIGC 服务的核心类。 - `AgoraAIGCServiceDelegate` 类:`AgoraAIGCService` 异步方法的事件回调类。 ## 相关文档 [#相关文档-1] 开发过程中,你还可以参考如下文档: 如果你选择使用声网的 RTC SDK 来实现原始音频数据采集和播放功能,也可以参考: