For the complete documentation index, see llms.txt. This page is also available as Markdown.

在一个房间中托管多个角色

将一组 Convai 角色连接到一个实时房间,选择由哪个角色回答,实时更改角色列表,并允许第二个人加入。

在一个实时房间中容纳多个角色,并且无需重新连接即可与其中任意一个对话。请在有多于一位说话者的场景中使用此页,例如向导和评估者、面试小组,或一组 NPC。

roster 房间的工作方式

房间中的每个角色都是独立参与者,拥有自己的声音、对话历史和生命周期。房间是共享的;角色状态不是共享的。

你通过传入一个有顺序的 characters 数组而不是 characterId来创建房间。每个条目都会成为 roster 的一个成员:

  • characters[0] 是初始活动成员,也就是第一个回答的成员。

  • 同一个 characterId 可以出现不止一次。每个条目都是一个独立副本,拥有自己的历史和声音。

  • 每个成员都会获得一个 membershipId。应通过 membershipId来称呼成员,绝不要通过 characterId,因为一个角色的两个副本共享一个 characterId.

roster 房间需要实时(WebRTC)传输以及一个非空的 endUserId.

使用 roster 连接

src/App.tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

const GUIDE = 'YOUR_CHARACTER_ID';
const ASSESSOR = 'YOUR_SECOND_CHARACTER_ID';

export default function App() {
  const client = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    endUserId: 'player-42',
    characters: [
      { characterId: GUIDE },     // characters[0] 先回答
      { characterId: ASSESSOR },
      { characterId: GUIDE },     // 向导的第二个独立副本
    ],
    maxNumParticipants: 2,
  });

  const { characters, activeMembershipId } = client.state;

  return (
    <div>
      <ul>
        {characters.map((c) => (
          <li key={c.membershipId}>
            {c.displayName ?? c.membershipId.slice(0, 8)} · {c.provisioningStatus}
            {c.membershipId === activeMembershipId && ' · active'}
            {c.failureCode && ` · failed: ${c.failureCode}`}
          </li>
        ))}
      </ul>
      <ConvaiWidget convaiClient={client} />
    </div>
  );
}
  • characters 和 characterId 彼此互斥。两者同时传入会在发送任何请求之前抛错。

  • roster 条目使用的是纯角色 UUID。诸如 characterId 接受的版本选择器,例如 <uuid>-draft 或 <uuid>-1.2,在 roster 中会被拒绝。

  • characterSessionId 在条目上设置会恢复该成员之前的历史。它在 roster 中必须唯一。

  • client.characterId 和 client.characterSessionId 对应 characters[0].

  • sharedSessionKey 将请求分组到一个房间中:匹配的创建请求会复用现有房间。

区分成员

client.characters (以及 client.state.characters 在 React 中)按顺序列出 roster。在单角色会话中它是空的,因此检查其长度即可区分二者。每个条目都是一个 ConvaiCharacterInstance ,携带其 membershipId, characterId, displayName (当运行时发送该字段时)及其状态。

成员产生的一切都会通过 membershipId归属,因此一个角色的两个副本永远不会合并:

  • 转写消息携带 membershipId 和 characterId.

  • characterAudioTrack 会标明每个音频轨道归属的成员。

  • characterReady 会传入变为就绪的成员。

就绪不是派发

provisioningStatus 只描述派发: dispatch_queued, dispatch_accepted 或 dispatch_failed. dispatch_accepted 并不意味着已就绪。成员在自己的就绪信号到达后才可用,这会设置 isReady 为 true 并触发 characterReady.

characterStatus 会报告运行时添加的成员以及后台派发失败的成员。不要仅凭一个 ready 状态就启用交互;要等待 characterReady.

播放每个成员的音频

内置组件会渲染一份共享转写记录,按消息归属,并播放每个成员的音频。若要为每个角色分别显示一个面板,请从 characterAudioTrack自行绑定音频。该事件在 roster 房间中总会标明所属成员,而无法归属到某个成员的轨道会被丢弃。

静音一个成员

传入一个 membershipId 为 setCharacterMuted 即可让一个成员静音并保留其他成员可听。若不传该值,会让房间中的每个角色都静音。参见 将角色的声音静音.

切换由谁回答

只有活动成员会接收用户回合。调用 setInteractionTarget 并传入一个 membershipId ,然后再把下一条消息导向别处。

应从 activeCharacterChange 渲染活动成员,而不是依赖你自己的调用,因为房间中的另一位参与者也可以切换目标。

  • setInteractionTarget(null) 会关闭所有闸门。在你再次设置目标之前,没有成员会听到用户。

  • 尚未就绪的目标会在命令发送前被拒绝。

  • 如果另一位参与者先切换了,调用会基于服务器当前状态重试一次。

动态添加和移除成员

updateCharacterRoster 会更改已连接房间的 roster。 remove 接受的是 membership id,而不是 character id。

  • 移除活动成员需要一个已就绪且留在房间中的替代者。若不传 replacementTarget.

  • ,系统会自动选择一个。新成员在各自发送就绪信号之前不能被呼叫。请关注 characterReady.

  • 房间不能被清空。

  • 如果另一位参与者先更改了 roster,该调用会以冲突错误拒绝,供你自行协调。它不会重试。

  • rosterChange 会随着新增和移除的成员,以及更改后的 roster 一起触发。

丢失确认不算失败。当服务器的确认丢失时,Promise 会拒绝并提示结果未知。在发送冲突命令之前,请读取 client.roomSession 以查看实际发生了什么。

