Udostępnij za pośrednictwem

Natywna obsługa dokumentów dla języka azure AI (wersja zapoznawcza)

  • Artykuł

Ważne

  • Natywna obsługa dokumentów jest podglądem z bramką. Aby poprosić o dostęp do funkcji obsługi dokumentów natywnych, ukończ i prześlij formularz Zastosuj o dostęp do wersji zapoznawczych usługi językowej .

  • Publiczne wersje zapoznawcze języka sztucznej inteligencji platformy Azure zapewniają wczesny dostęp do funkcji, które są aktywnie opracowywane.

  • Funkcje, podejścia i procesy mogą ulec zmianie przed ogólną dostępnością na podstawie opinii użytkowników.

Azure AI Language to oparta na chmurze usługa, która stosuje funkcje przetwarzania języka naturalnego (NLP) do danych tekstowych. Funkcja obsługi dokumentów natywnych umożliwia asynchroniczne wysyłanie żądań interfejsu API przy użyciu treści żądania HTTP POST w celu wysyłania danych i ciągu zapytania żądania HTTP GET w celu pobrania wyników stanu. Przetworzone dokumenty znajdują się w kontenerze docelowym usługi Azure Blob Storage.

Dokument natywny odnosi się do formatu pliku używanego do tworzenia oryginalnego dokumentu, takiego jak Microsoft Word (docx) lub przenośny plik dokumentu (pdf). Obsługa dokumentów natywnych eliminuje konieczność wstępnego przetwarzania tekstu przed użyciem funkcji zasobów języka sztucznej inteligencji platformy Azure. Obecnie obsługa dokumentów natywnych jest dostępna dla następujących funkcji:

  • Dane osobowe (PII) Funkcja wykrywania danych osobowych może identyfikować, kategoryzować i redagować poufne informacje w tekście bez struktury. Interfejs PiiEntityRecognition API obsługuje natywne przetwarzanie dokumentów.

  • Podsumowanie dokumentu. Podsumowanie dokumentów używa przetwarzania języka naturalnego do generowania wyodrębniających (istotnych wyodrębniania zdań) lub abstrakcyjnych (wyodrębniania wyrazów kontekstowych) dla dokumentów. Interfejsy AbstractiveSummarization API i ExtractiveSummarization obsługują natywne przetwarzanie dokumentów.

Obsługiwane formaty dokumentów

Aplikacje używają natywnych formatów plików do tworzenia, zapisywania lub otwierania dokumentów natywnych. Obecnie funkcje podsumowania danych i dokumentów obsługują następujące natywne formaty dokumentów:

Typ pliku Rozszerzenie pliku opis
Tekst .txt Niesformatowany dokument tekstowy.
Adobe PDF .pdf Przenośny plik dokumentu sformatowany.
Microsoft Word .docx Plik dokumentu programu Microsoft Word.

Wskazówki dotyczące danych wejściowych

Obsługiwane formaty plików

Typ pomoc techniczna i ograniczenia
Pliki PDF W pełni zeskanowane pliki PDF nie są obsługiwane.
Tekst na obrazach Obrazy cyfrowe z osadzonym tekstem nie są obsługiwane.
Tabele cyfrowe Tabele w zeskanowanych dokumentach nie są obsługiwane.

Rozmiar dokumentu

Atrybut Limit danych wejściowych
Łączna liczba dokumentów na żądanie ≤ 20
Łączny rozmiar zawartości na żądanie ≤ 1 MB

Dołączanie dokumentów natywnych do żądania HTTP

