Supporto di documenti nativi per la Lingua di Azure AI (anteprima)

  • Articolo

Importante

  • Il supporto dei documenti nativi è un'anteprima controllata. Per richiedere l'accesso alla funzionalità di supporto dei documenti nativi, completare e inviare il modulo Applica per l'accesso alle anteprime del servizio Lingua.

  • Le versioni di anteprima pubblica di Lingua di Azure AI offrono l'accesso anticipato alle funzionalità in fase di sviluppo attivo.

  • Le funzionalità, gli approcci e i processi possono cambiare prima della disponibilità generale, a seconda del feedback degli utenti.

La lingua di Azure AI è un servizio basato sul cloud che applica le funzionalità di elaborazione del linguaggio naturale ai dati basati su testo. La funzionalità di supporto del documento nativo consente di inviare richieste API in modo asincrono, usando un corpo della richiesta HTTP POST per inviare i dati e la stringa di query della richiesta HTTP GET per recuperare i risultati dello stato. I documenti elaborati si trovano nel contenitore di destinazione di archiviazione BLOB di Azure.

Un documento nativo fa riferimento al formato di file usato per creare il documento originale, ad esempio Microsoft Word (docx) o un file di documento portatile (pdf). Il supporto di documenti nativi elimina la necessità di pre-elaborazione del testo prima dell'uso delle funzionalità delle risorse di Lingua di Azure AI. Attualmente, il supporto per i documenti nativi è disponibile per le funzionalità seguenti:

  • informazioni personali (PII). La funzionalità di rilevamento delle informazioni personali consente di identificare, classificare e redigere le informazioni riservate in un testo non strutturato. L'API PiiEntityRecognition supporta l'elaborazione dei documenti nativa.

  • Riepilogo del documento Il riepilogo del documento usa l'elaborazione del linguaggio naturale per generare riepiloghi estrattivi (estrazione di frasi salienti) o astrattivi (estrazione di parole contestuali) per i documenti. Sia le API AbstractiveSummarization che ExtractiveSummarization supportano l'elaborazione dei documenti nativi.

Formati di documento supportati

Le applicazioni usano formati di file nativi per creare, salvare o aprire documenti nativi. Attualmente le funzionalità relative alle informazioni personali e al riepilogo del documento supportano i formati di documento nativi seguenti:

Tipo di file Estensione di file Descrizione
Testo .txt Documento di testo non formattato.
Adobe PDF .pdf Documento formattato con file di documento portatile.
Microsoft Word .docx File di documento Microsoft Word.

Linee guida per l'input

Formati di file supportati

Type Supporto e limitazioni
PDF I PDF a scansione completa non sono supportati.
Testo all'interno delle immagini Le immagini digitali con testo incorporato non sono supportate.
Tabelle digitali Le tabelle nei documenti analizzati non sono supportate.

Dimensioni del documento

Attributo Limite di input
Numero totale di documenti per richiesta ≤ 20
Dimensioni totali del contenuto per richiesta ≤ 1 MB

Includere documenti nativi con una richiesta HTTP

