Blog

كيفية استخدام Google Gen AI TypeScript/JavaScript SDK لبناء تطبيقات ذكاء اصطناعي توليدية قوية

Mark Ponomarev

Mark Ponomarev

27 مايو 2025

كيفية استخدام Google Gen AI TypeScript/JavaScript SDK لبناء تطبيقات ذكاء اصطناعي توليدية قوية

يتطور عالم الذكاء الاصطناعي بسرعة، وتتصدر جوجل المشهد بنماذجها القوية Gemini. لمطوري TypeScript وJavaScript الذين يتطلعون إلى تسخير هذه القوة، توفر Google Gen AI SDK حلاً شاملاً ومرنًا. تُمكّنك هذه الحزمة من بناء تطبيقات مدعومة بسهولة بنماذج Gemini 2.5 وغيرها من النماذج المتطورة، مع دعم قوي لكل من Gemini Developer API وVertex AI. سيكون هذا المقال دليلك لفهم واستخدام هذه الحزمة، حيث يغطي ميزاتها الرئيسية بدءًا من التفاعلات الحية في الوقت الفعلي ومعالجة المحتوى متعدد الوسائط وصولاً إلى تحويل النص إلى كلام (TTS)، وتوليد الصور، والمزيد.

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

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

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

مقدمة: سد الفجوة بين JavaScript وقوة Gemini

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

من نقاط القوة الأساسية للحزمة هو نهجها الموحد للوصول إلى نماذج Gemini، بغض النظر عما إذا كانت مستضافة على منصة Gemini Developer (عبر مفاتيح API من Google AI Studio) أو منصة Vertex AI في Google Cloud. تتيح هذه المرونة للمطورين اختيار البيئة التي تناسب احتياجات مشروعهم على أفضل وجه، بدءًا من النماذج الأولية السريعة باستخدام مفتاح API وصولاً إلى عمليات النشر على مستوى الإنتاج على Vertex AI مع قدرات MLOps الخاصة بها.

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

البدء: التثبيت والتهيئة

قبل الغوص في الميزات المتقدمة، دعنا نغطي أساسيات إعداد الحزمة.

المتطلبات المسبقة:
تأكد من تثبيت Node.js الإصدار 18 أو أحدث في بيئة التطوير الخاصة بك.

التثبيت:
تثبيت الحزمة بسيط باستخدام npm:

npm install @google/genai

التهيئة - بوابتك إلى Gemini:
تبدأ جميع التفاعلات مع Gemini API، سواء من خلال Google AI Studio أو Vertex AI، بإنشاء مثيل لفئة GoogleGenAI.

1. استخدام Gemini Developer API (مع مفتاح API):
غالبًا ما تكون هذه هي أسرع طريقة للبدء، خاصة للتطبيقات من جانب الخادم أو المشاريع الشخصية. ستحتاج إلى مفتاح API من Google AI Studio.

import { GoogleGenAI } from '@google/genai';

const GEMINI_API_KEY = process.env.GEMINI_API_KEY; // Or your actual API key
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

async function run() {
  // Example: Generate text content
  const model = ai.models.generateContent({
    model: "gemini-pro", // Or a specific Gemini 2.5 model like "gemini-2.5-flash-001"
    contents: [{ role: "user", parts: [{ text: "Explain the significance of the Google Gen AI SDK." }] }]
  });
  const response = await model;
  console.log(response.text);
}

run();
تحذير بشأن أمان مفتاح API:

2. استخدام Vertex AI:
للتطبيقات التي تتطلب قوة وتوسعية Google Cloud، فإن تهيئة الحزمة لـ Vertex AI هي الطريقة الصحيحة. يتضمن ذلك تحديد معرّف مشروع Google Cloud الخاص بك والموقع.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location', // e.g., 'us-central1'
});

async function runVertex() {
  // Example: Generate text content with Vertex AI
  const model = ai.models.generateContent({
    model: "gemini-1.5-pro-preview-0409", // Example Vertex AI model
    contents: [{ role: "user", parts: [{ text: "What are the benefits of using Vertex AI with the Gen AI SDK?" }] }]
  });
  const response = await model;
  console.log(response.text);
}

