멀티모달 임베딩 가져오기

멀티모달 임베딩 모델은 제공된 입력에 따라 1,408차원 벡터를 생성하며, 여기에는 이미지, 텍스트, 동영상 데이터의 조합이 포함될 수 있습니다. 그런 다음 임베딩 벡터를 이미지 분류 또는 동영상 콘텐츠 검토와 같은 후속 태스크에 사용할 수 있습니다.

이미지 임베딩 벡터와 텍스트 임베딩 벡터는 동일한 차원으로 동일한 시맨틱 공간에 위치합니다. 따라서 텍스트로 이미지를 검색하거나 이미지로 동영상을 검색하는 등의 사용 사례에 맞게 이러한 벡터를 서로 교환해서 사용할 수 있습니다.

텍스트 전용 임베딩 사용 사례의 경우 Vertex AI 텍스트 임베딩 API를 대신 사용하는 것이 좋습니다. 예를 들어 텍스트 기반 시맨틱 검색, 클러스터링, 긴 형식 문서 분석, 기타 텍스트 검색 또는 질의 응답 사용 사례에 텍스트 임베딩 API가 더 적합할 수 있습니다. 자세한 내용은 텍스트 임베딩 가져오기를 참조하세요.

* 기본값

사용 사례

이미지 및 텍스트:

이미지 분류: 이미지를 입력으로 받고 하나 이상의 클래스(라벨)를 예측합니다.
이미지 검색: 관련되었거나 유사한 이미지를 검색합니다.
권장사항: 이미지를 기반으로 제품 또는 광고 권장사항을 생성합니다.

이미지, 텍스트, 동영상:

권장사항: 동영상을 기반으로 제품 또는 광고 권장사항을 생성합니다(유사성 검색).
동영상 콘텐츠 검색
- 시맨틱 검색 사용: 텍스트를 입력으로 받고 쿼리와 일치하는 순위가 지정된 프레임 세트를 반환합니다.
- 유사성 검색 사용:
  - 동영상을 입력으로 받고 쿼리와 일치하는 동영상 세트를 반환합니다.
  - 이미지를 입력으로 받고 쿼리와 일치하는 동영상 세트를 반환합니다.
동영상 분류: 동영상을 입력으로 받고 하나 이상의 클래스를 예측합니다.

지원되는 모델

다음 모델을 사용하여 멀티모달 임베딩을 가져올 수 있습니다.

multimodalembedding

권장사항

멀티모달 임베딩 모델을 사용할 때 다음 입력 측면을 고려하세요.

이미지의 텍스트 - 모델은 광학 문자 인식(OCR)과 유사하게 이미지의 텍스트를 구분할 수 있습니다. 이미지 콘텐츠 설명과 이미지 내의 텍스트를 구분해야 할 경우에는 프롬프트 엔지니어링을 사용하여 대상 콘텐츠를 지정하는 것이 좋습니다. 예를 들어 사용 사례에 따라 단순히 '고양이' 대신 '고양이 사진' 또는 '고양이' 텍스트'를 지정합니다.

'고양이' 텍스트
고양이 사진	^{이미지 출처: Unsplash의 Manja Vitolic}

임베딩 유사성 - 임베딩의 내적은 보정된 확률이 아닙니다. 내적은 유사성 측정항목이며 사용 사례마다 점수 분포가 다를 수 있습니다. 따라서 고정 값 기준을 사용하여 품질을 측정하지 마세요. 그 대신 검색에 순위 접근 방식을 사용하거나 분류에 시그모이드를 사용합니다.

API 사용량

API 한도

텍스트 및 이미지 임베딩에 multimodalembedding 모델을 사용하는 경우 다음 한도가 적용됩니다.

한도	값 및 설명
	텍스트 및 이미지 데이터
