tessl/maven-dev-langchain4j--langchain4j-vertex-ai

LangChain4j integration for Google Vertex AI models including chat, language, embedding, image, and scoring capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Common Configuration

Name: tessl/maven-dev-langchain4j--langchain4j-vertex-ai
Author: tessl

Required Configuration Parameters

All models (except VertexAiScoringModel) require these builder parameters:

Builder endpoint(String endpoint);        // GCP API endpoint URL (required)
Builder project(String project);          // Google Cloud Project ID (required)
Builder location(String location);        // GCP region (required)
Builder publisher(String publisher);      // Model publisher, typically "google" (required)
Builder modelName(String modelName);      // Specific model name/version (required)

Optional Common Parameters

Builder maxRetries(Integer maxRetries);   // Retry attempts on API failure

Configuration Details

endpoint

Type: String (required)

Purpose: Google Cloud Platform API endpoint URL for Vertex AI.

Format varies by region:

US Central:       https://us-central1-aiplatform.googleapis.com/v1/
Europe West:      https://europe-west1-aiplatform.googleapis.com/v1/
Asia Northeast:   https://asia-northeast1-aiplatform.googleapis.com/v1/

Embedding models use different format:

us-central1-aiplatform.googleapis.com:443
europe-west1-aiplatform.googleapis.com:443

Pattern: https://{location}-aiplatform.googleapis.com/v1/ or {location}-aiplatform.googleapis.com:443

project

Type: String (required)

Purpose: Your Google Cloud Project ID (not project number).

Example: my-project-123 or production-ml-project

Finding your project ID:

Google Cloud Console: Top bar project selector
gcloud CLI: gcloud config get-value project
gcloud CLI: gcloud projects list

location

Type: String (required)

Purpose: Google Cloud Platform region where the model is hosted.

Common values:

us-central1       # Iowa, USA
us-east1          # South Carolina, USA
us-west1          # Oregon, USA
europe-west1      # Belgium
europe-west4      # Netherlands
asia-northeast1   # Tokyo, Japan
asia-southeast1   # Singapore

Notes:

Must match the endpoint location
Not all models available in all regions
Check Vertex AI regions for availability

publisher

Type: String (required)

Purpose: The organization that published the model.

Value: Almost always "google" for Vertex AI models.

Example:

.publisher("google")

modelName

Type: String (required)

Purpose: Specific model name and version to use.

Format: {model-name}@{version} or {model-name}

Chat Models:

chat-bison@001
chat-bison@002
gemini-pro
gemini-ultra

Language Models:

text-bison@001
text-bison@002
text-bison-32k

Embedding Models:

text-embedding-004
textembedding-gecko@001
textembedding-gecko@002
textembedding-gecko@003
text-multilingual-embedding-002
multimodalembedding

Image Models:

imagegeneration@006    # Imagen 3
imagegeneration@005    # Imagen 2
imagegeneration@002    # Imagen 1

Scoring Models:

semantic-ranker-512@latest

maxRetries

Type: Integer (optional)

Purpose: Maximum number of retry attempts for failed API calls.

Default: Varies by model type (typically 2-3)

Range: 0 or positive integer

Behavior:

Automatically retries on transient failures (network errors, rate limits)
Does not retry on non-retryable errors (invalid parameters, auth errors)
Implements exponential backoff between retries

Example:

.maxRetries(5)  // Retry up to 5 times on transient failures

Recommended values:

Development: 1-2 (fast failure)
Production: 3-5 (resilience)
Batch processing: 5-10 (maximize success)

Scoring Model Configuration

VertexAiScoringModel uses different required parameters:

Builder projectId(String projectId);         // GCP project ID (required)
Builder projectNumber(String projectNumber); // GCP project number (required)
Builder location(String location);           // GCP region (required)
Builder model(String model);                 // Ranking model name (required)

Key difference: Requires both projectId and projectNumber (12-digit number).

Finding project number:

gcloud projects describe PROJECT_ID --format="value(projectNumber)"

Or check Google Cloud Console project dashboard.

Configuration Examples

Minimal Configuration

VertexAiChatModel model = VertexAiChatModel.builder()
    .endpoint("https://us-central1-aiplatform.googleapis.com/v1/")
    .project("my-project")
    .location("us-central1")
    .publisher("google")
    .modelName("chat-bison@001")
    .build();

With Retry Configuration

VertexAiChatModel model = VertexAiChatModel.builder()
    .endpoint("https://us-central1-aiplatform.googleapis.com/v1/")
    .project("my-project")
    .location("us-central1")
    .publisher("google")
    .modelName("chat-bison@001")
    .maxRetries(5)
    .build();

Multi-Region Setup

String region = "europe-west1";
String endpoint = "https://" + region + "-aiplatform.googleapis.com/v1/";

VertexAiChatModel model = VertexAiChatModel.builder()
    .endpoint(endpoint)
    .project("my-project")
    .location(region)
    .publisher("google")
    .modelName("chat-bison@001")
    .build();

Environment-Based Configuration

String project = System.getenv("GCP_PROJECT_ID");
String location = System.getenv("GCP_LOCATION");
String endpoint = "https://" + location + "-aiplatform.googleapis.com/v1/";

VertexAiChatModel model = VertexAiChatModel.builder()
    .endpoint(endpoint)
    .project(project)
    .location(location)
    .publisher("google")
    .modelName("chat-bison@001")
    .build();

Error Handling

All models implement automatic retry logic for transient failures:

Network timeouts: Automatically retried
Rate limiting (429): Automatically retried with backoff
Server errors (5xx): Automatically retried
Client errors (4xx): Not retried (invalid request)
Auth errors (401/403): Not retried (configuration issue)

Configure retry behavior via maxRetries() parameter.

Best Practices

Use environment variables for project and location in production
Set appropriate maxRetries based on use case (higher for batch, lower for interactive)
Verify model availability in your chosen region before deploying
Use latest model versions (@latest or highest version number) for best quality
Cache builder configuration if creating many model instances
Validate configuration early in application startup, not at first use

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-vertex-ai@1.11.0

tessl/maven-dev-langchain4j--langchain4j-vertex-ai