تتوفّر الآن نافذة Gemini 1.5 Pro 2M للسياق وإمكانيات تنفيذ الرموز وGemma 2. مزيد من المعلومات

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

برنامج تعليمي: بدء استخدام Gemini API

يشرح هذا الدليل التوجيهي كيفية الوصول إلى Gemini API في Node.js. تطبيقًا باستخدام حزمة تطوير البرامج (SDK) لتكنولوجيات الذكاء الاصطناعي من Google

في هذا البرنامج التعليمي، ستتعرف على كيفية إجراء ما يلي:

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

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

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

يفترض هذا البرنامج التعليمي أنك على دراية بإنشاء تطبيقات باستخدام Node.js.

لإكمال هذا البرنامج التعليمي، تأكد من أن بيئة التطوير لديك تفي المتطلبات التالية:

الإصدار 18 من Node.js والإصدارات الأحدث
npm

إعداد مشروعك

قبل طلب Gemini API، عليك إعداد مشروعك، بما في ذلك: إعداد مفتاح واجهة برمجة التطبيقات، وتثبيت حزمة SDK، وتهيئة النموذج.

إعداد مفتاح واجهة برمجة التطبيقات

لاستخدام Gemini API، يجب توفُّر مفتاح واجهة برمجة تطبيقات. إذا لم يكن لديك واحد بالفعل، إنشاء مفتاح في Google AI Studio

الحصول على مفتاح واجهة برمجة التطبيقات

تأمين مفتاح واجهة برمجة التطبيقات

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

تفترض كل المقتطفات في هذا البرنامج التعليمي أنك تدخل إلى مفتاح واجهة برمجة التطبيقات أحد متغيرات البيئة.

تثبيت حزمة SDK

لاستخدام Gemini API في تطبيقك، يجب تثبيت حزمة GoogleGenerativeAI لـ Node.js:

npm install @google/generative-ai

إعداد النموذج التوليدي

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// ...

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

// ...

عند تحديد نموذج، يُرجى مراعاة ما يلي:

استخدِم نموذجًا مخصَّصًا لحالة الاستخدام (مثل gemini-1.5-flash). مخصص للإدخال متعدد الوسائط). في هذا الدليل، ستشمل التعليمات الخاصة بكل قائمة التنفيذ النموذج الموصى به لكل حالة استخدام.

ملاحظة: للحصول على معلومات تفصيلية عن النماذج المتاحة، بما في ذلك إمكاناته وحدود معدّل الزحف، يُرجى الاطّلاع على نماذج Gemini. نقدّم خيارات طلب زيادة الحدّ الأقصى لمعدّل الاستخدام إذا القيمة التلقائية غير كافية.

تنفيذ حالات الاستخدام الشائعة

بعد الانتهاء من إعداد مشروعك، يمكنك الآن استخدام Gemini API من أجل تنفيذ حالات استخدام مختلفة:

إنشاء نص من إدخال نص فقط
إنشاء نص من إدخال النص والصورة (متعدد الوسائط)
إنشاء محادثات متعددة الأدوار (محادثة)
استخدام البث المباشر للتفاعلات بشكل أسرع

يوفّر لك قسم "حالات الاستخدام المتقدّمة" معلومات حول Gemini API. والتضمين.

إنشاء نص من إدخال نص فقط

إذا كان نص الطلب يتضمّن نصًا فقط، استخدِم نموذج Gemini 1.5 مع generateContent لإنشاء ناتج نصي:

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

إنشاء نص من إدخال النص والصورة (متعدد الوسائط)

بإمكان Gemini 1.5 Flash و1.5 Pro معالجة عمليات الإدخال المتعدّدة الوسائط لتتمكّن من إدخال النصَين والصور. تأكد من مراجعة متطلبات الصور في الطلبات:

عندما يتضمّن إدخال الطلب نصًا وصورًا، استخدِم نموذج Gemini 1.5 مع الأسلوب generateContent لإنشاء إخراج نصي:

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Converts local file information to a GoogleGenerativeAI.Part object.
function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType
    },
  };
}

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

  const prompt = "What's different between these pictures?";

  const imageParts = [
    fileToGenerativePart("image1.png", "image/png"),
    fileToGenerativePart("image2.jpeg", "image/jpeg"),
  ];

  const result = await model.generateContent([prompt, ...imageParts]);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

إنشاء محادثات متعددة الأدوار (الدردشة)

باستخدام Gemini، يمكنك إجراء محادثات حرة بين مختلف الأدوار. تشير رسالة الأشكال البيانية تعمل SDK على تبسيط العملية من خلال إدارة حالة المحادثة، بحيث لا مع generateContent، لن تحتاج إلى تخزين سجلّ المحادثات نفسك.

لبدء محادثة متعددة الأدوار (مثل المحادثة)، استخدِم نموذج Gemini 1.5 أو نموذج Gemini 1.0 Pro، وبدء المحادثة من خلال الاتصال بالرقم startChat(). بعد ذلك، استخدِم sendMessage() لإرسال رسالة جديدة للمستخدم، والتي ستؤدي أيضًا إلى إلحاق الرسالة والرد على سجل الدردشة.

