استخدام Prompt API المضمّنة مع حزمة Vercel AI SDK

Thomas Steiner

تاريخ النشر: 16 يوليو 2026

AI SDK من Vercel هي مجموعة أدوات TypeScript مستقلة عن موفّر الخدمة ومصمَّمة لمساعدتك في إنشاء تطبيقات ووكلاء مستندين إلى الذكاء الاصطناعي باستخدام أُطر واجهة المستخدم الشائعة، مثل Next.js وReact وSvelte وVue وAngular، وبيئات التشغيل، مثل Node.js. مع أنّ معظم مقدّمي الخدمات يعتمدون على السحابة الإلكترونية، يركّز هذا الدليل الأول من سلسلة مؤلّفة من جزأين على مقدّم خدمات تابع للمنتدى يُدعى Browser AI، وهو من إنشاء جاكوب هوغ مورك (الذي حصل على تمويل من Google). تتيح لك ميزة "الذكاء الاصطناعي في المتصفّح" استخدام Prompt API مع حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي من Vercel. يوضّح الجزء الثاني من السلسلة كيفية إضافة واجهة مستخدم رسومية إلى تطبيق الذكاء الاصطناعي.

تثبيت المكتبة

حزمة @browser-ai/core هي موفِّر حزمة تطوير البرامج (SDK) للذكاء الاصطناعي لواجهة برمجة التطبيقات Prompt API. يمكنك تثبيته باستخدام npm. يتم تثبيت حزمة تطوير البرامج (SDK) الأساسية من Vercel AI تلقائيًا بواسطة الحزمة كإحدى التبعيات المتساوية.

npm install @browser-ai/core

الاستخدام الأساسي

لاستخدام موفّر الخدمة، اتّبِع الخطوات التالية:

1. استورِد الدالة الإنشائية browserAI من حزمة @browser-ai/core.
2. استورِد الدالتَين generateText() أو streamText() من Vercel AI SDK. تنشئ كلتا الدالتين نصًا وتستدعيان أدوات بناءً على طلب معيّن باستخدام نموذج لغوي:

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

لإنشاء مثيل نموذج، اتّبِع الخطوات التالية:

1. تواصل هاتفيًا مع "browserAI()". ملاحظة: من أفضل الممارسات التحقّق دائمًا من availability() للنموذج، ما يتيح لك استخدام خيار احتياطي (راجِع الاستخدام المختلط) عندما تكون حالة النموذج 'unavailable'، أو عرض تحديث عن مستوى التقدّم عندما تكون حالة النموذج 'downloadable' أو 'downloading'.

2. يمكنك بعد ذلك الاتصال بالرقم generateText() أو streamText(). راجِع مستندات Vercel AI SDK للحصول على القائمة الكاملة بالمعلمات، على سبيل المثال، بدلاً من تمرير prompt مباشرةً كما في عيّنة الرمز البرمجي التالية، يمكنك أيضًا تمرير عنصر messages أكثر تعقيدًا لطلب متعدد اللقطات، أو تمرير طلب system.

import { browserAI } from '@browser-ai/core';
import { generateText, streamText } from 'ai';

(async () => {
  const model = browserAI();
  const availability = await model.availability();

  if (availability === 'unavailable') {
    console.log('Your browser cannot run the built-in AI model.');
    return;
  }

  if (availability === 'downloadable' || availability === 'downloading') {
    await model.createSessionWithProgress((progress) => {
      console.log(`Download progress: ${Math.round(progress * 100)}%`);
    });
  }

  // Non-streaming text generation.
  const { text } = await generateText({
    model,
    prompt: 'Tell me a short joke',
  });
  console.log(text);

  // Streaming text generation.
  const result = streamText({
    model,
    prompt: 'Tell me a long joke',
  });

  for await (const chunk of result.textStream) {
    console.log(chunk);
  }
})();

استخدام متعدد الوسائط

تتيح حزمة @browser-ai/core إدخال بيانات متعددة الوسائط باستخدام عنصر type: 'file' في مصفوفة messages ضمن عناصر المحتوى.

content حقول الكائن (type: 'file')

type

'file'

data

string | Uint8Array | Buffer | ArrayBuffer | URL

عندما يكون data string، يجب أن يكون أحد ما يلي:

راجِع مقتطف الرمز التالي للاطّلاع على مثال:

import { streamText } from 'ai';
import { browserAI } from '@browser-ai/core';

const base64ImageData = await getBase64ImageData();
const audioData = await getAudioBuffer();

const result = streamText({
  model: browserAI(),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: "What's in this image?" },
        { type: 'file', mediaType: 'image/png', data: base64ImageData },
      ],
    },
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Transcribe this audio file!' },
        { type: 'file', mediaType: 'audio/mp3', data: audioData },
      ],
    },
  ],
});

for await (const chunk of result.textStream) {
  console.log(chunk);
}

ناتج منظَّم

تتيح حزمة Vercel AI SDK إخراج البيانات المنظَّمة من خلال zod، وهي أداة للتحقّق من صحة المخططات تستند إلى TypeScript وتتضمّن ميزة استنتاج الأنواع الثابتة. يمكنك الاطّلاع على مستندات تحديد المخططات في zod لمعرفة التفاصيل.

لطلب عنصر JSON يطابق المخطط، مرِّر output: Output.object({ schema }) إلى generateText() أو streamText():

