Google Gen AI（実験的）

https://github.com/googleapis/java-genai

[!WARNING]
この統合は現在実験的とマークされています。API と実装は将来のリリースで変更される可能性があります。新しい公式 Google Gen AI Java SDK（com.google.genai:google-genai）を使用します。

Maven 依存関係
API キー
利用可能なモデル
GoogleGenAiChatModel
- 設定
GoogleGenAiStreamingChatModel
- Executor
GoogleGenAiEmbeddingModel
GoogleGenAiImageModel
GoogleGenAiTextToSpeechModel
リクエストとレスポンスのログ
Batch API
ツール
コード実行
JSON Schema / 構造化出力
Grounding メタデータ
カスタムラベル
File API
キャッシュコンテンツのサポート
Thinking モデル（Gemini 3.0+）
トークン使用量
マルチモーダル（オーディオ、ビデオ、PDF）
音声文字起こし
画像生成出力
トークン数推定器
モデルカタログ

Maven 依存関係

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-google-genai</artifactId>
    <version>1.23.0-beta33</version>
</dependency>

認証

API キーまたは Google Cloud Vertex AI 認証情報を使用して Gemini モデルで認証できます。

Gemini Developer API（API キー）

API キーはこちらから無料で取得できます：https://ai.google.dev/gemini-api/docs/api-key。 .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY")) を使用してビルダーに提供できます。

Google Cloud Vertex AI

Vertex AI を使用している場合、Google Credentials とプロジェクト ID およびロケーションを使用して認証できます。利用可能な場合、統合は Application Default Credentials（ADC）を自動的に使用します。または明示的に提供することもできます。

ChatModel gemini = GoogleGenAiChatModel.builder()
    // .googleCredentials(...) // Optional: explicitly provide credentials
    .projectId("your-google-cloud-project-id")
    .location("us-central1")
    .modelName("gemini-2.5-flash")
    .build();

利用可能なモデル

ドキュメントで利用可能なモデルのリストを確認してください。

gemini-3.1-pro-preview
gemini-3.1-flash-lite
gemini-3-pro-preview
gemini-3-flash-preview
gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite

（-image、-tts、-live などの専用プレビューモデルの完全な一覧については、公式ドキュメントを参照してください）。

GoogleGenAiChatModel

通常の chat(...) メソッドが利用できます。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

String response = gemini.chat("Hello Gemini!");

および ChatResponse chat(ChatRequest req) メソッド:

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

ChatResponse chatResponse = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from(
        "How many R's are there in the word 'strawberry'?"))
    .build());

String response = chatResponse.aiMessage().text();

設定

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    // or .googleCredentials(...)
    .projectId(...)
    .location(...)
    .modelName("gemini-2.5-flash")
    .temperature(1.0)
    .topP(0.95)
    .topK(64)
    .seed(42)
    .maxOutputTokens(8192)
    .timeout(Duration.ofSeconds(60))
    .maxRetries(2)
    .stopSequences(List.of(...))
    .safetySettings(List.of(...))
    .responseFormat(ResponseFormat.JSON)
    .enableGoogleSearch(true)
    .enableGoogleMaps(true)
    .enableUrlContext(true)
    .enableCodeExecution(true)
    .includeCodeExecutionOutput(true)
    .allowedFunctionNames(List.of("getWeather"))
    .thinkingLevel("LOW")
    .listeners(...)
    .build();

高度: `GenerateContentConfig` のカスタマイズ

ビルダーメソッドは、最も一般的なオプションをカバーしています。基盤となる Google Gen AI Java SDK のオプションのうち、ビルダーメソッドでまだ公開されていないものを設定するには、generateContentConfigCustomizer を登録します。これは、この統合が GenerateContentConfig.Builder（生成パラメータ、ツール、システム指示など）を設定し終えた後、設定が構築される直前に GenerateContentConfig.Builder を受け取るため、リクエストごとのツールとシステム指示を保持したまま、追加のオプションを設定したり既存のオプションを上書きしたりできます。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .generateContentConfigCustomizer(config -> config.responseLogprobs(true).logprobs(5))
    .build();

これは GoogleGenAiStreamingChatModel でも同じように機能します。

リクエストとレスポンスのログ

デバッグ、トラブルシューティング、監査の目的で、GoogleGenAiChatModel、GoogleGenAiStreamingChatModel、GoogleGenAiEmbeddingModel、GoogleGenAiImageModel でリクエストとレスポンスのログを有効にできます。

これらのログをキャプチャするには、モデルビルダーで .logRequests(true)、.logResponses(true)（または .logRequestsAndResponses(true) で両方）を設定します。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .logRequests(true)
    .logResponses(true)
    // Or: .logRequestsAndResponses(true)
    .build();

