Web Sitenize Konuşan Bir Yapay Zeka Karakteri Nasıl Eklenir
Herhangi bir web sitesine konuşan bir yapay zeka karakteri ekleyin: Neocortex Web SDK'sını kurun, API anahtarını sunucuda tutun, bir ses sohbeti öğesi yerleştirin ve eylemleri yönetin.
Sercan AltundasFounder of Neocortex
· 7 dk okuma

Web sitesi karakteri; ziyaretçilerin kendi sözleriyle konuşabileceği bir rehber, bir sunucu ya da bir mağaza asistanıdır. Genel bir sohbet balonu yerine bir kişiliği ve bir sesi vardır. Bu rehber, Neocortex Web SDK'sı ile herhangi bir siteye nasıl ekleneceğini gösteriyor: sunucuda birkaç satır, sayfada bir öğe ve karakterin iş yapmasını sağlayan isteğe bağlı eylemler.
Ne inşa edeceksiniz
Sayfanızda, şunları yapan bir karakter:
- yazılmış ya da söylenmiş soruları kendi sesiyle yanıtlar
- yüklediğiniz bir bilgi tabanından içeriğinizi bilir
- ürün açma ya da tur başlatma gibi eylemleri sayfada çalıştırabilir
- API anahtarınızı asla tarayıcıya göstermez
Gerekenler
- Bir Neocortex hesabı, bir API anahtarı ve gösterge panelinden bir karakter
- Node 20 veya sonrasını çalıştıran bir sunucu ya da Cloudflare Workers, Bun ya da Deno
- HTTPS üzerinden sunulan bir sayfa; çünkü tarayıcılar mikrofonu yalnızca güvenli sayfalarda açar
Adım 1: karakteri tasarlayın
Neocortex düzenleyicisinde karaktere bir kişilik, bir ses ve ürün sayfalarınız, SSS'leriniz ya da tur notlarınızla bir bilgi tabanı verin. Doğru ses çıkana kadar tarayıcıda test edin: düzenleyici içi test her planda dahildir. Karakterin kimliğini gösterge panelinden kopyalayın.
Adım 2: SDK'yı kurun
Sitenizin projesinde npm install @neocortex-link/web komutunu çalıştırın.
Adım 3: sunucunuza proxy ekleyin
Neocortex API anahtarları gizlidir. Sayfanızın JavaScript'inden bir anahtarı okuyan herkes hesabınızdaki kullanımı artırabilir; bu yüzden SDK, anahtarı tutan küçük bir sunucu işleyicisi ile gelir. Ayrıca kimin konuştuğunu denetler ve yalnızca listelediğiniz karakterlere izin verir.
Bir Next.js uygulamasında app/api/neocortex/[...path]/route.ts dosyasını oluşturun:
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 ziyaretçiyi { id } olarak döndürür ya da reddetmek için null döndürür. Bu kimlik karakterin playerId değeri olur; böylece her ziyaretçi kendi konuşmasını alır. Express için aynı işleyiciyi toNodeHandler ile sarın ve /api/neocortex yoluna bağlayın. Giriş yapılmayan siteler, her ziyaretçiye imzalı bir çerezde kalıcı bir kimlik verebilir.
Adım 4: karakteri sayfaya yerleştirin
Arayüzü bir kez import "@neocortex-link/web/ui/auto" ile yükleyin (sitenizde bir paketleyici yoksa bir CDN script etiketinden) ve karakterin görünmesini istediğiniz yere öğeyi koyun:
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>Sohbet bir metin kutusu ve mikrofon girişiyle gelir. voice özniteliği sesli yanıtları ekler: her satır ses olarak akar ve mevcut satır çalarken bir sonraki satır getirilir. Ziyaretçiler konuşurken düğmeye basılı tutmalıysa push-to-talk ekleyin; yalnızca metin istiyorsanız mic="false" kullanın.
Öğeler standart Web Component'lardir; bu yüzden React, Vue, Svelte, Angular ya da düz HTML ile çalışır ve açık ya da koyu modda CSS özel özellikleriyle yeniden biçimlendirebilirsiniz. Birden fazla karakterli bir grup sohbeti (Pro ve Team planları) ve bir bilgi yarışması sunucusu (Team planı) için de öğeler vardır.
Adım 5: karakterin eylem yapmasına izin verin
Düzenleyicide OPEN_PRODUCT ya da START_TOUR gibi eylemleri tanımlayın, sonra sayfada bunları yönetin:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct sizin kendi fonksiyonunuzdur. Karakter bir eylemin konuşmaya ne zaman uyduğuna karar verir; ne yaptığına ise kodunuz karar verir.
Web sitesi karakterleri için fikirler
- Seçenekleri açıklayan ve istendiğinde renkleri değiştiren 3D yapılandırıcıda bir ürün rehberi.
- Program sorularını yanıtlayan ve ziyaretçileri doğru sahneye yönlendiren bir etkinlik sunucusu.
- Arşivinizdeki hikâyeleri kendi sesiyle anlatan bir müze ya da marka karakteri.
- Ziyaretçilerin satın almadan önce oyunun karakterleriyle konuşabildiği bir oyunun açılış sayfası.
Kullanım alanı rehberlerimiz, 3D web mağazaları için yapay zeka alışveriş rehberlerini ve sanal etkinlikler için yapay zeka sunucularını daha ayrıntılı işler.
Sık karşılaşılan sorunlar
- Mikrofon başlamıyor. Tarayıcılar kayıttan önce HTTPS ve bir tıklama ya da dokunma ister. Düz HTTP önizlemesinde değil, gerçek alan adınızda test edin.
- Uç noktadan 401 ya da 403.
authorizenulldöndürdü ya da karakter kimliğicharacterslistesinde yok. - Anahtar tarayıcıya düştü. Asla istemci koduna geçirmeyin. Yalnızca sunucu işleyicisi
NEOCORTEX_API_KEYdeğerini okumalıdır.
Sonraki adımlar
Web siteleri yerine oyun motorları için Unity oyununuza yapay zeka karakteri nasıl eklenir yazısıyla başlayın. Ses tarafını anlamak için yapay zeka NPC ses hattının nasıl çalıştığını okuyun. Serideki her eğitim yapay zeka NPC'leri kurma rehberinde yer alıyor; tam kurulum ise Web SDK dokümanlarında.
Sık sorulan sorular
Web siteme sesli bir yapay zeka karakteri nasıl eklerim?
Neocortex Web SDK'sını kurun, API anahtarı gizli kalsın diye küçük proxy'sini sunucunuza ekleyin, sonra sayfaya voice özniteliğiyle bir neocortex-chat öğesi yerleştirin. Ziyaretçiler yazabilir ya da konuşabilir; karakter yanıtını sesli verir.
API anahtarımı açığa çıkarmadan sitime bir yapay zeka sohbet robotu koyabilir miyim?
Evet. Neocortex Web SDK'sı anahtarı tutan, kimin konuştuğunu denetleyen ve yalnızca listelediğiniz karakterlere izin veren bir sunucu işleyicisi içerir. Tarayıcı yalnızca kendi uç noktanızla konuşur.
React, Vue ya da WordPress ile çalışır mı?
Sohbet arayüzü standart Web Component'lerden oluşur; bu yüzden React, Vue, Svelte, Angular ve düz HTML ile çalışır. Next.js, Express ya da Cloudflare Workers gibi küçük bir sunucu uç noktası çalıştırabilen her site proxy'yi barındırabilir.
Neocortex Web SDK'sı ücretsiz mi?
SDK, Apache-2.0 lisansı altında açık kaynaktır. Konuşmalar Neocortex planınıza sayılır.
Karakter sayfada işler yapabilir mi?
Evet. Neocortex düzenleyicisinde karakter için eylemler tanımlayın, sonra sayfada her biri için bir işleyici kaydedin; örneğin bir ürünü açmak, bir turu başlatmak ya da bir bölüme kaydırmak için.






