Udostępnij przez

Tworzenie analizatora niestandardowego za pomocą interfejsów API REST

Analizatory usługi Content Understanding definiują sposób przetwarzania i wyodrębniania szczegółowych informacji z zawartości. Zapewniają one jednolitą strukturę przetwarzania i danych wyjściowych dla całej zawartości w celu zapewnienia niezawodnych i przewidywalnych wyników. Oferujemy wstępnie przygotowane analizatory dla typowych przypadków użycia. W tym przewodniku pokazano, jak te analizatory można dostosować, aby lepiej pasowały do Twoich potrzeb.

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

Warunek wstępny

Aby rozpocząć pracę, upewnij się, że masz następujące zasoby i uprawnienia:

  • Subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób Microsoft Foundry w witrynie Azure Portal. Pamiętaj, aby utworzyć go w obsługiwanym regionie.
    • Ten zasób znajduje się w obszarze Foundry>Foundry w portalu.
  • Skonfiguruj domyślne wdrożenia modelu dla zasobu Content Understanding. Ustawienie wartości domyślnych powoduje utworzenie połączenia z modelami usługi Foundry używanymi dla żądań usługi Content Understanding. Wybierz jedną z poniższych metod:
    1. Przejdź do strony Ustawień usługi Content Understanding
    2. Wybierz przycisk "+ Dodaj zasób" w lewym górnym rogu
    3. Wybierz zasób Foundry, którego chcesz użyć, a następnie kliknij przycisk Dalej, a następnie pozycję Zapisz
      • Pamiętaj, aby pozostawić pole wyboru "Włącz automatyczne wdrażanie dla wymaganych modeli, jeśli nie są dostępne żadne wartości domyślne". Dzięki temu zasób jest w pełni skonfigurowany z wymaganymi modelami GPT-4.1, GPT-4.1-mini oraz modelami text-embedding-3-large. Różne wstępnie utworzone analizatory wymagają różnych modeli.
    Wykonując te kroki, skonfigurujesz połączenie między modelami Content Understanding i Foundry w zasobie usługi Foundry.

Definiowanie schematu analizatora

Aby utworzyć analizator niestandardowy, zdefiniuj schemat pola opisujący dane ustrukturyzowane, które chcesz wyodrębnić. W poniższym przykładzie utworzymy analizator oparty na wstępnie utworzonym analizatorze dokumentów na potrzeby przetwarzania paragonu.

Utwórz plik o nazwie receipt.json z następującą zawartością.

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    "returnDetails": true,
    "enableFormula": false,
    "disableContentFiltering": false,
    "estimateFieldSourceAndConfidence": true,
    "tableFormat": "html"
  },
 "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the receipt"
      },
      "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"
            }
          }
        }
      }
    }
  }
}

Jeśli masz różne typy dokumentów, które należy przetworzyć, ale chcesz kategoryzować i analizować tylko paragony, możesz utworzyć analizator, który najpierw kategoryzuje dokument. Następnie należy skierować go do utworzonego powyżej analizatora przy użyciu następującego schematu.

Utwórz plik o nazwie categorize.json z następującą zawartością.

{
  "baseAnalyzerId": "prebuilt-document",
  // Use the base analyzer to invoke the document specific capabilities.

  //Specify the model the analyzer should use. This is one of the supported completion models and one of the supported embeddings model. The specific deployment used during analyze is set on the resource or provided in the analyze request.
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    // Enable splitting of the input into segments. Set this property to false if you only expect a single document within the input file. When specified and enableSegment=false, the whole content will be classified into one of the categories.
    "enableSegment": false,

    "contentCategories": {
      // Category name.
      "receipt": {
        // Description to help with classification and splitting.
        "description": "Any images or documents of receipts",

        // Define the analyzer that any content classified as a receipt should be routed to
        "analyzerId": "receipt"
      },

      "invoice": {
        "description": "Any images or documents of invoice",
        "analyzerId": "prebuilt-invoice"
      },
      "policeReport": {
        "description": "A police or law enforcement report detailing the events that lead to the loss."
        // Don't perform analysis for this category.
      }

    },

    // Omit original content object and only return content objects from additional analysis.
    "omitContent": true
  }

  //You can use fieldSchema here to define fields that are needed from the entire input content.

}

Tworzenie analizatora

Żądanie PUT

Najpierw utwórz analizator paragonów, a następnie utwórz analizator kategorii.

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

Odpowiedź PUT

Odpowiedź 201 Created zawiera nagłówek Operation-Location z adresem URL, którego można użyć do śledzenia statusu operacji tworzenia asynchronicznego analizatora.

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

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

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

Analizowanie pliku

Wyślij plik

Teraz możesz użyć utworzonego analizatora niestandardowego do przetwarzania plików i wyodrębniania pól zdefiniowanych w schemacie.

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

  1. Zastąp {endpoint} wartościami punktów końcowych i {key} kluczami z wystąpienia w portalu Azure usługi Foundry.
  2. Zastąp {analyzerId} nazwą utworzonego przez siebie analizatora niestandardowego, używając pliku categorize.json.
  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/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

Żądanie POST

W tym przykładzie użyto analizatora niestandardowego utworzonego za categorize.json pomocą pliku w celu przeanalizowania potwierdzenia.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs":[
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png"
          }          
        ]
      }'

Odpowiedź POST

Odpowiedź 202 Accepted zawiera informacje {resultId} , których można użyć do śledzenia stanu tej operacji asynchronicznej.

{
  "id": {resultId},
  "status": "Running",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": []
  }
}

Uzyskiwanie wyniku analizy

Użyj Operation-Location z odpowiedzi POST i pobierz wynik analizy.

Żądanie GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Odpowiedź GET

Odpowiedź 200 OK zawiera status pole, które pokazuje postęp operacji.

  • status jest Succeeded jeśli operacja została ukończona pomyślnie.
  • Jeśli to jest running lub notStarted, wywołaj API ponownie ręcznie lub za pomocą skryptu: poczekaj co najmniej jedną sekundę między żądaniami.
Przykładowa odpowiedź
{
  "id": {resultId},
  "status": "Succeeded",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "path": "input1/segment1",
        "category": "receipt",
        "markdown": "Contoso\n\n123 Main Street\nRedmond, WA 98052\n\n987-654-3210\n\n6/10/2019 13:59\nSales Associate: Paul\n\n\n<table>\n<tr>\n<td>2 Surface Pro 6</td>\n<td>$1,998.00</td>\n</tr>\n<tr>\n<td>3 Surface Pen</td>\n<td>$299.97</td>\n</tr>\n</table> ...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "Contoso",
            "spans": [{"offset": 0,"length": 7}],
            "confidence": 0.996,
            "source": "D(1,774.0000,72.0000,974.0000,70.0000,974.0000,111.0000,774.0000,113.0000)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "2 Surface Pro 6",
                    "spans": [ { "offset": 115, "length": 15}],
                    "confidence": 0.423,
                    "source": "D(1,704.0000,482.0000,875.0000,482.0000,875.0000,508.0000,704.0000,508.0000)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 1998,
                    "spans": [{ "offset": 140,"length": 9}
                    ],
                    "confidence": 0.957,
                    "source": "D(1,952.0000,482.0000,1048.0000,482.0000,1048.0000,508.0000,952.0000,509.0000)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0944,
            "width": 1743,
            "height": 878
          }
        ],
        "analyzerId": "{analyzerId}",
        "mimeType": "image/png"
      }
    ]
  },
  "usage": {
    "documentPages": 1,
    "tokens": {
      "contextualization": 1000
    }
  }
}

Dalsze kroki

  • Przejrzyj przykłady kodu: wyszukiwanie w dokumentach wizualnych.
  • Przejrzyj przykładowy kod: szablony analizatora.
  • Spróbuj przetwarzać zawartość dokumentu przy użyciu usługi Content Understanding w narzędziu Foundry.
  • Last updated on