토큰 이해 및 계산

Gemini 및 기타 생성형 AI 모델은 토큰이라는 세부사항으로 입력과 출력을 처리합니다.

Gemini 모델의 경우 토큰은 약 4자에 해당합니다. 토큰 100개는 영어 단어 약 60~80개에 해당합니다.

토큰 정보

토큰은 단일 문자(예: z) 또는 전체 단어(예: cat)일 수 있습니다. 긴 단어는 여러 토큰으로 나뉩니다. 모델에서 사용하는 모든 토큰 집합을 어휘라고 하며, 텍스트를 토큰으로 분할하는 프로세스를 토큰화라고 합니다.

결제가 사용 설정된 경우 Gemini API 호출 비용은 입력 및 출력 토큰 수에 따라 결정되므로 토큰 수를 세는 방법을 알아두면 유용합니다.

Colab에서 토큰 수 계산해 보기

Colab을 사용하여 토큰 수를 세어 볼 수 있습니다.

ai.google.dev에서 보기

Colab 노트북 사용해 보기

GitHub에서 노트북 보기

컨텍스트 윈도우

Gemini API를 통해 사용할 수 있는 모델에는 토큰으로 측정되는 컨텍스트 윈도우가 있습니다. 컨텍스트 윈도우는 제공할 수 있는 입력의 양과 모델이 생성할 수 있는 출력의 양을 정의합니다. getModels 엔드포인트를 호출하거나 모델 문서를 확인하여 컨텍스트 윈도우의 크기를 확인할 수 있습니다.

다음 예에서 gemini-1.5-flash 모델의 입력 한도는 약 1,000,000개 토큰이고 출력 한도는 약 8,000개 토큰입니다. 즉, 컨텍스트 윈도우는 1,000,000개 토큰입니다.

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

토큰 집계

텍스트, 이미지 파일, 기타 비텍스트 모달리티를 비롯한 Gemini API의 모든 입력과 출력은 토큰화됩니다.

다음과 같은 방법으로 토큰을 계산할 수 있습니다.

텍스트 토큰 수 계산

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

멀티턴 (채팅) 토큰 수 계산

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

멀티모달 토큰 수 계산

텍스트, 이미지 파일, 기타 텍스트가 아닌 형식을 비롯한 Gemini API의 모든 입력은 토큰화됩니다. Gemini API에서 처리하는 동안 멀티모달 입력의 토큰화에 관한 다음 상위 수준 주요 사항에 유의하세요.

Gemini 2.0에서는 두 치수가 모두 384픽셀 이하인 이미지 입력이 258개의 토큰으로 계산됩니다. 한쪽 또는 양쪽 크기가 더 큰 이미지는 필요에 따라 768x768픽셀 타일로 잘리고 크기가 조정되며, 각 타일은 258개의 토큰으로 계산됩니다. Gemini 2.0 이전에는 이미지가 고정된 258개의 토큰을 사용했습니다.
동영상 및 오디오 파일은 다음 고정 요율로 토큰으로 변환됩니다. 동영상은 초당 263개 토큰, 오디오는 초당 32개 토큰입니다.

이미지 파일

File API에서 업로드된 이미지를 사용하는 예:

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

이미지를 인라인 데이터로 제공하는 예:

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

동영상 또는 오디오 파일

오디오와 동영상은 각각 다음 고정된 비율로 토큰으로 변환됩니다.

동영상: 초당 토큰 263개
오디오: 초당 토큰 32개

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

시스템 안내 및 도구

시스템 안내와 도구도 입력의 총 토큰 수에 포함됩니다.

시스템 안내를 사용하면 system_instruction 추가를 반영하기 위해 total_tokens 수가 증가합니다.

함수 호출을 사용하는 경우 tools 추가를 반영하기 위해 total_tokens 수가 증가합니다.