# 实现 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 语音助手的实现流程如下图所示:

上图中,采集和播放音频数据是使用声网 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 来实现原始音频数据采集和播放功能,也可以参考: