Eğitim: Gemini API'yi kullanmaya başlama


Bu eğitimde, Google AI JavaScript SDK'yı kullanarak Gemini API'ye doğrudan web uygulamanızdan nasıl erişeceğiniz gösterilmektedir. Web uygulamanızdaki Gemini modellerine erişmek için doğrudan REST API'lerle veya sunucu tarafı kodları (ör. Node.js) ile çalışmak istemiyorsanız bu SDK'yı kullanabilirsiniz.

Bu eğitimde aşağıdakileri nasıl yapacağınızı öğreneceksiniz:

Ayrıca bu eğitim, gelişmiş kullanım alanları (ör. sayım jetonları) ve içerik oluşturmayı kontrol etme seçenekleri hakkında bölümler içerir.

Ön koşullar

Bu eğitimde, web uygulamaları geliştirmek için JavaScript kullanma konusunda bilgi sahibi olduğunuz varsayılır. Bu kılavuz çerçeveden bağımsızdır.

Bu eğiticiyi tamamlamak için geliştirme ortamınızın aşağıdaki gereksinimleri karşıladığından emin olun:

  • (İsteğe bağlı) Node.js
  • Modern web tarayıcısı

Projenizi oluşturun

Gemini API'yi çağırmadan önce projenizi ayarlamanız gerekir. Bu işlemler arasında API anahtarı edinme, SDK'yı içe aktarma ve modeli başlatma adımları yer alır.

API anahtarınızı oluşturma

Gemini API'yi kullanmak için API anahtarına ihtiyacınız vardır. Henüz yoksa Google AI Studio'da bir anahtar oluşturun.

API anahtarı alma

API anahtarınızın güvenliğini sağlayın

Sürüm kontrol sisteminizde bir API anahtarını kontrol etmemeniz kesinlikle önerilir. Bunun yerine, modeli başlatmadan hemen önce API anahtarınızı uygulamanıza iletmeniz gerekir.

Bu eğitimdeki tüm snippet'ler, API anahtarınıza global sabit değer olarak eriştiğinizi varsayar.

SDK'yı içe aktarma ve üretken modeli başlatma

API çağrısı yapabilmek için SDK'yı içe aktarmanız ve üretken modeli ilk kullanıma hazırlamanız gerekir.

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

Bir model belirtirken aşağıdakilere dikkat edin:

  • Kullanım alanınıza özel bir model kullanın (örneğin, gemini-1.5-flash çok modlu giriş içindir). Bu kılavuzda, her uygulamaya ait talimatlarda her kullanım alanı için önerilen modeller listelenmiştir.

Yaygın kullanım alanlarını hayata geçirin

Artık projeniz hazır olduğuna göre Gemini API'yi kullanarak farklı kullanım alanları uygulayabilirsiniz:

Yalnızca metin girişinden metin oluştur

İstem girişi yalnızca metin içeriyorsa metin çıkışı oluşturmak için Gemini 1.5 modelini veya generateContent özelliğine sahip Gemini 1.0 Pro modelini kullanın:

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

Metin ve resim girişlerinden metin oluşturma (çok modlu)

Gemini, hem metin hem de resim girebilmeniz için çok modlu girişleri (Gemini 1.5 modelleri) işleyebilen çeşitli modeller sunar. İstemler için resim şartlarını incelemeyi unutmayın.

İstem girişi hem metin hem de resim içerdiğinde metin çıkışı oluşturmak için generateContent yöntemiyle Gemini 1.5 modelini kullanın:

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

Çok dönüşlü görüşmeler (sohbet) oluşturun

Gemini'ı kullanarak birden fazla turne arasında serbest biçimli sohbetler gerçekleştirebilirsiniz. SDK, görüşmenin durumunu yöneterek süreci basitleştirir. Bu sayede, generateContent uygulamasının aksine, görüşme geçmişini sizin saklamanız gerekmez.

Çok dönüşlü bir sohbet (ör. sohbet) başlatmak için Gemini 1.5 veya Gemini 1.0 Pro modelini kullanın. Ardından, startChat() numaralı telefonu arayarak sohbeti başlatın. Ardından, yeni kullanıcı mesajı göndermek için sendMessage() öğesini kullanın. Bu mesaj, mesajı ve yanıtı da sohbet geçmişine ekler.

