Vercel AI SDK: دليل المطور الشامل لبناء تطبيقات الذكاء الاصطناعي

Vercel AI SDK هو مجموعة أدوات TypeScript لبناء تطبيقات الذكاء الاصطناعي. يتولى إنشاء النصوص، البث المباشر، المخرجات المنظمة، استدعاءات الأدوات، وحلقات الوكيل متعددة الخطوات من خلال واجهة برمجة تطبيقات (API) موحدة واحدة — ويعمل مع أي مزود رئيسي لنماذج LLM الكبيرة. إذا كنت قد حاولت توصيل OpenAI أو Anthropic مباشرة في تطبيق Next.js وانتهى بك الأمر بصيانة ثلاثة تطبيقات بث مختلفة، فإن هذا SDK يحل هذه المشكلة.

يغطي هذا الدليل القدرات الأساسية لـ SDK، وكيفية توصيله بواجهة Novita AI المتوافقة مع OpenAI LLM API، وأين تتناسب سير عمل الوكيل للمطورين الذين يبنون أكثر من مجرد روبوت محادثة بسيط.

ما هو Vercel AI SDK؟

Vercel AI SDK (الحزمة: ai على npm) هي مكتبة مفتوحة المصدر تلخص الاختلافات بين مزودي LLM. بدلاً من تعلم بروتوكولات بث منفصلة لكل من OpenAI وAnthropic وGoogle، تستخدم نفس الدوال generateText و streamText و generateObject وتتبدل بين المزودين بتغيير استيراد واحد.

يتكون SDK من طبقتين:

• AI SDK Core يتولى التفاعلات مع النموذج: إنشاء النصوص، البث، الكائنات المنظمة، استدعاءات الأدوات، التضمينات، وحلقات الوكيل.
• AI SDK UI يوفر خطافات React (useChat، useCompletion، useObject، useAssistant) بالإضافة إلى محولات لـ Next.js وSvelteKit وNuxt تدير حالة البث في المتصفح.

هناك أيضًا حزمة @ai-sdk/openai-compatible للاتصال بأي مزود يطبق تنسيق OpenAI Chat Completions — وهذا هو كيفية دمج Novita AI.

يعمل SDK في بيئات Node.js وDeno وبيئات التشغيل الطرفية (Cloudflare Workers وVercel Edge) والمتصفح.

جوهر AI SDK Core: generateText و streamText و generateObject

قم بتثبيت SDK وحزمة المزود:

npm install ai @ai-sdk/openai

generateText

للاستكمالات غير المباشرة — المعالجة المجمعة، التصنيف، التوليد ذو الخطوة الواحدة:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: 'Explain how LLM embeddings work in two sentences.',
});

console.log(text);

streamText

لواجهات الدردشة حيث زمن الانتظار مهم:

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

const result = streamText({
  model: openai('gpt-4o-mini'),
  messages: [
    { role: 'user', content: 'Walk me through setting up a Next.js app.' },
  ],
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

generateObject

عندما تحتاج إلى مخرجات JSON منظمة بدلاً من النص الخام — يتم التحقق من المخطط تلقائيًا باستخدام Zod:

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-4o-mini'),
  schema: z.object({
    name: z.string(),
    skills: z.array(z.string()),
    experienceLevel: z.enum(['junior', 'mid', 'senior']),
  }),
  prompt: 'Generate a fictional software engineer profile.',
});

console.log(object.name, object.skills);

يتولى SDK حقن التعليمات النموذجية (system prompt) اللازمة لإجبار النموذج على إنتاج JSON صحيح وإعادة المحاولة عند المخرجات غير الصالحة.

أدوات AI SDK: استدعاء الدوال واستخدام الأدوات

تسمح الأدوات للنماذج باستدعاء دوال خارجية — واجهات البحث، استعلامات قواعد البيانات، الآلات الحاسبة — أثناء التوليد. معامل tools في SDK يأخذ كائنًا حيث يصبح كل مفتاح دالة قابلة للاستدعاء:

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { text, toolCalls } = await generateText({
  model: openai('gpt-4o-mini'),
  tools: {
    getWeather: tool({
      description: 'Get current weather for a location',
      parameters: z.object({
        city: z.string().describe('City name'),
        unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
      }),
      execute: async ({ city, unit }) => {
        // Replace with a real weather API call
        return { city, temperature: 22, unit, condition: 'sunny' };
      },
    }),
  },
  prompt: 'What is the weather in Tokyo right now?',
});

console.log(text);

المساعد tool() يوفر استدلالًا على الأنواع (type inference) من مخطط Zod إلى معاملات الدالة execute. لا حاجة للتحليل اليدوي لـ JSON.

استدعاءات الأدوات متعددة الخطوات

افتراضيًا، يتوقف generateText بعد جولة واحدة من استدعاءات الأدوات. اضبط maxSteps للسماح للنموذج باستخدام نتائج الأدوات في التفكير المتابع:

const { text } = await generateText({
  model: openai('gpt-4o'),
  maxSteps: 5,
  tools: { getWeather, searchWeb, lookupCalendar },
  prompt: 'Plan my outdoor activities for this weekend in Berlin.',
});

يتولى SDK حلقة استدعاء الأداة → النتيجة → الاستمرار تلقائيًا. يتم كشف كل خطوة عبر onStepFinish إذا كنت بحاجة إلى رؤية التفكير الوسيط.

بناء حلقات وكلاء الذكاء الاصطناعي باستخدام Vercel AI SDK

الوكيل في AI SDK هو نموذج يعمل في حلقة مع الأدوات حتى يقرر أن لديه معلومات كافية للإجابة. النمط هو نفسه استدعاء الأدوات متعدد الخطوات، ولكن مع أدوات أكثر وقيمة maxSteps أطول:

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const result = await generateText({
  model: openai('gpt-4o'),
  maxSteps: 10,
  system: 'You are a research assistant. Use available tools to answer thoroughly.',
  prompt: 'What are the main differences between Llama 3.1 and Qwen3?',
  tools: {
    search: tool({
      description: 'Search the web for current information',
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => searchWeb(query),
    }),
    summarize: tool({
      description: 'Summarize a URL',
      parameters: z.object({ url: z.string() }),
      execute: async ({ url }) => fetchAndSummarize(url),
    }),
  },
  onStepFinish({ stepType, toolCalls, toolResults }) {
    console.log('Step:', stepType, toolCalls?.map(t => t.toolName));
  },
});

لخطوط أنابيب الوكيل الإنتاجية، قم بتوصيل Novita AI كخلفية للنموذج للتحكم في التكلفة والإنتاجية على نطاق واسع — موضوع القسم التالي.

AI SDK React: خطاف useChat ودمج Next.js

يدير خطاف useChat حالة الدردشة المباشرة دون حاجة لكتابة كود متكرر:

// app/chat/page.tsx
'use client';
import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id} className={m.role === 'user' ? 'user' : 'assistant'}>
          {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask something..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}

معالج المسار المقابل:

// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

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

  const result = streamText({
    model: openai('gpt-4o-mini'),
    messages,
  });

  return result.toDataStreamResponse();
}

تتعامل toDataStreamResponse() مع بروتوكول تيار Vercel AI، الذي يفهمه useChat في العميل بشكل أصلي. لتيار الكائنات المنظمة من واجهة API، استبدل useChat بـ useObject و streamText بـ streamObject.

كيفية استخدام Novita AI مع Vercel AI SDK

توفر Novita AI واجهة API متوافقة مع OpenAI على https://api.novita.ai/v3/openai، مما يجعلها بديلاً جاهزًا لأي SDK يستخدم تنسيق OpenAI Chat Completions — بما في ذلك Vercel AI SDK.

لماذا استخدام Novita AI مع AI SDK

تستضيف Novita AI أكثر من 70 نموذجًا مفتوح المصدر — Llama 3.3 70B، Qwen3، DeepSeek V3، Mistral، وGemma 3 — عبر نقطة نهاية API واحدة. لا حاجة لإدارة بنية GPU التحتية. لسير عمل الوكيل، تتدرج API غير الخادمة من نماذج تعليمات صغيرة بحجم 7B إلى نماذج استدلال كبيرة دون تغيير في التكوين.

