Làm quen với API Gemini trong ứng dụng Node.js

Hướng dẫn này minh hoạ cách truy cập vào API Gemini cho ứng dụng Node.js bằng cách sử dụng SDK JavaScript của Google AI.

Trong hướng dẫn này, bạn sẽ tìm hiểu cách thực hiện những việc sau:

Ngoài ra, bài hướng dẫn này còn có các phần về các trường hợp sử dụng nâng cao (chẳng hạn như video nhúng và mã thông báo đếm) cũng như các tuỳ chọn để kiểm soát việc tạo nội dung.

Điều kiện tiên quyết

Hướng dẫn này giả định rằng bạn đã quen với việc tạo ứng dụng bằng Node.js.

Để hoàn tất phần hướng dẫn này, hãy đảm bảo môi trường phát triển của bạn đáp ứng các yêu cầu sau:

  • Node.js phiên bản 18 trở lên
  • hải lý/phút

Thiết lập dự án

Trước khi gọi API Gemini, bạn cần thiết lập dự án, bao gồm cả việc thiết lập khoá API, cài đặt gói SDK và khởi chạy mô hình.

Thiết lập khoá API

Để sử dụng API Gemini, bạn cần có một khoá API. Nếu bạn chưa có khoá, hãy tạo khoá trong Google AI Studio.

Lấy khoá API

Bảo mật khoá API

Bạn không nên kiểm tra khoá API trong hệ thống quản lý phiên bản của mình. Thay vào đó, bạn nên sử dụng kho lưu trữ bí mật cho khoá API của mình.

Tất cả các đoạn mã trong hướng dẫn này đều giả định rằng bạn đang truy cập khoá API dưới dạng một biến môi trường.

Cài đặt gói SDK

Để sử dụng API Gemini trong ứng dụng của riêng mình, bạn cần cài đặt gói GoogleGenerativeAI cho Node.js:

npm install @google/generative-ai

Khởi chạy Mô hình tạo sinh

Trước khi có thể thực hiện bất kỳ lệnh gọi API nào, bạn cần nhập và khởi chạy Mô hình tạo sinh.

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

// ...

Khi chỉ định một mô hình, hãy lưu ý những điều sau:

  • Sử dụng mô hình dành riêng cho trường hợp sử dụng của bạn (ví dụ: gemini-pro-vision dành cho phương thức nhập đa phương thức). Trong hướng dẫn này, hướng dẫn cho mỗi cách triển khai liệt kê mô hình được đề xuất cho từng trường hợp sử dụng.

Triển khai các trường hợp sử dụng phổ biến

Bây giờ, dự án của bạn đã được thiết lập, bạn có thể khám phá cách sử dụng API Gemini để triển khai các trường hợp sử dụng khác nhau:

Trong phần trường hợp sử dụng nâng cao, bạn có thể tìm thấy thông tin về API Gemini và nội dung nhúng.

Tạo văn bản từ phương thức nhập chỉ bằng văn bản

Khi câu lệnh đầu vào chỉ bao gồm văn bản, hãy sử dụng mô hình gemini-pro với phương thức generateContent để tạo đầu ra văn bả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();

Tạo văn bản bằng phương thức nhập văn bản và hình ảnh (đa phương thức)

Gemini cung cấp một mô hình đa phương thức (gemini-pro-vision) để bạn có thể nhập cả văn bản và hình ảnh. Hãy nhớ xem lại các yêu cầu về hình ảnh đối với câu lệnh.

Khi đầu vào của lời nhắc bao gồm cả văn bản và hình ảnh, hãy sử dụng mô hình gemini-pro-vision với phương thức generateContent để tạo đầu ra văn bả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();

Xây dựng cuộc trò chuyện nhiều lượt (trò chuyện)

Khi dùng Gemini, bạn có thể tạo các cuộc trò chuyện dạng tự do qua nhiều lượt. SDK đơn giản hoá quy trình bằng cách quản lý trạng thái của cuộc trò chuyện, vì vậy, không giống như generateContent, bạn không phải tự lưu trữ nhật ký cuộc trò chuyện.

Để tạo một cuộc trò chuyện nhiều lượt (như cuộc trò chuyện), hãy sử dụng mô hình gemini-pro và khởi động cuộc trò chuyện bằng cách gọi startChat(). Sau đó, sử dụng sendMessage() để gửi tin nhắn mới cho người dùng. Thao tác này cũng sẽ thêm tin nhắn và câu trả lời vào nhật ký trò chuyện.