• تعرض generateText() مع Output.object() عنصر JSON النهائي في الحقل output بعد اكتمال عملية الإنشاء.
• توفّر streamText() مع Output.object() تكرارًا غير متزامن partialOutputStream حيث يُضمن تحليل كل نتيجة وسيطة بشكل صحيح بتنسيق JSON. على سبيل المثال، إذا كان المخطط يفرض مصفوفة من رقمين، ستتلقّى [] كنتيجة جزئية أولى، و[123] كنتيجة جزئية ثانية، و[123, 456] كنتيجة نهائية.

import { browserAI } from '@browser-ai/core';
import { generateText, streamText, Output } from 'ai';
import z from 'zod';

const model = browserAI();

const schema = z.object({
  recipe: z.object({
    name: z.string(),
    ingredients: z.array(z.object({ name: z.string(), amount: z.string() })),
    steps: z.array(z.string()),
  }),
});

const prompt = 'Generate a lasagna recipe.';

// Non-streaming object generation.
const { output } = await generateText({
  model,
  output: Output.object({ schema }),
  prompt,
});

console.log(output);

// Streaming object generation.
const { partialOutputStream } = streamText({
  model,
  output: Output.object({ schema }),
  prompt,
});

for await (const partialObject of partialOutputStream) {
  console.log(partialObject);
}

الاستخدام المختلط

تتفوّق حزمة تطوير البرامج (SDK) المستندة إلى الذكاء الاصطناعي من Vercel في الاستخدام المختلط. وهي توفّر طبقة تجريد أعلى مستوى فوق عمليات التنفيذ الأدنى مستوى التي توفّرها الجهات الأساسية. عند استخدام Prompt API كموفّر، يمكنك إنشاء model من خلال استدعاء الدالة الإنشائية browserAI.

import { browserAI } from '@browser-ai/core';

const model = browserAI();

لاستخدام مقدّم خدمة مختلف، مثل مقدّم خدمة الذكاء الاصطناعي التوليدي من Google، عليك اتّباع الخطوات التالية:

1. ثبِّت مقدّم الخدمة المحدّد.

   npm install @ai-sdk/google
   

2. أنشئ مثيلاً من model باستخدام أداة إنشاء الموفّر، والتي تتضمّن عادةً تمرير مفتاح واجهة برمجة التطبيقات لموفّري الخدمات السحابية، مثل Google الذكاء الاصطناعي التوليدي. في حالة مقدّم خدمة الذكاء الاصطناعي التوليدي من Google، يمكنك أيضًا تمرير معرّف نموذج سحابي، مثل 'gemini-2.5-flash'. ستبقى بقية الرمز، مثل طلباتك إلى streamText()، كما هي تمامًا.

   import { createGoogleGenerativeAI } from '@ai-sdk/google';
   
   const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';
   
   const google = createGoogleGenerativeAI({ apiKey: API_KEY });
   const model = google('gemini-2.5-flash');
   

الرجوع إلى السحابة الإلكترونية

تتمثل إحدى حالات الاستخدام الكلاسيكية المختلطة في استخدام Prompt API عندما يكون متاحًا والرجوع إلى مقدّم خدمات السحابة الإلكترونية في حالات أخرى. للتحقّق من توفّر Prompt API، توفّر حزمة @browser-ai/core الدالة doesBrowserSupportBuiltInAI(). يمكنك استخدام هذه الدالة لإنشاء مثيل ديناميكي model كنموذج مستند إلى السحابة الإلكترونية أو نموذج مضمّن.

import { doesBrowserSupportBuiltInAI } from '@browser-ai/core';

const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';

const model = await (async () => {
  if (doesBrowserSupportBuiltInAI()) {
    const { browserAI } = await import('@browser-ai/core');
    return browserAI();
  }
  const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
  const google = createGoogleGenerativeAI({ apiKey: API_KEY });
  return google('gemini-2.5-flash');
})();

الإجراء الاحتياطي المضمَّن

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

import { doesBrowserSupportBuiltInAI } from '@browser-ai/core';

const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';

let model;

const switchProvider = async (forceCloud = false) => {
  model = await (async () => {
    if (navigator.onLine || forceCloud) {
      const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
      const google = createGoogleGenerativeAI({ apiKey: API_KEY });
      return google('gemini-2.5-flash');
    }
    const { browserAI } = await import('@browser-ai/core');
    return browserAI();
  })();
};

if (doesBrowserSupportBuiltInAI()) {
  window.addEventListener('online', switchProvider);
  window.addEventListener('offline', switchProvider);
}
await switchProvider(true);

عرض توضيحي

يتيح لك العرض التوضيحي المباشر تجربة كلا مقدّمي الخدمة جنبًا إلى جنب. اختَر Cloud API (Gemini 2.5 Flash) أو الذكاء الاصطناعي المضمّن من أزرار الاختيار، ثم انقر على تشغيل، وشاهِد الصفحة وهي تملأ أربعة أقسام بالتسلسل: نكتة قصيرة تم إنشاؤها دفعة واحدة باستخدام generateText()، ونكتة طويلة تم بثها رمزًا مميزًا تلو الآخر باستخدام streamText()، ووصفة لازانيا تم عرضها ككائن JSON كامل، ثم بث الوصفة نفسها كملف JSON صالح بشكل تدريجي باستخدام partialOutputStream. إذا اخترت الذكاء الاصطناعي المضمّن ولم يسبق أن نزّل متصفّحك النموذج، سيظهر مؤشر تقدّم قبل بدء العروض التوضيحية.

الخطوة التالية

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

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

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

يمكنك الاطّلاع على استخدام واجهة مستخدم Vercel AI SDK وعناصر الذكاء الاصطناعي مع Prompt API للتعرّف على كيفية إضافة واجهة مستخدم رسومية إلى تطبيقك.