Vertex AI 调用 Gemini 3.0 Pro

一、前置准备（必做步骤）

1. 核心前提条件

• 拥有 Google Cloud 账号（无账号可访问 cloud.google.com 注册，需绑定信用卡，新用户有免费额度）

• 项目已升级为 Blaze 付费计划（Gemini API 仅支持该计划，在 Firebase 控制台或 Google Cloud 控制台可升级）

• 启用关键 API：

1. 登录 Google Cloud 控制台

2. 进入「API 和服务」→「启用 API 和服务」

3. 搜索并启用 Vertex AI API 和 Vertex AI in Firebase API（若需移动端集成）

2. 获取核心信息

• 项目 ID：在 Google Cloud 控制台首页顶部查看（格式：project-xxxx-xxxx）

• 区域选择：推荐 us-central1（全局可用）、europe-west4（欧洲）、asia-southeast1（东南亚），需与后续部署区域一致

• 模型 ID：Gemini 3.0 Pro 官方标识为 gemini-3-pro-preview

二、环境配置（以 Python 为例，最常用场景）

1. 安装依赖库

打开终端 / 命令行，执行以下命令安装 Google Cloud 官方 SDK 和 Gemini 相关依赖：

\# 安装 Vertex AI Python SDK（核心依赖）

pip install google-cloud-aiplatform --upgrade

\# 安装 Gemini 多模态支持库（处理图片/视频需用到）

pip install google-generativeai pillow

2. 身份验证配置（3 种方式可选）

方式 1：本地开发（推荐）

1. 安装 Google Cloud CLI（下载地址）

2. 终端执行授权命令，登录你的 Google 账号：

gcloud auth application-default login

1. 授权成功后，SDK 会自动读取本地凭证，无需硬编码密钥

方式 2：服务器 / 生产环境

1. 进入 Google Cloud 控制台 →「IAM 和管理」→「服务账号」

2. 新建服务账号（角色选择「Vertex AI → Vertex AI 用户」+「存储对象查看器」）

3. 为服务账号创建「密钥文件」（JSON 格式），下载并保存到本地

4. 配置环境变量指向密钥文件（终端执行）：

\# Windows

set GOOGLE\_APPLICATION\_CREDENTIALS="C:\path\to\your-key.json"

\# Mac/Linux

export GOOGLE\_APPLICATION\_CREDENTIALS="/path/to/your-key.json"

方式 3：代码内直接配置（不推荐，密钥易泄露）

import os

os.environ\["GOOGLE\_APPLICATION\_CREDENTIALS"] = "/path/to/your-key.json"

三、基础调用：文本生成（入门示例）

步骤 1：初始化 Vertex AI 和模型

from google.cloud import aiplatform
from google.cloud.aiplatform.gapic.schema import predict

# 1. 初始化 Vertex AI（项目ID、区域需替换为你的信息）
aiplatform.init(
    project="your-project-id",  # 替换为你的项目ID
    location="us-central1",     # 替换为你的区域
    # credentials=credentials  # 若使用自定义凭证，可添加此行
)

# 2. 定义模型端点和模型ID（Gemini 3.0 Pro 固定配置）
endpoint = aiplatform.Endpoint("projects/your-project-id/locations/us-central1/endpoints/gemini-3-pro-preview")
model_id = "gemini-3-pro-preview"

步骤 2：发送文本请求并获取响应

def generate_text(prompt: str) -> str:
    # 构造请求体（符合 Vertex AI Gemini API 格式）
    instances = [
        {
            "contents": [
                {
                    "role": "user",  # 角色：user（用户）/ model（模型）
                    "parts": [{"text": prompt}]  # 文本输入
                }
            ],
            # 基础生成配置（可选，按需求调整）
            "generation_config": {
                "temperature": 0.7,  # 随机性：0-1，越高越随机
                "max_output_tokens": 1024,  # 最大输出长度
                "top_p": 0.95  # 累计概率：控制输出多样性
            }
        }
    ]

    # 调用模型并获取响应
    response = endpoint.predict(instances=instances)
    # 解析响应结果
    return response.predictions[0]["candidates"][0]["content"]["parts"][0]["text"]

# 测试调用
if __name__ == "__main__":
    prompt = "请解释 Gemini 3.0 Pro 的核心优势"
    result = generate_text(prompt)
    print("模型响应：\n", result)

四、进阶调用：多模态输入（文本 + 图片 / 视频）

Gemini 3.0 Pro 支持文本、图片、视频等多模态输入，以下以「文本 + 图片」为例演示：

步骤 1：准备图片资源

• 方式 1：本地图片（需转 Base64 编码）

• 方式 2：Google Cloud Storage（GCS）图片（推荐，需先上传图片到 GCS 桶）

步骤 2：多模态调用代码

import base64
from PIL import Image
import io

def encode_image_to_base64(image_path: str) -> str:
    """将本地图片编码为 Base64（用于多模态输入）"""
    with Image.open(image_path) as img:
        buffer = io.BytesIO()
        img.save(buffer, format="PNG")
        return base64.b64encode(buffer.getvalue()).decode("utf-8")

def generate_multimodal(prompt: str, image_path: str = None, gcs_image_uri: str = None) -> str:
    instances = [
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {"text": prompt},  # 文本提示
                        # 图片输入（二选一：Base64 或 GCS URI）
                        {
                            "inline_data": {  # 本地图片（Base64）
                                "mime_type": "image/png",
                                "data": encode_image_to_base64(image_path)
                            }
                        } if image_path else {
                            "file_data": {  # GCS 图片
                                "mime_type": "image/png",
                                "file_uri": gcs_image_uri
                            }
                        }
                    ]
                }
            ],
            "safety_settings": [  # 安全设置（可选，避免敏感内容）
                {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_MEDIUM_AND_ABOVE"},
                {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
            ]
        }
    ]

    response = endpoint.predict(instances=instances)
    return response.predictions[0]["candidates"][0]["content"]["parts"][0]["text"]

