Skip to content

Commit 27a1999

Browse files
PhilKang0704PhilKang0704
authored
Merge pull request #1756 from MicrosoftDocs/main
11/28 11:00 AM IST Publish
2 parents 744c16a + 70799f9 commit 27a1999

File tree

7 files changed

+121
-18
lines changed

7 files changed

+121
-18
lines changed

‎articles/ai-services/computer-vision/concept-face-recognition-data-structures.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,19 +43,29 @@ The Face Identify API uses container data structures to the hold face recognitio
4343

4444
### Person Directory
4545

46-
**PersonDirectory** is the newest data structure of this kind. It supports a larger scale and higher accuracy. Each Azure Face resource has a single default **PersonDirectory** data structure. It's a flat list of **PersonDirectoryPerson** objects - it can hold up to 75 million.
46+
**PersonDirectory** is the newest data structure of this kind. It supports a larger scale and higher accuracy. Each Azure Face resource has a single default **PersonDirectory** data structure. It's a flat list of **PersonDirectoryPerson** objects - it can hold up to 20 million.
4747

4848
**PersonDirectoryPerson** represents a person to be identified. Updated from the **PersonGroupPerson** model, it allows you to add faces from different recognition models to the same person. However, the Identify operation can only match faces obtained with the same recognition model.
4949

50-
**DynamicPersonGroup** is a lightweight data structure that allows you to dynamically reference a **PersonGroupPerson**. It doesn't require the Train operation: once the data is updated, it's ready to be used with the Identify API.
50+
**DynamicPersonGroup** is a lightweight data structure that allows you to dynamically reference a **PersonDirectoryPerson**. It doesn't require the Train operation: once the data is updated, it's ready to be used with the Identify API.
5151

5252
You can also use an **in-place person ID list** for the Identify operation. This lets you specify a more narrow group to identify from. You can do this manually to improve identification performance in large groups.
5353

5454
The above data structures can be used together. For example:
5555
- In an access control system, The **PersonDirectory** might represent all employees of a company, but a smaller **DynamicPersonGroup** could represent just the employees that have access to a single floor of the building.
5656
- In a flight onboarding system, the **PersonDirectory** could represent all customers of the airline company, but the **DynamicPersonGroup** represents just the passengers on a particular flight. An **in-place person ID list** could represent the passengers who made a last-minute change.
5757

58-
For more details, please refer to the [PersonDirectory how-to guide](./how-to/use-persondirectory.md).
58+
For more details, please refer to the [PersonDirectory how-to guide](./how-to/use-persondirectory.md). A quick comparison between **LargePersonGroup** and **PersonDirectory**:
59+
60+
| Detail | LargePersonGroup | PersonDirectory |
61+
| --- | --- | --- |
62+
| Capacity | A **LargePersonGroup** can hold up to 1 million **PersonGroupPerson** objects. | The collection can store up to 20 millions **PersonDirectoryPerson** identities. |
63+
| PersonURI | `/largepersongroups/{groupId}/persons/{personId}` | `(/v1.0-preview-or-above)/persons/{personId}` |
64+
| Ownership | The **PersonGroupPerson** objects are exclusively owned by the **LargePersonGroup** they belong to. If you want a same identity kept in multiple groups, you will have to [Create Large Person Group Person](/rest/api/face/person-group-operations/create-large-person-group-person) and [Add Large Person Group Person Face](/rest/api/face/person-group-operations/add-large-person-group-person-face) for each group individually, ending up with a set of person IDs in several groups. | The **PersonDirectoryPerson** objects are directly stored inside the **PersonDirectory**, as a flat list. You can use an in-place person ID list to [Identify From Person Directory](/rest/api/face/face-recognition-operations/identify-from-person-directory), or optionally [Create Dynamic Person Group](/rest/api/face/person-directory-operations/create-dynamic-person-group) and hybridly include a person into the group. A created **PersonDirectoryPerson** object can be referenced by multiple **DynamicPersonGroup** without duplication. |
65+
| Model | The recognition model is determined by the **LargePersonGroup**. New faces for all **PersonGroupPerson** objects will become associated with this model when they're added to it. | The **PersonDirectoryPerson** object prepares separated storage per recognition model. You can specify the model when you add new faces, but the Identify API can only match faces obtained with the same recognition model, that is associated with the query faces. |
66+
| Training | You must call the Train API to make any new face/person data reflect in the Identify API results. | There's no need to make Train calls, but API such as [Add Person Face](/rest/api/face/person-directory-operations/add-person-face) becomes a long running operation, which means you should use the response header "Operation-Location" to check if the update completes. |
67+
| Cleanup | [Delete Large Person Group](/rest/api/face/person-group-operations/delete-large-person-group) will also delete the all the **PersonGroupPerson** objects it holds, as well as their face data. | [Delete Dynamic Person Group](/rest/api/face/person-directory-operations/delete-dynamic-person-group) will only unreference the **PersonDirectoryPerson**. To delete actual person and the face data, see [Delete Person](/rest/api/face/person-directory-operations/delete-person). |
68+
5969