runVertex();

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

لـ Vertex AI (التعيين إلى v1):

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location',
    apiVersion: 'v1'
});

لـ Gemini Developer API (التعيين إلى v1alpha لميزات مثل ai.live):

const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',
    apiVersion: 'v1alpha'
});

هيكل الحزمة الأساسي: كائن GoogleGenAI

بمجرد تهيئته، يكون الكائن ai (مثيل من GoogleGenAI) هو واجهتك الأساسية لقدرات الحزمة. يوفر الوصول إلى وحدات فرعية متنوعة، كل منها يلبي وظائف محددة:

بناء التطبيقات باستخدام نماذج Gemini 2.5

الحزمة هي خط اتصالك المباشر بقوة نماذج Gemini 2.5 (والإصدارات السابقة مثل Gemini 1.0 Pro، 1.5 Pro، و 1.5 Flash). لاستخدام نموذج معين، ما عليك سوى الإشارة إلى اسمه في معلمة model لطرق مثل ai.models.generateContent() أو عند إنشاء جلسة دردشة باستخدام ai.chats.create().

على سبيل المثال، لاستخدام نموذج gemini-2.5-flash-001 (اسم افتراضي، استبدله بمعرفات النماذج الفعلية عند إصدارها):

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash-001', // Use the specific model identifier
  contents: [{ role: "user", parts: [{ text: "Tell me about the key advancements in Gemini 2.5." }] }]
});
console.log(response.text);

تتعامل الحزمة مع مكالمات API الأساسية، مما يتيح لك التركيز على صياغة طلباتك ومعالجة المحتوى الذي تم إنشاؤه. عندما تصدر Google نماذج جديدة وتحدّث النماذج الحالية، يمكنك عادةً التبديل إليها ببساطة عن طريق تغيير سلسلة معرّف النموذج، مما يسهل الحفاظ على تطبيقاتك في طليعة التكنولوجيا.

تعمق: معالجة المحتوى متعدد الوسائط (MCP)

أحد أقوى جوانب نماذج Gemini هو قدرتها على فهم وإنشاء محتوى عبر وسائط متعددة (نص، صور، صوت، فيديو). تدعم Google Gen AI SDK هذا بالكامل، مما يمكّنك من بناء تطبيقات غنية ومتعددة الوسائط.

يتم تحقيق MCP بشكل أساسي من خلال معلمة contents في طرق مثل generateContent وsendMessage (في الدردشة). تأخذ مصفوفة contents سلسلة من كائنات Content، يمكن لكل منها أن يحتوي على كائنات Part متعددة. يمكن لكل Part أن يمثل نوعًا مختلفًا من البيانات.

هيكل المحتوى متعدد الوسائط:

مثال: طلب متعدد الوسائط (نص وصورة):

import { GoogleGenAI } from '@google/genai';
// ... (Initialization)

async function describeImage() {
  // Assume 'base64ImageData' is a Base64 encoded string of a JPEG image
  const base64ImageData = "..."; // Your Base64 image data

  const contents = [
    {
      role: "user",
      parts: [
        { text: "What is in this image?" },
        {
          inlineData: {
            mimeType: "image/jpeg",
            data: base64ImageData,
          },
        },
      ],
    },
  ];

  const response = await ai.models.generateContent({
    model: "gemini-pro-vision", // Or a Gemini 2.5 vision-capable model
    contents: contents,
  });
  console.log(response.text);
}

describeImage();

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

التفاعلات في الوقت الفعلي مع Live API (ai.live)

للتطبيقات التي تتطلب تجارب تفاعلية بزمن انتقال منخفض، تعد الوحدة الفرعية ai.live بمثابة تغيير في قواعد اللعبة. حاليًا في مرحلة المعاينة وتتطلب إصدار API v1alpha لـ Gemini API، تقوم ai.live بإنشاء اتصال WebSocket للبث ثنائي الاتجاه مع نماذج Gemini. يتيح ذلك الإرسال في الوقت الفعلي لكتل النص والصوت، وحتى إطارات الفيديو كإدخال، واستقبال النص أو الصوت كإخراج.

