Blog

Hướng Dẫn Sử Dụng Google Gen AI TypeScript/JavaScript SDK Xây Dựng Ứng Dụng AI Tạo Sinh Mạnh Mẽ

Mark Ponomarev

Mark Ponomarev

27 tháng 5 2025

Hướng Dẫn Sử Dụng Google Gen AI TypeScript/JavaScript SDK Xây Dựng Ứng Dụng AI Tạo Sinh Mạnh Mẽ

Thế giới Trí tuệ Nhân tạo đang phát triển nhanh chóng, và Google đang đi đầu với các mô hình Gemini mạnh mẽ của mình. Đối với các nhà phát triển TypeScript và JavaScript muốn khai thác sức mạnh này, Google Gen AI SDK cung cấp một giải pháp toàn diện và linh hoạt. SDK này cho phép bạn dễ dàng xây dựng các ứng dụng được cung cấp năng lượng bởi Gemini 2.5 và các mô hình tiên tiến khác, hỗ trợ mạnh mẽ cho cả Gemini Developer API và Vertex AI. Bài viết này sẽ là hướng dẫn của bạn để hiểu và sử dụng SDK này, bao gồm các tính năng chính từ tương tác trực tiếp, thời gian thực và xử lý nội dung đa phương thức đến Chuyển văn bản thành giọng nói (TTS), tạo ảnh, và nhiều hơn nữa.

💡
Bạn muốn một công cụ Kiểm thử API tuyệt vời có thể tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, Tất cả trong một cho Đội ngũ Nhà phát triển của mình để làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn, và thay thế Postman với mức giá phải chăng hơn nhiều!

Giới thiệu: Kết nối JavaScript và sức mạnh của Gemini

Google Gen AI JavaScript SDK được thiết kế tỉ mỉ để cho phép các nhà phát triển tích hợp các khả năng AI tạo sinh tiên tiến của Google vào các ứng dụng web và Node.js của họ. Cho dù bạn đang xây dựng một chatbot phức tạp, một công cụ tạo nội dung thông minh, hay một ứng dụng có thể hiểu và tạo ra các loại phương tiện đa dạng, SDK này đều cung cấp các khối xây dựng cần thiết.

Một điểm mạnh cốt lõi của SDK là cách tiếp cận thống nhất để truy cập các mô hình Gemini, bất kể chúng được lưu trữ trên nền tảng Gemini Developer (thông qua khóa API từ Google AI Studio) hay nền tảng Vertex AI của Google Cloud. Sự linh hoạt này cho phép các nhà phát triển chọn môi trường phù hợp nhất với nhu cầu dự án của họ, từ tạo mẫu nhanh với khóa API đến triển khai cấp độ sản xuất trên Vertex AI với các khả năng MLOps của nó.

SDK được thiết kế để hoạt động liền mạch với các tính năng Gemini mới nhất, bao gồm các mô hình Gemini 2.5 rất được mong đợi, đảm bảo các nhà phát triển có quyền truy cập vào AI hiện đại ngay khi nó có sẵn.

Bắt đầu: Cài đặt và Khởi tạo

Trước khi đi sâu vào các tính năng nâng cao, hãy cùng tìm hiểu những điều cơ bản về việc thiết lập SDK.

Điều kiện tiên quyết:
Đảm bảo bạn đã cài đặt Node.js phiên bản 18 trở lên trong môi trường phát triển của mình.

Cài đặt:
Cài đặt SDK rất đơn giản bằng cách sử dụng npm:

npm install @google/genai

Khởi tạo - Cổng kết nối của bạn đến Gemini:
Tất cả các tương tác với Gemini API, dù thông qua Google AI Studio hay Vertex AI, đều bắt đầu bằng cách khởi tạo lớp GoogleGenAI.

1. Sử dụng Gemini Developer API (với Khóa API):
Đây thường là cách nhanh nhất để bắt đầu, đặc biệt đối với các ứng dụng phía máy chủ hoặc dự án cá nhân. Bạn sẽ cần một khóa API từ Google AI Studio.

import { GoogleGenAI } from '@google/genai';

