网络和 API 要求
Convai Unreal Engine 插件网络访问参考,包括 Convai 和 LiveKit 主机、防火墙规则、认证以及会话日志检查。
Convai Unreal Engine 插件在运行时需要出站互联网访问。会话设置使用 Convai HTTPS 端点,实时音频和数据则通过由捆绑 WebRTC 客户端管理的 LiveKit 房间传输。准备企业网络、验证防火墙允许列表,或确认编辑器内运行能否成功连接 Convai 时,请使用本页面。
所需的出站访问
运行时会话使用 Convai HTTPS 端点以及会话设置后使用的 LiveKit 主机。请允许运行 Unreal Engine 的计算机向以下主机发起出站流量。
Convai 端点
realtime-api.convai.com
443
HTTPS
实时连接 — 默认 URL https://realtime-api.convai.com/connect
api.convai.com
443
HTTPS
角色数据、REST API 和编辑器网络诊断
通过以下方式覆盖实时端点 编辑 > 项目设置 > 插件 > Convai > 自定义 URL,或者使用以下参数启动编辑器 -ConvaiStreamURL= 在针对非默认连接 URL 测试时。
LiveKit 最低要求
Convai 接受连接请求后,原生 WebRTC 客户端会加入 LiveKit 房间。LiveKit Cloud 连接的最低出站规则:
convai-technologies-lfslae7c.livekit.cloud
443
TCP
Convai LiveKit 信令端点
*.livekit.cloud
443
TCP
LiveKit WebSocket 信令
*.turn.livekit.cloud
443
TCP
当 UDP 被阻止时的 TURN/TLS 回退
可选的直连媒体路径
LiveKit 为直接 WebRTC 媒体和 TCP 回退记录了这些路径。当你的网络策略允许 UDP,或者 LiveKit 连接测试显示最低 TCP 规则还不够时,请添加它们。
*.host.livekit.cloud
3478
UDP
TURN/UDP 连接
所有 LiveKit 主机
50000–60000
UDP
WebRTC 媒体传输
所有 LiveKit 主机
7881
TCP
WebRTC TCP 回退
客户端计算机不需要入站端口。公开的 Unreal 插件源代码不提供单独的 TURN、STUN、WSS 或 UDP 设置 — 捆绑的 ConvaiWebRTC 客户端会在连接后选择传输路径。有关完整的 LiveKit 防火墙参考,请参阅 配置防火墙 在 LiveKit 文档中。
实时会话如何连接
每个角色会话都遵循以下流程:
Connect API 返回与以下文档中相同的房间字段: Connect API:
session_id
用于实时会话的 Convai 会话 ID
character_session_id
重连期间的会话连续性
room_url
LiveKit WebSocket 端点 — 例如 wss://convai-technologies-lfslae7c.livekit.cloud
room_name
客户端加入的 LiveKit 房间名称
token
用于加入房间的临时 LiveKit 房间令牌
Unreal 插件会在内部将连接凭据传递给原生 WebRTC 客户端。公开插件源代码不会读取或记录 room_url, room_name,或 token 直接 — 这些值在内部处理 ConvaiWebRTC 在 HTTPS 连接步骤完成后。示例主机 convai-technologies-lfslae7c.livekit.cloud 是一个 Convai 部署;您的会话可能会收到不同的 room_url 随着时间推移。
身份验证
运行时会话涉及两种凭据类型。
API 密钥
您的项目 API 密钥用于验证对 Convai 的请求。请通过 Convai 编辑器窗口(窗口 > 打开 Convai 编辑器)进行配置。该密钥存储在 UConvaiSettings.API_Key 中,并显示在 编辑 > 项目设置 > 插件 > Convai > API 密钥.
HTTPS REST(api.convai.com)
CONVAI-API-KEY
角色元数据、长期记忆以及其他 REST 调用
实时连接
X-API-Key
启动实时会话 — 子系统会重新映射 CONVAI-API-KEY 为 X-API-Key 然后再调用 WebRTC 客户端
当 API_Key 为空且已在以下位置配置个人访问令牌时 UConvaiSettings.AuthToken,实时连接会改用 API-AUTH-TOKEN 。请参阅 个人访问令牌.
LiveKit 房间令牌
每个成功的连接响应都包含一个临时的 token。原生 WebRTC 客户端使用此令牌加入 LiveKit 房间。该令牌有效期很短,且仅授予访问该房间的权限。请将其视为密码 — 不要在公共论坛、支持工单或版本控制系统中分享。
在日志中查找连接详情
公开的 Unreal 插件源代码不会在输出日志中打印 token, room_url,或 room_name 。房间加入详情由原生 WebRTC 客户端在内部处理。请使用以下日志确认 Convai 已接受该会话。
确认实时连接 URL
连接时,子系统会在以下日志类别下记录流 URL 和角色 ID: ConvaiSubsystemLog:
在输出日志中搜索 StreamURL ,以确认插件使用了哪个连接端点。
确认连接后的会话 ID
当 WebRTC 客户端成功连接时,子系统会记录 Convai 会话标识符:
SessionID
用于实时会话的 Convai 会话 ID
CharSessionID
用于保持对话连续性的 Convai 角色会话 ID
启用 详细 为以下项启用日志记录: ConvaiClientLog 以显示通过以下项转发的其他原生 WebRTC 客户端消息: OnLog.
有关完整的诊断导出步骤,请参阅 诊断和日志导出.
测试 LiveKit 连接
使用 LiveKit 连接测试 ,以便确认受限网络能否访问特定的 LiveKit 房间。
LiveKit URL
room_url 来自 Convai 连接响应
Room Token
token 来自 Convai 连接响应
公开的 Unreal 插件日志不会打印 room_url 或 token。如果您从支持诊断、自定义诊断构建或其他可信内部来源获取这些值,请粘贴 room_url 到 LiveKit URL,粘贴 token 到 Room Token,然后选择 运行测试。此测试会验证该临时房间的 LiveKit 信令和 WebRTC 连接。它不会验证您的 Convai API 密钥、 api.convai.com,或 CharacterID 配置。
防火墙验证清单
在部署到受限环境之前,请与网络或 IT 团队一起逐项完成此清单。
确认出站 TCP
443为realtime-api.convai.com和api.convai.com.确认出站 TCP
443为convai-technologies-lfslae7c.livekit.cloud,*.livekit.cloud,以及*.turn.livekit.cloud.当允许 UDP 时,请允许 UDP
3478为*.host.livekit.cloud和出站 UDP50000–60000.如果你的代理对 HTTPS 或 WSS 流量执行中间人解密,请将 Convai 和 LiveKit 主机名从 TLS 检查中排除。
进入编辑器内运行并确认
已调用 OnConnectedToServer,SessionID:出现在以下输出日志类别中:ConvaiSubsystemLog.调用 获取聊天机器人连接状态 在
Convai 聊天机器人组件,并确认状态变为已连接.
如果第 5 步或第 6 步失败,请参阅 连接和 API 密钥问题.
故障排除
所有请求均超时
Convai 端点在 TCP 上被阻止 443
允许 realtime-api.convai.com 和 api.convai.com
获取聊天机器人连接状态 返回 已连接
无法建立连接 使用有效的 API 密钥
连接后 LiveKit 主机被阻止
请从本页添加 LiveKit 最低规则和可选的直连媒体路径
OnConnectedToServer 日志出现;角色在 Play 模式中有响应
未在以下时间内收到 bot-ready 超时
网络缓慢或 WebRTC 路径被阻止
确认 LiveKit 防火墙规则;验证 CharacterID 在仪表板上
会话在客户端就绪超时期限内变为就绪
没有 OnConnectedToServer 日志行
会话从未到达 WebRTC 层
通过 Convai 编辑器窗口确认 API 密钥;验证 CharacterID 在 Convai 聊天机器人 组件
开始运行后出现日志行
项目设置中的 API 密钥字段为空
未通过 Convai 编辑器窗口保存密钥
打开 窗口 > 打开 Convai 编辑器,登录并保存密钥
API 密钥 项目设置中的字段已填充
使用有效房间详情时 LiveKit 连接测试失败
UDP 媒体或 TURN 回退路径被阻止
允许 UDP 50000–60000、UDP 3478 为 *.host.livekit.cloud和 TCP 443 为 *.turn.livekit.cloud
使用相同房间详情时 LiveKit 连接测试成功
下一步
确认网络要求后,请安装插件或查看连接故障排除。
最后更新于
这有帮助吗?