在一个房间中托管多个角色
将一组 Convai 角色连接到一个实时房间,选择由哪个角色回答,实时更改角色列表,并允许第二个人加入。
在一个实时房间中容纳多个角色,并且无需重新连接即可与其中任意一个对话。请在有多于一位说话者的场景中使用此页,例如向导和评估者、面试小组,或一组 NPC。
roster 房间的工作方式
房间中的每个角色都是独立参与者,拥有自己的声音、对话历史和生命周期。房间是共享的;角色状态不是共享的。
你通过传入一个有顺序的 characters 数组而不是 characterId来创建房间。每个条目都会成为 roster 的一个成员:
characters[0]是初始活动成员,也就是第一个回答的成员。同一个
characterId可以出现不止一次。每个条目都是一个独立副本,拥有自己的历史和声音。每个成员都会获得一个
membershipId。应通过membershipId来称呼成员,绝不要通过characterId,因为一个角色的两个副本共享一个characterId.
roster 房间需要实时(WebRTC)传输以及一个非空的 endUserId.
使用 roster 连接
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 一起触发。
让另一位用户加入
第二个人通过 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 的音频轨道归属给拥有它的成员。
完整事件列表请参见 事件参考.
最后更新于
这有帮助吗?