GoogleGenAITokenCounter

GoogleGenAITokenCounter는 Google Gen AI SDK의 countTokens 엔드포인트를 사용해 특정 Gemini 모델에 대한 ChatMessage 객체와 선택적 tool 스키마의 입력 토큰을 세요. 이 엔드포인트는 응답을 생성하지 않고 개수만 반환하므로 생성 비용이 들지 않아요.

출처: 문서

본문

Import path: haystack_integrations.token_counters.google_genai.GoogleGenAITokenCounter
필수 init 변수: model — 개수를 셀 Gemini 모델
API reference: Google GenAI
패키지명: google-genai-haystack

원격 API를 호출하므로 Google 자격 증명이 필요하고 매 개수마다 네트워크 지연이 더해져요. Gemini 모델에 대한 모델별 개수가 필요할 때 사용하세요. 로컬 추정에는 ApproximateTokenCounter 또는 TiktokenCounter를 사용하세요.

Installation

pip install google-genai-haystack

Usage

토큰 개수는 모델별로 다르므로, 생성에 사용하려는 모델을 전달하세요:

from haystack.dataclasses import ChatMessage
from haystack_integrations.token_counters.google_genai import GoogleGenAITokenCounter

messages = [
    ChatMessage.from_system("You are a helpful assistant."),
    ChatMessage.from_user("Explain retrieval-augmented generation."),
]
counter = GoogleGenAITokenCounter(model="gemini-3.8-flash")
token_count = counter.count(messages)
print(token_count)

기본적으로 이 카운터는 Gemini Developer API를 사용하고 GOOGLE_API_KEY 또는 GEMINI_API_KEY 환경 변수에서 API 키를 읽어요. Haystack Secret을 명시적으로 전달하거나, 기본 클라이언트의 timeout과 max_retries를 설정하거나, api="vertex"로 Vertex AI를 지정할 수도 있어요:

counter = GoogleGenAITokenCounter(
    model="gemini-3.8-flash",
    api="vertex",
    vertex_ai_project="my-project",
    vertex_ai_location="us-central1",
)

tool 스키마가 소비하는 컨텍스트를 포함하려면 count()에 tool을 전달하세요:

token_count = counter.count(messages, tools=[search_tool])

카운터는 count()를 처음 호출할 때 API 클라이언트를 만들어요. 애플리케이션 시작 시점에 만들려면 warm_up()을 명시적으로 호출하세요. 카운터 사용이 끝나면 close()를 호출해 클라이언트의 HTTP 리소스를 해제해요:

counter.warm_up()
...
counter.close()

Gemini Developer API versus Vertex AI

Google Gen AI SDK는 클라이언트가 Vertex AI를 대상으로 할 때만 countTokens에서 system instruction과 tool 스키마를 받아들여요. Gemini Developer API에서는 앞선 system 메시지가 사용자 턴으로 측정되어 정확한 개수가 아니라 가까운 근사치이며, tool을 전달하면 ValueError가 발생해요. system 프롬프트나 tool 스키마에 대한 정확한 개수가 필요하면 api="vertex"를 사용하세요.

Non-text content

Gemini는 이미지와 파일을 요청의 일부로 세므로, 카운터는 평면 추정 대신 그것들을 측정해요. GoogleGenAIChatGenerator와 같은 콘텐츠 유형을 지원해요: PNG, JPEG, WebP, HEIC, HEIF 이미지, 그리고 MIME 타입이 설정된 파일 — 둘 다 사용자 메시지에서만. 다른 이미지 MIME 타입은 추정 대신 에러를 발생시켜요.

Use with compaction

카운터를 CompactionHook에 전달하면 Geminin이 사용하는 것과 같은 토크나이저로 Agent의 대화 크기를 측정할 수 있어요:

from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor

compaction_hook = CompactionHook(
    compactor=SlidingWindowCompactor(),
    context_window=1_000_000,
    token_counter=GoogleGenAITokenCounter(model="gemini-3.8-flash", api="vertex"),
)

훅이 Agent의 매 스텝마다 메시지를 세므로 각 압축 확인마다 API 왕복이 든다는 점을 기억하세요. 훅은 또한 Agent의 tool을 카운터에 전달하므로, Agent에 tool이 있으면 api="vertex"를 사용하세요.

GoogleGenAITokenCounter