const GEMINI_API_KEY = process.env.GEMINI_API_KEY; // Hoặc khóa API thực tế của bạn
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

async function run() {
  // Ví dụ: Tạo nội dung văn bản
  const model = ai.models.generateContent({
    model: "gemini-pro", // Hoặc một mô hình Gemini 2.5 cụ thể như "gemini-2.5-flash-001"
    contents: [{ role: "user", parts: [{ text: "Giải thích ý nghĩa của Google Gen AI SDK." }] }]
  });
  const response = await model;
  console.log(response.text);
}

run();
Cảnh báo về Bảo mật Khóa API:

2. Sử dụng Vertex AI:
Đối với các ứng dụng yêu cầu sự mạnh mẽ và khả năng mở rộng của Google Cloud, khởi tạo SDK cho Vertex AI là lựa chọn phù hợp. Điều này bao gồm việc chỉ định ID dự án Google Cloud và vị trí của bạn.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location', // ví dụ: 'us-central1'
});

async function runVertex() {
  // Ví dụ: Tạo nội dung văn bản với Vertex AI
  const model = ai.models.generateContent({
    model: "gemini-1.5-pro-preview-0409", // Ví dụ mô hình Vertex AI
    contents: [{ role: "user", parts: [{ text: "Lợi ích của việc sử dụng Vertex AI với Gen AI SDK là gì?" }] }]
  });
  const response = await model;
  console.log(response.text);
}

runVertex();

Chọn Phiên bản API:
Theo mặc định, SDK sử dụng các điểm cuối API beta để cung cấp quyền truy cập sớm vào các tính năng xem trước. Tuy nhiên, đối với các ứng dụng yêu cầu sự ổn định, bạn có thể chọn rõ ràng phiên bản API v1 (ổn định) hoặc các phiên bản API cụ thể khác (như v1alpha cho một số tính năng xem trước trên Gemini API) trong quá trình khởi tạo:

Đối với Vertex AI (đặt thành v1):

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location',
    apiVersion: 'v1'
});

Đối với Gemini Developer API (đặt thành v1alpha cho các tính năng như ai.live):

const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',
    apiVersion: 'v1alpha'
});

Cấu trúc SDK cốt lõi: Đối tượng GoogleGenAI

Sau khi được khởi tạo, đối tượng ai (một phiên bản của GoogleGenAI) là giao diện chính của bạn để truy cập các khả năng của SDK. Nó cung cấp quyền truy cập vào các mô-đun con khác nhau, mỗi mô-đun phục vụ các chức năng cụ thể:

Xây dựng ứng dụng với các mô hình Gemini 2.5

SDK là đường dây trực tiếp của bạn đến sức mạnh của các mô hình Gemini 2.5 (và các phiên bản trước đó như Gemini 1.0 Pro, 1.5 Pro, và 1.5 Flash). Để sử dụng một mô hình cụ thể, bạn chỉ cần tham chiếu tên của nó trong tham số model của các phương thức như ai.models.generateContent() hoặc khi tạo phiên chat với ai.chats.create().

Ví dụ, để sử dụng mô hình gemini-2.5-flash-001 (tên giả định, thay thế bằng các định danh mô hình thực tế khi chúng được phát hành):

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash-001', // Sử dụng định danh mô hình cụ thể
  contents: [{ role: "user", parts: [{ text: "Hãy cho tôi biết về những tiến bộ chính trong Gemini 2.5." }] }]
});
console.log(response.text);

SDK xử lý các lệnh gọi API cơ bản, cho phép bạn tập trung vào việc tạo các prompt và xử lý nội dung được tạo ra. Khi Google phát hành các mô hình mới và cập nhật các mô hình hiện có, bạn thường có thể chuyển đổi sang chúng bằng cách đơn giản thay đổi chuỗi định danh mô hình, giúp ứng dụng của bạn luôn cập nhật công nghệ tiên tiến nhất.

Tìm hiểu sâu: Xử lý nội dung đa phương thức (MCP)

