יצירת שירות של תיאור תמונת סצנה אחרי סצנה באמצעות Cloud Run, Video Intelligence API ו-Vertex AI

1. מבוא

סקירה כללית

ב-Codelab הזה תיצרו שירות של Cloud Run שכתוב ב-Node.js שמספק תיאור חזותי של כל סצנה בסרטון. קודם כל, השירות ישתמש ב-Video Intelligence API כדי לזהות את חותמות הזמן של כל שינוי בסצנה. לאחר מכן, השירות שלך ישתמש בקובץ בינארי של צד שלישי שנקרא ffmpeg כדי לצלם צילום מסך של כל חותמת זמן של שינוי סצנה. לבסוף, כתוביות ויזואליות של Vertex AI משמשות כדי לספק תיאור חזותי של צילומי המסך.

ה-Codelab הזה גם מדגים איך להשתמש ב-ffmpeg בתוך שירות Cloud Run כדי לצלם תמונות מסרטון בחותמת זמן נתונה. צריך להתקין את ffmpeg בנפרד, ולכן ה-Codelab הזה מראה איך ליצור קובץ Docker כדי להתקין את ffmpeg כחלק משירות Cloud Run.

הנה איור של אופן הפעולה של שירות Cloud Run:

מה תלמדו

• איך ליצור קובץ אימג' של קונטיינר באמצעות קובץ Docker כדי להתקין קובץ בינארי של צד שלישי
• איך לשמור על העיקרון של הרשאות מינימליות על ידי יצירת חשבון שירות בשביל שירות Cloud Run כדי לקרוא לשירותי Google Cloud אחרים
• איך להשתמש בספריית הלקוח של Video Intelligence משירות Cloud Run
• איך מבצעים קריאה ל-Google APIs כדי לקבל את התיאור החזותי של כל סצנה מ-Vertex AI

2. הגדרה ודרישות

דרישות מוקדמות

• אתם מחוברים למסוף Cloud.
• פרסתם בעבר שירות של Cloud Run. לדוגמה, אפשר להיעזר במדריך למתחילים לפריסת שירות אינטרנט מקוד מקור כדי להתחיל בעבודה.

הפעלת Cloud Shell

1. במסוף Cloud, לוחצים על Activate Cloud Shell .

אם זו הפעם הראשונה שאתם מפעילים את Cloud Shell, יוצג לכם מסך ביניים שמתוארת בו. אם הוצג לכם מסך ביניים, לוחצים על המשך.

ההקצאה וההתחברות ל-Cloud Shell נמשכת כמה דקות.

במכונה הווירטואלית הזו נמצאים כל כלי הפיתוח הדרושים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר משמעותית את ביצועי הרשת והאימות. אם לא את כולן, ניתן לבצע חלק גדול מהעבודה ב-Codelab הזה באמצעות דפדפן.

אחרי ההתחברות ל-Cloud Shell, אתם אמורים לראות שהפרויקט מאומת ושהפרויקט מוגדר לפי מזהה הפרויקט שלכם.

2. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהאימות בוצע:

gcloud auth list

פלט הפקודה

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

הערה: כלי שורת הפקודה gcloud הוא כלי שורת הפקודה המתקדם והמאוחד ב-Google Cloud. הוא מותקן מראש ב-Cloud Shell. תוכלו לראות שהוא תומך בהשלמת כרטיסיות. יכול להיות שתוצג לכם בקשה לבצע אימות בפעם הראשונה שתריצו פקודה. למידע נוסף, קראו את המאמר סקירה כללית של כלי שורת הפקודה של Google Cloud.

3. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהפקודה ב-gcloud יודעת על הפרויקט שלכם:

gcloud config list project

פלט הפקודה

[core]
project = <PROJECT_ID>

אם היא לא נמצאת שם, תוכלו להגדיר אותה באמצעות הפקודה הבאה:

gcloud config set project <PROJECT_ID>

פלט הפקודה

Updated property [core/project].

