Compartir a través de

Creación de un analizador personalizado mediante las API REST

Los analizadores de Content Understanding definen cómo procesar y extraer información del contenido. Garantizan un procesamiento uniforme y una estructura de salida en todo el contenido para ofrecer resultados confiables y predecibles. Ofrecemos analizadores creados previamente para casos de uso comunes. En esta guía se muestra cómo se pueden personalizar estos analizadores para adaptarlos mejor a sus necesidades.

En esta guía, usamos la herramienta de línea de comandos cURL. Si no está instalado, puede descargar la versión adecuada para su entorno de desarrollador.

Prerrequisitos

Antes de empezar, asegúrese de tener los siguientes recursos y permisos:

  • Una suscripción de Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita.
  • Una vez que tenga la suscripción de Azure, cree un Recurso de Microsoft Foundry en Azure Portal. Asegúrese de crearlo en una región admitida.
    • Este recurso aparece en Foundry>Foundry en el portal.
  • Configure las implementaciones de modelos predeterminadas para el recurso de Content Understanding. Al establecer los valores predeterminados, se crea una conexión a los modelos de Foundry que se utilizan para las solicitudes de Comprensión de Contenido. Elija uno de los métodos siguientes:
    1. Vaya a la página de configuración de Content Understanding.
    2. Seleccione el botón "+ Agregar recurso" en la esquina superior izquierda.
    3. Seleccione el recurso Foundry que desea usar y haga clic en Siguiente y, a continuación, en Guardar.
      • Asegúrese de dejar "Habilitar la implementación automática para los modelos necesarios si no hay ningún valor predeterminado disponible". Esto garantiza que el recurso esté totalmente configurado con los modelos GPT-4.1, GPT-4.1-mini y text-embeding-3-large necesarios. Los distintos analizadores creados previamente requieren modelos diferentes.
    Al realizar estos pasos, configurará una conexión entre los modelos de Comprensión de Contenidos y Foundry en el recurso Foundry.

Definición de un esquema de analizador

Para crear un analizador personalizado, defina un esquema de campo que describa los datos estructurados que desea extraer. En el ejemplo siguiente, creamos un analizador basado en el analizador de documentos precompilado para procesar una recepción.

Cree un archivo JSON denominado receipt.json con el siguiente contenido:

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

Si tiene varios tipos de documentos que necesita procesar, pero desea clasificar y analizar solo los recibos, puede crear un analizador que clasifique primero el documento. A continuación, enrútela al analizador que creó más arriba con el siguiente esquema.

Cree un archivo JSON denominado categorize.json con el siguiente contenido:

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

}

Creación de un analizador

Solicitud PUT

Cree primero un analizador de recibos y, a continuación, cree el analizador de categorías.

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

Respuesta PUT

La respuesta 201 Created incluye un Operation-Location encabezado que contiene una dirección URL que puede usar para realizar un seguimiento del estado de esta operación de creación asincrónica del analizador.

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

Tras la finalización, la realización de un HTTP GET en la dirección URL de ubicación de la operación devuelve "status": "succeeded".

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

Analizar un archivo

Enviar el archivo

Ahora puede usar el analizador personalizado que creó para procesar archivos y extraer los campos que definió en el esquema.

Antes de ejecutar el comando cURL, realice los cambios siguientes en la solicitud HTTP:

  1. Reemplace {endpoint} y {key} por los valores de punto de conexión y clave de la instancia de Azure Portal Foundry.
  2. Reemplace por {analyzerId} el nombre del analizador personalizado que creó con el categorize.json archivo .
  3. Reemplace {fileUrl} por una dirección URL de acceso público del archivo que se va a analizar, como una ruta de acceso a un Azure Storage Blob con una firma de acceso compartido (SAS) o la dirección URL de ejemplo https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

Solicitud POST

En este ejemplo se usa el analizador personalizado que creó con el categorize.json archivo para analizar un recibo.

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

Respuesta de POST

La 202 Accepted respuesta incluye el {resultId} que puede usar para realizar el seguimiento del estado de esta operación asincrónica.

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

Obtención del resultado de análisis

Utilice el Operation-Location de la respuesta POST para recuperar el resultado del análisis.

Solicitud GET

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

Respuesta GET

Una 200 OK respuesta incluye un status campo que muestra el progreso de la operación.

  • status es Succeeded si la operación se ha completado correctamente.
  • Si es running o notStarted, vuelva a llamar a la API manualmente o con un script: espere al menos un segundo entre solicitudes.
Respuesta de ejemplo
{
  "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
    }
  }
}

Contenido relacionado

  • Last updated on