ログ設定のセットアップ

Google Gen AI 統合モジュール内のすべてのログは、標準の SLF4J ファサードを通じてルーティングされます。実際に出力を表示するには、次を確認してください。

SLF4J バインディング（実装）が依存関係に存在する。
ログフレームワークが、パッケージ dev.langchain4j.model.google.genai の INFO レベルでログを出力するように設定されている。

以下は一般的なログ環境のセットアップパターンです。

1. Logback を使用したセットアップ

プロジェクトに Logback classic 実装を追加します。

Maven

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.5.8</version> <!-- or your preferred version -->
</dependency>

Gradle

implementation 'ch.qos.logback:logback-classic:1.5.8'

次に、src/main/resources/logback.xml ファイルでログレベルを設定します。例:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Configure the package specifically for Google Gen AI logging -->
    <logger name="dev.langchain4j.model.google.genai" level="INFO" />

    <root level="WARN">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

2. Spring Boot アプリケーションでのセットアップ

Spring Boot は自動的に SLF4J プロバイダーを提供します。application.properties（または同等の application.yml）でログレベルを設定するだけです。

# Enable logging for Google Gen AI models
logging.level.dev.langchain4j.model.google.genai=INFO

3. SLF4J Simple でのセットアップ

スクリプトまたはシンプルなコマンドラインアプリケーションを作成している場合は、軽量の slf4j-simple バックエンドを使用できます。

Maven

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.13</version>
</dependency>

アプリケーション起動時にシステムプロパティ経由で SLF4J Simple を設定します。

java -Dorg.slf4j.simpleLogger.log.dev.langchain4j.model.google.genai=INFO -jar app.jar

または、src/main/resources/ に次の内容の simplelogger.properties ファイルを作成します：

org.slf4j.simpleLogger.log.dev.langchain4j.model.google.genai=info

GoogleGenAiStreamingChatModel

GoogleGenAiStreamingChatModel を使用すると、レスポンスのテキストをトークンごとにストリーミングできます。レスポンスは StreamingChatResponseHandler で処理する必要があります。

StreamingChatModel gemini = GoogleGenAiStreamingChatModel.builder()
        .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
        .modelName("gemini-2.5-flash")
        .build();

CompletableFuture<ChatResponse> futureResponse = new CompletableFuture<>();

gemini.chat("Tell me a joke about Java", new StreamingChatResponseHandler() {

    @Override
    public void onPartialResponse(String partialResponse) {
        System.out.print(partialResponse);
    }

    @Override
    public void onCompleteResponse(ChatResponse completeResponse) {
        futureResponse.complete(completeResponse);
    }

    @Override
    public void onError(Throwable error) {
        futureResponse.completeExceptionally(error);
    }
});

futureResponse.join();

Executor

Google Gen AI SDK はストリーミングをブロッキングの ResponseStream イテレータとして公開します。各チャンクはブロッキングの next() 呼び出しによって配信されます。したがって、GoogleGenAiStreamingChatModel は呼び出し元のスレッド外でその反復を駆動するために ExecutorService を必要とします。

渡さない場合、DefaultExecutorProvider の共有デフォルトが使用されます（遅延初期化、利用可能な場合は仮想スレッドを使用）。これはすぐに動作しますが、本番環境では推奨されません。デフォルトのエグゼキュータは無制限で、JVM 全体に及び、アプリケーションのライフサイクルに結び付けられていないため、バックプレッシャー、グレースフルシャットダウン、メトリクスでの可視性を提供しません。

ほぼ常に独自のエグゼキュータを提供すべきです。たとえば、フレームワーク管理のタスクエグゼキュータ（Spring TaskExecutor、Quarkus ManagedExecutor など）、所有する仮想スレッドエグゼキュータ、または同時実行予算に合わせて調整された有界プールです。

ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor(); // or your framework's executor

StreamingChatModel gemini = GoogleGenAiStreamingChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .executor(executor)
    .build();

ツール

ツール（関数呼び出し）がサポートされています。LangChain4j の AiServices を使用して定義できます。

class WeatherForecastService {
    @Tool("Get the weather forecast for a location")
    String getForecast(@P("Location to get the forecast for") String location) {
        return "The weather in " + location + " is sunny and 25°C.";
    }
}

interface WeatherAssistant {
    String chat(String userMessage);
}

WeatherForecastService weatherForecastService = new WeatherForecastService();

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .temperature(0.0)
    .build();

WeatherAssistant weatherAssistant = AiServices.builder(WeatherAssistant.class)
    .chatModel(gemini)
    .tools(weatherForecastService)
    .build();

String response = weatherAssistant.chat("What is the weather forecast for Tokyo?");

コード実行（Code Execution）

