ChatGoogle 集成 - Docs by LangChain中文

本库支持访问多种 Google 模型，包括 Gemini 系列模型及其 Nano Banana 图像生成模型。您可以通过 Google 的 Google AI API（有时也称为 Generative AI API 或 AI Studio API）或通过 Google Cloud Platform 的 Vertex AI 服务来访问这些模型。本文将帮助您快速上手 ChatGoogle 聊天模型。有关所有 ChatGoogle 功能和配置的详细文档，请参阅 API 参考。

推荐所有新的 Google Gemini 集成使用 @langchain/google 包。它取代了旧的 @langchain/google-genai 和 @langchain/google-vertexai 包。有关迁移详情，请参阅旧版包。

概览

集成详情

类	包	可序列化	Python 支持	下载量	版本
`ChatGoogle`	`@langchain/google`	✅	✅

模型特性

请参见下方表头的链接，获取如何使用特定功能的指南。

工具调用	结构化输出	图像输入	音频输入	视频输入	Token 级流式传输	Token 用量	Logprobs
✅	✅	✅	✅	✅	✅	✅	✅

请注意，虽然支持 logprobs，但 Gemini 对其使用有相当严格的限制。

设置

通过 AI Studio 获取凭证（API 密钥）

要通过 Google AI Studio（有时称为 Generative AI API）使用模型，您需要一个 API 密钥。您可以从 Google AI Studio 获取。获得 API 密钥后，您可以将其设置为环境变量：

export GOOGLE_API_KEY="your-api-key"

或者，也可以在模型构造函数中直接传入：

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle({
  apiKey: "your-api-key",
  model: "gemini-2.5-flash",
});

通过 Vertex AI 快速模式获取凭证（API 密钥）

Vertex AI 也支持 Express Mode，允许您使用 API 密钥进行身份验证。您可以从 Google Cloud 控制台获取 Vertex AI API 密钥。获得 API 密钥后，您可以将其设置为环境变量：

export GOOGLE_API_KEY="your-api-key"

使用 Vertex AI Express Mode 时，您还需要在实例化模型时将平台类型指定为 gcp。

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  platformType: "gcp",
  // apiKey: "...", // 如果已设置 GOOGLE_API_KEY，则可选
});

通过 Vertex AI 获取凭证（OAuth 应用默认凭证 / ADC）

在生产环境的 Google Cloud 中，建议使用应用程序默认凭据 (ADC)。这在 Node.js 环境中受支持。如果您在本地机器上运行，可以通过安装 Google Cloud SDK 并运行以下命令来设置 ADC：

gcloud auth application-default login

或者，您也可以将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号密钥文件的路径：

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

通过 Vertex AI 获取凭证（OAuth 已保存的凭据）

如果您在 Web 环境中运行或希望直接提供凭据，可以使用 GOOGLE_CLOUD_CREDENTIALS 环境变量。该变量应包含服务账号密钥文件的内容（而非路径）。

export GOOGLE_CLOUD_CREDENTIALS='{"type":"service_account","project_id":"your-project-id",...}'

您也可以使用 credentials 参数直接在代码中提供这些凭据。

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  platformType: "gcp",
  credentials: {
    type: "service_account",
    project_id: "your-project-id",
    private_key_id: "your-private-key-id",
    private_key: "your-private-key",
    client_email: "your-service-account-email",
    client_id: "your-client-id",
    auth_uri: "https://accounts.google.com/o/oauth2/auth",
    token_uri: "https://oauth2.googleapis.com/token",
    auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs",
    client_x509_cert_url: "your-cert-url",
  }
});

追踪

如果您想对模型调用进行自动追踪，也可以取消下方注释，设置您的 LangSmith API 密钥：

# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

安装

LangChain 的 ChatGoogle 集成位于 @langchain/google 包中：

npm install @langchain/google @langchain/core

实例化

导入路径取决于您是在 Node.js 环境还是 Web/Edge 环境中运行。

import { ChatGoogle } from "@langchain/google/node";

模型会根据您的配置自动决定使用 Google AI API 还是 Vertex AI：

