איך להשתמש במשימות של Cloud Run & ממשקי API של Video Intelligence לעיבוד סרטונים

1. מבוא

סקירה כללית

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

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

האיור הבא ממחיש איך עבודת Cloud Run פועלת:

מה תלמדו

• איך ליצור קובץ אימג' של קונטיינר באמצעות קובץ Docker כדי להתקין קובץ בינארי של צד שלישי
• איך יוצרים חשבון שירות בשביל Cloud Run Job כדי לשלוח קריאה לשירותים אחרים של 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)')
JOB_NAME=video-describer-job
BUCKET_ID=$PROJECT_ID-video-describer
SERVICE_ACCOUNT="cloud-run-job-video"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

4. יצירת חשבון שירות

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

קודם יוצרים את חשבון השירות.

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run Video Scene Image Describer service account"

לאחר מכן, נותנים לחשבון השירות גישה לקטגוריה של Cloud Storage ולממשקי Vertex AI API.

# 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

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

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

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

6. יצירת משימה ב-Cloud Run

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

mkdir video-describer-job && cd $_

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

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

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

הערה: צריך לעדכן את שתי השורות הראשונות שלמטה עם מזהה קטגוריה ושם קובץ הסרטון.

const bucketName = "<YOUR_BUCKET_ID>";
const videoFilename = "<YOUR-VIDEO-FILENAME>";

const { captureImages } = require("./helpers/imageCapture.js");
const { detectSceneChanges } = require("./helpers/sceneDetector.js");
const { getImageCaption } = require("./helpers/imageCaptioning.js");
const storageHelper = require("./helpers/storage.js");
const authHelper = require("./helpers/auth.js");

const fs = require("fs").promises;
const path = require("path");

const main = async () => {

    try {

        // download the file to locally to the Cloud Run Job instance
        let localFilename = await storageHelper.downloadVideoFile(
            bucketName,
            videoFilename
        );

        // PART 1 - Use Video Intelligence API
        // detect all the scenes in the video & save timestamps to an array

        // EXAMPLE OUTPUT
        // Detected scene changes at the following timestamps:
        // [1, 7, 11, 12]
        let timestamps = await detectSceneChanges(localFilename);
        console.log(
            "Detected scene changes at the following timestamps: ",
            timestamps
        );

        // PART 2 - Use ffmpeg via dockerfile install
        // create an image of each scene change
        // and save to a local directory called "output"
        // returns the base filename for the generated images

        // EXAMPLE OUTPUT
        // creating screenshot for scene:  1 at output/video-filename-1.png
        // creating screenshot for scene:  7 at output/video-filename-7.png
        // creating screenshot for scene:  11 at output/video-filename-11.png
        // creating screenshot for scene:  12 at output/video-filename-12.png
        // returns the base filename for the generated images
        let imageBaseName = await captureImages(localFilename, timestamps);

        // PART 3a - get Access Token to call Vertex AI APIs via REST
        // needed for the image captioning
        // since we're calling the Vertex AI APIs directly
        let accessToken = await authHelper.getAccessToken();
        console.log("got an access token");

        // PART 3b - use Image Captioning to describe each scene per screenshot
        // EXAMPLE OUTPUT
        /*
        [
            {
                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"
            }
        ]; */

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

        // for each timestamp, send the image to Vertex AI
        console.log("getting Vertex AI description for each timestamps");
        scenes = await Promise.all(
            timestamps.map(async (timestamp) => {
                let filepath = path.join(
                    "./output",
                    imageBaseName + "-" + timestamp + ".png"
                );

                // get the base64 encoded image bc sending via REST
                const encodedFile = await fs.readFile(filepath, "base64");

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

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

        console.log("finished collecting all the scenes");
        console.log(scenes);
    } catch (error) {
        //return an error
        console.error("received error: ", error);
    }
};

// Start script
main().catch((err) => {
    console.error(err);
});

לאחר מכן, יוצרים את 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 job on container startup.
CMD [ "npm", "start" ]

יוצרים קובץ בשם .dockerignore כדי להתעלם מהוספת קבצים מסוימים למאגר.

Dockerfile
.dockerignore
node_modules
npm-debug.log

עכשיו יוצרים תיקייה בשם helpers. התיקייה הזו תכיל 5 קבצים מסייעים.

mkdir helpers
cd helpers

לאחר מכן, יוצרים קובץ 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");
        return imageBaseName; // return the base filename for each image
    }
};

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

לבסוף, יוצרים קובץ בשם imageCaptioning.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 = {
    getImageCaption: async function (token, encodedFile) {
        // this example shows you how to call the Vertex REST APIs directly
        // https://cloud.google.com/vertex-ai/generative-ai/docs/image/image-captioning#get-captions-short
        // https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/image-captioning

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

יוצרים קובץ בשם auth.js. הקובץ הזה ישתמש בספריית הלקוח של Google לאימות כדי לקבל טוקן גישה שנדרש כדי לקרוא ישירות לנקודות הקצה של Vertex AI.

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

לבסוף, יוצרים קובץ בשם storage.js. הקובץ הזה ישתמש בספריות הלקוח של Cloud Storage כדי להוריד סרטון מאחסון בענן.

const { Storage } = require("@google-cloud/storage");

module.exports = {
    downloadVideoFile: async function (bucketName, 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;
    }
};

7. פריסה והפעלה של משימה ב-Cloud Run

קודם כל, מוודאים שאתם בספריית הבסיס video-describer-job של ה-codelab.

cd .. && pwd

אחר כך אפשר להשתמש בפקודה הזו כדי לפרוס את Cloud Run Job.

gcloud run jobs deploy $JOB_NAME  --source . --region $REGION

עכשיו אפשר להריץ את Cloud Run Job באמצעות הפקודה הבאה:

gcloud run jobs execute $JOB_NAME

אחרי שהעבודה מסתיימת, אפשר להריץ את הפקודה הבאה כדי לקבל קישור ל-URI של היומן. (אפשר גם להשתמש ב-Cloud Console ולעבור ישירות אל Cloud Run Jobs כדי לראות את היומנים).

gcloud run jobs executions describe <JOB_EXECUTION_ID>

הפלט הבא אמור להופיע ביומנים:

[{ timestamp: 1, description: 'what is google cloud vision api ? is written on a white background .'},
{ timestamp: 3, description: 'a woman wearing a google cloud vision api shirt sits at a table'},
{ timestamp: 18, description: 'a person holding a cell phone with the words what is cloud vision api on the bottom' }, ...]

8. מעולה!

כל הכבוד, סיימתם את ה-Codelab!

מומלץ לעיין במסמכי התיעוד בנושא Video Intelligence API,‏ Cloud Run ויצירת תיאורים לתמונות ב-Vertex AI.

מה נכלל

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

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

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

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

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