Google Vertex 是一项服务，它开放了 Google Cloud 中可用的所有基础模型，比如 gemini-2.5-pro、gemini-2.5-flash 等。 它还提供一些非 Google 的模型，例如 Anthropic’s Claude。 本指南将帮助你快速上手 ChatVertexAI 聊天模型。有关所有 ChatVertexAI 功能和配置的详细文档，请查阅 API 参考。
此库将被弃用此库将被 ChatGoogle 库取代。 新的实现应改用 ChatGoogle 库，现有的实现也应考虑迁移。

​
概览

​
集成详情

类包可序列化Python 支持下载量版本
ChatVertexAI@langchain/google-vertexai✅✅NPM - DownloadsNPM - Version

​
模型功能

请参阅下表标题中的链接，了解如何使用特定功能的指南。
工具调用结构化输出图片输入音频输入视频输入Token 级别的流式传输Token 用量Logprobs
✅✅✅✅✅✅✅✅
请注意，虽然支持 logprobs，但 Gemini 对其使用有较为严格的限制。

​
设置

LangChain.js 支持两种不同的身份验证方法，具体取决于你是在 Node.js 环境还是 Web 环境中运行。它还支持 Vertex AI Express 模式使用的身份验证方法，无论使用哪个包都可。 要访问 ChatVertexAI 模型，你需要在 Google Cloud Platform (GCP) 账户中设置 Google VertexAI，保存凭据文件，并安装 @langchain/google-vertexai 集成包。在 Node.js 中，该包使用 @langchain/google-gauth 进行身份验证（无需单独安装）。

​
凭据

前往你的 GCP 账户 生成凭据文件。完成后，设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量： 
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/credentials.json"
或者，你可以在本地机器上运行 gcloud auth application-default login 来使用应用默认凭据。 如果在 Web 环境中运行，请安装 @langchain/google-vertexai-web 包（该包使用 @langchain/google-webauth 进行身份验证）。在 GOOGLE_WEB_CREDENTIALS 中设置服务账号 JSON： 
export GOOGLE_WEB_CREDENTIALS='{"type":"service_account","project_id":"YOUR_PROJECT-12345",...}'
也支持 GOOGLE_VERTEX_AI_WEB_CREDENTIALS，但已弃用。 如果你使用的是 Vertex AI Express 模式，可以安装 @langchain/google-vertexai 或 @langchain/google-vertexai-web 包。 然后，前往 Express Mode API 密钥页面，在 GOOGLE_API_KEY 环境变量中设置你的 API 密钥： 
export GOOGLE_API_KEY="api_key_value"
如果你想自动跟踪模型调用，也可以设置 LangSmith API 密钥（取消下方注释）： 
# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

​
安装

LangChain 的 ChatVertexAI 集成位于 @langchain/google-vertexai 包中： 
npm install @langchain/google-vertexai @langchain/core
如果在 Web 环境（如 Vercel Edge function）中使用： 
npm install @langchain/google-vertexai-web @langchain/core

​
实例化

现在我们可以实例化模型对象并生成聊天补全： 
import { ChatVertexAI } from "@langchain/google-vertexai"
// 如果在 Web 环境中运行，请取消注释下面这行：
// import { ChatVertexAI } from "@langchain/google-vertexai-web"

const llm = new ChatVertexAI({
    model: "gemini-2.5-flash",
    temperature: 0,
    maxRetries: 2,
    // 对于 Web 环境，使用 authOptions.credentials
    // authOptions: { ... }
    // 其他参数...
})

​
调用

const aiMsg = await llm.invoke([
    [
        "system",
        "你是一个乐于助人的助手，将英语翻译成法语。翻译用户的句子。",
    ],
    ["human", "I love programming."],
])
aiMsg

AIMessageChunk {
  "content": "J'adore programmer. \n",
  "additional_kwargs": {},
  "response_metadata": {},
  "tool_calls": [],
  "tool_call_chunks": [],
  "invalid_tool_calls": [],
  "usage_metadata": {
    "input_tokens": 20,
    "output_tokens": 7,
    "total_tokens": 27
  }
}