让另一位用户加入

第二个人通过 roomSessionId 或通过 sharedSessionKey加入第一个人创建的房间。加入不会发送 roster:roster 属于服务器,且加入操作绝不会添加、移除或修复某个角色。

  • 只传入一个定位符。 roomSessionId 优先使用

  • endUserId 是必需的。

  • 容量按 endUserId 区分不同的人数来计算,默认值为 1。请在创建房间时设置 maxNumParticipants ,否则加入会失败并返回 409 Human room capacity reached。同一个人重新连接不会占用另一个名额。

限制

  • 仅支持实时传输。 roster 房间不在 WebSocket 或 SSE 传输上运行。参见 选择传输方式.

  • 不支持动作协议 v2 或客户端工具。 capabilities.actionProtocolVersion: 2 (或 modelOutputVersion: 2)需要单角色房间,因此 actionConfig.tools 也不可用。版本 1 可用。SDK 会在发送请求前拒绝这种组合。

  • resetSession() 会抛出 在 roster 房间中,因为服务器拥有每个成员的会话。

  • 复用一个 sharedSessionKey 并使用不同的有序 roster、创建者或容量会失败,返回 ROSTER_FINGERPRINT_MISMATCH。即使只是重排同样的角色也算不同,因为它会改变初始成员。

  • 派发重试。 当相同请求仍在创建房间时,SDK 会以有限退避进行重试。传入 rosterProvisioningRetry: false 即可自行处理 ROSTER_PROVISIONING_IN_PROGRESS 。

错误

一个 roster connect() 和 joinRoom() 会抛出 ConvaiRoomError 当房间无法创建或无法加入时。它包含 状态, code, requestTraceId, detail 和 isRetryable。联系支持时请包含 requestTraceId 。

代码
状态
含义

MULTI_CHARACTER_V0_DISABLED

403

你的账户未启用多角色房间。

MULTI_CHARACTER_ROSTER_LIMIT_EXCEEDED

403

roster 大小超过了你的账户允许的上限。

CHARACTER_NOT_FOUND_OR_INACCESSIBLE

404

roster 条目指定了你无法使用的角色。

ROSTER_FINGERPRINT_MISMATCH

409

一个 sharedSessionKey 被复用时使用了不同的 roster、创建者或容量。

ROSTER_PROVISIONING_IN_PROGRESS

409

房间仍在创建中。已自动重试。

已达到人类房间容量上限

409

该房间已容纳 maxNumParticipants 人。

API 参考

属性 / 方法
类型
说明

characters (配置)

ConvaiCharacterSpec[]

有序 roster,传入时替代 characterId。每个条目是 { characterId, characterSessionId? }.

sharedSessionKey (配置)

字符串

将创建请求分组到一个房间中;同时也是一个加入定位符。

connectAttemptId (配置)

字符串

一次逻辑连接的幂等键。只有在重试相同请求时才复用它。

maxNumParticipants (配置)

number

房间中最多不同的人数。角色不计入。默认值 1。

rosterProvisioningRetry (配置)

{ attempts?, initialDelayMs? } | false

在房间处于 provisioning 时重试。默认从 500 ms 开始共四次尝试。

characters

ConvaiCharacterInstance[]

按顺序排列的 roster。在单角色会话中为空。也存在于 状态.

activeMembershipId

string | null

当前接收用户回合的成员。也存在于 状态.

roomSession

ConvaiRoomSession | null

服务器拥有的房间快照: roomSessionId, activeMembershipId, routeEpoch, rosterEpoch, partialDispatch, characters。在单角色会话中为 null。

setInteractionTarget(membershipId)

(membershipId: string | null) => Promise<ActiveCharacterChange>

将后续用户回合路由给另一个成员。 null 关闭所有闸门。

updateCharacterRoster(options)

(options: UpdateCharacterRosterOptions) => Promise<CharacterRosterChange>

添加成员(add),按 membership id 移除(remove),并可选指定一个 replacementTarget.

joinRoom(options)

(options: JoinRoomOptions) => Promise<void>

通过 roomSessionId 或 sharedSessionKey加入一个现有房间,需要一个 endUserId.

appendMessage(message)

(message: AppendMessageOptions) => ChatMessage

在本地插入一行转写而不发送它。传入 membershipId 以将其归属给某个成员。

setCharacterMuted(muted, options?)

(muted: boolean, options?: { membershipId?: string }) => void

让每个角色静音,或者让某一个成员静音。

isCharacterMuted(membershipId?)

(membershipId?: string) => boolean

整个房间的设置,或某个成员的实际生效设置。

characterReady (事件)

(instance: ConvaiCharacterInstance | undefined) => void

某个成员发送了它的就绪信号。

characterStatus (事件)

(status: CharacterStatusEvent) => void

某个成员正在 开始, ready 或 失败,附带 failureCode 表示失败原因。

activeCharacterChange (事件)

(change: ActiveCharacterChange) => void

活动成员已更改: 之前, 当前, routeEpoch.

rosterChange (事件)

(change: CharacterRosterChange) => void

roster 已更改: 新增, 移除, characters, activeMembershipId.

characterAudioTrack (事件)

(event: CharacterAudioTrackEvent) => void

带有 membershipId 和 characterId 的音频轨道归属给拥有它的成员。

完整事件列表请参见 事件参考.

最后更新于

这有帮助吗?