프로젝트별 분당 최대 API 요청 수	120
최대 텍스트 길이	토큰 32개(최대 32단어) 최대 텍스트 길이는 토큰 32개(약 32단어)입니다. 입력이 토큰 32개를 초과하면 모델에서 내부적으로 입력을 이 길이로 줄입니다.
언어	영어
이미지 형식	BMP, GIF, JPG, PNG
이미지 크기	Base64로 인코딩된 이미지: 20MB(PNG로 트랜스코딩된 경우) Cloud Storage 이미지: 20MB(원본 파일 형식) 허용되는 최대 이미지 크기는 20MB입니다. 네트워크 지연 시간 증가를 방지하려면 작은 이미지를 사용합니다. 또한 이 모델은 이미지 크기를 512x512픽셀 해상도로 조정합니다. 따라서 더 높은 해상도의 이미지를 제공할 필요가 없습니다.
	동영상 데이터
오디오 지원	해당 없음 - 이 모델에서는 동영상 임베딩을 생성할 때 오디오 콘텐츠를 고려하지 않습니다.
동영상 형식	AVI, FLV, MKV, MOV, MP4, MPEG, MPG, WEBM, WMV
최대 동영상 길이(Cloud Storage)	한도 없음. 하지만 한 번에 2분 분량의 콘텐츠만 분석할 수 있습니다.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

환경에 대한 인증을 설정하세요.

Select the tab for how you plan to use the samples on this page:
Java

이 페이지의 Java 샘플을 로컬 개발 환경에서 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. Update and install gcloud components:
  gcloud components update
  gcloud components install beta
4. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경 인증 설정을 참조하세요.
Node.js

이 페이지의 Node.js 샘플을 로컬 개발 환경에서 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. Update and install gcloud components:
  gcloud components update
  gcloud components install beta
4. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경 인증 설정을 참조하세요.
Python

이 페이지의 Python 샘플을 로컬 개발 환경에서 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. Update and install gcloud components:
  gcloud components update
  gcloud components install beta
4. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경 인증 설정을 참조하세요.
REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공하는 사용자 인증 정보를 사용합니다.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. Update and install gcloud components:
  gcloud components update
  gcloud components install beta
자세한 내용은 Google Cloud 인증 문서의 REST 사용 인증을 참조하세요.
Python SDK를 사용하려면 Python용 Vertex AI SDK 설치의 안내를 따르세요. 자세한 내용은 Python용 Vertex AI SDK API 참조 문서를 확인하세요.
선택사항입니다. 이 기능의 가격 책정을 검토합니다. 임베딩 가격 책정은 전송하는 데이터 유형(예: 이미지 또는 텍스트)과 특정 데이터 유형에 사용하는 모드(예: Video Plus, Video Standard, Video Essential)에 따라 달라집니다.

위치

위치는 데이터가 영구 저장되는 위치를 제어하기 위해 요청에서 지정할 수 있는 리전입니다. 사용 가능한 리전 목록은 Vertex AI의 생성형 AI 위치를 참조하세요.

오류 메시지

할당량 초과 오류

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 부동 소수점 벡터를 반환합니다. 텍스트 및 이미지 데이터에 저차원 임베딩(128, 256, 512 부동 소수점 벡터)을 지정할 수도 있습니다. 이 옵션을 사용하면 임베딩 사용 계획에 따라 지연 시간, 스토리지 또는 품질을 최적화할 수 있습니다. 저차원 임베딩은 검색 또는 추천과 같은 후속 임베딩 태스크에 대한 스토리지 요구 사항을 줄이고 지연 시간을 단축하는 반면 고차원 임베딩은 동일한 태스크에 대해 더 높은 정확성을 제공합니다.

REST

parameters.dimension 필드를 추가하면 저차원에 액세스할 수 있습니다. 이 매개변수는 128, 256, 512, 1408 값 중 하나를 허용합니다. 응답에는 해당 차원의 임베딩이 포함됩니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 프로젝트의 리전입니다. 예를 들면 us-central1, europe-west2, asia-northeast3입니다. 사용 가능한 리전 목록은 Vertex AI의 생성형 AI 위치를 참조하세요.
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 메서드 및 URL:

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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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"
}