הערה: אם השלמתם את המדריך הזה מחוץ ל-Cloud Shell, קראו את המאמר הגדרת Application Default Credentials.

3. הפעלת ממשקי API והגדרת משתני סביבה

לפני שתוכלו להשתמש ב-Codelab הזה, יש כמה ממשקי API שתצטרכו להפעיל. ה-Codelab הזה מחייב שימוש בממשקי ה-API הבאים. כדי להפעיל את ממשקי ה-API האלה, מריצים את הפקודה הבאה:

gcloud services enable run.googleapis.com \
    storage.googleapis.com \
    cloudbuild.googleapis.com \
    videointelligence.googleapis.com \
    aiplatform.googleapis.com

לאחר מכן תוכלו להגדיר משתני סביבה שישמשו ב-Codelab הזה.

REGION=<YOUR-REGION>
PROJECT_ID=<YOUR-PROJECT-ID>

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
SERVICE_NAME=video-describer
export BUCKET_ID=$PROJECT_ID-video-describer

4. יצירת קטגוריה של Cloud Storage

יוצרים קטגוריה של Cloud Storage שבה אפשר להעלות סרטונים לעיבוד על ידי שירות Cloud Run באמצעות הפקודה הבאה:

gsutil mb -l us-central1 gs://$BUCKET_ID/

[אופציונלי] כדי להשתמש בסרטון לדוגמה הזה, צריך להוריד אותו באופן מקומי.

gsutil cp gs://cloud-samples-data/video/visionapi.mp4 testvideo.mp4

עכשיו מעלים את קובץ הסרטון לקטגוריית האחסון.

FILENAME=<YOUR-VIDEO-FILENAME>
gsutil cp $FILENAME gs://$BUCKET_ID

5. יצירת אפליקציית Node.js

קודם כל, יוצרים ספרייה עבור קוד המקור וה-cd בספרייה הזו.

mkdir video-describer && cd $_

לאחר מכן, יוצרים קובץ package.json עם התוכן הבא:

{
  "name": "video-describer",
  "version": "1.0.0",
  "private": true,
  "description": "describes the image in every scene for a given video",
  "main": "index.js",
  "author": "Google LLC",
  "license": "Apache-2.0",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/storage": "^7.7.0",
    "@google-cloud/video-intelligence": "^5.0.1",
    "axios": "^1.6.2",
    "express": "^4.18.2",
    "fluent-ffmpeg": "^2.1.2",
    "google-auth-library": "^9.4.1"
  }
}

האפליקציה הזו מורכבת מכמה קובצי מקור כדי לשפר את הקריאוּת. תחילה, יוצרים קובץ מקור index.js עם התוכן הבא. הקובץ הזה מכיל את נקודת הכניסה לשירות ומכיל את הלוגיקה העיקרית של האפליקציה.

const { captureImages } = require('./imageCapture.js');
const { detectSceneChanges } = require('./sceneDetector.js');
const transcribeScene = require('./imageDescriber.js');
const { Storage } = require('@google-cloud/storage');
const fs = require('fs').promises;
const path = require('path');
const express = require('express');
const app = express();

const bucketName = process.env.BUCKET_ID;

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`video describer service ready: listening on port ${port}`);
});