enableCodeExecution(true) を使用すると、Gemini は Python コードを作成し、Google がホストするサンドボックスで実行して、その結果を回答に使用できます。計算やデータ分析に適しており、アプリケーション内では何も実行されません。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.8-flash")
    .enableCodeExecution(true)
    .includeCodeExecutionOutput(true)
    .build();

String answer = gemini.chat("What is 2 to the power of 100? Generate and run code to compute it.");

デフォルトでは、モデルの回答のみが返されます。includeCodeExecutionOutput(true) を使用すると、実行されたコードとその出力が、Gemini が返す順序で AiMessage のテキストに追加されます：

Code executed:
```python
print(2**100)
```

Output:
```
1267650600228229401496703205376
```

2 to the power of 100 is 1267650600228229401496703205376.

When the code fails or runs too long, the outcome (OUTCOME_FAILED or OUTCOME_DEADLINE_EXCEEDED) and the error output are added instead of the output.

Charts the code draws, for example with matplotlib, are returned as images: see response.aiMessage().images().
The code is Python, runs for at most 30 seconds, and can only use the libraries of the sandbox, such as numpy, pandas and matplotlib.
The current Gemini models reject a request that combines code execution with your own tools. The same applies to Google Search.

To read the code and its result as SDK objects, use the raw response:

ChatResponse response = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from("What is 2 to the power of 100? Generate and run code to compute it."))
    .build());

GoogleGenAiChatResponseMetadata metadata = (GoogleGenAiChatResponseMetadata) response.metadata();

for (Part part : metadata.rawResponse().parts()) {
    part.executableCode().ifPresent(code -> System.out.println(code.code().orElse("")));
    part.codeExecutionResult().ifPresent(result ->
        System.out.println(result.outcome().orElse(null) + ": " + result.output().orElse("")));
}

GoogleGenAiStreamingChatModel も同じオプションを受け付けますが、その生のレスポンスには最後にストリーミングされたチャンクしか含まれないため、コードとその結果を SDK オブジェクトとして読み取るには GoogleGenAiChatModel を使用してください。

JSON Schema / 構造化出力

langchain4j-google-genai 統合は、LangChain4j の JSON スキーマ（ResponseFormat.jsonSchema()）を公式 Google Gen AI SDK の ResponseSchema に直接マップします。これにより、強く型付けされた Java レコードをネイティブに抽出できます！

record WeatherForecast(
    @Description("minimum temperature") Integer minTemperature,
    @Description("maximum temperature") Integer maxTemperature,
    @Description("chances of rain") boolean rain
) { }

interface WeatherForecastAssistant {
    WeatherForecast extract(String forecast);
}

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

WeatherForecastAssistant forecastAssistant = AiServices.builder(WeatherForecastAssistant.class)
    .chatModel(gemini)
    .build();

WeatherForecast forecast = forecastAssistant.extract("""
    Morning: The day dawns bright and clear in Osaka...
    Temperatures climb to a comfortable 22°C (72°F) and 
    will drop to 15°C (59°F).
    """);

[!NOTE]
Google Gen AI API には、高度な JSON スキーマ機能（anyOf / ポリモーフィック型付けなど）にいくつかの制限があります。シンプルな POJO、リスト、ネストされたオブジェクトは完全にサポートされています。

キャッシュコンテンツのサポート

複数のリクエストにわたって再利用される非常に大きなコンテキストウィンドウ（大規模なシステムプロンプト、大きなドキュメント、または広範なコードベースなど）を扱う場合、コンテンツをキャッシュすることでコストとレイテンシを大幅に削減できます。

公式の Google Gen AI SDK または API を使用してキャッシュコンテンツを作成したら、一意のキャッシュ識別子を LangChain4j チャットモデルビルダーに簡単に渡すことができます。

// Pass your cached content URI here
String cachedContentUri = "projects/123456/locations/us-central1/cachedContents/my-cached-content-789";

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-pro")
    .cachedContent(cachedContentUri)
    .build();

// The model will automatically use the cached context!
String response = gemini.chat("Summarize the cached document in 3 bullet points.");

この機能は GoogleGenAiChatModel、GoogleGenAiStreamingChatModel、GoogleGenAiBatchChatModel で利用できます。

キャッシュの作成と管理

帯域外でキャッシュを作成する代わりに、GoogleGenAiCaches を使用して LangChain4j から直接作成および管理できます。これは SDK のキャッシュライフサイクル（create / get / list / update TTL / delete）をラップします。メッセージはチャットモデルと同じ GoogleGenAiContentMapper を使用してキャッシュされるため、LangChain4j の ChatMessage ドメインに留まります。

GoogleGenAiCaches caches = GoogleGenAiCaches.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .build();

