Veo 3.1 è arrivato! Scopri di più sul nuovo modello e sulle sue funzionalità nel post del blog e nella documentazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Comprendi e conteggia i token

Gemini e altri modelli di AI generativa elaborano input e output con una granularità chiamata token.

Per i modelli Gemini, un token equivale a circa 4 caratteri. 100 token equivalgono a circa 60-80 parole in inglese.

Informazioni sui token

I token possono essere singoli caratteri come z o intere parole come cat. Le parole lunghe vengono suddivise in più token. L'insieme di tutti i token utilizzati dal modello è chiamato vocabolario e il processo di suddivisione del testo in token è chiamato tokenizzazione.

Quando la fatturazione è abilitata, il costo di una chiamata all'API Gemini è determinato in parte dal numero di token di input e output, quindi sapere come contare i token può essere utile.

Prova a conteggiare i token in Colab

Puoi provare a conteggiare i token utilizzando Colab.

Visualizza su ai.google.dev

Prova un notebook Colab

Visualizza il blocco note su GitHub

Finestre contestuali

I modelli disponibili tramite l'API Gemini hanno finestre contestuali misurate in token. La finestra contestuale definisce la quantità di input che puoi fornire e la quantità di output che il modello può generare. Puoi determinare le dimensioni della finestra contestuale chiamando l'endpoint getModels o consultando la documentazione sui modelli.

Nell'esempio seguente, puoi notare che il modello gemini-1.5-flash ha un limite di input di circa 1.000.000 di token e un limite di output di circa 8000 token, il che significa che una finestra contestuale è di 1.000.000 di token.

from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-2.0-flash")
print(f"{model_info.input_token_limit=}")
print(f"{model_info.output_token_limit=}")
# ( e.g., input_token_limit=30720, output_token_limit=2048 )count_tokens.py

Contare i token

Tutti gli input e gli output dell'API Gemini sono tokenizzati, inclusi testo, file di immagini e altre modalità non testuali.

Puoi contare i token nei seguenti modi:

Chiama count_tokens con l'input della richiesta.
Questo valore restituisce il numero totale di token solo nell'input. Puoi effettuare questa chiamata prima di inviare l'input al modello per verificare le dimensioni delle tue richieste.
Utilizza l'attributo usage_metadata sull'oggetto response dopo aver chiamato generate_content.
Restituisce il numero totale di token sia nell'input che nell'output: total_token_count.
Restituisce anche il conteggio dei token di input e output separatamente: prompt_token_count (token di input) e candidates_token_count (token di output).

Se utilizzi un modello di pensiero come quelli 2.5, i token utilizzati durante il processo di pensiero vengono restituiti in thoughts_token_count. Se utilizzi la memorizzazione nella cache del contesto, il conteggio dei token memorizzati nella cache sarà in cached_content_token_count.

Contare i token di testo

Se chiami count_tokens con un input solo di testo, restituisce il conteggio dei token del testo nell'input solo (total_tokens). Puoi effettuare questa chiamata prima di chiamare generate_content per controllare le dimensioni delle tue richieste.

Un'altra opzione è chiamare generate_content e poi utilizzare l'attributo usage_metadata nell'oggetto response per ottenere quanto segue:

I conteggi separati dei token dell'input (prompt_token_count), dei contenuti memorizzati nella cache (cached_content_token_count) e dell'output (candidates_token_count)
Il conteggio dei token per il processo di pensiero (thoughts_token_count)
Il numero totale di token sia nell'input che nell'output (total_token_count).

from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

# Count tokens using the new client method.
total_tokens = client.models.count_tokens(
    model="gemini-2.0-flash", contents=prompt
)
print("total_tokens: ", total_tokens)
# ( e.g., total_tokens: 10 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=prompt
)

# The usage_metadata provides detailed token counts.
print(response.usage_metadata)
# ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )count_tokens.py

Contare i token multi-turno (chat)

Se chiami count_tokens con la cronologia della chat, viene restituito il conteggio totale dei token del testo di ogni ruolo nella chat (total_tokens).

Un'altra opzione è chiamare send_message e poi utilizzare l'attributo usage_metadata nell'oggetto response per ottenere quanto segue:

I conteggi separati dei token dell'input (prompt_token_count), dei contenuti memorizzati nella cache (cached_content_token_count) e dell'output (candidates_token_count)
Il conteggio dei token per il processo di pensiero (thoughts_token_count)
Il numero totale di token sia nell'input che nell'output (total_token_count).

Per capire quanto sarà grande il tuo prossimo turno conversazionale, devi aggiungerlo alla cronologia quando chiami count_tokens.

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-2.0-flash",
    history=[
        types.Content(
            role="user", parts=[types.Part(text="Hi my name is Bob")]
        ),
        types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
    ],
)
# Count tokens for the chat history.
print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=chat.get_history()
    )
)
# ( e.g., total_tokens: 10 )

