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

网络和 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:

Connect 响应字段
运行时用途

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 团队一起逐项完成此清单。

  1. 确认出站 TCP 443 为 realtime-api.convai.com 和 api.convai.com.

  2. 确认出站 TCP 443 为 convai-technologies-lfslae7c.livekit.cloud, *.livekit.cloud,以及 *.turn.livekit.cloud.

  3. 当允许 UDP 时,请允许 UDP 3478 为 *.host.livekit.cloud 和出站 UDP 50000–60000.

  4. 如果你的代理对 HTTPS 或 WSS 流量执行中间人解密,请将 Convai 和 LiveKit 主机名从 TLS 检查中排除。

  5. 进入编辑器内运行并确认 已调用 OnConnectedToServer,SessionID: 出现在以下输出日志类别中: ConvaiSubsystemLog.

  6. 调用 获取聊天机器人连接状态 在 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 连接测试成功

下一步

确认网络要求后,请安装插件或查看连接故障排除。

安装 Convai 插件连接和 API 密钥问题

最后更新于

这有帮助吗?