如果您提供 apiKey（或设置了 GOOGLE_API_KEY），则默认使用 Google AI。
如果您提供 credentials（或在 Node 中设置了 GOOGLE_APPLICATION_CREDENTIALS / GOOGLE_CLOUD_CREDENTIALS），则默认使用 Vertex AI。

Google AI（AI Studio）

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  maxRetries: 2,
  // apiKey: "...", // 如果已设置 GOOGLE_API_KEY，则可选
});

Vertex AI

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  // credentials: { ... }, // 如果使用 ADC 或 GOOGLE_CLOUD_CREDENTIALS，则可选
});

Vertex AI 快速模式

要通过 API 密钥使用 Vertex AI（Express Mode），您必须明确设置 platformType。

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  platformType: "gcp",
  // apiKey: "...", // 如果已设置 GOOGLE_API_KEY，则可选
});

模型配置最佳实践

虽然 ChatGoogle 支持如 temperature、topP 和 topK 等标准模型参数，但使用 Gemini 模型的最佳实践是保持这些参数的默认值。这些模型已经针对这些默认值进行了高度调优。如果您想控制模型的“随机性”或“创造性”，建议在提示词或系统提示中使用具体的指令（例如，“要有创意”、“给出简洁的事实回答”），而不是调整 temperature。

调用

import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const aiMsg = await llm.invoke([
  new SystemMessage(
    "您是一个乐于助人的助手，可将英语翻译成法语。请翻译用户的句子。"
  ),
  new HumanMessage("I love programming."),
]);

console.log(aiMsg.text);

J'adore programmer.

响应元数据

AIMessage 响应包含有关生成的元数据，包括 token 用量和 log 概率。

Token 用量

usage_metadata 属性允许您检查 token 计数。

const res = await llm.invoke("Hello, how are you?");

console.log(res.usage_metadata);

{ input_tokens: 6, output_tokens: 7, total_tokens: 13 }

Logprobs

如果在模型配置中启用了 logprobs，它们将在 response_metadata 中可用。

const llmWithLogprobs = new ChatGoogle({
  model: "gemini-2.5-flash",
  logprobs: 2, // 返回的顶级候选项数量
});

const resWithLogprobs = await llmWithLogprobs.invoke("Hello");

console.log(resWithLogprobs.response_metadata.logprobs_result);

安全设置

默认情况下，当前版本的 Gemini 已关闭安全设置。如果您想为各种类别启用安全设置，可以使用模型的 safetySettings 属性。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle({
  model: "gemini-2.5-flash",
  safetySettings: [
    {
      category: "HARM_CATEGORY_HARASSMENT",
      threshold: "BLOCK_LOW_AND_ABOVE",
    },
  ],
});

结构化输出

您可以使用 withStructuredOutput 方法从模型获取结构化的 JSON 输出。

import { ChatGoogle } from "@langchain/google";
import { z } from "zod";

const llm = new ChatGoogle("gemini-2.5-flash");

const schema = z.object({
  people: z.array(z.object({
    name: z.string().describe("人名"),
    age: z.number().describe("年龄"),
  })),
});

const structuredLlm = llm.withStructuredOutput(schema);

const res = await structuredLlm.invoke("John is 25 and Jane is 30.");
console.log(res);

{
  "people": [
    { "name": "John", "age": 25 },
    { "name": "Jane", "age": 30 }
  ]
}

工具调用

ChatGoogle 支持标准的 LangChain 工具调用以及 Gemini 特有的“专业工具”（如代码执行和基于特定来源的增强响应）。

标准工具

您可以使用通过 Zod 模式定义的标准 LangChain 工具。

import { ChatGoogle } from "@langchain/google";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const weatherTool = tool((input) => {
  return "晴天，气温 75 华氏度。";
}, {
  name: "get_weather",
  description: "获取某地的天气",
  schema: z.object({
    location: z.string(),
  }),
});

const llm = new ChatGoogle("gemini-2.5-flash")
  .bindTools([weatherTool]);

const res = await llm.invoke("What is the weather in SF?");
console.log(res.tool_calls);

专业工具

Gemini 提供了几种内置工具，用于代码执行和基于特定来源的响应。

