获取多模态嵌入

多模态嵌入模型会根据您提供的输入生成多维向量，可以包含图片、文本和视频数据的组合。然后，嵌入向量可用于后续任务，例如图片分类或视频内容审核。

图片和文本嵌入向量位于同一语义空间中，并且具有相同的维度。因此，这些向量可以互换用于应用场景，例如按文本搜索图片或按图片搜索视频。

对于纯文本嵌入用例，我们建议改用 Gemini Enterprise Agent Platform 文本嵌入 API。例如，文本嵌入 API 可能更适合基于文本的语义搜索、聚类、长文档分析以及其他文本检索或问答应用场景。如需了解详情，请参阅获取文本嵌入。

支持的模型

您可以使用以下模型获取多模态嵌入：

  • gemini-embedding-2

  • multimodalembedding@001

最佳做法

使用多模态嵌入模型时，请考虑以下输入方面：

  • 图片中的文本 - 模型可以区分图片中的文本，类似于光学字符识别 (OCR)。如果您需要区分图片内容的说明和图片中的文本，请考虑使用提示工程来指定目标内容。例如：根据您的用例，指定“picture of a cat”或“the text 'cat”，而不只是“cat”。




    the text 'cat'
    “cat”一词以粗体字体显示。
    以粗体大号字体呈现的“猫”字样。




    picture of a cat
    一只猫坐在木地板上。
    图片来源：Manja Vitolic on Unsplash。
  • 嵌入相似度 - 嵌入的点积不是校准的概率。点积是相似度指标，不同用例的得分分布可能不同。因此，请避免使用固定值阈值来衡量质量。请改用排名方法进行检索，或使用 sigmoid 进行分类。

使用 gemini-embedding-2

gemini-embedding-2 模型接受图片、文本、文档、音频和视频模态的交错输入。

指定任务说明以提高性能

您可以将嵌入用于各种任务，从分类到文档搜索。指定正确的任务指令有助于针对预期关系优化嵌入，从而最大限度地提高准确性和效率。

下表展示了如何使用 gemini-embedding-2 模型针对对称和非对称用例设置查询和文档的格式。

检索用例（非对称格式）

使用场景 查询结构 文档结构
搜索查询 task: search result | query: {content} title: {title} | text: {content}

如果没有标题，则使用 title: none。
问答 task: question answering | query: {content} title: {title} | text: {content}
事实核查 task: fact checking | query: {content} title: {title} | text: {content}
代码检索 task: code retrieval | query: {content} title: {title} | text: {content}

单输入源用例（对称格式）

使用场景 输入结构
分类 task: classification | query: {content}
聚簇 task: clustering | query: {content}
语义相似度 task: sentence similarity | query: {content}

请勿将此方法用于搜索或检索。它旨在用于语义文本相似度。

Python 中的使用示例

Python

# Generate embedding for a search query
def prepare_query(query):
    return f"task: search result | query: {query}"

# Generate embedding for a search document
def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

# Generate embedding for classification
def prepare_classification_input(content):
    return f"task: classification | query: {content}"

API 用量

API 限额

使用 gemini-embedding-2 模型时，存在以下限制。

限制 值和说明
文本、图片、文档、视频和音频数据
输入 token 限制 8192 个词元

超过 8192 个词元的输入会以静默方式截断。所有模态共享总共 8192 个 token 的上下文窗口。各种模态的 token 数量计算方式如下：
  • 音频：每秒 25 个 token
  • 视频：每帧 66 个 token
  • 图片：每张图片 258 个 token
  • 文档 (PDF)：呈现为图片，因此每页 258 个 token。如果启用了 OCR，则会提取额外的文本令牌。
输出维度 3072（默认值，可使用 output_dimensionality 参数进行配置）
图片限制 每个请求 6 张图片
图片格式 JPEG、PNG、WebP、BMP、HEIC、HEIF、AVIF
图片尺寸 每张图片的像素数上限为 16384 x 16384
文档限制 每个申请 1 个文件，最多 6 页

我们强烈建议每个 PDF 文件包含 1 页，以获得最佳质量。
文档格式 PDF
视频和音频数据
视频限制 每个请求 1 个视频，最多 120 帧

120 秒的限制基于默认的 1 FPS 设置。设置不同的 FPS 时，时长会有所不同：时长 = 120 / FPS。
默认情况下，系统会针对视频停用音频提取功能。启用音轨提取选项后，时长不得超过音频时长上限 180 秒，并且视频总时长会受到音频时长上限和 token 上下文窗口（8192 个 token）的限制。
视频格式 容器：MOV、MP4。编解码器：AV1、H264、H265、VP9。
音频限制 每个请求 180 秒

音频支持针对语音进行了优化。环境声音和音乐可能无法以最高音质播放。
音频格式 MP3、WAV

视频时长（含音频提取）

由于所有模态共享总共 8192 个 token 的上下文窗口，因此启用 audio_track_extraction 后，视频时长上限会有所不同：

模态 token 数量
音频 每秒 25 个 token
视频帧 每帧 66 个 token
时间戳 每秒 10 个 token（每秒两个时间戳，格式为“mm:ss”）
FPS 由 FPS 设置决定（默认值为 1）

视频总时长受音频支持时长上限（180 秒）和 8192 个 token 的上下文窗口的限制。

计算示例：

