使用向量化執行影片擷取 (4.0 預覽版)

發行項
10/16/2024

Azure AI 影片擷取 API 是 Azure AI 視覺的一部分，可讓開發人員建立索引、將文件 (影片和影像) 新增至其中，以及使用自然語言進行搜尋。開發人員可以定義每個索引的中繼資料結構描述，並將中繼資料內嵌至服務，以協助擷取。開發人員也可以指定要從索引中擷取的功能 (視覺、語音)，並根據功能篩選其搜尋。

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
一旦您具有 Azure 訂用帳戶，請使用入口網站建立視覺資源。對於此預覽版，您必須在下列其中一個區域中建立資源 - 澳大利亞東部、瑞士北部、瑞典中部或美國東部。
Azure 儲存體資源 - 建立一個

輸入需求

支援的格式

檔案格式	描述
`asf`	ASF (進階/主動串流格式)
`avi`	AVI (音訊視訊交錯格式)
`flv`	FLV (Flash 視訊)
`matroskamm`, `webm`	Matroska/WebM
`mov`、`mp4`、`m4a`、`3gp`、`3g2`、`mj2`	QuickTime/MOV

支援的視訊轉碼器

Codec	格式
`h264`	H.264/AVC/MPEG-4 AVC/MPEG-4 第 10 部分
`h265`	H.265/HEVC
`libvpx-vp9`	libvpx VP9 (轉碼器 vp9)
`mpeg4`	MPEG-4 第 2 部分

支援的音訊轉碼器

Codec	格式
`aac`	AAC (進階音訊編碼)
`mp3`	MP3 (MPEG 音訊層 3)
`pcm`	PCM (未壓縮)
`vorbis`	Vorbis
`wmav2`	Windows Media 音訊 2

呼叫影片擷取 API

若要在一般模式中使用影片擷取 API，您將會執行下列步驟：

使用 PUT - 建立索引來建立索引。
使用 PUT - CreateIngestion 將影片文件新增至索引。
等待擷取完成，同時使用 GET - ListIngestions 進行檢查。
使用 POST - SearchByText 搜尋關鍵字或片語。

使用影片擷取 API 進行中繼資料型搜尋

影片擷取 API 可讓使用者將中繼資料新增至影片檔案。中繼資料是與影片檔案相關聯的額外資訊，例如「相機識別碼」、「時間戳記」或「位置」，其可用來組織、篩選及搜尋特定影片。此範例示範如何建立索引、新增具有相關聯中繼資料的影片檔案，以及使用不同的功能執行搜尋。

步驟 1：建立索引

若要開始，您必須建立索引來儲存並組織影片檔案及其中繼資料。下列範例示範如何使用建立索引 API 來建立名為 "my-video-index" 的索引。

curl.exe -v -X PUT "https://<YOUR_ENDPOINT_URL>/computervision/retrieval/indexes/my-video-index?api-version=2023-05-01-preview" -H "Ocp-Apim-Subscription-Key: <YOUR_SUBSCRIPTION_KEY>" -H "Content-Type: application/json" --data-ascii "
{
  'metadataSchema': {
    'fields': [
      {
        'name': 'cameraId',
        'searchable': false,
        'filterable': true,
        'type': 'string'
      },
      {
        'name': 'timestamp',
        'searchable': false,
        'filterable': true,
        'type': 'datetime'
      }
    ]
  },
  'features': [
    {
      'name': 'vision',
      'domain': 'surveillance'
    },
    {
      'name': 'speech'
    }
  ]
}"

回應：

HTTP/1.1 201 Created
Content-Length: 530
Content-Type: application/json; charset=utf-8
request-id: cb036529-d1cf-4b44-a1ef-0a4e9fc62885
api-supported-versions: 2023-01-15-preview,2023-05-01-preview
x-envoy-upstream-service-time: 202
Date: Thu, 06 Jul 2023 18:05:05 GMT
Connection: close

