Udostępnij za pośrednictwem

Szybki start: interfejsy API REST usługi Azure AI Content Understanding

  • Artykuł

  • Zacznij korzystać z najnowszej wersji zapoznawczej interfejsu API REST usługi Azure AI Content Understanding (2024-12-01-preview).

  • Usługa Azure AI Content Understanding to nowa usługa azure AI oparta na sztucznej inteligencji, która analizuje pliki dowolnej modalności (dokumentów, obrazów, wideo i audio) oraz wyodrębnia ustrukturyzowane dane wyjściowe w formatach pól zdefiniowanych przez użytkownika.

  • Łatwo zintegruj usługę Content Understanding z przepływami pracy i aplikacjami, wywołując nasze interfejsy API REST.

  • Ten przewodnik Szybki start przeprowadzi Cię przez proces tworzenia niestandardowego analizatora i wyodrębniania zawartości i pól z danych wejściowych przy użyciu interfejsu API REST usługi Content Understanding.

Wymagania wstępne

Aby rozpocząć pracę, potrzebujesz aktywnej subskrypcji platformy Azure. Jeśli nie masz konta platformy Azure, możesz utworzyć bezpłatną subskrypcję.

  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usług Azure AI Services w witrynie Azure Portal. Ten zasób z wieloma usługami umożliwia dostęp do wielu usług azure AI z jednym zestawem poświadczeń.

    • Ten zasób znajduje się na liście w obszarze Usługi sztucznej inteligencji platformy Azure → usług Azure AI w portalu.

      Ważne

      Platforma Azure udostępnia więcej niż jeden typ zasobu o nazwie Usługi Azure AI. Upewnij się, że wybrano tę z listy w obszarze usługi Azure AI services → usług Azure AI, jak pokazano na poniższej ilustracji. Aby uzyskać więcej informacji, zobacz Create an Azure AI Services resource (Tworzenie zasobu usług Azure AI Services).

      Zrzut ekranu przedstawiający stronę zasobów z wieloma usługami w witrynie Azure Portal.

  • W tym przewodniku Szybki start użyjemy narzędzia wiersza polecenia cURL. Jeśli nie jest zainstalowany, możesz pobrać wersję dla środowiska deweloperskiego:

Tworzenie niestandardowego analizatora

Aby utworzyć analizator niestandardowy, należy zdefiniować schemat pola opisujący dane ustrukturyzowane, które chcesz wyodrębnić. W poniższym przykładzie definiujemy schemat wyodrębniania podstawowych informacji z dokumentu faktury.

Najpierw utwórz plik JSON o nazwie o request_body.json następującej zawartości:

{
  "description": "Sample invoice analyzer",
  "scenario": "document",
  "config": {
    "returnDetails": true
  },
  "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the invoice"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Przed uruchomieniem następujących cURL poleceń wprowadź następujące zmiany w żądaniu HTTP:

  1. Zastąp {endpoint} wartości punktów {key} końcowych i kluczami z wystąpienia usług Azure AI Services w witrynie Azure Portal.
  2. Zastąp {analyzerId} ciąg nazwą nowego analizatora i utwórz, na przykład myInvoice.

Żądanie PUT

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @request_body.json

Odpowiedź PUT

Odpowiedź 201 (Created) zawiera Operation-Location nagłówek zawierający adres URL, którego można użyć do śledzenia stanu tej operacji asynchronicznej tworzenia.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview

Po zakończeniu wykonywanie żądania HTTP GET w adresie URL zwraca wartość "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Analizowanie pliku

Pliki można analizować przy użyciu utworzonego analizatora niestandardowego w celu wyodrębnienia pól zdefiniowanych w schemacie.

Przed uruchomieniem polecenia cURL wprowadź następujące zmiany w żądaniu HTTP:

  1. Zastąp {endpoint} wartości punktów {key} końcowych i kluczami z wystąpienia usług Azure AI Services w witrynie Azure Portal.
  2. Zastąp {analyzerId} ciąg nazwą utworzonego wcześniej analizatora niestandardowego.
  3. Zastąp {fileUrl} element publicznie dostępnym adresem URL pliku do analizy, takim jak ścieżka do obiektu blob usługi Azure Storage przy użyciu sygnatury dostępu współdzielonego (SAS) lub przykładowego adresu URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

Żądanie POST

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?stringEncoding=codePoint&api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"{fileUrl}\"}"

Odpowiedź POST

Odpowiedź 202 (Accepted) zawiera Operation-Location nagłówek zawierający adres URL, którego można użyć do śledzenia stanu tej operacji analizy asynchronicznej.

202 Accepted
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview

Uzyskiwanie wyniku analizy

resultId Użyj elementu z nagłówka Operation-Location zwróconego przez poprzednią POST odpowiedź i pobierz wynik analizy.

  1. Zastąp {endpoint} wartości punktów {key} końcowych i kluczami z wystąpienia usług Azure AI Services w witrynie Azure Portal.
  2. Zastąp {analyzerId} ciąg nazwą utworzonego wcześniej analizatora niestandardowego.
  3. Zastąp element {resultId} zwróconym resultId z POST żądania.

Żądanie GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Odpowiedź GET

Odpowiedź JSON 200 (OK) zawiera status pole wskazujące stan operacji. Jeśli operacja nie została ukończona, wartość to status running lub notStarted. W takich przypadkach należy ponownie wywołać interfejs API, ręcznie lub za pomocą skryptu. Poczekaj interwał co najmniej jednej sekundy między wywołaniami.

Przykładowa odpowiedź

{
  "id": "bcf8c7c7-03ab-4204-b22c-2b34203ef5db",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_invoice_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-13T07:15:46Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "CONTOSO LTD.",
            "spans": [ { "offset": 0, "length": 12 } ],
            "confidence": 0.941,
            "source": "D(1,0.5729,0.6582,2.3353,0.6582,2.3353,0.8957,0.5729,0.8957)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [ { "offset": 909, "length": 19 } ],
                    "confidence": 0.971,
                    "source": "D(1,2.3264,5.673,3.6413,5.673,3.6413,5.8402,2.3264,5.8402)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 60,
                    "spans": [ { "offset": 995, "length": 6 } ],
                    "confidence": 0.989,
                    "source": "D(1,7.4507,5.6684,7.9245,5.6684,7.9245,5.8323,7.4507,5.8323)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0039,
            "width": 8.5,
            "height": 11,
            "spans": [ { "offset": 0, "length": 1650 } ],
            "words": [
              {
                "content": "CONTOSO",
                "span": { "offset": 0, "length": 7 },
                "confidence": 0.997,
                "source": "D(1,0.5739,0.6582,1.7446,0.6595,1.7434,0.8952,0.5729,0.8915)"
              }, ...
            ],
            "lines": [
              {
                "content": "CONTOSO LTD.",
                "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
                "span": { "offset": 0, "length": 12 }
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "CONTOSO LTD.",
            "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
            "span": { "offset": 0, "length": 12 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          },
          {
            "span": { "offset": 0, "length": 12 },
            "elements": [ "/paragraphs/0" ]
          }, ...
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 6,
            "cells": [
              {
                "kind": "columnHeader",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "SALESPERSON",
                "source": "D(1,0.5389,4.5514,1.7505,4.5514,1.7505,4.8364,0.5389,4.8364)",
                "span": { "offset": 512, "length": 11 },
                "elements": [ "/paragraphs/19" ]
              }, ...
            ],
            "source": "D(1,0.4885,4.5543,8.0163,4.5539,8.015,5.1207,0.4879,5.1209)",
            "span": { "offset": 495, "length": 228 }
          }, ...
        ]
      }
    ]
  }
}

Następne kroki

  • W tym przewodniku Szybki start przedstawiono sposób wywoływania interfejsu API REST w celu utworzenia analizatora niestandardowego. Aby uzyskać środowisko użytkownika, wypróbuj usługę Azure AI Foundry.