您不能在同一个请求中将这些“特殊工具”（如代码执行、Google 搜索等）与标准的 LangChain 工具（如上面的天气工具）混用。

代码执行

Gemini 模型支持代码执行，允许模型生成并运行 Python 代码来解决复杂问题。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle("gemini-2.5-flash")
  .bindTools([
    {
      codeExecution: {},
    },
  ]);

const res = await llm.invoke("计算第 100 个斐波那契数。");
console.log(res.contentBlocks);

使用 Google 搜索增强响应

您可以使用 googleSearch 工具通过 Google 搜索来增强响应。这对于有关当前事件或特定事实的问题非常有用。

为保持向后兼容，保留了 googleSearchRetrieval 工具，但推荐使用 googleSearch。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle("gemini-2.5-flash")
  .bindTools([
    {
      googleSearch: {},
    },
  ]);

const res = await llm.invoke("最新的世界大赛冠军是谁？");
console.log(res.text);

使用 URL 内容增强响应

您也可以使用特定的 URL 来增强响应。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle("gemini-2.5-flash")
  .bindTools([
    {
      urlContext: {},
    },
  ]);

const prompt = "请总结此页面：https://js.langchain.com/";
const res = await llm.invoke(prompt);
console.log(res.text);

使用数据存储区增强响应

如果您使用的是 Vertex AI（platformType: "gcp"），可以使用 Vertex AI Search 数据存储区来增强响应。

import { ChatGoogle } from "@langchain/google";

const projectId = "YOUR_PROJECT_ID";
const datastoreId = "YOUR_DATASTORE_ID";

const searchRetrievalToolWithDataset = {
  retrieval: {
    vertexAiSearch: {
      datastore: `projects/${projectId}/locations/global/collections/default_collection/dataStores/${datastoreId}`,
    },
    disableAttribution: false,
  },
};

const llm = new ChatGoogle({
  model: "gemini-2.5-pro",
  platformType: "gcp",
}).bindTools([searchRetrievalToolWithDataset]);

const res = await llm.invoke(
  "阿根廷对玻利维亚的足球赛比分是多少？"
);
console.log(res.text);

上下文缓存

默认情况下，Gemini 模型会进行隐式上下文缓存。如果您发送给 Gemini 的历史记录开头与 Gemini 缓存中的上下文完全匹配，则将降低该请求的 token 成本。您也可以显式地将某些内容发送给模型一次，缓存输入 token，然后在后续请求中引用这些缓存的 token，以降低成本和延迟。LangChain 不支持创建此类显式缓存，但如果您已创建了缓存，可以在调用中引用它。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle("gemini-2.5-pro");

// 将缓存名称传递给模型
const res = await llm.invoke("总结这份文档", {
  cachedContent: "projects/123/locations/us-central1/cachedContents/456",
});

多模态请求

ChatGoogle 模型支持多模态请求，允许您在发送文本的同时发送图像、音频和视频。您可以在消息中使用 contentBlocks 字段以结构化的方式提供这些输入。

图像

import { ChatGoogle } from "@langchain/google";
import { HumanMessage } from "@langchain/core/messages";
import * as fs from "fs";

const llm = new ChatGoogle("gemini-2.5-flash");

const image = fs.readFileSync("./hotdog.jpg").toString("base64");

const res = await llm.invoke([
  new HumanMessage({
    contentBlocks: [
      {
        type: "text",
        text: "这张图片里有什么？",
      },
      {
        type: "image",
        mimeType: "image/jpeg",
        data: image,
      },
    ],
  }),
]);

console.log(res.text);

音频

const audio = fs.readFileSync("./speech.wav").toString("base64");

const res = await llm.invoke([
  new HumanMessage({
    contentBlocks: [
      {
        type: "text",
        text: "总结这段音频。",
      },
      {
        type: "audio",
        mimeType: "audio/wav",
        data: audio,
      },
    ],
  }),
]);

console.log(res.text);

视频

const video = fs.readFileSync("./movie.mp4").toString("base64");

