Blog

دليل المبتدئين لاستخدام Vercel AI SDK

Rebecca Kovács

Rebecca Kovács

10 أكتوبر 2025

دليل المبتدئين لاستخدام Vercel AI SDK

Apidog للمؤسسات

نشر محلي

SSO & RBAC

متوافق مع SOC 2

استكشاف Apidog Enterprise

مرحبًا بك في الدليل الشامل للمبتدئين لاستخدام Vercel AI SDK. في عالم يشهد تحولًا سريعًا في المشهد الرقمي بفضل الذكاء الاصطناعي، لم تعد القدرة على دمج الذكاء الاصطناعي في تطبيقات الويب مجرد تخصص محدود، بل أصبحت كفاءة أساسية للمطورين المعاصرين. تم تصميم هذا الدليل لينقلك من مجرد مبتدئ فضولي إلى مطور تطبيقات ذكاء اصطناعي متمكن.

لفترة طويلة، كان سد الفجوة بين نماذج اللغة الكبيرة (LLM) القوية وواجهة الويب سهلة الاستخدام مهمة معقدة. كان على المطورين التعامل مع واجهات برمجة تطبيقات مختلفة للموفرين، وإدارة حالات معقدة، وتطبيق ميزات مثل تدفق الاستجابة يدويًا. تم إنشاء Vercel AI SDK لحل هذه المشاكل بالضبط. إنها مجموعة أدوات تعتمد على TypeScript أولاً وتوفر طبقة تجريد موحدة وأنيقة فوق تعقيدات بناء التجارب المدعومة بالذكاء الاصطناعي.

هذا ليس مجرد دليل بدء سريع. على مدار هذا البرنامج التعليمي، سنقوم ببناء روبوت دردشة ذكاء اصطناعي كامل وغني بالميزات من البداية باستخدام Next.js ونموذج Gemini من Google. سنتجاوز بكثير مثال "hello world" البسيط. ستتعلم:

بنهاية هذا الدليل الشامل، لن يكون لديك فقط روبوت دردشة متقدم وعامل، بل ستمتلك أيضًا المعرفة المفاهيمية العميقة اللازمة لبناء تطبيقاتك الفريدة والقوية المدعومة بالذكاء الاصطناعي بثقة باستخدام Vercel AI SDK.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تولد توثيقًا جميلًا لواجهات برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر معقول أكثر بكثير!
button

الفصل الأول: الأساسيات والإعداد

كل بناء عظيم يحتاج إلى أساس متين. في هذا الفصل، سنقوم بإعداد بيئة التطوير الخاصة بنا، وتثبيت الأدوات اللازمة، وترتيب مفاتيح واجهة برمجة التطبيقات (API). سنتوقف أيضًا لحظة لفهم "السبب" وراء كل خيار نتخذه.

المتطلبات الأساسية

قبل أن نكتب سطرًا واحدًا من التعليمات البرمجية، دعنا نتأكد من أن مجموعة أدواتك جاهزة.

  1. انتقل إلى Google AI Studio.
  2. قم بتسجيل الدخول باستخدام حساب Google الخاص بك.
  3. انقر على "Get API key" ثم "Create API key in new project".
  4. انسخ المفتاح الذي تم إنشاؤه واحفظه في مكان آمن في الوقت الحالي. تعامل مع هذا المفتاح ككلمة مرور؛ لا تعرضه علنًا أبدًا.

الخطوة 1: تهيئة مشروع Next.js

سنستخدم Next.js، إطار عمل React الرائد لبناء تطبيقات جاهزة للإنتاج. يتكامل نموذج App Router الخاص به بشكل مثالي مع طبيعة تطبيقات الذكاء الاصطناعي التي تركز على الخادم.

افتح الطرفية الخاصة بك ونفذ هذا الأمر لإنشاء مشروع جديد:

npx create-next-app@latest vercel-ai-tutorial

سيطالبك المثبت بعدة أسئلة. استخدم هذه الإعدادات للمتابعة بسلاسة:

بمجرد اكتمال التثبيت، انتقل إلى دليل المشروع الذي أنشأته حديثًا:

cd vercel-ai-tutorial

الخطوة 2: تثبيت Vercel AI SDK

الآن، دعنا نضيف حزم AI SDK إلى مشروعنا.

npm install ai @ai-sdk/react @ai-sdk/google zod

دعنا نفصل ما تفعله كل من هذه الحزم:

الخطوة 3: تأمين مفتاح واجهة برمجة التطبيقات الخاص بك

لا تقم أبدًا بترميز مفتاح واجهة برمجة التطبيقات (API key) مباشرة في التعليمات البرمجية لتطبيقك. إنه يمثل خطرًا أمنيًا كبيرًا. المعيار الاحترافي هو استخدام متغيرات البيئة. يدعم Next.js هذا بشكل مدمج باستخدام ملفات .env.local.

قم بإنشاء الملف في جذر مشروعك:

touch .env.local

الآن، افتح هذا الملف الجديد وأضف مفتاح Google AI الخاص بك:

# .env.local
# هذا الملف مخصص للتطوير المحلي ويجب عدم إضافته إلى git.
GOOGLE_GENERATIVE_AI_API_KEY=YOUR_GOOGLE_AI_API_KEY

استبدل YOUR_GOOGLE_AI_API_KEY بالمفتاح الذي نسخته سابقًا. يقوم Next.js تلقائيًا بتحميل هذا الملف ويجعل المفتاح متاحًا على الخادم، وهو بالضبط حيث نحتاجه.

الفصل الثاني: بناء الهيكل الأساسي لروبوت الدردشة

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

بنية العميل-الخادم لتطبيق الذكاء الاصطناعي

سيحتوي روبوت الدردشة الخاص بنا على جزأين رئيسيين:

  1. مسار واجهة برمجة تطبيقات على جانب الخادم (/api/chat/route.ts): هذه بيئة آمنة تعمل على خادم. وظيفتها الأساسية هي استقبال سجل الدردشة من متصفح المستخدم، إضافة مفتاح واجهة برمجة التطبيقات السري الخاص بنا، إعادة توجيه الطلب إلى خدمة Google AI، ثم تدفق الاستجابة مرة أخرى إلى المستخدم. الحفاظ على هذا المنطق على الخادم أمر بالغ الأهمية للأمان - فهو يضمن عدم تعرض مفتاح واجهة برمجة التطبيقات الخاص بنا للجمهور أبدًا.
  2. واجهة مستخدم على جانب العميل (page.tsx): هذا هو مكون React الذي يعمل في متصفح المستخدم. إنه مسؤول عن عرض سجل الدردشة، والتقاط إدخال المستخدم، وإرسال هذا الإدخال إلى مسار واجهة برمجة التطبيقات الخاص بنا.

هذا الفصل أساسي لبناء تطبيقات ويب آمنة وعالية الأداء.

الخطوة 4: إنشاء معالج مسار واجهة برمجة التطبيقات

دعنا ننشئ نقطة النهاية على جانب الخادم. في دليل src/app الخاص بك، أنشئ مجلدًا جديدًا باسم api، وداخل ذلك، مجلدًا آخر باسم chat. أخيرًا، أنشئ ملفًا باسم route.ts داخل مجلد chat.

المسار النهائي يجب أن يكون src/app/api/chat/route.ts.

املأ هذا الملف بالتعليمات البرمجية التالية:

// src/app/api/chat/route.ts

import { google } from '@ai-sdk/google';
import { streamText } from 'ai';

// إعداد خاص بـ Vercel للسماح بتدفق الاستجابات لمدة تصل إلى 30 ثانية
export const maxDuration = 30;

// معالج مسار واجهة برمجة التطبيقات الرئيسي
export async function POST(req: Request) {
  try {
    // استخراج مصفوفة `messages` من نص الطلب
    const { messages } = await req.json();

    // استدعاء موفر الذكاء الاصطناعي مع سجل المحادثة
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // توفر مصفوفة `messages` النموذج بالسياق للمحادثة
      messages,
    });

    // الاستجابة باستجابة متدفقة
    return result.toDataStreamResponse();
  } catch (error) {
    // من الممارسات الجيدة التعامل مع الأخطاء المحتملة
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'An unknown error occurred' }), { status: 500 });
  }
}

