Class GoogleAiGeminiBatchEmbeddingModel

java.lang.Object

dev.langchain4j.model.googleai.GoogleAiGeminiBatchEmbeddingModel

All Implemented Interfaces:

BatchEmbeddingModel

@Experimental
public final class GoogleAiGeminiBatchEmbeddingModel
extends Object
implements BatchEmbeddingModel

Batch embedding model for Google AI Gemini.

Provides asynchronous batch processing for generating embeddings from multiple text segments at reduced cost (50% of standard pricing) with a 24-hour turnaround SLO.

Implements BatchEmbeddingModel for unified batch processing of embedding requests.

See Also:

• BatchEmbeddingModel
• BatchResponse

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GoogleAiGeminiBatchEmbeddingModel.Builder	Builder for constructing GoogleAiGeminiBatchEmbeddingModel instances.

Method Summary

Modifier and Type	Method	Description
static GoogleAiGeminiBatchEmbeddingModel.Builder	builder()	Returns a new builder for constructing GoogleAiGeminiBatchEmbeddingModel instances.
void	cancel(String batchId)	Cancels an embedding batch operation that is currently pending or running.
void	deleteBatchJob(String batchId)	Deletes a batch job from the system.
BatchPage<Response<Embedding>>	list(@Nullable BatchPagination batchPagination)	Lists embedding batch jobs with optional pagination.
BatchResponse<Response<Embedding>>	retrieve(String batchId)	Retrieves the current state and results of an embedding batch operation.
BatchResponse<Response<Embedding>>	submit(BatchRequest<TextSegment> request)	Creates a batch of text segments and submits them for asynchronous embedding processing.
BatchResponse<Response<Embedding>>	submit(GeminiBatchRequest<TextSegment> request)	Creates and enqueues a batch of embedding requests, with Gemini-specific options such as display name and priority.
BatchResponse<Response<Embedding>>	submit(String displayName, GeminiFiles.GeminiFile file)	Creates and enqueues a batch of embedding requests from an uploaded file.
void	writeBatchToFile(JsonLinesWriter writer, Iterable<BatchRequestResponse.BatchFileRequest<TextSegment>> requests)	Writes a sequence of text segments to a JSONL file writer in the format required for file-based batch processing.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

submit

public BatchResponse<Response<Embedding>> submit(BatchRequest<TextSegment> request)

Creates a batch of text segments and submits them for asynchronous embedding processing.

The returned BatchResponse represents the status of the batch operation.

Creates and enqueues a batch of embedding requests using default display name and priority. To set a custom display name or priority, pass a GeminiBatchRequest (it will resolve to submit(GeminiBatchRequest)).

Specified by:

submit in interface BatchEmbeddingModel

Parameters:

request - the list of TextSegments to generate embeddings for

Returns:

a BatchResponse representing the initial state of the batch operation

submit

public BatchResponse<Response<Embedding>> submit(GeminiBatchRequest<TextSegment> request)

Creates and enqueues a batch of embedding requests, with Gemini-specific options such as display name and priority.

Parameters:

request - a GeminiBatchRequest carrying the text segments and optional metadata

Returns:

a BatchResponse representing the initial state of the batch operation

submit

public BatchResponse<Response<Embedding>> submit(String displayName,
 GeminiFiles.GeminiFile file)

Creates and enqueues a batch of embedding requests from an uploaded file.

This method is used for processing large volumes of embedding requests that exceed the limits of the inline API (20 MB). Before calling this method, you must write your requests to a JSONL file (using writeBatchToFile(JsonLinesWriter, Iterable)) and upload it using the GeminiFiles API to get a GeminiFiles.GeminiFile.

Parameters:

displayName - a user-defined name for the batch, used for identification

file - the GeminiFiles.GeminiFile representing the uploaded JSONL file containing the requests

Returns:

a BatchResponse representing the initial state of the batch operation

See Also:

• writeBatchToFile(JsonLinesWriter, Iterable)
• GeminiFiles.uploadFile(java.nio.file.Path, String)

writeBatchToFile

public void writeBatchToFile(JsonLinesWriter writer,
 Iterable<BatchRequestResponse.BatchFileRequest<TextSegment>> requests)
                      throws IOException

Writes a sequence of text segments to a JSONL file writer in the format required for file-based batch processing.

This helper method takes high-level TextSegment objects wrapped in BatchRequestResponse.BatchFileRequests (which enable assigning unique keys to each request) and serializes them into the specific JSON structure expected by the Gemini Batch API. It handles the conversion to internal request objects, including metadata handling for document titles.

Example Usage:

Path batchFile = Files.createTempFile("embeddings", ".jsonl");
try (JsonLinesWriter writer = new StreamingJsonLinesWriter(batchFile)) {
    List<BatchFileRequest<TextSegment>> requests = List.of(
        new BatchFileRequest<>("doc-1", TextSegment.from("Content for document 1")),
        new BatchFileRequest<>("doc-2", TextSegment.from("Content for document 2"))
    );
    batchModel.writeBatchToFile(writer, requests);
}

Parameters:

writer - the JsonLinesWriter to write to

requests - an iterable of BatchRequestResponse.BatchFileRequests, each containing a key and a TextSegment

Throws:

IOException - if an error occurs while writing to the underlying stream

retrieve

public BatchResponse<Response<Embedding>> retrieve(String batchId)

Retrieves the current state and results of an embedding batch operation.

The response indicates whether the batch is still processing, completed successfully, or failed. Use this to retrieve the computed embeddings once the state is success.

Polls the Gemini API to get the latest state of a previously created batch. Clients should poll this method at intervals to check the operation status until completion.

Specified by:

retrieve in interface BatchEmbeddingModel

Parameters:

batchId - the batch name obtained from BatchEmbeddingModel.submit(BatchRequest) or submit(String, GeminiFile)

Returns:

a BatchResponse representing the current state of the batch operation

cancel

public void cancel(String batchId)

Cancels an embedding batch operation that is currently pending or running.

Cancellation is only possible for batches that are in PENDING or RUNNING state. Batches that have already completed, failed, or been cancelled cannot be cancelled.

Specified by:

cancel in interface BatchEmbeddingModel

Parameters:

batchId - the batch name to cancel

deleteBatchJob

public void deleteBatchJob(String batchId)

Deletes a batch job from the system.

This removes the batch job record but does not cancel it if still running. Use cancel(String) to cancel a running batch before deletion.

Parameters:

batchId - the batch name to delete

Throws:

RuntimeException - if the batch job cannot be deleted or does not exist

list

public BatchPage<Response<Embedding>> list(@Nullable BatchPagination batchPagination)

Lists embedding batch jobs with optional pagination.

Specified by:

list in interface BatchEmbeddingModel

Parameters:

batchPagination - the maximum number of batch jobs to return and token for retrieving a specific page; if null, uses server default

Returns:

a BatchPage containing embedding batch responses and pagination information

builder

public static GoogleAiGeminiBatchEmbeddingModel.Builder builder()

Returns a new builder for constructing GoogleAiGeminiBatchEmbeddingModel instances.

Returns:

a new builder instance