{
  "name": "my-video-index",
  "metadataSchema": {
    "language": "en",
    "fields": [
      {
        "name": "cameraid",
        "searchable": false,
        "filterable": true,
        "type": "string"
      },
      {
        "name": "timestamp",
        "searchable": false,
        "filterable": true,
        "type": "datetime"
      }
    ]
  },
  "userData": {},
  "features": [
    {
      "name": "vision",
      "modelVersion": "2023-05-31",
      "domain": "surveillance"
    },
    {
      "name": "speech",
      "modelVersion": "2023-06-30",
      "domain": "generic"
    }
  ],
  "eTag": "\"7966244a79384cca9880d67a4daa9eb1\"",
  "createdDateTime": "2023-07-06T18:05:06.7582534Z",
  "lastModifiedDateTime": "2023-07-06T18:05:06.7582534Z"
}

步驟 2：將影片檔案新增至索引

接下來，您可以將影片檔案及其相關聯的中繼資料新增至索引。下列範例示範如何透過建立擷取 API 使用 SAS URL 將兩個影片檔案新增至索引。

curl.exe -v -X PUT "https://<YOUR_ENDPOINT_URL>/computervision/retrieval/indexes/my-video-index/ingestions/my-ingestion?api-version=2023-05-01-preview" -H "Ocp-Apim-Subscription-Key: <YOUR_SUBSCRIPTION_KEY>" -H "Content-Type: application/json" --data-ascii "
{
  'videos': [
    {
      'mode': 'add',
      'documentId': '02a504c9cd28296a8b74394ed7488045',
      'documentUrl': 'https://example.blob.core.windows.net/videos/02a504c9cd28296a8b74394ed7488045.mp4?sas_token_here',
      'metadata': {
        'cameraId': 'camera1',
        'timestamp': '2023-06-30 17:40:33'
      }
    },
    {
      'mode': 'add',
      'documentId': '043ad56daad86cdaa6e493aa11ebdab3',
      'documentUrl': '[https://example.blob.core.windows.net/videos/043ad56daad86cdaa6e493aa11ebdab3.mp4?sas_token_here',
      'metadata': {
        'cameraId': 'camera2'
      }
    }
  ]
}"

回應：

HTTP/1.1 202 Accepted
Content-Length: 152
Content-Type: application/json; charset=utf-8
request-id: ee5e48df-13f8-4a87-a337-026947144321
operation-location: http://api.example.com.trafficmanager.net/retrieval/indexes/my-test-index/ingestions/my-ingestion
api-supported-versions: 2023-01-15-preview,2023-05-01-preview
x-envoy-upstream-service-time: 709
Date: Thu, 06 Jul 2023 18:15:34 GMT
Connection: close

{
  "name": "my-ingestion",
  "state": "Running",
  "createdDateTime": "2023-07-06T18:15:33.8105687Z",
  "lastModifiedDateTime": "2023-07-06T18:15:34.3418564Z"
}

步驟 3：等待擷取完成

將影片檔案新增至索引後，擷取流程即啟動。視檔案的大小和數目而定，這可能需要一些時間。為了確保擷取在執行搜尋之前已完成，您可以使用取得擷取 API 來檢查狀態。請等候此呼叫傳回 "state" = "Completed"，再繼續進行下一個步驟。

curl.exe -v -X GET "https://<YOUR_ENDPOINT_URL>/computervision/retrieval/indexes/my-video-index/ingestions?api-version=2023-05-01-preview&$top=20" -H "ocp-apim-subscription-key: <YOUR_SUBSCRIPTION_KEY>"

回應：

HTTP/1.1 200 OK
Content-Length: 164
Content-Type: application/json; charset=utf-8
request-id: 4907feaf-88f1-4009-a1a5-ad366f04ee31
api-supported-versions: 2023-01-15-preview,2023-05-01-preview
x-envoy-upstream-service-time: 12
Date: Thu, 06 Jul 2023 18:17:47 GMT
Connection: close

{
  "value": [
    {
      "name": "my-ingestion",
      "state": "Completed",
      "createdDateTime": "2023-07-06T18:15:33.8105687Z",
      "lastModifiedDateTime": "2023-07-06T18:15:34.3418564Z"
    }
  ]
}

步驟 4：使用中繼資料執行搜尋

將影片檔案新增至索引之後，您可以使用中繼資料來搜尋特定影片。此範例示範兩種類型的搜尋：一種使用「視覺」功能，另一種使用「語音」功能。