الإعداد

قم بتثبيت حزمة المزود المتوافقة مع OpenAI:

npm install ai @ai-sdk/openai-compatible

قم بتكوين المزود:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const novita = createOpenAICompatible({
  name: 'novita',
  baseURL: 'https://api.novita.ai/v3/openai',
  apiKey: process.env.NOVITA_API_KEY,
});

هذا هو الإعداد الكامل. الآن استخدمه تمامًا مثل أي مزود آخر في AI SDK:

import { generateText } from 'ai';

const { text } = await generateText({
  model: novita('meta-llama/llama-3.3-70b-instruct'),
  prompt: 'What are the tradeoffs between RAG and fine-tuning for a customer support bot?',
});

البث يعمل بنفس الطريقة:

import { streamText } from 'ai';

const result = streamText({
  model: novita('qwen/qwen3-235b-a22b-instruct-2507'),
  messages: [
    { role: 'system', content: 'You are a helpful coding assistant.' },
    { role: 'user', content: 'Show me how to build a REST API with FastAPI.' },
  ],
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

استدعاءات الأدوات مع Novita AI

النماذج التي تدعم استدعاء الدوال تعمل مع واجهة أدوات AI SDK دون أي تكوين إضافي. يدعم Llama 3.3 70B Instruct وQwen3 استدعاءات الأدوات عبر API Novita:

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text } = await generateText({
  model: novita('meta-llama/llama-3.3-70b-instruct'),
  maxSteps: 5,
  tools: {
    calculator: tool({
      description: 'Evaluate a mathematical expression',
      parameters: z.object({ expression: z.string() }),
      execute: async ({ expression }) => {
        return { result: eval(expression) }; // use a safe math parser in production
      },
    }),
  },
  prompt: 'What is 12% of 847, then divide by 3.14?',
});

إعداد البيئة

أضف مفتاح Novita API إلى .env.local:

NOVITA_API_KEY=your_novita_api_key_here

احصل على مفتاح على novita.ai — الحسابات الجديدة تشمل أرصدة مجانية لاختبار API.

Agent Sandbox لأحمال العمل الأطول زمنيًا

لمهام الوكيل التي تشغل كودًا، أو تصل إلى أنظمة الملفات، أو تنفذ سير عمل لعدة دقائق، يوفر Novita AI Agent Sandbox بيئات تنفيذ معزولة فوق API LLM. يتولى AI SDK طبقة استدلال النموذج. يتولى الصندوق الرملي التنفيذ الحالّي الذي لا يمكن تشغيله داخل مهلة دالة الحافة.

اختيار مزود LLM لـ Vercel AI SDK

يجعل AI SDK التبديل بين المزودين سهلاً، وهو أمر مفيد — ولكن من المفيد فهم المفاضلات قبل اختيار مزود للإنتاج.

زمن الانتظار: الوقت للرمز الأول (Time-to-first-token) أهم من سرعة التوليد الكلية للدردشة المباشرة. النماذج الأصغر (8B–14B) تنتج الرموز الأولى أسرع. نقاط نهاية Novita AI غير الخادمة مُحسَّنة لزمن انتظار بدء تشغيل منخفض للنماذج المفتوحة.

التكلفة على نطاق واسع: GPT-4o ممتاز، ولكن في أحجام الاستعلام العالية، تصبح فجوة السعر بين النموذج الحدودي ونموذج مفتوح مُضبَّط جيدًا (مثل Llama 3.3 70B) كبيرة. يسمح لك AI SDK بتجربة كليهما دون إعادة كتابة منطق التطبيق.

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

نافذة السياق: لمهام RAG ذات المستندات الكبيرة أو سجلات المحادثة الطويلة، تحقق من حدود السياق. تدعم العديد من النماذج المفتوحة 128K رمزًا، وهو ما يغطي معظم حالات الاستخدام العملية.

الارتباط بمزود معين: تجريد مزود AI SDK مع نقطة نهاية Novita AI المتوافقة مع OpenAI يعني أنه يمكنك تبديل النماذج أو إضافة مزود احتياطي دون لمس كود التطبيق.

الخلاصة

يزيل Vercel AI SDK الكود التكراري من بناء تطبيقات الذكاء الاصطناعي — API واحدة لتوليد النصوص، البث، استدعاءات الأدوات، وحلقات الوكيل عبر أي مزود LLM. سواء كنت تبني واجهة دردشة مباشرة مع useChat، أو تستخرج بيانات منظمة بـ generateObject، أو تدير وكيلًا متعدد الخطوات يستدعي أدوات خارجية، فإن SDK يتولى الأعمال السباكة لتتمكن من التركيز على منطق التطبيق.

للاستدلال بالنماذج المفتوحة، تتصل API Novita AI المتوافقة مع OpenAI مباشرة بـ SDK عبر @ai-sdk/openai-compatible. تحصل على الوصول إلى أكثر من 70 نموذجًا — Llama، Qwen3، DeepSeek، Mistral — دون إدارة بنية GPU التحتية، ويمكنك تبديل النماذج أو إضافة مزودين احتياطيين دون لمس كود التطبيق.

ابدأ على novita.ai — الحسابات الجديدة تشمل أرصدة مجانية.

الأسئلة الشائعة

ما هو ai sdk react؟

دمج React الخاص بـ AI SDK موجود في حزمة ai/react. يوفر خطافات — useChat، useCompletion، useObject، useAssistant — تربط واجهة أمامية React بمسار بث من جانب الخادم. تتعامل الخطافات مع حالة البث، سجل الرسائل، مؤشرات التحميل، ومعالجة الأخطاء، لذا لا تضطر لإدارة ReadableStream في حالة المكون.

ما الذي يضيفه ai sdk 5؟

أعاد AI SDK 5 (الذي تم إصداره كنسخة تجريبية في منتصف 2025) تصميم مواصفات المزود لتحسين أمان الأنواع، وفصل إدارة حالة واجهة المستخدم عن منطق التفاعل مع النموذج، وقدم تنسيق رسائل منقح يجعل حالة واجهة المستخدم الوكيلة أسهل في التسلسل. إذا كنت تبدأ مشروعًا جديدًا في 2026، تحقق من ai-sdk.dev لأحدث إصدار مستقر — استمر SDK في التطور عبر الإصدارات 6 و7.

هل هناك وثائق ai sdk يمكنني الرجوع إليها؟

الوثائق الرسمية موجودة على ai-sdk.dev. تتضمن أدلة إعداد المزود، مراجع API لجميع الدوال الأساسية، أدلة دمج الأطر (Next.js، Nuxt، SvelteKit)، وأمثلة من كتاب الطبخ للأنماط الشائعة مثل RAG وحلقات الوكيل والاستخراج المنظم.

هل يمكنني استخدام أدوات ai sdk مع نماذج غير OpenAI؟

نعم. أي مزود يدعم استدعاء الدوال يعمل مع واجهة tool() في AI SDK. تستضيف Novita AI عدة نماذج مفتوحة مع دعم استدعاء الدوال. تختلف جودة السلوك — يعد Llama 3.3 70B وQwen3 الأكثر موثوقية لاستخدام الأدوات متعددة الخطوات بين النماذج المفتوحة المتاحة عبر API Novita.

ما الفرق بين وثائق vercel ai sdk ووثائق ai-sdk.dev؟

إنهما نفس المنتج. الوثائق كانت سابقًا على sdk.vercel.ai وتعيد التوجيه إلى ai-sdk.dev. يتم صيانة SDK بواسطة فريق Vercel ولكنه مفتوح المصدر وغير مرتبط بالنشر على بنية Vercel التحتية.

كيف تقارن واجهات SDK للذكاء الاصطناعي بالاتصال المباشر بواجهة LLM API؟

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

مقالات مقترحة

• أي مزود استدلال هو المناسب لوكلاء الذكاء الاصطناعي
• بناء نظام متعدد الوكلاء باستخدام Novita وCrewAI
• أفضل مزودي LLM API في عام 2026