Một trong những khía cạnh mạnh mẽ nhất của các mô hình Gemini là khả năng hiểu và tạo nội dung trên nhiều phương thức (văn bản, ảnh, âm thanh, video). Google Gen AI SDK hỗ trợ đầy đủ điều này, cho phép bạn xây dựng các ứng dụng đa phương thức phong phú.

MCP chủ yếu được thực hiện thông qua tham số contents trong các phương thức như generateContent và sendMessage (trong chat). Mảng contents chứa một loạt các đối tượng Content, mỗi đối tượng có thể chứa nhiều đối tượng Part. Mỗi Part có thể đại diện cho một loại dữ liệu khác nhau.

Cấu trúc Nội dung Đa phương thức:

Ví dụ: Prompt Đa phương thức (Văn bản và Ảnh):

import { GoogleGenAI } from '@google/genai';
// ... (Khởi tạo)

async function describeImage() {
  // Giả sử 'base64ImageData' là một chuỗi Base64 được mã hóa của một ảnh JPEG
  const base64ImageData = "..."; // Dữ liệu ảnh Base64 của bạn

  const contents = [
    {
      role: "user",
      parts: [
        { text: "Có gì trong bức ảnh này?" },
        {
          inlineData: {
            mimeType: "image/jpeg",
            data: base64ImageData,
          },
        },
      ],
    },
  ];

  const response = await ai.models.generateContent({
    model: "gemini-pro-vision", // Hoặc một mô hình Gemini 2.5 có khả năng xử lý ảnh
    contents: contents,
  });
  console.log(response.text);
}

describeImage();

Khả năng kết hợp liền mạch các loại dữ liệu khác nhau trong các prompt của bạn mở ra một loạt các khả năng ứng dụng, từ hệ thống hỏi đáp trực quan đến các công cụ phân tích và mô tả nội dung video. Mặc dù SDK cung cấp các phương thức trực tiếp để tạo ảnh, việc tạo video không được cung cấp rõ ràng như một phương thức SDK trực tiếp. Thay vào đó, video chủ yếu được xử lý như một phương thức đầu vào. Tuy nhiên, các mô hình đa phương thức tiên tiến được truy cập qua generateContent có thể có khả năng xử lý và phản hồi đầu vào video theo những cách tinh vi, chẳng hạn như tóm tắt hoặc trả lời các câu hỏi về nội dung video.

Tương tác thời gian thực với Live API (ai.live)

Đối với các ứng dụng yêu cầu trải nghiệm tương tác, độ trễ thấp, mô-đun con ai.live là một bước đột phá. Hiện đang ở dạng Xem trước và yêu cầu phiên bản API v1alpha cho Gemini API, ai.live thiết lập kết nối WebSocket để truyền dữ liệu hai chiều theo luồng với các mô hình Gemini. Điều này cho phép truyền văn bản, các đoạn âm thanh, và thậm chí cả các khung hình video theo thời gian thực làm đầu vào, và nhận văn bản hoặc âm thanh làm đầu ra.

Các Khái niệm Chính của ai.live:

  1. ai.live.connect(params): Đây là điểm vào. Bạn cung cấp các tham số như tên mô hình (model), cấu hình kết nối (config), và các hàm callback (callbacks) cho các sự kiện WebSocket khác nhau (ví dụ: onopen, onmessage, onerror, onclose). Nó trả về một Promise giải quyết thành một đối tượng Session.
  2. Đối tượng Session: Đại diện cho kết nối WebSocket đang hoạt động. Nó có các phương thức để:

Cấu hình (LiveConnectParameters và LiveConnectConfig):

Callbacks (LiveCallbacks):

Ví dụ: Thiết lập ai.live cơ bản (Khái niệm):

import { GoogleGenAI, Modality } from '@google/genai';

// Đảm bảo bạn khởi tạo với apiVersion: 'v1alpha' cho Gemini API
const ai = new GoogleGenAI({ apiKey: 'YOUR_GEMINI_API_KEY', apiVersion: 'v1alpha' });