response = chat.send_message(
    message="In one sentence, explain how a computer works to a young child."
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 25, candidates_token_count: 21, total_token_count: 46 )

# You can count tokens for the combined history and a new message.
extra = types.UserContent(
    parts=[
        types.Part(
            text="What is the meaning of life?",
        )
    ]
)
history = chat.get_history()
history.append(extra)
print(client.models.count_tokens(model="gemini-2.0-flash", contents=history))
# ( e.g., total_tokens: 56 )count_tokens.py

Contare i token multimodali

Tutti gli input dell'API Gemini vengono tokenizzati, inclusi testo, file immagine e altre modalità non testuali. Tieni presente i seguenti punti chiave di alto livello sulla tokenizzazione dell'input multimodale durante l'elaborazione da parte dell'API Gemini:

Con Gemini 2.0, gli input di immagini con entrambe le dimensioni <=384 pixel vengono conteggiati come 258 token. Le immagini più grandi in una o entrambe le dimensioni vengono ritagliate e scalate in base alle necessità in riquadri di 768 x 768 pixel, ognuno dei quali viene conteggiato come 258 token. Prima di Gemini 2.0, le immagini utilizzavano 258 token fissi.
I file video e audio vengono convertiti in token alle seguenti tariffe fisse: video a 263 token al secondo e audio a 32 token al secondo.

File immagine

Se chiami count_tokens con un input di testo e immagine, restituisce il conteggio dei token combinato del testo e dell'immagine solo nell'input (total_tokens). Puoi effettuare questa chiamata prima di chiamare generate_content per controllare le dimensioni delle tue richieste. Se vuoi, puoi anche chiamare count_tokens sul testo e sul file separatamente.

Un'altra opzione è chiamare generate_content e poi utilizzare l'attributo usage_metadata nell'oggetto response per ottenere quanto segue:

I conteggi separati dei token dell'input (prompt_token_count), dei contenuti memorizzati nella cache (cached_content_token_count) e dell'output (candidates_token_count)
Il conteggio dei token per il processo di pensiero (thoughts_token_count)
Il numero totale di token sia nell'input che nell'output (total_token_count).

Esempio che utilizza un'immagine caricata dall'API File:

from google import genai

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = client.files.upload(file=media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_image_file]
    )
)
# ( e.g., total_tokens: 263 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 264, candidates_token_count: 80, total_token_count: 345 )count_tokens.py

Esempio che fornisce l'immagine come dati in linea:

from google import genai
import PIL.Image

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")

# Count tokens for combined text and inline image.
print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_image_file]
    )
)
# ( e.g., total_tokens: 263 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 264, candidates_token_count: 80, total_token_count: 345 )count_tokens.py

File video o audio

Audio e video vengono convertiti in token alle seguenti tariffe fisse:

Video: 263 token al secondo
Audio: 32 token al secondo

Se chiami count_tokens con un input di testo e video/audio, restituisce il conteggio dei token combinato del testo e del file video/audio solo nell'input (total_tokens). Puoi effettuare questa chiamata prima di chiamare generate_content per controllare le dimensioni delle tue richieste. Puoi anche chiamare facoltativamente count_tokens sul testo e sul file separatamente.

Un'altra opzione è chiamare generate_content e poi utilizzare l'attributo usage_metadata nell'oggetto response per ottenere quanto segue:

I conteggi separati dei token dell'input (prompt_token_count), dei contenuti memorizzati nella cache (cached_content_token_count) e dell'output (candidates_token_count)
Il conteggio dei token per il processo di pensiero (thoughts_token_count)
Il numero totale di token sia nell'input che nell'output (total_token_count).

from google import genai
import time

client = genai.Client()
prompt = "Tell me about this video"
your_file = client.files.upload(file=media / "Big_Buck_Bunny.mp4")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not your_file.state or your_file.state.name != "ACTIVE":
    print("Processing video...")
    print("File state:", your_file.state)
    time.sleep(5)
    your_file = client.files.get(name=your_file.name)

print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_file]
    )
)
# ( e.g., total_tokens: 300 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 301, candidates_token_count: 60, total_token_count: 361 )count_tokens.py

Istruzioni e strumenti di sistema

Anche le istruzioni e gli strumenti di sistema vengono conteggiati nel conteggio totale dei token per l'input.

Se utilizzi le istruzioni di sistema, il conteggio di total_tokens aumenta per riflettere l'aggiunta di system_instruction.

Se utilizzi la chiamata di funzione, il conteggio di total_tokens aumenta per riflettere l'aggiunta di tools.