UI 定制指南#

概述#

本指南将引导您了解如何使用 Tokkio 创建您自己的自定义 UI 设计。在本指南结束时，您将能够理解可用的不同定制选项，并为您的用例实施定制的 UI。

为了遵循本指南，建议您具备一定的 Web 开发经验，并且熟悉 JavaScript 语言。

定制选项#

根据所需的定制级别，有两种方法可以创建自定义 UI

  • 在 Tokkio 参考 UI 中创建自定义布局

  • 从头开始创建新的 UI

本指南的大部分内容都集中在第一个选项上，这是创建完全自定义 UI 的推荐方法。

要了解有关第一个选项的更多信息，创建自定义布局 部分将描述执行此操作的步骤。

对于第二个选项，请访问本页底部的 从头开始创建自定义 UI 部分。

创建自定义布局#

先决条件#

本指南将向您展示如何更新 Tokkio 参考 UI 代码以添加自定义布局。在阅读本节之前，请确保您已完成以下操作

  • 部署了您的 Tokkio 应用程序。

  • 下载了 UI 代码并运行一次，以确保一切端到端工作正常。您应该能够看到和听到头像。确保在开始之前能够与头像进行对话。有关首次从源代码设置 UI 的文档，请参阅此处。

  • 熟悉了 UI 代码库。建议完整阅读本节，并在开始定制之前熟悉 UI 代码的相关部分。

  • 确保您使用的 UI 版本与本文档的版本匹配。本文档假定您正在使用 Tokkio 的 4.1 版本。

Tokkio UI 使用了几种技术，在开始开发之前阅读这些技术将很有用。这些技术是

  • React

  • React Redux

  • Material UI

  • Node Package Manager

本指南假定您已满足先决条件，并且对列出的技术有基本的了解，尤其是 React。

UI 代码结构#

UI 源代码包含在从下载的 NGC 工件中的 src/ 目录中。它将具有以下结构

├── App.jsx
├── applications
│   ├── AbstractTokkioApplication.jsx
│   ├── custom
│   └── qsr
├── config
│   └── config.js
├── connection
│   ├── axios-interceptors
│   └── websocket
├── features
│   ├── asrText
│   ├── avatar-window
│   ├── backdrops
│   ├── conversation-state
│   ├── error
│   ├── feedback
│   ├── manage-roi
│   ├── mic-button
│   ├── reconnect-dialog
│   ├── start-conversation
│   ├── top-bar
│   ├── ttsText
│   └── ui-window
├── index.css
├── index.jsx
├── layouts
│   ├── FullscreenLayout.jsx
│   ├── KioskLayout.jsx
│   └── layoutSlice.jsx
├── logo.svg
├── ngc-background.png
├── nvidia-background.jpeg
├── pages
│   └── ErrorPages.jsx
├── serviceWorker.js
├── session
│   ├── AccessAndIdTokenWrapper
│   ├── AuthorizationCodeWrapper
│   └── sessionSlice.jsx
├── setupTests.js
├── store
│   └── store.jsx
├── theme
│   ├── themeSlice.jsx
│   └── TokkioThemeProvider.jsx
├── trianglify.svg
├── utils
│   ├── Countdown.jsx
│   ├── Snackbar.jsx
│   ├── useInterval.js
│   ├── useQuery.js
│   └── utils.js
└── white-diamond-dark.png

下表列出了不同的代码文件和目录，并解释了其中的代码负责什么

Tokkio UI 代码职责#

代码部分

描述

index.jsx, index.css 文件

index.jsx 是 Tokkio UI 的入口点。它负责初始化主题、通知系统（SnackbarProvider 组件）、路由和授权组件。Authorization 包装器将包含应用程序的大部分代码，并在授权成功后初始化它。

session 目录

session 目录中的代码将每 15 秒调用一次来自 ingress 的 GET /token 端点。一旦从 ingress 成功检索到会话令牌，它将通过初始化 App.jsx 文件来启动应用程序。所有进入 Tokkio 的 API 调用都必须附加来自此令牌调用的会话 Cookie。

App.jsx 文件

此文件初始化 UI 布局和应用程序。根据配置，它将初始化 Kiosk 布局 + 零售应用程序，或全屏布局 + LLM 应用程序。

layouts 目录

这包含 UI 的可用布局。默认情况下可用的两个布局是 Kiosk 和 Fullscreen。可以为自定义用例添加其他布局。

applications 目录

这包含 UI 的可用应用程序。默认情况下可用的两个应用程序是自定义应用程序（由 LLM 应用程序使用）和零售应用程序（在 UI 代码中称为 qsr，快餐服务餐厅是零售用例的示例实现）。相应的应用程序文件夹将包含特定于该应用程序的所有功能、页面和资产。例如，retail 应用程序具有零售触摸菜单的页面。

theme 目录

这包含应用程序其余部分使用的主题。默认主题使用 NVIDIA 配色方案。更新主题不是一个经过测试可以开箱即用的用例，但对于更新应用程序的主题来说是一个很好的开始。

features 目录

这包含任何应用程序或布局之间通用的功能。例如，显示 TTS 和 ASR 文本记录的功能可以被任何应用程序使用。

store 目录

初始化 Redux 存储，用于管理整个应用程序的 Redux 状态树。

connection 目录

用于处理来自 UI 服务器的传入 WebSocket 消息。

pages 目录

包含任何应用程序通用的页面。今天，这只包含错误页面。

config 目录

设置应用程序的默认配置，并处理通过 env-config.js 从 ENV 变量传递的任何配置。

utils 目录

包含 UI 使用的各种实用程序。

创建自定义布局#