async function startLiveSession() {
  try {
    const session = await ai.live.connect({
      model: 'gemini-pro', // Hoặc một mô hình cụ thể hỗ trợ live, kiểm tra tài liệu
      config: {
        responseModalities: [Modality.TEXT, Modality.AUDIO], // Mong đợi nhận văn bản và âm thanh
        // speechConfig: { ... } // Cho TTS, được đề cập dưới đây
      },
      callbacks: {
        onopen: () => console.log('Phiên live đã kết nối!'),
        onmessage: (serverMessage) => {
          // Xử lý tin nhắn từ máy chủ
          // Đây có thể là văn bản, dữ liệu âm thanh, lệnh gọi công cụ, v.v.
          console.log('Đã nhận từ máy chủ:', serverMessage);
          if (serverMessage.speechUpdate?.audio) {
            // Xử lý dữ liệu âm thanh đến (ví dụ: phát nó)
            const audioBytes = serverMessage.speechUpdate.audio;
            // ... logic phát âm thanh của bạn ...
          }
          if (serverMessage.textUpdate?.text) {
             console.log("Văn bản: ", serverMessage.textUpdate.text);
          }
        },
        onerror: (error) => console.error('Lỗi phiên live:', error),
        onclose: () => console.log('Phiên live đã đóng.'),
      },
    });

    // Bây giờ bạn có thể gửi tin nhắn
    session.sendClientContent({ turns: [{ role: 'user', parts: [{text: 'Xin chào, Gemini live!'}] }] });

    // Đối với đầu vào âm thanh liên tục:
    // navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
    //   const mediaRecorder = new MediaRecorder(stream);
    //   mediaRecorder.ondataavailable = event => {
    //     if (event.data.size > 0) {
    //       session.sendRealtimeInput({ media: { mediaChunks: [event.data] } });
    //     }
    //   };
    //   mediaRecorder.start(1000); // Gửi các đoạn âm thanh mỗi giây
    // });

    // Nhớ đóng phiên khi hoàn thành
    // session.close();

  } catch (error) {
    console.error('Không thể kết nối phiên live:', error);
  }
}

startLiveSession();

Mô-đun ai.live cực kỳ mạnh mẽ để xây dựng các ứng dụng có cảm giác thực sự đàm thoại và phản hồi nhanh, phản ứng theo thời gian thực với các đầu vào của người dùng trên các phương thức khác nhau.

Các mô hình và khả năng Chuyển văn bản thành giọng nói (TTS)

SDK hỗ trợ việc tạo Chuyển văn bản thành giọng nói (TTS), chủ yếu thông qua giao diện ai.live khi yêu cầu đầu ra âm thanh. Điều này cho phép các mô hình Gemini phản hồi không chỉ bằng văn bản, mà còn bằng âm thanh nói.

Cấu hình TTS (SpeechConfig và VoiceConfig):

Khi bạn thiết lập kết nối trực tiếp bằng cách sử dụng ai.live.connect(), bạn có thể chỉ định một speechConfig trong tham số config.

Ví dụ: Yêu cầu Đầu ra Âm thanh trong Phiên Live:

// Trong các tham số ai.live.connect:
// ...
config: {
  responseModalities: [Modality.AUDIO], // Quan trọng cho TTS
  speechConfig: {
    voiceConfig: {
      // Thay thế bằng tên giọng nói được xây dựng sẵn thực tế có sẵn
      prebuiltVoice: 'aura-asteria-en',
    }
  }
},
callbacks: {
  onmessage: (serverMessage) => {
    if (serverMessage.speechUpdate?.audio) {
      const audioData = serverMessage.speechUpdate.audio; // Đây là ArrayBuffer
      // Logic để phát dữ liệu âm thanh này trong trình duyệt hoặc lưu nó trong Node.js
      // Ví dụ, trong trình duyệt:
      // const audioBlob = new Blob([audioData], { type: 'audio/mpeg' }); // Hoặc loại MIME phù hợp
      // const audioUrl = URL.createObjectURL(audioBlob);
      // new Audio(audioUrl).play();
      console.log('Đã nhận dữ liệu âm thanh cho TTS.');
    }
    if (serverMessage.textUpdate?.text) {
        console.log("Văn bản đi kèm (nếu có):", serverMessage.textUpdate.text)
    }
  },
  // ... các callbacks khác
},
// ...