المفاهيم الأساسية لـ ai.live:

  1. ai.live.connect(params): هذه هي نقطة الدخول. تقوم بتوفير معلمات مثل اسم النموذج (model)، تكوين الاتصال (config)، ودوال رد الاتصال (callbacks) لأحداث WebSocket المختلفة (مثل onopen، onmessage، onerror، onclose). تُرجع Promise يتم حلها إلى كائن Session.
  2. كائن Session: يمثل اتصال WebSocket النشط. يحتوي على طرق لـ:

التكوين (LiveConnectParameters وLiveConnectConfig):

ردود الاتصال (LiveCallbacks):

مثال: إعداد ai.live أساسي (مفاهيمي):

import { GoogleGenAI, Modality } from '@google/genai';

// Ensure you initialize with apiVersion: 'v1alpha' for Gemini API
const ai = new GoogleGenAI({ apiKey: 'YOUR_GEMINI_API_KEY', apiVersion: 'v1alpha' });

async function startLiveSession() {
  try {
    const session = await ai.live.connect({
      model: 'gemini-pro', // Or a specific model supporting live, check documentation
      config: {
        responseModalities: [Modality.TEXT, Modality.AUDIO], // Expect text and audio back
        // speechConfig: { ... } // For TTS, covered below
      },
      callbacks: {
        onopen: () => console.log('Live session connected!'),
        onmessage: (serverMessage) => {
          // Process messages from the server
          // This could be text, audio data, tool calls, etc.
          console.log('Received from server:', serverMessage);
          if (serverMessage.speechUpdate?.audio) {
            // Handle incoming audio data (e.g., play it)
            const audioBytes = serverMessage.speechUpdate.audio;
            // ... your audio playback logic ...
          }
          if (serverMessage.textUpdate?.text) {
             console.log("Text: ", serverMessage.textUpdate.text);
          }
        },
        onerror: (error) => console.error('Live session error:', error),
        onclose: () => console.log('Live session closed.'),
      },
    });

    // Now you can send messages
    session.sendClientContent({ turns: [{ role: 'user', parts: [{text: 'Hello, live Gemini!'}] }] });

    // For continuous audio input:
    // navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
    //   const mediaRecorder = new MediaRecorder(stream);
    //   mediaRecorder.ondataavailable = event => {
    //     if (event.data.size > 0) {
    //       session.sendRealtimeInput({ media: { mediaChunks: [event.data] } });
    //     }
    //   };
    //   mediaRecorder.start(1000); // Send audio chunks every second
    // });

    // Remember to close the session when done
    // session.close();

  } catch (error) {
    console.error('Failed to connect live session:', error);
  }
}

startLiveSession();

تعد الوحدة ai.live قوية للغاية لبناء تطبيقات تبدو تفاعلية ومتجاوبة حقًا، وتتفاعل في الوقت الفعلي مع مدخلات المستخدم عبر وسائط مختلفة.

نماذج وقدرات تحويل النص إلى كلام (TTS)

تسهل الحزمة توليد تحويل النص إلى كلام (TTS)، بشكل أساسي من خلال واجهة ai.live عند طلب إخراج صوتي. يتيح ذلك لنماذج Gemini الاستجابة ليس فقط بالنص، بل أيضًا بالصوت المنطوق.

تكوين TTS (SpeechConfig وVoiceConfig):

عند إنشاء اتصال مباشر باستخدام ai.live.connect()، يمكنك تحديد speechConfig ضمن معلمة config.

مثال: طلب إخراج صوتي في جلسة مباشرة:

// Within ai.live.connect parameters:
// ...
config: {
  responseModalities: [Modality.AUDIO], // Crucial for TTS
  speechConfig: {
    voiceConfig: {
      // Replace with an actual available prebuilt voice name
      prebuiltVoice: 'aura-asteria-en',
    }
  }
},
callbacks: {
  onmessage: (serverMessage) => {
    if (serverMessage.speechUpdate?.audio) {
      const audioData = serverMessage.speechUpdate.audio; // This is ArrayBuffer
      // Logic to play this audio data in the browser or save it in Node.js
      // For example, in a browser:
      // const audioBlob = new Blob([audioData], { type: 'audio/mpeg' }); // Or appropriate MIME type
      // const audioUrl = URL.createObjectURL(audioBlob);
      // new Audio(audioUrl).play();
      console.log('Received audio data for TTS.');
    }
    if (serverMessage.textUpdate?.text) {
        console.log("Accompanying text (if any):", serverMessage.textUpdate.text)
    }
  },
  // ... other callbacks
},
// ...

عند التكوين لإخراج الصوت، سيستقبل رد الاتصال onmessage في جلستك المباشرة كائنات ServerMessage. إذا كانت الرسالة تحتوي على كلام، فإن حقل speechUpdate.audio سيحتوي على بيانات الصوت (عادةً كـ ArrayBuffer). يمكنك بعد ذلك معالجة هذه البيانات لتشغيلها للمستخدم أو حفظها كملف صوتي. قد يتم أيضًا ملء حقل textUpdate.text بالنسخة النصية للكلام.

هذا التكامل لـ TTS مباشرة في التدفق المباشر والتفاعلي يجعل الحزمة مثالية لتطبيقات الصوت أولاً، والمساعدين التفاعليين، وميزات إمكانية الوصول.

نماذج توليد الصور

توفر الحزمة طريقة مخصصة لتوليد الصور باستخدام نماذج مثل Imagen: ai.models.generateImages(). تتيح لك هذه الطريقة تقديم طلب نصي واستقبال بيانات الصورة التي تم إنشاؤها.

استخدام ai.models.generateImages():

تأخذ هذه الطريقة GenerateImagesParameters، والتي تتضمن:

مثال: توليد صورة:

import { GoogleGenAI } from '@google/genai';
// ... (Initialization for Vertex AI, as Imagen is often a Vertex AI service)
const ai = new GoogleGenAI({ vertexai: true, project: 'your-gcp-project-id', location: 'your-gcp-location' });


async function createImage() {
  try {
    const response = await ai.models.generateImages({
      model: 'imagen-3.0-generate-002', // Check documentation for latest model
      prompt: 'A futuristic cityscape at sunset, with flying vehicles and neon lights.',
      config: {
        numberOfImages: 1,
        aspectRatio: '16:9',
        includeRaiReason: true,
      },
    });

    if (response?.generatedImages && response.generatedImages.length > 0) {
      const imageBytesBase64 = response.generatedImages[0]?.image?.imageBytes;
      if (imageBytesBase64) {
        // imageBytesBase64 is a Base64 encoded string of the image
        console.log('Image generated (Base64 encoded)!');
        // You can then display this image in a browser (e.g., <img src="data:image/png;base64,..." />)
        // or save it to a file in Node.js
      }
    } else {
      console.log('No image generated or RAI filtered:', response?.raiFilteredReason);
    }
  } catch (error) {
    console.error('Error generating image:', error);
  }
}

createImage();

ستحتوي الاستجابة (GenerateImagesResponse) على مصفوفة من كائنات GeneratedImage. يمكن أن يحتوي كل كائن على بيانات الصورة (غالبًا كـ imageBytes بتنسيق Base64)، وraiFilteredReason إذا تم تصفيتها، وبيانات وصفية أخرى.

معالجة الفيديو (كإدخال)

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

تحميل ملفات الفيديو (ai.files.upload() - Gemini API):
يمكنك تحميل ملفات الفيديو (مثل MP4) باستخدام الوحدة الفرعية ai.files. بمجرد تحميلها، تتلقى URI للملف يمكن الإشارة إليه في جزء fileData من كائن Content الخاص بك.

