Sdílet prostřednictvím

Nativní podpora dokumentů pro Azure AI Language (Preview)

  • Článek

Důležité

  • Verze Public Preview jazyka Azure AI poskytují dřívější přístup k funkcím, které jsou aktivní ve vývoji.
  • Funkce, přístupy a procesy se můžou před obecnou dostupností (GA) změnit na základě zpětné vazby uživatelů.

Azure AI Language je cloudová služba, která používá funkce NLP (Natural Language Processing) na textová data. Funkce podpory nativních dokumentů umožňuje asynchronně odesílat požadavky rozhraní API pomocí textu požadavku HTTP POST k odesílání dat a řetězce dotazu požadavku HTTP GET k načtení výsledků stavu. Zpracované dokumenty se nacházejí v cílovém kontejneru služby Azure Blob Storage.

Nativní dokument odkazuje na formát souboru použitý k vytvoření původního dokumentu, jako je Microsoft Word (docx) nebo přenosný soubor dokumentu (pdf). Nativní podpora dokumentů eliminuje potřebu předběžného zpracování textu před použitím funkcí prostředků Azure AI Language. V současné době je k dispozici podpora nativních dokumentů pro následující možnosti:

  • Identifikovatelné osobní údaje (PII) Funkce detekce PII dokáže identifikovat, kategorizovat a redactovat citlivé informace v nestrukturovaném textu. Rozhraní PiiEntityRecognition API podporuje nativní zpracování dokumentů.

  • Shrnutí dokumentu Sumarizace dokumentů používá zpracování přirozeného jazyka ke generování extrahovaných (výslovných vět) nebo abstrakčních souhrnů (extrakce kontextových slov) pro dokumenty. Rozhraní AbstractiveSummarization API podporují ExtractiveSummarization nativní zpracování dokumentů.

Podporované formáty dokumentů

Aplikace používají nativní formáty souborů k vytváření, ukládání nebo otevírání nativních dokumentů. Funkce souhrnů osobních údajů a dokumentů v současné době podporují následující nativní formáty dokumentů:

Typ souboru Přípona souboru Popis
Text .txt Neformátovaný textový dokument
Adobe PDF .pdf Přenosný dokument naformátovaný souborem dokumentu
Microsoft Word .docx Soubor dokumentu aplikace Microsoft Word.

Pokyny pro zadávání

Podporované formáty souborů

Typ podpora a omezení
Soubory PDF Plně naskenované soubory PDF nejsou podporované.
Text v obrázcích Digitální obrázky s vloženým textem se nepodporují.
Digitální tabulky Tabulky v naskenovaných dokumentech nejsou podporované.

Velikost dokumentu

Atribut Vstupní limit
Celkový počet dokumentů na žádost ≤ 20
Celková velikost obsahu na požadavek ≤ 10 MB

Zahrnutí nativních dokumentů s požadavkem HTTP

Pojďme začít:

  • Pro tento projekt používáme nástroj příkazového řádku cURL k volání rozhraní REST API.

    Poznámka:

    Balíček cURL je předinstalovaný ve většině distribucí windows 10 a Windows 11 a většiny distribucí macOS a Linuxu. Verzi balíčku můžete zkontrolovat pomocí následujících příkazů: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Pokud není nainstalovaný cURL, tady jsou instalační odkazy pro vaši platformu:

  • Aktivní účet Azure Pokud žádné nemáte, můžete si vytvořit bezplatný účet.

  • Účet služby Azure Blob Storage. Potřebujete také vytvořit kontejnery v účtu služby Azure Blob Storage pro zdrojové a cílové soubory:

    • Zdrojový kontejner. V tomto kontejneru nahrajete nativní soubory pro analýzu (povinné).
    • Cílový kontejner. Tento kontejner je místo, kde jsou uložené analyzované soubory (povinné).

  • Prostředek jazyka s jednou službou (nikoli prostředek služeb Azure AI s více službami):

    Vyplňte pole podrobností projektu zdroje jazyka a instance následujícím způsobem:

    1. Předplatné Vyberte jedno z dostupných předplatných Azure.

    2. Skupina prostředků: Můžete vytvořit novou skupinu prostředků nebo přidat prostředek do existující skupiny prostředků, která sdílí stejný životní cyklus, oprávnění a zásady.

    3. Oblast zdroje. Zvolte Globální, pokud vaše firma nebo aplikace nevyžaduje konkrétní oblast. Pokud pro ověřování plánujete použít spravovanou identitu přiřazenou systémem (RBAC), zvolte geografickou oblast, jako je USA – západ.

    4. Název. Zadejte název, který jste zvolili pro prostředek. Název, který zvolíte, musí být v rámci Azure jedinečný.

    5. Cenová úroveň: K vyzkoušení služby můžete použít cenovou úroveňFree F0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

    6. Vyberte Zkontrolovat a vytvořit.

    7. Projděte si podmínky služby a vyberte Vytvořit a nasaďte prostředek.

    8. Po úspěšném nasazení prostředku vyberte Přejít k prostředku.

Načtení klíče a koncového bodu služby jazyka

Požadavky na službu Language vyžadují pro ověření přístupu klíč jen pro čtení a vlastní koncový bod.

  1. Pokud jste vytvořili nový prostředek, po nasazení vyberte Přejít k prostředku. Pokud máte existující prostředek služby jazyka, přejděte přímo na stránku prostředku.

  2. Na levém řádku v části Správa prostředků vyberte Klíče a koncový bod.

  3. Můžete zkopírovat a vložit své key a language service instance endpoint do ukázek kódu, abyste ověřili vaši žádost ve službě Language. K volání rozhraní API je nutný jenom jeden klíč.

Vytvoření kontejnerů Azure Blob Storage

Vytvořte kontejnery v účtu služby Azure Blob Storage pro zdrojové a cílové soubory.

  • Zdrojový kontejner. V tomto kontejneru nahrajete nativní soubory pro analýzu (povinné).
  • Cílový kontejner. Tento kontejner je místo, kde jsou uložené analyzované soubory (povinné).

Authentication

Váš prostředek jazyka musí mít udělený přístup k vašemu účtu úložiště, aby mohl vytvářet, číst nebo odstraňovat objekty blob. Existují dvě primární metody, které můžete použít k udělení přístupu k datům úložiště:

  • Tokeny sdíleného přístupového podpisu (SAS) Tokeny SAS delegování uživatele jsou zabezpečené pomocí přihlašovacích údajů Microsoft Entra. Tokeny SAS poskytují zabezpečený a delegovaný přístup k prostředkům ve vašem účtu úložiště Azure.

  • Řízení přístupu na základě role spravované identity (RBAC) Spravované identity pro prostředky Azure jsou instanční objekty, které vytvářejí identitu Microsoft Entra a konkrétní oprávnění pro spravované prostředky Azure.

Pro tento projekt ověřujeme přístup k source location adresám URL target location pomocí tokenů sdíleného přístupového podpisu (SAS) připojených jako řetězce dotazu. Každý token je přiřazený ke konkrétnímu objektu blob (souboru).

Snímek obrazovky s adresou URL úložiště s připojeným tokenem SAS

  • Zdrojový kontejner nebo objekt blob musí určit přístup pro čtení a seznam.
  • Cílový kontejner nebo objekt blob musí určit přístup k zápisu a seznamu.

Tip

Vzhledem k tomu, že zpracováváme jeden soubor (objekt blob), doporučujeme delegovat přístup SAS na úrovni objektu blob.

Hlavičky a parametry požadavku

parametr Popis
-X POST <endpoint> Určuje koncový bod prostředku jazyka pro přístup k rozhraní API.
--header Content-Type: application/json Typ obsahu pro odesílání dat JSON.
--header "Ocp-Apim-Subscription-Key:<key> Určuje klíč prostředku jazyka pro přístup k rozhraní API.
-data Soubor JSON obsahující data, která chcete předat s vaším požadavkem.

