Node.js uygulamalarında Gemini API'yi kullanmaya başlama

Bu eğiticide, Google AI JavaScript SDK'yı kullanarak Node.js uygulamanız için Gemini API'ye nasıl erişileceği gösterilmektedir.

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

Ayrıca bu eğitimde, gelişmiş kullanım alanları (ör. yerleştirmeler ve sayma jetonları) ve içerik oluşturma sürecini kontrol etme seçenekleri hakkında bölümler yer alır.

Ön koşullar

Bu eğitim, Node.js ile uygulama derleme hakkında bilgi sahibi olduğunuzu varsayar.

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

  • Node.js v18 ve sonraki sürümleri
  • npm

Projenizi oluşturun

Gemini API'yi çağırmadan önce projenizi ayarlamanız gerekir. Bu adımlar API anahtarınızı oluşturma, SDK paketini yükleme ve modeli başlatma işlemlerini içerir.

API anahtarınızı oluşturma

Gemini API'yi kullanmak için API anahtarı gerekir. Anahtarınız yoksa Google AI Studio'da bir anahtar oluşturun.

API anahtarı alma

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

Sürüm kontrol sisteminizde bir API anahtarını kontrol etmemeniz kesinlikle önerilir. Bunun yerine, API anahtarınız için gizli anahtar deposu kullanmanız gerekir.

Bu eğitimdeki tüm snippet'lerde, API anahtarınıza ortam değişkeni olarak eriştiğiniz varsayılır.

SDK paketini yükleyin

Gemini API'yi kendi uygulamanızda kullanmak için Node.js için GoogleGenerativeAI paketini yüklemeniz gerekir:

npm install @google/generative-ai

Üretken Modeli Başlatma

Herhangi bir API çağrısı yapabilmeniz için öncelikle Üretken Model'i içe aktarıp başlatmanız gerekir.

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

// ...

const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

// ...

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

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

Yaygın kullanım alanlarından yararlanın

Projeniz hazır olduğuna göre farklı kullanım alanları uygulamak için Gemini API'yi nasıl kullanabileceğinizi keşfedebilirsiniz:

Gelişmiş kullanım alanları bölümünde, Gemini API ve yerleştirmeler hakkında bilgi edinebilirsiniz.

Yalnızca metin girişinden metin oluştur

İstem girişi yalnızca metin içeriyorsa metin çıkışı oluşturmak için generateContent yöntemiyle gemini-pro modelini kullanın:

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 text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  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şinden metin oluşturma (çok modlu)

Gemini çok modlu bir model (gemini-pro-vision) sunar. Böylece hem metin hem de resim girebilirsiniz. İstemler için resim gereksinimlerini incelediğinizden emin olun.

İstem girişi hem metin hem de resimleri içerdiğinde metin çıkışı oluşturmak için generateContent yöntemiyle gemini-pro-vision modelini kullanın:

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() {
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  const model = genAI.getGenerativeModel({ model: "gemini-pro-vision" });

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

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

Gemini'ı kullanarak birden fazla dönüş için serbest biçimli konuşmalar oluşturabilirsiniz. SDK, görüşmenin durumunu yöneterek süreci basitleştirir. Böylece, generateContent'den farklı olarak sohbet geçmişini sizin saklamanız gerekmez.

Çok dönüşlü bir görüşme (ör. sohbet) oluşturmak için gemini-pro modelini kullanın ve startChat() yöntemini çağırarak sohbeti başlatın. Ardından, yeni bir kullanıcı mesajı göndermek için sendMessage() kullanın. Bu işlem, 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 rol. Bu değer, sendMessage çağrıları için varsayılan değerdir.

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

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 text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  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ış özelliğini kullanın

Varsayılan olarak model, tüm oluşturma işlemini tamamladıktan sonra bir yanıt döndürür. Tüm sonucu beklemeyip 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 benzer bir yaklaşım kullanabilirsiniz.

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

chat örneğini nasıl göstereceğinizi öğrenmek için yukarıdaki sohbet örneğini inceleyin.

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

Gelişmiş kullanım alanları

Bu eğiticinin önceki bölümünde açıklanan yaygın kullanım alanları, Gemini API'yi kullanmaya alışmanıza yardımcı olur. Bu bölümde, daha ileri düzey olarak değerlendirilebilecek bazı kullanım alanları açıklanmaktadır.

Yerleştirmeleri kullanma

Yerleştirme, bilgiyi bir dizideki kayan nokta sayıları listesi olarak göstermek için kullanılan bir tekniktir. Gemini ile metinleri (kelimeler, cümleler ve metin blokları) vektörleştirilmiş biçimde temsil edebilirsiniz. Böylece, yerleştirilmiş öğeleri daha kolay karşılaştırıp karşılaştırabilirsiniz. Örneğin, benzer bir konuyu veya duyguyu paylaşan iki metin, kosinüs benzerliği gibi matematiksel karşılaştırma teknikleriyle tanımlanabilecek benzer yerleştirmelere sahip olmalıdır.

Yerleştirme oluşturmak için embedding-001 modelini embedContent yöntemiyle (veya batchEmbedContent yöntemiyle) kullanın. Aşağıdaki örnek, tek bir dize için yerleştirme oluşturur:

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

Jetonları say

Uzun istemler kullanırken, modele içerik göndermeden önce jetonların sayılması yararlı olabilir. Aşağıdaki örneklerde countTokens() öğesinin çeşitli kullanım alanlarında nasıl kullanılacağı gösterilmektedir:

// 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ı denetleme seçenekleri

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

Bir model isteği yöntemine (generateContent gibi) generationConfig veya safetySettings geçirilmesinin, getGenerativeModel öğesinde geçirilen adla yapılandırma nesnesini tamamen geçersiz kılacağını unutmayın.

Model parametrelerini yapılandırma

Modele gönderdiğiniz her istem, modelin nasıl yanıt oluşturacağını 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.

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME",  generationConfig });

Güvenlik ayarlarını kullan

Zararlı olarak değerlendirilebilecek yanıtlar alma olasılığını ayarlamak için güvenlik ayarlarını kullanabilirsiniz. Güvenlik ayarları, varsayılan olarak güvenli olmayan içerik olması orta ve/veya yüksek olasılıklı tüm 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 belirleyeceğiniz açıklanmıştır:

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

// ...

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME", safetySettings });

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ı alan istemler oluşturma sürecidir. İyi yapılandırılmış istemler yazmak, bir dil modelinden doğru, 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ık, 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ı sunuyor. Kullanılabilir Gemini modelleri hakkında bilgi edinin.

  • Gemini, hız sınırının artırılmasını isteme seçeneği sunar. Gemini Pro modelleri için hız sınırı dakikada 60 istektir (BGBG).