如果您以 1 FPS 的默认采样率处理视频并启用音频提取功能，则：

  • 消耗率：每秒视频消耗 66 个 token（1 帧）+ 25 个 token（1 秒音频）+ 10 个 token（时间戳）= 101 个 token。
  • 时长上限：在 8192 个词元的限制下，时长上限约为 8192 / 101 ≈ 81 秒。

如果输入内容超出上下文窗口，超出部分将被静默截断。

获取多模态嵌入

REST

PROJECT_ID="YOUR_PROJECT_ID"
LOCATION="us"

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.${LOCATION}.rep.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/gemini-embedding-2:embedContent" \
  -d '{
  "content": {
    "parts": [
      {
        "text": "Whats this"
      },
      {
        "file_data": {
          "mime_type": "video/mp4",
          "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"
        }
      }
    ]
  }
}'

Python

from google import genai
from google.genai import types

# Initialize the client.
client = genai.Client(vertexai=True, project="YOUR_PROJECT_ID", location="us")

content = types.Content(
    parts=[
        types.Part.from_text(text="Audio AI"),
        types.Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/audio/Chirp-3-Docs-Dive.mp3",
            mime_type="audio/mpeg",
        ),
    ],
)

response = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[content]
)

print(response.embeddings[0].values)

位置

位置是您可以在请求中指定的区域，用于控制静态数据的存储位置。如需查看可用区域的列表，请参阅 Agent Platform 位置。

配额

如需查看 gemini-embedding-2 的配额限制，请参阅 Gemini Enterprise Agent Platform 上的生成式 AI 的配额和系统限制。

维度

使用 gemini-embedding-2 模型时，您可以在 EmbedContentConfig 中使用 output_dimensionality 参数指定较低的维度。

以下示例返回一个 128 维向量。对于 gemini-embedding-2，输出嵌入已针对非默认维度进行 L2 归一化（与 gemini-embedding-001 不同）。

Python

import numpy as np
from google import genai
from google.genai import types

# Initialize the client.
client = genai.Client(vertexai=True, project="YOUR_PROJECT_ID", location="us")

content = types.Content(
    parts=[
        types.Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/audio/Chirp-3-Docs-Dive.mp3",
            mime_type="audio/mpeg",
        ),
    ],
)

response = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[content],
    config=types.EmbedContentConfig(output_dimensionality=128),
)

embedding_values_np = np.array(response.embeddings[0].values)

print(f"Embedding length: {len(embedding_values_np)}")
print(f"Norm of embedding: {np.linalg.norm(embedding_values_np):.6f}") # Should be very close to 1

参数

默认视频抽样率为 1 帧/秒 (FPS)。您可以使用 video_metadata 添加其他参数：

Python

from google import genai
from google.genai import types

# Initialize the client.
client = genai.Client(vertexai=True, project="YOUR_PROJECT_ID", location="us")

content = types.Content(
    parts=[
        types.Part(
            file_data=types.FileData(
                file_uri="gs://cloud-samples-data/generative-ai/video/pixel8.mp4",
                mime_type="video/mp4",
            ),
            video_metadata=types.VideoMetadata(
                fps=0.5,
                start_offset="10s",
                end_offset="20s",
            ),
        ),
    ]
)

response = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[content]
)

print(response.embeddings[0].values)

EmbedContentConfig 中还有其他选项。

选项 类型 说明
output_dimensionality int 降低输出嵌入的维度。
document_ocr bool 为文档输入启用 OCR。
audio_track_extraction bool 从视频输入中提取音频。

使用 multimodalembedding@001

使用 multimodalembedding@001 模型进行文本和图片嵌入时，存在以下限制：

限制 值和说明
文本和图片数据
每项目每分钟的 API 请求数上限 120-600，具体取决于区域
文本长度上限 32 个词法单元（约 32 个字）

最大文本长度为 32 个词法单元（约 32 个词）。如果输入超过 32 个词法单元，则模型会在内部将输入缩短到此长度。
语言 英语
图片格式 BMP、GIF、JPG、PNG
图片大小 采用 Base64 编码的图片：20 MB（转码为 PNG 时）
Cloud Storage 图片：20 MB（原始文件格式）

接受的图片大小上限为 20 MB。为避免增加网络延迟时间，请使用较小的图片。此外，该模型会将图片的大小调整为 512 x 512 像素分辨率。因此，您无需提供分辨率更高的图片。
视频数据
支持音频 不适用 - 模型在生成视频嵌入时不会考虑音频内容
视频格式 AVI、FLV、MKV、MOV、MP4、MPEG、MPG、WEBM 和 WMV
视频时长上限 (Cloud Storage) 无限制。但是，一次只能分析 2 分钟的内容。

准备工作

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 为您的环境设置身份验证。

    选择标签页以了解您打算如何使用本页面上的示例：

    Java

    如需在本地开发环境中使用本页面上的 Java 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭据。

    1. 安装 Google Cloud CLI。

    2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

    3. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

      gcloud components update
gcloud components install beta

    4. 为您的用户账号创建本地身份验证凭证： 

      gcloud auth application-default login

      如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅身份验证文档中的 为本地开发环境设置 ADC。 Google Cloud

    Node.js

    如需在本地开发环境中使用本页面上的 Node.js 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭证。

    1. 安装 Google Cloud CLI。

    2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

    3. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

      gcloud components update
gcloud components install beta

    4. 为您的用户账号创建本地身份验证凭证： 

      gcloud auth application-default login

      如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅身份验证文档中的 为本地开发环境设置 ADC。 Google Cloud

    Python

    如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

    1. 安装 Google Cloud CLI。

    2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

    3. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

      gcloud components update