Bir görüşmedeki içerikle ilişkili role için iki olası seçenek vardır:

  • user: İstemleri sağlayan roldür. Bu değer, sendMessage çağrıları için varsayılandır ve farklı bir rol geçilirse işlev bir istisna atar.

  • model: yanıtları sağlayan rol. Bu rol, mevcut history ile startChat() çağrısı yapılırken kullanılabilir.

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

Daha hızlı etkileşimler için akışı kullanın

Varsayılan olarak model, oluşturma sürecinin tamamını tamamladıktan sonra yanıt döndürür. Sonucun tamamını beklemeden, bunun yerine kısmi sonuçları işlemek için akışı kullanarak daha hızlı etkileşimler gerçekleştirebilirsiniz.

Aşağıdaki örnekte, metin ve resim giriş isteminden metin oluşturmak için generateContentStream yöntemiyle akışın nasıl uygulanacağı gösterilmektedir.

// ...

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

// ...

Yalnızca metin girişi ve sohbet kullanım alanları için de benzer bir yaklaşım kullanabilirsiniz.

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

chat örneğinin nasıl hazırlanacağını öğrenmek için yukarıdaki sohbet örneğine bakın.

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

Gelişmiş kullanım alanları uygulayın

Bu eğiticinin önceki bölümünde açıklanan yaygın kullanım alanları, Gemini API'yi rahatça kullanmanıza yardımcı olur. Bu bölümde, daha gelişmiş olarak değerlendirilebilecek bazı kullanım alanları açıklanmaktadır.

İşlev çağırma

İşlev çağrısı, üretken modellerden yapılandırılmış veri çıkışları almanızı kolaylaştırır. Daha sonra bu çıkışları kullanarak diğer API'leri çağırabilir ve ilgili yanıt verilerini modele döndürebilirsiniz. Başka bir deyişle, işlev çağrısı, üretken modelleri harici sistemlere bağlamanıza yardımcı olur. Böylece, oluşturulan içerik en güncel ve doğru bilgileri içerir. İşlev çağrısı eğiticisinden daha fazla bilgi edinebilirsiniz.

Jetonları say

Uzun istemler kullanırken, modele herhangi bir içerik göndermeden önce jetonları saymak faydalı olabilir. Aşağıdaki örnekler, çeşitli kullanım alanları için countTokens() hizmetinin nasıl kullanılacağını gösterir:

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

İçerik oluşturmayı kontrol etme seçenekleri

Model parametrelerini yapılandırarak ve güvenlik ayarlarını kullanarak içerik oluşturmayı kontrol edebilirsiniz.

Model parametrelerini yapılandırma

Modele gönderdiğiniz her istem, modelin yanıt oluşturma şeklini kontrol eden parametre değerleri içerir. Model, farklı parametre değerleri için farklı sonuçlar oluşturabilir. Model parametreleri hakkında daha fazla bilgi edinin. Yapılandırma, model örneğinizin kullanım ömrü boyunca korunur.

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

Güvenlik ayarlarını kullan

Zararlı olarak değerlendirilebilecek yanıtlar alma olasılığını ayarlamak için güvenlik ayarlarını kullanabilirsiniz. Varsayılan olarak güvenlik ayarları, güvenli olmayan içerik olma olasılığı orta ve yüksek olasılıklı içerikleri tüm boyutlarda engeller. Güvenlik ayarları hakkında daha fazla bilgi edinin.

Aşağıda, bir güvenlik ayarını nasıl yapacağınız açıklanmaktadır:

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

Ayrıca, birden fazla güvenlik ayarı da belirleyebilirsiniz:

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

Sırada ne var?

  • İstem tasarımı, dil modellerinden istenen yanıtı üreten istem oluşturma sürecidir. İyi yapılandırılmış istemler yazmak, bir dil modelinden doğru ve yüksek kaliteli yanıtlar almanın önemli bir parçasıdır. İstem yazmayla ilgili en iyi uygulamalar hakkında bilgi edinin.

  • Gemini; giriş türleri ve karmaşıklığı, sohbet veya diğer iletişim dili görevlerine yönelik uygulamalar ve boyut kısıtlamaları gibi farklı kullanım alanlarının ihtiyaçlarını karşılamak için çeşitli model varyasyonları sunar. Mevcut Gemini modelleri hakkında bilgi edinin.