Mostrar y contar tokens

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta página se explica cómo enumerar los tokens y sus IDs de un prompt, así como cómo obtener el número total de tokens de un prompt mediante el SDK de IA generativa de Google.

Tokens y la importancia de la lista y el recuento de tokens

Los modelos de IA generativa desglosan el texto y otros datos de una petición en unidades llamadas tokens para procesarlos. La forma en que se convierten los datos en tokens depende del tokenizador utilizado. Un token puede ser caracteres, palabras o frases.

Cada modelo tiene un número máximo de tokens que puede gestionar en una petición y una respuesta. Conocer el número de tokens de tu petición te permite saber si has superado este límite o no. Además, el recuento de tokens también devuelve los caracteres facturables de la petición, lo que te ayuda a estimar el coste.

La opción de listar tokens devuelve una lista de los tokens en los que se desglosa tu petición. Cada token de la lista está asociado a un ID de token, que te ayuda a solucionar problemas y analizar el comportamiento del modelo.

Modelos admitidos

En la siguiente tabla se muestran los modelos que admiten la lista y el recuento de tokens:

• Versión preliminar de Gemini 2.5 Flash Image (versión preliminar)
• Gemini 2.5 Flash-Lite
• Gemini 2.0 Flash con generación de imágenes (vista previa)
• Vertex AI Model Optimizer (experimental)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash
• Gemini 2.0 Flash-Lite

Obtener una lista de tokens e IDs de tokens de una petición

En el siguiente código de ejemplo se muestra cómo obtener una lista de tokens e IDs de tokens de una petición. La petición solo debe contener texto. No se admiten las peticiones multimodales.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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

Consulta cómo instalar o actualizar Go.

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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 obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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

Consulta cómo instalar o actualizar Java.

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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();
    }
  }
}

Obtener el recuento de tokens y los caracteres facturables de una petición

En el siguiente código de ejemplo se muestra cómo obtener el recuento de tokens y el número de caracteres facturables de una petición. Se admiten peticiones de solo texto y multimodales.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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

Consulta cómo instalar o actualizar Go.

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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 obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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

Consulta cómo instalar o actualizar Java.

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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();
    }
  }
}