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
api.mddocs/models/scoring/
Scoring Model API Reference
Class Definition
public class VertexAiScoringModel implements ScoringModel {
public Response<List<Double>> scoreAll(List<TextSegment> segments, String query);
public static Builder builder();
}Methods
/**
* Score multiple text segments against a query.
*
* @param segments List of text segments to score
* @param query The query string to score segments against
* @return Response containing list of relevance scores (one per segment)
*/
public Response<List<Double>> scoreAll(List<TextSegment> segments, String query);
/**
* Create a new builder for configuring a VertexAiScoringModel.
*
* @return A new Builder instance
*/
public static Builder builder();Constructor
/**
* Create a VertexAiScoringModel with explicit parameters.
*
* @param projectId Google Cloud Project ID
* @param projectNumber Google Cloud Project number
* @param location GCP region
* @param model Ranking model name
* @param titleMetadataKey Metadata key for document titles
*/
public VertexAiScoringModel(
String projectId,
String projectNumber,
String location,
String model,
String titleMetadataKey
);Builder Methods
/**
* Set the ranking model name.
*
* @param model The model name (e.g., "semantic-ranker-512@latest")
* @return This builder
*/
public Builder model(String model);
/**
* Set the Google Cloud Project ID.
*
* @param projectId The GCP project ID
* @return This builder
*/
public Builder projectId(String projectId);
/**
* Set the Google Cloud Project number.
*
* @param projectNumber The GCP project number (12-digit number)
* @return This builder
*/
public Builder projectNumber(String projectNumber);
/**
* Set the GCP region/location.
*
* @param location The region (e.g., "us-central1", "europe-west1")
* @return This builder
*/
public Builder location(String location);
/**
* Set the metadata key for document titles.
*
* @param titleMetadataKey The metadata key name (default: "title")
* @return This builder
*/
public Builder titleMetadataKey(String titleMetadataKey);
/**
* Build the VertexAiScoringModel instance.
*
* @return Configured VertexAiScoringModel instance
*/
public VertexAiScoringModel build();Parameter Details
projectId
- Type: String
- Required: Yes
- Description: Google Cloud Project ID (not project number)
- Example:
my-project-123
projectNumber
- Type: String
- Required: Yes
- Description: Google Cloud Project number (12-digit identifier)
- Example:
123456789012 - Find via:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
location
- Type: String
- Required: Yes
- Description: GCP region where ranking API is hosted
- Examples:
us-central1,europe-west1
model
- Type: String
- Required: Yes
- Description: Ranking model name
- Values:
semantic-ranker-512@latest
titleMetadataKey
- Type: String
- Required: No
- Default:
"title" - Description: Metadata key for document titles
- Note: Model uses titles for better relevance scoring when available
Response Type
Response<List<Double>>
public class Response<T> {
public T content();
public TokenUsage tokenUsage();
public FinishReason finishReason();
}Score Interpretation
- Type: List of Double values
- One score per document: Scores correspond 1:1 with input segments
- Higher = more relevant: Higher scores indicate better relevance to query
- Relative values: Scores should be compared within same query, not across queries
- Range: Varies by model
Scoring Behavior
Title Usage
If documents have titles in metadata (using titleMetadataKey), the model considers both:
- Document title
- Document content
This improves relevance scoring for documents with descriptive titles.
No Authentication Parameter
Unlike other models, VertexAiScoringModel does not support custom credentials() parameter. Always uses default application credentials.
Best Practices
Batch Size
- Score multiple documents in a single call for efficiency
- API handles batching internally
- Consider breaking very large document sets into multiple calls
Query Quality
- More specific queries produce better relevance scores
- Include key terms and concepts in query
- Avoid overly broad or vague queries
Document Preparation
- Include document titles in metadata when available
- Keep document lengths reasonable (very long may be truncated)
- Ensure content is clean and well-formatted
Title Metadata
If using custom metadata key:
VertexAiScoringModel model = VertexAiScoringModel.builder()
.titleMetadataKey("doc_title") // Custom key
.build();
TextSegment doc = TextSegment.from(
"Content...",
Metadata.from("doc_title", "Title") // Use same key
);Error Handling
Common errors:
- Invalid project number: Use numeric project number, not project ID
- Model not available: Check model availability in your region
- Empty segments list: Provide at least one document
- Quota exceeded: Monitor API usage and quotas in Google Cloud Console
Thread Safety
Thread-safe, can be reused across threads. Builder is not thread-safe.
Integration with LangChain4j
Integrates with LangChain4j retrieval and RAG components:
ScoringModel scoringModel = VertexAiScoringModel.builder()
.projectId("your-project")
.projectNumber("123456789012")
.location("us-central1")
.model("semantic-ranker-512@latest")
.build();
// Use with retrieved documents
List<TextSegment> retrieved = retriever.findRelevant(query);
Response<List<Double>> scores = scoringModel.scoreAll(retrieved, query);Install with Tessl CLI
npx tessl i tessl/maven-dev-langchain4j--langchain4j-vertex-ai@1.11.0