ما الذي ستنشئه

ينشئ هذا الدرس التقني روبوت محادثة قائمًا على الطلب والاستجابة. يكتب الزائر رسالة، ويرسلها Next.js إلى /api/chat، ثم يستدعي مسار الخادم واجهة OpenAI Responses API. ويُضاف النص المُعاد إلى نافذة المحادثة. يمثل ذلك أساسًا مختصرًا عن قصد: فهو يثبت تدفق البيانات ويحمي مفتاح API، من دون الادعاء بتضمين ميزات الإنتاج مثل حسابات المستخدمين أو المحادثات المحفوظة أو البث أو قاعدة المعرفة.

تعرض موارد المطورين الموثقة من OpenAI واجهة Responses API وحالة المحادثة والبث وعدّ الرموز ووضع الخلفية وWebhooks ودليل الترحيل كمواضيع منفصلة. وهذا الفصل مهم؛ إذ لا يحتاج روبوت المحادثة الأساسي إلى كل الإمكانات المتقدمة منذ اليوم الأول. ابدأ باستدعاء موثوق من جانب الخادم، ثم اختر حالة المحادثة والبث والميزات الأخرى فقط عندما يبررها أحد متطلبات المنتج.

يختار المثال gpt-5.6، الذي يظهر في قائمة التنقل الحالية لموارد مطوري OpenAI. ويُضبط النموذج عبر متغير بيئة حتى لا يحتاج كود التطبيق إلى التغيير عندما يعتمد فريقك نموذجًا آخر مسموحًا به.

المتطلبات المسبقة

• Node.js ١٨ أو إصدار أحدث.
• مفتاح OpenAI API متاح عبر حسابك على منصة OpenAI.
• إلمام أساسي بـ JavaScript وReact وسطر الأوامر.
• مشروع Next.js جديد أو قائم يستخدم App Router.

لا تضع مفتاح OpenAI في كود جانب العميل، أو في مكوّن يحمل علامة 'use client'، أو في مستودع عام، أو في متغير بيئة يبدأ بـ NEXT_PUBLIC_. صُممت المتغيرات التي تحمل هذه البادئة لتكون مكشوفة للمتصفح. في هذا المشروع، لا يقرأ OPENAI_API_KEY سوى معالج المسار.

الخطوة ١: إنشاء مشروع Next.js

أنشئ تطبيقًا جديدًا، وادخل إلى دليله، وثبّت SDK JavaScript الرسمي من OpenAI. عند ظهور المطالبات من create-next-app، اختر JavaScript وفعّل App Router. يفترض الكود أدناه بنية الدليل app الافتراضية.

npx create-next-app@latest nextjs-openai-chatbot
cd nextjs-openai-chatbot
npm install openai
npm run dev

افتح http://localhost:3000. تؤكد شاشة البداية أن Next.js يعمل قبل إضافة أي تكامل للذكاء الاصطناعي. أوقف الخادم باستخدام Ctrl+C قبل تغيير الإعدادات إذا كان سير عملك المحلي يتطلب ذلك.

الملفات الناتجة ذات الصلة بهذا الدرس التقني هي:

nextjs-openai-chatbot/
├── app/
│   ├── api/
│   │   └── chat/
│   │       └── route.js
│   ├── globals.css
│   ├── layout.js
│   └── page.js
├── .env.local
└── package.json

يؤدي استخدام App Router إلى تجنب عدم توافق التوجيه في المسودة الأصلية. تنتمي معالجات المسارات إلى app/api/.../route.js ويمكنها تصدير أساليب مثل POST. أما اصطلاح pages/api الأقدم فيستخدم بنية مختلفة للمعالج.

الخطوة ٢: إضافة متغيرات بيئة للخادم فقط

أنشئ .env.local في جذر المشروع. استبدل المفتاح التجريبي بمفتاحك الحقيقي. احتفظ بالنموذج في متغير منفصل حتى يمكن تغييره دون تعديل منطق المسار.

OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-5.6

لا تحفظ .env.local في المستودع مطلقًا. إذا كنت تستخدم التحكم بالمصادر، فتأكد من تجاهل الملف قبل إضافة الملفات. أعد تشغيل npm run dev بعد إضافة متغيرات البيئة أو تعديلها حتى يحمّل Next.js القيم الحالية.

لا يوجد NEXT_PUBLIC_API_ENDPOINT في هذا الإعداد عن قصد. لا يستدعي العميل نقطة نهاية OpenAI مباشرة، بل يستدعي نقطة النهاية الداخلية النسبية /api/chat، بينما يتولى SDK من جانب الخادم معالجة طلب OpenAI.

الخطوة ٣: إنشاء مسار Responses API

أنشئ app/api/chat/route.js. يتحقق هذا المسار الكامل من بنية JSON الواردة، ويقصر المحادثة التي يرسلها هذا العرض التوضيحي على أحدث ٢٠ رسالة، ويستدعي واجهة Responses API، ويعيد JSON عاديًا. حد الرسائل هو خيار على مستوى التطبيق للحفاظ على حدود المثال؛ وليس حدًا لمنصة OpenAI.

import OpenAI from 'openai';export const runtime = 'nodejs';const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});export async function POST(request) {
if (!process.env.OPENAI_API_KEY) {
return Response.json(
{ error: 'OPENAI_API_KEY is not configured on the server.' },
{ status: 500 }
);
}try {
const body = await request.json();
const messages = Array.isArray(body.messages) ? body.messages : null;if (!messages || messages.length === 0) {
return Response.json(
{ error: 'Send a non-empty messages array.' },
{ status: 400 }
);
}const input = messages.slice(-20).map((message) => ({
role: message.role === 'assistant' ? 'assistant' : 'user',
content: String(message.content || '').slice(0, 4000),
}));if (input.some((message) => message.content.trim().length === 0)) {
return Response.json(
{ error: 'Every message must contain text.' },
{ status: 400 }
);
}const response = await openai.responses.create({
model: process.env.OPENAI_MODEL || 'gpt-5.6',
input,
});const content = response.output_text.trim();return Response.json({
message: {
...
تابع القراءة
سجل دخولك مجاناً لقراءة المقال كاملاً والوصول إلى أدوات الذكاء الاصطناعي.
تسجيل الدخول / إنشاء حساب