tai-ch0802/vertex-ai-api-dev

Google Cloud Vertex AI 上的 Gemini API

透過 Google Cloud Vertex AI 上的 Gemini API，存取 Google 專為企業級應用案例打造的最先進 AI 模型。

提供以下核心功能：

• 文字生成 (Text generation) - 聊天、完成、摘要
• 多模態理解 (Multimodal understanding) - 處理圖片、音訊、影片和文件
• 工具呼叫 (Function calling) - 讓模型呼叫您的自訂函式
• 結構化輸出 (Structured output) - 生成符合您 Schema 的有效 JSON
• 情境快取 (Context caching) - 快取大型上下文以提高效率
• 嵌入 (Embeddings) - 生成文字嵌入以進行語意搜尋
• 即時 API (Live Realtime API) - 適用於低延遲語音和影片互動的雙向串流
• 批次預測 (Batch Prediction) - 處理大量的非同步資料集預測工作負載

核心準則

• 統一的 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。

SDKs

• 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>
    

[!WARNING] 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 Mode)

當使用帶有 API 金鑰的快速模式時，請設定以下變數：

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")

模型 (Models)

• 使用 gemini-3.1-pro-preview 處理複雜推理、編碼、研究 (1M tokens)
• 使用 gemini-3-flash-preview 取得快速、平衡的效能、多模態 (1M tokens)
• 使用 gemini-3-pro-image-preview 進行 Nano Banana Pro 圖片生成與編輯
• 使用 gemini-live-2.5-flash-native-audio 使用 Live Realtime API (包含原生音訊)

如有明確要求，請使用以下模型：

• 使用 gemini-2.5-flash-image 進行 Nano Banana 圖片生成與編輯
• 使用 gemini-2.5-flash
• 使用 gemini-2.5-flash-lite
• 使用 gemini-2.5-pro

[!IMPORTANT] 像是 gemini-2.0-*、gemini-1.5-*、gemini-1.0-*、gemini-pro 等模型為舊版且已棄用。請使用上述新模型。 對於生產環境，請參閱 Vertex AI 文件以取得穩定的模型版本 (例如 gemini-3-flash)。

快速入門 (Quick Start)

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)。

[!TIP] 使用 Developer Knowledge MCP 伺服器：如果可以使用 search_documents 或 get_document 工具，請使用它們直接在上下文中尋找並擷取 Google Cloud 和 Vertex AI 的官方文件。這是獲取最新 API 詳細資訊和程式碼片段的首選方法。

工作流程與程式碼範例

請參考 Python Docs Samples 儲存庫以取得其他程式碼範例和特定使用情境。

根據特定的使用者請求，請參閱以下參考檔案以取得詳細的程式碼範例和使用模式 (Python 範例)：

• 文字與多模態: 聊天、多模態輸入 (圖片、影片、音訊) 和串流。請參閱 references/text_and_multimodal.md
• 嵌入 (Embeddings): 生成文字嵌入以進行語意搜尋。請參閱 references/embeddings.md
• 結構化輸出與工具: JSON 生成、工具呼叫、搜尋增強 (Search Grounding) 和程式碼執行。請參閱 references/structured_and_tools.md
• 媒體生成: 圖片生成、圖片編輯和影片生成。請參閱 references/media_generation.md
• 邊界框偵測 (Bounding Box Detection): 圖片和影片中的物件偵測與定位。請參閱 references/bounding_box.md
• 即時 API (Live API): 用於語音、視覺和文字的即時雙向串流。請參閱 references/live_api.md
• 進階功能: 情境快取 (Content Caching)、批次預測和思考/推理 (Thinking/Reasoning)。請參閱 references/advanced_features.md
• 安全性: 調整負責任的 AI 過濾器和閾值。請參閱 references/safety.md
• 模型微調 (Model Tuning): 監督式微調 (Supervised Fine-Tuning) 和偏好微調 (Preference Tuning)。請參閱 references/model_tuning.md