// entry point for the service
app.get('/', async (req, res) => {

  try {

    // download the requested video from Cloud Storage
    let videoFilename =  req.query.filename; 
    console.log("processing file: " + videoFilename);

    // download the file to locally to the Cloud Run instance
    let localFilename = await downloadVideoFile(videoFilename);

    // detect all the scenes in the video & save timestamps to an array
    let timestamps = await detectSceneChanges(localFilename);
    console.log("Detected scene changes at the following timestamps: ", timestamps);

    // create an image of each scene change
    // and save to a local directory called "output"
    await captureImages(localFilename, timestamps);

    // get an access token for the Service Account to call the Google APIs 
    let accessToken = await transcribeScene.getAccessToken();
    console.log("got an access token");

    let imageBaseName = path.parse(localFilename).name;

    // the data structure for storing the scene description and timestamp
    // e.g. an array of json objects {timestamp: 1, description: "..."}, etc.    
    let scenes = []

    // for each timestamp, send the image to Vertex AI
    console.log("getting Vertex AI description all the timestamps");
    scenes = await Promise.all(
      timestamps.map(async (timestamp) => {

        let filepath = path.join("./output", imageBaseName + "-" + timestamp + ".png");

        // get the base64 encoded image
        const encodedFile = await fs.readFile(filepath, 'base64');

        // send each screenshot to Vertex AI for description
        let description = await transcribeScene.transcribeScene(accessToken, encodedFile)

        return { timestamp: timestamp, description: description };
      }));

    console.log("finished collecting all the scenes");
    //console.log(scenes);

    return res.json(scenes);

  } catch (error) {

    //return an error
    console.log("received error: ", error);
    return res.status(500).json("an internal error occurred");
  }

});

async function downloadVideoFile(videoFilename) {
  // Creates a client
  const storage = new Storage();

  // keep same name locally
  let localFilename = videoFilename;

  const options = {
    destination: localFilename
  };

  // Download the file
  await storage.bucket(bucketName).file(videoFilename).download(options);

  console.log(
    `gs://${bucketName}/${videoFilename} downloaded locally to ${localFilename}.`
  );

  return localFilename;
}

לאחר מכן, יוצרים קובץsceneDetector.js עם התוכן הבא. הקובץ הזה משתמש ב-Video Intelligence API כדי לזהות מתי הסצנות בסרטון משתנות.

const fs = require('fs');
const util = require('util');
const readFile = util.promisify(fs.readFile);
const ffmpeg = require('fluent-ffmpeg');

const Video = require('@google-cloud/video-intelligence');
const client = new Video.VideoIntelligenceServiceClient();

module.exports = {
    detectSceneChanges: async function (downloadedFile) {

        // Reads a local video file and converts it to base64       
        const file = await readFile(downloadedFile);
        const inputContent = file.toString('base64');

        // setup request for shot change detection
        const videoContext = {
            speechTranscriptionConfig: {
                languageCode: 'en-US',
                enableAutomaticPunctuation: true,
            },
        };

        const request = {
            inputContent: inputContent,
            features: ['SHOT_CHANGE_DETECTION'],
        };

        // Detects camera shot changes
        const [operation] = await client.annotateVideo(request);
        console.log('Shot (scene) detection in progress...');
        const [operationResult] = await operation.promise();

        // Gets shot changes
        const shotChanges = operationResult.annotationResults[0].shotAnnotations;

        console.log("Shot (scene) changes detected: " + shotChanges.length);

        // data structure to be returned 
        let sceneChanges = [];

        // for the initial scene
        sceneChanges.push(1);

        // if only one scene, keep at 1 second
        if (shotChanges.length === 1) {
            return sceneChanges;
        }

        // get length of video
        const videoLength = await getVideoLength(downloadedFile);

        shotChanges.forEach((shot, shotIndex) => {
            if (shot.endTimeOffset === undefined) {
                shot.endTimeOffset = {};
            }
            if (shot.endTimeOffset.seconds === undefined) {
                shot.endTimeOffset.seconds = 0;
            }
            if (shot.endTimeOffset.nanos === undefined) {
                shot.endTimeOffset.nanos = 0;
            }

            // convert to a number
            let currentTimestampSecond = Number(shot.endTimeOffset.seconds);                  

            let sceneChangeTime = 0;
            // double-check no scenes were detected within the last second
            if (currentTimestampSecond + 1 > videoLength) {
                sceneChangeTime = currentTimestampSecond;                
            } else {
                // otherwise, for simplicity, just round up to the next second 
                sceneChangeTime = currentTimestampSecond + 1;
            }

            sceneChanges.push(sceneChangeTime);
        });

        return sceneChanges;
    }
}

