通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

通过 REST API 创建自定义分析器

内容理解分析器决定如何处理和提取信息。 它们可确保所有内容的统一处理和输出结构，以提供可靠且可预测的结果。 我们为常见用例提供 预生成分析器 。 本指南演示如何自定义这些分析器，以更好地满足你的需求。

本指南使用 cURL 命令行工具。 如果未安装，可以 下载 适用于开发环境的相应版本。

先决条件

要开始使用，请确保你拥有以下资源和权限：

  • 一份 Azure 订阅。 如果还没有 Azure 订阅，可以创建一个免费帐户。
  • 拥有 Azure 订阅后，请在 Azure 门户中创建 Microsoft Foundry 资源 。 请务必在 受支持的区域中创建它。
    • 此资源在门户中的“Foundry”>“Foundry”下列出。
  • 为内容理解资源设置默认模型部署。 默认设置将创建与用于内容理解请求的 Foundry 模型的连接。 选择下列方法之一：
    1. 转到 “内容理解设置”页
    2. 选择左上角的“+ 添加资源”按钮
    3. 选择要使用的 Foundry 资源，然后单击“下一步”，然后单击“保存”
      • 选中“如果没有可用的默认值，请确保为所需模型启用自动部署”。 确保资源已用所需的 GPT-4.1、GPT-4.1-mini 和 text-embedding-3-large 型模进行完整设置。 不同的预生成分析器需要不同的模型。
    通过执行这些步骤，可以在 Foundry 资源中设置内容理解模型和 Foundry 模型之间的连接。

定义分析器架构

若要创建自定义分析器，请定义描述要提取的结构化数据的字段架构。 在以下示例中，我们基于 预生成的文档分析器 创建分析器来处理收据。

创建包含以下内容的 JSON 文件 receipt.json ：

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

如果你需要处理各种类型的文档，但想要仅对收据进行分类和分析，则可以创建先对文档进行分类的分析器。 然后，使用以下架构将其路由到上面创建的分析器。

创建包含以下内容的 JSON 文件 categorize.json ：

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

}

创建分析器

PUT 请求

首先创建收据分析器，然后创建分类分析器。

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

PUT 响应

201 Created 响应包含一个 Operation-Location 标头，其中包含一个可用于跟踪此异步分析器创建操作状态的 URL。

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

完成后，对操作位置 URL 执行 HTTP GET 将返回"status": "succeeded"。

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

分析文件

发送文件

现在可以使用创建的自定义分析器来处理文件并提取架构中定义的字段。

在运行 cURL 命令之前，请对 HTTP 请求进行以下更改：

  1. 将{endpoint}和{key}替换为 Azure 门户 Foundry 实例中的终结点和密钥值。
  2. 将 {analyzerId} 替换为使用 categorize.json 文件创建的自定义分析器的名称。
  3. 将 {fileUrl} 替换为要分析的文件的可公开访问 URL，例如具有共享访问签名 (SAS) 或示例 URL https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png 的 Azure 存储 Blob 的路径。

POST 请求

此示例使用您借助categorize.json 文件创建的自定义分析器来分析收据。

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

POST 响应

响应 202 Accepted 包括 {resultId}，可用于跟踪此异步作的状态。

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

获取分析结果

使用 Operation-Location 响应中的 POST，并检索分析结果。

GET 请求

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

GET 响应

200 OK响应包含一个显示操作进度的status字段。

  • status 如果操作成功完成，则为 Succeeded。
  • 如果是running或notStarted，请手动或使用脚本再次调用 API：请求之间至少间隔一秒钟。
示例响应
{
  "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
    }
  }
}

后续步骤

  • Last updated on