Tokens verstehen und zählen


Gemini und andere generative KI-Modelle verarbeiten Eingaben und Ausgaben mit einer Detaillierung, die als Token bezeichnet wird.

Tokens

Tokens können einzelne Zeichen wie z oder ganze Wörter wie cat sein. Lange Wörter werden in mehrere Tokens aufgeteilt. Die Gesamtheit aller vom Modell verwendeten Tokens wird als Vokabular bezeichnet. Das Aufteilen von Text in Tokens wird als Tokenisierung bezeichnet.

Bei Gemini-Modellen entspricht ein Token etwa vier Zeichen. 100 Tokens entsprechen etwa 60–80 englischen Wörtern.

Wenn die Abrechnung aktiviert ist, werden die Kosten eines Aufrufs der Gemini API teilweise durch die Anzahl der Eingabe- und Ausgabetokens bestimmt. Daher kann es hilfreich sein, zu wissen, wie Tokens gezählt werden.

Tokens zählen

Alle Eingaben in die und Ausgaben aus der Gemini API werden tokenisiert, einschließlich Text, Bilddateien und anderer nicht textbasierter Modalitäten.

So können Sie Tokens zählen:

  • Rufen Sie countTokens mit der Eingabe der Anfrage auf.
    Damit wird die Gesamtzahl der Tokens nur in der Eingabe zurückgegeben. Sie können diesen Aufruf ausführen, bevor Sie die Eingabe an das Modell senden, um die Größe Ihrer Anfragen zu prüfen.

  • Verwende das usageMetadata-Attribut für das response-Objekt, nachdem du generate_content aufgerufen hast.
    Dadurch wird die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe zurückgegeben: totalTokenCount.
    Außerdem werden die Tokenanzahl der Eingabe und der Ausgabe separat zurückgegeben: promptTokenCount (Eingabetokens) und candidatesTokenCount (Ausgabetokens).

Text-Token zählen

Wenn Sie countTokens mit einer reinen Texteingabe aufrufen, wird die Tokenanzahl des Texts nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufruf von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das usageMetadata-Attribut für das response-Objekt zu verwenden, um Folgendes zu erhalten:

  • Die separaten Tokenanzahlen der Eingabe (promptTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (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

Anzahl der Tokens für Unterhaltungen in mehreren Runden (Chat) zählen

Wenn Sie countTokens mit dem Chatverlauf aufrufen, wird die Gesamtzahl der Tokens für den Text jeder Rolle im Chat (totalTokens) zurückgegeben.

Eine weitere Möglichkeit besteht darin, sendMessage aufzurufen und dann das usageMetadata-Attribut für das response-Objekt zu verwenden, um Folgendes zu erhalten:

  • Die separaten Tokenanzahlen der Eingabe (promptTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (totalTokenCount)

Wenn Sie wissen möchten, wie lang Ihr nächster Gesprächsbeitrag sein wird, müssen Sie ihn an den Verlauf anhängen, wenn Sie countTokens aufrufen.

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

Multimodale Tokens zählen

Alle Eingaben in die Gemini API werden tokenisiert, einschließlich Text, Bilddateien und anderer nicht textbasierter Modalitäten. Beachten Sie die folgenden wichtigen Punkte zur Tokenisierung multimodaler Eingaben bei der Verarbeitung durch die Gemini API:

  • Bei Gemini 2.0 werden Bildeingaben mit beiden Abmessungen von maximal 384 Pixeln als 258 Tokens gezählt. Bilder, die in einer oder beiden Dimensionen größer sind, werden bei Bedarf zu Kacheln mit einer Größe von 768 x 768 Pixeln zugeschnitten und skaliert. Sie werden jeweils mit 258 Tokens gezählt. Vor Gemini 2.0 wurden für Bilder 258 Token verwendet.

  • Video- und Audiodateien werden mit den folgenden festen Raten in Tokens umgewandelt: Video mit 263 Tokens pro Sekunde und Audio mit 32 Tokens pro Sekunde.

Bilddateien

Wenn Sie countTokens mit einer Text- und Bildeingabe aufrufen, wird die kombinierte Tokenanzahl des Texts und des Bilds nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufruf von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen. Optional können Sie countTokens auch für den Text und die Datei separat aufrufen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das usageMetadata-Attribut für das response-Objekt zu verwenden, um Folgendes zu erhalten:

  • Die separaten Tokenanzahlen der Eingabe (promptTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (totalTokenCount)

Beispiel für ein hochgeladenes Bild aus der 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);
count_tokens.js

Beispiel für ein Bild als Inline-Daten:

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

Video- oder Audiodateien

Audio und Video werden jeweils mit den folgenden festen Raten in Tokens umgewandelt:

  • Video: 263 Tokens pro Sekunde
  • Audio: 32 Tokens pro Sekunde

Wenn Sie countTokens mit einer Text- und Video-/Audioeingabe aufrufen, wird die kombinierte Tokenanzahl des Texts und der Video-/Audiodatei nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufruf von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen. Optional können Sie countTokens auch für den Text und die Datei separat aufrufen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das usageMetadata-Attribut für das response-Objekt zu verwenden, um Folgendes zu erhalten:

  • Die separaten Tokenanzahlen der Eingabe (promptTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (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

Systemanweisungen und ‑tools

Systemanweisungen und -tools werden ebenfalls auf die Gesamtzahl der Tokens für die Eingabe angerechnet.

Wenn Sie Systemanweisungen verwenden, erhöht sich die Anzahl von totalTokens, um die Hinzufügung von systemInstruction widerzuspiegeln.

Wenn Sie Funktionsaufrufe verwenden, erhöht sich die Anzahl von totalTokens, um die Hinzufügung von tools widerzuspiegeln.