Понимать и считать жетоны

Gemini и другие модели генеративного ИИ обрабатывают входные и выходные данные с уровнем детализации, называемым токеном .

Для моделей Gemini один токен эквивалентен примерно 4 символам. 100 токенов равны примерно 60-80 английским словам.

О токенах

Токены могут представлять собой отдельные символы, например, z или целые слова, например, cat . Длинные слова разбиваются на несколько токенов. Множество всех токенов, используемых моделью, называется словарем, а процесс разделения текста на токены называется токенизацией .

При включенной плате за использование API Gemini стоимость вызова определяется, в частности, количеством входных и выходных токенов, поэтому знание того, как подсчитывать токены, может быть полезным.


Подсчет токенов

Все входные и выходные данные API Gemini, включая текст, файлы изображений и другие нетекстовые форматы, токенизируются.

Подсчет токенов можно производить следующими способами:

  • Вызовите функцию countTokens используя в качестве входных данных запрос.
    Эта функция возвращает только общее количество токенов во входных данных . Вы можете вызвать её перед отправкой входных данных в модель, чтобы проверить размер ваших запросов.

  • После вызова функции generate_content используйте атрибут usageMetadata объекта response .
    Эта функция возвращает общее количество токенов как на входе, так и на выходе : totalTokenCount .
    Также он возвращает количество токенов на входе и выходе отдельно: promptTokenCount (токены на входе) и candidatesTokenCount (токены на выходе). А если вы используете контекстное кэширование , количество кэшированных токенов будет в cachedContentTokenCount .

    Если вы используете модель мышления, подобную той, что используется в версии 2.5, токены, использованные в процессе мышления, возвращаются в thoughtsTokenCount .

Подсчет текстовых токенов

Если вы вызовете countTokens с текстовым полем ввода, он вернет количество токенов только из текста в этом поле ( totalTokens ). Вы можете сделать этот вызов перед вызовом generateContent , чтобы проверить размер ваших запросов.

Другой вариант — вызвать функцию generateContent , а затем использовать атрибут usageMetadata объекта response , чтобы получить следующее:

  • Отдельные подсчеты токенов для входных данных ( promptTokenCount ), кэшированного содержимого ( cachedContentTokenCount ) и выходных данных ( candidatesTokenCount ).
  • Количество токенов, используемых в процессе мышления ( thoughtsTokenCount )
  • Общее количество токенов как на входе, так и на выходе ( 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

Подсчет токенов для многоходовых (чат) операций

Если вы вызовете функцию countTokens с историей чата, она вернет общее количество токенов текста от каждой роли в чате ( totalTokens ).

Другой вариант — вызвать функцию sendMessage , а затем использовать атрибут usageMetadata объекта response , чтобы получить следующее:

  • Отдельные подсчеты токенов для входных данных ( promptTokenCount ), кэшированного содержимого ( cachedContentTokenCount ) и выходных данных ( candidatesTokenCount ).
  • Количество токенов, используемых в процессе мышления ( thoughtsTokenCount )
  • Общее количество токенов как на входе, так и на выходе ( 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,
);
count_tokens.js

Подсчет мультимодальных токенов

Все входные данные в API Gemini токенизируются, включая текст, файлы изображений и другие нетекстовые форматы. Обратите внимание на следующие основные моменты, касающиеся токенизации мультимодальных входных данных в процессе обработки API Gemini:

  • В Gemini 2.0 изображения, у которых оба измерения <=384 пикселей, учитываются как 258 токенов. Изображения большего размера в одном или обоих измерениях обрезаются и масштабируются по мере необходимости в фрагменты размером 768x768 пикселей, каждый из которых учитывается как 258 токенов. До Gemini 2.0 изображения использовали фиксированное количество токенов — 258.

  • Видео- и аудиофайлы преобразуются в токены со следующей фиксированной скоростью: видео — 263 токена в секунду, аудио — 32 токена в секунду.

Резолюции СМИ

В Gemini 3 Pro Preview реализовано детальное управление обработкой мультимодального зрения с помощью параметра media_resolution . Параметр media_resolution определяет максимальное количество токенов, выделяемых на каждое входное изображение или видеокадр. Более высокое разрешение улучшает способность модели считывать мелкий текст или идентифицировать мелкие детали, но увеличивает использование токенов и задержку.

Для получения более подробной информации о параметре и о том, как он может влиять на вычисления токенов, см. руководство по разрешению медиаконтента .

Файлы изображений

Если вы вызываете функцию countTokens с текстовым и графическим полем ввода, она возвращает суммарное количество токенов только для текста и изображения во входных данных ( totalTokens ). Вы можете вызвать эту функцию перед вызовом generateContent , чтобы проверить размер ваших запросов. Вы также можете дополнительно вызвать countTokens отдельно для текста и файла.

Другой вариант — вызвать функцию generateContent , а затем использовать атрибут usageMetadata объекта response , чтобы получить следующее:

  • Отдельные подсчеты токенов для входных данных ( promptTokenCount ), кэшированного содержимого ( cachedContentTokenCount ) и выходных данных ( candidatesTokenCount ).
  • Количество токенов, используемых в процессе мышления ( thoughtsTokenCount )
  • Общее количество токенов как на входе, так и на выходе ( 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);
count_tokens.js

Пример, предоставляющий изображение в виде встроенных данных:

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

Видео- или аудиофайлы

Аудио- и видеоматериалы конвертируются в токены по следующим фиксированным курсам:

  • Видео: 263 токена в секунду
  • Аудио: 32 токена в секунду

Если вы вызываете countTokens с текстовым и видео/аудио входными данными, он возвращает суммарное количество токенов только для текста и видео/аудиофайла во входных данных ( totalTokens ). Вы можете вызвать этот метод перед вызовом generateContent , чтобы проверить размер ваших запросов. Вы также можете дополнительно вызвать countTokens для текста и файла по отдельности.

Другой вариант — вызвать функцию generateContent , а затем использовать атрибут usageMetadata объекта response , чтобы получить следующее:

  • Отдельные подсчеты токенов для входных данных ( promptTokenCount ), кэшированного содержимого ( cachedContentTokenCount ) и выходных данных ( candidatesTokenCount ).
  • Количество токенов, используемых в процессе мышления ( thoughtsTokenCount )
  • Общее количество токенов как на входе, так и на выходе ( 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

Системные инструкции и инструменты

Системные инструкции и инструменты также учитываются в общем количестве токенов для ввода.

При использовании системных инструкций количество totalTokens увеличивается, отражая добавление systemInstruction .

При использовании вызовов функций количество totalTokens увеличивается, отражая добавление tools .