Neocortex Logo

如何为网站添加会说话的 AI 角色

为任意网站添加会说话的 AI 角色:安装 Neocortex Web SDK,将 API 密钥保留在服务器上,放入语音聊天元素,并处理角色动作。

Sercan AltundasFounder of Neocortex

· 阅读约 7 分钟

为任意网站添加会说话的 AI 角色:安装 Neocortex Web SDK,将 API 密钥保留在服务器上,放入语音聊天元素,并处理角色动作。

网站角色可以是向导、主持人或店铺助手,访客可以用自己的话与它交谈。它有性格、有声音,而不是一个通用的聊天气泡。本指南说明如何使用 Neocortex Web SDK 为任何网站添加一个角色:服务器上的几行代码,页面上的一个元素,以及让角色执行操作的可选动作。

你将构建什么

页面上的一个角色,它能够:

  • 用自己的声音回答访客输入或说出的问题
  • 了解你的内容,来自你上传的知识库
  • 在页面上执行动作,例如打开一件商品或开始一段导览
  • 绝不向浏览器暴露你的 API 密钥

你需要准备什么

  • 一个 Neocortex 账户、一个 API 密钥,以及在控制台中创建的一个角色
  • 一台运行 Node 20 或更高版本的服务器,或 Cloudflare Workers、Bun 或 Deno
  • 通过 HTTPS 提供的页面,因为浏览器只允许在安全页面上使用麦克风

第一步:设计角色

在 Neocortex 编辑器中,为角色设定性格、声音,并用你的产品页面、常见问题或导览说明建立知识库。在编辑器中反复测试,直到听起来正确为止:编辑器内测试包含在每个套餐中。从控制台复制角色的 ID。

第二步:安装 SDK

在你网站的项目中运行 npm install @neocortex-link/web。

第三步:在服务器上添加代理

Neocortex API 密钥属于机密信息。任何人只要从你页面的 JavaScript 中读取到密钥,就能消耗你账户的用量,因此 SDK 提供了一个小型服务器处理程序来保管密钥。它还会检查谁在对话,并且只允许你列出的角色。

在 Next.js 应用中,创建 app/api/neocortex/[...path]/route.ts:

import { createNeocortexHandler } from "@neocortex-link/web/server";
import { auth } from "@/auth";

const handler = createNeocortexHandler({
  apiKey: process.env.NEOCORTEX_API_KEY!,
  characters: ["your-character-id"],
  authorize: async () => {
    const session = await auth();
    return session?.user ? { id: session.user.id } : null;
  },
});

export { handler as GET, handler as POST, handler as OPTIONS };

authorize 以 { id } 的形式返回访客信息,或返回 null 以拒绝访问。该 ID 会成为角色的 playerId,因此每位访客都有自己的对话。如果使用 Express,请用 toNodeHandler 包装同一个处理程序,并挂载到 /api/neocortex。没有登录功能的网站,可以通过签名 Cookie 为每位访客分配一个稳定的 ID。

第四步:将角色放到页面上

使用 import "@neocortex-link/web/ui/auto" 加载一次界面(如果你的网站没有打包工具,则可以使用 CDN 的 script 标签),然后将元素放在角色应该出现的位置:

<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>

聊天界面带有文本输入框和麦克风输入。voice 属性会添加语音回复:每句台词都以语音流式输出,并且在当前这句播放时,就会提前获取下一句。如果希望访客在说话时按住按钮,请添加 push-to-talk;如果只需要文字,则使用 mic="false"。

这些元素是标准的 Web Components,因此可以在 React、Vue、Svelte、Angular 或纯 HTML 中使用,并且可以通过 CSS 自定义属性在浅色或深色模式下重新设置样式。此外,还提供与多个角色进行群聊的元素(Pro 和 Team 套餐),以及问答主持人元素(Team 套餐)。

第五步:让角色执行动作

在编辑器中定义动作,例如 OPEN_PRODUCT 或 START_TOUR,然后在页面中处理它们:

const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));

openProduct 是你自己的函数。角色决定何时动作适合当前对话,而你的代码决定动作具体做什么。

网站角色的创意

  • 产品向导:在 3D 配置器中,解释各项选项,并在被询问时切换颜色。
  • 活动主持人:回答日程问题,并把访客引导到正确的舞台。
  • 博物馆或品牌角色:以自己的声音讲述你档案中的故事。
  • 游戏的落地页:访客在购买前即可与游戏中的角色对话。

我们的用例指南对 3D 网络商店的 AI 导购和虚拟活动的 AI 主持人有更深入的介绍。

常见问题排查

  • 麦克风无法启动。 浏览器要求使用 HTTPS,并且需要先点击或轻触才能录音。请在你的真实域名上测试,而不是在普通 HTTP 预览中测试。
  • 端点返回 401 或 403。 要么 authorize 返回了 null,要么角色 ID 不在 characters 列表中。
  • 密钥出现在了浏览器中。 绝不要把它传给客户端代码。只有服务器处理程序应该读取 NEOCORTEX_API_KEY。

后续步骤

如果你要为游戏引擎而非网站添加角色,请先阅读如何为 Unity 游戏添加 AI 角色。要了解语音部分,请阅读 AI NPC 语音管线的工作原理。系列中的每篇教程都列在 制作 AI NPC 指南中,完整的设置步骤见 Web SDK 文档。

常见问题

如何在我的网站上添加带语音的 AI 角色?

安装 Neocortex Web SDK,在服务器上添加其小型代理,以确保 API 密钥保持私密,然后在页面上放置一个带有 voice 属性的 neocortex-chat 元素。访客可以打字或开口说话,角色会大声回答。

能在网站上放 AI 聊天机器人而不暴露 API 密钥吗?

可以。Neocortex Web SDK 包含一个保管密钥的服务器处理程序,它会检查谁在对话,并且只允许你列出的角色。浏览器只会与你自己的端点通信。

能与 React、Vue 或 WordPress 一起使用吗?

聊天界面由标准的 Web Components 构成,因此可以在 React、Vue、Svelte、Angular 和纯 HTML 中使用。任何能够运行小型服务器端点的网站,例如 Next.js、Express 或 Cloudflare Workers,都可以托管该代理。

Neocortex Web SDK 免费吗?

SDK 是基于 Apache-2.0 许可证的开源软件。对话计入你的 Neocortex 套餐用量。

角色能在页面上执行操作吗?

可以。在 Neocortex 编辑器中为角色定义动作,然后在页面中为每个动作注册一个处理程序,例如打开商品、开始导览或滚动到某个章节。

相关文章

继续阅读