6070
## Data structures used with Find Similar
6171

‎articles/ai-services/computer-vision/how-to/use-large-scale.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ feedback_help_link_url: https://learn.microsoft.com/answers/tags/156/azure-face
2525
This guide shows you how to scale up from existing **PersonGroup** and **FaceList** objects to **LargePersonGroup** and **LargeFaceList** objects, respectively. **PersonGroups** can hold up to 1000 persons in the free tier and 10,000 in the paid tier, while **LargePersonGroups** can hold up to one million persons in the paid tier.
2626

2727
> [!IMPORTANT]
28-
> The newer data structure **PersonDirectory** is recommended for new development. It can hold up to 75 million identities and does not require manual training. For more information, see the [PersonDirectory guide](./use-persondirectory.md).
28+
> The newer data structure **PersonDirectory** is recommended for new development. It can hold up to 20 million identities and does not require manual training. For more information, see the [PersonDirectory guide](./use-persondirectory.md).
2929
3030
This guide demonstrates the migration process. It assumes a basic familiarity with **PersonGroup** and **FaceList** objects, the **Train** operation, and the face recognition functions. To learn more about these subjects, see the [face recognition](../concept-face-recognition.md) conceptual guide.
3131

‎articles/ai-services/computer-vision/how-to/use-persondirectory.md

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ To perform face recognition operations such as Identify and Find Similar, Face A
2424

2525
## Advantages of PersonDirectory
2626

27-
Currently, the Face API offers the **LargePersonGroup** structure, which has similar functionality but is limited to 1 million identities. The **PersonDirectory** structure can scale up to 75 million identities.
27+
Currently, the Face API offers the **LargePersonGroup** structure, which has similar functionality but is limited to 1 million identities. The **PersonDirectory** structure can scale up to 20 million identities.
2828

2929
Another major difference between **PersonDirectory** and previous data structures is that you'll no longer need to make any Train API calls after adding faces to a **Person** object—the update process happens automatically.
3030