임베딩 요청 보내기(이미지 및 텍스트)

다음 코드 샘플을 사용하여 이미지 및 텍스트 데이터가 포함된 임베딩 요청을 보냅니다. 이 샘플은 두 데이터 유형이 모두 포함된 요청을 보내는 방법을 보여 주지만 개별 데이터 유형에서 서비스를 사용할 수도 있습니다.

텍스트 및 이미지 임베딩 가져오기

REST

multimodalembedding 모델 요청에 대한 자세한 내용은 multimodalembedding 모델 API 참조를 확인하세요.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 프로젝트의 리전입니다. 예를 들면 us-central1, europe-west2, asia-northeast3입니다. 사용 가능한 리전 목록은 Vertex AI의 생성형 AI 위치를 참조하세요.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
TEXT: 임베딩을 가져올 대상 텍스트. 예를 들면 a cat입니다.
B64_ENCODED_IMG: 임베딩을 가져올 대상 이미지. 이미지는 base64 인코딩 바이트 문자열로 지정되어야 합니다.

HTTP 메서드 및 URL:

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

Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.

from typing import Optional

import vertexai
from vertexai.vision_models import (
    Image,
    MultiModalEmbeddingModel,
    MultiModalEmbeddingResponse,
)

def get_image_embeddings(
    project_id: str,
    location: str,
    image_path: str,
    contextual_text: Optional[str] = None,
) -> MultiModalEmbeddingResponse:
    """Example of how to generate multimodal embeddings from image and text.

    Args:
        project_id: Google Cloud Project ID, used to initialize vertexai
        location: Google Cloud Region, used to initialize vertexai
        image_path: Path to image (local or Google Cloud Storage) to generate embeddings for.
        contextual_text: Text to generate embeddings for.
    """

    vertexai.init(project=project_id, location=location)

    model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding")
    image = Image.load_from_file(image_path)

    embeddings = model.get_embeddings(
        image=image,
        contextual_text=contextual_text,
    )
    print(f"Image Embedding: {embeddings.image_embedding}")
    print(f"Text Embedding: {embeddings.text_embedding}")

Node.js

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Vertex AI Node.js API 참고 문서를 참조하세요.

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