gcloud components install beta

    4. 为您的用户账号创建本地身份验证凭证： 

      gcloud auth application-default login

      如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅身份验证文档中的 为本地开发环境设置 ADC。 Google Cloud

    REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

    1. 安装 Google Cloud CLI。

    2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

    3. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

      gcloud components update
gcloud components install beta

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

  5. 如需使用 Python SDK，请按照安装 Agent Platform SDK for Python 中的说明操作。如需了解详情，请参阅 Agent Platform SDK for Python API 参考文档。
  6. 可选。查看此功能的价格。嵌入的价格取决于您发送的数据类型（例如图片或文本），还取决于您用于某些数据类型（例如 Video Plus、Video Standard 或 Video Essential）的模式。

位置

位置是您可以在请求中指定的区域，用于控制静态数据的存储位置。如需查看可用区域的列表，请参阅 Agent Platform 位置。

错误消息

本部分介绍了您可能会遇到的常见错误消息。

“超出配额”错误

google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded for
aiplatform.googleapis.com/online_prediction_requests_per_base_model with base
model: multimodalembedding. Please submit a quota increase request.

如果这是您第一次收到此错误，请使用 Google Cloud 控制台为您的项目申请调整配额。在申请调整配额之前，请使用以下过滤条件：

  • Service ID: aiplatform.googleapis.com
  • metric: aiplatform.googleapis.com/online_prediction_requests_per_base_model
  • base_model:multimodalembedding

前往配额

如果您已发送配额调整请求，请等待另一个请求。如果您需要进一步增加配额，请重复调整配额申请，并提供持续配额调整的理由。

指定低维嵌入

根据所用模型，嵌入请求会返回 1408 个浮点矢量或 3072 个浮点矢量。您可以为文本和图片数据指定较低维度的嵌入，以优化延迟时间和存储空间，或优化质量。低维嵌入可降低存储需求，并为后续嵌入任务（例如搜索或推荐）提供更低的延迟时间。高维嵌入可为这些任务提供更高的准确率，但需要更高的存储空间和更长的延迟时间。

下表显示了每种模型的默认维度和可用的较低维度：

模型 默认维度（最高） 支持的维度（范围） 建议的较低维度
gemini-embedding-2 3072 128 到 3072 128、768 或 1536
multimodalembedding@001 1408 128 到 1408 128、256 或 512

使用以下示例生成维度较低的嵌入：

REST

可以通过添加 parameters.dimension 字段来获得较低维度。该参数接受适用于相应模型的任何维度值。 例如，使用 multimodalembedding@001 模型时，您可以指定 128、256、512 或 1408。响应包含指定维度的嵌入。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • IMAGE_URI：要获取其嵌入的目标图片的 Cloud Storage URI。例如，gs://my-bucket/embeddings/supermarket-img.png。

    您还可以以 base64 编码的字节字符串形式提供图片：

          [...]
      "image": {
        "bytesBase64Encoded": "B64_ENCODED_IMAGE"
      }
      [...]
  • TEXT：要获取嵌入的目标文本。例如 a cat。
  • EMBEDDING_DIMENSION：嵌入维度的数量。值越小，后续任务使用这些嵌入时的延迟时间就越短，而值越大，准确率就越高。可用值：128、256、512 和 1408（默认值）。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

请求 JSON 正文： 

