Zrozumienie i liczenie tokenów


Gemini i inne modele generatywnej AI przetwarzają dane wejściowe i wyjściowe z poziomu szczegółowości zwanej tokenem.

Informacje o tokenach

Tokeny mogą być pojedynczymi znakami, np. z, lub całymi słowami, np. cat. Długie słowa są dzielone na kilka tokenów. Zbiór wszystkich tokenów używanych przez model nazywa się słownictwem, a proces dzielenia tekstu na tokeny to tokenizacja.

W przypadku modeli Gemini token odpowiada około 4 znakom. 100 tokenów to około 60–80 słów w języku angielskim.

Gdy płatności są włączone, koszt wywołania interfejsu Gemini API jest częściowo określany przez liczbę tokenów wejściowych i wyjściowych, więc warto wiedzieć, jak je zliczać.

Liczba tokenów

Wszystkie dane wejściowe i wyjściowe Gemini API są tokenizowane, w tym tekst, pliki graficzne i inne dane nietekstowe.

Tokeny możesz zliczać na te sposoby:

  • Wywołaj funkcję countTokens z danymi z żądania.
    Zwraca łączną liczbę tokenów tylko w danych wejściowych. Możesz wykonać to wywołanie przed wysłaniem danych wejściowych do modelu, aby sprawdzić rozmiar żądań.

  • Użyj atrybutu usageMetadata w obiekcie response po wywołaniu funkcji generate_content.
    Zwraca łączną liczbę tokenów zarówno na wejściu, jak i na wyjściu: totalTokenCount.
    Zwraca też liczbę tokenów wejściowych i wyjściowych oddzielnie: promptTokenCount (tokeny wejściowe) i candidatesTokenCount (tokeny wyjściowe).

Liczenie tokenów tekstowych

Jeśli wywołasz funkcję countTokens z tekstem jako jedynym wejściem, zwraca ona liczbę tokenów tekstu w tylko wejściu (totalTokens). Możesz wykonać to wywołanie przed wywołaniem funkcji generateContent, aby sprawdzić rozmiar swoich żądań.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać:

  • Liczba tokenów wejściowych (promptTokenCount) i wyjściowych (candidatesTokenCount)
  • Łączna liczba tokenów w danych wejściowych i wyjściowych (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

Liczenie tokenów czatu wieloetapowego

Jeśli wywołasz funkcję countTokens z historią czatu, zwróci ona łączną liczbę tokenów tekstu z każdej roli w czacie (totalTokens).

Inną opcją jest wywołanie sendMessage, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać:

  • Liczba tokenów wejściowych (promptTokenCount) i wyjściowych (candidatesTokenCount)
  • Łączna liczba tokenów w danych wejściowych i wyjściowych (totalTokenCount).

Aby dowiedzieć się, jak długi będzie Twój następny wątek konwersacji, musisz dodać go do historii, gdy wywołasz funkcję 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

Liczenie tokenów multimodalnych

Wszystkie dane wejściowe do interfejsu Gemini API są tokenizowane, w tym tekst, pliki graficzne i inne modality nietekstowe. Pamiętaj o tych ogólnych kluczowych informacjach dotyczących tokenizacji danych multimodalnych podczas przetwarzania przez interfejs Gemini API:

  • W Gemini 2.0 dane wejściowe dotyczące obrazów, których oba wymiary są mniejsze niż 384 piksele, są zliczane jako 258 tokenów. Obrazy większe w jednym lub obu wymiarach są przycinane i skalowane w razie potrzeby do rozmiaru 768 x 768 pikseli. Każdy z nich jest liczony jako 258 tokenów. Przed wersją Gemini 2.0 obrazy używały stałych 258 tokenów.

  • Pliki wideo i audio są konwertowane na tokeny z użyciem tych stałych współczynników: filmy – 263 tokeny na sekundę, a dźwięk – 32 tokeny na sekundę.

Pliki graficzne

Jeśli wywołasz countTokens z tekstem i obrazem, zwróci to połączoną liczbę tokenów tekstu i obrazu w tylko wejściu (totalTokens). Możesz wykonać to wywołanie przed wywołaniem generateContent, aby sprawdzić rozmiar swoich żądań. Opcjonalnie możesz też wywołać countTokens osobno dla tekstu i pliku.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać:

  • Liczba tokenów wejściowych (promptTokenCount) i wyjściowych (candidatesTokenCount)
  • Łączna liczba tokenów w danych wejściowych i wyjściowych (totalTokenCount).

Przykład, który używa przesłanego obrazu z interfejsu 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

Przykład obrazka jako danych wstawionych:

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

pliki wideo lub audio,

Dźwięk i obraz są przekształcane w tokeny według tych stałych stawek:

  • Film: 263 tokeny na sekundę
  • Dźwięk: 32 tokeny na sekundę

Jeśli wywołasz funkcję countTokens z tekstem i filmem lub dźwiękiem, zwróci ona połączoną liczbę tokenów tekstu i pliku wideo lub dźwięku w tylko wejściu (totalTokens). Możesz wykonać to wywołanie przed wywołaniem funkcji generateContent, aby sprawdzić rozmiar swoich żądań. Opcjonalnie możesz też wywołać countTokens osobno dla tekstu i pliku.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać:

  • Liczba tokenów wejściowych (promptTokenCount) i wyjściowych (candidatesTokenCount)
  • Łączna liczba tokenów w danych wejściowych i wyjściowych (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

Instrukcje i narzędzia systemowe

Instrukcje systemowe i narzędzie są również uwzględniane w łącznej liczbie tokenów dla danych wejściowych.

Jeśli używasz instrukcji systemowych, liczba totalTokens zwiększy się, aby uwzględnić dodanie systemInstruction.

Jeśli używasz wywołania funkcji, liczba totalTokens zwiększa się, aby odzwierciedlić dodanie tools.