Khi được cấu hình cho đầu ra âm thanh, hàm callback onmessage trong phiên live của bạn sẽ nhận các đối tượng ServerMessage. Nếu tin nhắn chứa giọng nói, trường speechUpdate.audio sẽ chứa dữ liệu âm thanh (thường dưới dạng ArrayBuffer). Sau đó, bạn có thể xử lý dữ liệu này để phát lại cho người dùng hoặc lưu nó dưới dạng tệp âm thanh. Trường textUpdate.text cũng có thể được điền phiên bản văn bản của giọng nói.

Sự tích hợp TTS này trực tiếp vào luồng hội thoại trực tiếp làm cho SDK trở nên lý tưởng cho các ứng dụng ưu tiên giọng nói, trợ lý tương tác và các tính năng hỗ trợ tiếp cận.

Các mô hình tạo ảnh

SDK cung cấp một phương thức chuyên dụng để tạo ảnh bằng cách sử dụng các mô hình như Imagen: ai.models.generateImages(). Phương thức này cho phép bạn cung cấp một prompt văn bản và nhận dữ liệu ảnh được tạo ra.

Sử dụng ai.models.generateImages():

Phương thức này nhận các tham số GenerateImagesParameters, bao gồm:

Ví dụ: Tạo một bức ảnh:

import { GoogleGenAI } from '@google/genai';
// ... (Khởi tạo cho Vertex AI, vì Imagen thường là một dịch vụ của Vertex AI)
const ai = new GoogleGenAI({ vertexai: true, project: 'your-gcp-project-id', location: 'your-gcp-location' });


async function createImage() {
  try {
    const response = await ai.models.generateImages({
      model: 'imagen-3.0-generate-002', // Kiểm tra tài liệu để biết mô hình mới nhất
      prompt: 'Một cảnh quan thành phố tương lai lúc hoàng hôn, với các phương tiện bay và đèn neon.',
      config: {
        numberOfImages: 1,
        aspectRatio: '16:9',
        includeRaiReason: true,
      },
    });

    if (response?.generatedImages && response.generatedImages.length > 0) {
      const imageBytesBase64 = response.generatedImages[0]?.image?.imageBytes;
      if (imageBytesBase64) {
        // imageBytesBase64 là một chuỗi Base64 được mã hóa của ảnh
        console.log('Ảnh đã được tạo (đã mã hóa Base64)!');
        // Sau đó, bạn có thể hiển thị ảnh này trong trình duyệt (ví dụ: <img src="data:image/png;base64,..." />)
        // hoặc lưu nó vào một tệp trong Node.js
      }
    } else {
      console.log('Không có ảnh được tạo hoặc bị lọc bởi RAI:', response?.raiFilteredReason);
    }
  } catch (error) {
    console.error('Lỗi khi tạo ảnh:', error);
  }
}

createImage();

Phản hồi (GenerateImagesResponse) sẽ chứa một mảng các đối tượng GeneratedImage. Mỗi đối tượng có thể bao gồm dữ liệu ảnh (thường dưới dạng imageBytes ở định dạng Base64), một raiFilteredReason nếu nó bị lọc, và các siêu dữ liệu khác.

Xử lý Video (dưới dạng Đầu vào)

Như đã nhấn mạnh trước đó, SDK chủ yếu coi video là một phương thức đầu vào chứ không phải là đầu ra được tạo ra. Bạn có thể bao gồm dữ liệu video trong các prompt của mình cho các mô hình Gemini đa phương thức theo một vài cách:

Tải lên Tệp Video (ai.files.upload() - Gemini API):
Bạn có thể tải lên các tệp video (ví dụ: MP4) bằng cách sử dụng mô-đun con ai.files. Sau khi tải lên, bạn nhận được một URI tệp có thể được tham chiếu trong phần fileData của đối tượng Content của bạn.

// Ví dụ khái niệm về tải lên tệp (Gemini API)
// const uploadedFile = await ai.files.upload({
//   file: pathToYourVideoFile, // Hoặc một Blob trong trình duyệt
//   mimeType: 'video/mp4',
//   displayName: 'my-cool-video.mp4'
// });
// const videoFileUri = uploadedFile.uri;

