Baca dalam bahasa Inggris

Bagikan melalui

Mulai Cepat: Azure AI Content Understanding REST API

  • Artikel

  • Mulai gunakan versi pratinjau terbaru Rest API Pemahaman Konten Azure AI (pratinjau 2024-12-01).

  • Azure AI Content Understanding adalah Azure AI Service berbasis AI generatif baru yang menganalisis file modalitas apa pun (dokumen, gambar, video, dan audio) dan mengekstrak output terstruktur dalam format bidang yang ditentukan pengguna.

  • Integrasikan layanan Content Understanding ke dalam alur kerja dan aplikasi Anda dengan mudah dengan memanggil REST API kami.

  • Mulai cepat ini memandu Anda menggunakan CONTENT Understanding REST API untuk membuat penganalisis kustom dan mengekstrak konten dan bidang dari input Anda.

Prasyarat

Untuk memulai, Anda memerlukan langganan Azure aktif. Jika Anda tidak memiliki akun Azure, Anda dapat membuat langganan gratis.

  • Setelah Anda memiliki langganan Azure, buat sumber daya Azure AI Services di portal Azure. Sumber daya multi-layanan ini memungkinkan akses ke beberapa layanan Azure AI dengan satu set kredensial.

    • Sumber daya ini tercantum di bawah layanan Azure AI → layanan Azure AI di portal.

      Penting

      Azure menyediakan lebih dari satu jenis sumber daya bernama layanan Azure AI. Pastikan Anda memilih yang tercantum di bawah layanan Azure AI → layanan Azure AI seperti yang digambarkan dalam gambar berikut. Untuk informasi selengkapnya, lihat Membuat sumber daya Azure AI Services.

      Cuplikan layar halaman sumber daya multi-layanan di portal Azure.

  • Dalam mulai cepat ini, kami menggunakan alat baris perintah cURL. Jika tidak diinstal, Anda dapat mengunduh versi untuk lingkungan dev Anda:

Membuat penganalisis kustom

Untuk membuat penganalisis kustom, Anda perlu menentukan skema bidang yang menjelaskan data terstruktur yang ingin Anda ekstrak. Dalam contoh berikut, kami menentukan skema untuk mengekstrak informasi dasar dari dokumen faktur.

Pertama, buat file JSON bernama request_body.json dengan konten berikut:

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

Sebelum menjalankan perintah berikut cURL , buat perubahan berikut pada permintaan HTTP:

  1. Ganti {endpoint} dan {key} dengan titik akhir dan nilai kunci dari instans Azure AI Services portal Azure Anda.
  2. Ganti {analyzerId} dengan nama penganalisis baru dan buat, seperti myInvoice.

Permintaan PUT

Bash 
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

Respons PUT

Respons 201 (Created) menyertakan header yang Operation-Location berisi URL yang dapat Anda gunakan untuk melacak status operasi pembuatan asinkron ini.

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

Setelah selesai, melakukan HTTP GET pada URL mengembalikan "status": "succeeded".

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

Menganalisis file

Anda dapat menganalisis file menggunakan penganalisis kustom yang Anda buat untuk mengekstrak bidang yang ditentukan dalam skema.

Sebelum menjalankan perintah cURL, buat perubahan berikut pada permintaan HTTP:

  1. Ganti {endpoint} dan {key} dengan titik akhir dan nilai kunci dari instans Azure AI Services portal Azure Anda.
  2. Ganti {analyzerId} dengan nama penganalisis kustom yang dibuat sebelumnya.
  3. Ganti {fileUrl} dengan URL file yang dapat diakses publik untuk dianalisis, seperti jalur ke Azure Storage Blob dengan tanda tangan akses bersama (SAS) atau URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdfsampel .

Permintaan POST

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

Respons POST

Respons 202 (Accepted) menyertakan header yang Operation-Location berisi URL yang dapat Anda gunakan untuk melacak status operasi analisis asinkron ini.

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

Dapatkan hasil analisis

resultId Gunakan dari header yang Operation-Location dikembalikan oleh respons sebelumnya POST dan ambil hasil analisis.

  1. Ganti {endpoint} dan {key} dengan titik akhir dan nilai kunci dari instans Azure AI Services portal Azure Anda.
  2. Ganti {analyzerId} dengan nama penganalisis kustom yang dibuat sebelumnya.
  3. Ganti {resultId} dengan yang resultId dikembalikan dari POST permintaan.

Permintaan GET

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

Respons GET

Respons JSON 200 (OK) mencakup bidang yang status menunjukkan status operasi. Jika operasi tidak selesai, nilainya status adalah running atau notStarted. Dalam kasus seperti itu, Anda harus memanggil API lagi, baik secara manual atau melalui skrip. Tunggu interval satu detik atau lebih di antara panggilan.

Respon sampel

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

Langkah berikutnya

  • Dalam mulai cepat ini, Anda mempelajari cara memanggil REST API untuk membuat penganalisis kustom. Untuk pengalaman pengguna, coba portal Azure AI Foundry.