ثمة خياران محتملان لحساب role المرتبط بالمحتوى في المحادثة:

user: الدور الذي يقدّم الطلبات هذه القيمة هي القيمة الافتراضية sendMessage مكالمة
model: الدور الذي يقدّم الردود يمكن استخدام هذا الدور عندما جارٍ الاتصال بـ startChat() باستخدام history الحالي.

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const chat = model.startChat({
    history: [
      {
        role: "user",
        parts: [{ text: "Hello, I have 2 dogs in my house." }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
    generationConfig: {
      maxOutputTokens: 100,
    },
  });

  const msg = "How many paws are in my house?";

  const result = await chat.sendMessage(msg);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

استخدام البث المباشر للتفاعلات بشكل أسرع

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

يوضّح المثال التالي كيفية تنفيذ البث باستخدام طريقة generateContentStream لإنشاء نص من إدخال نص وصورة مطالبة.

//...

const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

//...

يمكنك استخدام أسلوب مماثل لحالات استخدام إدخال النص فقط والدردشة.

// Use streaming with text-only input
const result = await model.generateContentStream(prompt);

راجِع مثال المحادثة أعلاه للتعرّف على كيفية إنشاء مثيل. chat.

// Use streaming with multi-turn conversations (like chat)
const result = await chat.sendMessageStream(msg);

تنفيذ حالات الاستخدام المتقدّمة

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

استخدام التضمينات

التضمين هو أسلوب يُستخدَم لتمثيل المعلومات. كقائمة بأرقام النقاط العائمة في مصفوفة. باستخدام Gemini، يمكنك تمثيل نص (كلمات وجمل وكتل نصية) في شكل متجه، مما تسهيل المقارنة والتباين بين التضمينات. على سبيل المثال، هناك نصان يتشاركان موضوع أو آراء متشابهة يجب أن تحتوي على تضمينات متشابهة، والتي يمكن أن تم تحديدها من خلال تقنيات المقارنة الرياضية مثل تشابه جيب التمام.

استخدِم النموذج embedding-001 مع طريقة embedContent (أو batchEmbedContent) لإنشاء تضمينات. المثال التالي يؤدي إلى إنشاء تضمين لسلسلة واحدة:

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // For embeddings, use the embedding-001 model
  const model = genAI.getGenerativeModel({ model: "embedding-001"});

  const text = "The quick brown fox jumps over the lazy dog."

  const result = await model.embedContent(text);
  const embedding = result.embedding;
  console.log(embedding.values);
}

run();

استدعاء الدالة

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

عدد الرموز المميّزة

عند استخدام الطلبات الطويلة، قد يكون من المفيد حساب الرموز المميزة قبل إرسال أي المحتوى إلى النموذج. توضِّح الأمثلة التالية كيفية استخدام "countTokens()". لحالات الاستخدام المختلفة:

// For text-only input
const { totalTokens } = await model.countTokens(prompt);

// For text-and-image input (multimodal)
const { totalTokens } = await model.countTokens([prompt, ...imageParts]);

// For multi-turn conversations (like chat)
const history = await chat.getHistory();
const msgContent = { role: "user", parts: [{ text: msg }] };
const contents = [...history, msgContent];
const { totalTokens } = await model.countTokens({ contents });

خيارات التحكّم في إنشاء المحتوى

يمكنك التحكّم في عملية إنشاء المحتوى من خلال ضبط مَعلمات النماذج واستخدام إعدادات الأمان.

يُرجى العِلم أنّه يتم تمرير generationConfig أو safetySettings إلى طلب النموذج. (مثل generateContent) ستلغي كائن الإعدادات بالكامل بالاسم نفسه الذي تم تمريره في getGenerativeModel.

ضبط مَعلمات النموذج

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

const generationConfig = {
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
};

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash",  generationConfig });

استخدام إعدادات الأمان

يمكنك استخدام إعدادات الأمان لضبط احتمالية تلقّي ردود ضارًا. تحظر إعدادات الأمان المحتوى باستخدام الوسيط و/أو احتمالية عالية لكونه محتوى غير آمن بجميع السمات. التعلّم مزيد من المعلومات حول إعدادات الأمان

إليك كيفية ضبط إعداد أمان واحد:

import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";

// ...

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
];

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", safetySettings });

يمكنك أيضًا ضبط أكثر من إعداد أمان واحد:

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

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

تصميم الطلب هو عملية إنشاء الطلبات التي ستنتج عن المطلوب استجابة من النماذج اللغوية. كتابة طلبات منظمة بشكل جيد أمر أساسي لضمان تقديم ردود دقيقة وعالية الجودة باستخدام نموذج لغوي. مزيد من المعلومات حول أفضل الممارسات لكتابة الطلب
يقدّم Gemini صيغًا متعدّدة للنماذج لتلبية احتياجات الاستخدام المختلفة. مثل أنواع الإدخال ودرجة التعقيد أو عمليات التنفيذ المتعلقة بالدردشة أو غير ذلك ومهام لغة مربع الحوار وقيود الحجم. مزيد من المعلومات حول طُرز Gemini المتاحة