Как добавить говорящего AI-персонажа на свой сайт
Добавьте говорящего AI-персонажа на любой сайт: установите Neocortex Web SDK, держите API-ключ на сервере, вставьте элемент голосового чата и обработайте действия.
Sercan AltundasFounder of Neocortex
· 7 мин чтения

Персонаж сайта - это проводник, ведущий или помощник продавца, с которым посетители могут говорить своими словами: с личностью и голосом, а не с безликим окошком чата. Этот гид показывает, как добавить такого персонажа на любой сайт с Neocortex Web SDK: несколько строк на сервере, один элемент на странице и необязательные действия, которые позволяют персонажу что-то делать.
Что вы построите
Персонаж на вашей странице, который:
- отвечает на вопросы, написанные или произнесенные, своим голосом
- знает ваш контент из загруженной базы знаний
- может выполнять действия на странице, например открыть товар или начать экскурсию
- никогда не раскрывает ваш API-ключ браузеру
Что вам нужно
- Аккаунт Neocortex, API-ключ и персонаж из панели
- Сервер с Node 20 или новее, либо Cloudflare Workers, Bun или Deno
- Страница, открытая по HTTPS, поскольку браузеры разрешают микрофон только на защищенных страницах
Шаг 1: спроектируйте персонажа
В редакторе Neocortex дайте персонажу личность, голос и базу знаний с вашими страницами товаров, FAQ или заметками об экскурсии. Тестируйте его в браузере, пока он не будет звучать правильно: тестирование в редакторе включено на каждом тарифе. Скопируйте ID персонажа из панели.
Шаг 2: установите SDK
Выполните npm install @neocortex-link/web в проекте вашего сайта.
Шаг 3: добавьте прокси на сервер
Ключи API Neocortex секретны. Любой, кто прочитает ключ из 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. На сайтах без входа можно выдавать каждому посетителю стабильный id в подписанном cookie.
Шаг 4: разместите персонажа на странице
Загрузите интерфейс один раз командой import "@neocortex-link/web/ui/auto" (или из тега script CDN, если на сайте нет сборщика), а затем поставьте элемент там, где должен появляться персонаж:
<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).
Шаг 5: позвольте персонажу действовать
Определите действия в редакторе, например OPEN_PRODUCT или START_TOUR, а затем обработайте их на странице:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct - ваша собственная функция. Персонаж решает, когда действие подходит разговору, а ваш код решает, что оно делает.
Идеи для персонажей сайта
- Гид по товару в 3D-конфигураторе, который объясняет опции и меняет цвета по запросу.
- Ведущий мероприятия, который отвечает на вопросы о расписании и направляет посетителей к нужной сцене.
- Персонаж музея или бренда, который рассказывает истории из вашего архива своим голосом.
- Лендинг игры, где посетители могут поговорить с персонажами игры, прежде чем купить.
Наши гиды по вариантам использования подробнее описывают AI-гиды по покупкам для 3D-магазинов в вебе и AI-ведущих для виртуальных мероприятий.
Частые проблемы
- Микрофон не запускается. Браузеры требуют HTTPS и нажатия или касания перед записью. Проверяйте на своем реальном домене, а не на обычном превью по HTTP.
- 401 или 403 от эндпоинта.
authorizeвернулnull, или ID персонажа нет в спискеcharacters. - Ключ попал в браузер. Никогда не передавайте его клиентскому коду. Только серверный обработчик должен читать
NEOCORTEX_API_KEY.
Следующие шаги
Для игровых движков вместо сайтов начните с как добавить AI-персонажа в вашу игру на Unity. Чтобы понять голосовую часть, прочитайте как работает голосовой конвейер AI NPC. Каждый урок серии есть в гиде по созданию AI NPC, а полная настройка описана в документации Web SDK.
Частые вопросы
Как добавить AI-персонажа с голосом на свой сайт?
Установите Neocortex Web SDK, добавьте его небольшой прокси на сервер, чтобы API-ключ оставался закрытым, а затем разместите на странице элемент neocortex-chat с атрибутом voice. Посетители могут писать или говорить, а персонаж отвечает вслух.
Можно ли поставить 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, а затем зарегистрируйте обработчик для каждого на странице, например чтобы открыть товар, начать экскурсию или прокрутить к разделу.