/**
 * 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 bastImagePath = "YOUR_BASED_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

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Vertex AI Java API 참고 문서를 참조하세요.

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


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();
  }
}

임베딩 요청 보내기(동영상, 이미지 또는 텍스트)

임베딩 요청을 전송할 때 입력 동영상만 단독으로 지정하거나 동영상, 이미지, 텍스트 데이터의 조합을 지정할 수 있습니다.

동영상 임베딩 모드

동영상 임베딩에는 Essential, Standard 또는 Plus와 같은 3가지 모드를 사용할 수 있습니다. 모드는 생성된 임베딩의 밀도에 해당하며, 요청의 interval_sec 구성으로 지정할 수 있습니다. 길이가 interval_sec인 각 동영상 간격에 대해 임베딩이 생성됩니다. 최소 동영상 간격 길이는 4초입니다. 간격 길이가 120초를 초과하면 생성된 임베딩의 품질에 부정적인 영향을 미칠 수 있습니다.

동영상 임베딩에 대한 가격 책정은 사용하는 모드에 따라 다릅니다. 자세한 내용은 가격 책정을 참조하세요.

다음 표에는 동영상 임베딩에 사용할 수 있는 세 가지 모드가 요약되어 있습니다.

모드	분당 최대 임베딩 수	동영상 임베딩 간격(최솟값)
필수 사항	4	15 다음에 해당합니다. `intervalSec` >= 15
Standard	8	8 다음에 해당합니다. 8 <= `intervalSec` < 15
더하기	15	4 다음에 해당합니다. 4 <= `intervalSec` < 8

동영상 임베딩 권장사항

동영상 임베딩 요청을 보낼 때 다음 사항을 고려하세요.

길이에 관계없이 입력 동영상의 처음 2분에 대한 단일 임베딩을 생성하려면 다음 videoSegmentConfig 설정을 사용합니다.

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

길이가 2분을 초과하는 동영상의 임베딩을 생성하려면 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

multimodalembedding 모델 요청에 대한 자세한 내용은 multimodalembedding 모델 API 참조를 확인하세요.

다음 예시에서는 Cloud Storage에 있는 동영상을 사용합니다. video.bytesBase64Encoded 필드를 사용하여 동영상의 base64 인코딩 문자열 표현을 제공할 수도 있습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 프로젝트의 리전입니다. 예를 들면 us-central1, europe-west2, asia-northeast3입니다. 사용 가능한 리전 목록은 Vertex AI의 생성형 AI 위치를 참조하세요.
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.intervalSec에 설정한 값은 요금이 청구되는 가격 책정 등급에 영향을 줍니다. 자세한 내용은 동영상 임베딩 모드 섹션 및 가격 책정 페이지를 참조하세요.

예를 들면 다음과 같습니다.
```
[...]
"videoSegmentConfig": {
  "startOffsetSec": 10,
  "endOffsetSec": 60,
  "intervalSec": 10
}
[...]
```
이 구성을 사용하면 10초에서 60초 사이의 동영상 데이터가 지정되고 다음 10초 비디오 간격([10, 20), [20, 30), [30, 40), [40, 50), [50, 60))에 대한 임베딩이 생성됩니다. 이 동영상 간격("intervalSec": 10)은 Standard 동영상 임베딩 모드에 속하며 사용자에게 Standard 모드 가격 책정 요금이 부과됩니다.

videoSegmentConfig를 생략하면 서비스에서 기본값 "videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }을 사용합니다. 이 동영상 간격("intervalSec": 16)은 Essential 동영상 임베딩 모드에 속하며 사용자에게 Essential 모드 가격 책정 요금이 부과됩니다.

HTTP 메서드 및 URL:

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

Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.

from typing import Optional

import vertexai
from vertexai.vision_models import (
    MultiModalEmbeddingModel,
    MultiModalEmbeddingResponse,
    Video,
    VideoSegmentConfig,
)

def get_video_embeddings(
    project_id: str,
    location: str,
    video_path: str,
    contextual_text: Optional[str] = None,
    dimension: Optional[int] = 1408,
    video_segment_config: Optional[VideoSegmentConfig] = None,
) -> MultiModalEmbeddingResponse:
    """Example of how to generate multimodal embeddings from video and text.

    Args:
        project_id: Google Cloud Project ID, used to initialize vertexai
        location: Google Cloud Region, used to initialize vertexai
        video_path: Path to video (local or Google Cloud Storage) to generate embeddings for.
        contextual_text: Text to generate embeddings for.
        dimension: Dimension for the returned embeddings.
            https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-multimodal-embeddings#low-dimension
        video_segment_config: Define specific segments to generate embeddings for.
            https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-multimodal-embeddings#video-best-practices
    """

    vertexai.init(project=project_id, location=location)

    model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding")
    video = Video.load_from_file(video_path)

    embeddings = model.get_embeddings(
        video=video,
        video_segment_config=video_segment_config,
        contextual_text=contextual_text,
        dimension=dimension,
    )

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

이미지, 텍스트, 동영상 임베딩 가져오기

다음 샘플을 사용하여 동영상, 텍스트, 이미지 콘텐츠의 임베딩을 가져옵니다.

REST

multimodalembedding 모델 요청에 대한 자세한 내용은 multimodalembedding 모델 API 참조를 확인하세요.

다음 예시에서는 이미지, 텍스트, 동영상 데이터를 사용합니다. 요청 본문에서 이러한 데이터 유형의 조합을 사용할 수 있습니다.

또한 이 샘플에서는 Cloud Storage에 있는 동영상을 사용합니다. video.bytesBase64Encoded 필드를 사용하여 동영상의 base64 인코딩 문자열 표현을 제공할 수도 있습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 프로젝트의 리전입니다. 예를 들면 us-central1, europe-west2, asia-northeast3입니다. 사용 가능한 리전 목록은 Vertex AI의 생성형 AI 위치를 참조하세요.
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.intervalSec에 설정한 값은 요금이 청구되는 가격 책정 등급에 영향을 줍니다. 자세한 내용은 동영상 임베딩 모드 섹션 및 가격 책정 페이지를 참조하세요.

예를 들면 다음과 같습니다.
```
[...]
"videoSegmentConfig": {
  "startOffsetSec": 10,
  "endOffsetSec": 60,
  "intervalSec": 10
}
[...]
```
이 구성을 사용하면 10초에서 60초 사이의 동영상 데이터가 지정되고 다음 10초 비디오 간격([10, 20), [20, 30), [30, 40), [40, 50), [50, 60))에 대한 임베딩이 생성됩니다. 이 동영상 간격("intervalSec": 10)은 Standard 동영상 임베딩 모드에 속하며 사용자에게 Standard 모드 가격 책정 요금이 부과됩니다.

videoSegmentConfig를 생략하면 서비스에서 기본값 "videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }을 사용합니다. 이 동영상 간격("intervalSec": 16)은 Essential 동영상 임베딩 모드에 속하며 사용자에게 Essential 모드 가격 책정 요금이 부과됩니다.

HTTP 메서드 및 URL:

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

Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.

from typing import Optional

import vertexai
from vertexai.vision_models import (
    Image,
    MultiModalEmbeddingModel,
    MultiModalEmbeddingResponse,
    Video,
    VideoSegmentConfig,
)

def get_image_video_text_embeddings(
    project_id: str,
    location: str,
    image_path: str,
    video_path: str,
    contextual_text: Optional[str] = None,
    dimension: Optional[int] = 1408,
    video_segment_config: Optional[VideoSegmentConfig] = None,
) -> MultiModalEmbeddingResponse:
    """Example of how to generate multimodal embeddings from image, video, and text.

    Args:
        project_id: Google Cloud Project ID, used to initialize vertexai
        location: Google Cloud Region, used to initialize vertexai
        image_path: Path to image (local or Google Cloud Storage) to generate embeddings for.
        video_path: Path to video (local or Google Cloud Storage) to generate embeddings for.
        contextual_text: Text to generate embeddings for.
        dimension: Dimension for the returned embeddings.
            https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-multimodal-embeddings#low-dimension
        video_segment_config: Define specific segments to generate embeddings for.
            https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-multimodal-embeddings#video-best-practices
    """

    vertexai.init(project=project_id, location=location)

    model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding")
    image = Image.load_from_file(image_path)
    video = Video.load_from_file(video_path)

    embeddings = model.get_embeddings(
        image=image,
        video=video,
        video_segment_config=video_segment_config,
        contextual_text=contextual_text,
        dimension=dimension,
    )

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

다음 단계

'멀티모달 검색이란? '비전을 사용한 LLM' 비즈니스 변경' 블로그 읽어보기
텍스트 전용 사용 사례(텍스트 기반 시맨틱 검색, 클러스터링, 긴 형식 문서 분석, 기타 텍스트 검색 또는 질문 답변 사용 사례)에 대한 자세한 내용은 텍스트 임베딩 가져오기 읽어보기
Vertex AI의 이미지 개요에서 모든 Vertex AI 이미지 생성형 AI 제품 확인하기
Model Garden의 미리 학습된 모델 살펴보기
Vertex AI의 책임감 있는 AI 권장사항 및 안전 필터 알아보기