const res = await llm.invoke([
  new HumanMessage({
    contentBlocks: [
      {
        type: "text",
        text: "描述这个视频。",
      },
      {
        type: "video",
        mimeType: "video/mp4",
        data: video,
      },
    ],
  }),
]);

console.log(res.text);

推理 / 思考

Google 的 Gemini 2.5 和 Gemini 3 模型支持“思考”或“推理”步骤。即使您没有明确配置，这些模型也可能执行推理，但本库仅当您明确设置推理/思考量的值时，才会返回推理摘要（思考块）。本库在各模型之间提供兼容性，允许您使用统一的参数：

maxReasoningTokens（或 thinkingBudget）：指定用于推理的最大 token 数量。
- 0：关闭推理（如果支持）。
- -1：使用模型默认值。
- > 0：设置特定的 token 预算。
reasoningEffort（或 thinkingLevel）：设置相对推理力度。
- 可选值："minimal"、"low"、"medium"、"high"。

import { ChatGoogle } from "@langchain/google";

const llm = new ChatGoogle({
  model: "gemini-3.1-pro-preview",
  reasoningEffort: "high",
});

const res = await llm.invoke("144 的平方根是多少？");

// 推理步骤可在 contentBlocks 中获取
const reasoningBlocks = res.contentBlocks.filter((block) => block.type === "reasoning");
reasoningBlocks.forEach((block) => {
  if (block.type === "reasoning") {
    console.log("思考过程:", block.reasoning);
  }
});

console.log("答案:", res.text);

思考块还包含一个 reasoningContentBlock 字段。它包含基于 Gemini 发送的底层部分的 ContentBlock。虽然这通常是一个文本块，但对于像 Nano Banana Pro 这样的多模态模型，它可能是图像或其他媒体块。

使用 Nano Banana 和 Nano Banana Pro 进行图像生成

要生成图像，您需要使用支持此功能的模型（例如 gemini-2.5-flash-image），并将 responseModalities 配置为包含 "IMAGE"。

import { ChatGoogle } from "@langchain/google";
import * as fs from "fs";

const llm = new ChatGoogle({
  model: "gemini-2.5-flash-image",
  responseModalities: ["IMAGE", "TEXT"],
});

const res = await llm.invoke(
  "我想看一幅房子画，头上太阳高照。用蜡笔画的风格。"
);

// 生成的图像在消息的 contentBlocks 中返回
for (const [index, block] of res.contentBlocks.entries()) {
  if (block.type === "file" && block.data) {
    const base64Data = block.data;
    // 根据 MIME 类型确定正确的文件扩展名
    const mimeType = (block.mimeType || "image/png").split(";")[0];
    const extension = mimeType.split("/")[1] || "png";
    const filename = `generated_image_${index}.${extension}`;

    // 将图像保存到文件
    fs.writeFileSync(filename, Buffer.from(base64Data, "base64"));
    console.log(`[图像已保存至 ${filename}]`);
  } else if (block.type === "text") {
    console.log(block.text);
  }
}

语音生成（TTS）

某些 Gemini 模型支持生成语音（音频输出）。要启用此功能，请将 responseModalities 配置为包含 "AUDIO"，并提供 speechConfig。 speechConfig 可以是一个完整的 Gemini 语音配置对象，但在大多数情况下，您只需要提供一个包含预构建语音名称的字符串。许多模型以原始 PCM 格式（audio/L16）返回音频，这需要添加 WAV 文件头才能被大多数媒体播放器播放。

import { ChatGoogle } from "@langchain/google";
import * as fs from "fs";

const llm = new ChatGoogle({
  model: "gemini-2.5-flash-preview-tts",
  responseModalities: ["AUDIO", "TEXT"],
  speechConfig: "Zubenelgenubi", // 预构建的语音名称
});

const res = await llm.invoke("请高兴地说：祝您拥有美好的一天！");

