Dela via

Internt dokumentstöd för Azure AI Language (förhandsversion)

  • Artikel

Viktigt!

  • Offentliga förhandsversioner av Azure AI Language ger tidig åtkomst till funktioner som är i aktiv utveckling.
  • Funktioner, metoder och processer kan ändras, före allmän tillgänglighet (GA), baserat på användarfeedback.

Azure AI Language är en molnbaserad tjänst som tillämpar NLP-funktioner (Natural Language Processing) på textbaserade data. Med den inbyggda dokumentsupportfunktionen kan du skicka API-begäranden asynkront med hjälp av en HTTP POST-begärandetext för att skicka dina data och HTTP GET-frågesträngen för att hämta statusresultatet. Dina bearbetade dokument finns i din Azure Blob Storage-målcontainer.

Ett internt dokument refererar till det filformat som används för att skapa det ursprungliga dokumentet, till exempel Microsoft Word (docx) eller en bärbar dokumentfil (pdf). Stöd för inbyggt dokument eliminerar behovet av förbearbetning av text innan du använder Resursfunktioner för Azure AI Language. För närvarande är inbyggt dokumentstöd tillgängligt för följande funktioner:

  • Personligt identifierbar information (PII). PII-identifieringsfunktionen kan identifiera, kategorisera och redigera känslig information i ostrukturerad text. API:et PiiEntityRecognition stöder intern dokumentbearbetning.

  • Dokumentsammanfattning. Dokumentsammanfattningar använder bearbetning av naturligt språk för att generera extrahering (extrahering av viktig mening) eller abstrakta sammanfattningar (kontextuell ordextrahering) för dokument. Både AbstractiveSummarization API:er och ExtractiveSummarization har stöd för intern dokumentbearbetning.

Dokumentformat som stöds

Program använder inbyggda filformat för att skapa, spara eller öppna interna dokument. Funktionerna för PII- och dokumentsammanfattning stöder för närvarande följande interna dokumentformat:

Filtyp Filnamnstillägg Beskrivning
Text .txt Ett oformaterat textdokument.
Adobe PDF .pdf Ett portabelt dokumentfilformaterat dokument.
Microsoft Word .docx En Microsoft Word-dokumentfil.

Riktlinjer för indata

Filformat som stöds

Typ support och begränsningar
PDF-filer Fullständigt skannade PDF-filer stöds inte.
Text i bilder Digitala bilder med inbäddad text stöds inte.
Digitala tabeller Tabeller i skannade dokument stöds inte.

Dokumentstorlek

Attribut Indatagräns
Totalt antal dokument per begäran ≤ 20
Total innehållsstorlek per begäran ≤ 10 MB

Inkludera interna dokument med en HTTP-begäran

Nu ska vi komma igång:

  • För det här projektet använder vi kommandoradsverktyget cURL för att göra REST API-anrop.

    Kommentar

    cURL-paketet är förinstallerat på de flesta Windows 10- och Windows 11- och de flesta macOS- och Linux-distributioner. Du kan kontrollera paketversionen med följande kommandon: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Om cURL inte är installerat finns här installationslänkar för din plattform:

  • Ett aktivt Azure-konto. Om du inte har någon, kan du skapa ett kostnadsfritt konto.

  • Ett Azure Blob Storage-konto. Du måste också skapa containrar i ditt Azure Blob Storage-konto för dina käll- och målfiler:

    • Källcontainer. I den här containern laddar du upp dina interna filer för analys (krävs).
    • Målcontainer. I den här containern lagras dina analyserade filer (krävs).

  • En språkresurs med en enda tjänst (inte en Azure AI-tjänstresurs med flera tjänster):

    Fyll i fälten Språkresursprojekt och instansinformation på följande sätt:

    1. Prenumeration. Välj en av dina tillgängliga Azure-prenumerationer.

    2. Resursgrupp. Du kan skapa en ny resursgrupp eller lägga till resursen i en befintlig resursgrupp som delar samma livscykel, behörigheter och principer.

    3. Resursregion. Välj Global om inte ditt företag eller program kräver en viss region. Om du planerar att använda en systemtilldelad hanterad identitet (RBAC) för autentisering väljer du en geografisk region som USA, västra.

    4. Namn. Ange det namn som du valde för resursen. Namnet du väljer måste vara unikt i Azure.

    5. Prisnivå. Du kan använda den kostnadsfria prisnivån (Free F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.

    6. Välj Granska + skapa.

    7. Granska tjänstvillkoren och välj Skapa för att distribuera resursen.

    8. När resursen har distribuerats väljer du Gå till resurs.

Hämta din nyckel- och språktjänstslutpunkt

Begäranden till språktjänsten kräver en skrivskyddad nyckel och en anpassad slutpunkt för att autentisera åtkomsten.

  1. Om du har skapat en ny resurs väljer du Gå till resurs när den har distribuerats. Om du har en befintlig språktjänstresurs går du direkt till resurssidan.

  2. Välj Nycklar och slutpunkt under Resurshantering i det vänstra spåret.

  3. Du kan kopiera och klistra in din key och din language service instance endpoint i kodexemplen för att autentisera din begäran till språktjänsten. Endast en nyckel krävs för att göra ett API-anrop.

Skapa Azure Blob Storage-containrar

Skapa containrar i ditt Azure Blob Storage-konto för käll- och målfiler.

  • Källcontainer. I den här containern laddar du upp dina interna filer för analys (krävs).
  • Målcontainer. I den här containern lagras dina analyserade filer (krävs).

Autentisering

Språkresursen måste beviljas åtkomst till ditt lagringskonto innan den kan skapa, läsa eller ta bort blobar. Det finns två primära metoder som du kan använda för att bevilja åtkomst till dina lagringsdata:

  • SAS-token (Signatur för delad åtkomst). SAS-token för användardelegering skyddas med Microsoft Entra-autentiseringsuppgifter. SAS-token ger säker, delegerad åtkomst till resurser i ditt Azure Storage-konto.

  • Rollbaserad åtkomstkontroll för hanterad identitet (RBAC). Hanterade identiteter för Azure-resurser är tjänstens huvudnamn som skapar en Microsoft Entra-identitet och specifika behörigheter för Azure-hanterade resurser.

För det här projektet autentiserar vi åtkomst till source location target location och URL:er med SAS-token (Signatur för delad åtkomst) som läggs till som frågesträngar. Varje token tilldelas till en specifik blob (fil).

Skärmbild av en lagrings-URL med SAS-token bifogad.

  • Källcontainern eller bloben måste ange läs- och liståtkomst.
  • Målcontainern eller bloben måste ange skriv- och liståtkomst.

Dricks

Eftersom vi bearbetar en enda fil (blob) rekommenderar vi att du delegerar SAS-åtkomst på blobnivå.

Begärandehuvuden och parametrar

parameter Description
-X POST <endpoint> Anger din språkresursslutpunkt för åtkomst till API:et.
--header Content-Type: application/json Innehållstypen för att skicka JSON-data.
--header "Ocp-Apim-Subscription-Key:<key> Anger språkresursnyckeln för åtkomst till API:et.
-data JSON-filen som innehåller de data som du vill skicka med din begäran.

Följande cURL-kommandon körs från ett BASH-gränssnitt. Redigera dessa kommandon med ditt eget resursnamn, resursnyckel och JSON-värden. Prova att analysera interna dokument genom att Personally Identifiable Information (PII) välja exempelprojektet eller Document Summarization :

PII-exempeldokument

För den här snabbstarten behöver du ett källdokument som laddats upp till källcontainern. Du kan ladda ned vårt Microsoft Word-exempeldokument eller Adobe PDF för det här projektet. Källspråket är engelska.

Skapa POST-begäran

  1. Använd din föredragna redigerare eller IDE och skapa en ny katalog för din app med namnet native-document.

  2. Skapa en ny json-fil med namnet pii-detection.json i din interna dokumentkatalog.

  3. Kopiera och klistra in följande PII-begärandeexempel (Personligt identifierbar information) i filenpii-detection.json. Ersätt {your-source-container-SAS-URL} och {your-target-container-SAS-URL} med värden från din Azure Portal Storage-kontocontainerinstans:

Exempel på begäran

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

  • location Källvärdet är SAS-URL:en för källdokumentet (blob) och inte SAS-URL:en för källcontainern.

  • Möjliga redactionPolicy värden är UseRedactionCharacterWithRefId (standard) eller UseEntityTypeName. Mer information finns i PiiTask-parametrar.

Kör POST-begäran

  1. Här är den preliminära strukturen för POST-begäran:

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

  2. Innan du kör POST-begäran ersätter {your-language-resource-endpoint} du och {your-key} med värdena från din Azure Portal Language-tjänstinstans.

    Viktigt!

    Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i Säkerhet för Azure AI-tjänster.

    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"

    kommandotolk/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. Här är ett exempelsvar:

    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-svar (jobId)

Du får ett svar från 202 (Lyckades) som innehåller en skrivskyddad rubrik för åtgärdsplats. Värdet för det här huvudet innehåller ett jobId som kan efterfrågas för att hämta status för den asynkrona åtgärden och hämta resultaten med hjälp av en GET-begäran :

Skärmbild som visar värdet operation-location i POST-svaret.

Hämta analysresultat (GET-begäran)

  1. Efter din lyckade POST-begäran avsöker du rubriken operation-location som returneras i POST-begäran för att visa bearbetade data.

  2. Här är den preliminära strukturen för GET-begäran :

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

  3. Innan du kör kommandot gör du följande ändringar:

    • Ersätt {jobId} med rubriken Operation-Location från POST-svaret.

    • Ersätt {your-language-resource-endpoint} och {your-key} med värdena från language service-instansen i Azure Portal.

Hämta begäran

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

Granska svaret

Du får ett svar på 200 (lyckades) med JSON-utdata. Statusfältet anger resultatet av åtgärden. Om åtgärden inte är slutförd är värdet för statusen "körs" eller "notStarted" och du bör anropa API:et igen, antingen manuellt eller via ett skript. Vi rekommenderar ett intervall på en sekund eller mer mellan anrop.

Exempelsvar

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

När det har slutförts:

  • De analyserade dokumenten finns i målcontainern.
  • Post-metoden returnerar en 202 Accepted svarskod som anger att tjänsten skapade batchbegäran.
  • POST-begäran returnerade även svarshuvuden, inklusive Operation-Location som ger ett värde som används i efterföljande GET-begäranden.

Rensa resurser

Om du vill rensa och ta bort en Azure AI-tjänstprenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort.

Nästa steg

Översikt över PII-identifiering – översikt över dokumentsammanfattning