Listar e contar tokens

Prévia

Este produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Esta página mostra como listar os tokens e os IDs deles de um comando e como conferir uma contagem total de tokens de um comando usando o SDK da IA generativa do Google.

Tokens e a importância da listagem e contagem de tokens

Os modelos de IA generativa dividem o texto e outros dados em um comando em unidades chamadas tokens para processamento. A maneira como os dados são convertidos em tokens depende do tokenizador usado. Um token pode ser composto por caracteres, palavras ou frases.

Cada modelo tem um número máximo de tokens que pode ser processado em um comando e uma resposta. Saber a contagem de tokens da solicitação permite saber se você excedeu esse limite ou não. Além disso, a contagem de tokens também retorna os caracteres faturáveis do comando, o que ajuda a estimar o custo.

O comando "List tokens" retorna uma lista dos tokens em que o comando é dividido. Cada token listado está associado a um ID de token, que ajuda você a realizar solucionar problemas e analisar o comportamento do modelo.

Modelos compatíveis

A tabela a seguir mostra os modelos compatíveis com a listagem e a contagem de tokens:

• Prévia da imagem do Gemini 2.5 Flash (pré-lançamento)
• Gemini 2.5 Flash-Lite
• Gemini 2.0 Flash com geração de imagens (pré-lançamento)
• Otimizador de modelos da Vertex AI (experimental)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash
• Gemini 2.0 Flash-Lite

Receber uma lista de tokens e IDs de token de um comando

O exemplo de código abaixo mostra como receber uma lista de tokens e IDs de token para um comando. A solicitação precisa conter apenas texto. Não há suporte para comandos multimodais.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.compute_tokens(
    model="gemini-2.5-flash",
    contents="What's the longest word in the English language?",
)

print(response)
# Example output:
# tokens_info=[TokensInfo(
#    role='user',
#    token_ids=[1841, 235303, 235256, 573, 32514, 2204, 575, 573, 4645, 5255, 235336],
#    tokens=[b'What', b"'", b's', b' the', b' longest', b' word', b' in', b' the', b' English', b' language', b'?']
#  )]

Go

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// computeWithTxt shows how to compute tokens with text input.
func computeWithTxt(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What's the longest word in the English language?"},
		},
			Role: "user"},
	}

	resp, err := client.Models.ComputeTokens(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	type tokenInfoDisplay struct {
		IDs    []int64  `json:"token_ids"`
		Tokens []string `json:"tokens"`
	}
	// See the documentation: https://pkg.go.dev/google.golang.org/genai#ComputeTokensResponse
	for _, instance := range resp.TokensInfo {
		display := tokenInfoDisplay{
			IDs:    instance.TokenIDs,
			Tokens: make([]string, len(instance.Tokens)),
		}
		for i, t := range instance.Tokens {
			display.Tokens[i] = string(t)
		}

		data, err := json.MarshalIndent(display, "", "  ")
		if err != nil {
			return fmt.Errorf("failed to marshal token info: %w", err)
		}
		fmt.Fprintln(w, string(data))
	}

	// Example response:
	// {
	// 	"ids": [
	// 		1841,
	// 		235303,
	// 		235256,
	//    ...
	// 	],
	// 	"values": [
	// 		"What",
	// 		"'",
	// 		"s",
	//    ...
	// 	]
	// }

	return nil
}

Node.js

Instalar

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function countTokens(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const ai = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
    httpOptions: {apiVersion: 'v1'},
  });

  const response = await ai.models.computeTokens({
    model: 'gemini-2.5-flash',
    contents: "What's the longest word in the English language?",
  });

  console.log(response);

  return response.tokensInfo;
}

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import com.google.genai.Client;
import com.google.genai.types.ComputeTokensResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.TokensInfo;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Optional;

public class CountTokensComputeWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    computeTokens(modelId);
  }

  // Computes tokens with text input
  public static Optional<List<TokensInfo>> computeTokens(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      ComputeTokensResponse response = client.models.computeTokens(
              modelId, "What's the longest word in the English language?", null);

      // Print TokensInfo
      response.tokensInfo().ifPresent(tokensInfoList -> {
        for (TokensInfo info : tokensInfoList) {
          info.role().ifPresent(role -> System.out.println("role: " + role));
          info.tokenIds().ifPresent(tokenIds -> System.out.println("tokenIds: " + tokenIds));
          // print tokens input as strings since they are in a form of byte array
          System.out.println("tokens: ");
          info.tokens().ifPresent(tokens ->
              tokens.forEach(token ->
                  System.out.println(new String(token, StandardCharsets.UTF_8))
              )
          );
        }
      });
      // Example response.tokensInfo()
      // role: user
      // tokenIds: [1841, 235303, 235256, 573, 32514, 2204, 575, 573, 4645, 5255, 235336]
      // tokens:
      // What
      // '
      // s
      // the
      return response.tokensInfo();
    }
  }
}

Receber a contagem de tokens e os caracteres faturáveis de um comando

O exemplo de código abaixo mostra como conferir a contagem de tokens e o número de caracteres faturáveis de um comando. Tanto os comandos somente de texto quanto os multimodais suporte.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))

prompt = "Why is the sky blue?"

# Send text to Gemini
response = client.models.generate_content(
    model="gemini-2.5-flash", contents=prompt
)

# Prompt and response tokens count
print(response.usage_metadata)

# Example output:
#  cached_content_token_count=None
#  candidates_token_count=311
#  prompt_token_count=6
#  total_token_count=317

Go

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateTextAndCount shows how to generate text and obtain token count metadata from the model response.
func generateTextAndCount(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "Why is the sky blue?"},
		},
			Role: "user"},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	usage, err := json.MarshalIndent(resp.UsageMetadata, "", "  ")
	if err != nil {
		return fmt.Errorf("failed to convert usage metadata to JSON: %w", err)
	}
	fmt.Fprintln(w, string(usage))

	// Example response:
	// {
	// 	 "candidatesTokenCount": 339,
	// 	 "promptTokenCount": 6,
	// 	 "totalTokenCount": 345
	// }

	return nil
}

Node.js

Instalar

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function countTokens(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const ai = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
    httpOptions: {apiVersion: 'v1'},
  });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Why is the sky blue?',
  });

  console.log(response.usageMetadata);

  return response.usageMetadata;
}

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GenerateContentResponseUsageMetadata;
import com.google.genai.types.HttpOptions;
import java.util.Optional;

public class CountTokensResponseWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    countTokens(modelId);
  }

  // Generates content response usage metadata that contains prompt and response token counts
  public static Optional<GenerateContentResponseUsageMetadata> countTokens(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      GenerateContentResponse response =
              client.models.generateContent(modelId, "Why is the sky blue?", null);

      response.usageMetadata().ifPresent(System.out::println);
      // Example response:
      // GenerateContentResponseUsageMetadata{cacheTokensDetails=Optional.empty,
      // cachedContentTokenCount=Optional.empty, candidatesTokenCount=Optional[569],
      // candidatesTokensDetails=Optional[[ModalityTokenCount{modality=Optional[TEXT],
      // tokenCount=Optional[569]}]], promptTokenCount=Optional[6],
      // promptTokensDetails=Optional[[ModalityTokenCount{modality=Optional[TEXT],
      // tokenCount=Optional[6]}]], thoughtsTokenCount=Optional[1132],
      // toolUsePromptTokenCount=Optional.empty, toolUsePromptTokensDetails=Optional.empty,
      // totalTokenCount=Optional[1707], trafficType=Optional[ON_DEMAND]}
      return response.usageMetadata();
    }
  }
}