你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用矢量化（版本 4.0 预览版）功能进行视频检索

项目
09/03/2024

Azure AI 视频检索 API 是 Azure AI 视觉的一部分，使开发人员能够创建索引、向其添加文档（视频和图像），并使用自然语言进行搜索。开发人员可以为每个索引定义元数据架构，并将元数据引入服务以帮助检索。开发人员还可以指定要从索引中提取哪些功能（视觉、语音），并根据功能筛选其搜索。

先决条件

Azure 订阅 - 免费创建订阅。
拥有 Azure 订阅后，使用门户创建视觉资源。对于此预览版，必须在以下区域之一创建资源：澳大利亚东部、瑞士北部、瑞典中部或美国东部。
Azure 存储资源 - 创建一个

输入要求

支持的格式

文件格式	说明
`asf`	ASF（高级/活动流格式）
`avi`	AVI（音频视频交错）
`flv`	FLV（闪存视频）
`matroskamm`、`webm`	Matroska/WebM
`mov`,`mp4`,`m4a`,`3gp`,`3g2`,`mj2`	QuickTime/MOV

支持的视频编解码器

编解码器	Format
`h264`	H.264/AVC/MPEG-4 AVC/MPEG-4 第 10 部分
`h265`	H.265/HEVC
`libvpx-vp9`	libvpx VP9（编解码器 vp9）
`mpeg4`	MPEG-4 第 2 部分

支持的音频编解码器

编解码器	格式
`aac`	AAC（高级音频编码）
`mp3`	MP3（运动图像专家组音频层面 3）
`pcm`	PCM（解压缩）
`vorbis`	Vorbis
`wmav2`	Windows Media 音频 2

调用视频检索 API

若要在典型模式中使用视频检索 API，请执行以下步骤：

使用 PUT - 创建索引创建索引。
使用 PUT - CreateIngestion 将视频文档添加到索引中。
等待引入完成，使用 GET - ListIngestions 进行检查。
使用 POST - SearchByText 搜索关键字或短语。

使用视频检索 API 进行基于元数据的搜索

视频检索 API 允许用户将元数据添加到视频文件。元数据是与视频文件关联的其他信息（例如“相机 ID”、“时间戳”或“位置”），可用于组织、筛选和搜索特定视频。此示例演示如何创建索引、添加具有关联元数据的视频文件，以及使用不同的功能执行搜索。

步骤 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：使用元数据执行搜索

将视频文件添加到索引后，可以使用元数据搜索特定视频。此示例演示了两种类型的搜索：一种使用“视觉”功能，另一种使用“语音”功能。

使用“视觉”功能进行搜索

若要使用“视觉”功能执行搜索，请使用带有 vision 筛选器的按文本搜索 API，指定查询文本和任何其他所需筛选器。

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
    },
  ]
}

使用“语音”功能进行搜索

若要使用“语音”功能执行搜索，请使用带有 speech 筛选器的按文本搜索 API，提供查询文本和任何其他所需筛选器。

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：使用元数据执行搜索

使用“视觉”功能进行搜索

使用“语音”功能进行搜索

后续步骤

反馈

其他资源