{
  "instances": [
    {
      "image": {
        "gcsUri": "IMAGE_URI"
      },
      "text": "TEXT"
    }
  ],
  "parameters": {
    "dimension": EMBEDDING_DIMENSION
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
模型返回的嵌入是您指定的维度的浮点矢量。为了节约空间，以下示例响应已被缩短。

128 个维度：

{
  "predictions": [
    {
      "imageEmbedding": [
        0.0279239565,
        [...128 dimension vector...]
        0.00403284049
      ],
      "textEmbedding": [
        0.202921599,
        [...128 dimension vector...]
        -0.0365431122
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

256 个维度：

{
  "predictions": [
    {
      "imageEmbedding": [
        0.248620048,
        [...256 dimension vector...]
        -0.0646447465
      ],
      "textEmbedding": [
        0.0757875815,
        [...256 dimension vector...]
        -0.02749932
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

512 个维度：

{
  "predictions": [
    {
      "imageEmbedding": [
        -0.0523675755,
        [...512 dimension vector...]
        -0.0444030389
      ],
      "textEmbedding": [
        -0.0592851527,
        [...512 dimension vector...]
        0.0350437127
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

import vertexai

from vertexai.vision_models import Image, MultiModalEmbeddingModel

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

# TODO(developer): Try different dimenions: 128, 256, 512, 1408
embedding_dimension = 128

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")
image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)

embeddings = model.get_embeddings(
    image=image,
    contextual_text="Colosseum",
    dimension=embedding_dimension,
)

print(f"Image Embedding: {embeddings.image_embedding}")
print(f"Text Embedding: {embeddings.text_embedding}")

# Example response:
# Image Embedding: [0.0622573346, -0.0406507477, 0.0260440577, ...]
# Text Embedding: [0.27469793, -0.146258667, 0.0222803634, ...]

Go

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	aiplatformpb "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateWithLowerDimension shows how to generate lower-dimensional embeddings for text and image inputs.
func generateWithLowerDimension(w io.Writer, project, location string) error {
	// location = "us-central1"
	ctx := context.Background()
	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return fmt.Errorf("failed to construct API client: %w", err)
	}
	defer client.Close()

	model := "multimodalembedding@001"
	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)

	// This is the input to the model's prediction call. For schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#request_body
	instance, err := structpb.NewValue(map[string]any{
		"image": map[string]any{
			// Image input can be provided either as a Google Cloud Storage URI or as
			// base64-encoded bytes using the "bytesBase64Encoded" field.
			"gcsUri": "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png",
		},
		"text": "Colosseum",
	})
	if err != nil {
		return fmt.Errorf("failed to construct request payload: %w", err)
	}

	// TODO(developer): Try different dimenions: 128, 256, 512, 1408
	outputDimensionality := 128
	params, err := structpb.NewValue(map[string]any{
		"dimension": outputDimensionality,
	})
	if err != nil {
		return fmt.Errorf("failed to construct request params: %w", err)
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint: endpoint,
		// The model supports only 1 instance per request.
		Instances:  []*structpb.Value{instance},
		Parameters: params,
	}

	resp, err := client.Predict(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to generate embeddings: %w", err)
	}

	instanceEmbeddingsJson, err := protojson.Marshal(resp.GetPredictions()[0])
	if err != nil {
		return fmt.Errorf("failed to convert protobuf value to JSON: %w", err)
	}
	// For response schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#response-body
	var instanceEmbeddings struct {
		ImageEmbeddings []float32 `json:"imageEmbedding"`
		TextEmbeddings  []float32 `json:"textEmbedding"`
	}
	if err := json.Unmarshal(instanceEmbeddingsJson, &instanceEmbeddings); err != nil {
		return fmt.Errorf("failed to unmarshal JSON: %w", err)
	}

	imageEmbedding := instanceEmbeddings.ImageEmbeddings
	textEmbedding := instanceEmbeddings.TextEmbeddings

	fmt.Fprintf(w, "Text embedding (length=%d): %v\n", len(textEmbedding), textEmbedding)
	fmt.Fprintf(w, "Image embedding (length=%d): %v\n", len(imageEmbedding), imageEmbedding)
	// Example response:
	// Text Embedding (length=128): [0.27469793 -0.14625867 0.022280363 ... ]
	// Image Embedding (length=128): [0.06225733 -0.040650766 0.02604402 ... ]

	return nil
}

获取图片和文本嵌入 (multimodalembedding@001)

使用以下代码示例发送包含图片和数据的嵌入请求。这些示例展示了如何同时发送这两种数据类型的请求，但您也可以将该服务用于个别数据类型。

获取文本和图片嵌入

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • TEXT：要获取嵌入的目标文本。例如 a cat。
  • B64_ENCODED_IMG：要获取嵌入的目标图片。图片必须指定为 base64 编码的字节字符串。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

请求 JSON 正文： 

{
  "instances": [
    {
      "text": "TEXT",
      "image": {
        "bytesBase64Encoded": "B64_ENCODED_IMG"
      }
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
模型返回的嵌入是 1408 个浮点矢量。以下示例响应会缩短。 
{
  "predictions": [
    {
      "textEmbedding": [
        0.010477379,
        -0.00399621,
        0.00576670747,
        [...]
        -0.00823613815,
        -0.0169572588,
        -0.00472954148
      ],
      "imageEmbedding": [
        0.00262696808,
        -0.00198890246,
        0.0152047109,
        -0.0103145819,
        [...]
        0.0324628279,
        0.0284924973,
        0.011650892,
        -0.00452344026
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.vision_models import Image, MultiModalEmbeddingModel

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")
image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)

embeddings = model.get_embeddings(
    image=image,
    contextual_text="Colosseum",
    dimension=1408,
)
print(f"Image Embedding: {embeddings.image_embedding}")
print(f"Text Embedding: {embeddings.text_embedding}")
# Example response:
# Image Embedding: [-0.0123147098, 0.0727171078, ...]
# Text Embedding: [0.00230263756, 0.0278981831, ...]

Node.js

试用此示例之前，请按照Agent Platform 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 Agent Platform Node.js API 参考文档。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
// const baseImagePath = 'YOUR_BASE_IMAGE_PATH';
// const textPrompt = 'YOUR_TEXT_PROMPT';
const aiplatform = require('@google-cloud/aiplatform');

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = aiplatform;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};
const publisher = 'google';
const model = 'multimodalembedding@001';

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictImageFromImageAndText() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/publishers/${publisher}/models/${model}`;

  const fs = require('fs');
  const imageFile = fs.readFileSync(baseImagePath);

  // Convert the image data to a Buffer and base64 encode it.
  const encodedImage = Buffer.from(imageFile).toString('base64');

  const prompt = {
    text: textPrompt,
    image: {
      bytesBase64Encoded: encodedImage,
    },
  };
  const instanceValue = helpers.toValue(prompt);
  const instances = [instanceValue];

  const parameter = {
    sampleCount: 1,
  };
  const parameters = helpers.toValue(parameter);

  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);
  console.log('Get image embedding response');
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}

await predictImageFromImageAndText();

Java

试用此示例之前，请按照Agent Platform 快速入门：使用客户端库中的 Java 设置说明进行操作。如需了解详情，请参阅 Agent Platform Java API 参考文档。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


import com.google.cloud.aiplatform.v1beta1.EndpointName;
import com.google.cloud.aiplatform.v1beta1.PredictResponse;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceSettings;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class PredictImageFromImageAndTextSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String project = "YOUR_PROJECT_ID";
    String textPrompt = "YOUR_TEXT_PROMPT";
    String baseImagePath = "YOUR_BASE_IMAGE_PATH";

    // Learn how to use text prompts to update an image:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/image/edit-images
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("sampleCount", 1);

    String location = "us-central1";
    String publisher = "google";
    String model = "multimodalembedding@001";

    predictImageFromImageAndText(
        project, location, publisher, model, textPrompt, baseImagePath, parameters);
  }

  // Update images using text prompts
  public static void predictImageFromImageAndText(
      String project,
      String location,
      String publisher,
      String model,
      String textPrompt,
      String baseImagePath,
      Map<String, Object> parameters)
      throws IOException {
    final String endpoint = String.format("%s-aiplatform.googleapis.com:443", location);
    final PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      final EndpointName endpointName =
          EndpointName.ofProjectLocationPublisherModelName(project, location, publisher, model);

      // Convert the image to Base64
      byte[] imageData = Base64.getEncoder().encode(Files.readAllBytes(Paths.get(baseImagePath)));
      String encodedImage = new String(imageData, StandardCharsets.UTF_8);

      JsonObject jsonInstance = new JsonObject();
      jsonInstance.addProperty("text", textPrompt);
      JsonObject jsonImage = new JsonObject();
      jsonImage.addProperty("bytesBase64Encoded", encodedImage);
      jsonInstance.add("image", jsonImage);

      Value instanceValue = stringToValue(jsonInstance.toString());
      List<Value> instances = new ArrayList<>();
      instances.add(instanceValue);

      Gson gson = new Gson();
      String gsonString = gson.toJson(parameters);
      Value parameterValue = stringToValue(gsonString);

      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instances, parameterValue);
      System.out.println("Predict Response");
      System.out.println(predictResponse);
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }

  // Convert a Json string to a protobuf.Value
  static Value stringToValue(String value) throws InvalidProtocolBufferException {
    Value.Builder builder = Value.newBuilder();
    JsonFormat.parser().merge(value, builder);
    return builder.build();
  }
}

Go

试用此示例之前，请按照Agent Platform 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 Agent Platform Go API 参考文档。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	aiplatformpb "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateForTextAndImage shows how to use the multimodal model to generate embeddings for
// text and image inputs.
func generateForTextAndImage(w io.Writer, project, location string) error {
	// location = "us-central1"
	ctx := context.Background()
	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return fmt.Errorf("failed to construct API client: %w", err)
	}
	defer client.Close()

	model := "multimodalembedding@001"
	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)

	// This is the input to the model's prediction call. For schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#request_body
	instance, err := structpb.NewValue(map[string]any{
		"image": map[string]any{
			// Image input can be provided either as a Google Cloud Storage URI or as
			// base64-encoded bytes using the "bytesBase64Encoded" field.
			"gcsUri": "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png",
		},
		"text": "Colosseum",
	})
	if err != nil {
		return fmt.Errorf("failed to construct request payload: %w", err)
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint: endpoint,
		// The model supports only 1 instance per request.
		Instances: []*structpb.Value{instance},
	}

	resp, err := client.Predict(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to generate embeddings: %w", err)
	}

	instanceEmbeddingsJson, err := protojson.Marshal(resp.GetPredictions()[0])
	if err != nil {
		return fmt.Errorf("failed to convert protobuf value to JSON: %w", err)
	}
	// For response schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#response-body
	var instanceEmbeddings struct {
		ImageEmbeddings []float32 `json:"imageEmbedding"`
		TextEmbeddings  []float32 `json:"textEmbedding"`
	}
	if err := json.Unmarshal(instanceEmbeddingsJson, &instanceEmbeddings); err != nil {
		return fmt.Errorf("failed to unmarshal JSON: %w", err)
	}

	imageEmbedding := instanceEmbeddings.ImageEmbeddings
	textEmbedding := instanceEmbeddings.TextEmbeddings

	fmt.Fprintf(w, "Text embedding (length=%d): %v\n", len(textEmbedding), textEmbedding)
	fmt.Fprintf(w, "Image embedding (length=%d): %v\n", len(imageEmbedding), imageEmbedding)
	// Example response:
	// Text embedding (length=1408): [0.0023026613 0.027898183 -0.011858357 ... ]
	// Image embedding (length=1408): [-0.012314269 0.07271844 0.00020170923 ... ]

	return nil
}

获取视频、图片或文本嵌入 (multimodalembedding@001)

发送嵌入请求时，您可以单独指定输入视频，也可以指定视频、图片和文本数据的组合。

视频嵌入模式

有三种模式可用于视频嵌入：Essential、Standard 或 Plus。该模式与生成的嵌入的密度相对应，可以由请求中的 interval_sec 配置指定。对于时长为 interval_sec 的每个视频间隔，系统会生成一个嵌入。视频间隔时长下限为 4 秒。间隔时长超过 120 秒可能会对生成的嵌入的质量产生负面影响。

视频嵌入的价格取决于您使用的模式。如需了解详情，请参阅价格。

下表总结了可用于视频嵌入的三种模式：

模式 每分钟的嵌入数上限 视频嵌入间隔（最小值）
Essential 4 15

这对应于：intervalSec >= 15
标准 8 8

这对应于：8 <= intervalSec < 15
Plus 15 4

这对应于：4 <= intervalSec < 8

视频嵌入最佳实践

发送视频嵌入请求时，请考虑以下事项：

  • 如需为任意时长的输入视频的前两分钟生成单个嵌入，请使用以下 videoSegmentConfig 设置：

    request.json：

    // other request body content
"videoSegmentConfig": {
  "intervalSec": 120
}
// other request body content

  • 如需为时长超过两分钟的视频生成嵌入，您可以发送多个在 videoSegmentConfig 中指定开始时间和结束时间的请求：

    request1.json：

    // other request body content
"videoSegmentConfig": {
  "startOffsetSec": 0,
  "endOffsetSec": 120
}
// other request body content

    request2.json：

    // other request body content
"videoSegmentConfig": {
  "startOffsetSec": 120,
  "endOffsetSec": 240
}
// other request body content

    获取视频嵌入

使用以下示例单独获取视频内容的嵌入。

REST

以下示例使用位于 Cloud Storage 中的视频。您还可以使用 video.bytesBase64Encoded 字段提供视频的 base64 编码字符串表示形式。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • VIDEO_URI：要为其获取嵌入的目标视频的 Cloud Storage URI。例如： gs://my-bucket/embeddings/supermarket-video.mp4。

    您还可以以 base64 编码的字节字符串形式提供视频：

    [...]
"video": {
  "bytesBase64Encoded": "B64_ENCODED_VIDEO"
}
[...]
  • videoSegmentConfig（START_SECOND、END_SECOND、INTERVAL_SECONDS）。可选。为其生成嵌入的特定视频片段（以秒为单位）。

    例如：

    [...]
"videoSegmentConfig": {
  "startOffsetSec": 10,
  "endOffsetSec": 60,
  "intervalSec": 10
}
[...]

    使用此配置可指定从 10 秒到 60 秒的视频数据，并为以下 10 秒的视频间隔生成嵌入：[10, 20)、[20, 30)、[30, 40)、[40, 50)、[50, 60)。此视频间隔 ("intervalSec": 10) 属于 标准视频嵌入模式，您按标准模式价格费率计费。

    如果省略 videoSegmentConfig，则服务使用以下默认值："videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }。此视频间隔 ("intervalSec": 16) 属于基本视频嵌入模式，用户按基本模式价格费率计费。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

请求 JSON 正文： 

{
  "instances": [
    {
      "video": {
        "gcsUri": "VIDEO_URI",
        "videoSegmentConfig": {
          "startOffsetSec": START_SECOND,
          "endOffsetSec": END_SECOND,
          "intervalSec": INTERVAL_SECONDS
        }
      }
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
模型返回的嵌入是 1408 个浮点矢量。以下响应示例缩短了空间。

响应（7 秒视频，未指定 videoSegmentConfig）：

{
  "predictions": [
    {
      "videoEmbeddings": [
        {
          "endOffsetSec": 7,
          "embedding": [
            -0.0045467657,
            0.0258095954,
            0.0146885719,
            0.00945400633,
            [...]
            -0.0023291884,
            -0.00493789,
            0.00975185353,
            0.0168156829
          ],
          "startOffsetSec": 0
        }
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

响应（59 秒视频，采用以下视频片段配置："videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 60, "intervalSec": 10 }）：

{
  "predictions": [
    {
      "videoEmbeddings": [
        {
          "endOffsetSec": 10,
          "startOffsetSec": 0,
          "embedding": [
            -0.00683252793,
            0.0390476175,
            [...]
            0.00657121744,
            0.013023301
          ]
        },
        {
          "startOffsetSec": 10,
          "endOffsetSec": 20,
          "embedding": [
            -0.0104404651,
            0.0357737206,
            [...]
            0.00509833824,
            0.0131902946
          ]
        },
        {
          "startOffsetSec": 20,
          "embedding": [
            -0.0113538112,
            0.0305239167,
            [...]
            -0.00195809244,
            0.00941874553
          ],
          "endOffsetSec": 30
        },
        {
          "embedding": [
            -0.00299320649,
            0.0322436653,
            [...]
            -0.00993082579,
            0.00968887936
          ],
          "startOffsetSec": 30,
          "endOffsetSec": 40
        },
        {
          "endOffsetSec": 50,
          "startOffsetSec": 40,
          "embedding": [
            -0.00591270532,
            0.0368893594,
            [...]
            -0.00219071587,
            0.0042470959
          ]
        },
        {
          "embedding": [
            -0.00458270218,
            0.0368121453,
            [...]
            -0.00317760976,
            0.00595594104
          ],
          "endOffsetSec": 59,
          "startOffsetSec": 50
        }
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai

from vertexai.vision_models import MultiModalEmbeddingModel, Video
from vertexai.vision_models import VideoSegmentConfig

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")

embeddings = model.get_embeddings(
    video=Video.load_from_file(
        "gs://cloud-samples-data/vertex-ai-vision/highway_vehicles.mp4"
    ),
    video_segment_config=VideoSegmentConfig(end_offset_sec=1),
)

# Video Embeddings are segmented based on the video_segment_config.
print("Video Embeddings:")
for video_embedding in embeddings.video_embeddings:
    print(
        f"Video Segment: {video_embedding.start_offset_sec} - {video_embedding.end_offset_sec}"
    )
    print(f"Embedding: {video_embedding.embedding}")

# Example response:
# Video Embeddings:
# Video Segment: 0.0 - 1.0
# Embedding: [-0.0206376351, 0.0123456789, ...]

Go

试用此示例之前，请按照Agent Platform 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 Agent Platform Go API 参考文档。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"time"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	aiplatformpb "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateForVideo shows how to use the multimodal model to generate embeddings for video input.
func generateForVideo(w io.Writer, project, location string) error {
	// location = "us-central1"

	// The default context timeout may be not enough to process a video input.
	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return fmt.Errorf("failed to construct API client: %w", err)
	}
	defer client.Close()

	model := "multimodalembedding@001"
	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)

	// This is the input to the model's prediction call. For schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#request_body
	instances, err := structpb.NewValue(map[string]any{
		"video": map[string]any{
			// Video input can be provided either as a Google Cloud Storage URI or as base64-encoded
			// bytes using the "bytesBase64Encoded" field.
			"gcsUri": "gs://cloud-samples-data/vertex-ai-vision/highway_vehicles.mp4",
			"videoSegmentConfig": map[string]any{
				"startOffsetSec": 1,
				"endOffsetSec":   5,
			},
		},
	})
	if err != nil {
		return fmt.Errorf("failed to construct request payload: %w", err)
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint: endpoint,
		// The model supports only 1 instance per request.
		Instances: []*structpb.Value{instances},
	}
	resp, err := client.Predict(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to generate embeddings: %w", err)
	}

	instanceEmbeddingsJson, err := protojson.Marshal(resp.GetPredictions()[0])
	if err != nil {
		return fmt.Errorf("failed to convert protobuf value to JSON: %w", err)
	}
	// For response schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#response-body
	var instanceEmbeddings struct {
		VideoEmbeddings []struct {
			Embedding      []float32 `json:"embedding"`
			StartOffsetSec float64   `json:"startOffsetSec"`
			EndOffsetSec   float64   `json:"endOffsetSec"`
		} `json:"videoEmbeddings"`
	}
	if err := json.Unmarshal(instanceEmbeddingsJson, &instanceEmbeddings); err != nil {
		return fmt.Errorf("failed to unmarshal json: %w", err)
	}
	// Get the embedding for our single video segment (`.videoEmbeddings` object has one entry per
	// each processed segment).
	videoEmbedding := instanceEmbeddings.VideoEmbeddings[0]

	fmt.Fprintf(w, "Video embedding (seconds: %.f-%.f; length=%d): %v\n",
		videoEmbedding.StartOffsetSec,
		videoEmbedding.EndOffsetSec,
		len(videoEmbedding.Embedding),
		videoEmbedding.Embedding,
	)
	// Example response:
	// Video embedding (seconds: 1-5; length=1408): [-0.016427778 0.032878537 -0.030755188 ... ]

	return nil
}

获取图片、文本和视频嵌入

使用以下示例获取视频、文本和图片内容的嵌入。

REST

以下示例使用图片、文本和视频数据。您可以在请求正文中使用这些数据类型的任意组合。

此外，此示例还会使用 Cloud Storage 中的视频。您还可以使用 video.bytesBase64Encoded 字段提供视频的 base64 编码字符串表示形式。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • TEXT：要获取嵌入的目标文本。例如 a cat。
  • IMAGE_URI：要获取其嵌入的目标图片的 Cloud Storage URI。例如，gs://my-bucket/embeddings/supermarket-img.png。

    您还可以以 base64 编码的字节字符串形式提供图片： 

    [...]
"image": {
  "bytesBase64Encoded": "B64_ENCODED_IMAGE"
}
[...]
  • VIDEO_URI：要为其获取嵌入的目标视频的 Cloud Storage URI。例如，gs://my-bucket/embeddings/supermarket-video.mp4。

    您还可以以 base64 编码的字节字符串形式提供视频：

    [...]
"video": {
  "bytesBase64Encoded": "B64_ENCODED_VIDEO"
}
[...]
  • videoSegmentConfig（START_SECOND、END_SECOND、INTERVAL_SECONDS）。可选。为其生成嵌入的特定视频片段（以秒为单位）。

    例如：

    [...]
  "videoSegmentConfig": {
    "startOffsetSec": 10,
    "endOffsetSec": 60,
    "intervalSec": 10
  }
  [...]

    使用此配置可指定从 10 秒到 60 秒的视频数据，并为以下 10 秒的视频间隔生成嵌入：[10, 20)、[20, 30)、[30, 40)、[40, 50)、[50, 60)。此视频间隔 ("intervalSec": 10) 属于 标准视频嵌入模式，您按标准模式价格费率计费。

    如果省略 videoSegmentConfig，则服务使用以下默认值："videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }。此视频间隔 ("intervalSec": 16) 属于基本视频嵌入模式，用户按基本模式价格费率计费。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

请求 JSON 正文： 

{
  "instances": [
    {
      "text": "TEXT",
      "image": {
        "gcsUri": "IMAGE_URI"
      },
      "video": {
        "gcsUri": "VIDEO_URI",
        "videoSegmentConfig": {
          "startOffsetSec": START_SECOND,
          "endOffsetSec": END_SECOND,
          "intervalSec": INTERVAL_SECONDS
        }
      }
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
模型返回的嵌入是 1408 个浮点矢量。以下示例响应会缩短。 
{
  "predictions": [
    {
      "textEmbedding": [
        0.0105433334,
        -0.00302835181,
        0.00656806398,
        0.00603460241,
        [...]
        0.00445805816,
        0.0139605571,
        -0.00170318608,
        -0.00490092579
      ],
      "videoEmbeddings": [
        {
          "startOffsetSec": 0,
          "endOffsetSec": 7,
          "embedding": [
            -0.00673126569,
            0.0248149596,
            0.0128901172,
            0.0107588246,
            [...]
            -0.00180952181,
            -0.0054573305,
            0.0117037306,
            0.0169312079
          ]
        }
      ],
      "imageEmbedding": [
        -0.00728622358,
        0.031021487,
        -0.00206603738,
        0.0273937676,
        [...]
        -0.00204976718,
        0.00321615417,
        0.0121978866,
        0.0193375275
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai

from vertexai.vision_models import Image, MultiModalEmbeddingModel, Video
from vertexai.vision_models import VideoSegmentConfig

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")

image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)
video = Video.load_from_file(
    "gs://cloud-samples-data/vertex-ai-vision/highway_vehicles.mp4"
)

embeddings = model.get_embeddings(
    image=image,
    video=video,
    video_segment_config=VideoSegmentConfig(end_offset_sec=1),
    contextual_text="Cars on Highway",
)

print(f"Image Embedding: {embeddings.image_embedding}")

# Video Embeddings are segmented based on the video_segment_config.
print("Video Embeddings:")
for video_embedding in embeddings.video_embeddings:
    print(
        f"Video Segment: {video_embedding.start_offset_sec} - {video_embedding.end_offset_sec}"
    )
    print(f"Embedding: {video_embedding.embedding}")

print(f"Text Embedding: {embeddings.text_embedding}")
# Example response:
# Image Embedding: [-0.0123144267, 0.0727186054, 0.000201397663, ...]
# Video Embeddings:
# Video Segment: 0.0 - 1.0
# Embedding: [-0.0206376351, 0.0345234685, ...]
# Text Embedding: [-0.0207006838, -0.00251058186, ...]

Go

试用此示例之前，请按照Agent Platform 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 Agent Platform Go API 参考文档。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"time"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	aiplatformpb "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateForImageTextAndVideo shows how to use the multimodal model to generate embeddings for
// image, text and video data.
func generateForImageTextAndVideo(w io.Writer, project, location string) error {
	// location = "us-central1"

	// The default context timeout may be not enough to process a video input.
	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return fmt.Errorf("failed to construct API client: %w", err)
	}
	defer client.Close()

	model := "multimodalembedding@001"
	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)

	// This is the input to the model's prediction call. For schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#request_body
	instance, err := structpb.NewValue(map[string]any{
		"text": "Domestic cats in natural conditions",
		"image": map[string]any{
			// Image and video inputs can be provided either as a Google Cloud Storage URI or as
			// base64-encoded bytes using the "bytesBase64Encoded" field.
			"gcsUri": "gs://cloud-samples-data/generative-ai/image/320px-Felis_catus-cat_on_snow.jpg",
		},
		"video": map[string]any{
			"gcsUri": "gs://cloud-samples-data/video/cat.mp4",
		},
	})
	if err != nil {
		return fmt.Errorf("failed to construct request payload: %w", err)
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint: endpoint,
		// The model supports only 1 instance per request.
		Instances: []*structpb.Value{instance},
	}

	resp, err := client.Predict(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to generate embeddings: %w", err)
	}

	instanceEmbeddingsJson, err := protojson.Marshal(resp.GetPredictions()[0])
	if err != nil {
		return fmt.Errorf("failed to convert protobuf value to JSON: %w", err)
	}
	// For response schema, see:
	// https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-embeddings-api#response-body
	var instanceEmbeddings struct {
		ImageEmbeddings []float32 `json:"imageEmbedding"`
		TextEmbeddings  []float32 `json:"textEmbedding"`
		VideoEmbeddings []struct {
			Embedding      []float32 `json:"embedding"`
			StartOffsetSec float64   `json:"startOffsetSec"`
			EndOffsetSec   float64   `json:"endOffsetSec"`
		} `json:"videoEmbeddings"`
	}
	if err := json.Unmarshal(instanceEmbeddingsJson, &instanceEmbeddings); err != nil {
		return fmt.Errorf("failed to unmarshal JSON: %w", err)
	}

	imageEmbedding := instanceEmbeddings.ImageEmbeddings
	textEmbedding := instanceEmbeddings.TextEmbeddings
	// Get the embedding for our single video segment (`.videoEmbeddings` object has one entry per
	// each processed segment).
	videoEmbedding := instanceEmbeddings.VideoEmbeddings[0].Embedding

	fmt.Fprintf(w, "Image embedding (length=%d): %v\n", len(imageEmbedding), imageEmbedding)
	fmt.Fprintf(w, "Text embedding (length=%d): %v\n", len(textEmbedding), textEmbedding)
	fmt.Fprintf(w, "Video embedding (length=%d): %v\n", len(videoEmbedding), videoEmbedding)
	// Example response:
	// Image embedding (length=1408): [-0.01558477 0.0258355 0.016342038 ... ]
	// Text embedding (length=1408): [-0.005894961 0.008349559 0.015355394 ... ]
	// Video embedding (length=1408): [-0.018867437 0.013997682 0.0012682161 ... ]

	return nil
}

后续步骤