دعنا نحلل هذا الملف الهام:

الخطوة 5: صياغة واجهة المستخدم

الآن للجزء الممتع: بناء واجهة المستخدم. بفضل حزمة @ai-sdk/react، هذا بسيط بشكل مدهش. افتح ملف الصفحة الرئيسية في src/app/page.tsx واستبدل محتواه بالكامل بما يلي:

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // مرجع لحاوية الرسائل القابلة للتمرير
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // تأثير للتمرير إلى أسفل حاوية الرسائل كلما تغيرت الرسائل
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* حاوية الرسائل */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* عرض صورة المستخدم الرمزية */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* فقاعة الرسالة */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'You' : 'AI Assistant'}</span>
              {m.content}
            </div>

            {/* عرض صورة الذكاء الاصطناعي الرمزية */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
            )}
          </div>
        ))}
      </div>

      {/* نموذج الإدخال */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Ask me anything..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Send
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

هذا قدر كبير من التعليمات البرمجية، ولكن معظمه مخصص لإنشاء واجهة مستخدم مصقولة باستخدام Tailwind CSS. دعنا نركز على المنطق:

الخطوة 6: تشغيل تطبيقك

لقد قمت الآن ببناء روبوت دردشة ذكاء اصطناعي كامل ومنظم بشكل جيد. دعنا نشغله!

npm run dev

انتقل إلى http://localhost:3000 في متصفحك. يجب أن تستقبلك واجهة دردشة مصقولة. اطرح سؤالاً. سترى رسالتك تظهر فورًا، وستتدفق استجابة الذكاء الاصطناعي رمزًا برمز (token by token).

الفصل الثالث: القدرات المتقدمة - منح روبوت الدردشة الخاص بك قوى خارقة

روبوت الدردشة الخاص بنا ذكي، لكن معرفته محدودة ببيانات التدريب الخاصة به. لا يمكنه الوصول إلى المعلومات الحية أو أداء إجراءات في العالم الحقيقي. في هذا الفصل، سنمنحه "أدوات" للتغلب على هذه القيود.

ما هي الأدوات؟

الأداة هي دالة تقوم بتعريفها يمكن لنموذج اللغة الكبير (LLM) اختيار تنفيذها. تصف الأداة للنموذج، وعندما يعتقد النموذج أن الأداة ضرورية للإجابة على استعلام المستخدم، سيوقف توليد النص وبدلاً من ذلك يخرج كائن "استدعاء أداة" (tool call) خاص. يقوم التعليمات البرمجية الخاصة بك بعد ذلك بتنفيذ الدالة باستخدام الوسائط التي يوفرها النموذج، ويتم إرسال النتيجة مرة أخرى إلى النموذج. يستخدم النموذج بعد ذلك هذه المعلومات الجديدة لتوليد استجابته النهائية الأكثر دقة.

دعنا نمكّن روبوت الدردشة الخاص بنا بأداتين:

  1. أداة للحصول على الطقس الحالي لموقع معين.
  2. أداة لتحويل درجات الحرارة من فهرنهايت إلى مئوي.

سيسمح هذا لروبوتنا بالإجابة على أسئلة مثل "ما هو الطقس في لندن بالمئوي؟" - وهي مهمة تتطلب خطوات متعددة وبيانات خارجية.

الخطوة 7: ترقية واجهة برمجة التطبيقات لدعم الأدوات

نحتاج إلى تعريف أدواتنا في استدعاء streamText على الخادم. افتح src/app/api/chat/route.ts وقم بتعديله ليشمل تعريف tools الجديد.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // تعريف الأدوات التي يمكن للنموذج استخدامها
    tools: {
      getWeather: tool({
        description: 'Get the current weather for a specific location. Always returns temperature in Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('The city and state, e.g., San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // في تطبيق حقيقي، ستقوم بالاستعلام من واجهة برمجة تطبيقات طقس حقيقية
          console.log(`Fetching weather for ${location}`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Convert a temperature from Fahrenheit to Celsius.',
        parameters: z.object({
          temperature: z.number().describe('The temperature in Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Converting ${temperature}°F to Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

دعنا نحلل كائن tools:

الخطوة 8: تمكين استدعاءات الأدوات متعددة الخطوات في واجهة المستخدم

مجرد تعريف الأدوات على الخادم ليس كافيًا. بشكل افتراضي، عندما يقوم النموذج باستدعاء أداة، تتوقف المحادثة. نحتاج إلى إخبار خطاف useChat الخاص بنا بإرسال نتيجة استدعاء الأداة تلقائيًا مرة أخرى إلى النموذج حتى يتمكن من متابعة تفكيره وصياغة إجابة نهائية.

هذا بسيط للغاية. في src/app/page.tsx، قم بتحديث تهيئة خطاف useChat:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // أخبر الخطاف بإرسال نتائج الأداة تلقائيًا مرة أخرى إلى النموذج
    experimental_sendExtraToolMessages: true,
  });
  // ... بقية المكون
}

هذا كل شيء. الخاصية experimental_sendExtraToolMessages: true تنشط تدفق استخدام الأدوات متعدد الخطوات.

الخطوة 9: واجهة مستخدم أفضل لاستدعاءات الأدوات

واجهة المستخدم الحالية لدينا تعرض فقط m.content. عندما يتم استدعاء أداة، تكون المعلومات المثيرة للاهتمام في خاصية مختلفة على كائن الرسالة. دعنا ننشئ مكونًا مخصصًا لعرض استدعاءات الأدوات بشكل جميل.

أولاً، دعنا نحدث حلقة الرسائل الرئيسية في src/app/page.tsx لعرض هذه الاستدعاءات.

// src/app/page.tsx

// ... داخل عبارة الإرجاع لمكون Chat
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... صور رمزية ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'You' : 'AI Assistant'}</span>

        {/* عرض استدعاءات الأدوات */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Tool Call: `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... صور رمزية ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

لقد أضفت أيضًا مؤشر كتابة بسيط يظهر بينما يفكر المساعد. ستحتاج إلى إضافة بعض CSS له. في ملف src/app/globals.css الخاص بك، أضف:

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

الآن، قم بتشغيل التطبيق مرة أخرى. اسأله: "ما هو الطقس في نيويورك بالمئوي؟" سترى سلسلة رائعة من الأحداث تتكشف في واجهة المستخدم الخاصة بك:

  1. سيقوم النموذج أولاً باستدعاء أداة getWeather. سترى استدعاء الأداة المعروض في واجهة المستخدم.
  2. يتم إرسال النتيجة (درجة حرارة عشوائية بالفهرنهايت) مرة أخرى إلى النموذج.
  3. سيقوم النموذج، وهو يعلم أنه يحتاج إلى المئوي، باستدعاء أداة convertFahrenheitToCelsius، باستخدام درجة الحرارة من نتيجة الأداة الأولى كمدخل له.
  4. أخيرًا، مع درجة الحرارة بالمئوي في متناول اليد، سيولد استجابة بلغة طبيعية تجيب على سؤالك الأصلي.

هذه هي قوة بناء وكلاء الذكاء الاصطناعي (AI Agents)، وVercel AI SDK يجعل هذا التنظيم المعقد مباشرًا بشكل ملحوظ.

الفصل الرابع: إلى أين تتجه من هنا؟

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

لقد قدم لك هذا الدليل أساسًا قويًا، لكنه مجرد البداية. Vercel AI SDK لديه المزيد ليقدمه. إليك بعض المسارات لاستكشافك المستمر:

مستقبل تطوير الويب ذكي، تفاعلي، وشخصي. مع Vercel AI SDK، أنت الآن تمتلك الأدوات والمعرفة لتكون في طليعة هذه الثورة. بناء سعيد!

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تولد توثيقًا جميلًا لواجهات برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر معقول أكثر بكثير!
button

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل