Delen via

Systeemeigen documentondersteuning voor Azure AI Language (preview)

  • Artikel

Belangrijk

  • Openbare preview-versies van Azure AI Language bieden vroege toegang tot functies die actief zijn in ontwikkeling.
  • Functies, benaderingen en processen kunnen veranderen, vóór algemene beschikbaarheid (GA), op basis van feedback van gebruikers.

Azure AI Language is een cloudservice die NLP-functies (Natural Language Processing) toepast op gegevens op basis van tekst. Met de systeemeigen mogelijkheid voor documentondersteuning kunt u API-aanvragen asynchroon verzenden met behulp van een HTTP POST-aanvraagbody om uw gegevens en queryreeks voor HTTP GET-aanvragen te verzenden om de statusresultaten op te halen. Uw verwerkte documenten bevinden zich in de doelcontainer van Azure Blob Storage.

Een systeemeigen document verwijst naar de bestandsindeling die wordt gebruikt om het oorspronkelijke document te maken, zoals Microsoft Word (docx) of een draagbaar documentbestand (PDF). Systeemeigen documentondersteuning elimineert de noodzaak van tekstvoorverwerking voordat u de resourcemogelijkheden van Azure AI Language gebruikt. Momenteel is systeemeigen documentondersteuning beschikbaar voor de volgende mogelijkheden:

  • Persoonlijk identificeerbare informatie (PII). De functie PII-detectie kan gevoelige informatie identificeren, categoriseren en redacteren in ongestructureerde tekst. De PiiEntityRecognition API ondersteunt systeemeigen documentverwerking.

  • Samenvatting van documenten. Documentsamenvatting maakt gebruik van natuurlijke taalverwerking voor het genereren van extraherende (opvallende zinextractie) of abstractieve samenvattingen (contextuele woordextractie) voor documenten. ExtractiveSummarization Zowel AbstractiveSummarization als API's ondersteunen systeemeigen documentverwerking.

Ondersteunde documentindelingen

Toepassingen gebruiken systeemeigen bestandsindelingen om systeemeigen documenten te maken, op te slaan of te openen. Momenteel bieden PII - en documentsamenvattingsmogelijkheden ondersteuning voor de volgende systeemeigen documentindelingen:

Bestandstype Bestandsextensie Beschrijving
Tekst .txt Een niet-opgemaakt tekstdocument.
Adobe PDF .pdf Een document met een draagbare documentindeling.
Microsoft Word .docx Een Microsoft Word-documentbestand.

Invoerrichtlijnen

Ondersteunde bestandsindelingen

Type ondersteuning en beperkingen
PDF-bestanden Volledig gescande PDF-bestanden worden niet ondersteund.
Tekst in afbeeldingen Digitale afbeeldingen met ingesloten tekst worden niet ondersteund.
Digitale tabellen Tabellen in gescande documenten worden niet ondersteund.

Documentgrootte

Kenmerk Invoerlimiet
Totaal aantal documenten per aanvraag ≤ 20
Totale inhoudsgrootte per aanvraag ≤ 10 MB

Systeemeigen documenten opnemen met een HTTP-aanvraag

Laten we aan de slag gaan:

  • Voor dit project gebruiken we het opdrachtregelprogramma cURL om REST API-aanroepen uit te voeren.

    Notitie

    Het cURL-pakket is vooraf geïnstalleerd op de meeste Windows 10- en Windows 11- en de meeste macOS- en Linux-distributies. U kunt de pakketversie controleren met de volgende opdrachten: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Als cURL niet is geïnstalleerd, vindt u hier installatiekoppelingen voor uw platform:

  • Een actief Azure-account. Als u nog geen account hebt, kunt u een gratis account aanmaken.

  • Een Azure Blob Storage-account. U moet ook containers maken in uw Azure Blob Storage-account voor uw bron- en doelbestanden:

    • Broncontainer. In deze container uploadt u uw systeemeigen bestanden voor analyse (vereist).
    • Doelcontainer. In deze container worden uw geanalyseerde bestanden opgeslagen (vereist).

  • Een taalresource met één service (niet een Azure AI-servicesresource met meerdere services):

    Vul de velden Taalresourceproject en instantiegegevens als volgt in:

    1. Abonnement. Selecteer een van uw beschikbare Azure-abonnementen.

    2. Resourcegroep. U kunt een nieuwe resourcegroep maken of uw resource toevoegen aan een bestaande resourcegroep die dezelfde levenscyclus, machtigingen en beleidsregels deelt.

    3. Resourceregio. Kies Globaal , tenzij uw bedrijf of toepassing een specifieke regio vereist. Als u van plan bent om een door het systeem toegewezen beheerde identiteit (RBAC) te gebruiken voor verificatie, kiest u een geografische regio, zoals VS - west.

    4. Name. Voer de naam in die u voor uw resource hebt gekozen. De naam die u kiest, moet uniek zijn binnen Azure.

    5. Prijscategorie. U kunt de gratis prijscategorie (Free F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

    6. Selecteer Controleren + maken.

    7. Controleer de servicevoorwaarden en selecteer Maken om uw resource te implementeren.

    8. Nadat de resource is geïmplementeerd, selecteert u Ga naar de resource.

Uw sleutel- en taalservice-eindpunt ophalen

Aanvragen voor de taalservice vereisen een alleen-lezen sleutel en een aangepast eindpunt om toegang te verifiëren.

  1. Als u een nieuwe resource hebt gemaakt nadat deze is geïmplementeerd, selecteert u Ga naar de resource. Als u een bestaande taalserviceresource hebt, gaat u rechtstreeks naar de resourcepagina.

  2. Selecteer sleutels en eindpunt in de linkerrail onder Resourcebeheer.

  3. U kunt uw key en uw language service instance endpoint codevoorbeelden kopiëren en plakken om uw aanvraag te verifiëren bij de Taalservice. Er is slechts één sleutel nodig om een API-aanroep te maken.

Azure Blob Storage-containers maken

Maak containers in uw Azure Blob Storage-account voor bron- en doelbestanden.

  • Broncontainer. In deze container uploadt u uw systeemeigen bestanden voor analyse (vereist).
  • Doelcontainer. In deze container worden uw geanalyseerde bestanden opgeslagen (vereist).

Verificatie

Aan uw taalresource is toegang tot uw opslagaccount verleend voordat blobs kunnen worden gemaakt, gelezen of verwijderd. Er zijn twee primaire methoden die u kunt gebruiken om toegang te verlenen tot uw opslaggegevens:

  • Sas-tokens (Shared Access Signature). SAS-tokens voor gebruikersdelegering worden beveiligd met Microsoft Entra-referenties. SAS-tokens bieden beveiligde, gedelegeerde toegang tot resources in uw Azure-opslagaccount.

  • Op rollen gebaseerd toegangsbeheer (RBAC) voor beheerde identiteiten. Beheerde identiteiten voor Azure-resources zijn service-principals die een Microsoft Entra-identiteit en specifieke machtigingen voor door Azure beheerde resources maken.

Voor dit project verifiëren we de toegang tot de source location en target location URL's met SAS-tokens (Shared Access Signature) die als querytekenreeksen zijn toegevoegd. Elk token wordt toegewezen aan een specifieke blob (bestand).

Schermopname van een opslag-URL waaraan een SAS-token is toegevoegd.

  • Uw broncontainer of -blob moet lees- en lijsttoegang aanwijzen.
  • Uw doelcontainer of blob moet schrijf- en lijsttoegang aanwijzen.

Tip

Omdat we één bestand (blob) verwerken, raden we u aan SAS-toegang op blobniveau te delegeren.

Aanvraagheaders en -parameters

parameter Description
-X POST <endpoint> Hiermee geeft u het taalresource-eindpunt op voor toegang tot de API.
--header Content-Type: application/json Het inhoudstype voor het verzenden van JSON-gegevens.
--header "Ocp-Apim-Subscription-Key:<key> Hiermee geeft u de taalresourcesleutel op voor toegang tot de API.
-data Het JSON-bestand met de gegevens die u wilt doorgeven aan uw aanvraag.

De volgende cURL-opdrachten worden uitgevoerd vanuit een Bash-shell. Bewerk deze opdrachten met uw eigen resourcenaam, resourcesleutel en JSON-waarden. Probeer systeemeigen documenten te analyseren door het Personally Identifiable Information (PII) voorbeeldproject of Document Summarization het codevoorbeeldproject te selecteren:

PII-voorbeelddocument

Voor deze quickstart hebt u een brondocument nodig dat is geüpload naar uw broncontainer. U kunt ons Microsoft Word-voorbeelddocument of Adobe PDF voor dit project downloaden. De brontaal is Engels.

De POST-aanvraag maken

  1. Maak met behulp van uw favoriete editor of IDE een nieuwe map voor uw app met de naam native-document.

  2. Maak een nieuw json-bestand met de naam pii-detection.json in uw systeemeigen documentmap .

  3. Kopieer en plak het volgende PII-aanvraagvoorbeeld (Personally Identifiable Information) in uw pii-detection.json bestand. Vervang {your-source-container-SAS-URL} en {your-target-container-SAS-URL} door waarden van uw azure Portal Storage-accountcontainerexemplaren:

Voorbeeld van aanvraag

{ 
    "displayName": "Document PII Redaction example", 
    "analysisInput": { 
        "documents": [ 
            { 
                "language": "en-US", 
                "id": "Output-1", 
                "source": { 
                    "location": "{your-source-blob-with-SAS-URL}" 
                }, 
                "target": { 
                    "location": "{your-target-container-with-SAS-URL}" 
                } 
            } 
        ] 
    }, 
    "tasks": [ 
        { 
            "kind": "PiiEntityRecognition", 
            "taskName": "Redact PII Task 1", 
            "parameters": { 
                "redactionPolicy": { 
                    "policyKind": "entityMask"  // Optional. Defines redactionPolicy; changes behavior based on value. Options: noMask, characterMask (default), and entityMask. 
                }, 
                "piiCategories": [ 
                    "Person", 
                    "Organization" 
                ], 
                "excludeExtractionData": false  // Default is false. If true, only the redacted document is stored, without extracted entities data. 
            } 
        } 
    ] 
}

  • De bronwaarde location is de SAS-URL voor het brondocument (blob), niet de SAS-URL van de broncontainer.

  • De redactionPolicy mogelijke waarden zijn UseRedactionCharacterWithRefId (standaard) of UseEntityTypeName. Zie PiiTask Parameters voor meer informatie.

De POST-aanvraag uitvoeren

  1. Dit is de voorlopige structuur van de POST-aanvraag:

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview

  2. Voordat u de POST-aanvraag uitvoert, vervangt en {your-key} vervangt {your-language-resource-endpoint} u deze door de waarden van uw Azure Portal Language Service-exemplaar.

    Belangrijk

    Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie Beveiliging van Azure AI-services voor meer informatie.

    Powershell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    opdrachtprompt/terminal

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. Hier volgt een voorbeeldantwoord:

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2024-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST-antwoord (jobId)

U ontvangt een antwoord van 202 (Geslaagd) dat een alleen-lezen bewerkingslocatieheader bevat. De waarde van deze header bevat een jobId die kan worden opgevraagd om de status van de asynchrone bewerking op te halen en de resultaten op te halen met behulp van een GET-aanvraag :

Schermopname van de waarde van de bewerkingslocatie in het POST-antwoord.

Resultaten analyseren ophalen (GET-aanvraag)

  1. Nadat uw POST-aanvraag is geslaagd, controleert u de header van de bewerkingslocatie die is geretourneerd in de POST-aanvraag om de verwerkte gegevens weer te geven.

  2. Dit is de voorlopige structuur van de GET-aanvraag :

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview

  3. Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:

    • Vervang {jobId} door de header Operation-Location van het POST-antwoord.

    • Vervang {your-language-resource-endpoint} en {your-key} door de waarden van uw Language-service-exemplaar in Azure Portal.

Aanvraag ophalen

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Het antwoord bekijken

U ontvangt een antwoord van 200 (Geslaagd) met JSON-uitvoer. Het statusveld geeft het resultaat van de bewerking aan. Als de bewerking niet is voltooid, is de waarde van de status 'actief' of 'notStarted', en moet u de API opnieuw aanroepen, handmatig of via een script. Een interval van één seconde of meer tussen oproepen wordt aanbevolen.

Voorbeeldrespons

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

Na een geslaagde voltooiing:

  • De geanalyseerde documenten vindt u in uw doelcontainer.
  • De geslaagde POST-methode retourneert een 202 Accepted antwoordcode die aangeeft dat de service de batchaanvraag heeft gemaakt.
  • De POST-aanvraag heeft ook antwoordheaders geretourneerd, waaronder Operation-Location die een waarde biedt die wordt gebruikt in volgende GET-aanvragen.

Resources opschonen

Als u een Azure AI-servicesabonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle bijbehorende resources verwijderd.

Volgende stappen

Overzicht van overzicht van piI-detectie van documentsamenvatting