@@ -239,7 +239,7 @@ using (var content = new ByteArrayContent(byteData))
239239
```
240240

241241
> [!NOTE]
242-
> As soon as the call returns, the created **DynamicPersonGroup** will be ready to use in an Identify call, with any **Person** references provided in the process. The completion status of the returned operation ID, on the other hand, indicates the update status of the person-to-group relationship.
242+
> As soon as the call returns, the created **DynamicPersonGroup** will be ready to use in an Identify call, with any **Person** references provided in the process. The completion status of the returned operation ID, on the other hand, only indicates the update status for [Get Dynamic Person Group References](/rest/api/face/person-directory-operations/get-dynamic-person-group-references) lookup calls.
243243
244244
### Update the DynamicPersonGroup
245245

@@ -394,6 +394,97 @@ using (var content = new ByteArrayContent(byteData))
394394

395395
The response will contain a Boolean value indicating whether the service considers the new face to belong to the same **Person**, and a confidence score for the prediction.
396396

397+
## Overview of asynchronous operations
398+
399+
The tables below summarize whether a **PersonDirectory** management call is a long-running operation (LRO) processed asynchronously, or it completes immediately and synchronously:
400+
401+
| Person/Face Management | URI | LRO? |
402+
| --- | --- | --- |
403+
| [Get Persons](/rest/api/face/person-directory-operations/get-persons) | /persons | |
404+
| [Create Person](/rest/api/face/person-directory-operations/create-person) | /persons | ✅ |
405+
| [Get Person](/rest/api/face/person-directory-operations/get-person) | /persons/{personId} | |
406+
| [Update Person](/rest/api/face/person-directory-operations/update-person) | /persons/{personId} | |
407+
| [Delete Person](/rest/api/face/person-directory-operations/delete-person) | /persons/{personId} | ✅ |
408+
| [Get Person Faces](/rest/api/face/person-directory-operations/get-person-faces) | /persons/{personId}/recognitionModels/{model}/persistedfaces | |
409+
| [Add Person Face](/rest/api/face/person-directory-operations/add-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces | ✅ |
410+
| [Add Person Face From Url](/rest/api/face/person-directory-operations/add-person-face-from-url) | /persons/{personId}/recognitionModels/{model}/persistedfaces | ✅ |
411+
| [Get Person Face](/rest/api/face/person-directory-operations/get-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | |
412+
| [Update Person Face](/rest/api/face/person-directory-operations/update-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | |
413+
| [Delete Person Face](/rest/api/face/person-directory-operations/delete-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | ✅ |
414+
415+
| Group Management | URI | LRO? |
416+
| --- | --- | --- |
417+
| [Get Dynamic Person Groups](/rest/api/face/person-directory-operations/get-dynamic-person-groups) | /dynamicpersongroups | |
418+
| [Create Dynamic Person Group](/rest/api/face/person-directory-operations/create-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | |
419+
| [Create Dynamic Person Group With Person](/rest/api/face/person-directory-operations/create-dynamic-person-group-with-person) | /dynamicpersongroups/{dynamicPersonGroupId} | ✅ |
420+
| [Get Dynamic Person Group](/rest/api/face/person-directory-operations/get-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | |
421+
| [Update Dynamic Person Group](/rest/api/face/person-directory-operations/update-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | |
422+
| [Update Dynamic Person Group With Person Changes](/rest/api/face/person-directory-operations/update-dynamic-person-group-with-person-changes) | /dynamicpersongroups/{dynamicPersonGroupId} | ✅ |
423+
| [Delete Dynamic Person Group](/rest/api/face/person-directory-operations/delete-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | ✅ |
424+
| [Get Dynamic Person Group Persons](/rest/api/face/person-directory-operations/get-dynamic-person-group-persons) | /dynamicpersongroups/{dynamicPersonGroupId}/persons | |
425+
| [Get Dynamic Person Group References](/rest/api/face/person-directory-operations/get-dynamic-person-group-references) | /persons/{personId}/dynamicPersonGroupReferences | |
426+
427+
The following code illustrates the dependencies of these asynchronous operations:
428+
429+
```csharp
430+
var createPersonResponse = await CreatePersonAsync();
431+
var personId = createPersonResponse.PersonId;
432+
433+
// faces can be added once the person creation HTTP call returns, even if it's still processing
434+
var addPersonFaceResponse = await AddPersonFaceAsync(personId);
435+
var addPersonFaceFromUrlResponse = await AddPersonFaceFromUrlAsync(personId);
436+
437+
switch (scenario)
438+
{
439+
case Scenario.Verify:
440+
// only need to ensure the addition of face data has propagated
441+
await WaitForLongRunningOperationsAsync(new[]
442+
{
443+
addPersonFaceResponse.OperationLocation,
444+
addPersonFaceFromUrlResponse.OperationLocation
445+
});
446+
await VerifyFromPersonDirectoryAsync(queryFaceId, personId);
447+
break;
448+
449+
case Scenario.IdentifyInPersonDirectory:
450+
// ensure person creation and face data enrollment finish successfully
451+
await WaitForLongRunningOperationsAsync(new[]
452+
{
453+
createPersonResponse.OperationLocation,
454+
addPersonFaceResponse.OperationLocation,
455+
addPersonFaceFromUrlResponse.OperationLocation
456+
});
457+
await IdentifyFromPersonDirectoryAsync(queryFaceId);
458+
break;
459+
460+
case Scenario.IdentifyAgainstDynamicPersonGroup:
461+
// person creation needs to be completed before it can be added to a group
462+
await WaitForLongRunningOperationsAsync(new[]
463+
{
464+
createPersonResponse.OperationLocation
465+
});
466+
var groupResponse = await CreateOrUpdateDynamicPersonGroupWithPersonChangesAsync(groupId, [personId]);
467+
// and make sure face data are ready before identification
468+
await WaitForLongRunningOperationsAsync(new[]
469+
{
470+
addPersonFaceResponse.OperationLocation,
471+
addPersonFaceFromUrlResponse.OperationLocation
472+
});
473+
await IdentifyFromDynamicPersonGroupAsync(queryFaceId, groupId);
474+
// optionally check the person-to-group relationship, which requires the completion of the group's creation or updating call
475+
await WaitForLongRunningOperationsAsync(new[]
476+
{
477+
groupResponse.OperationLocation
478+
});
479+
var groupIds = await GetDynamicPersonGroupReferencesAsync(personId);
480+
break;
481+
482+
default:
483+
break;
484+
}
485+
```
486+
487+
397488
## Next steps
398489

399490
In this guide, you learned how to use the **PersonDirectory** structure to store face and person data for your Face app. Next, learn the best practices for adding your users' face data.

‎articles/ai-services/computer-vision/identity-quotas-limits.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ This article contains a reference and a detailed description of the quotas and l
2626
| **Pricing tier** | **Limit value** |
2727
| --- | --- |
2828
| Free (F0) | 20 transactions per minute |
29-
| Standard (S0),</br>Enterprise (E0) | 10 transactions per second, and 200 TPS across all resources in a single region.</br>See the next section if you want to increase this limit. |
29+
| Standard (S0), </br>Enterprise (E0) | 10 transactions per second, and 200 TPS across all resources in a single region. </br>See the next section if you want to increase this limit. |
3030

3131
> [!NOTE]
3232
> If you exceed the default rate limit, you'll receive a `429` error. To address this issue, refer to the [Performance guide](/azure/ai-services/computer-vision/how-to/mitigate-latency#handle-errors-effectively).
@@ -42,9 +42,9 @@ This article contains a reference and a detailed description of the quotas and l
4242

4343
### How to request an increase to the default limits
4444

45-
To increase rate limits and resource limits, you can submit a support request. However, for other quota limits, you need to switch to a higher pricing tier to increase those quotas.
45+
To increase rate limits and resource limits for paid subscription, you can submit a support request.
4646

47-
[Submit a support request](/azure/ai-services/cognitive-services-support-options?context=%2Fazure%2Fai-services%2Fopenai%2Fcontext%2Fcontext) and provide the following information:
47+
[Submit a support request](https://azure.microsoft.com/support/create-ticket/) and provide the following information:
4848
- A description of your Face use case.
4949
- The reason for requesting an increase in your current limits.
5050
- Which of your subscriptions or resources are affected?
@@ -69,40 +69,40 @@ We evaluate TPS increase requests on a case-by-case basis, and our decision is b
6969

7070
| **Pricing tier** | **Limit value** |
7171
| --- | --- |
72-
| Free (F0) |<ul><li>1 PersonDirectory</li><li>1,000 persons</li><li>Each holds up to 248 faces.</li><li>Unlimited DynamicPersonGroups</li></ul>|
73-
| Standard (S0),</br>Enterprise (E0) | <ul><li>1 PersonDirectory</li><li>75,000,000 persons<ul><li>Contact support if you want to increase this limit.</li></ul></li><li>Each holds up to 248 faces.</li><li>Unlimited DynamicPersonGroups</li></ul> |
72+
| Free (F0) |<ul><li>1 PersonDirectory</li><li>1,000 persons</li><li>Each holds up to 248 faces.</li><li>1,000,000 DynamicPersonGroups</li></ul>|
73+
| Standard (S0), </br>Enterprise (E0) | <ul><li>1 PersonDirectory</li><li>20,000,000 persons<ul><li>Contact support if you want to increase this limit.</li></ul></li><li>Each holds up to 248 faces.</li><li>1,000,000 DynamicPersonGroups</li></ul> |
7474

7575

7676
**Quota of FaceList**
7777

7878
| **Pricing tier** | **Limit value** |
7979
| --- | --- |
80-
| Free (F0),</br>Standard (S0),</br>Enterprise (E0) |<ul><li>64 FaceLists.</li><li>Each holds up to 1,000 faces.</li></ul>|
80+
| Free (F0), </br>Standard (S0), </br>Enterprise (E0) |<ul><li>64 FaceLists.</li><li>Each holds up to 1,000 faces.</li></ul>|
8181

8282
**Quota of LargeFaceList**
8383

8484
| **Pricing tier** | **Limit value** |
8585
| --- | --- |
8686
| Free (F0) | <ul><li>64 LargeFaceLists.</li><li>Each holds up to 1,000 faces.</li></ul>|
87-
| Standard (S0),</br>Enterprise (E0) | <ul><li>1,000,000 LargeFaceLists.</li><li>Each holds up to 1,000,000 faces.</li></ul> |
87+
| Standard (S0), </br>Enterprise (E0) | <ul><li>1,000,000 LargeFaceLists.</li><li>Each holds up to 1,000,000 faces.</li></ul> |
8888

8989
**Quota of PersonGroup**
9090

9191
| **Pricing tier** | **Limit value** |
9292
| --- | --- |
9393
| Free (F0) |<ul><li>1,000 PersonGroups. </li><li>Each holds up to 1,000 Persons.</li><li>Each Person can hold up to 248 faces.</li></ul>|
94-
| Standard (S0),</br>Enterprise (E0) |<ul><li>1,000,000 PersonGroups.</li> <li>Each holds up to 10,000 Persons.</li><li>Each Person can hold up to 248 faces.</li></ul>|
94+
| Standard (S0), </br>Enterprise (E0) |<ul><li>1,000,000 PersonGroups.</li> <li>Each holds up to 10,000 Persons.</li><li>Each Person can hold up to 248 faces.</li></ul>|
9595

9696
**Quota of LargePersonGroup**
9797

9898
| **Pricing tier** | **Limit value** |
9999
| --- | --- |
100100
| Free (F0) | <ul><li>1,000 LargePersonGroups</li><li> Each holds up to 1,000 Persons.</li><li>Each Person can hold up to 248 faces.</li></ul> |
101-
| Standard (S0),</br>Enterprise (E0) | <ul><li>1,000,000 LargePersonGroups</li><li> Each holds up to 1,000,000 Persons.</li><li>Each Person can hold up to 248 faces.</li><li>The total Persons in all LargePersonGroups shouldn't exceed 1,000,000,000.</li></ul> |
101+
| Standard (S0), </br>Enterprise (E0) | <ul><li>1,000,000 LargePersonGroups</li><li> Each holds up to 1,000,000 Persons.</li><li>Each Person can hold up to 248 faces.</li><li>The total Persons in all LargePersonGroups shouldn't exceed 1,000,000,000.</li></ul> |
102102

103103
**[Customer-managed keys (CMK)](/azure/ai-services/computer-vision/identity-encrypt-data-at-rest)**
104104

105105
| **Pricing tier** | **Limit value** |
106106
| --- | --- |
107-
| Free (F0),</br>Standard (S0) | Not supported |
107+
| Free (F0), </br>Standard (S0) | Not supported |
108108
| Enterprise (E0) | Supported |

0 commit comments

Comments
 (0)