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


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

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

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

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

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

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

  • (اختياري) Node.js
  • متصفح ويب حديث

إعداد مشروعك

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

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

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

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

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

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

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

استيراد حزمة تطوير البرامج (SDK) وإعداد النموذج التوليدي

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

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";
      // Reminder: This should only be for local testing

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

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

      // ...
    </script>
  </body>
</html>

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

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

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

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

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

عندما يتضمّن الإدخال المخصّص نصًا فقط، يُرجى استخدام نموذج Gemini 1.5 أو نموذج Gemini 1.0 Pro مع "generateContent" لإنشاء إخراج النص:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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 نماذج مختلفة يمكنها التعامل مع الإدخالات المتعدّدة الوسائط (نموذج Gemini 1.5) لتتمكن من إدخال النصَين والصور. تأكد من مراجعة متطلبات الصور في الطلبات:

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

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

// Converts a File object to a GoogleGenerativeAI.Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

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 fileInputEl = document.querySelector("input[type=file]");
  const imageParts = await Promise.all(
    [...fileInputEl.files].map(fileToGenerativePart)
  );

  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 الحالي.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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 يصف هذا القسم بعض حالات الاستخدام التي يمكن اعتبارها أكثر تقدمًا.

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

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

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

عند استخدام الطلبات الطويلة، قد يكون من المفيد حساب الرموز المميزة قبل إرسال أي المحتوى إلى النموذج. توضِّح الأمثلة التالية كيفية استخدام "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 });

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

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

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

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

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 المتاحة