使用「視覺」功能進行搜尋

若要使用「視覺」功能執行搜尋，請使用依文字搜尋 API 搭配 vision 篩選條件，同時指定查詢文字和任何其他所需的篩選條件。

curl.exe -v -X POST "https://<YOUR_ENDPOINT_URL>/computervision/retrieval/indexes/my-video-index:queryByText?api-version=2023-05-01-preview" -H "Ocp-Apim-Subscription-Key: <YOUR_SUBSCRIPTION_KEY>" -H "Content-Type: application/json" --data-ascii "
{
  'queryText': 'a man with black hoodie',
  'filters': {
    'stringFilters': [
      {
        'fieldName': 'cameraId',
        'values': [
          'camera1'
        ]
      }
    ],
    'featureFilters': ['vision']
  }
}"

回應：

HTTP/1.1 200 OK
Content-Length: 3289
Content-Type: application/json; charset=utf-8
request-id: 4c2477df-d89d-4a98-b433-611083324a3f
api-supported-versions: 2023-05-01-preview
x-envoy-upstream-service-time: 233
Date: Thu, 06 Jul 2023 18:42:08 GMT
Connection: close

{
  "value": [
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "VideoFrame",
      "start": "00:01:58",
      "end": "00:02:09",
      "best": "00:02:03",
      "relevance": 0.23974405229091644
    },
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "VideoFrame",
      "start": "00:02:27",
      "end": "00:02:29",
      "best": "00:02:27",
      "relevance": 0.23762696981430054
    },
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "VideoFrame",
      "start": "00:00:26",
      "end": "00:00:27",
      "best": "00:00:26",
      "relevance": 0.23250913619995117
    },
  ]
}

使用「語音」功能進行搜尋

若要使用「語音」功能執行搜尋，請使用依文字搜尋 API 搭配 speech 篩選條件，同時提供查詢文字和任何其他所需的篩選條件。

curl.exe -v -X POST "https://<YOUR_ENDPOINT_URL>com/computervision/retrieval/indexes/my-video-index:queryByText?api-version=2023-05-01-preview" -H "Ocp-Apim-Subscription-Key: <YOUR_SUBSCRIPTION_KEY>" -H "Content-Type: application/json" --data-ascii "
{
  'queryText': 'leave the area',
  'dedup': false,
  'filters': {
    'stringFilters': [
      {
        'fieldName': 'cameraId',
        'values': [
          'camera1'
        ]
      }
    ],
    'featureFilters': ['speech']
  }
}"

回應：

HTTP/1.1 200 OK
Content-Length: 49001
Content-Type: application/json; charset=utf-8
request-id: b54577bb-1f46-44d8-9a91-c9326df3ac23
api-supported-versions: 2023-05-01-preview
x-envoy-upstream-service-time: 148
Date: Thu, 06 Jul 2023 18:43:07 GMT
Connection: close

{
  "value": [
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "SpeechTextSegment",
      "start": "00:07:07.8400000",
      "end": "00:07:08.4400000",
      "best": "00:07:07.8400000",
      "relevance": 0.8597901463508606
    },
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "SpeechTextSegment",
      "start": "00:07:02.0400000",
      "end": "00:07:03.0400000",
      "best": "00:07:02.0400000",
      "relevance": 0.8506758213043213
    },
    {
      "documentId": "02a504c9cd28296a8b74394ed7488045",
      "documentKind": "SpeechTextSegment",
      "start": "00:07:10.4400000",
      "end": "00:07:11.5200000",
      "best": "00:07:10.4400000",
      "relevance": 0.8474636673927307
    }
  ]
}

下一步

多模式內嵌概念

共用方式為

使用向量化執行影片擷取 (4.0 預覽版)

必要條件

輸入需求

支援的格式

支援的視訊轉碼器

支援的音訊轉碼器

呼叫影片擷取 API

使用影片擷取 API 進行中繼資料型搜尋

步驟 1：建立索引

步驟 2：將影片檔案新增至索引

步驟 3：等待擷取完成

步驟 4：使用中繼資料執行搜尋

使用「視覺」功能進行搜尋

使用「語音」功能進行搜尋

下一步

意見反應

其他資源