Tutorial: Mulai menggunakan Gemini API


Tutorial ini menunjukkan cara mengakses Gemini API langsung dari aplikasi web Anda menggunakan Google AI JavaScript SDK. Anda dapat menggunakan SDK ini jika tidak ingin bekerja langsung dengan REST API atau kode sisi server (seperti Node.js) untuk mengakses model Gemini di aplikasi web.

Dalam tutorial ini, Anda akan mempelajari cara melakukan hal berikut:

Selain itu, tutorial ini berisi bagian tentang kasus penggunaan lanjutan (seperti token penghitungan) serta opsi untuk mengontrol pembuatan konten.

Prasyarat

Tutorial ini mengasumsikan bahwa Anda sudah memahami penggunaan JavaScript untuk mengembangkan aplikasi web. Panduan ini tidak bergantung pada framework.

Untuk menyelesaikan tutorial ini, pastikan lingkungan pengembangan Anda memenuhi persyaratan berikut:

  • (Opsional) Node.js
  • Browser web modern

Menyiapkan project

Sebelum memanggil Gemini API, Anda perlu menyiapkan project yang mencakup memperoleh kunci API, mengimpor SDK, dan menginisialisasi model.

Menyiapkan kunci API

Untuk menggunakan Gemini API, Anda memerlukan kunci API. Jika Anda belum memilikinya, buat kunci di Google AI Studio.

Mendapatkan kunci API

Mengamankan kunci API Anda

Sebaiknya Anda tidak melakukan check in kunci API ke dalam sistem kontrol versi Anda. Sebagai gantinya, Anda harus meneruskan kunci API ke aplikasi tepat sebelum menginisialisasi model tersebut.

Semua cuplikan dalam tutorial ini mengasumsikan bahwa Anda mengakses kunci API sebagai konstanta global.

Mengimpor SDK dan melakukan inisialisasi model generatif

Sebelum dapat melakukan panggilan API, Anda perlu mengimpor SDK dan menginisialisasi model generatif.

<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>

Saat menetapkan model, perhatikan hal-hal berikut:

  • Gunakan model yang spesifik untuk kasus penggunaan Anda (misalnya, gemini-1.5-flash untuk input multimodal). Dalam panduan ini, petunjuk untuk setiap penerapan mencantumkan model yang direkomendasikan untuk setiap kasus penggunaan.

Menerapkan kasus penggunaan umum

Setelah project siap, Anda dapat menjelajah menggunakan Gemini API untuk menerapkan berbagai kasus penggunaan:

Membuat teks dari input khusus teks

Jika input perintah hanya menyertakan teks, gunakan model Gemini 1.5 atau model Gemini 1.0 Pro dengan generateContent untuk menghasilkan output teks:

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();

Membuat teks dari input teks dan gambar (multimodal)

Gemini menyediakan berbagai model yang dapat menangani input multimodal (model Gemini 1.5 dan Gemini 1.0 Pro Vision) sehingga Anda dapat memasukkan teks dan gambar. Pastikan Anda meninjau persyaratan gambar untuk perintah.

Saat input perintah mencakup teks dan gambar, gunakan model Gemini 1.5 atau model Gemini 1.0 Pro Vision dengan metode generateContent untuk menghasilkan output teks:

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();

Membuat percakapan multi-giliran (chat)

Dengan Gemini, Anda dapat membuat percakapan berformat bebas di berbagai kesempatan. SDK menyederhanakan proses dengan mengelola status percakapan, sehingga tidak seperti generateContent, Anda tidak perlu menyimpan sendiri histori percakapan sendiri.

Untuk membuat percakapan multi-giliran (seperti chat), gunakan model Gemini 1.5 atau model Gemini 1.0 Pro, dan inisialisasi chat dengan memanggil startChat(). Kemudian, gunakan sendMessage() untuk mengirim pesan pengguna baru, yang juga akan menambahkan pesan dan respons ke histori chat.

