Rychlý start: Azure AI Content Understanding REST API

Článek
11/23/2024

Začněte používat nejnovější verzi Preview rozhraní REST API služby Azure AI Content Understanding (2024-12-01-preview).
Azure AI Content Understanding je nová generující služba Azure AI založená na umělé inteligenci, která analyzuje soubory libovolného způsobu (dokumenty, obrázky, videa a zvuk) a extrahuje strukturovaný výstup v uživatelsky definovaných formátech polí.
Snadno integrujte službu Content Understanding do pracovních postupů a aplikací voláním našich rozhraní REST API.
Tento rychlý start vás provede používáním rozhraní REST API služby Content Understanding k vytvoření vlastního analyzátoru a extrakci obsahu a polí ze vstupu.

Požadavky

Abyste mohli začít, potřebujete aktivní předplatné Azure. Pokud nemáte účet Azure, můžete si vytvořit bezplatné předplatné.

Jakmile budete mít předplatné Azure, vytvořte prostředek azure AI Services na webu Azure Portal. Tento prostředek s více službami umožňuje přístup k více službám Azure AI s jedinou sadou přihlašovacích údajů.
- Tento prostředek je uvedený v části Služby Azure AI → služby Azure AI na portálu.
  
  Důležité
  
  Azure poskytuje více než jeden typ prostředku s názvem Služby Azure AI. Ujistěte se, že vyberete ten uvedený v části Služby Azure AI → služby Azure AI, jak je znázorněno na následujícím obrázku. Další informace najdete v tématu Vytvoření prostředku Azure AI Services.
V tomto rychlém startu používáme nástroj příkazového řádku cURL. Pokud není nainstalovaná, můžete si stáhnout verzi pro vývojové prostředí:
- Windows
- Mac nebo Linux

Vytvoření vlastního analyzátoru

Pokud chcete vytvořit vlastní analyzátor, musíte definovat schéma pole, které popisuje strukturovaná data, která chcete extrahovat. V následujícím příkladu definujeme schéma pro extrakci základních informací z dokumentu faktury.

Nejprve vytvořte soubor JSON s názvem request_body.json s následujícím obsahem:

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

Pokud chcete vytvořit vlastní analyzátor, musíte definovat schéma pole, které popisuje strukturovaná data, která chcete extrahovat. V následujícím příkladu definujeme schéma pro identifikaci zjištěných na obrázcích kovových plátů.

Nejprve vytvořte soubor JSON s názvem request_body.json s následujícím obsahem:

{
  "description": "Sample chart analyzer",
  "scenario": "image",
  "fieldSchema": {
    "fields": {
      "Title": {
        "type": "string"
      },
      "ChartType": {
        "type": "string",
        "method": "classify",
        "enum": [ "bar", "line", "pie" ]
      }
    }
  }
}

Nejprve vytvořte soubor JSON s názvem request_body.json s následujícím obsahem:

{
  "description": "Sample call transcript analyzer",
  "scenario": "callCenter",
  "config": {
    "returnDetails": true,
    "locales": ["en-US"]
  },
  "fieldSchema": {
    "fields": {
      "Summary": {
        "type": "string",
        "method": "generate"
      },
      "Sentiment": {
        "type": "string",
        "method": "classify",
        "enum": [ "Positive", "Neutral", "Negative" ]
      },
      "People": {
        "type": "array",
        "description": "List of people mentioned",
        "items": {
          "type": "object",
          "properties": {
            "Name": { "type": "string" },
            "Role": { "type": "string" }
          }
        }
      }
    }
  }
}

Nejprve vytvořte soubor JSON s názvem request_body.json s následujícím obsahem:

{
  "description": "Sample marketing video analyzer",
  "scenario": "videoShot",
  "fieldSchema": {
    "fields": {
      "Description": {
        "type": "string",
        "description": "Detailed summary of the video segment, focusing on product characteristics, lighting, and color palette."
      },
      "Sentiment": {
        "type": "string",
        "method": "classify",
        "enum": [ "Positive", "Neutral", "Negative" ]
      }
    }
  }
}

Před spuštěním následujících cURL příkazů proveďte následující změny požadavku HTTP:

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem nového analyzátoru a vytvořte, například myInvoice.

Požadavek 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

Odpověď PUT

Odpověď 201 (Created) obsahuje hlavičku Operation-Location obsahující adresu URL, kterou můžete použít ke sledování stavu této asynchronní operace vytvoření.

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

Po dokončení se vrátí příkaz HTTP GET na adrese URL "status": "succeeded".

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

Analýza souboru

Soubory můžete analyzovat pomocí vlastního analyzátoru, který jste vytvořili k extrahování polí definovaných ve schématu.

Před spuštěním příkazu cURL proveďte následující změny požadavku HTTP:

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem vlastního analyzátoru vytvořeného dříve.
Nahraďte {fileUrl} veřejně přístupnou adresou URL souboru k analýze, například cestu k objektu blob služby Azure Storage sdíleným přístupovým podpisem (SAS) nebo ukázkovou adresou URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem vlastního analyzátoru vytvořeného dříve.
Nahraďte {fileUrl} veřejně přístupnou adresou URL souboru, která se má analyzovat, například cestu k objektu blob služby Azure Storage sdíleným přístupovým podpisem (SAS).

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem vlastního analyzátoru vytvořeného dříve.
Nahraďte {fileUrl} veřejně přístupnou adresou URL souboru, která se má analyzovat, například cestu k objektu blob služby Azure Storage sdíleným přístupovým podpisem (SAS).

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem vlastního analyzátoru vytvořeného dříve.
Nahraďte {fileUrl} veřejně přístupnou adresou URL souboru, která se má analyzovat, například cestu k objektu blob služby Azure Storage sdíleným přístupovým podpisem (SAS).

Požadavek POST

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

Odpověď POST

Odpověď 202 (Accepted) obsahuje hlavičku Operation-Location obsahující adresu URL, kterou můžete použít ke sledování stavu této asynchronní operace analýzy.

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

Získání výsledku analýzy

resultId Použijte hlavičku Operation-Location vrácenou předchozí POST odpovědí a načtěte výsledek analýzy.

Nahraďte a {key} nahraďte {endpoint} hodnoty koncového bodu a klíče z vaší instance služby Azure AI Services na webu Azure Portal.
Nahraďte {analyzerId} názvem vlastního analyzátoru vytvořeného dříve.
Nahraďte {resultId} vrácenou resultId z POST požadavku.

Požadavek GET

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

Odpověď GET

Odpověď JSON 200 (OK) obsahuje status pole označující stav operace. Pokud operace není dokončená, hodnota status je running nebo notStarted. V takových případech byste měli rozhraní API volat znovu ručně nebo prostřednictvím skriptu. Počkejte interval jedné sekundy nebo více mezi voláními.

Ukázková odpověď

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

{
  "id": "12fd421b-b545-4d63-93a5-01284081bbe1",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_chart_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:41:00Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "![image](image)\n",
        "fields": {
          "Title": {
            "type": "string",
            "valueString": "Weekly Work Hours Distribution"
          },
          "ChartType": {
            "type": "string",
            "valueString": "pie"
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "width": 1283,
            "height": 617
          }
        ]
      }
    ]
  }
}

{
  "id": "247c369c-1aa5-4f92-b033-a8e4318e1c02",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_chart_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:42:58Z",
    "warnings": [],
    "contents": [
      {
        "kind": "audioVisual",
        "startTimeMs": 0,
        "endTimeMs": 32182,
        "markdown": "```WEBVTT\n\n00:00.080 --> 00:00.640\n<v Agent>Good day...",
        "fields": {
          "Sentiment": {
            "type": "string",
            "valueString": "Positive"
          },
          "Summary": {
            "type": "string",
            "valueString": "Maria Smith contacted Contoso to inquire about her current point balance. Agent John Doe confirmed her identity and informed her that she has 599 points. Maria did not require any further information and the call ended on a positive note."
          },
          "People": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Name": {
                    "type": "string",
                    "valueString": "Maria Smith"
                  },
                  "Role": {
                    "type": "string",
                    "valueString": "Customer"
                  }
                }
              }, ...
            ]
          }
        },
        "transcriptPhrases": [
          {
            "speaker": "Agent 1",
            "startTimeMs": 80,
            "endTimeMs": 640,
            "text": "Good day.",
            "confidence": 0.932,
            "words": [
              {
                "startTimeMs": 80,
                "endTimeMs": 280,
                "text": "Good"
              }, ...
            ],
            "locale": "en-US"
          }, ...
        ]
      }
    ]
  }
}

{
  "id": "204fb777-e961-4d6d-a6b1-6e02c773d72c",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_marketing_video_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:57:21Z",
    "warnings": [],
    "contents": [
      {
        "kind": "audioVisual",
        "startTimeMs": 0,
        "endTimeMs": 2800,
        "width": 540,
        "height": 960,
        "markdown": "# Shot 0:0.0 => 0:1.800\n\n## Transcript\n\n```\n\nWEBVTT\n\n0:0.80 --> 0:10.560\n<v Speaker>When I was planning my trip...",
        "fields": {
          "sentiment": {
            "type": "string",
            "valueString": "Neutral"
          },
          "description": {
            "type": "string",
            "valueString": "The video begins with a view from a glass floor, showing a person's feet in white sneakers standing on it. The scene captures a downward view of a structure, possibly a tower, with a grid pattern on the floor and a clear view of the ground below. The lighting is bright, suggesting a sunny day, and the colors are dominated by the orange of the structure and the gray of the floor."
          }
        }
      },
      ...
    ]
  }
}

Další kroky

V tomto rychlém startu jste zjistili, jak volat rozhraní REST API k vytvoření vlastního analyzátoru. Pro uživatelské prostředí zkuste portál Azure AI Foundry.

Sdílet prostřednictvím

Rychlý start: Azure AI Content Understanding REST API

Požadavky

Vytvoření vlastního analyzátoru

Požadavek PUT

Odpověď PUT

Analýza souboru

Požadavek POST

Odpověď POST

Získání výsledku analýzy

Požadavek GET

Odpověď GET

Ukázková odpověď

Další kroky

Váš názor

Další materiály