Có 2 tuỳ chọn cho role liên kết với nội dung trong cuộc trò chuyện:

  • user: vai trò đưa ra lời nhắc. Giá trị này là giá trị mặc định cho các lệnh gọi sendMessage.

  • model: vai trò đưa ra câu trả lời. Bạn có thể dùng vai trò này khi gọi startChat() bằng history hiện có.

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

Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Theo mặc định, mô hình sẽ trả về một phản hồi sau khi hoàn tất toàn bộ quá trình tạo. Bạn có thể đạt được tương tác nhanh hơn bằng cách không đợi toàn bộ kết quả, mà thay vào đó sử dụng phương thức truyền trực tuyến để xử lý một phần kết quả.

Ví dụ sau cho thấy cách triển khai truyền trực tuyến bằng phương thức generateContentStream để tạo văn bản từ lời nhắc nhập văn bản và hình ảnh.

//...

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

//...

Bạn có thể áp dụng phương pháp tương tự cho các trường hợp sử dụng chỉ nhập văn bản và trò chuyện.

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

Xem ví dụ về cuộc trò chuyện ở trên để biết cách tạo thực thể cho chat.

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

Triển khai các trường hợp sử dụng nâng cao

Các trường hợp sử dụng phổ biến được mô tả trong phần trước của hướng dẫn này giúp bạn làm quen với việc sử dụng API Gemini. Phần này mô tả một số trường hợp sử dụng có thể được coi là nâng cao hơn.

Sử dụng tính năng nhúng

Nhúng là kỹ thuật dùng để biểu thị thông tin dưới dạng danh sách các số dấu phẩy động trong một mảng. Với Gemini, bạn có thể biểu thị văn bản (từ, câu và khối văn bản) dưới dạng vectơ hoá, giúp bạn dễ dàng so sánh và đối chiếu các tệp nhúng. Ví dụ: hai văn bản có cùng một chủ đề hoặc tình cảm nên có các nội dung nhúng tương tự nhau, có thể được xác định thông qua các kỹ thuật so sánh toán học, chẳng hạn như tính tương đồng về giá trị cos.

Sử dụng mô hình embedding-001 với phương thức embedContent (hoặc phương thức batchEmbedContent) để tạo các bản nhúng. Ví dụ sau đây tạo một phép nhúng cho một chuỗi:

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

Số lượng mã thông báo

Khi sử dụng lời nhắc dài, bạn nên đếm mã thông báo trước khi gửi bất kỳ nội dung nào đến mô hình. Các ví dụ sau đây minh hoạ cách sử dụng countTokens() cho nhiều trường hợp sử dụng:

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

Các tuỳ chọn kiểm soát việc tạo nội dung

Bạn có thể kiểm soát việc tạo nội dung bằng cách định cấu hình các tham số mô hình và sử dụng các chế độ cài đặt an toàn.

Lưu ý rằng việc truyền generationConfig hoặc safetySettings sang phương thức yêu cầu mô hình (như generateContent) sẽ ghi đè toàn bộ đối tượng cấu hình có cùng tên được truyền trong getGenerativeModel.

Định cấu hình thông số mô hình

Mọi lời nhắc bạn gửi đến mô hình đều bao gồm các giá trị tham số kiểm soát cách mô hình tạo ra một phản hồi. Mô hình này có thể tạo ra các kết quả khác nhau cho các giá trị tham số khác nhau. Tìm hiểu thêm về Tham số mô hình.

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

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

Sử dụng các chế độ cài đặt an toàn

Bạn có thể sử dụng các chế độ cài đặt an toàn để điều chỉnh khả năng nhận được những câu trả lời có thể bị coi là gây hại. Theo mặc định, các chế độ cài đặt an toàn sẽ chặn nội dung có xác suất là nội dung không an toàn trên mọi phương diện ở mức trung bình và/hoặc cao. Tìm hiểu thêm về Chế độ cài đặt an toàn.

Sau đây là cách đặt một chế độ cài đặt an toàn:

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

Bạn cũng có thể đặt nhiều chế độ cài đặt an toàn:

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

Bước tiếp theo

  • Thiết kế lời nhắc là quá trình tạo các câu lệnh để khơi gợi phản hồi mong muốn từ các mô hình ngôn ngữ. Việc viết câu lệnh có cấu trúc hợp lý là một phần cần thiết để đảm bảo câu trả lời chính xác và chất lượng cao từ mô hình ngôn ngữ. Tìm hiểu các phương pháp hay nhất để viết gợi ý.

  • Gemini cung cấp một số biến thể mô hình để đáp ứng nhu cầu của nhiều trường hợp sử dụng, chẳng hạn như loại dữ liệu đầu vào và độ phức tạp, cách triển khai cho cuộc trò chuyện hoặc các tác vụ khác về ngôn ngữ hộp thoại cũng như các quy tắc ràng buộc về kích thước. Tìm hiểu về các mô hình Gemini hiện có.

  • Gemini đưa ra các tuỳ chọn để yêu cầu tăng giới hạn tốc độ. Giới hạn tốc độ cho các mô hình Genmini Pro là 60 yêu cầu mỗi phút (RPM).