共用方式為

遙測和疑難排解

  • 發行項

重要

2025 年 3 月 30 日，Azure AI 視覺空間分析將會淘汰。 請在指定的日期之前轉換至 Azure AI 影片索引器 或其他開放原始碼解決方案。 我們鼓勵您更快切換，以取得 Azure AI 影片索引器更豐富的優點。 除了您所使用的熟悉功能之外，以下是 Azure AI 視覺空間分析和 Azure AI 影片索引器之間的快速比較。

功能 Azure AI 視覺空間分析 Azure AI Video Indexer
Edge 支援 Yes Yes
物件偵測 僅限人員與車輛偵測 偵測1000個以上的物件
音訊/語音處理 不支援 支援 （包括語音轉譯、翻譯和摘要）
支援 >（包括語音轉譯和情感分析）
事件偵測和追蹤 支援 （追蹤人員和車輛， 事件偵測 ） Edge 尚不支援。 雲端部分支援。
Azure Arc 支援 不支援 原生支援
重點領域 使用特製化追蹤進行可視化分析 全面分析音訊和視覺內容

從現在到 2025 年 3 月 30 日，您可以在指定的日期之前繼續使用 Azure AI 視覺空間分析或轉換至 Azure AI 影片索引器 。 在 2025 年 3 月 30 日之後，將不再支援空間分析容器，並停止處理新的數據流。

空間分析包含一組功能，可監視系統的健康情況，並協助診斷問題。

啟用視覺效果

若要在視訊畫面中啟用 AI 見解事件的視覺效果，您需要在桌上型電腦或 Azure VM 上使用空間分析作業的 .debug 版本。 視覺效果不適用於 Azure Stack Edge 裝置。 有四個可用的偵錯作業。

如果您的裝置是本機桌上型電腦或 Azure GPU VM (已啟用遠端桌面)，則您可以切換至任何作業的 .debug 版本，並將輸出視覺化。

  1. 在本機或使用執行空間分析的主機電腦上的遠端桌面用戶端，開啟桌面。

  2. 在終端機中，執行 xhost +

  3. 使用 DISPLAY 環境變數的值，更新 spaceanalytics 模組下的部署資訊清單。 在主機電腦上的終端機中執行 echo $DISPLAY，可以找到其值。

    "env": {        
    "DISPLAY": {
        "value": ":11"
        }
}

  4. 在您想要在偵錯模式下執行的部署資訊清單中，更新圖表。 在下列範例中，我們會將 operationId 更新為 cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug。 需要有新的參數 VISUALIZER_NODE_CONFIG，才能啟用視覺化檢視視窗。 所有作業都可以在偵錯類別中使用。 使用共用節點時，請使用 cognitiveservices.vision.spatialanalysis.debug 作業，並將 VISUALIZER_NODE_CONFIG 新增到執行個體參數。

    "zonecrossing": {
     "operationId" : "cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug",
     "version": 1,
     "enabled": true,
     "parameters": {
         "VIDEO_URL": "Replace http url here",
         "VIDEO_SOURCE_ID": "zonecrossingcamera",
         "VIDEO_IS_LIVE": false,
        "VIDEO_DECODE_GPU_INDEX": 0,
         "DETECTOR_NODE_CONFIG": "{ \"gpu_index\": 0 }",
        "CAMERACALIBRATOR_NODE_CONFIG": "{ \"gpu_index\": 0}",
        "VISUALIZER_NODE_CONFIG": "{ \"show_debug_video\": true }",
         "SPACEANALYTICS_CONFIG": "{\"zones\":[{\"name\":\"queue\",\"polygon\":[[0.3,0.3],[0.3,0.9],[0.6,0.9],[0.6,0.3],[0.3,0.3]], \"threshold\":35.0}]}"
     }
}

  5. 重新部署，您將會在主機電腦上看到視覺化檢視視窗

  6. 完成部署之後，您可能必須將 .Xauthority 檔案從主機電腦複製到容器，然後將其重新啟動。 在下列範例中，peopleanalytics 是主機電腦上的容器名稱。

    sudo docker cp $XAUTHORITY peopleanalytics:/root/.Xauthority
sudo docker stop peopleanalytics
sudo docker start peopleanalytics
xhost +

收集系統健康情況遙測

Telegraf 是可搭配空間分析使用的開放原始碼映像，而且可在 Microsoft Container Registry 中取得。 Telegraf 採用下列輸入，並將其傳送至 Azure 監視器。 您可以使用所需的自訂輸入和輸出，建置 Telegraf 模組。 空間分析中的 Telegraf 模組設定是部署資訊清單的一部分 (以上連結)。 此模組是選用的，如果不需要，可以從資訊清單中移除。

