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 wywołać tę funkcję 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, zwraca 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 moduły 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 obrazu, 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 danymi wejściowymi zawierającymi tekst i obraz, zwróci to połączoną liczbę tokenów tekstu i obrazu w danych wejściowych (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 i narzędzia systemowe również wliczają się do łącznej liczby tokenów dla danych wejściowych.

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

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