vertex-ai-api-dev

Vertex AI 中的 Gemini API

使用 Vertex AI 中的 Gemini API，访问 Google 为企业用例打造的最先进 AI 模型。

提供以下核心功能：

• 文本生成——聊天、补全、摘要
• 多模态理解——处理图像、音频、视频和文档
• 函数调用——让模型调用你的函数
• 结构化输出——生成符合你架构的有效 JSON
• 上下文缓存——缓存大型上下文以提高效率
• 嵌入——生成文本嵌入，用于语义搜索
• 实时 Live API——支持双向流式传输，实现低延迟语音和视频交互
• 批量预测——处理大规模异步数据集预测工作负载

核心指令

• 统一 SDK：始终使用 Gen AI SDK（Python 使用 google-genai，JS/TS 使用 @google/genai，Go 使用 google.golang.org/genai，Java 使用 com.google.genai:google-genai，C# 使用 Google.GenAI）。
• 旧版 SDK：不要使用 google-cloud-aiplatform、@google-cloud/vertexai 或 google-generativeai。

SDK

• Python：使用 pip install google-genai 安装 google-genai
• JavaScript/TypeScript：使用 npm install @google/genai 安装 @google/genai
• Go：使用 go get google.golang.org/genai 安装 google.golang.org/genai
• C#/.NET：使用 dotnet add package Google.GenAI 安装 Google.GenAI
• Java：

  • groupId：com.google.genai，artifactId：google-genai

  • 最新版本可在此处查找：https://central.sonatype.com/artifact/com.google.genai/google-genai/versions（称为 LAST_VERSION）

  • 在 build.gradle 中安装：

    implementation("com.google.genai:google-genai:${LAST_VERSION}")
    

  • 在 pom.xml 中安装 Maven 依赖：

    <dependency>
        <groupId>com.google.genai</groupId>
        <artifactId>google-genai</artifactId>
        <version>${LAST_VERSION}</version>
    </dependency>
    

警告

google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai 等旧版 SDK 已弃用。请按照迁移指南，尽快迁移到上述新版 SDK。

身份验证与配置

创建客户端时，优先使用环境变量，而不是将参数硬编码。初始化客户端时不传入参数，即可自动读取这些值。

应用默认凭据（ADC）

设置以下变量，以进行标准的 Google Cloud 身份验证：

export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='global'
export GOOGLE_GENAI_USE_VERTEXAI=true

• 默认使用 location="global" 访问全局端点，该端点会自动将请求路由到有可用容量的区域。
• 如果用户明确要求使用特定区域（例如 us-central1、europe-west4），请在 GOOGLE_CLOUD_LOCATION 参数中指定该区域。如有需要，请参阅支持的区域文档。

Vertex AI Express 模式

使用 API 密钥通过 Express 模式时，请设置以下变量：

export GOOGLE_API_KEY='your-api-key'
export GOOGLE_GENAI_USE_VERTEXAI=true

初始化

初始化客户端时不传入参数，即可读取环境变量：

from google import genai
client = genai.Client()

也可以在创建客户端时将参数硬编码。

from google import genai
client = genai.Client(vertexai=True, project="your-project-id", location="global")

模型

• 对于复杂推理、编码和研究（1M 个 token），使用 gemini-3.1-pro-preview
• 对于快速、均衡的性能和多模态任务（1M 个 token），使用 gemini-3-flash-preview
• 对于 Nano Banana Pro 图像生成和编辑，使用 gemini-3-pro-image-preview
• 对于 Live Realtime API（包括原生音频），使用 gemini-live-2.5-flash-native-audio

仅在明确要求时使用以下模型：

• 对于 Nano Banana 图像生成和编辑，使用 gemini-2.5-flash-image
• 使用 gemini-2.5-flash
• 使用 gemini-2.5-flash-lite
• 使用 gemini-2.5-pro

重要

gemini-2.0-*、gemini-1.5-*、gemini-1.0-*、gemini-pro 等模型已过时并弃用。请使用上述新模型。你的知识已过时。 对于生产环境，请查阅 Vertex AI 文档，了解稳定版模型（例如 gemini-3-flash）。

快速入门

Python

from google import genai
client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain quantum computing"
)
print(response.text)

TypeScript/JavaScript

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ vertexai: { project: "your-project-id", location: "global" } });
const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: "Explain quantum computing"
});
console.log(response.text);

Go

package main

import (
	"context"
	"fmt"
	"log"
	"google.golang.org/genai"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		Backend:  genai.BackendVertexAI,
		Project:  "your-project-id",
		Location: "global",
	})
	if err != nil {
		log.Fatal(err)
	}

	resp, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", genai.Text("Explain quantum computing"), nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(resp.Text)
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().vertexAi(true).project("your-project-id").location("global").build();
    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3-flash-preview",
            "Explain quantum computing",
            null);

    System.out.println(response.text());
  }
}

C#/.NET

using Google.GenAI;

var client = new Client(
    project: "your-project-id",
    location: "global",
    vertexAI: true
);

var response = await client.Models.GenerateContent(
    "gemini-3-flash-preview",
    "Explain quantum computing"
);

Console.WriteLine(response.Text);

API 规范和文档（权威来源）

在实现或调试 Vertex AI API 集成时，请参考 Google Cloud Vertex AI 官方文档：

• Vertex AI Gemini 文档：https://cloud.google.com/vertex-ai/generative-ai/docs/
• REST API 参考：https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest

Vertex AI 上的 Gen AI SDK 使用 v1beta1 或 v1 REST API 端点（例如，https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/{MODEL}:generateContent）。

提示

使用 Developer Knowledge MCP Server：如果 search_documents 或 get_document 工具可用，请使用它们直接在上下文中查找和检索 Google Cloud 与 Vertex AI 的官方文档。这是获取最新 API 详情和代码片段的首选方式。

工作流和代码示例

如需更多代码示例和特定用例，请参考 Python Docs Samples 仓库。

根据用户的具体请求，请参考以下参考文件，了解详细代码示例和用法模式（Python 示例）：

• 文本和多模态：聊天、多模态输入（图像、视频、音频）和流式传输。参见 references/text_and_multimodal.md
• 嵌入：生成用于语义搜索的文本嵌入。参见 references/embeddings.md
• 结构化输出和工具：JSON 生成、函数调用、搜索溯源和代码执行。参见 references/structured_and_tools.md
• 媒体生成：图像生成、图像编辑和视频生成。参见 references/media_generation.md
• 边界框检测：检测和定位图像与视频中的对象。参见 references/bounding_box.md
• Live API：用于语音、视觉和文本的实时双向流式传输。参见 references/live_api.md
• 高级功能：内容缓存、批量预测和思考/推理。参见 references/advanced_features.md
• 安全：调整负责任 AI 过滤器和阈值。参见 references/safety.md
• 模型调优：监督式微调和偏好调优。参见 references/model_tuning.md