Zacznijmy:

  • W tym projekcie używamy narzędzia wiersza polecenia cURL do wykonywania wywołań interfejsu API REST.

    Uwaga

    Pakiet cURL jest wstępnie zainstalowany w większości dystrybucji systemów Windows 10 i Windows 11 oraz większości systemów macOS i Linux. Wersję pakietu można sprawdzić za pomocą następujących poleceń: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Jeśli program cURL nie jest zainstalowany, poniżej znajdują się linki instalacyjne dla twojej platformy:

  • Aktywne konto platformy Azure. Jeśli nie masz, możesz utworzyć bezpłatne konto.

  • Konto usługi Azure Blob Storage. Musisz również utworzyć kontenery na koncie usługi Azure Blob Storage dla plików źródłowych i docelowych:

    • Kontener źródłowy. Ten kontener służy do przekazywania plików natywnych do analizy (wymagane).
    • Kontener docelowy. W tym kontenerze są przechowywane przeanalizowane pliki (wymagane).

  • Zasób języka pojedynczej usługi (a nie zasób usług Azure AI z wieloma usługami):

    Wypełnij pola Projekt zasobów języka i szczegóły wystąpienia w następujący sposób:

    1. Subskrypcja. Wybierz jedną z dostępnych subskrypcji platformy Azure.

    2. Grupa zasobów. Możesz utworzyć nową grupę zasobów lub dodać zasób do istniejącej grupy zasobów, która współudzieli ten sam cykl życia, uprawnienia i zasady.

    3. Region zasobów. Wybierz pozycję Globalny , chyba że Twoja firma lub aplikacja wymaga określonego regionu. Jeśli planujesz uwierzytelnianie przy użyciu tożsamości zarządzanej przypisanej przez system, wybierz region geograficzny , taki jak Zachodnie stany USA.

    4. Name. Wprowadź nazwę wybraną dla zasobu. Wybrana nazwa musi być unikatowa na platformie Azure.

    5. Warstwa cenowa. Możesz użyć warstwy cenowej bezpłatna (Free F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

    6. Wybierz pozycję Przejrzyj i utwórz.

    7. Przejrzyj warunki usługi i wybierz pozycję Utwórz , aby wdrożyć zasób.

    8. Po pomyślnym wdrożeniu zasobu wybierz pozycję Przejdź do zasobu.

Pobieranie klucza i punktu końcowego usługi językowej

Żądania do usługi językowej wymagają klucza tylko do odczytu i niestandardowego punktu końcowego w celu uwierzytelnienia dostępu.

  1. Jeśli utworzono nowy zasób, po jego wdrożeniu wybierz pozycję Przejdź do zasobu. Jeśli masz istniejący zasób usługi językowej, przejdź bezpośrednio do strony zasobu.

  2. W lewej szynie w obszarze Zarządzanie zasobami wybierz pozycję Klucze i punkt końcowy.

  3. Możesz skopiować i wkleić kod key language service instance endpoint do przykładów kodu, aby uwierzytelnić żądanie w usłudze językowej. Tylko jeden klucz jest wymagany do wykonania wywołania interfejsu API.

Tworzenie kontenerów usługi Azure Blob Storage

Utwórz kontenery na koncie usługi Azure Blob Storage dla plików źródłowych i docelowych.

  • Kontener źródłowy. Ten kontener służy do przekazywania plików natywnych do analizy (wymagane).
  • Kontener docelowy. W tym kontenerze są przechowywane przeanalizowane pliki (wymagane).

Authentication

Zasób języka wymaga udzielenia dostępu do konta magazynu, zanim będzie mógł tworzyć, odczytywać lub usuwać obiekty blob. Istnieją dwie podstawowe metody, których można użyć do udzielenia dostępu do danych magazynu:

  • Tokeny sygnatury dostępu współdzielonego (SAS). Tokeny SAS delegowania użytkownika są zabezpieczone przy użyciu poświadczeń usługi Microsoft Entra. Tokeny SAS zapewniają bezpieczny, delegowany dostęp do zasobów na koncie usługi Azure Storage.

  • Kontrola dostępu oparta na rolach (RBAC) tożsamości zarządzanej. Tożsamości zarządzane dla zasobów platformy Azure to jednostki usługi, które tworzą tożsamość firmy Microsoft Entra i określone uprawnienia dla zasobów zarządzanych platformy Azure.

W tym projekcie uwierzytelniamy dostęp do source location adresów URL i target location przy użyciu tokenów sygnatury dostępu współdzielonego (SAS) dołączanych jako ciągi zapytania. Każdy token jest przypisywany do określonego obiektu blob (pliku).

Zrzut ekranu przedstawiający adres URL magazynu z dołączonym tokenem SAS.

  • Źródłowy kontener lub obiekt blob musi wyznaczyć dostęp do odczytu i listy.
  • Docelowy kontener lub obiekt blob musi wyznaczyć dostęp do zapisu i listy.

Napiwek

Ponieważ przetwarzamy pojedynczy plik (blob), zalecamy delegowanie dostępu współdzielonego na poziomie obiektu blob.

Nagłówki i parametry żądania

parametr Opis
-X POST <endpoint> Określa punkt końcowy zasobu języka na potrzeby uzyskiwania dostępu do interfejsu API.
--header Content-Type: application/json Typ zawartości do wysyłania danych JSON.
--header "Ocp-Apim-Subscription-Key:<key> Określa klucz zasobu języka na potrzeby uzyskiwania dostępu do interfejsu API.
-data Plik JSON zawierający dane, które chcesz przekazać z żądaniem.

Następujące polecenia cURL są wykonywane z powłoki BASH. Edytuj te polecenia przy użyciu własnych nazw zasobów, klucza zasobu i wartości JSON. Spróbuj przeanalizować dokumenty natywne, wybierając przykładowy Personally Identifiable Information (PII) projekt lub Document Summarization kodu:

Przykładowy dokument pii

W tym przewodniku Szybki start potrzebny jest dokument źródłowy przekazany do kontenera źródłowego. Możesz pobrać przykładowy dokument programu Microsoft Word lub adobe PDF dla tego projektu. Język źródłowy to angielski.

Kompilowanie żądania POST

  1. Za pomocą preferowanego edytora lub środowiska IDE utwórz nowy katalog dla aplikacji o nazwie native-document.

  2. Utwórz nowy plik JSON o nazwie pii-detection.json w katalogu dokumentu natywnego.

  3. Skopiuj i wklej następujący przykładowy wniosek o identyfikację użytkownika (PII) do plikupii-detection.json. Zastąp {your-source-container-SAS-URL} wartości i {your-target-container-SAS-URL} wartościami z wystąpienia kontenerów konta usługi Azure Portal Storage:

Przykład żądania

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • Wartość źródłowa location to adres URL sygnatury dostępu współdzielonego dla dokumentu źródłowego (blob), a nie źródłowy adres URL sygnatury dostępu współdzielonego kontenera.

  • Możliwe wartości to UseRedactionCharacterWithRefId (wartość domyślnaredactionPolicy) lub UseEntityTypeName. Aby uzyskać więcej informacji, zobacz Parametry usługi PiiTask.

Uruchamianie żądania POST

  1. Oto wstępna struktura żądania POST:

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

  2. Przed uruchomieniem żądania POST zastąp {your-language-resource-endpoint} wartości i {your-key} wartościami z wystąpienia usługi językowej witryny Azure Portal.

    Ważne

    Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz Zabezpieczenia usług Azure AI.

    Program PowerShell

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

    wiersz polecenia/terminal

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

  3. Oto przykładowa odpowiedź:

    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=2023-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

Odpowiedź POST (jobId)

Otrzymasz odpowiedź 202 (Powodzenie), która zawiera nagłówek Operation-Location tylko do odczytu. Wartość tego nagłówka zawiera identyfikator jobId , który można wykonać zapytanie w celu uzyskania stanu operacji asynchronicznej i pobrania wyników przy użyciu żądania GET :

Zrzut ekranu przedstawiający wartość lokalizacji operacji w odpowiedzi POST.

Pobieranie wyników analizy (żądanie GET)

  1. Po pomyślnym żądaniu POST sprawdź nagłówek operation-location zwrócony w żądaniu POST, aby wyświetlić przetworzone dane.

  2. Oto wstępna struktura żądania GET :

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

  3. Przed uruchomieniem polecenia wprowadź następujące zmiany:

    • Zastąp element {jobId} nagłówkiem Operation-Location z odpowiedzi POST.

    • Zastąp ciąg {your-language-resource-endpoint} i {your-key} wartościami z wystąpienia usługi językowej w witrynie Azure Portal.

Pobieranie żądania

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-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=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Sprawdzanie odpowiedzi

Otrzymasz odpowiedź 200 (Powodzenie) z danymi wyjściowymi JSON. Pole stanu wskazuje wynik operacji. Jeśli operacja nie zostanie ukończona, wartość stanu to "running" lub "notStarted" i należy wywołać interfejs API ponownie, ręcznie lub za pomocą skryptu. Zalecamy interwał co najmniej jednej sekundy między wywołaniami.

Przykładowa odpowiedź

{
  "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 pomyślnym zakończeniu:

  • Przeanalizowane dokumenty można znaleźć w kontenerze docelowym.
  • Pomyślna metoda POST zwraca 202 Accepted kod odpowiedzi wskazujący, że usługa utworzyła żądanie wsadowe.
  • Żądanie POST zwróciło również nagłówki odpowiedzi, w tym Operation-Location wartości używane w kolejnych żądaniach GET.

Czyszczenie zasobów

Jeśli chcesz wyczyścić i usunąć subskrypcję usług Azure AI, możesz usunąć zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów.

Następne kroki

Omówienie wykrywania danych pii — omówienie podsumowania dokumentów