API de CountTokens

La API de CountTokens calcula la cantidad de tokens de entrada antes de enviar una solicitud a la API de Gemini.

Usa la API de CountTokens para evitar que las solicitudes excedan la ventana de contexto del modelo y estimar los costos potenciales según los caracteres facturables.

La API de CountTokens puede usar el mismo parámetro contents que las solicitudes de inferencia de la API de Gemini.

Modelos compatibles:

Modelo	Código
Gemini 1.5 Flash	gemini-1.5-flash-002 gemini-1.5-flash-001 gemini-1.5-flash-preview-0514
Gemini 1.5 Pro	gemini-1.5-pro-002 gemini-1.5-pro-001 gemini-1.5-pro-preview-0514
Gemini 1.0 Pro Vision	gemini-1.0-pro-vision gemini-1.0-pro-vision-001
Gemini 1.0 Pro	gemini-1.0-pro gemini-1.0-pro-001 gemini-1.0-pro-002
Gemini Experimental	gemini-experimental

Limitaciones:

gemini-1.0-pro-vision-001 y gemini-1.0-ultra-vision-001 usan una cantidad fija de tokens para las entradas de video.

Ejemplo de sintaxis

La sintaxis para enviar una solicitud de recuento de tokens.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:countTokens \
-d '{
  "contents": [{
    ...
  }],
  "system_instruction": {
  "role": "...",
  "parts": [{
      ...
    }],
  "tools": [{
      "function_declarations": [{
        ...
      }]
    }],
  }
}'

Python

gemini_model = GenerativeModel(MODEL_ID)
model_response = gemini_model.count_tokens([...])

Lista de parámetros

Esta clase consta de dos propiedades principales: role y parts. La propiedad role denota la persona que produce el contenido, mientras que la propiedad parts contiene varios elementos, cada uno de los cuales representa un segmento de datos dentro de un mensaje.

Parámetros
role	Opcional: string La identidad de la entidad que crea el mensaje. Establece la cadena en uno de los siguientes valores: user: indica que el mensaje lo envía una persona real. Por ejemplo, un mensaje generado por el usuario. model: indica que el modelo genera el mensaje. El valor model se usa para insertar mensajes del modelo en la conversación durante las conversaciones de varios turnos. En el caso de las conversaciones que no tengan varios turnos, este campo se puede dejar en blanco o sin configurar.
parts	part Una lista de partes ordenadas que conforman un solo mensaje. Es posible que las diferentes partes tengan distintos tipos de MIME de IANA.

Part

Un tipo de datos que contiene contenido multimedia que forma parte de un mensaje Content de varias partes.

Parámetros
text	Opcional: string Un mensaje de texto o un fragmento de código.
inline_data	Opcional: Blob Datos intercalados en bytes sin procesar.
file_data	Opcional: FileData Datos almacenados en un archivo.

Blob

BLOB de contenido. Si es posible, envía como texto en lugar de bytes sin procesar.

Parámetros
mime_type	string Tipo de MIME de IANA de los datos.
data	bytes Bytes sin procesar.

FileData

Los datos basados en el URI.

Parámetros
mime_type	string Tipo de MIME de IANA de los datos.
file_uri	string El URI de Cloud Storage para el archivo que almacena los datos.

system_instruction

Este campo es para el system_instructions proporcionado por el usuario. Es igual a contents, pero con una compatibilidad limitada de los tipos de contenido.

Parámetros
role	string Tipo de MIME de IANA de los datos. Este campo se ignora de forma interna.
parts	Part Solo texto. Las instrucciones que los usuarios desean pasar al modelo.

FunctionDeclaration

Una representación estructurada de una declaración de función según lo definido por la especificación de OpenAPI 3.0 que representa una función para la que el modelo puede generar entradas JSON.

Parámetros
name	string El nombre de la función a la que se llamará.
description	Opcional: string Descripción y propósito de la función.
parameters	Opcional: Schema Describe los parámetros de la función en el formato de objeto de esquema JSON de OpenAPI: especificación de OpenAPI 3.0.
response	Opcional: Schema Describe el resultado de la función en el formato de objeto de esquema JSON de OpenAPI: especificación de OpenAPI 3.0.

