Jak dodać mówiącą postać AI do swojej strony
Dodaj mówiącą postać AI do dowolnej strony: zainstaluj Neocortex Web SDK, trzymaj klucz API na serwerze, wstaw element czatu głosowego i obsłuż akcje.
Sercan AltundasFounder of Neocortex
· 7 min czytania

Postać na stronie to przewodnik, gospodarz albo asystent sklepu, z którym odwiedzający mogą rozmawiać własnymi słowami, z osobowością i głosem, zamiast z ogólnym dymkiem czatu. Ten poradnik pokazuje, jak dodać taką postać do dowolnej strony przy użyciu Neocortex Web SDK: kilka linijek na serwerze, jeden element na stronie i opcjonalne akcje, dzięki którym postać może coś zrobić.
Co zbudujesz
Postać na twojej stronie, która:
- odpowiada na pytania wpisane lub wypowiedziane własnym głosem
- zna twoje treści z bazy wiedzy, którą wgrywasz
- może wykonywać akcje na stronie, na przykład otworzyć produkt albo rozpocząć wycieczkę
- nigdy nie ujawnia twojego klucza API przeglądarce
Czego potrzebujesz
- Konta Neocortex, klucza API i postaci z panelu
- Serwera z Node 20 lub nowszym albo Cloudflare Workers, Bun czy Deno
- Strony obsługiwanej przez HTTPS, bo przeglądarki zezwalają na mikrofon tylko na bezpiecznych stronach
Krok 1: zaprojektuj postać
W edytorze Neocortex nadaj postaci osobowość, głos i bazę wiedzy z twoimi stronami produktów, FAQ lub notatkami do wycieczki. Testuj ją w przeglądarce, aż brzmi dobrze: testowanie w edytorze jest w każdym planie. Skopiuj identyfikator postaci z panelu.
Krok 2: zainstaluj SDK
Uruchom npm install @neocortex-link/web w projekcie swojej strony.
Krok 3: dodaj proxy na serwerze
Klucze API Neocortex są tajne. Ktokolwiek odczyta klucz z JavaScriptu twojej strony, może podbić zużycie na twoim koncie, dlatego SDK zawiera mały handler serwerowy, który przechowuje klucz. Sprawdza też, kto rozmawia, i pozwala tylko na postaci, które wymienisz.
W aplikacji Next.js utwórz 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 zwraca odwiedzającego jako { id } albo null, by odmówić dostępu. Ten identyfikator staje się playerId postaci, więc każdy odwiedzający ma własną rozmowę. W Express owiń ten sam handler w toNodeHandler i podłącz go pod /api/neocortex. Strony bez logowania mogą wydać każdemu odwiedzającemu stały identyfikator w podpisanym ciasteczku.
Krok 4: umieść postać na stronie
Załaduj interfejs raz przez import "@neocortex-link/web/ui/auto" (albo tagiem skryptu z CDN, jeśli twoja strona nie ma bundlera), a potem umieść element tam, gdzie ma się pojawiać postać:
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>Czat ma pole tekstowe i wejście z mikrofonu. Atrybut voice dodaje odpowiedzi głosowe: każda kwestia jest strumieniowana jako mowa, a następna jest pobierana, gdy bieżąca już gra. Dodaj push-to-talk, jeśli odwiedzający mają przytrzymywać przycisk podczas mówienia, albo mic="false" dla samego tekstu.
Elementy to standardowe Web Components, więc działają w React, Vue, Svelte, Angular lub zwykłym HTML, a wygląd możesz zmienić przez właściwości CSS w trybie jasnym lub ciemnym. Są też elementy do czatu grupowego z kilkoma postaciami (plany Pro i Team) oraz gospodarza quizu (plan Team).
Krok 5: pozwól postaci działać
Zdefiniuj akcje w edytorze, na przykład OPEN_PRODUCT albo START_TOUR, a potem obsłuż je na stronie:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct to twoja własna funkcja. Postać decyduje, kiedy akcja pasuje do rozmowy, a twój kod decyduje, co ona robi.
Pomysły na postacie na stronach
- Przewodnik po produkcie w konfiguratorze 3D, który wyjaśnia opcje i zmienia kolory na prośbę.
- Gospodarz wydarzenia, który odpowiada na pytania o harmonogram i kieruje odwiedzających na właściwą scenę.
- Postać muzeum albo marki, która opowiada historie z twojego archiwum własnym głosem.
- Strona docelowa gry, na której odwiedzający mogą porozmawiać z postaciami gry, zanim kupią.
Nasze poradniki o przypadkach użycia omawiają głębiej przewodniki zakupowe AI dla sklepów 3D w sieci i AI jako gospodarze wydarzeń wirtualnych.
Częste problemy
- Mikrofon się nie uruchamia. Przeglądarki wymagają HTTPS i kliknięcia albo dotknięcia przed nagrywaniem. Testuj na swojej prawdziwej domenie, a nie na podglądzie przez zwykły HTTP.
- 401 lub 403 z endpointu.
authorizezwróciłonullalbo identyfikator postaci nie znajduje się na liściecharacters. - Klucz trafił do przeglądarki. Nigdy nie przekazuj go do kodu klienta. Tylko handler serwerowy powinien odczytywać
NEOCORTEX_API_KEY.
Kolejne kroki
Jeśli zamiast strony budujesz grę w silniku, zacznij od jak dodać postać AI do gry w Unity. Aby zrozumieć stronę głosową, przeczytaj jak działa potok głosowy AI NPC. Każdy poradnik z serii znajdziesz w przewodniku po budowaniu AI NPC, a pełna konfiguracja jest w dokumentacji Web SDK.
Najczęściej zadawane pytania
Jak dodać postać AI z głosem do mojej strony?
Zainstaluj Neocortex Web SDK, dodaj jego małe proxy do serwera, aby klucz API pozostał prywatny, a potem umieść na stronie element neocortex-chat z atrybutem voice. Odwiedzający mogą pisać albo mówić, a postać odpowiada na głos.
Czy mogę umieścić na stronie chatbota AI bez ujawniania klucza API?
Tak. Neocortex Web SDK zawiera handler serwerowy, który przechowuje klucz, sprawdza, kto rozmawia, i pozwala tylko na wymienione przez ciebie postacie. Przeglądarka rozmawia wyłącznie z twoim własnym endpointem.
Czy to działa z React, Vue albo WordPress?
Interfejs czatu składa się ze standardowych Web Components, więc działa w React, Vue, Svelte, Angular i zwykłym HTML. Każda strona, która może uruchomić mały endpoint serwerowy, jak Next.js, Express czy Cloudflare Workers, może hostować proxy.
Czy Neocortex Web SDK jest darmowy?
SDK jest open source na licencji Apache-2.0. Rozmowy liczą się do twojego planu Neocortex.
Czy postać może robić rzeczy na stronie?
Tak. Zdefiniuj akcje dla postaci w edytorze Neocortex, a potem zarejestruj na stronie obsługę każdej z nich, na przykład otwarcie produktu, rozpoczęcie wycieczki albo przewinięcie do sekcji.