console.log(aiMsg.content)

J'adore programmer.

​
使用 Google 搜索检索进行工具调用

可以调用带有 Google 搜索工具的模型，利用该工具将内容生成 [扎根] (https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/grounding) 于现实世界信息，减少幻觉。 gemini-2.0-flash-exp 目前不支持扎根功能。 你可以选择使用 Google 搜索或自定义数据存储进行扎根。以下是两种方式的示例：

​
Google 搜索检索

使用 Google 搜索的扎根示例： 
import { ChatVertexAI } from "@langchain/google-vertexai"

const searchRetrievalTool = {
  googleSearchRetrieval: {
    dynamicRetrievalConfig: {
      mode: "MODE_DYNAMIC", // 使用动态检索
      dynamicThreshold: 0.7, // 动态检索的默认阈值
    },
  },
};

const searchRetrievalModel = new ChatVertexAI({
  model: "gemini-2.5-pro",
  temperature: 0,
  maxRetries: 0,
}).bindTools([searchRetrievalTool]);

const searchRetrievalResult = await searchRetrievalModel.invoke("谁赢得了 2024 年 NBA 总决赛？");

console.log(searchRetrievalResult.content);

波士顿凯尔特人队赢得了 2024 年 NBA 总决赛，以 4-1 击败达拉斯独行侠队，夺得队史第 18 个 NBA 总冠军。这是他们自 2008 年以来的首个冠军，并使他们成为夺得 NBA 总冠军次数最多的球队，超过了洛杉矶湖人队的 17 个冠军。

​
使用数据存储的 Google 搜索检索

首先，设置你的数据存储（以下为示例数据存储的架构）：
ID日期队伍 1比分队伍 2
30012023-09-07Argentina1 - 0Ecuador
30022023-09-12Venezuela1 - 0Paraguay
30032023-09-12Chile0 - 0Colombia
30042023-09-12Peru0 - 1Brazil
30052024-10-15Argentina6 - 0Bolivia
然后，在下面提供的示例中使用这个数据存储： （注意，你需要使用自己变量 projectId 和 datastoreId） 
import { ChatVertexAI } from "@langchain/google-vertexai";

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 searchRetrievalModelWithDataset = new ChatVertexAI({
  model: "gemini-2.5-pro",
  temperature: 0,
  maxRetries: 0,
}).bindTools([searchRetrievalToolWithDataset]);

const searchRetrievalModelResult = await searchRetrievalModelWithDataset.invoke(
  "阿根廷对玻利维亚足球比赛的比分是多少？"
);

console.log(searchRetrievalModelResult.content);

阿根廷队在 2024 年 10 月 15 日以 6-0 战胜了玻利维亚队。
你应该会得到基于所提供数据存储的结果。

​
上下文缓存

Vertex AI 提供上下文缓存功能，通过存储和重复使用跨多次 API 请求的长段消息内容来帮助优化成本。当你拥有较长的对话历史或频繁出现的消息段落时，此功能特别有用。 要使用此功能，请先按照 官方指南 创建上下文缓存。 创建缓存后，可以将其 ID 作为运行时参数传递，如下所示： 
import { ChatVertexAI } from "@langchain/google-vertexai";

const modelWithCachedContent = new ChatVertexAI({
  model: "gemini-2.5-pro-002",
  location: "us-east5",
});

await modelWithCachedContent.invoke("内容中有什么？", {
  cachedContent:
    "projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID",
});
你也可以将此字段直接绑定到模型实例上： 
const modelWithBoundCachedContent = new ChatVertexAI({
  model: "gemini-2.5-pro-002",
  location: "us-east5",
}).bind({
  cachedContent:
    "projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID",
});
请注意，并非所有模型当前都支持上下文缓存。

​
API 参考

有关所有 ChatVertexAI 功能和配置的详细文档，请查阅 API 参考。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.