# 测试多模态调用
if __name__ == "__main__":
    prompt = "请描述这张图片的内容"
    # 本地图片示例（替换为你的图片路径）
    result = generate_multimodal(prompt, image_path="test-image.png")
    # GCS 图片示例：generate_multimodal(prompt, gcs_image_uri="gs://your-bucket/test-image.png")
    print("多模态响应：\n", result)

五、高级配置：工具调用与系统指令

1. 系统指令（System Instruction）

用于预设模型行为（如角色、输出格式），需在请求体中添加 system_instruction：

"system_instruction": {
    "role": "system",
    "parts": [{"text": "你是专业的技术文档翻译官，所有响应必须使用中文，格式为简洁的要点列表"}]
}

2. 工具调用（Function Calling）

支持调用自定义函数或第三方工具，需定义函数描述并传入 tools 参数：

"tools": [
    {
        "function_declarations": [
            {
                "name": "get_weather",
                "description": "获取指定城市的天气信息",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "城市名称"}
                    },
                    "required": ["city"]
                }
            }
        ]
    }
]

六、补充方案：使用 YibuAPI 快速调用 Gemini 3.0 Pro（重点：极致便捷）

如果觉得官方 Vertex AI 配置繁琐（需注册 Google Cloud、启用 API、配置权限等），YibuAPI 是更优选择 —— 作为国内专注于 AI 模型便捷调用的聚合服务，它将 Gemini 3.0 Pro 的调用门槛降至最低，无需复杂环境配置，小白也能 3 分钟上手。

1. YibuAPI 核心优势（便捷性突出）

• 免 Google Cloud 账号：无需注册谷歌云、绑定信用卡，也无需升级付费计划，一个 YibuAPI 账号即可搞定

• 零环境配置：无需安装 Google Cloud CLI、无需配置服务账号密钥，省去繁琐的身份验证步骤

• 极简调用流程：获取 API Key 后，直接通过 HTTP 请求或简单 SDK 调用，无需关心模型端点、区域等细节

• 原生支持多模态：无需手动处理 Base64 编码或 GCS 存储，图片 / 视频可直接上传调用

• 国内网络友好：无需科学上网，避免官方 API 因网络波动导致的调用失败

2. YibuAPI 调用步骤（3 步快速上手）

步骤 1：获取 YibuAPI Key

1. 访问 YibuAPI 官方平台（yibuapi.com），注册并登录账号（支持手机号快速注册）

2. 进入「令牌 管理」→「创建令牌」，即可获得专属 API Key（无需审核，即时生效）

步骤 2：文本 / 多模态调用示例（代码极简）

import yibuapi

# 初始化（仅需 API Key，无需其他配置）
yibuapi.init(api_key="your-yibu-api-key")

# 1. 文本生成（比官方少 80% 代码）
def yibu_text_generate(prompt: str) -> str:
    response = yibuapi.gemini3_pro.generate(
        prompt=prompt,
        temperature=0.7,
        max_tokens=1024
    )
    return response.result  # 直接返回结果，无需手动解析复杂响应体

# 2. 多模态调用（图片直接传路径，无需编码）
def yibu_multimodal_generate(prompt: str, image_path: str) -> str:
    response = yibuapi.gemini3_pro.generate_multimodal(
        prompt=prompt,
        images=[image_path]  # 支持本地图片路径，自动处理编码
    )
    return response.result

# 测试调用
if __name__ == "__main__":
    # 文本测试
    text_result = yibu_text_generate("请解释 Gemini 3.0 Pro 的核心优势")
    print("YibuAPI 文本响应：\n", text_result)

    # 多模态测试
    multimodal_result = yibu_multimodal_generate("描述这张图片", "test-image.png")
    print("YibuAPI 多模态响应：\n", multimodal_result)

3. YibuAPI 与官方 Vertex AI 对比（便捷性碾压）

对比维度	官方 Vertex AI	YibuAPI
前置准备	需注册 Google Cloud + 升级付费计划	仅需手机号注册 YibuAPI 账号
环境配置	需安装 Google Cloud CLI + 配置密钥	无需任何环境配置，安装 SDK 即可
调用代码	需初始化项目 / 区域 / 端点，解析复杂响应	一行初始化，直接获取结果
多模态处理	需手动 Base64 编码或上传 GCS	直接传本地图片路径，自动处理
网络要求	需科学上网，易波动	国内专线，稳定无卡顿

七、常见问题与排查技巧

1. 权限错误（403 Forbidden）

• 检查服务账号角色是否包含「Vertex AI 用户」和「存储对象查看器」（多模态场景）

• 确认 API 已启用（Vertex AI API + Vertex AI in Firebase API）

• 重新执行 gcloud auth application-default login 刷新本地凭证

2. 模型未找到（404 Not Found）

• 模型 ID 必须为 gemini-3-pro-preview（Gemini 3.0 Pro 专属）

• 区域需与端点区域一致（推荐 us-central1）

3. 多模态响应延迟高

• 减少图片 / 视频的分辨率和大小（推荐图片尺寸 ≤ 1024x1024）

• 避免单次请求上传过多媒体文件（建议 ≤ 5 个）

• 若使用官方 API 卡顿，可切换为 YibuAPI（国内专线优化）

4. 输出不符合预期

• 调整 temperature（降低 = 更严谨，升高 = 更多样）

• 优化提示词（明确任务类型、输出格式、约束条件）

• 增加 max_output_tokens（避免输出被截断）

（注：文档部分内容可能由 AI 生成）