كيفية تنفيذ روبوت محادثة في موقع ويب خطوة بخطوة
يتلخص تعلم كيفية تنفيذ روبوت محادثة في مشاريع الويب في ثلاثة أجزاء: مربع محادثة في المتصفح، وخادم صغير يحتوي على مفتاح API الخاص بك، واستدعاء لنقطة النهاية المتوافقة مع OpenAI. يبني هذا الدليل كل جزء باستخدام كود قابل للتشغيل.
تم التحديث

نقاط رئيسية
- لا تستدِ واجهة برمجة التطبيقات أبدًا من كود المتصفح. احتفظ بالمفتاح على خادم واكشف عن مسار /api/chat الخاص بك.
- واجهة برمجة التطبيقات متوافقة مع OpenAI، لذا تعمل أدوات SDK القياسية بعد ضبط عنوان URL الأساسي واستخدام النموذج uncensored.
- استخدم الردود المتدفقة لتبدو الصفحة سريعة، وحدّث سجل المحادثات على الخادم.
- عالج استجابات 429 واضبط حدًا لكل زائر، حيث يسمح مفتاح كامل بـ 8 طلبات متزامنة.
البنية في صورة واحدة
الطريقة المعتادة لتنفيذ روبوت محادثة في مشاريع الويب هي وسيط ثلاثي الخطوات. يكتب الزائر في مربع المحادثة. ترسل صفحتك الرسالة إلى خادمك الخاص. يستدعي خادمك واجهة برمجة تطبيقات النموذج بمفتاحك السري ويعيد إجابة العميل. لا يرى المتصفح المفتاح أبدًا.
هذا مهم لأن أي شيء في جافا سكريبت للواجهة الأمامية يكون عامًا. إذا وضعت المفتاح في وسم <script>، يمكن لأي شخص يفتح أدوات المطور نسخه وإنفاق رصيدك. كما يمنحك مسار الخادم الخلفي مكانًا واحدًا لإضافة حدود المعدل، حذف السجل، التسجيل وباب التحقق من العمر. لمزيد من الشرح التفصيلي لصفحة جاهزة، انظر دليل دردشة الويب.
الخطوة 1: احصل على مفتاح واختبر نقطة النهاية
سجّل باستخدام Google أو عبر البريد الإلكتروني وكلمة المرور، ثم احصل على التجربة المجانية في صفحة مفتاح API. تتضمن التجربة رصيداً بقيمة $0.50 صالحاً لمدة 7 أيام، مخصص لشخص واحد، ولا يتطلب أي دفع. احفظ المفتاح كمتغير بيئة وليس داخل الكود الخاص بك.
تحقق من عمله باستخدام curl قبل كتابة أي كود للتطبيق:
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."}]}'الاستدعاء الأول يعرض قائمة النماذج، والثاني يعيد إكمال المحادثة. إذا نجح الاثنان، فإن المفتاح وعنوان URL الأساسي صحيحان. يشير الخطأ 401 إلى أن المفتاح غير صحيح أو أنه يفتقر إلى بادئة Bearer.
الخطوة 2: كتابة مسار الخلفية
يستخدم المثال أدناه Node 18 أو أحدث، و Express، وحزمة openai الرسمية. قم بتثبيتها باستخدام npm install express openai واضبط "type": "module" في package.json.
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"));ثلاثة تفاصيل تؤدي العمل الفعلي هنا. يقوم الخادم بإعادة بناء قائمة الرسائل بنفسه، لذا لا يمكن للزائر حقن رسالة نظام مزيفة. يحتفظ بآخر 10 رسائل فقط ويقصر كل منها إلى 4,000 حرف، مما يتحكم في التكلفة. ويحدد الأدوار دائماً بشكل صريح، حيث يحول أي دور غير معروف إلى user.
الخطوة 3: بناء صندوق الدردشة
ضع هذا في public/index.html. يستخدم JavaScript عادي بدون إطار عمل، لذا يمكنك لصقه في قالب موجود.
<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 بدلاً من innerHTML لمخرجات النموذج لمنع الرد من حقن علامات في صفحتك. التزم بهذه العادة حتى عندما يكون النموذج متصرفاً بشكل جيد.
الخطوة 4: معالجة الحدود والأخطاء
المفتاح الكامل يسمح بـ 8 طلبات متزامنة و 300 طلب في الدقيقة. يسمح المفتاح التجريبي بـ 2 طلب متزامن و 60 طلب في الدقيقة. عند تجاوز الحد، تُعيد الـ API استجابة HTTP 429 مع رمز خطأ: rate_limited لطلبات في الدقيقة أو concurrency لعدد كبير جداً في وقت واحد. في حالات الحمل المؤقت، تُعيد أيضاً 429 مع رأس Retry-After: 5.
تتبع ذلك قاعدتان عمليتان. أولاً، أعد المحاولة عند الخطأ 429 بعد التأخير مع زيادة تدريجية قصيرة، وأظهر رسالة ودية للزائر إذا استمر الفشل. ثانياً، تذكر أن الطلب المتدفق يحتفظ بفتحة التوازي الخاصة به حتى ينتهي البث. إذا قام عشرة زوار بالبث في وقت واحد باستخدام مفتاح كامل، سيتم رفض اثنين منهم، لذا أضف طابورًا صغيرًا أو حدًا لكل زائر على خادمك. يكفي عداد بسيط في الذاكرة مرتبطًا بعنوان IP لموقع صغير.
تساعدك رؤوس الاستجابة في التصحيح: يُحدد X-Request-Id الاستدعاء إذا تواصلت مع الدعم، ويُظهر X-Balance-USD رصيدك المتبقي. حد حجم جسم الطلب هو 8 MB، وهو أعلى بكثير مما تحتاجه الدردشة، ونافذة السياق هي 100,000 رمز (token).
أخطاء شائعة عند النشر
يعمل الكود أعلاه على localhost. هذه هي المشاكل التي تظهر بمجرد نشره على خادم حقيقي.
- الوكلاء الوسيطين للتخزين المؤقت. بعض الوكلاء العكسيين يمسكون بالاستجابات المتدفقة حتى تنتهي، لذا تظهر الإجابة دفعة واحدة. إذا كنت تستخدم nginx، عطّل تخزين الاستجابة المؤقت لمسار الدردشة. اختبر البث المتدفق عبر نفس سلسلة الوكلاء التي تستخدمها في الإنتاج، وليس فقط على جهازك المحلي.
- المفاتيح في المستودع. احتفظ بالمفتاح في متغير بيئة أو متجر أسرار وأضف أي ملف بيئة محلي إلى قائمة التجاهل. إذا وصل مفتاح إلى مستودع عام، أنشئ مفتاحاً جديداً وتوقف عن استخدام المفتاح القديم.
- الثقة بالعميل. يرسل المتصفح تاريخ الدردشة، لذا يمكن للزائر تعديله. ولهذا السبب يحدد الخادم في الخطوة 2 الأدوار بنفسه ويقصر طول الرسائل. لا تقبل رسالة نظام من العميل أبداً.
- الاستدعاءات عبر النطاقات. إذا كانت صفحتك وخادمك الخلفي على نطاقات مختلفة، سيقوم المتصفح بحظر الطلب حتى يرسل خادمك رؤوس CORS الصحيحة. تقديم الاثنين من أصل واحد يتجنب هذه المشكلة.
- التكلفة الهاربة. يمكن لزائر مبرمج إرسال مئات الرسائل. احسب الطلبات لكل عنوان IP أو جلسة على الخادم ورفضها عندما يكون العدد مرتفعًا جدًا. كما يحدد المثال طول الرسالة كحد أقصى.
- Markdown والروابط. غالباً ما ترد النماذج بقوائم وكتل الكود. قرر ما إذا كنت سترسم ذلك أو تعرض نصاً عاديًا، ولا تدرج نص الرد كـ HTML خام.
التحقق الأخير هو التخطيط للهاتف المحمول. تأتي معظم حركة الدردشة على المواقع العامة من الهواتف، لذا اختبر بشاشة ضيقة، ولوحة مفاتيح برمجية مفتوحة، واتصال غير مستقر. إذا انقطع البث في منتصف الطريق، يجب أن يتمكن الزائر من إعادة الإرسال دون فقدان سياق المحادثة.
توسعة البوت لاحقاً
بمجرد أن يعمل الوسيط الأساسي، يمكن للمسار نفسه القيام بالمزيد، لأن الواجهة البرمجية تدعم ميزات OpenAI القياسية. يمكنك طلب مخرجات منظمة باستخدام وضع JSON عن طريق تعيين response_format إلى {"type": "json_object"} والقول في الموجّه أن الرد يجب أن يكون JSON. يناسب ذلك نموذجاً لجمع العملاء المحتملين يحول رسالة نصية حرة إلى حقول مثل الاسم والموضوع والأولوية.
يسمح استدعاء الدوال للنموذج بطلب خادمك لتشغيل دالة، مثل البحث عن طلب أو التحقق من ساعات العمل. تمرر قائمة tools، تقرأ tool_calls في الاستجابة، تشغل الدالة بنفسك، وترسل النتيجة مرة أخرى كرسالة مع role: "tool". يكتب النموذج بعد ذلك الإجابة النهائية من بياناتك. بهذه الطريقة يحصل بوت الموقع على معلومات حقيقية بدلاً من التخمين.
إعدادات أخذ العينات مفتوحة لك أيضاً. درجة الحرارة المنخفضة تناسب مكاتب المساعدة الواقعية، بينما تناسب درجة الحرارة العالية سرد القصص. أضف تغييراً واحداً في كل مرة وقارن النتائج على نفس أسئلة الاختبار الخمسة.
الخطوة 5: صمّم البوت وأطلقه
يحدد الموجّه للنظام هوية البوت الخاص بك. أخبره بمن هو، وما الذي يغطيه، وكم يجب أن تكون مدة الإجابات. إذا كان للشخصية طابع معين، فإن الملاحظات حول تصميم الشخصية تذهب إلى أعمق. نظرًا لأن النموذج مُعد للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين، فإن ضوابط الرقابة لجمهورك هي ما تكتبه: تأكيد العمر، رابط للإبلاغ، وقائمة واضحة لما لن يناقشه البوت. محتوى الجنس الذي يتضمن القاصرين غير مسموح به مطلقًا. انظر صفحة الاستخدام المسؤول والضمانات قبل الإطلاق.
من حيث التكلفة، تدفع $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج. تبلغ تكلفة إجابة تحتوي على 1,200 رمز مدخل و300 رمز مخرج $0.00018 زائد $0.00015، أي ما مجموعه $0.00033. يغطي الشحن بمبلغ $20 أكثر من 60,000 إجابة من هذا النوع. تتراوح الشحنات من $20 إلى $500، مع زيادة 5% من $50، و10% من $100، و15% من $200، تُدفع بـ USDT على TRC20 أو USDC على Base. الرصيد لا ينتهي. يحتوي صفحة الأسعار على التفاصيل، ويذكر الدليل كل معلمة مدعومة، بما في ذلك استدعاء الدوال ووضع JSON.
قبل الإطلاق، اختبر مع بضع محادثات طويلة، راقب السجلات بحثاً عن 429، وتأكد من أن خادمك يقوم بتقليم السجل. لا تُستخدم الموجّهات للتدريب، لكن يجب عليك إعلام زوارك بما تخزنه.
المزيد من الأدلة
أسئلة وأجوبة
هل يمكن استدعاء API مباشرة من جافاسكريبت المتصفح؟
يمكنك ذلك، لكن لا ينبغي لك ذلك. سيكون المفتاح مرئياً لكل زائر. وجه الطلبات عبر خادمك الخاص واحتفظ بالمفتاح في متغير بيئة.
ما هي اللغات وواجهات برمجة التطبيقات (SDKs) المدعومة؟
أي عميل SDK أو HTTP لـ OpenAI. اضبط Base URL إلى https://api.uncensoredchatbotapi.com/v1, واستخدم مفتاحك كرمز Bearer واضبط النموذج على uncensored. تعمل Python وNode وcurl جميعها.
هل يعمل البث المتدفق في المتصفح؟
نعم. تقوم الـ API بالبث عبر SSE مع تعيين البث المتدفق إلى true. ينقل المثال النص عبر خادمك باستخدام fetch وقارئ البث المتدفق.
ماذا يحدث عند الوصول إلى حدّ المعدل؟
تظهر لك استجابة HTTP 429 مع الكود rate_limited أو concurrency. انتظر وأعد المحاولة. في حالة الحمل الزائد المؤقت، تكون قيمة رأس Retry-After هي 5 ثوانٍ.
مفتاحك على بُعد نموذج واحد
أنشئ حساباً، وانسخ المفتاح، ثم غيّر نقطة النهاية. هذه هي الإعدادات الكاملة.