// 为原始 PCM 数据添加 WAV 文件头的函数
function addWavHeader(pcmData: Buffer, sampleRate = 24000) {
  const header = Buffer.alloc(44);
  header.write("RIFF", 0);
  header.writeUInt32LE(36 + pcmData.length, 4);
  header.write("WAVE", 8);
  header.write("fmt ", 12);
  header.writeUInt32LE(16, 16);
  header.writeUInt16LE(1, 20); // PCM
  header.writeUInt16LE(1, 22); // 单声道
  header.writeUInt32LE(sampleRate, 24);
  header.writeUInt32LE(sampleRate * 2, 28); // 字节率（16 位单声道）
  header.writeUInt16LE(2, 32); // 块对齐
  header.writeUInt16LE(16, 34); // 每个样本的位数
  header.write("data", 36);
  header.writeUInt32LE(pcmData.length, 40);
  return Buffer.concat([header, pcmData]);
}

// 生成的音频在 contentBlocks 中返回
for (const [index, block] of res.contentBlocks.entries()) {
  if (block.type === "file" && block.data) {
    let audioBuffer = Buffer.from(block.data, "base64");
    let filename = `generated_audio_${index}.wav`;

    if (block.mimeType?.startsWith("audio/L16")) {
      audioBuffer = addWavHeader(audioBuffer);
    } else if (block.mimeType) {
      // 忽略 mimeType 中的参数，例如 "; rate=24000"
      const mimeType = block.mimeType.split(";")[0];
      const extension = mimeType.split("/")[1] || "wav";
      filename = `generated_audio_${index}.${extension}`;
    }

    // 将音频保存到文件
    fs.writeFileSync(filename, audioBuffer);
    console.log(`[音频已保存至 ${filename}]`);
  } else if (block.type === "text") {
    console.log(block.text);
  }
}

多说话人 TTS

您还可以为单个请求配置多个说话人。这有助于让 Gemini 朗读剧本。为此，简化的 speechConfig 要求您为每个代表声音的预定义 name 分配一个 speaker，然后在剧本中使用该说话人。

const multiSpeakerLlm = new ChatGoogle({
  model: "gemini-2.5-flash-preview-tts",
  responseModalities: ["AUDIO"],
  speechConfig: [
    { speaker: "Joe", name: "Kore" },
    { speaker: "Jane", name: "Puck" },
  ],
});

const res = await multiSpeakerLlm.invoke(`
  Joe: 今天过得怎么样，Jane？
  Jane: 还不错，你呢？
`);

API 参考

有关所有 ChatGoogle 功能和配置的详细文档，请参阅 API 参考。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​概览

​集成详情

​模型特性

​设置

​通过 AI Studio 获取凭证（API 密钥）

​通过 Vertex AI 快速模式获取凭证（API 密钥）

​通过 Vertex AI 获取凭证（OAuth 应用默认凭证 / ADC）

​通过 Vertex AI 获取凭证（OAuth 已保存的凭据）

​追踪

​安装

​实例化

​Google AI（AI Studio）

​Vertex AI

​Vertex AI 快速模式

​模型配置最佳实践

​调用

​响应元数据

​Token 用量

​Logprobs

​安全设置

​结构化输出

​工具调用

​标准工具

​专业工具

​代码执行

​使用 Google 搜索增强响应

​使用 URL 内容增强响应

​使用数据存储区增强响应

​上下文缓存

​多模态请求

​图像

​音频

​视频

​推理 / 思考

​使用 Nano Banana 和 Nano Banana Pro 进行图像生成

​语音生成（TTS）

​多说话人 TTS

​API 参考

概览

集成详情

模型特性

设置

通过 AI Studio 获取凭证（API 密钥）

通过 Vertex AI 快速模式获取凭证（API 密钥）

通过 Vertex AI 获取凭证（OAuth 应用默认凭证 / ADC）

通过 Vertex AI 获取凭证（OAuth 已保存的凭据）

追踪

安装

实例化

Google AI（AI Studio）

Vertex AI

Vertex AI 快速模式

模型配置最佳实践

调用

响应元数据

Token 用量

Logprobs

安全设置

结构化输出

工具调用

标准工具

专业工具

代码执行

使用 Google 搜索增强响应

使用 URL 内容增强响应

使用数据存储区增强响应

上下文缓存

多模态请求

图像

音频

视频

推理 / 思考

使用 Nano Banana 和 Nano Banana Pro 进行图像生成

语音生成（TTS）

多说话人 TTS

API 参考