واجهة برمجة تطبيقات Node JS AI: البث المتدفق، الأدوات والأخطاء في Express
يأخذك هذا البرنامج التعليمي لواجهة برمجة تطبيقات Node JS AI من مجلد فارغ إلى مسار Express يبث ردود الدردشة، ويستدعي أداة ويتعامل مع أخطاء حدّ المعدل. تقوم فقط بتغيير عنوان URL الأساسي والمفتاح في الحزمة الرسمية OpenAI، ثم ترسل النموذج uncensored.
محدّثUnfiltered AI

نقاط رئيسية
- ثبّت الحزمة openai واضبط baseURL على https://api.unfilteredaiapi.com/v1.
- بث باستخدام stream: true وأمرر الشرائح إلى المتصفح كحدث مرسل من الخادم.
- تصل استدعاءات الأدوات كـ tool_calls؛ ارجع النتائج مع role tool.
- يعني 429 rate_limited، أو concurrency، أو تحميل زائد مؤقت؛ أعد المحاولة بعد تأخير Retry-After.
الإعداد: التثبيت وإرسال الطلب الأول
تحتاج إلى Node 18 أو أحدث. أنشئ مشروعًا، وثبّت الـ SDK وExpress، ثم انتقل إلى وحدات ES.
mkdir ai-node && cd ai-node
npm init -y
npm pkg set type=module
npm install openai express
# base URL: https://api.unfilteredaiapi.com/v1 model: uncensored
export AI_API_KEY="YOUR_KEY"
احصل على مفتاح من صفحة مفتاح API. يمكن للحسابات الجديدة المطالبة بـ $0.50 من رصيد تجريبي بنقرة واحدة، صالح لمدة 7 أيام. ثم أنشئ client.js:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const res = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Give me three names for a tavern keeper." }],
});
console.log(res.choices[0].message.content);
شغّله باستخدام node client.js. يحدد كل مقتطف أدناه العميل مرة أخرى بحيث يعمل بشكل مستقل. هذه هي عملية الترحيل بأكملها إذا كنت تستخدم بالفعل حزمة OpenAI: تغيير baseURL، ومفتاحك، ومعرف النموذج. الخدمة متوافقة مع OpenAI وتقتصر على النصوص فقط، مع نافذة سياق تتسع لـ 100,000 رمز. اطّلع على الوثائق لمعرفة كل الطرق المدعومة.
بث الرد
يُرسِل البث المتدفق الرموز بمجرد إنتاجها، مما يسمح للمستخدمين برؤية النص فورًا. اضبط stream: true وتكرّر عبر القطع:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Describe a rainy harbor town." }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
if (chunk.usage) console.log("\nusage:", chunk.usage);
}
يصل الاستخدام في الشريحة الأخيرة، مما يتيح لك تسجيل عدد الرموز الفعلي لكل طلب. ضع حقيقة في ذهنك: يشغل الطلب المتدفق شريحة التزامن الخاصة به حتى ينتهي البث. إذا انقطع اتصال العميل، أوقف الاتصال بالأعلى لتحرير الشريحة بسرعة.
مسار Express يقوم بالبث المتدفق إلى المتصفح
إليك خادم صغير يحتوي على مسار POST /chat. يقوم بإعادة توجيه البث كـ أحداث مُرسَلة من الخادم (SSE) ويُلغي الطلب البعيد عند إغلاق المتصفح للاتصال.
import express from "express";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const app = express();
app.use(express.json({ limit: "1mb" }));
app.post("/chat", async (req, res) => {
const { messages } = req.body;
if (Array.isArray(messages) === false) return res.status(400).json({ error: "messages required" });
res.set({
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
const controller = new AbortController();
req.on("close", () => controller.abort());
try {
const stream = await client.chat.completions.create(
{ model: "uncensored", messages, stream: true },
{ signal: controller.signal }
);
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) res.write("data: " + JSON.stringify({ delta }) + "\n\n");
}
res.write("data: [DONE]\n\n");
} catch (err) {
res.write("data: " + JSON.stringify({ error: err.status || 500 }) + "\n\n");
} finally {
res.end();
}
});
app.listen(3000, () => console.log("listening on 3000"));
لا تضع المفتاح في كود المتصفح. يبقي المسار أعلاه المفتاح على الخادم، حيث ينبغي أن يكون. يُظهر نفس النمط في Python في مقال خلفية دردشة الروبوت FastAPI.
استدعاء أداة
يتبع استدعاء الأدوات تنسيق OpenAI: تصف الدوال في tools، ويرد النموذج بـ tool_calls، وتشغّل الدالة وترسل النتيجة مرة أخرى كرسالة بـ role: "tool".
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const tools = [{
type: "function",
function: {
name: "roll_dice",
description: "Roll a die with the given number of sides",
parameters: {
type: "object",
properties: { sides: { type: "integer" } },
required: ["sides"],
},
},
}];
const messages = [{ role: "user", content: "Roll a d20 for my attack." }];
const first = await client.chat.completions.create({
model: "uncensored", messages, tools, tool_choice: "auto",
});
const msg = first.choices[0].message;
if (msg.tool_calls) {
messages.push(msg);
for (const call of msg.tool_calls) {
const { sides } = JSON.parse(call.function.arguments);
const result = 1 + Math.floor(Math.random() * sides);
messages.push({ role: "tool", tool_call_id: call.id, content: String(result) });
}
const second = await client.chat.completions.create({ model: "uncensored", messages, tools });
console.log(second.choices[0].message.content);
}
قم دائمًا بتحليل arguments داخل كتلة try في الكود الحقيقي، لأن النماذج قد تُرجج أحيانًا JSON غير صالح. للإخراج المهيكل دون أدوات، اضبط response_format: { type: "json_object" } واذكر JSON في الموجّه. تغطي مشاهد الألعاب التي تستدعي دوال النرد أو المخزون في بناء شخصيات NPCs والأدب التفاعلي.
معالجة الأخطاء وحدود المعدل
تُرجع الـ API خطأ HTTP 429 في ثلاث حالات. يعني رمز الخطأ rate_limited وجود طلبات كثيرة جدًا في الدقيقة: 300 للمفتاح الكامل، و60 لمفتاح التجربة. يعني الرمز concurrency وجود طلبات متزامنة كثيرة جدًا: 8 للمفتاح الكامل، و2 لمفتاح التجربة. في حالات الحمل الزائد المؤقت، تحصل أيضًا على 429 مع رأس Retry-After: 5. يكشف الـ SDK عن الحالة في الخطأ المرمي، لذا يمكن لمغلف صغير معالجة الحالات الثلاث:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
export async function chatWithRetry(params, tries = 4) {
for (let i = 0; i < tries; i++) {
try {
return await client.chat.completions.create({ model: "uncensored", ...params });
} catch (err) {
if (err.status === 429 && i < tries - 1) {
const wait = Number(err.headers?.["retry-after"]) || 2 ** i;
await sleep(wait * 1000);
continue;
}
throw err;
}
}
}
ينتظر المغلف التأخير الذي يطلبه الخادم وينتقل إلى التراجع الأسي. لاحظ أن حزمة OpenAI تُعيد محاولة بعض الأخطاء بنفسها؛ اضبط maxRetries على العميل إذا كنت تريد التحكم في ذلك. لا ينبغي إعادة محاولة حالات أخرى، مثل 401 للمفتاح غير الصحيح. يوجد نظرة أعمق على الحدود في الأسئلة الشائعة.
التشغيل واختبار المسار
ابدأ الخادم بـ node server.js واختبره من طرفية ثانية. يُعطّل العلم -N تخزين مؤقت في curl لترى وصول الأحداث واحدة تلو الأخرى:
# the server calls https://api.unfilteredaiapi.com/v1 with model uncensored
curl -N http://localhost:3000/chat -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"Write a two-line riddle."}]}'
في المتصفح، اقرأ البث المتدفق باستخدام fetch وقارئ، أو باستخدام مكتبة مساعدة صغيرة لـ SSE. ونظراً لأن المسار هو POST، فإن كائن EventSource الأصلي لا يناسب، لذا استخدم fetch وفك الترميز للقطع بنفسك.
عادات الإنتاج
- احتفظ بالمفتاح في متغير بيئة أو مخزن أسرار، وليس في المستودع.
- حدد حجم جسم الطلب. تقبل الـ API ما يصل إلى 8 MB، لكن مسار الخاص بك يجب أن يقبل حجمًا أقل بكثير.
- حدّد من السجل الذي ترسله. اقتطع المحاور القديمة قبل أن تكلفك المال أو تملأ نافذة الـ 100,000 رمز.
- صفّف العمل الإضافي أو ارفضه عندما يكون لديك بالفعل 8 تدفقات مفتوحة، بدلاً من السماح للـ API بإجابة 429 لمستخدميك.
- سجّل رأس الاستجابة
X-Request-Id، بحيث يمكن للدعم تتبع طلب واحد.
تحقق من رصيدك وتكلفة الاستخدام
يحمل كل استجابة رأس X-Balance-USD، ويعيد GET /v1/balance الرصيد مباشرة. تبلغ الأسعار $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، وتُخصم من الرصيد المسبق الدفع، والطلبات الفاشلة أو المرفوضة مجانية. تكلفة دورة محادثة تتألف من 800 رمز مدخل و250 رمز مخرج هي $0.000245، لذا فإن 10,000 دورة تكلف $2.45. سجّل استخدام usage من كل استجابة ويمكنك التنبؤ بفاتورتك ضمن بضعة سنتات. تذكر صفحة التسعير شحنات الرصيد من $20 إلى $500.
المزيد من الأدلة
أسئلة وأجوبة
أي حزمة npm يجب أن أستخدم؟
تعمل حزمة openai الرسمية. اضبط baseURL على https://api.unfilteredaiapi.com/v1، مرر مفتاحك، واستخدم معرف النموذج uncensored.
هل يمكنني بث الاستجابات من Node؟
نعم. مرر stream: true وتكرر باستخدام for await. أضف stream_options مع include_usage للحصول على عدد الرموز في الشريحة الأخيرة.
هل يدعم الـ API استدعاء الدوال؟
نعم. أرسل tools و tool_choice، واقرأ tool_calls من الرد، ثم أعد النتائج كرسائل مع role tool.
ماذا يجب أن يفعل الخادم عند استلام HTTP 429؟
انتظر قيمة Retry-After إن وجدت، وإلا فتراجع تدريجيًا بشكل أسي، ثم أعد المحاولة بضع مرات. قلل الطلبات المتوازية إذا كان رمز الخطأ هو concurrency.
مفتاحك على بُعد نموذج واحد
أنشئ حساباً، وانسخ المفتاح، ثم غيّر base URL. هذا هو الإعداد الكامل.