יצירת שירות של תיאור תמונת סצנה אחרי סצנה באמצעות 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 Console.
• כבר פרסתם שירות Cloud Run. לדוגמה, אפשר לפעול לפי ההוראות שבמדריך למתחילים לפריסת שירות אינטרנט מקוד מקור.

הפעלת Cloud Shell

1. ב-Cloud Console, לוחצים על 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

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

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];
    }
}

יצירת קובץ Dockerfile וקובץ ‎ .dockerignore

מכיוון שהשירות הזה משתמש ב-ffmpeg, צריך ליצור Dockerfile שמתקין את 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 Console של Cloud Run בכתובת https://console.cloud.google.com/run/ ומוחקים את הפונקציה video-describer (או את ‎ $SERVICE_NAME אם השתמשתם בשם אחר).

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