تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. مقدمة

نظرة عامة

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

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

في ما يلي صورة توضيحية حول كيفية عمل مهمة التشغيل في السحابة الإلكترونية:

صورة توضيحية لوصف فيديو لمهمة تشغيل السحابة الإلكترونية

المعلومات التي ستطّلع عليها

كيفية إنشاء صورة حاوية باستخدام ملف Docker لتثبيت برنامج ثنائي لجهة خارجية
كيفية اتّباع مبدأ الحدّ الأدنى من الأذونات المميّزة من خلال إنشاء حساب خدمة لوظيفة 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 حيث يمكنك تحميل الفيديوهات لمعالجتها من خلال "مهمة تشغيل السحابة الإلكترونية" باستخدام الأمر التالي:

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- إنشاء مهمة تشغيل السحابة الإلكترونية

أولاً، أنشئ دليلاً لرمز المصدر والقرص المضغوط في هذا الدليل.

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. نشر مهمة تشغيل السحابة الإلكترونية وتنفيذها

أولاً، تأكَّد من أنّك في الدليل الجذر video-describer-job الخاص بالدرس التطبيقي حول الترميز.

cd .. && pwd

بعد ذلك، يمكنك استخدام هذا الأمر لنشر "مهمة تشغيل السحابة الإلكترونية".

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

الآن، يمكنك تنفيذ مهمة تشغيل السحابة الإلكترونية من خلال تشغيل الأمر التالي:

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

تهانينا على إكمال الدرس التطبيقي حول الترميز.

ننصحك بمراجعة المحتوى المتعلّق بـ 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 Console على الرابط https://console.cloud.google.com/run/ واحذف الدالة video-describer-job (أو $JOB_NAME في حال استخدام اسم مختلف).

إذا اخترت حذف المشروع بالكامل، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة الثانية، ثم اختيار "حذف". إذا حذفت المشروع، ستحتاج إلى تغيير المشاريع في حزمة تطوير البرامج (SDK) للسحابة الإلكترونية. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.