Následující příkazy cURL se spouští z prostředí BASH. Tyto příkazy můžete upravit pomocí vlastního názvu prostředku, klíče prostředku a hodnot JSON. Zkuste analyzovat nativní dokumenty výběrem ukázkového projektu nebo Document Summarization ukázkového Personally Identifiable Information (PII) projektu kódu:

Ukázkový dokument PII

Pro účely tohoto rychlého startu potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro tento projekt si můžete stáhnout ukázkový dokument Microsoft Wordu nebo Adobe PDF . Zdrojový jazyk je angličtina.

Sestavení požadavku POST

  1. Pomocí preferovaného editoru nebo integrovaného vývojového prostředí vytvořte nový adresář pro vaši aplikaci s názvem native-document.

  2. V adresáři nativního dokumentu vytvořte nový soubor JSON s názvem pii-detection.json.

  3. Zkopírujte a vložte do souboru pii-detection.json následující ukázku žádosti o identifikovatelné osobní údaje (PII). Nahraďte {your-source-container-SAS-URL} a {your-target-container-SAS-URL} nahraďte hodnotami z instance kontejneru účtu úložiště na webu Azure Portal:

Ukázka požadavku

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

  • Zdrojová location hodnota je adresa URL SAS zdrojového dokumentu (objekt blob), nikoli adresa URL SAS zdrojového kontejneru.

  • Možné redactionPolicy hodnoty jsou UseRedactionCharacterWithRefId (výchozí) nebo UseEntityTypeName. Další informace naleznete v tématu PiiTask Parameters.

Spuštění požadavku POST

  1. Tady je předběžná struktura požadavku POST:

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

  2. Před spuštěním požadavku POST nahraďte {your-language-resource-endpoint} a {your-key} nahraďte hodnoty z instance jazykové služby webu Azure Portal.

    Důležité

    Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v tématu Zabezpečení služeb Azure AI.

    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"

    příkazový řádek / terminál

       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. Tady je ukázková odpověď:

    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

Odpověď POST (jobId)

Obdržíte odpověď 202 (Úspěch), která obsahuje hlavičku operace jen pro čtení. Hodnota této hlavičky obsahuje ID úlohy , na které se dá dotazovat, aby se získal stav asynchronní operace a načetly výsledky pomocí požadavku GET :

Snímek obrazovky znázorňující hodnotu umístění operace v odpovědi POST

Získání výsledků analýzy (požadavek GET)

  1. Po úspěšném požadavku POST dotazujte hlavičku umístění operace vrácenou v požadavku POST a zobrazte zpracovávaná data.

  2. Tady je předběžná struktura požadavku GET :

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

  3. Před spuštěním příkazu proveďte tyto změny:

    • Nahraďte {jobId} hlavičkou Operation-Location z odpovědi POST.

    • Nahraďte {your-language-resource-endpoint} a {your-key} hodnotami z instance služby Language na webu Azure Portal.

Získání žádosti

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

Prozkoumání odpovědi

Obdržíte odpověď 200 (Úspěch) s výstupem JSON. Pole stavu označuje výsledek operace. Pokud operace není dokončená, hodnota stavu je spuštěná nebo notStarted a měli byste rozhraní API volat znovu, a to buď ručně, nebo prostřednictvím skriptu. Doporučujeme interval jedné sekundy nebo více mezi voláními.

Ukázková odpověď

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

Po úspěšném dokončení:

  • Analyzované dokumenty najdete v cílovém kontejneru.
  • Úspěšná metoda POST vrátí 202 Accepted kód odpovědi označující, že služba vytvořila dávkovou žádost.
  • Požadavek POST také vrátil hlavičky odpovědi, včetně Operation-Location toho, že poskytuje hodnotu použitou v následných požadavcích GET.

Vyčištění prostředků

Pokud chcete vyčistit a odebrat předplatné služeb Azure AI, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní prostředky, které jsou k ní přidružené.

Další kroky

Přehled shrnutí dokumentů s přehledem detekce PII