// Cache a large, reusable context (a system instruction plus a long document)
CachedContent cache = caches.createCache(
    "gemini-2.5-flash",
    List.of(
        SystemMessage.from("You are a precise assistant answering questions about the attached document."),
        UserMessage.from(longDocumentText)),
    Duration.ofHours(1));

// Reuse it across many requests via cachedContent
ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .cachedContent(cache.name().orElseThrow())
    .build();

String answer = gemini.chat("Summarize the cached document in 3 bullet points.");

// Manage the cache lifecycle
caches.updateCacheTtl(cache.name().orElseThrow(), Duration.ofHours(2));
caches.listCaches();
caches.deleteCache(cache.name().orElseThrow());

注意: 明示的なコンテキストキャッシュには有料ティアが必要です。無料ティアでは利用できません。

Thinking モデル（Gemini 3.0+）

Gemini 3.0 モデル（gemini-3.0-pro や gemini-3.0-flash など）は、高度な推論（thinking）機能をサポートしています。モデル設定時に thinkingLevel を指定することで有効にできます。サポートされる値は "MINIMAL"、"LOW"、"MEDIUM"、"HIGH" です。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.0-pro")
    .thinkingLevel("MEDIUM")
    .build();

[!NOTE] 以前は、thinking はトークンベースの thinkingBudget を使用して設定されていました。thinkingBudget パラメータは現在レガシーと見なされていますが、引き続きサポートされています。thinkingLevel と thinkingBudget の両方を同時に指定することはできません。

[!TIP] LangChain4j の google-genai 統合は、thinking モデルを使用したマルチターンのツール実行に必要な複雑な状態をシームレスに管理します。会話ターン間で必要な隠し thought_signature トークンを自動的に永続化および注入し、堅牢で中断のないエージェントワークフローを保証します！

思考の要約（Thought summaries）

includeThoughts(true) を設定すると、モデルが回答とともに思考の要約を返すようになり、 returnThinking(true) を設定すると、それが AiMessage.thinking() にマッピングされます：

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.1-pro-preview")
    .thinkingLevel("MEDIUM")
    .includeThoughts(true)
    .returnThinking(true)
    .build();

ChatResponse response = gemini.chat(UserMessage.from("What is 6 times 7?"));

String thinking = response.aiMessage().thinking();
String answer = response.aiMessage().text();

ストリーミング時、思考の要約は StreamingChatResponseHandler.onPartialThinking() を通じて配信され、回答は引き続き onPartialResponse() を通じて届きます。

後続のリクエストで思考の要約をモデルに送り返すには、sendThinking(true) を設定します。マルチターンのツール実行に必要な thought_signature トークンは独立して処理され、この設定に関係なく常に保持されます。

[!NOTE] returnThinking はデフォルトで無効です。その場合、モデルが返した思考の要約は破棄され、 AiMessage.text() には現れません。

トークン使用量と自動継続（Token Usage & Automatic Continuation）

レスポンスには GoogleGenAiTokenUsage が含まれます。これは、標準の入力・出力・合計のトークン数に、Gemini が報告する thinking、キャッシュされたコンテンツ、ツール結果、マルチホップの継続に関するトークン数を追加したものです：

GoogleGenAiTokenUsage tokenUsage = (GoogleGenAiTokenUsage) response.metadata().tokenUsage();

Integer thoughtsTokenCount = tokenUsage.thoughtsTokenCount();
Integer cachedContentTokenCount = tokenUsage.cachedContentTokenCount();
Integer toolUsePromptTokenCount = tokenUsage.toolUsePromptTokenCount();
Integer initialPromptTokenCount = tokenUsage.initialPromptTokenCount();

モデルが報告しない場合、各項目は null になります。cachedContentTokenCount は inputTokenCount() のサブセットですが、 toolUsePromptTokenCount と thoughtsTokenCount はそれに加えてカウントされます： Gemini は合計を inputTokenCount + outputTokenCount + toolUsePromptTokenCount + thoughtsTokenCount と定義しています。

Gemini は、CONTINUATION の終了理由で長いレスポンスを途中で終了することがあります。デフォルトでは、Google Gen AI SDK はその後、継続トークンを付けて同じリクエストを、モデルが完了するまで再送信し、すべてのパートを 1 つのレスポンスとして返します。これらのリクエスト（ホップ）はそれぞれ個別に課金されます。この場合、inputTokenCount() はすべてのホップのプロンプトトークンの合計であり、initialPromptTokenCount() は最初のホップのみのプロンプトトークン数です。 1 回のリクエストで済んだレスポンスでは、両者は同じです。

自動継続をオフにするには、モデルビルダーで automaticContinuation(false) を設定するか、リクエストごとに GoogleGenAiChatRequestParameters 経由で設定します：

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .automaticContinuation(false)
    .build();

