自定义对话角色实践

1. 协议参数说明

客户端在与服务端建立 WebSocket 连接并发送 run-task 开始指令时，需在 parameters 中携带自定义角色的音色与提示词变量。

2. 建联请求示例（JSON 协议）

{
  "header": {
    "action": "run-task",
    "streaming": "duplex",
    "task_id": "Task_Id_Example"
  },
  "payload": {
    "task_group": "aigc",
    "task": "multimodal-generation",
    "function": "generation",
    "model": "multimodal-dialog",
    "input": {
      "workspace_id": "Workspace_Id_Example",
      "app_id": "App_Id_Example",
      "directive": "Start"
    },
    "parameters": {
      "upstream": {
        "sample_rate": 16000,
        "type": "AudioAndVideo",
        "mode": "tap2talk",
        "audio_format": "pcm",
        "enable_server_vad_start": false
      },
      "downstream": {
        "voice": "longanhuan",
        "sample_rate": 16000,
        "audio_format": "mp3",
        "volume": 50,
        "speech_rate": 100,
        "pitch_rate": 100,
        "intermediate_text": "transcript,dialog",
        "transmit_rate_limit": 16000
      },
      "client_info": {
        "user_id": "test_1",
        "device": {
          "uuid": "test_1"
        }
      },
      "biz_params": {
        "user_prompt_params": {
          "name": "阿云",
          "skill": "唱歌"
        }
      }
    }
  }
}

1. 角色配置映射表

由于客户端开发语言存在差异，SDK 不代为管理角色列表，需由客户端在业务层自主实现配置管理。

建议在业务层维护一张角色与参数的映射表（每个角色包含固定的音色 voice 和对应的 user_prompt_params 变量组），同时在本地或业务服务端持久化存储当前用户（UID）与角色 ID 的绑定关系。

2. 客户端通用数据结构示例（JSON）

开发时，建议在本地客户端将上述映射关系及用户绑定关系以类似如下的通用结构进行存储（各语言可自行转化为本地的 Map/Dictionary/Object 结构）：

{
  "header": {
    "action": "run-task",
    "streaming": "duplex",
    "task_id": "Task_Id_Example"
  },
  "payload": {
    "task_group": "aigc",
    "task": "multimodal-generation",
    "function": "generation",
    "model": "multimodal-dialog",
    "input": {
      "workspace_id": "Workspace_Id_Example",
      "app_id": "App_Id_Example",
      "directive": "Start"
    },
    "parameters": {
      "upstream": {
        "sample_rate": 16000,
        "type": "AudioAndVideo",
        "mode": "tap2talk",
        "audio_format": "pcm",
        "enable_server_vad_start": false
      },
      "downstream": {
        "voice": "longanhuan",
        "sample_rate": 16000,
        "audio_format": "mp3",
        "volume": 50,
        "speech_rate": 100,
        "pitch_rate": 100,
        "intermediate_text": "transcript,dialog",
        "transmit_rate_limit": 16000
      },
      "client_info": {
        "user_id": "test_1",
        "device": {
          "uuid": "test_1"
        }
      },
      "biz_params": {
        "user_prompt_params": {
          "name": "阿云",
          "skill": "唱歌"
        }
      }
    }
  }
}

1. 切换步骤说明

1. 断开当前连接：客户端主动关闭当前的 WebSocket 连接，并销毁相关实例，释放底层音频双工通道及硬件资源。

2. 更新绑定关系：在本地或业务服务端，将当前用户（UID）绑定的 Role ID 更新为新选定的角色。

3. 加载新配置重连：从角色映射表中提取新角色的 voice 和 user_prompt_params 参数，重新发起 WebSocket 握手建联，并在首帧 run-task 指令中传入新参数。

2. 角色切换业务时序图

客户端 UI             客户端业务层 (SDK)             百炼服务端
   │                       │                             │
   │ 1. 触发切换新角色       │                             │
   ├──────────────────────>│                             │
   │                       │ 2. 主动断开当前连接          │
   │                       ├────────────────────────────>X (断开旧连接)
   │                       │                             │
   │                       │ 3. 读取新角色配置及变量     │
   │                       │    (voice & prompt params)  │
   │                       │                             │
   │                       │ 4. 携新参数发起 WebSocket    │
   │                       ├────────────────────────────>──┐ (重新建联)
   │                       │                               │
   │                       │<──────────────────────────────┘
   │ 5. 提示切换成功       │                             │
   |<──────────────────────┤                             │