Ejemplos

Obtén el recuento de tokens a partir de un mensaje de texto

En este ejemplo, se cuentan los tokens de un solo mensaje de texto:

REST

Para obtener el recuento de tokens y la cantidad de caracteres facturables de un mensaje mediante la API de Vertex AI, envía una solicitud POST al extremo del modelo del publicador.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• LOCATION: La región para procesar la solicitud. Las opciones disponibles incluyen las siguientes:

  Haz clic para expandir una lista parcial de regiones disponibles

  • us-central1
  • us-west4
  • northamerica-northeast1
  • us-east4
  • us-west1
  • asia-northeast3
  • asia-southeast1
  • asia-northeast1
• PROJECT_ID: El ID del proyecto.
• MODEL_ID: el ID del modelo multimodal que deseas usar.
• ROLE: El rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en casos de uso de un solo turno. Los valores aceptables son los siguientes:
  • USER: especifica el contenido que envías.
• TEXT: Las instrucciones de texto que se incluirán en el mensaje.
• NAME: el nombre de la función a la que se llamará.
• DESCRIPTION: la descripción y el propósito de la función.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens

Cuerpo JSON de la solicitud:

{
  "contents": [{
    "role": "ROLE",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "system_instruction": {
    "role": "ROLE",
    "parts": [{
      "text": "TEXT"
    }]
  }
  "tools": [{
    "function_declarations": [
      {
        "name": "NAME",
        "description": "DESCRIPTION",
        "parameters": {
          "type": "OBJECT",
          "properties": {
            "location": {
              "type": "TYPE",
              "description": "DESCRIPTION"
            }
          },
          "required": [
            "location"
          ]
        }
      }
    ]
  }]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens"

PowerShell

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Respuesta

{ "totalTokens": 43 }

Python

import vertexai
from vertexai.generative_models import GenerativeModel

# TODO (developer): update project_id
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-1.5-flash-002")

prompt = "Why is the sky blue?"
# Prompt tokens count
response = model.count_tokens(prompt)
print(f"Prompt Token Count: {response.total_tokens}")
print(f"Prompt Character Count: {response.total_billable_characters}")

# Send text to Gemini
response = model.generate_content(prompt)

# Response tokens count
usage_metadata = response.usage_metadata
print(f"Prompt Token Count: {usage_metadata.prompt_token_count}")
print(f"Candidates Token Count: {usage_metadata.candidates_token_count}")
print(f"Total Token Count: {usage_metadata.total_token_count}")

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function countTokens(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  const req = {
    contents: [{role: 'user', parts: [{text: 'How are you doing today?'}]}],
  };

  // Prompt tokens count
  const countTokensResp = await generativeModel.countTokens(req);
  console.log('Prompt tokens count: ', countTokensResp);

  // Send text to gemini
  const result = await generativeModel.generateContent(req);

  // Response tokens count
  const usageMetadata = result.response.usageMetadata;
  console.log('Response tokens count: ', usageMetadata);
}

Java

import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.CountTokensResponse;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import java.io.IOException;

public class GetTokenCount {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-google-cloud-project-id";
    String location = "us-central1";
    String modelName = "gemini-1.5-flash-001";

    getTokenCount(projectId, location, modelName);
  }

  // Gets the number of tokens for the prompt and the model's response.
  public static int getTokenCount(String projectId, String location, String modelName)
      throws IOException {
    // 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 (VertexAI vertexAI = new VertexAI(projectId, location)) {
      GenerativeModel model = new GenerativeModel(modelName, vertexAI);

      String textPrompt = "Why is the sky blue?";
      CountTokensResponse response = model.countTokens(textPrompt);

      int promptTokenCount = response.getTotalTokens();
      int promptCharCount = response.getTotalBillableCharacters();

      System.out.println("Prompt token Count: " + promptTokenCount);
      System.out.println("Prompt billable character count: " + promptCharCount);

      GenerateContentResponse contentResponse = model.generateContent(textPrompt);

      int tokenCount = contentResponse.getUsageMetadata().getPromptTokenCount();
      int candidateTokenCount = contentResponse.getUsageMetadata().getCandidatesTokenCount();
      int totalTokenCount = contentResponse.getUsageMetadata().getTotalTokenCount();

      System.out.println("Prompt token Count: " + tokenCount);
      System.out.println("Candidate Token Count: " + candidateTokenCount);
      System.out.println("Total token Count: " + totalTokenCount);

      return promptTokenCount;
    }
  }
}

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/vertexai/genai"
)

