آموزش: با Gemini API شروع کنید


این آموزش نحوه دسترسی مستقیم به Gemini API را از برنامه وب خود با استفاده از Google AI JavaScript SDK نشان می دهد. اگر نمی‌خواهید مستقیماً با REST API یا کدهای سمت سرور (مانند Node.js) برای دسترسی به مدل‌های Gemini در برنامه وب خود کار کنید، می‌توانید از این SDK استفاده کنید.

در این آموزش، نحوه انجام کارهای زیر را خواهید آموخت:

علاوه بر این، این آموزش شامل بخش هایی در مورد موارد استفاده پیشرفته (مانند شمارش توکن ها ) و همچنین گزینه هایی برای کنترل تولید محتوا است .

پیش نیازها

این آموزش فرض می کند که شما با استفاده از جاوا اسکریپت برای توسعه برنامه های وب آشنا هستید. این راهنما مستقل از چارچوب است.

برای تکمیل این آموزش، مطمئن شوید که محیط توسعه شما شرایط زیر را دارد:

  • (اختیاری) Node.js
  • مرورگر وب مدرن

پروژه خود را تنظیم کنید

قبل از فراخوانی Gemini API، باید پروژه خود را راه‌اندازی کنید که شامل دریافت کلید API، وارد کردن SDK و مقداردهی اولیه مدل می‌شود.

کلید API خود را تنظیم کنید

برای استفاده از Gemini API، به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.

یک کلید API دریافت کنید

کلید API خود را ایمن کنید

اکیداً توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید . درعوض، باید کلید API خود را درست قبل از مقداردهی اولیه مدل به برنامه خود بدهید.

تمام قطعه های این آموزش فرض می کنند که شما به کلید API خود به عنوان یک ثابت جهانی دسترسی دارید.

SDK را وارد کنید و مدل تولیدی را مقداردهی اولیه کنید

قبل از اینکه بتوانید هر گونه تماس API برقرار کنید، باید 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);

موارد استفاده پیشرفته را اجرا کنید

موارد استفاده متداول که در بخش قبلی این آموزش شرح داده شده است به شما کمک می کند تا با استفاده از API 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 برای پاسخگویی به نیازهای موارد مختلف استفاده ، مانند انواع ورودی و پیچیدگی ، پیاده سازی برای گپ یا سایر کارهای زبان گفتگو و محدودیت های اندازه ، چندین مدل مدل ارائه می دهد. در مورد مدل های جمینی موجود بیاموزید.