GoogleGenAiEmbeddingModel

GoogleGenAiEmbeddingModel を使用すると、gemini-embedding-2 などのモデルを使用してテキストセグメントの埋め込みを生成できます。

EmbeddingModel embeddingModel = GoogleGenAiEmbeddingModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-embedding-2")
    .outputDimensionality(768)
    .taskType(GoogleGenAiEmbeddingModel.TaskTypeEnum.RETRIEVAL_DOCUMENT)
    .build();

Response<Embedding> response = embeddingModel.embed("Hello world!");

バッチ処理とリトライ

複数のテキストセグメントを埋め込む場合（embedAll 経由）、GoogleGenAiEmbeddingModel はバッチ処理と API リクエストのリトライを自動的に管理します。

EmbeddingModel embeddingModel = GoogleGenAiEmbeddingModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-embedding-2")
    .maxSegmentsPerBatch(100) // Default: 100. Sets maximum segments per batch request.
    .maxRetries(3)             // Default: 3. Automatically retries failed requests.
    .build();

タイトルベースのグループ化戦略

公式 Google Gen AI Java SDK の embedContent API は、バッチリクエストごとに単一の共通 title のみをサポートします。この制限をクリーンに処理し、ドキュメントレベルの関連付けを保持するために、GoogleGenAiEmbeddingModel はタイトルによるグループ化バッチ戦略を実装しています。

taskType が RETRIEVAL_DOCUMENT に設定されている場合、モデルはドキュメントタイトル（.titleMetadataKey(...) で定義されたキーを使用してセグメントのメタデータから抽出、デフォルトは "title"）でテキストセグメントをグループ化します。
同じタイトルを共有するセグメントはバッチ処理され、単一の API 呼び出しで一緒に送信されます。
異なるタイトル（またはタイトルなし）のセグメントは、個別の最適化されたバッチで処理されます。
結果の埋め込みはシームレスに再組み立てされ、元の順序で返されます。

これにより、ドキュメントメタデータコンテキストや個々のセグメントタイトルを失うことなく、API スループットが最大化されます。

GoogleGenAiImageModel

GoogleGenAiImageModel を使用すると、テキストプロンプトから画像を生成できます。アスペクト比、画像サイズ、人物生成ポリシーなどのカスタム設定をサポートしています。

ImageModel imageModel = GoogleGenAiImageModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.1-flash-image-preview")
    .aspectRatio("16:9")
    .build();

Response<Image> response = imageModel.generate("A futuristic city at sunset");

GoogleGenAiTextToSpeechModel

GoogleGenAiTextToSpeechModel は、gemini-3.8-flash-tts や gemini-3.8-flash-lite-tts などの Gemini テキスト読み上げモデルを使って、テキストを音声に変換します。

TextToSpeechModel model = GoogleGenAiTextToSpeechModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.8-flash-tts")
    .voice("Kore")
    .build();

TextToSpeechResponse response = model.synthesize("Have a wonderful day!");

Files.write(Path.of("speech.wav"), response.audio().binaryData());

voice：読み上げに使用するプリビルトの音声（Kore や Puck など）。TextToSpeechRequest に設定された音声が優先されます。音声が設定されていない場合は、API が選択します。
languageCode：読み上げる言語の BCP-47 コード（de-DE など）。設定されていない場合、言語はテキストから検出されます。

音声は WAV として返されます。gemini-3.1-flash-tts-preview などのプレビューモデルは生の 16 ビット PCM で応答するため、WAV ヘッダーで包んで、どのモデルでも再生可能なファイルが返されるようにしています。

gemini-3.8-flash-tts では、"Say cheerfully:" のような指示を含め、テキスト全体が読み上げられます。

複数の話者（Multiple speakers）

会話を音声化するには、speaker で各話者に音声を割り当て、各ターンを新しい行で、話者の名前とコロンから始めます：

TextToSpeechModel model = GoogleGenAiTextToSpeechModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.8-flash-tts")
    .speaker("Joe", "Kore")
    .speaker("Jane", "Puck")
    .build();

TextToSpeechResponse response = model.synthesize("""
    Joe: How is the weather in Paris today?
    Jane: Sunny and warm.
    """);

話者名で始まらない行は、直前のターンに属するため、テキストは話者から始める必要があります。最初のターンより前のテキストは IllegalArgumentException で拒否されます。会話の話者はちょうど 2 人で、voice と組み合わせることはできず、gemini-3.8 のテキスト読み上げモデルが必要です。プレビューモデルはこれを拒否します。話者にプリビルトの音声以上のものが必要な場合、multiSpeakerVoiceConfig は SDK の MultiSpeakerVoiceConfig を受け取ります。

