Bir Web Sitesine Chatbot Nasıl Entegre Edilir, Adım Adım
Web sitesi projelerine chatbot entegre etmeyi öğrenmek üç kısımdan ibarettir: tarayıcıdaki bir sohbet kutusu, API anahtarınızı tutan küçük bir arka uç ve OpenAI uyumlu bir uç noktaya yapılan çağrı. Bu kılavuz her kısmı çalışan kodla oluşturur.
güncellendi

Temel noktalar
- API'yi tarayıcı kodundan asla çağırmayın. Anahtarı bir sunucuda tutun ve kendi /api/chat rotanızı açın.
- API OpenAI uyumlu olduğu için, base URL'yi ayarladıktan ve uncensored modelini kullandıktan sonra standart SDK'lar çalışır.
- Sayfanın hızlı hissetmesi için akış yanıtlarını kullanın ve sunucuda geçmişi sınırlandırın.
- 429 yanıtlarını işleyin ve tam anahtar 8 eşzamanlı isteklere izin verdiği için ziyaretçi başına bir limit ayarlayın.
Tek bir resimde mimari
Web sitesi projelerinde chatbot entegre etmenin yaygın yolu üç aşamalı bir aktarmadır. Ziyaretçi bir sohbet kutusuna yazar. Sayfanız mesajı kendi sunucunuza gönderir. Sunucunuz gizli anahtarınızla model API'sini çağırır ve cevabı geri iletir. Tarayıcı anahtarı asla görmez.
Bu önemlidir çünkü ön uç JavaScript'indeki her şey halka açıktır. Anahtarı bir script etiketine koyarsanız, geliştirici araçlarını açan herkes kopyalayıp bakiyenizi harcayabilir. Bir arka uç rotası ayrıca hız limitleri, geçmiş kısaltma, günlük kaydı ve yaş doğrulaması eklemek için tek bir yer sağlar. Tamamlanmış bir sayfa için daha uzun bir anlatım için web sohbet öğreticisine bakın.
Adım 1: bir anahtar alın ve uç noktayı test edin
Google veya e-posta ve şifre ile kaydolun, ardından API anahtarı sayfasında ücretsiz deneme kredisi talep edin. Deneme $0,50 kredi değerindedir, 7 gün geçerlidir, kişi başı bir kez geçerlidir ve ödeme gerektirmez. Anahtarı ortam değişkeni olarak kaydedin, kodunuzda değil.
Herhangi bir uygulama kodu yazmadan önce curl ile çalıştığını kontrol edin:
export API_KEY="YOUR_KEY"
curl https://api.uncensoredchatbotapi.com/v1/models -H "Authorization: Bearer $API_KEY"
curl https://api.uncensoredchatbotapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello in five words."}]}'İlk çağrı modelleri listeler ve ikinci çağrı bir sohbet tamamlama döndürür. İkisi de başarılı olursa, anahtar ve base URL doğrudur. 401 hatası anahtarın yanlış olduğunu veya Bearer önekini içermediğini gösterir.
Adım 2: arka uç rotasını yazın
Aşağıdaki örnek Node 18 veya daha yeni, Express ve resmi openai paketini kullanır. npm install express openai ile yükleyin ve package.json içinde "type": "module" ayarlayın.
import express from "express";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredchatbotapi.com/v1",
apiKey: process.env.API_KEY,
});
const SYSTEM = "You are a helpful assistant for our website. Keep answers under 150 words.";
const app = express();
app.use(express.json({ limit: "100kb" }));
app.use(express.static("public"));
app.post("/api/chat", async (req, res) => {
const incoming = Array.isArray(req.body.messages) ? req.body.messages : [];
const history = incoming.slice(-10).map((m) => ({
role: m.role === "assistant" ? "assistant" : "user",
content: String(m.content).slice(0, 4000),
}));
try {
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "system", content: SYSTEM }, ...history],
stream: true,
});
res.setHeader("Content-Type", "text/plain; charset=utf-8");
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) res.write(text);
}
} catch (err) {
if (res.headersSent === false) res.status(err.status === 429 ? 429 : 502);
}
res.end();
});
app.listen(3000, () => console.log("Listening on http://localhost:3000"));Aşağıdaki üç detay asıl işi yapar. Sunucu mesaj listesini kendisi yeniden oluşturur, bu nedenle bir ziyaretçi sahte bir sistem mesajı enjekte edemez. Sadece son 10 mesajı tutar ve her birini 4.000 karaktere keser, bu da maliyeti kontrol eder. Ve her zaman rolleri açıkça ayarlar, bilinmeyen her şeyi user olarak eşler.
Adım 3: sohbet kutusunu oluşturun
Bunu public/index.html dosyasına koyun. Çerçeve kullanmadan saf JavaScript kullanır, böylece mevcut bir şablona yapıştırabilirsiniz.
<div id="log"></div>
<form id="form">
<input id="input" autocomplete="off" required />
<button>Send</button>
</form>
<script>
const messages = [];
const log = document.getElementById("log");
document.getElementById("form").addEventListener("submit", async (e) => {
e.preventDefault();
const input = document.getElementById("input");
messages.push({ role: "user", content: input.value });
log.insertAdjacentHTML("beforeend", "<p></p>");
log.lastElementChild.textContent = "You: " + input.value;
input.value = "";
const reply = document.createElement("p");
log.appendChild(reply);
const res = await fetch("/api/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ messages }),
});
if (res.ok === false) { reply.textContent = "Busy, please try again in a moment."; return; }
const reader = res.body.getReader();
const decoder = new TextDecoder();
let full = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
full += decoder.decode(value, { stream: true });
reply.textContent = full;
}
messages.push({ role: "assistant", content: full });
});
</script>textContent kullanmak, model çıktısı için innerHTML yerine, yanıtın sayfanıza biçimlendirme enjekte etmesini önler. Model iyi davrandığında bile bu alışkanlığı sürdürün.
Adım 4: limitleri ve hataları işleyin
Tam bir anahtar 8 eşzamanlı istek ve dakika başına 300 istek izin verir. Bir deneme anahtarı 2 eşzamanlı ve dakika başına 60 izin verir. Aştığınızda API HTTP 429 hatasını bir hata koduyla döndürür: dakika başı istekler için rate_limited veya aynı anda çok fazla istek için concurrency. Geçici aşırı yüklenme durumunda ayrıca Retry-After: 5 başlığıyla 429 döndürür.
İki pratik kural daha vardır. İlk olarak, 429 hatası alındığında kısa bir bekleme süresiyle yeniden deneyin ve hata devam ederse ziyaretçiye dostça bir mesaj gösterin. İkinci olarak, akışlı bir istek, akış sonlanana kadar eşzamanlılık slotunu meşgul tutar. Tüm anahtarınız doluysa ve on ziyaretçi aynı anda akış başlatırsa, ikisi reddedilecektir; bu nedenle sunucunuza küçük bir kuyruk veya ziyaretçi başına bir sınır ekleyin. Küçük bir site için IP'ye göre anahtarlanan basit bir bellek içi sayaç yeterlidir.
Yanıt başlıkları hata ayıklamanıza yardımcı olur: X-Request-Id bir çağrıyı destekle iletişime geçtiğinizde tanımlar ve X-Balance-USD kalan kredinizi gösterir. İstek gövdesi limiti 8 MB'dir, bir sohbet için gerekenin çok üzerindedir ve bağlam penceresi 100,000 token'dır.
Dağıtım sırasında dikkat edilmesi gerekenler
Yukarıdaki kod localhost'ta çalışır. Bunlar gerçek bir sunucuya geçtiğinde ortaya çıkan sorunlardır.
- Yanıt arabellekleme yapan vekil sunucular. Bazı ters vekil sunucular, akışlı yanıtları tamamlanana kadar tutar, bu da yanıtın aniden görünmesine neden olur. nginx kullanıyorsanız, sohbet rotası için yanıt arabellekleme özelliğini kapatın. Üretimde kullandığınız aynı vekil sunucu zincirinden akışı test edin, yalnızca dizüstü bilgisayarınızda değil.
- Depodaki anahtarlar. Anahtarı bir ortam değişkeninde veya gizli depolamada tutun ve yerel env dosyasını yoksayma listenize ekleyin. Bir anahtar bir genel depoya düşerse, yeni bir tane oluşturun ve eskisini kullanmayı bırakın.
- İstemciye güvenmek. Tarayıcı sohbet geçmişini gönderir, bu nedenle bir ziyaretçi onu düzenleyebilir. Bu nedenle 2. adımdaki sunucu rolleri kendisi ayarlar ve mesaj uzunluğunu keser. İstemciden bir sistem mesajını asla kabul etmeyin.
- Cross-origin çağrılar. Sayfanız ve arka uçunuz farklı etki alanlarında yaşıyorsa, tarayıcı isteği sunucunuz doğru CORS başlıklarını gönderene kadar engeller. Her ikisini de tek bir etki alanından sunmak sorunu önler.
- Kontrolsüz maliyet. Bir scriptlenmiş ziyaretçi yüzlerce mesaj gönderebilir. Sunucuda IP veya oturum başına istekleri sayın ve sayı çok yüksek olduğunda reddedin. Ayrıca mesaj uzunluğunu kısıtlayın, örnek bunu yapar.
- Markdown ve bağlantılar. Modeller genellikle listeler ve kod çitleri ile yanıt verir. Bunları işleyip işlemediğinize karar verin ve yanıt metnini ham HTML olarak asla enjekte etmeyin.
Son bir kontrol mobil düzen içindir. Genel sitelerdeki sohbet trafiğinin çoğu telefonlardan gelir, bu nedenle dar bir ekranla, açık bir yazılım klavyesiyle ve kırılgan bir bağlantıyla test edin. Akış yarım kesilirse, ziyaretçi ipliği kaybetmeden yeniden gönderebilmelidir.
Botu daha sonra genişletme
Temel aktarma çalıştıktan sonra aynı yol daha fazlasını yapabilir, çünkü API standart OpenAI özelliklerini destekler. response_format değerini {"type": "json_object"} olarak ayarlayıp istemde yanıtın JSON olması gerektiğini belirterek JSON modu ile yapılandırılmış çıktı isteyebilirsiniz. Bu, serbest metinli bir mesajı ad, konu ve aciliyet gibi alanlara dönüştüren bir müşteri formu için uygundur.
Tool calling, modelin bir işlevi çalıştırmak için sunucunuzu sorgulamasına olanak tanır, örneğin bir siparişi aramak veya çalışma saatlerini kontrol etmek. Bir tools listesi iletirsiniz, yanıtta tool_calls'i okursunuz, işlevi kendiniz çalıştırırsınız ve sonucu role: "tool" ile bir mesaj olarak geri gönderirsiniz. Model daha sonra verilerinizden nihai cevabı yazar. Bu, bir web sitesi botunun tahmin etmek yerine gerçek bilgi almasını sağlar.
Örneklem ayarları da size açıktır. Daha düşük bir sıcaklık, gerçek bilgi hizmetleri için uygundur; daha yüksek bir sıcaklık ise hikaye anlatımı için uygundur. Her seferinde bir değişiklik yapın ve sonuçları aynı beş test sorusunda karşılaştırın.
Adım 5: botu şekillendirin ve yayına alın
Sistem promptu botunuzu tanımlar. Ona kim olduğunu, neyi kapsadığını ve cevapların ne kadar uzun olması gerektiğini söyleyin. Karakterin bir kişiliği varsa, persona tasarımı hakkında daha fazla bilgi alın. Model, yasal yetişkin kullanımı için içerik reddi olmadan yanıt verecek şekilde ayarlandığından, kitleniz için güvenlik önlemleri size aittir: bir yaş onayı, bir rapor bağlantısı ve botun tartışmayacağı şeylerin açık listesi. Reşit olmayanlar içeren cinsel içerik asla izin verilmez. Lansmandan önce sorumlu kullanım ve güvenlik sayfasına bakın.
Maliyet konusunda, 1M girdi token başına $0,15 ve 1M çıktı token başına $0,50 ödersiniz. 1.200 girdi token ve 300 çıktı token içeren bir yanıt $0,00018 artı $0,00015'e, yani $0,00033'e mal olur. $20'lik bir bakiye yükleme, 60.000'den fazla böyle yanıtı karşılar. Bakiye yüklemeler $20 ile $500 arasında değişir, $50'den itibaren +%5, $100'den itibaren +%10 ve $200'den itibaren +%15 eklenir; USDT (TRC20) veya USDC (Base) ile ödenir. Kredi asla sona ermez. fiyatlandırma sayfası detayları içerir ve dokümantasyon fonksiyon çağırma ve JSON modu dahil olmak üzere desteklenen her parametreyi listeler.
Yayınlamadan önce, birkaç uzun konuşma ile test edin, 429 hataları için günlükleri izleyin ve sunucunuzun geçmişi temizlediğinden emin olun. İstemler eğitim için kullanılmaz, ancak yine de ziyaretçilerinize neyi depoladığınızı bildirmelisiniz.
Daha fazla kılavuz
Sorular ve cevaplar
API'yi doğrudan tarayıcı JavaScript'inden çağırabilir miyim?
Evet, ancak yapmamanız gerekir. Anahtar tüm ziyaretçiler için görünür olur. İstekleri kendi sunucunuz üzerinden yönlendirin ve anahtarı ortam değişkeninde tutun.
Hangi diller ve SDK'lar çalışır?
Herhangi bir OpenAI SDK veya HTTP istemcisi. Base URL'yi https://api.uncensoredchatbotapi.com/v1 olarak ayarlayın, anahtarınızı bearer token olarak kullanın ve modeli uncensored olarak ayarlayın. Python, Node ve curl hepsi çalışır.
Tarayıcıda streaming çalışır mı?
Evet. API, stream true olarak ayarlanarak SSE üzerinden akış yapar. Örnek, metni fetch ve bir stream reader kullanarak sunucunuz üzerinden iletir.
Hız limitine (rate limit) ulaştığımda ne olur?
HTTP 429 hatasını rate_limited veya concurrency koduyla alırsınız. Bekleyin ve yeniden deneyin. Geçici aşırı yüklenme durumunda Retry-After başlığı 5 saniyedir.
Anahtarınız tek bir formun uzağında
Bir hesap oluşturun, anahtarı kopyalayın ve base URL'yi değiştirin. Kurulum bu kadar basit.