輸入：

  • 空間分析計量
  • 磁碟計量
  • CPU 計量
  • Docker 計量
  • GPU 計量

輸出：

  • Azure 監視器

提供的空間分析 Telegraf 模組會將空間分析容器發出的所有遙測資料發佈至 Azure 監視器。 如需有關將 Azure 監視器新增至訂用帳戶的詳細資訊，請參閱 Azure 監視器。

設定 Azure 監視器之後，您將需要建立可讓模組傳送遙測的認證。 您可以使用 Azure 入口網站建立新的服務主體，或使用以下的 Azure CLI 命令建立一個。

注意

此命令會要求您擁有訂用帳戶的擁有者權限。

# Find your Azure IoT Hub resource ID by running this command. The resource ID  should start with something like 
# "/subscriptions/b60d6458-1234-4be4-9885-c7e73af9ced8/resourceGroups/..."
az iot hub list

# Create a Service Principal with `Monitoring Metrics Publisher` role in the IoTHub resource:
# Save the output from this command. The values will be used in the deployment manifest. The password won't be shown again so make sure to write it down
az ad sp create-for-rbac --role="Monitoring Metrics Publisher" --name "<principal name>" --scopes="<resource ID of IoT Hub>"

在 Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的部署資訊清單中，尋找 Telegraf 模組，並將下列值取代為上一個步驟中的服務主體資訊，然後重新部署。