代わりに ChatModel から音声を取得するには、音声 / オーディオ生成出力を参照してください。

Batch API

Google Gen AI 統合は Batch API のサポートを提供し、バックグラウンドで非同期に操作を実行できます。次のバッチモデルがサポートされています。

GoogleGenAiBatchChatModel
GoogleGenAiBatchEmbeddingModel
GoogleGenAiBatchImageModel

インラインまたは Google Cloud にアップロードされたファイルからバッチジョブを作成できます。

GoogleGenAiBatchChatModel batchChatModel = GoogleGenAiBatchChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

BatchResponse<ChatResponse> batchResponse = batchChatModel.submit(
    "My Batch Job",
    List.of(
        ChatRequest.builder().messages(UserMessage.from("What is 2+2?")).build(),
        ChatRequest.builder().messages(UserMessage.from("What is the capital of France?")).build()
    )
);

System.out.println("Batch Job ID: " + batchResponse.batchId());

その後、batchChatModel.retrieve(batchResponse.batchId()) を使用してジョブのステータスと結果を取得できます。

Grounding メタデータ

Google Search grounding を有効にするか、Vertex AI Search データストアを使用する場合、Google Gen AI チャットモデルはネイティブの GroundingMetadata を ChatResponse に直接公開します。基盤となる生の GenerateContentResponse を介してレスポンスメタデータから取得できます。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .enableGoogleSearch(true)
    .build();

ChatResponse response = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from("Who won the super bowl in 2024?"))
    .build());

GoogleGenAiChatResponseMetadata metadata = 
    (GoogleGenAiChatResponseMetadata) response.metadata();

if (metadata.rawResponse() != null 
        && metadata.rawResponse().candidates() != null 
        && !metadata.rawResponse().candidates().isEmpty()) {
    var groundingMetadata = metadata.rawResponse().candidates().get(0).groundingMetadata();
    if (groundingMetadata != null && groundingMetadata.webSearchQueries() != null) {
        System.out.println("Search Queries: " + groundingMetadata.webSearchQueries());
    }
}

カスタムラベル

Google Gen AI リクエストにカスタムのキー値ラベルを適用できます。これは課金、メトリクス、追跡の目的で有用です。カスタムラベルは次でサポートされています。

GoogleGenAiChatModel
GoogleGenAiStreamingChatModel
GoogleGenAiBatchChatModel
GoogleGenAiImageModel
GoogleGenAiBatchImageModel

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .labels(Map.of("environment", "production", "team", "backend"))
    .build();

GoogleGenAiChatRequestParameters 経由で、リクエストごとにラベルを上書きすることもできます：

ChatResponse response = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from("Hello"))
    .parameters(GoogleGenAiChatRequestParameters.builder()
        .labels(Map.of("environment", "staging", "tenant", "acme"))
        .build())
    .build());

File API

Google Gen AI 統合は、Google のサーバー上でファイルをアップロードおよび管理するための GoogleGenAiFiles ユーティリティを提供します。これは、標準のリクエスト制限を超える可能性のある大規模なマルチモーダル入力（長いビデオ、オーディオファイル、または広範な PDF など）を渡すのに特に有用です。

GoogleGenAiFiles fileApi = GoogleGenAiFiles.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .build();

String uploadedFileUri = fileApi.uploadFile(
    Paths.get("path/to/my-video.mp4"), 
    "video/mp4", 
    "My Video Demo"
);

// You can now use this URI in your chat requests
ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

ChatResponse response = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from(
        VideoContent.from(uploadedFileUri, "video/mp4"),
        TextContent.from("What happens in this video?")
    ))
    .build());

マルチモーダル（オーディオ、ビデオ、PDF）

この統合は LangChain4j のマルチモーダルコンテンツタイプを完全にサポートしています。基盤となる GoogleGenAiContentMapper がそれらを適切な Gemini Part オブジェクトに自動的に変換します。

ChatModel gemini = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

ChatResponse response = gemini.chat(ChatRequest.builder()
    .messages(UserMessage.from(
        AudioContent.from("https://example.com/audio.mp3"),
        PdfFileContent.from("https://example.com/document.pdf"),
        TextContent.from("Summarize the document and the audio recording.")
    ))
    .build());

音声文字起こし（Audio Transcription）

gemini-3.5-transcribe など、音声認識向けに構築されたモデルは、音声をテキストに変換します。音声を AudioContent として送信します。テキストの指示は不要です。文字起こし結果は AiMessage のテキストとして返されます。

audioTranscriptionConfig を使用して、音声の文字起こし方法を制御します：

ChatModel transcriber = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.5-transcribe")
    .audioTranscriptionConfig(AudioTranscriptionConfig.builder()
        .mode(AudioTranscriptionConfigMode.Known.VERBATIM)
        .languageCodes("en-US")
        .customVocabulary("LangChain4j", "Gemini")
        .wordTimestamp(true)
        .diarization(true)
        .build())
    .build();

ChatResponse response = transcriber.chat(ChatRequest.builder()
    .messages(UserMessage.from(AudioContent.from("https://example.com/meeting.mp3")))
    .build());

String transcript = response.aiMessage().text();

mode：VERBATIM（デフォルト）は、フィラーワード、繰り返し、言い直しを含め、すべての単語を保持します。 SMART はそれらを取り除き、テキストを軽く整形します。単語タイムスタンプと話者分離は SMART では使用できません。
languageCodes：音声で話されている言語の BCP-47 コード。省略した場合、言語は自動的に検出されます。
customVocabulary：製品名や人名など、モデルが認識すべき単語やフレーズ。
wordTimestamp：各単語の開始オフセットと終了オフセットを返します。
diarization：誰が何を話したかをラベル付けします（話者分離）。

セグメント単位のタイムスタンプ（Duration 型の startOffset と endOffset）、単語タイムスタンプ、話者ラベルは AiMessage のテキストには含まれません。生のレスポンスから読み取ってください：

GoogleGenAiChatResponseMetadata metadata = (GoogleGenAiChatResponseMetadata) response.metadata();

for (Part part : metadata.rawResponse().parts()) {
    part.audioTranscription().ifPresent(transcription -> {
        String speaker = transcription.speakerLabel().orElse("");
        Duration segmentStart = transcription.startOffset().orElse(Duration.ZERO);
        Duration segmentEnd = transcription.endOffset().orElse(Duration.ZERO);
        System.out.printf("Segment [%s] (%s - %s): %s%n",
            speaker, segmentStart, segmentEnd, transcription.text().orElse(""));
        for (WordInfo word : transcription.words().orElse(List.of())) {
            System.out.printf("  [%s] %s - %s %s%n",
                speaker, word.startOffset().orElse(""), word.endOffset().orElse(""), word.word().orElse(""));
        }
    });
}

GoogleGenAiStreamingChatModel も同じ audioTranscriptionConfig を受け付けますが、その生のレスポンスには最後にストリーミングされたチャンクしか含まれないため、タイムスタンプや話者ラベルが必要な場合は GoogleGenAiChatModel を使用してください。

音声 / オーディオ生成出力（Speech / Audio Generation Output）

Gemini TTS モデル（gemini-3.8-flash-tts、gemini-3.8-flash-lite-tts、gemini-3.1-flash-tts-preview など）は、テキストから音声オーディオを合成できます。speechConfig（単一話者または複数話者の音声、言語コード、PronunciationDictionaryConfig によるカスタム発音辞書を含む）を、responseModalities(List.of("AUDIO")) とともに設定します：

ChatModel ttsModel = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-3.8-flash-tts")
    .responseModalities(List.of("AUDIO"))
    .speechConfig(SpeechConfig.builder()
        .languageCode("en-US")
        .voiceConfig(VoiceConfig.builder()
            .prebuiltVoiceConfig(PrebuiltVoiceConfig.builder().voiceName("Kore").build())
            .build())
        .build())
    .build();

ChatResponse response = ttsModel.chat(UserMessage.from("Welcome to LangChain4j!"));

List<Audio> audioParts = response.aiMessage().audios();

各 Audio は、モデルが返した 1 つのオーディオパートをそのまま保持し、その mimeType() と base64Data() を持ちます。 gemini-3.8 の TTS モデルは WAV（audio/wav）を返します。プレビューの TTS モデルは、再生可能なファイルではなく生の PCM オーディオ（たとえば audio/L16;codec=pcm;rate=24000）を返すため、保存または再生する前に WAV ヘッダーを追加するか、ヘッダーを追加してくれる GoogleGenAiTextToSpeechModel を使用してください。

GoogleGenAiStreamingChatModel は、オーディオを複数のチャンクで受信します。最終的な AiMessage は、到着した順序ですべてのパートを保持するため、すべてのパートのバイトを連結して完全なオーディオを取得します。

画像生成出力（Image Generation Output）

gemini-2.5-flash-image などの一部の Gemini モデルは、チャットレスポンスのテキストとともに生成された画像を返します。これらは inlineData パートとして届き、GoogleGenAiChatModel はそれらを AiMessage の属性の GENERATED_IMAGES_KEY の下にマッピングします。これは AiMessage.images() が読み取る場所です：

ChatModel model = GoogleGenAiChatModel.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash-image")
    .build();

ChatResponse response = model.chat(UserMessage.from("A watercolor sketch of a lighthouse at dusk"));

for (Image image : response.aiMessage().images()) {
    System.out.println("Generated image: " + image.mimeType());

    // Save it, display it, or hand it to another model
    Files.write(Paths.get("generated_image.png"), Base64.getDecoder().decode(image.base64Data()));
}

image/* の blob のみが生成画像になります。audio/* の blob は AiMessage.audios() で返され（上記参照）、それ以外のタイプのインラインデータは無視されます。

ストリーミングレスポンスも同様に動作します。GoogleGenAiStreamingChatModel は回答を 1 チャンクずつ受信し、各チャンクがその画像を最終メッセージに追加するため、単独のチャンクで届いた画像も失われません。

langchain4j-google-ai-gemini も生成された画像を同じキーの下に保存するため、同じ読み取りコードがどちらのモジュールでも動作します。

トークン数推定器

公式 SDK のカウントエンドポイントを使用する GoogleGenAiTokenCountEstimator を使用して、プロンプトとメッセージ内のトークン数を正確に推定できます。

TokenCountEstimator estimator = GoogleGenAiTokenCountEstimator.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

int tokenCount = estimator.estimateTokenCount("How many tokens is this sentence?");
System.out.println("Tokens: " + tokenCount);

モデルカタログ

GoogleGenAiModelCatalog を使用して、利用可能な Gemini モデルのリストをプログラムでクエリできます。これは、モデルの機能、コンテキストウィンドウ、サポートされているメソッドを動的に発見するのに役立ちます。

GoogleGenAiModelCatalog catalog = GoogleGenAiModelCatalog.builder()
    .apiKey(System.getenv("GOOGLE_AI_GEMINI_API_KEY"))
    .build();

List<Model> availableModels = catalog.listModels();
availableModels.forEach(model -> {
    System.out.println("Model Name: " + model.name());
    System.out.println("Supported Generation Methods: " + model.supportedGenerationMethods());
});

目次​

Maven 依存関係​

認証​

Gemini Developer API（API キー）​

Google Cloud Vertex AI​

利用可能なモデル​

GoogleGenAiChatModel​

設定​

高度: GenerateContentConfig のカスタマイズ​

リクエストとレスポンスのログ​

ログ設定のセットアップ​

1. Logback を使用したセットアップ​

Maven​

Gradle​

2. Spring Boot アプリケーションでのセットアップ​

3. SLF4J Simple でのセットアップ​

Maven​

GoogleGenAiStreamingChatModel​

Executor​

ツール​

コード実行（Code Execution）​

JSON Schema / 構造化出力​

キャッシュコンテンツのサポート​

キャッシュの作成と管理​

Thinking モデル（Gemini 3.0+）​

思考の要約（Thought summaries）​

トークン使用量と自動継続（Token Usage & Automatic Continuation）​

GoogleGenAiEmbeddingModel​

バッチ処理とリトライ​

タイトルベースのグループ化戦略​

GoogleGenAiImageModel​

GoogleGenAiTextToSpeechModel​

複数の話者（Multiple speakers）​

Batch API​

Grounding メタデータ​

カスタムラベル​

File API​

マルチモーダル（オーディオ、ビデオ、PDF）​

音声文字起こし（Audio Transcription）​

音声 / オーディオ生成出力（Speech / Audio Generation Output）​

画像生成出力（Image Generation Output）​

トークン数推定器​

モデルカタログ​

目次

Maven 依存関係

認証

Gemini Developer API（API キー）

Google Cloud Vertex AI

利用可能なモデル

GoogleGenAiChatModel

設定

高度: `GenerateContentConfig` のカスタマイズ

リクエストとレスポンスのログ

ログ設定のセットアップ

1. Logback を使用したセットアップ

Maven

Gradle

2. Spring Boot アプリケーションでのセットアップ

3. SLF4J Simple でのセットアップ

Maven

GoogleGenAiStreamingChatModel

Executor

ツール

コード実行（Code Execution）

JSON Schema / 構造化出力

キャッシュコンテンツのサポート

キャッシュの作成と管理

Thinking モデル（Gemini 3.0+）

思考の要約（Thought summaries）

トークン使用量と自動継続（Token Usage & Automatic Continuation）

GoogleGenAiEmbeddingModel

バッチ処理とリトライ

タイトルベースのグループ化戦略

GoogleGenAiImageModel

GoogleGenAiTextToSpeechModel

複数の話者（Multiple speakers）

Batch API

Grounding メタデータ

カスタムラベル

File API

マルチモーダル（オーディオ、ビデオ、PDF）

音声文字起こし（Audio Transcription）

音声 / オーディオ生成出力（Speech / Audio Generation Output）

画像生成出力（Image Generation Output）

トークン数推定器

モデルカタログ