提供事件管理功能的 Vertex AI Vision 人數分析應用程式

1. 目標

總覽

本程式碼研究室將著重於建立端對端的 Vertex AI Vision 應用程式，以透過事件管理功能傳送事件。我們會使用預先訓練的「入住率分析」專用模型內建功能，根據下列事項的擷取結果產生事件：

計算在特定線上穿越道路的車輛和人數。
計算道路上任何固定區域的車輛/人數。
偵測道路任何部分的壅塞情況。

課程內容

如何擷取影片以供串流播放
如何在 Vertex AI Vision 中建立應用程式
入住率分析提供的不同功能及使用方式
如何部署應用程式
瞭解如何搜尋儲存在 Vertex AI Vision 媒體倉儲中的影片。
如何建立 Cloud Function，處理 Occupancy Analytics 模型資料。
如何建立 Pub/Sub 主題和訂閱項目。
如何設定事件管理功能，透過 Pub/Sub 主題傳送事件。

2. 事前準備

在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。前往專案選取器
確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
啟用 Compute Engine 和 Vision AI API。啟用 API

建立服務帳戶：

前往 Google Cloud 控制台中的「Create service account」(建立服務帳戶) 頁面。前往「建立服務帳戶」
選取專案。
在「Service account name」(服務帳戶名稱) 欄位中輸入名稱。Google Cloud 控制台會根據這個名稱填入「Service account ID」(服務帳戶 ID) 欄位。在「Service account description」(服務帳戶說明) 欄位中輸入說明。例如：快速入門導覽課程的服務帳戶。
按一下 [建立並繼續]。
如要提供專案存取權，請將下列角色授予服務帳戶：Vision AI > Vision AI 編輯者、Compute Engine > Compute 執行個體管理員 (Beta 版)、Storage > Storage 物件檢視者 †。在「Select a role」(選取角色) 清單中，選取角色。如要新增其他角色，請按一下「新增其他角色」，然後新增其他角色。注意：「Role」(角色) 欄位會影響服務帳戶在專案中可存取的資源。日後可以撤銷這些角色或授予其他角色。在正式環境中，請勿授予「擁有者」、「編輯者」或「檢視者」角色。而是根據需求，授予預先定義角色或自訂角色。
按一下「繼續」。
按一下「Done」(完成)，即完成建立服務帳戶。請勿關閉瀏覽器視窗，後續步驟會用到。

建立服務帳戶金鑰：

在 Google Cloud 控制台中，點按您建立的服務帳戶電子郵件地址。
點按「Keys」(金鑰)。
依序點按「Add key」(新增金鑰) 和「Create new key」(建立新的金鑰)。
按一下「建立」，系統會將 JSON 金鑰檔案下載至您的電腦。
點選「關閉」。
安裝並初始化 Google Cloud CLI。

† 如果要從 Cloud Storage bucket 複製範例影片檔，才需要這個角色。

3. 擷取影片檔案以進行串流

你可以使用 vaictl 將影片資料串流至入住率分析應用程式。

首先，請在 Cloud 控制台中啟用 Vision AI API

註冊新的串流

按一下 Vertex AI Vision 左側面板中的「串流」分頁標籤。
按一下「註冊」
在「串流名稱」中輸入「traffic-stream」
在區域中輸入「us-central1」
按一下「註冊」

系統需要幾分鐘才能完成註冊。

準備範例影片

您可以使用下列 gsutil cp 指令複製範例影片。請替換下列變數：

來源：要使用的影片檔案位置。你可以使用自己的影片檔案來源 (例如 gs://BUCKET_NAME/FILENAME.mp4)，也可以使用範例影片 (gs://cloud-samples-data/vertex-ai-vision/street_vehicles_people.mp4)(含人物和車輛的影片，來源)

export SOURCE=gs://cloud-samples-data/vertex-ai-vision/street_vehicles_people.mp4
gsutil cp $SOURCE .

將資料擷取到串流中

如要將這個本機影片檔案傳送至應用程式輸入串流，請使用下列指令。您必須進行下列變數替換：

PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION_ID：您的位置 ID。例如 us-central1。詳情請參閱「Cloud 據點」一文。
LOCAL_FILE：本機影片檔案的檔案名稱。例如 street_vehicles_people.mp4。
-loop 旗標：選用。循環處理檔案資料，模擬串流。

export PROJECT_ID=<Your Google Cloud project ID>
export LOCATION_ID=us-central1
export LOCAL_FILE=street_vehicles_people.mp4

這項指令會將影片檔案串流至串流。如果使用 –loop 旗標，影片會循環播放到串流中，直到你停止指令為止。我們會以背景工作形式執行這項指令，確保串流作業持續進行。

( 在開頭加上 nohup，結尾加上「&」，即可將其設為背景工作)

nohup vaictl -p $PROJECT_ID \
    -l $LOCATION_ID \
    -c application-cluster-0 \
    --service-endpoint visionai.googleapis.com \
send video-file to streams 'traffic-stream' --file-path $LOCAL_FILE --loop &

開始 vaictl 擷取作業後，影片可能需要約 100 秒才會顯示在資訊主頁。

串流擷取功能上線後，選取流量串流，即可在 Vertex AI Vision 資訊主頁的「串流」分頁中查看影片動態消息。

前往「串流」分頁

UI 中串流的即時影像 在 Google Cloud 控制台中，即時查看影片擷取至串流的狀態。影片來源： Elizabeth Mavor (已加入像素化效果)，取自 Pixabay。

4. 建立 Cloud 函式

我們需要 Cloud Function 來消化模型的資料，並產生稍後會透過事件管道傳送的事件。

如要進一步瞭解 Cloud Function，請參閱這篇文章。

建立監聽模型的 Cloud 函式

前往 Cloud Functions UI 建立頁面。
設定函式名稱，稍後在事件管理設定中參照這個 Cloud 函式時會用到。
請確認區域與應用程式相符。
調整並儲存觸發條件設定。
按一下「下一步」按鈕，前往「程式碼」部分。
編輯 Cloud 函式。以下是 Node.js 執行階段的範例。

/**
* Responds to any HTTP request.
*
* @param {!express:Request} req HTTP request context.
* @param {!express:Response} res HTTP response context.
*/
exports.hello_http = (req, res) => {
 // Logging statement can be read with cmd `gcloud functions logs read {$functionName}`.
 // For more about logging, please see https://cloud.google.com/functions/docs/monitoring

 // The processor output will be stored in req.body.
 const messageString = constructMessage(req.body);

 // Send your message to operator output with res HTTP response context.
 res.status(200).send(messageString);
};

function constructMessage(data) {
 /**
  * Typically, your processor output should contains appPlatformMetadata & it's designed output.
  * For example here, if your output is of tyoe OccupancyCountingPredictionResult, you will need
  * to construct the return annotation as such. 
  */

 // access appPlatformMetat.
 const appPlatformMetadata = data.appPlatformMetadata;

 // access annotations.
 const annotations = data.annotations.map(annotation => {
  // This is a mock OccupancyCountingPredictionResult annotation.
  return {"annotation" : {"track_info": {"track_id": "12345"}}};
 });

 const events = [];
 for(const annotation of annotations) {
   events.push({
       "event_message": "Detection event",
       "payload" : {
         "description" : "object detected"
       },
       "event_id" : "track_id_12345"
     });
 }

  /**
   * Typically, your cloud function should return a string represent a JSON which has two fields:
   * "annotations" must follow the specification of the target model.
   * "events" should be of type "AppPlatformEventBody".
   */
 const messageJson = {
   "annotations": annotations,
   "events": events,
 };
 return JSON.stringify(messageJson);
}

按一下「Deploy」(部署) 按鈕來部署函式。

5. 建立 Pub/Sub 主題和訂閱項目

我們需要為應用程式提供 Pub/Sub 主題，應用程式才能將事件傳送至該主題。如要接收事件，Pub/Sub 訂閱項目必須訂閱已設定的光纖。

如要進一步瞭解 Pub/Sub 主題，請參閱這篇文章；如要瞭解訂閱項目，請參閱這篇文章。

建立 Pub/Sub 主題

如要建立 Pub/Sub 主題，可以使用 gcloud CLI：(請將 SUBSCRIPTION_ID 替換為設定中的實際值)

gcloud pubsub topics create TOPIC_ID

或者，您也可以使用 Pub/Sub 使用者介面

建立 Pub/Sub 訂閱項目

如要建立 Pub/Sub 訂閱項目，可以使用 gcloud CLI：(您應將 SUBSCRIPTION_ID 和 TOPIC_ID 替換為設定中的實際值)

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \

或者，您也可以使用 Pub/Sub 使用者介面

6. 建立應用程式

首先，請建立處理資料的應用程式。應用程式可視為自動化管道，可連結下列項目：

資料擷取：影片動態饋給會擷取至串流。
資料分析：擷取資料後，即可加入 AI(電腦視覺) 模型。
資料儲存：影片動態饋給的兩個版本 (原始串流和 AI 模型處理的串流) 可以儲存在媒體倉儲中。

在 Google Cloud 控制台中，應用程式會以圖表表示。

建立空白的應用程式

您必須先建立空白應用程式，才能填入應用程式圖表。

在 Google Cloud 控制台中建立應用程式。

前往 Google Cloud 控制台。
開啟 Vertex AI Vision 資訊主頁的「應用程式」分頁。

前往「應用程式」分頁

按一下「建立」按鈕。
輸入 traffic-app 做為應用程式名稱，然後選擇區域。
按一下「Create」(建立)。

新增應用程式元件節點

建立空白應用程式後，即可將三個節點新增至應用程式圖表：

擷取節點：擷取資料的串流資源。
處理節點：根據擷取資料運作的入住率分析模型。
儲存節點：媒體倉儲，用於儲存處理過的影片，並做為中繼資料儲存空間。中繼資料儲存空間包括擷取的影片資料分析資訊，以及 AI 模型推斷的資訊。

在管理中心將元件節點新增至應用程式。

開啟 Vertex AI Vision 資訊主頁的「應用程式」分頁。前往「應用程式」分頁
在流量應用程式行中，選取「查看圖表」。系統會將您導向處理管道的圖表視覺化畫面。

新增資料擷取節點

如要新增輸入串流節點，請在側邊選單的「Connectors」(連接器) 區段中選取「Streams」(串流) 選項。
在隨即開啟的「串流」選單中，選取「來源」部分的「新增串流」。
在「新增串流」選單中，選擇「註冊新串流」，並將 traffic-stream 新增為串流名稱。
如要將串流新增至應用程式圖表，請按一下「新增串流」。

新增資料處理節點

如要新增入住人數計數模型節點，請在側邊選單的「Specialized models」(專業模型) 區段中，選取「occupancy analytics」(入住人數分析) 選項。
保留預設選取的「人物」和「車輛」。
在「線條交叉」中新增線條。使用多點線條工具繪製線條，偵測車輛或人員進出。
繪製活動區，計算該區域內的人數/車輛數。
如果繪製了活動區，請新增停留時間設定，偵測擁擠情況。

(目前系統不支援同時啟用活動區和越線偵測。一次只能使用一項功能)。

新增資料儲存節點

如要新增輸出目的地 (儲存空間) 節點，請在側邊選單的「Connectors」(連接器) 區段中選取「Vertex AI Vision's Media Warehouse」(Vertex AI Vision 的媒體倉儲) 選項。
在「Vertex AI Vision 的媒體倉儲」選單中，按一下「連結倉儲」。
在「Connect Warehouse」(連結倉儲) 選單中，選取「Create new warehouse」(新建倉儲)。將倉儲命名為 traffic-warehouse，並將 TTL 持續時間保留 14 天。
按一下「Create」(建立) 按鈕來新增倉儲。