Attività iniziali:

  • Per questo progetto viene usato lo strumento da riga di comando cURL per effettuare chiamate API REST.

    Nota

    Il pacchetto cURL è preinstallato nella maggior parte delle distribuzioni di Windows 10, Windows 11, macOS e Linux. È possibile controllare la versione del pacchetto con i comandi seguenti: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Se cURL non è installato, ecco i collegamenti di installazione per la piattaforma:

  • Un account Azure attivo. Se non si ha un account, è possibile crearne uno gratuito.

  • Un account di Archiviazione BLOB di Azure. È anche necessario creare i contenitori nell'account di Archiviazione BLOB di Azure per i file di origine e di destinazione:

    • Contenitore di origine. Questo contenitore consente di caricare i file nativi per l'analisi (obbligatorio).
    • Contenitore di destinazione. Questo contenitore è il percorso in cui vengono archiviati i file analizzati (obbligatorio).

  • Una risorsa Lingua a servizio singolo (non una risorsa Servizi di Azure AI multiservizio):

    Completare i campi dei dettagli dell'istanza e del progetto di risorse lingua come indicato di seguito:

    1. Sottoscrizione. Selezionare una delle sottoscrizioni di Azure disponibili.

    2. Gruppo di risorse. È possibile creare un nuovo gruppo di risorse o aggiungere la risorsa a un gruppo di risorse preesistente che condivide ciclo di vita, autorizzazioni e criteri identici.

    3. Area della risorsa. Scegliere Globale a meno che l'azienda o l'applicazione non richieda un'area specifica. Se si prevede di usare un'identità gestita assegnata dal sistema per l'autenticazione, scegliere un'area geografica come Stati Uniti occidentali.

    4. Nome. Immettere il nome scelto per la risorsa. Il nome scelto deve essere univoco in Azure.

    5. Piano tariffario. È possibile usare il piano tariffario gratuito (Free F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

    6. Selezionare Rivedi e crea.

    7. Esaminare le condizioni del servizio e selezionare Crea per distribuire la risorsa.

    8. Dopo aver distribuito correttamente la risorsa, selezionare Vai alla risorsa.

Recuperare la chiave e l'endpoint del servizio di lingua

Le richieste al servizio Lingua richiedono una chiave di sola lettura e un endpoint personalizzato per autenticare l'accesso.

  1. Se è stata creata una nuova risorsa, dopo la distribuzione selezionare Vai alla risorsa. Se si dispone di una risorsa del servizio lingua esistente, passare direttamente alla pagina della risorsa.

  2. Nella barra di scorrimento a sinistra, in Gestione risorse, selezionare Chiavi ed endpoint.

  3. È possibile copiare e incollare key e language service instance endpoint negli esempi di codice per autenticare la richiesta al servizio lingua. Per effettuare una chiamata API è necessaria una sola chiave.

Creare contenitori di Archiviazione BLOB di Azure

Sarà necessario creare contenitori nell'account di Archiviazione BLOB di Azure per i file di origine e di destinazione.

  • Contenitore di origine. Questo contenitore consente di caricare i file nativi per l'analisi (obbligatorio).
  • Contenitore di destinazione. Questo contenitore è il percorso in cui vengono archiviati i file analizzati (obbligatorio).

Autenticazione

Prima di poter creare, leggere o eliminare BLOB, è necessario concedere alla risorsa lingua l'accesso all'account di archiviazione. Esistono due metodi principali che è possibile usare per concedere l'accesso ai dati di archiviazione:

Per questo progetto, l'accesso agli URL source location e target location viene autenticato con token di firma di accesso condiviso (SAS) aggiunti come stringhe di query. Ogni token viene assegnato a un BLOB specifico (file).

Screenshot di un URL di archiviazione con il token di firma di accesso condiviso aggiunto.

  • Il contenitore o il BLOB di origine deve designare l'accesso in lettura e per elenchi.
  • Il contenitore o il BLOB di destinazione deve designare l'accesso di scrittura e per elenchi.

Suggerimento

Poiché si sta elaborando un singolo file (BLOB), è consigliabile delegare l'accesso SAS delegato a livello di BLOB.

Intestazioni e parametri della richiesta

parameter Descrizione
-X POST <endpoint> Specifica l'endpoint della risorsa lingua per l'accesso all'API.
--header Content-Type: application/json Il tipo di contenuto per l'invio di dati JSON.
--header "Ocp-Apim-Subscription-Key:<key> Specifica la chiave della risorsa lingua per l'accesso all'API.
-data File JSON contenente i dati da passare con la richiesta.

I comandi cURL seguenti vengono eseguiti da una shell BASH. Modificare questi comandi con il nome e la chiave della risorsa e con i valori del file JSON. Provare ad analizzare i documenti nativi selezionando il progetto di codice di esempio Personally Identifiable Information (PII) o Document Summarization:

Documento di esempio PII

Per questo avvio rapido è necessario caricare un documento di origine nel contenitore di origine. È possibile scaricare il documento di esempio di Microsoft Word o Adobe PDF per questo progetto. La lingua di origine è l'inglese.

Compilare la richiesta POST

  1. Usando l'editor o l'IDE preferito, creare una nuova directory per l'app denominata native-document.

  2. Creare un nuovo file JSON denominato pii-detection.json nella directory native-document .

  3. Copiare e incollare il seguente esempio di richiesta di informazioni personali dell'utente finalenel file pii-detection.json. Sostituire {your-source-container-SAS-URL} e {your-target-container-SAS-URL} con i valori dell'istanza dei contenitori dell'account di archiviazione nel portale di Azure.

Esempio di richiesta

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

  • Il valore di origine location è l'URL di firma di accesso condiviso per il documento di origine (BLOB) e non l'URL della firma di accesso condiviso del contenitore di origine.

  • I valori possibili redactionPolicy sono UseRedactionCharacterWithRefId (predefinito) o UseEntityTypeName. Per altre informazioni, vedereParametri PiiTask.

Eseguire la richiesta POST

  1. Ecco la struttura preliminare della richiesta POST:

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

  2. Prima di eseguire la richiesta POST, sostituire {your-language-resource-endpoint} e {your-key} con i valori dell'istanza del servizio Lingua nel portale di Azure.

    Importante

    Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza di Servizi di Azure AI.

    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"

    Prompt dei comandi/terminale

       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. Di seguito è fornito un esempio di risposta:

    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

Risposta POST (jobId)

Si riceve una risposta 202 (Operazione riuscita) che include un'intestazione Operation-Location di sola lettura. Il valore di questa intestazione contiene un jobId che può essere sottoposto a query per ottenere lo stato dell'operazione asincrona e recuperare i risultati usando una richiesta GET:

Screenshot che mostra il valore della posizione dell'operazione (operation-location) nella risposta POST.

Ottenere i risultati dell'analisi (richiesta GET)

  1. Dopo aver completato la richiesta POST, eseguire il polling dell'intestazione operation-location restituita nella richiesta POST per visualizzare i dati elaborati.

  2. Ecco la struttura preliminare della richiesta GET:

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

  3. Prima di eseguire il comando, apportare queste modifiche:

    • Sostituire {jobId} con l'intestazione Operation-Location della risposta POST.

    • Sostituire {your-language-resource-endpoint} e {your-key} con i valori dell'istanza del servizio Lingua nel portale di Azure.

Richiesta GET

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

Esaminare i risultati

Si riceve una risposta 200 (Operazione riuscita) con l'output JSON. Il campo stato indica il risultato dell'operazione. Se l'operazione non è completa, il valore di stato è "in esecuzione" o "notStarted" (non avviato) ed è necessario chiamare di nuovo l'API, manualmente o tramite uno script. Si consiglia di attendere almeno un secondo tra le chiamate.

Risposta di esempio

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

Al termine dell'operazione:

  • I documenti analizzati sono disponibili nel contenitore di destinazione.
  • La corretta esecuzione del metodo POST restituisce un codice di risposta 202 Accepted che indica che il servizio ha creato la richiesta batch.
  • Anche la richiesta POST restituisce intestazioni della risposta, tra cui Operation-Location che fornisce un valore usato nelle richieste GET successive.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi

Panoramica rilevamento informazioni personali Panoramica del riepilogo del documento