"Telegraf": { 
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/Telegraf:1.0",
  "createOptions":   "{\"HostConfig\":{\"Runtime\":\"nvidia\",\"NetworkMode\":\"azure-iot-edge\",\"Memory\":33554432,\"Binds\":[\"/var/run/docker.sock:/var/run/docker.sock\"]}}"
},
"type": "docker",
"env": {
    "AZURE_TENANT_ID": {
        "value": "<Tenant Id>"
    },
    "AZURE_CLIENT_ID": {
        "value": "Application Id"
    },
    "AZURE_CLIENT_SECRET": {
        "value": "<Password>"
    },
    "region": {
        "value": "<Region>"
    },
    "resource_id": {
        "value": "/subscriptions/{subscriptionId}/resourceGroups/{resoureGroupName}/providers/Microsoft.Devices/IotHubs/{IotHub}"
    },
...

部署 Telegraf 模組之後，就可以透過 Azure 監視器服務，或在 Azure 入口網站的 IoT 中樞選取 [監視]，存取回報的計量。

Azure 監視器遙測報告

系統健康情況事件

事件名稱 描述
archon_exit 當使用者將空間分析模組狀態從執行中變更為已停止時傳送。
archon_error 當容器內的任何程序損毀時傳送。 此為重大錯誤。
InputRate 圖形處理影片輸入的速率。 每五分鐘報告一次。
OutputRate 圖形輸出 AI 見解的速率。 每五分鐘報告一次。
archon_allGraphsStarted 在所有圖表都完成啟動時傳送。
archon_configchange 在圖表設定變更時傳送。
archon_graphCreationFailed 當含有報告 graphId 的圖表無法啟動時傳送。
archon_graphCreationSuccess 當含有報告 graphId 的圖表成功啟動時傳送。
archon_graphCleanup 當含有報告 graphId 的圖表清除並結束時傳送。
archon_graphHeartbeat 針對每個技能圖表每分鐘傳送的活動訊號。
archon_apiKeyAuthFail 當視覺資源金鑰因為下列原因而無法驗證容器的時間超過 24 小時時傳送：配額不足、無效、離線。
VideoIngesterHeartbeat 每小時傳送一次，表示影片會從影片來源進行串流處理，並顯示該小時的錯誤數目。 針對每個圖表回報一次。
VideoIngesterState 針對影片串流處理回報已停止或已啟動。 針對每個圖表回報一次。

針對 IoT Edge 裝置進行疑難排解

您可以使用 iotedge 命令列工具，檢查執行中模組的狀態和記錄。 例如：

  • iotedge list：報告執行中模組的清單。 您可以使用 iotedge logs edgeAgent 進一步檢查錯誤。 如果 iotedge 停滯，您可以嘗試使用 iotedge restart edgeAgent 將其重新啟動
  • iotedge logs <module-name>
  • iotedge restart <module-name> 重新啟動特定模組

使用診斷容器收集記錄檔

空間分析會產生可供您用來診斷執行階段問題或包含在支援票證中的 Docker 偵錯記錄。 空間分析診斷模組在 Microsoft Container Registry 中，可供您下載。 在 Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的資訊清單部署檔案中，尋找診斷模組。

在 "env" 區段中，新增下列設定：

"diagnostics": {  
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/diagnostics:1.0",
  "createOptions":   "{\"HostConfig\":{\"Mounts\":[{\"Target\":\"/usr/bin/docker\",\"Source\":\"/home/data/docker\",\"Type\":\"bind\"},{\"Target\":\"/var/run\",\"Source\":\"/run\",\"Type\":\"bind\"}],\"LogConfig\":{\"Config\":{\"max-size\":\"500m\"}}}}"
  }

若要將上傳至遠端端點的記錄最佳化 (例如 Azure Blob 儲存體)，建議您維持小型檔案大小。 請參閱下列範例以取得建議的 Docker 記錄設定。

{
    "HostConfig": {
        "LogConfig": {
            "Config": {
                "max-size": "500m",
                "max-file": "1000"
            }
        }
    }
}

設定記錄層級

記錄層級設定可讓您控制所產生記錄的詳細資訊。 支援的記錄層級為：none、verbose、info、warning 和 error。 節點和平台的預設記錄詳細資訊層級為 info。

您可以將 ARCHON_LOG_LEVEL 環境變數設定為其中一個允許的值，以便在全域修改記錄層級。 您也可以在全域針對所有已部署的技能，或透過設定 platformLogLevel 和 nodesLogLevel 的值，以針對每個特定技能，透過 IoT Edge 模組對應項文件設定記錄層級，如下所示。

{
    "version": 1,
    "properties": {
        "desired": {
            "globalSettings": {
                "platformLogLevel": "verbose"
            },
            "graphs": {
                "samplegraph": {
                    "nodesLogLevel": "verbose",
                    "platformLogLevel": "verbose"
                }
            }
        }
    }
}

收集記錄

注意

diagnostics 模組不會影響記錄內容，只有助於收集、篩選和上傳現有的記錄。 您必須擁有 Docker API 1.40 版或更新版本，才能使用此模組。

Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的範例部署資訊清單檔包含一個名為 diagnostics 的模組，可收集和上傳記錄。 此模組預設為停用狀態，而且當您需要存取記錄時，應該透過 IoT Edge 模組設定來啟用。

diagnostics 集合可視需要透過 IoT Edge 直接方法控制，而且可以將記錄傳送至 Azure Blob 儲存體。

設定診斷上傳目標

從 IoT Edge 入口網站選取您的裝置，然後選取診斷模組。 在 Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的範例部署資訊清單檔中，針對名為 env 的診斷，尋找 [環境變數] 區段，並新增下列資訊：

將上傳設定為 Azure Blob 儲存體

  1. 建立您自己的 Azure Blob 儲存體帳戶 (如果您還沒有的話)。
  2. 從 Azure 入口網站取得您儲存體帳戶的連接字串。 該字串位於存取金鑰中。
  3. 空間分析記錄會自動上傳至名為 rtcvlogs 的 Blob 儲存體容器中，且檔案名稱格式如下：{CONTAINER_NAME}/{START_TIME}-{END_TIME}-{QUERY_TIME}.log。
"env":{
    "IOTEDGE_WORKLOADURI":"fd://iotedge.socket",
    "AZURE_STORAGE_CONNECTION_STRING":"XXXXXX",   //from the Azure Blob Storage account
    "ARCHON_LOG_LEVEL":"info"
}

上傳空間分析記錄

記錄是使用 getRTCVLogs IoT Edge 方法，視需要上傳到 diagnostics 模組中。

  1. 移至 IoT 中樞入口網站頁面，選取 [Edge 裝置]，然後選取您的裝置和診斷模組。
  2. 移至模組的詳細資料頁面，然後選取 [直接方法] 索引標籤。
  3. 在 [方法名稱] 上輸入 getRTCVLogs，並在承載中輸入 json 格式字串。 您可以輸入 {}，這表示空白承載。
  4. 設定連線和方法逾時，然後選取 [叫用方法]。
  5. 選取您的目標容器，並使用記錄語法一節中所述的參數，建置承載 json 字串。 選取 [叫用方法] 以執行要求。

注意

使用空白承載叫用 getRTCVLogs 方法時，將會傳回在裝置上部署的所有容器的清單。 方法名稱會區分大小寫。 如果指定了不正確的方法名稱，您將會收到 501 錯誤。

叫用 getRTCVLogs 方法getRTCVLogs Direct 方法頁面

記錄語法

下表列出查詢記錄時可使用的參數。

關鍵字 描述 預設值
StartTime 需要的記錄開始時間 (以 UTC 毫秒為單位)。 -1，容器執行階段的開始時間。 將 [-1.-1] 當作時間範圍使用時，API 會傳回過去一小時的記錄。
EndTime 需要的記錄結束時間 (以 UTC 毫秒為單位)。 -1，目前的時間。 使用 [-1.-1] 時間範圍時，API 會傳回過去一小時的記錄。
ContainerId 用於擷取記錄的目標容器。 null (沒有容器識別碼時)。 API 會傳回所有可用的容器資訊以及識別碼。
DoPost 執行上傳作業。 當此設定為 false 時，其會執行要求的作業，並傳回上傳大小，而不會執行上傳。 當設定為 true 時，其會起始所選記錄的非同步上傳 false，不要上傳。
節流處理 指出每個批次上傳的記錄行數 1000，使用此參數可調整張貼速度。
篩選 篩選要上傳的記錄 null，您可以根據空間分析記錄結構，將篩選指定為索引鍵值組：[UTC, LocalTime, LOGLEVEL,PID, CLASS, DATA]。 例如：{"TimeFilter":[-1,1573255761112]}, {"TimeFilter":[-1,1573255761112]}, {"CLASS":["myNode"]

下表列出查詢回應中的屬性。

關鍵字 描述
DoPost True 或 False。 指出是否已上傳記錄。 當您選擇不上傳記錄時，API 會以同步方式傳回資訊。 當您選擇上傳記錄時，如果要求有效，API 會傳回 200，並以非同步方式開始上傳記錄。
TimeFilter 套用至記錄的時間篩選條件。
ValueFilters 套用至記錄檔的關鍵字篩選條件。
TimeStamp 方法執行開始時間。
ContainerId 目標容器識別碼。
FetchCounter 記錄行總數。
FetchSizeInByte 記錄資料的總量 (以位元組為單位)。
MatchCounter 有效的記錄行數。
MatchSizeInByte 記錄資料的有效數量 (以位元組為單位)。
FilterCount 套用篩選條件之後的記錄行總數。
FilterSizeInByte 套用篩選條件之後的記錄資料總數量 (以位元組單位)。
FetchLogsDurationInMiliSec 擷取作業持續時間。
PaseLogsDurationInMiliSec 篩選作業持續時間。
PostLogsDurationInMiliSec 張貼作業持續時間。

範例要求

{
    "StartTime": -1,
    "EndTime": -1,
    "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
    "DoPost": false,
    "Filters": null
}

範例回應

{
    "status": 200,
    "payload": {
        "DoPost": false,
        "TimeFilter": [-1, 1581310339411],
        "ValueFilters": {},
        "Metas": {
            "TimeStamp": "2020-02-10T04:52:19.4365389+00:00",
            "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
            "FetchCounter": 61,
            "FetchSizeInByte": 20470,
            "MatchCounter": 61,
            "MatchSizeInByte": 20470,
            "FilterCount": 61,
            "FilterSizeInByte": 20470,
            "FetchLogsDurationInMiliSec": 0,
            "PaseLogsDurationInMiliSec": 0,
            "PostLogsDurationInMiliSec": 0
        }
    }
}

檢查擷取記錄的行數、時間和大小，如果那些設定看起來正常，請將 DoPost 取代為 true，並使用相同的篩選條件，將記錄推送至目的地。

針對問題進行疑難排解時，您可以從 Azure Blob 儲存體匯出記錄。

針對 Azure Stack Edge 裝置進行疑難排解

下一節可協助您針對 Azure Stack Edge 裝置的狀態進行偵錯和驗證。

存取 Kubernetes API 端點。 

  1. 在裝置的本機 UI 中，移至 [裝置] 頁面。
  2. 在 [裝置端點] 底下，複製 Kubernetes API 服務端點。 此端點的字串為下列格式：https://compute..[device-IP-address]。
  3. 儲存端點字串。 稍後設定 kubectl 存取 Kubernetes 叢集時，將會用到此資訊。

連線至 PowerShell 介面

從遠端 Windows 用戶端連線。 建立 Kubernetes 叢集之後，您可以透過此叢集管理應用程式。 您將需要連線至裝置的 PowerShell 介面。 視用戶端的作業系統而定，從遠端連線到裝置的程序可能有所不同。 下列步驟適用於執行 PowerShell 的 Windows 用戶端。

提示

  • 開始之前，請確定您的 Windows 用戶端執行的是 Windows PowerShell 5.0 或更新版本。
  • PowerShell 也可以在 Linux 上使用。

  1. 以系統管理員身分執行 Windows PowerShell 工作階段。

    請確定您的用戶端上正在執行 Windows 遠端管理服務。 在命令提示字元中，輸入 winrm quickconfig。

  2. 指派裝置 IP 位址的變數。 例如： $ip = "<device-ip-address>" 。

  3. 使用下列命令，將裝置的 IP 位址新增至用戶端的受信任主機清單。

    Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force

  4. 在裝置上啟動 Windows PowerShell 工作階段。

    Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell

  5. 出現提示時，請提供密碼。 使用與用來登入本機 Web 介面相同的密碼。 預設的本機 Web 介面密碼為 Password1。

存取 Kubernetes 叢集

建立 Kubernetes 叢集之後，您可以使用 kubectl 命令列工具存取叢集。

  1. 建立新的命名空間。

    New-HcsKubernetesNamespace -Namespace

  2. 建立使用者並取得組態檔。 此命令會輸出 Kubernetes 叢集的設定資訊。 複製此資訊，並將其儲存在名為 config 的檔案中。請勿以檔案副檔名來儲存檔案。

    New-HcsKubernetesUser -UserName

  3. 將 config 檔案新增至本機電腦上使用者設定檔中的 .kube 資料夾。

  4. 為命名空間與您建立的使用者建立關聯。

    Grant-HcsKubernetesNamespaceAccess -Namespace -UserName

  5. 使用下列命令，在您的 Windows 用戶端上安裝 kubectl：

    curl https://storage.googleapis.com/kubernetesrelease/release/v1.15.2/bin/windows/amd64/kubectl.exe -O kubectl.exe

  6. 將 DNS 項目新增至系統上的 hosts 檔案。

    1. 以系統管理員身分啟動 [記事本]，然後開啟位於 C:\windows\system32\drivers\etc\hosts 的 hosts 檔案。
    2. 在 hosts 檔案中建立一個項目，其中包含您從本機 UI 的 [裝置] 頁面取得的裝置 IP 位址和 DNS 網域。 您應該使用的端點類似如下：https://compute.asedevice.microsoftdatabox.com/10.100.10.10。

  7. 確認您可以連線至 Kubernetes Pod。

    kubectl get pods -n "iotedge"

若要取得容器記錄，請執行下列命令：

kubectl logs <pod-name> -n <namespace> --all-containers

實用的命令

Command 描述
Get-HcsKubernetesUserConfig -AseUser 產生 Kubernetes 組態檔。 使用命令時，將資訊複製到名為 config 的檔案中。請勿使用檔案副檔名來儲存檔案。
Get-HcsApplianceInfo 傳回您裝置的相關資訊。
Enable-HcsSupportAccess 產生存取認證以啟動支援工作階段。

如何針對空間分析提出支援票證

如果您需要更多支援來解決您遇到的空間分析容器問題，請依照下列步驟，填寫並提交支援票證。 我們的小組將為您提供進一步指導。

填寫基本資訊

在 [新增支援要求] 頁面建立新的支援票證。 依照提示，填寫下列參數：

支援基本

  1. 將 [問題類型] 設定為 Technical。
  2. 選取您要用來部署空間分析容器的訂用帳戶。
  3. 選取 My services 並選取 Azure AI services 作為服務。
  4. 選取您要用來部署空間分析容器的資源。
  5. 撰寫簡短的描述，詳述您遇到的問題。
  6. 選取 Spatial Analysis 作為您的問題類型。
  7. 從下拉式清單中選取適當的子類型。
  8. 選取 [下一步: 解決方案]，移至下一頁。

下一個階段將提供您所選問題類型的建議解決方案。 這些解決方案將會解決最常見的問題，但如果對您的解決方案來說並不實用，請選取 [下一步: 詳細資料]，移至下一個步驟。

詳細資料

在此頁面上，新增一些有關您所遇到之問題的額外詳細資料。 請務必盡可能詳述細節，因為這可協助我們的工程師更清楚地縮小問題的範圍。 請著名您慣用的連絡方法和問題的嚴重性，讓我們可以適當地聯繫您，然後選取 [下一步: 檢閱 + 建立]，移至下一個步驟。

檢閱及建立

檢閱支援要求的詳細資料，以確保一切都正確無誤，並有效地呈現問題。 當您準備就緒時，選取 [建立]，將票證傳送給我們的小組！ 收到票證之後，您將會收到一封電子郵件確認，而且我們的小組會儘快回覆您。 您可以在 Azure 入口網站中檢視您票證的狀態。

下一步