瞭解及計算符記


Gemini 和其他生成式 AI 模型會以稱為「符記」的精細程度處理輸入和輸出內容。

關於符記

符記可以是單一字元 (例如 z),也可以是整個字詞 (例如 cat)。長字詞會拆分為多個字元。模型使用的所有符記集合稱為詞彙,將文字分割為符記的程序稱為符記化

對於 Gemini 模型,一個符號約等於 4 個字元。100 個符記大約等於 60 到 80 個英文單字。

啟用計費功能後,對 Gemini API 的呼叫費用部分取決於輸入和輸出符記的數量,因此瞭解如何計算符記會很有幫助。

計算符記

所有輸入至 Gemini API 的內容和輸出內容都會經過符號化,包括文字、圖片檔案和其他非文字模式。

您可以透過下列方式計算符記:

  • 使用要求的輸入內容呼叫 countTokens
    這會傳回僅輸入中詞元的總數。您可以在將輸入內容傳送至模型前,先發出這項呼叫,以便檢查要求的大小。

  • 呼叫 generate_content 後,請在 response 物件上使用 usageMetadata 屬性。
    這會傳回輸入和輸出中詞元的總數:totalTokenCount
    它也會分別傳回輸入和輸出的符記數量:promptTokenCount (輸入符記) 和 candidatesTokenCount (輸出符記)。

計算文字符號

如果您使用僅文字的輸入內容呼叫 countTokens,系統會傳回僅輸入內容 (totalTokens) 中的文字符號數量。您可以在呼叫 generateContent 之前發出這項呼叫,以便檢查要求的大小。

另一個做法是呼叫 generateContent,然後使用 response 物件的 usageMetadata 屬性,取得以下內容:

  • 輸入 (promptTokenCount) 和輸出 (candidatesTokenCount) 的個別符號計數
  • 輸入和輸出中分詞的總數 (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);

計算多輪 (聊天) 符記

如果您使用聊天記錄呼叫 countTokens,系統會傳回聊天中每個角色的文字總符記數 (totalTokens)。

另一個做法是呼叫 sendMessage,然後使用 response 物件的 usageMetadata 屬性,取得以下內容:

  • 輸入 (promptTokenCount) 和輸出 (candidatesTokenCount) 的個別符號計數
  • 輸入和輸出中分詞的總數 (totalTokenCount)

如要瞭解下一個對話輪次的大小,您需要在呼叫 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,
);

計算多模態符記

所有 Gemini API 輸入內容都會經過符號化,包括文字、圖片檔案和其他非文字模式。請注意以下關於 Gemini API 處理期間多模態輸入內容符記化的重點:

  • 在 Gemini 2.0 中,如果圖片輸入內容的兩個尺寸都小於或等於 384 像素,系統會將其計為 258 個符記。圖片的一個或兩個尺寸大於 768 x 768 像素時,系統會視需要裁剪及縮放圖片,使其成為 768 x 768 像素的圖塊,每個圖塊會計為 258 個符記。在 Gemini 2.0 之前,圖片使用的是固定的 258 個符記。

  • 影片和音訊檔案會以下列固定的比率轉換為符記:影片為每秒 263 個符記,音訊為每秒 32 個符記。

圖片檔

如果您使用文字和圖片輸入內容呼叫 countTokens,系統會傳回文字和圖片在僅輸入內容 (totalTokens) 中的組合符記數。您可以在呼叫 generateContent 之前發出這項呼叫,以便檢查要求的大小。您也可以選擇分別對文字和檔案呼叫 countTokens

另一個做法是呼叫 generateContent,然後使用 response 物件的 usageMetadata 屬性,取得以下內容:

  • 輸入 (promptTokenCount) 和輸出 (candidatesTokenCount) 的個別符號計數
  • 輸入和輸出中分詞的總數 (totalTokenCount)

使用 File API 上傳的圖片的範例:

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

以下範例會以內嵌資料提供圖片:

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

影片或音訊檔案

音訊和影片會以下列固定費率轉換為符記:

  • 影片:每秒 263 個符記
  • 音訊:每秒 32 個符記

如果您使用文字和影片/音訊輸入內容呼叫 countTokens,系統會僅在輸入內容中傳回文字和影片/音訊檔案的組合符記數 (totalTokens)。您可以在呼叫 generateContent 之前發出這項呼叫,以便檢查要求的大小。您也可以選擇分別對文字和檔案呼叫 countTokens

另一個做法是呼叫 generateContent,然後使用 response 物件的 usageMetadata 屬性,取得以下內容:

  • 輸入 (promptTokenCount) 和輸出 (candidatesTokenCount) 的個別符號計數
  • 輸入和輸出中分詞的總數 (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);

系統指令和工具

系統指令和工具也會計入輸入內容的符記總數。

如果您使用系統指令,totalTokens 計數會增加,以反映 systemInstruction 的新增數量。

如果您使用函式呼叫,totalTokens 計數就會增加,以反映 tools 的增加。