> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文以家庭智能设备中的个性化交互和控制智能家居为例，介绍如何在 WebSocket 或 RTC 通话中集成声纹识别能力，包括每轮对话实时声纹识别、首轮对话声纹识别、特定声纹唤醒三种场景。
## 场景描述 {#3cbb487d}
在家庭智能设备中，你可以通过以下三种方案实现声纹识别，以满足不同的个性化服务与安全控制需求： 

* **每轮对话实时声纹识别（家庭智能设备个性化交互场景）**
   在家庭智能设备的 WebSocket 或 RTC 通话中，通过每轮对话实时进行声纹识别，精准区分家庭成员身份，例如妈妈和宝宝，扣子编程会根据识别结果为不同用户提供专属服务和个性化内容，例如为妈妈推送生活闲聊服务，为宝宝提供趣味问答互动，以此提升家庭智能设备的交互体验。此场景适用于对安全性要求较高的交互，需注意每次识别会产生相应费用。
* **首轮对话声纹识别（家庭智能设备个性化交互场景）**
   在家庭智能设备的 WebSocket 或 RTC 通话中，仅在首轮对话进行声纹识别以确定家庭成员身份，例如妈妈和宝宝，后续对话直接沿用该身份信息，从而减少声纹识别消耗的 Token。同时，仍能基于身份信息提供专属服务，例如为妈妈推送生活闲聊服务，为宝宝提供趣味问答互动，提升家庭智能设备的交互体验。该场景适合对资源消耗较敏感的个性化交互需求。
* **特定声纹唤醒智能体（智能家居控制场景）**
   在智能手机、智能家居等终端设备中，你可以设置仅特定的声纹，例如仅妈妈和宝宝的声纹能唤醒智能体，确保设备操作的安全性和准确性。此方案适用于需要严格控制设备访问权限的场景，例如防止儿童误操作或保护隐私。

## 前期准备：创建声纹组和声纹 {#fa06a826}
你可以通过扣子编程 Web 页面或 Open API 创建声纹组和声纹。为匹配家庭智能设备场景中区分家庭成员的需求，在本场景中声纹组中**需包含妈妈的声纹和宝宝的声纹**。
### 方式一：通过扣子编程页面 {#41a06423}
在扣子编程页面创建声纹组，用于统一管理家庭成员声纹将。在声纹组中分别创建名称为“妈妈”和“宝宝”的声纹，并上传各自的声纹数据。具体操作请参见[声纹识别](/guides/voiceprint_recognition)。
![Image=600x292](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/cc14ae7f05684fe9a202a0efda73348a~tplv-goo7wpa0wc-image.image)
### 方式二：通过扣子编程 Open API {#a60c91a2}

1. 调用[创建声纹组](/developer_guides/create_voiceprint_group) API 创建声纹组（用于统一管理家庭成员声纹）。
2. 调用[创建声纹](/developer_guides/create_voiceprint)API，分别创建“妈妈”和“宝宝”的声纹，并上传各自的声纹数据，并将两者绑定至同一声纹组中。

## 场景一：每轮对话实时声纹识别 {#b0a2934d}
在本场景中，利用系统变量 `sys_voiceprint_name` 的值区分成员身份，并根据不同的身份信息设计分支逻辑。在 WebSocket 或 RTC 通话的上行事件中绑定声纹组，语音通话时扣子编程自动匹配声纹组中的声纹，并将声纹信息通过系统变量 `sys_voiceprint_name` 传给对话流，实现个性化服务，例如为妈妈提供生活闲聊，为宝宝提供趣味问答等，后续对话沿用该身份信息。
### 1 为智能体开启声纹识别 {#246b5fa5}

1. 创建一个**单 Agent（对话流模式）​**的智能体。
2. 在智能体的编排页面，在**对话体验** ＞ **语音**区域开启语音通话和声纹识别。
   开启声纹识别后，扣子编程会自动添加声纹识别的系统变量 `sys_voiceprint_name` 和 `sys_voiceprint_info`，后续在智能体对话流中需要引用该声纹变量，实现为不同用户身份提供专属服务和个性化内容。
   本场景中主要使用 `sys_voiceprint_name` 变量，用于标识识别的对话人的身份（如 “妈妈” 或 “宝宝”）。例如，当  `sys_voiceprint_name` 的值为“妈妈”时，智能体将触发与妈妈相关的闲聊服务。当值为“宝宝”时，则触发与宝宝相关的趣味问答服务。
   ![Image=400x607](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/049c9528222b4e65a733d818a8b6f5fd~tplv-goo7wpa0wc-image.image)

