# 实现 AI 语音助手 (/zh-CN/ai/aigc/get-started/quick-start/android)
> 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 的相应功能实现。
## 前提条件 [#前提条件]
开始前,请确保满足如下要求:
- [Git](https://git-scm.com/downloads)
- [Java Development Kit](https://www.oracle.com/java/technologies/downloads/)
- Android Studio 4.1 以上版本
- Android API 级别 23 及以上
- Android 6.0 或以上版本的移动设备。声网推荐使用真机运行项目,部分模拟机可能存在功能缺失或者性能问题
- 参考[开通服务](/zh-CN/ai/aigc/get-started/enable-service)创建项目、获取 App ID、App 证书、临时 Token 并开通 AIGCService 服务
## 集成 SDK [#集成-sdk]
参考如下步骤获取 AIGCService SDK,并将 SDK 集成到你的项目中。
:::info[信息]
如果你本地尚无 Android 项目,可以参考 Android 官方文档 [Create a project](https://developer.android.com/studio/projects/create-project) 创建。
:::
联系 sales@shengwang.cn 获取最新的 AIGCService SDK 版本号,在 `/app/build.gradle` 的 `dependencies` 中添加对 AIGCService SDK 的依赖。
```java
// x.y.z 替换为最新的 AIGCService SDK 版本号,例如 1.2.0
implementation("io.github.winskyan:Agora-AIGCService:x.y.z")
```
:::warning[注意]
AIGCService SDK 仅支持 arm64-v8a 和 armeabi-v7a 架构。
:::
## 项目设置 [#项目设置]
#### 权限申请 [#权限申请]
在项目的 `/app/src/main/AndroidManifest.xml` 文件中,添加如下权限:
```java
```
#### 环境配置 [#环境配置]
在项目的 `/app/build.gradle` 文件的 `defaultConfig` 字段中添加如下行:
```java
minSdk 21
targetSdk 30
compileSdk 32
```
#### 防止代码混淆 [#防止代码混淆]
在 `/app/proguard-rules.pro` 文件中添加如下行:
```java
-keep class io.agora.** { *; }
-keepnames class io.agora.* { *; }
-keepnames interface io.agora.* { *; }
-dontwarn io.agora.**
-keep class com.microsoft.cognitiveservices.speech.** { *; }
-keepnames class com.microsoft.cognitiveservices.speech.* { *; }
-keepnames interface com.microsoft.cognitiveservices.speech.* { *; }
-dontwarn com.microsoft.cognitiveservices.speech.**
-keep class io.netty.** { *; }
-keepnames class io.netty.* { *; }
-keepnames interface io.netty.* { *; }
-dontwarn io.netty.**
```
## 实现 AI 语音助手 [#实现-ai-语音助手]
下文展示如何在项目中集成 AIGCService 的核心 API,并实现发送音频数据、接收语言模型处理后的音频数据的逻辑。完整的 API 时序图可以参考 [API 时序图](#api-时序图)。
### 1. 创建 AIGCService 实例 [#1-创建-aigcservice-实例]
调用 `create` 和 `initialize` 方法创建并初始化 AIGC 服务示例。你需要在 `initialize` 方法中通过 [`AIGCServiceConfig`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#aigcserviceconfig) 对服务实例进行配置。
```java
if (null == mAIGCService) {
mAIGCService = AIGCService.create();
}
mAIGCService.initialize(new AIGCServiceConfig() {{
this.context = onContext;
this.callback = serviceCallback;
this.enableLog = true;
this.enableSaveLogToFile = true;
this.userName = "AI";
this.appId = KeyCenter.APP_ID;
this.rtmToken = KeyCenter.getRtmToken(KeyCenter.getUserUid());
this.userId = String.valueOf(KeyCenter.getUserUid());
this.enableMultiTurnShortTermMemory = false;
this.speechRecognitionFiltersLength = 0;
this.input = new SceneMode() {{
this.language = Language.ZH_CN;
this.speechFrameSampleRates = 16000;
this.speechFrameChannels = 1;
this.speechFrameBits = 16;
}};
this.output = new SceneMode() {{
this.language = Language.ZH_CN;
this.speechFrameSampleRates = 16000;
this.speechFrameChannels = 1;
this.speechFrameBits = 16;
}};
this.noiseEnvironment = NoiseEnvironment.NOISE;
this.speechRecognitionCompletenessLevel = SpeechRecognitionCompletenessLevel.NORMAL;
}});
```
初始化为耗时操作。完成初始化后,SDK 会触发 `onEventResult(INITIALIZE, SUCCESS)` 回调。
### 2. 监听回调事件 [#2-监听回调事件]
除了 `onEventResult` 回调外,你还需要注册如下回调,用来接收各语言模型返回的数据结果:
- `onSpeech2TextResult`:回调语音转文字 (STT) 处理后的结果。
- `onLLMResult`:回调大语言模型 (LLM) 处理后的结果。
- `onText2SpeechResult`:回调文字转语音 (TTS) 处理后的结果。
- `onSpeechStateChange`:识别语音说话的状态。
```java
@Override
public void onEventResult(@NonNull ServiceEvent event, @NonNull ServiceCode code, @Nullable String msg) {
Log.i(TAG, "onEventResult event:" + event + " code:" + code + " msg:" + msg);
if (event == ServiceEvent.INITIALIZE && code == ServiceCode.SUCCESS) {
} else if (event == ServiceEvent.START && code == ServiceCode.SUCCESS) {
} else if (event == ServiceEvent.STOP && code == ServiceCode.SUCCESS) {
} else if (event == ServiceEvent.DESTROY && code == ServiceCode.SUCCESS) {
}
}
@Override
public HandleResult onSpeech2TextResult(String roundId, Data result, boolean isRecognizedSpeech, ServiceCode code) {
Log.i(TAG, "onSpeech2TextResult roundId:" + roundId + " result:" + result + " isRecognizedSpeech:" + isRecognizedSpeech + " code:" + code);
return HandleResult.CONTINUE;
}
@Override
public HandleResult onLLMResult(String roundId, Data answer, boolean isRoundEnd, int estimatedResponseTokens, ServiceCode code) {
Log.i(TAG, "onLLMResult roundId:" + roundId + " answer:" + answer + " isRoundEnd:" + isRoundEnd + " estimatedResponseTokens:" + estimatedResponseTokens + " code:" + code);
return HandleResult.CONTINUE;
}
@Override
public HandleResult onText2SpeechResult(String roundId, Data voice, int sampleRates, int channels, int bits, ServiceCode code) {
Log.i(TAG, "onText2SpeechResult roundId:" + roundId + " voice:" + voice + " sampleRates:" + sampleRates + " channels:" + channels + " bits:" + bits + " code:" + code);
return HandleResult.CONTINUE;
}
@Override
public void onSpeechStateChange(SpeechState state) {
Log.i(TAG, "onSpeechStateChange state:" + state);
}
```
### 3. 获取和设置参数 [#3-获取和设置参数]
该步骤允许用户根据场景需要,自定义 AIGC 服务的属性。具体步骤如下:
1. 调用 `getRoles` 获取 SDK 支持的所有 [`AIRole`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#airole),包括 AI 服务的名称、职业、性别等。
2. 调用 `setRole` 设置 SDK 使用的 `AIRole`。
3. 调用 `getServiceVendors` 获取所有 AI 服务商的信息,包含三种类型:
- [`LLMVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#llmvendor):大语言模型
- [`STTVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#sttvendor):语音转文字模型
- [`TTSVendor`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ttsvendor):文字转语音模型
4. 调用 `setServiceVendor` 设置所使用的 AI 服务商。
```java
@Override
public void onEventResult(@NonNull ServiceEvent event, @NonNull ServiceCode code, @Nullable String msg) {
Log.i(TAG, "onEventResult event:" + event + " code:" + code + " msg:" + msg);
if (event == ServiceEvent.INITIALIZE && code == ServiceCode.SUCCESS) {
Log.i(TAG, "getRoles:" + Arrays.toString(mAIGCService.getRoles()));
Log.i(TAG, "getCurrentRole:" + mAIGCService.getCurrentRole());
mAIGCService.setRole(mAIGCService.getRoles()[0].getRoleId());
Log.i(TAG, "getServiceVendors:" + mAIGCService.getServiceVendors());
ServiceVendor serviceVendor = new ServiceVendor();
serviceVendor.setTtsVendor(mAIGCService.getServiceVendors().getTtsList().get(0));
mAIGCService.setServiceVendor(serviceVendor);
mAIGCService.setSTTMode(STTMode.FREESTYLE);
}
}
```
### 4. 开启 AIGCService [#4-开启-aigcservice]
完成初始化相关设置后,调用 `start` 方法开启服务。
```java
mAIGCService.start()
```
该步骤也是耗时操作。完成开启服务后,会收到 `onEventResult(START, SUCCESS)` 回调,告知 AIGCService 开启成功。
### 5. 发送接收到的数据 [#5-发送接收到的数据]
获取到用户发送的消息数据后,你需要将该数据发送给 `AIGCService`。AIGCService SDK 接收到数据后,会将数据发送给接入的各语言模型。
:::warning[注意]
该步骤需要在调用 `start` 开启服务后实现。
:::
语音消息
文字消息
如果用户发送的是语音消息,进行如下步骤:
1. 采集本地用户发送的音频数据。如果你选用的是声网 RTC SDK,可以参考[音频原始数据](/zh-CN/realtime-media/rtc/build/audio/raw-audio-data),从 `onRecordAudioFrame` 回调中获取。
2. 获取到音频数据后,调用 [`pushSpeechDialogue`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushspeechdialogue) 方法将数据发送给 `AIGCService`。
```java
mAIGCService.pushSpeechDialogue(data, Vad.UNKNOWN, false);
```
如果用户发送的是文字消息,你可以直接调用 [`pushTxtDialogue`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushtxtdialogue) 或者 [`pushMessagesToLLM`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#pushmessagestollm) 将数据发送给 `AIGCService`。
```java
// 仅支持推送单条文字消息
mAIGCService.pushTxtDialogue("你叫什么名字?", "");
// 支持推送多条消息(消息及其上下文语境)
mAIGCService.pushMessagesToLLM("[{\n" +
"\t\t\"role\": \"user\",\n" +
"\t\t\"content\": \"你想去郊游吗?\"\n" +
"\t}, {\n" +
"\t\t\"role\": \"assistant\",\n" +
"\t\t\"content\": \"好啊!我们什么时候去?\"\n" +
"\t},\n" +
"\t{\n" +
"\t\t\"role\": \"user\",\n" +
"\t\t\"content\": \"周日?\"\n" +
"\t}\n" +
"]", "{\n" +
"\t\"temperature\": 0.5,\n" +
"\t\"presence_penalty\": 0.9,\n" +
"\t\"frequency_penalty\": 0.9\n" +
"}", "");
```
### 6. 接收处理结果 [#6-接收处理结果]
各语言模型处理结束后,会将处理结果返回给 SDK。SDK 会触发如下回调,将处理结果发送给 App。
语音消息
文字消息
如果用户发送的是语音消息,需要监听如下回调:
- [`onSpeech2TextResult`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onspeech2textresult)
- [`onLLMResult`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onllmresult)
- [`onText2SpeechResult`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ontext2speechresult)
```java
// 接收语音转文字的处理结果
@Override
public HandleResult onSpeech2TextResult(String roundId, Data result, boolean isRecognizedSpeech, ServiceCode code) {
Log.i(TAG, "onSpeech2TextResult roundId:" + roundId + " result:" + result + " isRecognizedSpeech:" + isRecognizedSpeech + " code:" + code);
return HandleResult.CONTINUE;
}
// 接收大语言模型的处理结果
@Override
public HandleResult onLLMResult(String roundId, Data answer, boolean isRoundEnd, int estimatedResponseTokens, ServiceCode code) {
Log.i(TAG, "onLLMResult roundId:" + roundId + " answer:" + answer + " isRoundEnd:" + isRoundEnd + " estimatedResponseTokens:" + estimatedResponseTokens + " code:" + code);
return HandleResult.CONTINUE;
}
// 接收语音识别的处理结果
@Override
public HandleResult onText2SpeechResult(String roundId, Data voice, int sampleRates, int channels, int bits, ServiceCode code) {
Log.i(TAG, "onText2SpeechResult roundId:" + roundId + " voice:" + voice + " sampleRates:" + sampleRates + " channels:" + channels + " bits:" + bits + " code:" + code);
return HandleResult.CONTINUE;
}
```
如果用户发送的是文字消息,需要监听如下回调:
- [`onLLMResult`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#onllmresult)
- [`onText2SpeechResult`](/zh-CN/api-reference/conversational-ai/aigc/aigcservice#ontext2speechresult)
```java
// 接收大语言模型的处理结果
@Override
public HandleResult onLLMResult(String roundId, Data answer, boolean isRoundEnd, int estimatedResponseTokens, ServiceCode code) {
Log.i(TAG, "onLLMResult roundId:" + roundId + " answer:" + answer + " isRoundEnd:" + isRoundEnd + " estimatedResponseTokens:" + estimatedResponseTokens + " code:" + code);
return HandleResult.CONTINUE;
}
// 接收语音识别的处理结果
@Override
public HandleResult onText2SpeechResult(String roundId, Data voice, int sampleRates, int channels, int bits, ServiceCode code) {
Log.i(TAG, "onText2SpeechResult roundId:" + roundId + " voice:" + voice + " sampleRates:" + sampleRates + " channels:" + channels + " bits:" + bits + " code:" + code);
return HandleResult.CONTINUE;
}
```
接收到处理后的数据后,如果是文字消息,你可以直接返回;如果是语音消息,还需要播放获取到的音频数据。
:::info[信息]
如果你选用的是声网 RTC SDK,可以参考[音频原始数据](/zh-CN/realtime-media/rtc/build/audio/raw-audio-data),使用 `onPlaybackAudioFrame` 播放。
:::
### 7. 停止 AIGCService [#7-停止-aigcservice]
无需使用 AI 语音助手后,你可以调用 `stop` 停止 `AIGCService` 实例。
:::warning[注意]
该步骤需要在调用 `start` 开启服务后实现。
:::
停止服务为耗时操作。成功停止后,会收到 `onEventResult(STOP, SUCCESS)` 回调。
```java
mAIGCService.stop();
```
### 8. 销毁 AIGCService [#8-销毁-aigcservice]
成功停止服务后调用 `destroy` 销毁服务实例。
```java
AIGCService.destroy();
```
成功销毁后,会收到 `onEventResult(DESTROY, SUCCESS)` 回调。
### API 时序图 [#api-时序图]
实现 AI 语音助手的 API 调用时序图如下。其中,实现步骤需要用到如下关键类:
- `AIGCService` 类:提供 AIGC 服务的核心类。
- `AIGCServiceCallback` 类:`AIGCService` 异步方法的事件回调类。
## 相关文档 [#相关文档]
开发过程中,你还可以参考如下文档:
如果你选择使用声网的 RTC SDK 来实现原始音频数据采集和播放功能,也可以参考: