Delen via

Een aangepaste analyse maken met REST API's

Inhoudsinzichtanalyses definiëren hoe u inzichten uit uw inhoud kunt verwerken en extraheren. Ze zorgen voor uniforme verwerkings- en uitvoerstructuur voor al uw inhoud om betrouwbare en voorspelbare resultaten te leveren. We bieden vooraf samengestelde analyses voor veelvoorkomende gebruiksvoorbeelden . Deze handleiding laat zien hoe deze analyses kunnen worden aangepast om beter aan uw behoeften te voldoen.

In deze handleiding gebruiken we het opdrachtregelprogramma cURL. Als deze niet is geïnstalleerd, kunt u de juiste versie voor uw ontwikkelomgeving downloaden.

Vereiste voorwaarden

Zorg ervoor dat u de volgende resources en machtigingen hebt om aan de slag te gaan:

  • Een Azure-abonnement. Als u geen Azure-abonnement hebt, maakt u een gratis account.
  • Zodra u uw Azure-abonnement hebt, maakt u een Microsoft Foundry-resource in Azure Portal. Zorg ervoor dat u deze maakt in een ondersteunde regio.
    • Deze resource wordt vermeld onder Foundry>Foundry in de portal.
  • Stel standaardmodelimplementaties in voor uw Content Understanding-resource. Als u de standaardinstellingen instelt, wordt er een verbinding gemaakt met de Foundry-modellen die u gebruikt voor Aanvragen voor Content Understanding. Kies één van de volgende methoden:
    1. Ga naar de pagina Inhoudsbegrip-instellingen
    2. Selecteer de knop + Resource toevoegen in de linkerbovenhoek
    3. Selecteer de Foundry-resource die u wilt gebruiken en klik op Volgende en klik vervolgens op Opslaan
      • Zorg ervoor dat u 'Automatisch implementeren voor vereiste modellen inschakelen als er geen standaardinstellingen beschikbaar zijn' ingeschakeld. Dit zorgt ervoor dat uw resource volledig is ingesteld met de vereiste modellen: GPT-4.1, GPT-4.1-mini en tekst-embedding-3-groot. Voor verschillende vooraf samengestelde analyses zijn verschillende modellen vereist.
    Door deze stappen uit te voeren, stelt u een verbinding in tussen Content Understanding- en Foundry-modellen in uw Foundry-resource.

Een analyseschema definiëren

Als u een aangepaste analyse wilt maken, definieert u een veldschema waarin de gestructureerde gegevens worden beschreven die u wilt extraheren. In het volgende voorbeeld maken we een analyse op basis van vooraf samengestelde documentanalyse voor het verwerken van een ontvangstbewijs.

Maak een JSON-bestand met de naam receipt.json met de volgende inhoud:

{
  "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"
            }
          }
        }
      }
    }
  }
}

Als u verschillende typen documenten hebt die u moet verwerken, maar alleen de ontvangstbewijzen wilt categoriseren en analyseren, kunt u eerst een analyse maken waarmee het document wordt gecategoraliseerd. Routeer deze vervolgens naar de analyse die u hierboven hebt gemaakt met het volgende schema.

Maak een JSON-bestand met de naam categorize.json met de volgende inhoud:

{
  "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.

}

Een analyse maken

PUT-aanvraag

Maak eerst een ontvangstanalyse en maak vervolgens de categoriseeranalyse.

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

PUT-antwoord

Het 201-antwoord Created bevat een Operation-Location header met een URL die u kunt gebruiken om de status van deze asynchrone analysebewerking bij te houden.

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

Na voltooiing retourneert "status": "succeeded"een HTTP GET op de locatie-URL van de bewerking.

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

Een bestand analyseren

Het bestand verzenden

U kunt nu de aangepaste analyse gebruiken die u hebt gemaakt om bestanden te verwerken en de velden te extraheren die u in het schema hebt gedefinieerd.

Voordat u de cURL-opdracht uitvoert, moet u de volgende wijzigingen aanbrengen in de HTTP-aanvraag:

  1. Vervang {endpoint} en {key} met de eindpunt- en sleutelwaarden van uw Azure portal Foundry-exemplaar.
  2. Vervang {analyzerId} door de naam van de aangepaste analyse die u hebt gemaakt met het categorize.json bestand.
  3. Vervang {fileUrl} door een openbaar toegankelijke URL van het bestand dat u wilt analyseren, zoals een pad naar een Azure Storage-blob met een SAS (Shared Access Signature) of de voorbeeld-URL https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

POST-aanvraag

In dit voorbeeld wordt de aangepaste analyse gebruikt die u met het categorize.json bestand hebt gemaakt om een ontvangstbewijs te analyseren.

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"
          }          
        ]
      }'

POST-antwoord

Het 202 Accepted antwoord bevat het {resultId} antwoord dat u kunt gebruiken om de status van deze asynchrone bewerking bij te houden.

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

Resultaat analyseren ophalen

Gebruik het Operation-Location antwoord POST en haal het resultaat van de analyse op.

GET-aanvraag

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

GET-antwoord

Een 200 OK antwoord bevat een status veld waarin de voortgang van de bewerking wordt weergegeven.

  • status is Succeeded als de bewerking succesvol is voltooid.
  • Als het running of notStarted is, roept u de API handmatig of met een script aan: wacht minstens één seconde tussen verzoeken.
Voorbeeldantwoord
{
  "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
    }
  }
}

Verwante inhoud

  • Codevoorbeelden bekijken: zoeken in visuele documenten.
  • Codevoorbeeld bekijken: analysesjablonen.
  • Probeer uw documentinhoud te verwerken met Content Understanding in Foundry.
  • Last updated on