要创建定制的 UI，建议在 layouts 目录中创建第三个布局，除了已经存在的两个布局之外。以下是开始的基本步骤

  1. 在 layouts 目录中，创建一个名为 MyCustomLayout.jsx 的文件（您可以随意命名此文件）。

  2. 在此文件中，添加一个返回 <p>Hello World!</p> 的 React 组件。这将最终包含您的应用程序的自定义代码。目前，这可以是一个非常基本的组件。

  3. 在 App.jsx 中，将 KioskLayout 和 FullscreenLayout 的代码替换为您在上一步中创建的自定义组件。您可能会注意到应用程序参数已传递到这些布局中。为了您的定制目的，您的自定义布局中不需要此变量，您可以安全地忽略它。

  4. 完成这些步骤后，您可以使用来自 此处 的步骤运行 UI，并在浏览器启动时看到 Hello World! 出现在浏览器中。

向自定义布局添加功能#

现在您已经设置了自定义布局，是时候开始向其中添加功能了！Tokkio 参考 UI 在 features 目录中包含可用功能的代码。

下表包含当前可用于 Tokkio UI 的功能。请注意，仅支持下面列出的功能。features 目录中有些目录不起作用，这些目录已从下表中排除。

Tokkio UI 代码职责#

组件名称

在 features 目录中的位置

功能描述

AsrStateText

asrText

显示用户语音的文本记录

AvatarWindow

avatar-window

初始化 WebRTC 连接，并显示带有头像的视频

UserAttentionState

conversation-state

为用户状态添加指示器（用户是否正在看摄像头，还是分心？）。请注意，不再支持此目录中的 Bot 状态（头像状态）。

QSRMicButton

mic-button

用于静音/取消静音用户的麦克风

StartConversation

start-conversation

如果用户的摄像头被禁用，您可以使用此按钮显示一个开始/停止按钮，以从 UI 手动启动和停止会话

VideoCaption

ttsText

显示头像语音的文本记录

默认情况下，可用功能与参考 UI 的整体样式要求相匹配。但是，可以通过更改代码中存在的 CSS 代码轻松更新这些组件的外观。如果您不确定某个功能应该如何工作，您可以搜索组件名称的代码，以查看它在现有零售和自定义参考应用程序中的使用方式。

此时，您应该能够通过将可用功能的现有组件与您自己的 React 代码相结合来组合您的自定义布局。

有用的开发工具#

Redux DevTools Chrome 扩展程序 可用于在 UI 运行时查看应用程序的 redux 状态树。

从头开始创建自定义 UI#

概述和警告#

本指南将帮助您开始从头开始创建自己的 UI，但它不是全面的文档。

不建议使用此方法，原因如下

  • UI 与应用程序其余部分之间的接口可能会在大多数版本中更改，恕不另行通知。从头开始构建的 UI 需要在更新 Tokkio 版本时跟上这些接口更改。从参考 UI 中的自定义布局构建将使您免受这些接口更改的影响。

  • 从头开始构建的 UI 将无法开箱即用地利用参考 UI 中提供的预构建功能。每个这些功能都需要在新 UI 中重新实现。

  • 您可能会遇到与不正确使用与 Ingress、Tokkio UI 服务器或 VST 的接口相关的意外错误。

简而言之，参考 UI 为您提供了一种快速设置自定义设计并在各个版本中维护它的方法。从头开始创建 UI 时，将需要额外的努力来创建和维护 UI。

先决条件#

在阅读本节之前，请确保您已完成以下操作

  • 部署了您的 Tokkio 应用程序。

  • 部署了参考 UI 以确保一切端到端工作正常。您应该能够看到和听到头像。确保在开始之前能够与头像进行对话。

  • 熟悉了参考 UI 代码库。即使您不使用此代码，其中一些代码也可能会在您的自定义 UI 中重复使用。在执行这些步骤之前，请阅读创建自定义布局。

本节仅适用于高级用户。要遵循本节，您必须熟悉 VST、Ingress 和 UI 服务器微服务，并对它们的接口有实际的了解。您还必须是一位经验丰富的 Web 开发人员。

UI 工作所需的最低组件#

为了使 UI 连接到 Tokkio 并访问所有功能，它必须实现以下操作

  • 定期调用 Ingress 以获取会话 Cookie

  • 为头像视频连接创建 VST 流媒体库的实例

  • 通过 WebSocket 连接到 UI 服务器，以与 Tokkio 部署进行双向通信（用于获取所有 Tokkio 功能，不是查看头像视频所必需的）

要从 Ingress 获取会话 Cookie，请进行以下 API 调用：GET http(s)://<ingress endpoint>/token。此 API 将返回如下所示的响应：{"token_ttl":"30","token":"77234b6a-89e0-4b37-8bb7-c33e0d2a7183"}。获取令牌并将其作为 Cookie 添加到对 Tokkio 部署的所有后续请求中。Cookie 应采用以下格式：Session=77234b6a-89e0-4b37-8bb7-c33e0d2a7183。为了保持会话处于活动状态，请每 15 秒调用一次此端点，并确保会话 Cookie 存在于这些后续 API 调用中。

获得会话 Cookie 后，通过 VST 流媒体库初始化 VST 连接。有关如何执行此操作的示例，请参阅参考 UI 中的代码（src/features/avatar-window 目录）。vstWebsocketEndpoint 参数应设置为 ws(s)://<ingress endpoint>/vms/ws。

接下来，通过 Ingress 建立与 Tokkio UI 服务器的 WebSocket 连接。连接端点为 ws(s)://<ingress endpoint>/ws。

现在您已经建立了必要的连接，您应该能够看到头像视频并与 UI 服务器通信。有关任何其他功能，请参阅参考 UI，了解这些功能应如何工作。

在本页中