Ada dua kemungkinan opsi untuk role yang dikaitkan dengan konten dalam percakapan:

  • user: peran yang menyediakan dialog. Nilai ini merupakan default untuk panggilan sendMessage, dan fungsi ini akan menampilkan pengecualian jika peran yang berbeda diteruskan.

  • model: peran yang memberikan respons. Peran ini dapat digunakan saat memanggil startChat() dengan history yang ada.

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();

Menggunakan streaming untuk interaksi yang lebih cepat

Secara default, model akan menampilkan respons setelah menyelesaikan seluruh proses pembuatan. Anda dapat mencapai interaksi yang lebih cepat dengan tidak menunggu seluruh hasil, dan sebagai gantinya menggunakan streaming untuk menangani hasil parsial.

Contoh berikut menunjukkan cara mengimplementasikan streaming dengan metode generateContentStream untuk menghasilkan teks dari permintaan input teks dan gambar.

// ...

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;
}

// ...

Anda dapat menggunakan pendekatan serupa untuk kasus penggunaan chat dan input khusus teks.

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

Lihat contoh chat di atas untuk mengetahui cara membuat instance chat.

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

Menerapkan kasus penggunaan lanjutan

Kasus penggunaan umum yang dijelaskan di bagian tutorial sebelumnya membantu Anda merasa nyaman dalam menggunakan Gemini API. Bagian ini menjelaskan beberapa kasus penggunaan yang mungkin dianggap lebih lanjut.

Panggilan fungsi

Panggilan fungsi memudahkan Anda mendapatkan output data terstruktur dari model generatif. Anda kemudian dapat menggunakan output ini untuk memanggil API lain dan menampilkan data respons yang relevan ke model. Dengan kata lain, panggilan fungsi membantu Anda menghubungkan model generatif ke sistem eksternal sehingga konten yang dihasilkan berisi informasi terbaru dan akurat. Pelajari lebih lanjut di tutorial memanggil fungsi.

Hitung token

Saat menggunakan perintah panjang, sebaiknya hitung token sebelum mengirim konten apa pun ke model. Contoh berikut menunjukkan cara menggunakan countTokens() untuk berbagai kasus penggunaan:

// 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 });

Opsi untuk mengontrol pembuatan konten

Anda dapat mengontrol pembuatan konten dengan mengonfigurasi parameter model dan dengan menggunakan setelan keamanan.

Mengonfigurasi parameter model

Setiap prompt yang Anda kirim ke model menyertakan parameter value yang mengontrol cara model menghasilkan respons. Model ini dapat memberikan hasil yang berbeda untuk parameter value yang berbeda. Pelajari Parameter model lebih lanjut. Konfigurasi dipertahankan selama masa pakai instance model Anda.

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 });

Gunakan setelan keamanan

Anda dapat menggunakan setelan keamanan untuk menyesuaikan kemungkinan mendapatkan respons yang mungkin dianggap berbahaya. Secara default, setelan keamanan memblokir konten yang memiliki kemungkinan sedang dan/atau tinggi sebagai konten yang tidak aman di semua dimensi. Pelajari Setelan keamanan lebih lanjut.

Berikut cara menetapkan satu setelan keamanan:

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 });

Anda juga dapat menetapkan lebih dari satu setelan keamanan:

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

Langkah selanjutnya

  • Desain prompt adalah proses pembuatan prompt yang mendapatkan respons yang diinginkan dari model bahasa. Menulis dialog yang terstruktur dengan baik adalah bagian penting untuk memastikan respons yang akurat dan berkualitas tinggi dari model bahasa. Pelajari praktik terbaik untuk penulisan perintah.

  • Gemini menawarkan beberapa variasi model untuk memenuhi kebutuhan berbagai kasus penggunaan, seperti jenis input dan kompleksitas, implementasi untuk chat atau tugas bahasa dialog lainnya, dan batasan ukuran. Pelajari model Gemini yang tersedia.

  • Gemini menawarkan opsi untuk meminta peningkatan batas kapasitas. Batas kapasitas untuk model Gemini Pro adalah 60 permintaan per menit (RPM).