// Conceptual example for file upload (Gemini API)
// const uploadedFile = await ai.files.upload({
//   file: pathToYourVideoFile, // Or a Blob in the browser
//   mimeType: 'video/mp4',
//   displayName: 'my-cool-video.mp4'
// });
// const videoFileUri = uploadedFile.uri;

const contents = [{
  role: "user",
  parts: [
    { text: "Summarize this video." },
    { fileData: { mimeType: "video/mp4", fileUri: "YOUR_UPLOADED_VIDEO_URI_HERE" } },
    // Optionally, add VideoMetadata
    // { videoMetadata: { startOffset: "0s", endOffset: "30s" } } // Process first 30s
  ]
}];

استخدام URIs تخزين Google Cloud (Vertex AI):
عند استخدام Vertex AI، يمكنك الإشارة مباشرة إلى ملفات الفيديو المخزنة في مجموعات تخزين Google Cloud باستخدام URI gs:// الخاص بها في جزء fileData.

إطارات الفيديو المباشرة (ai.live):
كما تمت مناقشته في قسم ai.live، يمكنك إرسال إطارات فيديو فردية (ككائنات Blob، على الأرجح بأنواع MIME للصور مثل image/jpeg أو image/png) باستخدام session.sendRealtimeInput(). يتيح ذلك التحليل أو التفاعل في الوقت الفعلي بناءً على بث فيديو مباشر.

تسمح واجهة VideoMetadata، مع startOffset وendOffset، بتحديد الجزء الذي يجب أن يركز عليه النموذج من ملف الفيديو، وهو مفيد لمعالجة مقاطع الفيديو الطويلة.

دعم Gemini API مقابل Vertex AI: نهج مزدوج

ميزة هامة لـ Google Gen AI SDK هي دعمها السلس لكل من Gemini Developer API (عبر Google AI Studio) وVertex AI. يوفر هذا الدعم المزدوج للمطورين المرونة ومسار ترقية واضح.

تجرّد الحزمة العديد من الاختلافات. تعمل الطرق الأساسية مثل ai.models.generateContent() بشكل مشابه لكليهما، مع التمييز الرئيسي هو التهيئة (apiKey مقابل vertexai: true, project, location). يتيح لك ذلك البدء بـ Gemini API والترحيل إلى Vertex AI مع نضج وتوسع تطبيقك، دون إعادة كتابة كاملة لمنطق الذكاء الاصطناعي الخاص بك. غالبًا ما تحدد وثائق الطرق ما إذا كانت ميزة أو معلمة فريدة لمنصة واحدة.

الخلاصة: أدواتك لتطبيقات الذكاء الاصطناعي من الجيل التالي

Google Gen AI TypeScript/JavaScript SDK هي مجموعة أدوات قوية ومتعددة الاستخدامات تجلب قدرات Gemini 2.5 والنماذج المتقدمة الأخرى مباشرة إلى مطوري JavaScript. دعمها للمحتوى متعدد الوسائط، التفاعلات في الوقت الفعلي عبر Live API، TTS المدمج، توليد الصور، والمرونة في الاختيار بين Gemini Developer API وVertex AI يجعلها موردًا لا غنى عنه.

من خلال فهم هيكل الحزمة، ووحداتها الأساسية (ai.models، ai.live، ai.chats، ai.files، ai.caches)، والفروق الدقيقة في صياغة الطلبات متعددة الوسائط، أنت مجهز جيدًا لبناء تطبيقات مبتكرة يمكنها الرؤية، السمع، التحدث، وفهم العالم بطرق أغنى من أي وقت مضى. مع استمرار جوجل في دفع حدود الذكاء الاصطناعي، ستكون هذه الحزمة مفتاحك لفتح تلك الإمكانيات داخل مشاريع JavaScript وTypeScript الخاصة بك. انغمس، جرب، وابنِ مستقبل التطبيقات المدعومة بالذكاء الاصطناعي اليوم!

لقد قمت بتوليد المقال بناءً على المعلومات المجمعة من README.md ودليل docs. يغطي جميع المواضيع المحددة ويهدف إلى عدد الكلمات المطلوب.

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

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

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