const contents = [{
  role: "user",
  parts: [
    { text: "Tóm tắt video này." },
    { fileData: { mimeType: "video/mp4", fileUri: "YOUR_UPLOADED_VIDEO_URI_HERE" } },
    // Tùy chọn, thêm VideoMetadata
    // { videoMetadata: { startOffset: "0s", endOffset: "30s" } } // Xử lý 30s đầu tiên
  ]
}];

Sử dụng URI Google Cloud Storage (Vertex AI):
Khi sử dụng Vertex AI, bạn có thể trực tiếp tham chiếu các tệp video được lưu trữ trong các bucket Google Cloud Storage bằng cách sử dụng URI gs:// của chúng trong phần fileData.

Khung hình Video Trực tiếp (ai.live):
Như đã thảo luận trong phần ai.live, bạn có thể gửi các khung hình video riêng lẻ (dưới dạng đối tượng Blob, có thể là các loại MIME ảnh như image/jpeg hoặc image/png) bằng cách sử dụng session.sendRealtimeInput(). Điều này cho phép phân tích hoặc tương tác theo thời gian thực dựa trên luồng video trực tiếp.

Giao diện VideoMetadata, với startOffset và endOffset, cho phép bạn chỉ định phân đoạn nào của tệp video mà mô hình nên tập trung vào, điều này hữu ích cho việc xử lý các video dài.

Hỗ trợ Gemini API so với Vertex AI: Một cách tiếp cận kép

Một lợi thế đáng kể của Google Gen AI SDK là khả năng hỗ trợ liền mạch cho cả Gemini Developer API (thông qua Google AI Studio) và Vertex AI. Hỗ trợ kép này mang lại sự linh hoạt cho nhà phát triển và một lộ trình nâng cấp rõ ràng.

SDK trừu tượng hóa nhiều điểm khác biệt. Các phương thức cốt lõi như ai.models.generateContent() hoạt động tương tự cho cả hai, với điểm khác biệt chính là việc khởi tạo (apiKey so với vertexai: true, project, location). Điều này cho phép bạn bắt đầu với Gemini API và di chuyển sang Vertex AI khi ứng dụng của bạn trưởng thành và mở rộng quy mô, mà không cần viết lại toàn bộ logic AI của bạn. Tài liệu cho các phương thức thường chỉ định nếu một tính năng hoặc tham số là duy nhất cho một nền tảng.

Kết luận: Bộ công cụ của bạn cho các ứng dụng AI thế hệ tiếp theo

Google Gen AI TypeScript/JavaScript SDK là một bộ công cụ mạnh mẽ và linh hoạt mang khả năng của Gemini 2.5 và các mô hình tiên tiến khác trực tiếp đến các nhà phát triển JavaScript. Khả năng hỗ trợ nội dung đa phương thức, tương tác thời gian thực qua Live API, tích hợp TTS, tạo ảnh, và sự linh hoạt trong việc lựa chọn giữa Gemini Developer API và Vertex AI làm cho nó trở thành một nguồn tài nguyên không thể thiếu.

Bằng cách hiểu cấu trúc của SDK, các mô-đun cốt lõi của nó (ai.models, ai.live, ai.chats, ai.files, ai.caches), và các sắc thái của việc tạo prompt đa phương thức, bạn được trang bị tốt để xây dựng các ứng dụng sáng tạo có thể nhìn, nghe, nói và hiểu thế giới theo những cách phong phú hơn bao giờ hết. Khi Google tiếp tục đẩy mạnh ranh giới của AI, SDK này sẽ là chìa khóa để bạn khai thác tiềm năng đó trong các dự án JavaScript và TypeScript của mình. Hãy bắt tay vào, thử nghiệm và xây dựng tương lai của các ứng dụng được hỗ trợ bởi AI ngay hôm nay!

Tôi đã tạo bài viết dựa trên thông tin thu thập được từ tệp README.md và thư mục docs. Nó bao gồm tất cả các chủ đề được chỉ định và hướng tới số lượng từ được yêu cầu.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống