Tìm hiểu và tính mã thông báo

Gemini và các mô hình AI tạo sinh khác xử lý dữ liệu đầu vào và đầu ra ở mức độ chi tiết được gọi là mã thông báo.

Giới thiệu về mã thông báo

Mã thông báo có thể là một ký tự đơn như z hoặc toàn bộ từ như cat. Các từ dài được chia thành nhiều mã thông báo. Tập hợp tất cả các mã thông báo mà mô hình sử dụng được gọi là từ vựng và quá trình chia văn bản thành các mã thông báo được gọi là tạo mã thông báo.

Đối với các mô hình Gemini, một mã thông báo tương đương với khoảng 4 ký tự. 100 mã thông báo tương đương với khoảng 60 đến 80 từ tiếng Anh.

Khi bật tính năng thanh toán, chi phí của một lệnh gọi đến API Gemini sẽ được xác định một phần theo số lượng mã thông báo đầu vào và đầu ra. Vì vậy, bạn nên biết cách tính mã thông báo.

Đếm mã thông báo

Tất cả dữ liệu đầu vào và đầu ra của API Gemini đều được mã hoá, bao gồm cả văn bản, tệp hình ảnh và các phương thức không phải văn bản khác.

Bạn có thể đếm mã thông báo theo các cách sau:

Gọi countTokens bằng dữ liệu đầu vào của yêu cầu.
Hàm này trả về tổng số mã thông báo trong phần đầu vào. Bạn có thể thực hiện lệnh gọi này trước khi gửi dữ liệu đầu vào đến mô hình để kiểm tra kích thước của các yêu cầu.
Sử dụng thuộc tính usageMetadata trên đối tượng response sau khi gọi generate_content.
Hàm này trả về tổng số mã thông báo trong cả dữ liệu đầu vào và đầu ra: totalTokenCount.
Hàm này cũng trả về số lượng mã thông báo của dữ liệu đầu vào và đầu ra riêng biệt: promptTokenCount (mã thông báo đầu vào) và candidatesTokenCount (mã thông báo đầu ra).

Đếm mã thông báo văn bản

Nếu bạn gọi countTokens bằng dữ liệu đầu vào chỉ văn bản, thì hàm này sẽ trả về số lượng mã thông báo của văn bản trong dữ liệu đầu vào (totalTokens). Bạn có thể thực hiện lệnh gọi này trước khi gọi generateContent để kiểm tra kích thước của các yêu cầu.

Một lựa chọn khác là gọi generateContent, sau đó sử dụng thuộc tính usageMetadata trên đối tượng response để nhận được kết quả sau:

Số lượng mã thông báo riêng biệt của dữ liệu đầu vào (promptTokenCount) và đầu ra (candidatesTokenCount)
Tổng số mã thông báo trong cả dữ liệu đầu vào và đầu ra (totalTokenCount)

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(generateResponse.usageMetadata);count_tokens.js

Đếm mã thông báo nhiều lượt (trò chuyện)

Nếu bạn gọi countTokens bằng nhật ký trò chuyện, hàm này sẽ trả về tổng số mã thông báo của văn bản từ mỗi vai trò trong cuộc trò chuyện (totalTokens).

Một lựa chọn khác là gọi sendMessage, sau đó sử dụng thuộc tính usageMetadata trên đối tượng response để nhận được kết quả sau:

Số lượng mã thông báo riêng biệt của dữ liệu đầu vào (promptTokenCount) và đầu ra (candidatesTokenCount)
Tổng số mã thông báo trong cả dữ liệu đầu vào và đầu ra (totalTokenCount)

Để biết lượt trò chuyện tiếp theo sẽ dài bao nhiêu, bạn cần thêm lượt trò chuyện đó vào nhật ký khi gọi countTokens.

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Initial chat history.
const history = [
  { role: "user", parts: [{ text: "Hi my name is Bob" }] },
  { role: "model", parts: [{ text: "Hi Bob!" }] },
];
const chat = ai.chats.create({
  model: "gemini-2.0-flash",
  history: history,
});

// Count tokens for the current chat history.
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);

const chatResponse = await chat.sendMessage({
  message: "In one sentence, explain how a computer works to a young child.",
});
console.log(chatResponse.usageMetadata);

// Add an extra user message to the history.
const extraMessage = {
  role: "user",
  parts: [{ text: "What is the meaning of life?" }],
};
const combinedHistory = chat.getHistory();
combinedHistory.push(extraMessage);
const combinedCountTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: combinedHistory,
});
console.log(
  "Combined history token count:",
  combinedCountTokensResponse.totalTokens,
);count_tokens.js

Đếm mã thông báo đa phương thức

Tất cả dữ liệu đầu vào cho API Gemini đều được mã hoá, bao gồm cả văn bản, tệp hình ảnh và các phương thức không phải văn bản khác. Hãy lưu ý những điểm chính sau đây về việc mã hoá dữ liệu đầu vào đa phương thức trong quá trình xử lý bằng Gemini API:

Với Gemini 2.0, dữ liệu đầu vào hình ảnh có cả hai kích thước <=384 pixel được tính là 258 mã thông báo. Những hình ảnh lớn hơn ở một hoặc cả hai kích thước sẽ được cắt và điều chỉnh theo tỷ lệ nếu cần thành các ô có kích thước 768x768 pixel, mỗi ô được tính là 258 mã thông báo. Trước Gemini 2.0, hình ảnh sử dụng 258 mã thông báo cố định.
Tệp video và âm thanh được chuyển đổi thành mã thông báo theo các tốc độ cố định sau: video ở tốc độ 263 mã thông báo mỗi giây và âm thanh ở tốc độ 32 mã thông báo mỗi giây.

Tệp hình ảnh

Nếu bạn gọi countTokens bằng dữ liệu đầu vào văn bản và hình ảnh, thì hàm này sẽ trả về số lượng mã thông báo kết hợp của văn bản và hình ảnh trong chỉ dữ liệu đầu vào (totalTokens). Bạn có thể thực hiện lệnh gọi này trước khi gọi generateContent để kiểm tra kích thước của các yêu cầu. Bạn cũng có thể gọi countTokens trên văn bản và tệp riêng biệt.

Một lựa chọn khác là gọi generateContent, sau đó sử dụng thuộc tính usageMetadata trên đối tượng response để nhận được kết quả sau:

Số lượng mã thông báo riêng biệt của dữ liệu đầu vào (promptTokenCount) và đầu ra (candidatesTokenCount)
Tổng số mã thông báo trong cả dữ liệu đầu vào và đầu ra (totalTokenCount)

Ví dụ sử dụng hình ảnh đã tải lên từ API Tệp:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const organ = await ai.files.upload({
  file: path.join(media, "organ.jpg"),
  config: { mimeType: "image/jpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);count_tokens.js

Ví dụ cung cấp hình ảnh dưới dạng dữ liệu nội tuyến:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

// Convert buffer to base64 string.
const imageBase64 = imageBuffer.toString("base64");

// Build contents using createUserContent and createPartFromBase64.
const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, "image/jpeg"),
]);

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(generateResponse.usageMetadata);count_tokens.js

Tệp video hoặc âm thanh

Âm thanh và video được chuyển đổi thành mã thông báo theo các tỷ lệ cố định sau:

Video: 263 mã thông báo mỗi giây
Âm thanh: 32 mã thông báo mỗi giây

Nếu bạn gọi countTokens bằng dữ liệu đầu vào văn bản và video/âm thanh, thì hàm này sẽ trả về số lượng mã thông báo kết hợp của văn bản và tệp video/âm thanh ở chỉ đầu vào (totalTokens). Bạn có thể thực hiện lệnh gọi này trước khi gọi generateContent để kiểm tra kích thước của các yêu cầu. Bạn cũng có thể tuỳ ý gọi countTokens trên văn bản và tệp riêng biệt.

Một lựa chọn khác là gọi generateContent, sau đó sử dụng thuộc tính usageMetadata trên đối tượng response để nhận được kết quả sau:

Số lượng mã thông báo riêng biệt của dữ liệu đầu vào (promptTokenCount) và đầu ra (candidatesTokenCount)
Tổng số mã thông báo trong cả dữ liệu đầu vào và đầu ra (totalTokenCount)

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this video";
let videoFile = await ai.files.upload({
  file: path.join(media, "Big_Buck_Bunny.mp4"),
  config: { mimeType: "video/mp4" },
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!videoFile.state || videoFile.state.toString() !== "ACTIVE") {
  console.log("Processing video...");
  console.log("File state: ", videoFile.state);
  await sleep(5000);
  videoFile = await ai.files.get({ name: videoFile.name });
}

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);count_tokens.js

Hướng dẫn và công cụ hệ thống

Các hướng dẫn và công cụ của hệ thống cũng được tính vào tổng số mã thông báo cho dữ liệu đầu vào.

Nếu bạn sử dụng hướng dẫn hệ thống, số lượng totalTokens sẽ tăng lên để phản ánh việc thêm systemInstruction.

Nếu bạn sử dụng lệnh gọi hàm, số lượng totalTokens sẽ tăng lên để phản ánh việc thêm tools.