async function getVideoLength(localFile) {
    let getLength = util.promisify(ffmpeg.ffprobe);
    let length = await getLength(localFile);

    console.log("video length: ", length.format.duration);
    return length.format.duration;
}

עכשיו יוצרים קובץ בשם imageCapture.js עם התוכן הבא. הקובץ הזה משתמש בחבילת הצמתים fluent-ffmpeg כדי להריץ פקודות ffmpeg מתוך אפליקציה של צומת.

const ffmpeg = require('fluent-ffmpeg');
const path = require('path');
const util = require('util');


module.exports = {
    captureImages: async function (localFile, scenes) {


        let imageBaseName = path.parse(localFile).name;


        try {
            for (scene of scenes) {
                console.log("creating screenshot for scene: ", + scene);
                await createScreenshot(localFile, imageBaseName, scene);
            }


        } catch (error) {
            console.log("error gathering screenshots: ", error);
        }


        console.log("finished gathering the screenshots");
    }
}


async function createScreenshot(localFile, imageBaseName, scene) {
    return new Promise((resolve, reject) => {
        ffmpeg(localFile)
            .screenshots({
                timestamps: [scene],
                filename: `${imageBaseName}-${scene}.png`,
                folder: 'output',
                size: '320x240'
            }).on("error", () => {
                console.log("Failed to create scene for timestamp: " + scene);
                return reject('Failed to create scene for timestamp: ' + scene);
            })
            .on("end", () => {
                return resolve();
            });
    })
}

לסיום, יוצרים קובץ בשם 'imageDescriber.js' עם התוכן הבא. בקובץ הזה נעשה שימוש ב-Vertex AI כדי לקבל תיאור חזותי של כל תמונה של סצנה.

const axios = require("axios");
const { GoogleAuth } = require('google-auth-library');

const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform'
});

module.exports = {
    getAccessToken: async function () {

        return await auth.getAccessToken();
    }, 

    transcribeScene: async function(token, encodedFile) {

        let projectId = await auth.getProjectId();
    
        let config = {
            headers: {
                'Authorization': 'Bearer ' + token,
                'Content-Type': 'application/json; charset=utf-8'
            }
        }

        const json = {
            "instances": [
                {
                    "image": {
                        "bytesBase64Encoded": encodedFile
                    }
                }
            ],
            "parameters": {
                "sampleCount": 1,
                "language": "en"
            }
        }

        let response = await axios.post('https://us-central1-aiplatform.googleapis.com/v1/projects/' + projectId + '/locations/us-central1/publishers/google/models/imagetext:predict', json, config);

        return response.data.predictions[0];
    }
}

יצירת קובץ Docker וקובץ dockerignore

מכיוון שהשירות הזה משתמש ב-ffmpeg, יהיה עליך ליצור קובץ Docker שמתקין את ffmpeg.

יוצרים קובץ בשם Dockerfile שמכיל את התוכן הבא:

# Copyright 2020 Google, LLC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Use the official lightweight Node.js image.
# https://hub.docker.com/_/node
FROM node:20.10.0-slim

# Create and change to the app directory.
WORKDIR /usr/src/app

RUN apt-get update && apt-get install -y ffmpeg

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure both package.json AND package-lock.json are copied.
# Copying this separately prevents re-running npm install on every code change.
COPY package*.json ./

# Install dependencies.
# If you add a package-lock.json speed your build by switching to 'npm ci'.
# RUN npm ci --only=production
RUN npm install --production

# Copy local code to the container image.
COPY . .

# Run the web service on container startup.
CMD [ "npm", "start" ]

ויוצרים קובץ בשם dockerignore .כדי להתעלם מהקונטיינרים של קבצים מסוימים.

Dockerfile
.dockerignore
node_modules
npm-debug.log

6. יצירה של חשבון שירות.

יוצרים חשבון שירות לשירות Cloud Run שאפשר להשתמש בו כדי לגשת ל-Cloud Storage, ל-Vertex AI ול-Video Intelligence API.

SERVICE_ACCOUNT="cloud-run-video-description"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run Video Scene Image Describer service account"
 
# to view & download storage bucket objects
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/storage.objectViewer

# to call the Vertex AI imagetext model
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/aiplatform.user

7. פריסת השירות Cloud Run

עכשיו אפשר להשתמש בפריסה מבוססת מקור כדי ליצור באופן אוטומטי קונטיינרים לשירות Cloud Run.

הערה: זמן העיבוד שמוגדר כברירת מחדל לשירות Cloud Run הוא 60 שניות. הזמן הקצוב לתפוגה של Codelab הוא 5 דקות כי סרטון הבדיקה המוצע הוא באורך 2 דקות. יכול להיות שתצטרכו לשנות את משך הזמן אם אתם משתמשים בסרטון שאורכו ארוך יותר.

gcloud run deploy $SERVICE_NAME \
  --region=$REGION \
  --set-env-vars BUCKET_ID=$BUCKET_ID \
  --no-allow-unauthenticated \
  --service-account $SERVICE_ACCOUNT_ADDRESS \
  --timeout=5m \
  --source=.

לאחר הפריסה, שומרים את כתובת ה-URL של השירות במשתנה סביבה.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --platform managed --region $REGION --format 'value(status.url)')

8. קריאה לשירות Cloud Run

עכשיו אפשר להתקשר לשירות על ידי ציון שם הסרטון שהעלית ל-Cloud Storage.

curl -X GET -H "Authorization: Bearer $(gcloud auth print-identity-token)" ${SERVICE_URL}?filename=${FILENAME}

התוצאות אמורות להיות דומות לפלט לדוגמה הבא:

[{"timestamp":1,"description":"an aerial view of a city with a bridge in the background"},{"timestamp":7,"description":"a man in a blue shirt sits in front of shelves of donuts"},{"timestamp":11,"description":"a black and white photo of people working in a bakery"},{"timestamp":12,"description":"a black and white photo of a man and woman working in a bakery"}]

9. מעולה!

מזל טוב, השלמת את Codelab!

אנחנו ממליצים לעיין במסמכים בנושא Video Intelligence API, Cloud Run וכתוביות חזותיות ב-Vertex AI.

אילו נושאים דיברנו?

• איך ליצור קובץ אימג' של קונטיינר באמצעות קובץ Docker כדי להתקין קובץ בינארי של צד שלישי
• איך לשמור על העיקרון של הרשאות מינימליות על ידי יצירת חשבון שירות בשביל שירות Cloud Run כדי לקרוא לשירותי Google Cloud אחרים
• איך להשתמש בספריית הלקוח של Video Intelligence משירות Cloud Run
• איך מבצעים קריאה ל-Google APIs כדי לקבל את התיאור החזותי של כל סצנה מ-Vertex AI

10. הסרת המשאבים

כדי להימנע מחיובים לא מכוונים (לדוגמה, אם שירות Cloud Run הזה הופעל בטעות יותר פעמים מההקצאה החודשית של ההפעלה ב-Cloud Run בתוכנית ללא תשלום), אפשר למחוק את השירות של Cloud Run או למחוק את הפרויקט שיצרתם בשלב 2.

כדי למחוק את שירות Cloud Run, נכנסים למסוף Cloud Run Cloud בכתובת https://console.cloud.google.com/run/ ומוחקים את הפונקציה video-describer (או את $SERVICE_NAME אם השתמשתם בשם אחר).

אם בוחרים למחוק את הפרויקט כולו, נכנסים לכתובת https://console.cloud.google.com/cloud-resource-manager, בוחרים את הפרויקט שיצרתם בשלב 2 ובוחרים באפשרות 'מחיקה'. אם תמחקו את הפרויקט, יהיה צריך לבצע שינויים בפרויקטים ב-Cloud SDK. כדי להציג את הרשימה של כל הפרויקטים הזמינים, אפשר להריץ את הפקודה gcloud projects list.