// countTokens returns the number of tokens for this prompt.
func countTokens(w io.Writer, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.5-flash-001"

	ctx := context.Background()
	prompt := genai.Text("Why is the sky blue?")

	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)

	resp, err := model.CountTokens(ctx, prompt)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Number of tokens for the prompt: %d\n", resp.TotalTokens)

	resp2, err := model.GenerateContent(ctx, prompt)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Number of tokens for the prompt: %d\n", resp2.UsageMetadata.PromptTokenCount)
	fmt.Fprintf(w, "Number of tokens for the candidates: %d\n", resp2.UsageMetadata.CandidatesTokenCount)
	fmt.Fprintf(w, "Total number of tokens: %d\n", resp2.UsageMetadata.TotalTokenCount)

	return nil
}

Obtén el recuento de tokens a partir de un mensaje de contenido multimedia

En este ejemplo, se cuentan los tokens de un mensaje que usa varios tipos de medios.

REST

Para obtener el recuento de tokens y la cantidad de caracteres facturables de un mensaje mediante la API de Vertex AI, envía una solicitud POST al extremo del modelo del publicador.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• LOCATION: La región para procesar la solicitud. Las opciones disponibles incluyen las siguientes:

  Haz clic para expandir una lista parcial de regiones disponibles

  • us-central1
  • us-west4
  • northamerica-northeast1
  • us-east4
  • us-west1
  • asia-northeast3
  • asia-southeast1
  • asia-northeast1
• PROJECT_ID: El ID del proyecto.
• MODEL_ID: el ID del modelo multimodal que deseas usar.
• ROLE: El rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en casos de uso de un solo turno. Los valores aceptables son los siguientes:
  • USER: especifica el contenido que envías.
• TEXT: Las instrucciones de texto que se incluirán en el mensaje.
• FILE_URI: Es el URI o la URL del archivo que se incluirá en la instrucción. Los valores aceptables son los siguientes:
  • URI del bucket de Cloud Storage: El objeto debe poder leerse de forma pública o residir en el mismo proyecto de Google Cloud que envía la solicitud.
  • URL HTTP: La URL del archivo debe ser legible públicamente. Puedes especificar un archivo de video y hasta 10 archivos de imagen por solicitud. Los archivos de audio y los documentos no pueden superar los 15 MB.
  • URL del video de YouTube: El video de YouTube debe ser propiedad de la cuenta que usaste para acceder a la consola de Google Cloud o ser público. Solo se admite una URL de video de YouTube por solicitud.

  Cuando especifiques un fileURI, también debes especificar el tipo de medio (mimeType) del archivo.

• MIME_TYPE El tipo de medio del archivo especificado en los campos data o fileUri. Los valores aceptables son los siguientes:

  Haz clic para expandir los tipos de MIME.

  • application/pdf
  • audio/mpeg
  • audio/mp3
  • audio/wav
  • image/png
  • image/jpeg
  • image/webp
  • text/plain
  • video/mov
  • video/mpeg
  • video/mp4
  • video/mpg
  • video/avi
  • video/wmv
  • video/mpegps
  • video/flv

HTTP method and URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens

Cuerpo JSON de la solicitud:

{
  "contents": [{
    "role": "ROLE",
    "parts": [
      {
        "file_data": {
          "file_uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT
      }
    ]
  }]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens"

PowerShell

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Respuesta

{ "totalTokens": 43 }

Python

import vertexai
from vertexai.generative_models import GenerativeModel, Part

# TODO (developer): update project_id
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-1.5-flash-002")

contents = [
    Part.from_uri(
        "gs://cloud-samples-data/generative-ai/video/pixel8.mp4",
        mime_type="video/mp4",
    ),
    "Provide a description of the video.",
]

# Prompt tokens count
response = model.count_tokens(contents)
print(f"Prompt Token Count: {response.total_tokens}")
print(f"Prompt Character Count: {response.total_billable_characters}")

# Send text to Gemini
response = model.generate_content(contents)
usage_metadata = response.usage_metadata

# Response tokens count
print(f"Prompt Token Count: {usage_metadata.prompt_token_count}")
print(f"Candidates Token Count: {usage_metadata.candidates_token_count}")
print(f"Total Token Count: {usage_metadata.total_token_count}")

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function countTokens(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  const req = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            file_data: {
              file_uri:
                'gs://cloud-samples-data/generative-ai/video/pixel8.mp4',
              mime_type: 'video/mp4',
            },
          },
          {text: 'Provide a description of the video.'},
        ],
      },
    ],
  };

  const countTokensResp = await generativeModel.countTokens(req);
  console.log('Prompt Token Count:', countTokensResp.totalTokens);
  console.log(
    'Prompt Character Count:',
    countTokensResp.totalBillableCharacters
  );

  // Sent text to Gemini
  const result = await generativeModel.generateContent(req);
  const usageMetadata = result.response.usageMetadata;

  console.log('Prompt Token Count:', usageMetadata.promptTokenCount);
  console.log('Candidates Token Count:', usageMetadata.candidatesTokenCount);
  console.log('Total Token Count:', usageMetadata.totalTokenCount);
}

Java

import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.Content;
import com.google.cloud.vertexai.api.CountTokensResponse;
import com.google.cloud.vertexai.generativeai.ContentMaker;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.PartMaker;
import java.io.IOException;

public class GetMediaTokenCount {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-google-cloud-project-id";
    String location = "us-central1";
    String modelName = "gemini-1.5-flash-001";

    getMediaTokenCount(projectId, location, modelName);
  }

  // Gets the number of tokens for the prompt with text and video and the model's response.
  public static int getMediaTokenCount(String projectId, String location, String modelName)
      throws IOException {
    // 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 (VertexAI vertexAI = new VertexAI(projectId, location)) {
      GenerativeModel model = new GenerativeModel(modelName, vertexAI);

      Content content = ContentMaker.fromMultiModalData(
          "Provide a description of the video.",
          PartMaker.fromMimeTypeAndData(
              "video/mp4", "gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
      );

      CountTokensResponse response = model.countTokens(content);

      int tokenCount = response.getTotalTokens();
      System.out.println("Token count: " + tokenCount);

      return tokenCount;
    }
  }
}

Go

import (
	"context"
	"fmt"
	"io"
	"mime"
	"path/filepath"

	"cloud.google.com/go/vertexai/genai"
)

// countTokensMultimodal finds the number of tokens for a multimodal prompt (video+text), and writes to w. Then,
// it calls the model with the multimodal prompt and writes token counts from the response metadata to w.
//
// video is a Google Cloud Storage path starting with "gs://"
func countTokensMultimodal(w io.Writer, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.5-flash-001"
	prompt := "Provide a description of the video."
	video := "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"

	ctx := context.Background()

	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)

	part1 := genai.Text(prompt)

	// Given a video file URL, prepare video file as genai.Part
	part2 := genai.FileData{
		MIMEType: mime.TypeByExtension(filepath.Ext(video)),
		FileURI:  video,
	}

	// Finds the total number of tokens for the 2 parts (text, video) of the multimodal prompt,
	// before actually calling the model for inference.
	resp, err := model.CountTokens(ctx, part1, part2)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Number of tokens for the multimodal video prompt: %d\n", resp.TotalTokens)

	res, err := model.GenerateContent(ctx, part1, part2)
	if err != nil {
		return fmt.Errorf("unable to generate contents: %w", err)
	}

	// The token counts are also provided in the model response metadata, after inference.
	fmt.Fprintln(w, "\nModel response")
	md := res.UsageMetadata
	fmt.Fprintf(w, "Prompt Token Count: %d\n", md.PromptTokenCount)
	fmt.Fprintf(w, "Candidates Token Count: %d\n", md.CandidatesTokenCount)
	fmt.Fprintf(w, "Total Token Count: %d\n", md.TotalTokenCount)

	return nil
}

¿Qué sigue?

• Obtén más información sobre la API de Gemini.