Implementation:Arize ai Phoenix Legacy GoogleGenAIModel

Overview

GoogleGenAIModel is a legacy model wrapper in the phoenix-evals package that provides an interface for using Google Gemini models via the Google GenAI SDK. It extends BaseModel and supports both direct Google AI Studio access (via API key) and VertexAI access (via credentials/project). The wrapper features full async support, dynamic rate limiting, multimodal prompt processing (text, images, and audio), and structured token usage tracking including thinking tokens.

LLM_Evaluation Model_Integration

Description

The GoogleGenAIModel class is implemented as a Python dataclass that extends the abstract BaseModel. Key characteristics include:

• Dual-mode authentication: Supports both API key-based access (Google AI Studio) and VertexAI-based access via vertexai=True with project/location/credentials parameters.
• API key resolution: Checks for GOOGLE_API_KEY and GEMINI_API_KEY environment variables, prioritizing the former and logging a warning when both are set.
• Full async support: Natively implements both sync and async generation using self._client.models.generate_content() and self._client.aio.models.generate_content().
• Dynamic rate limiting: Uses a custom GoogleRateLimitError exception class; catches ServerError with HTTP status 429 from the Google SDK and re-raises to trigger rate limiter backoff.
• Multimodal support: Processes text, image (base64 and URL), and audio content parts. Validates image formats against {png, jpeg, webp, heic, heif} and audio formats against {wav, mp3, aiff, aac, ogg, flac}.
• Image URL downloading: Fetches images from URLs via urllib.request.urlopen() with a 30-second timeout, converting them to base64 for inline embedding.
• Function call extraction: Detects function call responses and serializes their arguments as JSON.
• Thinking token tracking: Usage extraction includes thoughts_token_count in completion tokens alongside candidates_token_count.

Usage

# Set the GOOGLE_API_KEY or GEMINI_API_KEY environment variable

from phoenix.evals.models import GoogleGenAIModel

# Basic usage with defaults (gemini-2.5-flash)
model = GoogleGenAIModel()

# Specify model and parameters
model = GoogleGenAIModel(
    model="gemini-2.5-pro",
    initial_rate_limit=10,
)

response = model("Explain how neural networks learn.")
print(response)

Code Reference

Source Location

Property	Value
Repository	Arize-ai/phoenix
File	packages/phoenix-evals/src/phoenix/evals/legacy/models/google_genai.py
Lines	332
Module	phoenix.evals.legacy.models.google_genai

Class Signature

@dataclass
class GoogleGenAIModel(BaseModel):
    model: str = "gemini-2.5-flash"
    vertexai: Optional[bool] = None
    api_key: Optional[str] = None
    credentials: Optional["Credentials"] = None
    project: Optional[str] = None
    location: Optional[str] = None
    initial_rate_limit: int = 5

Constructor Parameters

Parameter	Type	Default	Description
model	str	"gemini-2.5-flash"	The Gemini model name to use.
vertexai	Optional[bool]	None	When True, uses VertexAI backend instead of API key.
api_key	Optional[str]	None	Google API key; falls back to GOOGLE_API_KEY or GEMINI_API_KEY env vars.
credentials	Optional[Credentials]	None	Google auth credentials for VertexAI mode.
project	Optional[str]	None	GCP project ID for VertexAI mode.
location	Optional[str]	None	GCP location/region for VertexAI mode.
initial_rate_limit	int	5	Initial requests-per-second rate limit.

Key Methods

Method	Signature	Description
__post_init__	(self) -> None	Resolves API key, initializes client and rate limiter.
_init_client	(self) -> None	Creates the genai.Client in either VertexAI or API key mode.
_init_rate_limiter	(self) -> None	Configures rate limiter with custom GoogleRateLimitError.
_generate_with_extra	(self, prompt, instruction=None, **kwargs) -> Tuple[str, ExtraInfo]	Synchronous generation with system instruction support.
_async_generate_with_extra	async (self, prompt, instruction=None, **kwargs) -> Tuple[str, ExtraInfo]	Native async generation via _client.aio.models.generate_content().
_process_prompt	(self, prompt: MultimodalPrompt) -> List[Dict[str, Any]]	Converts multimodal prompt parts to Google GenAI content format.
_extract_text	(self, response: GenerateContentResponse) -> str	Extracts text or function call arguments from response.
_extract_usage	(self, usage_metadata) -> Optional[Usage]	Extracts token usage including thinking tokens.
_parse_output	(self, response: GenerateContentResponse) -> Tuple[str, ExtraInfo]	Combines text extraction and usage extraction.

Helper Functions

Function	Signature	Description
_get_env_api_key	() -> Optional[str]	Retrieves API key from GOOGLE_API_KEY or GEMINI_API_KEY environment variables.
_download_image_from_url	(url: str) -> bytes	Downloads image bytes from a URL with 30-second timeout.
_is_url	(url: str) -> bool	Checks if a string is a valid URL with scheme and netloc.

Helper Class

Class	Description
GoogleRateLimitError	Custom exception raised when a 429 status is received from the Google GenAI API, used as the rate limiter's trigger exception.

Supported Formats

Media Type	Supported Formats
Image	png, jpeg, webp, heic, heif
Audio	wav, mp3, aiff, aac, ogg, flac

Import

from phoenix.evals.models import GoogleGenAIModel

I/O Contract

Direction	Type	Description
Input	Union[str, MultimodalPrompt]	A text string or multimodal prompt with text, image, and/or audio parts.
Input (optional)	Optional[str]	A system instruction string passed via the instruction parameter.
Output	str	Generated text response, or JSON-serialized function call arguments.
Output (with extra)	Tuple[str, ExtraInfo]	Generated text paired with ExtraInfo containing optional Usage token counts.
Error	PhoenixUnsupportedImageFormat	Raised for unsupported image formats.
Error	PhoenixUnsupportedAudioFormat	Raised for unsupported audio formats.
Error	ImportError	Raised if google-genai package is not installed.

Usage Examples

Using with VertexAI

from phoenix.evals.models import GoogleGenAIModel

model = GoogleGenAIModel(
    vertexai=True,
    project="my-gcp-project",
    location="us-central1",
    model="gemini-2.5-pro",
)

response = model("Summarize the key points of reinforcement learning.")
print(response)

With System Instruction

from phoenix.evals.models import GoogleGenAIModel

model = GoogleGenAIModel(model="gemini-2.5-flash")
response = model(
    "What is the capital of France?",
    instruction="You are a geography expert. Be concise.",
)
print(response)

Multimodal Prompt with Image

from phoenix.evals.models import GoogleGenAIModel
from phoenix.evals.legacy.templates import MultimodalPrompt

model = GoogleGenAIModel(model="gemini-2.5-flash")
# Image can be provided as a URL or base64-encoded string
prompt = MultimodalPrompt.from_parts([
    {"type": "text", "content": "Describe this image."},
    {"type": "image", "content": "https://example.com/image.png"},
])

Related Pages

• Arize_ai_Phoenix_Legacy_BaseModel - Abstract base class that GoogleGenAIModel extends
• Arize_ai_Phoenix_Legacy_GeminiModel - Alternative Gemini wrapper using the VertexAI SDK directly
• Arize_ai_Phoenix_Legacy_VertexAIModel - Legacy VertexAI text/code generation wrapper (deprecated)
• Arize_ai_Phoenix_Legacy_OpenAIModel - OpenAI model wrapper (similar multimodal support pattern)
• Arize_ai_Phoenix_Legacy_AnthropicModel - Anthropic model wrapper