كيفية استخدام وظائف Cloud Run واجهات Video Intelligence API لمعالجة الفيديوهات

1. مقدمة

نظرة عامة

في هذا الدرس العملي، ستنشئ مهمة Cloud Run مكتوبة بلغة Node.js تقدّم وصفًا مرئيًا لكل مشهد في الفيديو. أولاً، ستستخدم مهمتك واجهة برمجة التطبيقات Video Intelligence API لرصد الطوابع الزمنية التي يتغير فيها المشهد. بعد ذلك، ستستخدم مهمتك برنامجًا ثنائيًا تابعًا لجهة خارجية باسم ffmpeg لالتقاط لقطة شاشة لكل طابع زمني لتغيير المشهد. أخيرًا، يتم استخدام ميزة "وصف الصور" في Vertex AI لتقديم وصف مرئي للقطات الشاشة.

يوضّح هذا الدرس التطبيقي حول الترميز أيضًا كيفية استخدام ffmpeg في مهمة Cloud Run لالتقاط صور من فيديو في طابع زمني محدّد. بما أنّه يجب تثبيت ffmpeg بشكل مستقل، يوضّح لك هذا الدرس التطبيقي كيفية إنشاء ملف شامل لتثبيت ffmpeg كجزء من مهمة Cloud Run.

في ما يلي رسم توضيحي لطريقة عمل Cloud Run Job:

صورة توضيحية لوصف فيديو Cloud Run Job

ما ستتعلمه

كيفية إنشاء صورة حاوية باستخدام Dockerfile لتثبيت ملف ثنائي تابع لجهة خارجية
كيفية اتّباع مبدأ الامتياز الأقل من خلال إنشاء حساب خدمة لـ Cloud Run Job من أجل استدعاء خدمات Google Cloud الأخرى
كيفية استخدام مكتبة برامج Video Intelligence من مهمة Cloud Run
كيفية إرسال طلب إلى Google APIs للحصول على الوصف المرئي لكل مشهد من Vertex AI

2. الإعداد والمتطلبات

المتطلبات الأساسية

يجب أن تكون مسجّلاً الدخول إلى Cloud Console.
سبق لك نشر خدمة Cloud Run. على سبيل المثال، يمكنك اتّباع دليل البدء السريع لنشر خدمة ويب من الرمز المصدر للبدء.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهية هذه الخدمة. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات التطوير اللازمة. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم عملك في هذا الدرس التطبيقي حول الترميز، إن لم يكن كله، باستخدام متصفح.

بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تم إثبات هويتك وأنّه تم ضبط المشروع على رقم تعريف مشروعك.

نفِّذ الأمر التالي في 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`

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك:

gcloud config list project

ناتج الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

3- تفعيل واجهات برمجة التطبيقات وضبط متغيرات البيئة

قبل البدء في استخدام هذا الدرس العملي، عليك تفعيل العديد من واجهات برمجة التطبيقات. يتطلّب هذا الدرس التطبيقي استخدام واجهات برمجة التطبيقات التالية. يمكنك تفعيل واجهات برمجة التطبيقات هذه من خلال تنفيذ الأمر التالي:

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

بعد ذلك، يمكنك ضبط متغيرات البيئة التي سيتم استخدامها في جميع أنحاء هذا الدرس التطبيقي حول الترميز.

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.

# 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 لبرنامج التدريب العملي.

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" مباشرةً للاطّلاع على السجلّات).

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. تهانينا!

تهانينا على إكمال هذا الدرس العملي.

ننصحك بمراجعة المستندات حول Video Intelligence API وCloud Run والتعليق المرئي في Vertex AI.

المواضيع التي تناولناها

كيفية إنشاء صورة حاوية باستخدام Dockerfile لتثبيت ملف ثنائي تابع لجهة خارجية
كيفية اتّباع مبدأ الامتياز الأقل من خلال إنشاء حساب خدمة لـ 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.