### 2 搭建对话流 {#ffe5ab1f}
本文以家庭智能设备为例，对话流通过声纹变量`sys_voiceprint_name`区分成员身份，并根据不同的身份信息设计分支逻辑，实现 "妈妈闲聊" 和 "宝宝闲聊" 的个性化交互。对话流的编排详情如下图所示。
![Image=800x292](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/19091c92a9e74fd7b04976a781346040~tplv-goo7wpa0wc-image.image)
各节点的详细配置如下。
<!-- @cols-width: 141,339,343 -->
| | | | \
|**节点** |**说明** |**示例** |
|---|---|---|
| | | | \
|开始节点  |保持默认输入参数即可。 |![Image=200x127](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/ddf8cd7581c4422fb861e6256e0807e3~tplv-goo7wpa0wc-image.image) |
| | | | \
|选择器节点  |智能体根据系统变量 `sys_voiceprint_name` 的值是“妈妈”或者“宝宝”，来决定进入**与妈妈闲聊**节点还是**与宝宝闲聊**节点。 |\
| |:::tip 说明 |\
| |变量的值需要和创建的声纹名称保持一致，例如本示例中的值是“妈妈”和“宝宝”。 |\
| |::: |\
| | |![Image=200x273](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c5b41c04e8b24736b4ca199401117a40~tplv-goo7wpa0wc-image.image) |
| | | | \
|与妈妈闲聊（大模型节点）  |* 输入参数：增加 `user_input` 和 `voice_name` 参数。 |\
| |   * `user_input` 参数的值引用开始节点的 `USER_INPUT`。 |\
| |   * `voice_name` 参数的值引用系统变量 `sys_voiceprint_name`。本文的系统提示词请参见[附录-提示词](/tutorial/audio_voiceprint#0480aaf0)。 |\
| |* 系统提示词：根据妈妈这个身份，设闲聊的回复逻辑和风格，例如亲切、生活化。 |\
| |* 用户提示词：引用输入参数中的 `user_input`。 |![Image=200x428](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e02bf7e7e2e34a05bcda6176d9708032~tplv-goo7wpa0wc-image.image) |
| | | | \
|与宝宝闲聊（大模型节点）  |* 输入参数：增加 `user_input` 和 `voice_name` 参数。 |\
| |   * `user_input` 参数的值引用开始节点的 `USER_INPUT`。 |\
| |   * `voice_name` 参数的值引用系统变量 `sys_voiceprint_name`。 |\
| |* 系统提示词：根据宝宝这个身份，设闲聊的回复逻辑和风格，如童趣、简单。本文的系统提示词请参见[附录-提示词](/tutorial/audio_voiceprint#0480aaf0)。 |\
| |* 用户提示词：引用输入参数中的 `user_input`。 |\
| | |\
| | |![Image=200x434](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c6a4edc717b642369317d547cf9791f2~tplv-goo7wpa0wc-image.image) |
| | | | \
|结束节点 |添加两个输出变量，变量的值分别引用与妈妈闲聊和与宝宝闲聊大模型的输出结果。 |![Image=200x141](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/489fb23d44de4913b7014276bb937c90~tplv-goo7wpa0wc-image.image) |

### 3 测试并发布智能体 {#c1d6ace8}

1. 试运行并发布对话流后，在智能体中添加对话流，在智能体右侧的调试页面单击通话图标，选择对应的声纹组，发起语音通话，验证声纹识别的效果是否符合预期。
   ![Image=600x223](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a4c757dae9fc49b399d12105b76aca75~tplv-goo7wpa0wc-image.image)
2. 发布智能体至 API 渠道。

### 4 语音通话时进行声纹识别 {#007ace95}
若需在音视频通话场景中实现个性化服务，需在通过 WebSocket 或 RTC 接入音视频时集成声纹识别能力。实现后，智能体可识别发言者的声纹特征并精准判断其身份（如家庭成员中的妈妈或宝宝），基于身份信息触发差异化交互逻辑，提供针对性的个性化问答服务。
#### 方式一：WebSocket 语音通话 {#de228d97}

1. 建立 WebSocket 连接时，在 URL 路径的 Query 参数中设置 bot_id。 
2. 建立 WebSocket 连接后，发送 `chat.update` 上行事件，在 `data.voice_print_config` 参数中绑定对应的声纹组，事件的详细说明请参见[双向流式对话上行事件](/developer_guides/streaming_chat_event)。 
   ```JSON
   { 
       "id": "event_id", 
       "event_type": "chat.update", 
       "data": {
          "voice_print_config": {
              "group_id": "750564519176***",  //group_id为你创建的声纹组的ID，可通过扣子编程页面的声纹组详情或创建声纹组API的返回结果获取
              "score": 40,
              "reuse_voice_info": false
          }
   } 
   ```

3. 通过 WebSocket 与扣子智能体进行实时语音交互时，通过` input_audio_buffer.append` 上行事件，流式上传音频数据，事件的详细说明请参见[流式上传音频片段](/developer_guides/streaming_chat_event#98463f78)。 

#### 方式二： RTC 音视频通话 {#e8e8347a}

1. 调用[创建房间](/developer_guides/create_room) API 创建扣子房间。 
2. 发送 `session.update` 上行事件绑定对应的声纹组，具体的事件说明可参考[更新房间配置](/developer_guides/signaling_uplink_event#bb460fb4)。
   ```JSON
   { 
       "id": "event_id", 
       "event_type": "session.update", 
       "data": { 
           "voice_print_config": {
               "group_id": "750564519176***",  //group_id为你创建的声纹组的ID，可通过扣子编程页面的声纹组详情或创建声纹组API的返回结果获取
               "score": 40,
               "reuse_voice_info": false
           }
       }
   }
   ```


## 场景二：首轮对话声纹识别 {#9719765d}
本场景中，你需要在对话流中添加自定义变量 `voice_print`，并根据其值是“妈妈”或“宝宝”设计分支逻辑。在建立 Websocket 连接前调用 API 完成声纹比对，将结果存入自定义变量 `voice_print`，根据不同身份提供个性化服务，例如为妈妈提供生活闲聊，为宝宝提供趣味问答等，后续对话沿用该身份信息。
### 1 搭建对话流 {#d2bc3143}
本文以家庭智能设备为例，对话流通过自定义的声纹变量区分成员身份，并根据其值是“妈妈”或“宝宝”设计分支逻辑，实现 "妈妈闲聊" 和 "宝宝闲聊" 的个性化交互。对话流的编排详情如下图所示。
![Image=600x220](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/5c1e3e84ed214835adb35b0196823b0a~tplv-goo7wpa0wc-image.image)
各节点的详细配置如下。
<!-- @cols-width: 141,339,343 -->
| | | | \
|**节点** |**说明** |**示例** |
|---|---|---|
| | | | \
|开始节点  |在**开始节点**的输入参数中创建自定义参数，例如 `voice_print`。 |![Image=200x137](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/196e25c63bdc4a1c94635a258cb5099c~tplv-goo7wpa0wc-image.image) |
| | | | \
|选择器节点  |智能体根据开始节点中变量 `voice_print` 的值是“妈妈”或者“宝宝”，来决定进入**与妈妈闲聊**节点还是**与宝宝闲聊**节点。 |\
| |:::tip 说明 |\
| |变量的值需要和创建的声纹名称保持一致，例如本示例中的值是“妈妈”和“宝宝”。 |\
| |::: |![Image=200x254](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/1071e7afc3b941f48ca58109b873abcf~tplv-goo7wpa0wc-image.image) |
| | | | \
|与妈妈闲聊（大模型节点）  |* 输入参数：增加 `user_input` 和 `voice_name` 参数。 |\
| |   * `user_input` 参数的值引用开始节点的 `USER_INPUT`。 |\
| |   * `voice_print` 参数的值引用开始节点的输入参数 `voice_print`。 |\
| |* 系统提示词：根据妈妈这个身份，设闲聊的回复逻辑和风格，例如亲切、生活化。本文的系统提示词请参见[附录-提示词](/tutorial/audio_voiceprint#0480aaf0)。 |\
| |* 用户提示词：引用输入参数中的 `user_input`参数。 |![Image=200x431](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e0da0112bebe42cb8d992c170e075e6f~tplv-goo7wpa0wc-image.image) |
| | | | \
|与宝宝闲聊（大模型节点）  |* 输入参数：增加 `user_input` 和 `voice_name` 参数。 |\
| |   * `user_input` 参数的值引用开始节点的 `USER_INPUT`。 |\
| |   * `voice_print` 参数的值引用开始节点的输入参数 `voice_print`。 |\
| |* 系统提示词：根据宝宝这个身份，设闲聊的回复逻辑和风格，如童趣、简单。本文的系统提示词请参见[附录-提示词](/tutorial/audio_voiceprint#0480aaf0)。 |\
| |* 用户提示词：引用输入参数中的 `user_input` 参数。 |\
| | |\
| | |![Image=200x444](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e6874139625b45cab1fa90ee88c39500~tplv-goo7wpa0wc-image.image) |
| | | | \
|结束节点 |添加两个输出变量，变量的值分别引用与妈妈闲聊和与宝宝闲聊大模型的输出结果。 |![Image=200x141](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/489fb23d44de4913b7014276bb937c90~tplv-goo7wpa0wc-image.image) |

### 2 测试并发布智能体 {#6545d9f1}

1. 试运行并发布对话流.
2. 创建一个**单 Agent（对话流模式）​**的智能体，在智能体中添加对话流，在智能体右侧的调试页面单击通话图标，选择对应的声纹组，发起语音通话，验证声纹识别的效果是否符合预期。
   ![Image=600x223](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a4c757dae9fc49b399d12105b76aca75~tplv-goo7wpa0wc-image.image)
3. 发布智能体至 API 渠道。

### 3 语音通话时进行声纹识别 {#f4b76757}
本文以 WebSocket 为例，RTC 的实现方式类似。

1. 建立 WebSocket 连接前进行声纹比对。
   调用[声纹特征比对](/developer_guides/identify_voiceprint) API，传入声纹组 ID。当用户说话时，扣子编程会将用户输入的音频与声纹组中的声纹进行比对，并返回声纹组中得分最高的声纹信息，作为本轮对话的说话人身份（标记为 `{{voice_info}}`）。 
2. 更新对话配置。
   建立 WebSocket 连接后，发送 `chat.update` 事件，在 `chat.update` 事件的 `chat_config.parameters` 参数中，将声纹信息通过 `parameters` 参数传递到 WebSocket 的接口中，WebSocket 会将该自定义参数的值传给对话流。`parameters` 中的参数名称为对话流开始节点中设置的自定义参数（`voice_print`），参数的值为说话人的身份信息 `{{voice_info}}`。
   ```JSON
   { 
       "id": "event_id", 
       "event_type": "chat.update", 
       "data": {
         "chat_config": { 
               "parameters": {
                     "voice_print":  "{{voice_info}}" // 这里的参数类型以你自己定义的自定义参数类型为准，支持字符串和数字
              }  
           }
   }
   ```


## 场景三：特定声纹唤醒智能体 {#f9d3609b}
在本场景中，你可以设置仅特定的声纹（例如仅妈妈和宝宝的声纹）能唤醒智能体，实现流程如下：
![Image=500x381](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/9037480a8d4342c7a4a814f2b5e7e100~tplv-goo7wpa0wc-image.image)

1. 调用[声纹特征比对](/developer_guides/identify_voiceprint) API，传入声纹组 ID。当用户说话时，扣子编程会将用户输入的音频与声纹组中的声纹进行比对，并返回声纹列表。
2. 开发者根据返回的声纹列表信息进行业务逻辑中的身份比对，仅当声纹匹配成功后，建立 WebSocket 连接或创建 RTC 房间。

## 附录-提示词 {#0480aaf0}
本文中用到的提示词如下，仅供参考：

::::cols
@col 50
与妈妈闲聊
```Markdown
# 角色
你是一位贴心的生活陪伴小助手，尤其擅长与妈妈们进行交流，能给予温暖且实用的回应。

## 技能
### 技能 1: 闲聊陪伴
1. 积极与妈妈互动，认真倾听她的心声，围绕烹饪、小孩成长、美妆、衣服搭配等妈妈关心的话题展开交流，回复 100 字左右。
2. 结合历史消息和妈妈当前输入，根据她开启的话题深入探讨，分享有趣的观点和经验，让她感受到贴心陪伴。

### 技能 2: 烹饪交流
1. 当妈妈提及烹饪相关话题时，分享不同菜系的特色菜谱。
2. 针对妈妈在烹饪过程中遇到的问题，如食材处理、烹饪技巧等，给出专业且实用的建议。

### 技能 3: 小孩成长探讨
1. 若妈妈聊到小孩成长，提供不同年龄段孩子的教育方法和注意事项。
2. 分享培养孩子兴趣爱好、性格塑造方面的经验和案例。

### 技能 4: 美妆分享
1. 当妈妈谈到美妆话题，介绍适合妈妈年龄段的护肤品牌和产品。
2. 分享日常妆容打造技巧，以及不同场合的妆容搭配建议。

### 技能 5: 衣服搭配建议
1. 妈妈提及衣服搭配时，根据不同季节、场合给出服装搭配方案。
2. 推荐适合妈妈身材和风格的服装款式和颜色组合。

## 用户个人信息
用户的身份是
- 结合用户画像和妈妈历史交流中发生过的记忆点事件，灵活地回答她的问题。

## 回答格式
- 直接输出文本，不要输出 json

## 限制:
- 所输出的内容必须按照给定的格式进行组织，不能偏离框架要求。
- 请确保信息来源准确可靠，必要时注明引用来源。
```



@col 50
与宝宝闲聊
```Markdown
## 回复语气
- 俏皮可爱，就像一个6岁的孩子一样

## 聊天模式：
   - 自然的陪伴儿童闲聊，关心他的生活状态和在学校的状态
   - 单轮回应要长一点，让小朋友感受到你对他的关注，要超过50个字
   - 每1轮都触发问句，推进聊天节奏。但是如果已经询问了小朋友的年龄或者姓名了，就别再问更多问题了
   - 经常夸奖小朋友

## 知识问答模式：
  - 绘声绘色的详细的解答小朋友的问题，就像百科全书一样，讲完一小段，会停顿一下  
  - 每次返回的内容不少于500个字
  - 讲完之后，结合小朋友的情况，问一些相关的问题

##  讲故事模式：
   - 绘声绘色的讲述很长的故事，包括人物、场景都细节的描述出来，讲完一小段，会停顿一下
   - 故事来源于 《伊索寓言》《格林童话》《安徒生通话》《一千零一夜》等等
   - 是小朋友喜欢的主题，首先会告诉小朋友故事的标题
   - 每次返回的故事不少于500个字
   - 讲完一个故事后，会询问小朋友关于故事的一些问题，比如故事告诉我们什么道理呢？然后再问朋友要不要听其他故事
   

## 古诗教学系统
- 欢欢说诗词的上句，让小朋友接下句
- 如果接不上来，就询问是不是需要提示
- 有节奏的朗诵诗句
- 在完成整个一首古诗的接龙之后，会把完整的古诗朗诵一遍，包括标题、作者和古诗内容
- 朗诵完之后，再把这个故事的背景介绍一下，介绍的时候，与小朋友的现状相结合
- 经常夸奖小朋友

## 成语学习系统
1. 故事叙述："今天我们要学『井底之蛙』~ 从前有只小青蛙住在深井里..."，每个成语的叙述都要详细，绘声绘色的描述故事里的人物和场景，要超过500个字
2. 道理阐释："这个成语告诉我们呀，不能像小青蛙那样只看眼前哦~"，一般200个字左右
3. 知识扩展：询问小朋友要不要听其他与这个成语相关的成语？
4. 经常夸奖小朋友   
    
## 异常处理
当收到非预期输入：
"我们换个好玩的好不好？比如..." + 推荐当前未进行的活动
```


::::