Partager via

Créer un analyseur personnalisé à l’aide d’API REST

Les analyseurs Content Understanding définissent comment traiter et extraire des insights de votre contenu. Ils garantissent une structure uniforme de traitement et de sortie dans tout votre contenu pour fournir des résultats fiables et prévisibles. Nous offrons des analyseurs prédéfinis pour les cas d’usage courants. Ce guide montre comment ces analyseurs peuvent être personnalisés pour mieux répondre à vos besoins.

Dans ce guide, nous utilisons l’outil en ligne de commande cURL. S’il n’est pas installé, vous pouvez télécharger la version appropriée pour votre environnement de développement.

Prerequisites

Pour commencer, assurez-vous de disposer des ressources et des autorisations suivantes :

  • Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit.
  • Une fois que vous avez votre abonnement Azure, créez une ressource Microsoft Foundry dans le Portail Azure. Veillez à le créer dans une région prise en charge.
    • Cette ressource est listée sous Foundry>Foundry dans le portail.
  • Configurez les déploiements de modèles par défaut pour votre ressource Content Understanding. La définition par défaut crée une connexion aux modèles Foundry que vous utilisez pour les requêtes Content Understanding. Choisissez l’une des méthodes suivantes :
    1. Accédez à la page des paramètres Content Understanding
    2. Sélectionnez le bouton « + Ajouter une ressource » en haut à gauche
    3. Sélectionnez la ressource Foundry que vous souhaitez utiliser, puis cliquez sur Suivant, puis Enregistrez
      • Veillez à laisser « Activer le redéploiement automatique pour les modèles requis si aucune valeur par défaut n’est disponible ». Cela garantit que votre ressource est entièrement configurée avec les modèles GPT-4.1, GPT-4.1-mini et text-embedding-3-large requis. Différents analyseurs prédéfinis nécessitent différents modèles.
    En effectuant ces étapes, vous configurez une connexion entre les modèles Content Understanding et Foundry dans votre ressource Foundry.

Définir un schéma d’analyseur

Pour créer un analyseur personnalisé, définissez un schéma de champ qui décrit les données structurées que vous souhaitez extraire. Dans l’exemple suivant, nous créons un analyseur basé sur l’analyseur de documents prédéfini pour le traitement d’un reçu.

Créez un fichier JSON nommé receipt.json avec le contenu suivant :

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    "returnDetails": true,
    "enableFormula": false,
    "disableContentFiltering": false,
    "estimateFieldSourceAndConfidence": true,
    "tableFormat": "html"
  },
 "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the receipt"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Si vous avez différents types de documents que vous devez traiter, mais que vous souhaitez catégoriser et analyser uniquement les reçus, vous pouvez créer un analyseur qui catégorise le document en premier. Ensuite, routez-le vers l’analyseur que vous avez créé ci-dessus avec le schéma suivant.

Créez un fichier JSON nommé categorize.json avec le contenu suivant :

{
  "baseAnalyzerId": "prebuilt-document",
  // Use the base analyzer to invoke the document specific capabilities.

  //Specify the model the analyzer should use. This is one of the supported completion models and one of the supported embeddings model. The specific deployment used during analyze is set on the resource or provided in the analyze request.
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    // Enable splitting of the input into segments. Set this property to false if you only expect a single document within the input file. When specified and enableSegment=false, the whole content will be classified into one of the categories.
    "enableSegment": false,

    "contentCategories": {
      // Category name.
      "receipt": {
        // Description to help with classification and splitting.
        "description": "Any images or documents of receipts",

        // Define the analyzer that any content classified as a receipt should be routed to
        "analyzerId": "receipt"
      },

      "invoice": {
        "description": "Any images or documents of invoice",
        "analyzerId": "prebuilt-invoice"
      },
      "policeReport": {
        "description": "A police or law enforcement report detailing the events that lead to the loss."
        // Don't perform analysis for this category.
      }

    },

    // Omit original content object and only return content objects from additional analysis.
    "omitContent": true
  }

  //You can use fieldSchema here to define fields that are needed from the entire input content.

}

Créer un analyseur

Requête d’PUT

Créez d’abord un analyseur de reçu, puis créez l’analyseur de catégorie.

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @receipt.json

Réponse PUT

La réponse 201 Created inclut un Operation-Location en-tête contenant une URL que vous pouvez utiliser pour suivre l’état de cette opération de création d’analyseur asynchrone.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2025-05-01-preview

Une fois l’opération terminée, l’exécution d’une requête HTTP GET sur l’URL de l’emplacement de l’opération retourne "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Analyser un fichier

Envoyer le fichier

Vous pouvez maintenant utiliser l’analyseur personnalisé que vous avez créé pour traiter les fichiers et extraire les champs que vous avez définis dans le schéma.

Avant d’exécuter la commande cURL, apportez les modifications suivantes à la requête HTTP :

  1. Remplacez {endpoint} et {key} par les valeurs de point de terminaison et de clé de votre instance Foundry du portail Azure.
  2. Remplacez {analyzerId} par le nom de l’analyseur personnalisé que vous avez créé par le categorize.json fichier.
  3. Remplacez {fileUrl} par une URL accessible publiquement du fichier pour analyser, par exemple un chemin d’accès à un Azure Storage Blob avec une signature d’accès partagé (SAP) ou l’exemple d’URL https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

Requête POST

Cet exemple utilise l’analyseur personnalisé que vous avez créé avec le categorize.json fichier pour analyser un reçu.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs":[
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png"
          }          
        ]
      }'

Réponse POST

La 202 Accepted réponse inclut celle {resultId} que vous pouvez utiliser pour suivre l’état de cette opération asynchrone.

{
  "id": {resultId},
  "status": "Running",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": []
  }
}

Obtenir le résultat d’analyse

Utilisez la Operation-Location de la réponse POST, et récupérez le résultat de l’analyse.

Requête GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Réponse GET

Une 200 OK réponse inclut un status champ qui indique la progression de l’opération.

  • status est Succeeded si l’opération est terminée avec succès.
  • S’il s’agit running ou notStarted, appelez à nouveau l’API manuellement ou avec un script : attendez au moins une seconde entre les requêtes.
Exemple de réponse
{
  "id": {resultId},
  "status": "Succeeded",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "path": "input1/segment1",
        "category": "receipt",
        "markdown": "Contoso\n\n123 Main Street\nRedmond, WA 98052\n\n987-654-3210\n\n6/10/2019 13:59\nSales Associate: Paul\n\n\n<table>\n<tr>\n<td>2 Surface Pro 6</td>\n<td>$1,998.00</td>\n</tr>\n<tr>\n<td>3 Surface Pen</td>\n<td>$299.97</td>\n</tr>\n</table> ...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "Contoso",
            "spans": [{"offset": 0,"length": 7}],
            "confidence": 0.996,
            "source": "D(1,774.0000,72.0000,974.0000,70.0000,974.0000,111.0000,774.0000,113.0000)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "2 Surface Pro 6",
                    "spans": [ { "offset": 115, "length": 15}],
                    "confidence": 0.423,
                    "source": "D(1,704.0000,482.0000,875.0000,482.0000,875.0000,508.0000,704.0000,508.0000)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 1998,
                    "spans": [{ "offset": 140,"length": 9}
                    ],
                    "confidence": 0.957,
                    "source": "D(1,952.0000,482.0000,1048.0000,482.0000,1048.0000,508.0000,952.0000,509.0000)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0944,
            "width": 1743,
            "height": 878
          }
        ],
        "analyzerId": "{analyzerId}",
        "mimeType": "image/png"
      }
    ]
  },
  "usage": {
    "documentPages": 1,
    "tokens": {
      "contextualization": 1000
    }
  }
}

Contenu connexe

  • Last updated on