Inicio rápido: API REST de clasificación de texto personalizada

Use este artículo para empezar a crear un proyecto de clasificación de texto personalizada en el que puede entrenar modelos personalizados para la clasificación de texto. Un modelo es software de IA entrenado para realizar una determinada tarea. Para este sistema, los modelos clasifican texto y se entrenan mediante el aprendizaje de datos etiquetados.

La clasificación de texto personalizada admite dos tipos de proyectos:

• Clasificación de etiqueta única: se puede asignar una sola clase a cada documento del conjunto de datos. Por ejemplo, un guión de película solo podría clasificarse como "Romance" o "Comedia".
• Clasificación mediante varias etiquetas: se pueden asignar varias clases a cada documento del conjunto de datos. Por ejemplo, un guión de película podría clasificarse como "Comedia" o "Romance" y "Comedia".

En este inicio rápido, puede usar los conjuntos de datos de ejemplo proporcionados para crear una clasificación de varias etiquetas para clasificar los scripts de películas en una o varias categorías. Como alternativa, puede usar un conjunto de datos de clasificación de etiquetas única para clasificar resúmenes de documentos científicos en uno de los dominios definidos.

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita.

Creación de un nuevo lenguaje de Azure en el recurso de Foundry Tools y la cuenta de almacenamiento de Azure

Para poder usar la clasificación de texto personalizada, deberá crear un recurso de lenguaje, que le proporcionará las credenciales que necesita para crear un proyecto e iniciar el entrenamiento de un modelo. También necesitará una cuenta de Almacenamiento de Azure, donde puede cargar el conjunto de datos que se usa en la creación del modelo.

Creación de un nuevo recurso en Azure Portal

1. Vaya a Azure Portal para crear un nuevo lenguaje de Azure en el recurso de Foundry Tools.

2. En la ventana que se abre, seleccione Clasificación de texto personalizado y reconocimiento de entidades con nombre personalizadas en las características personalizadas. Seleccione Continuar para crear el recurso en la parte inferior de la pantalla.

   

3. Cree un recurso de idioma con los detalles siguientes.

   Nombre	Valor requerido
   Suscripción	Su suscripción de Azure.
   Grupo de recursos	Grupo de recursos que contendrá su recurso. Puede elegir uno existente o crear uno.
   Región	Una de las regiones admitidas. Por ejemplo, "Oeste de EE. UU. 2".
   Nombre	Nombre del recurso.
   Plan de tarifa	Uno de los planes de tarifa admitidos. Puede usar el nivel de servicio Gratis (F0) para probar el servicio.

   Si recibe un mensaje que indica "la cuenta de inicio de sesión no es propietaria del grupo de recursos de la cuenta de almacenamiento seleccionada", la cuenta debe tener asignado un rol de propietario en el grupo de recursos para poder crear un recurso de idioma. Póngase en contacto con el propietario de la suscripción de Azure para obtener ayuda.

   Para determinar el propietario de la suscripción de Azure, busque en el grupo de recursos y siga el vínculo a su suscripción asociada. A continuación:

   1. Seleccione la pestaña Control de acceso (IAM).
   2. Seleccione Asignaciones de roles.
   3. Filtre por Role:Owner.

4. En la sección Clasificación de texto personalizado y reconocimiento de entidades con nombre personalizadas, seleccione una cuenta de almacenamiento existente o Nueva cuenta de almacenamiento. Cabe decir que estos valores son para ayudarle a empezar; no son necesariamente los valores de la cuenta de almacenamiento que querrá usar en entornos de producción. Para evitar la latencia durante la compilación del proyecto, conéctese a cuentas de almacenamiento en la misma región que el recurso de idioma.

   Valor de la cuenta de almacenamiento	Valor recomendado
   Nombre de la cuenta de almacenamiento	Cualquier nombre
   Tipo de cuenta de almacenamiento	LRS estándar

5. Asegúrese de que el Aviso de IA responsable esté activado. En la parte inferior de la página, seleccione Revisar y crear.

Carga de datos de ejemplo en el contenedor de blob

Después de crear una cuenta de Azure Storage y conectarla al recurso language, debe cargar los documentos del conjunto de datos de ejemplo en el directorio raíz del contenedor. Estos documentos se usan para entrenar el modelo.

Portal de Azure

1. En Azure Portal, vaya a la cuenta de almacenamiento que ha creado y selecciónela seleccionando Cuentas de almacenamiento y escribiendo el nombre de la cuenta de almacenamiento en Filtro para cualquier campo.

   Si el grupo de recursos no aparece, asegúrese de que el filtro Subscription equals (La suscripción es igual a) está establecido en Todo.

2. En la cuenta de almacenamiento, seleccione Contenedores en el menú de la izquierda, que se encuentra debajo de Almacenamiento de datos. En la pantalla que aparece, seleccione + Contenedor. Asigne al contenedor el nombre example-data y deje el Nivel de acceso público predeterminado.

   

3. Una vez creado el contenedor, selecciónelo. A continuación, seleccione el botón Cargar para seleccionar los archivos .txt y .json que descargó anteriormente.

   

Obtención de las claves de recursos y el punto de conexión

• Vaya a la página de información general del recurso en Azure Portal.

• En el menú de la izquierda, seleccione Claves y punto de conexión. El punto de conexión y la clave se usan para las solicitudes de API.

Crear un proyecto de clasificación de texto personalizado

Una vez configurados el recurso y el contenedor de almacenamiento, cree un nuevo proyecto de clasificación de texto personalizado. Un proyecto es un área de trabajo para compilar modelos de Machine Learning personalizados basados en los datos. Usted y otros usuarios que tienen acceso al recurso de lenguaje de Azure solo pueden acceder al proyecto.

Desencadenamiento del trabajo del proyecto de importación

Envíe una solicitud POST con la dirección URL, los encabezados y el cuerpo JSON que se incluyen a continuación para importar el archivo de etiquetas. Asegúrese de que el archivo de etiquetas siga el formato aceptado.

Si ya existe un proyecto con el mismo nombre, se reemplazan los datos de ese proyecto.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Cuerpo

Utilice el siguiente código JSON en la solicitud. Reemplace los valores de los marcadores de posición por sus propios valores.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

Una vez que envíe la solicitud de API, recibirá una 202 respuesta que indica que el trabajo se envió correctamente. En los encabezados de respuesta, extraiga el valor operation-location con el siguiente formato:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} se usa para identificar la solicitud, ya que esta operación es asincrónica. Utilice esta dirección URL para obtener el estado del trabajo de importación.

Posibles escenarios de error para esta solicitud:

• El recurso seleccionado no tiene los permisos adecuados para la cuenta de almacenamiento.
• El valor storageInputContainerName especificado no existe.
• Se ha usado un código de idioma no válido o si el tipo de código de idioma no es una cadena.
• El valor de multilingual es una cadena y no un valor booleano.

Obtención del estado del trabajo de importación

Use la siguiente solicitud GET para obtener el estado de la importación del proyecto. Reemplace los valores de los marcadores de posición por sus propios valores.

URL de la solicitud

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Entrenamiento de un modelo

Después de crear un proyecto, continúe y empiece a etiquetar los documentos que tiene en el contenedor conectado al proyecto. En este inicio rápido, ha importado un conjunto de datos etiquetado de ejemplo e inicializado el proyecto con el archivo de etiquetas JSON de ejemplo.

Inicio del entrenamiento del modelo

Una vez importado el proyecto, puede empezar a entrenar el modelo.

Envíe una solicitud POST mediante la dirección URL, los encabezados y el cuerpo JSON para enviar un trabajo de entrenamiento. Reemplace los valores de los marcadores de posición por sus propios valores.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Cuerpo de la solicitud

Use el siguiente código JSON en el cuerpo de la solicitud. El modelo se denominará {MODEL-NAME} una vez completado el entrenamiento. Solo los trabajos de entrenamiento correctos generarán modelos.

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}

Una vez que envíe la solicitud de API, recibirá una 202 respuesta que indica que el trabajo se envió correctamente. En los encabezados de respuesta, extraiga el valor location con el siguiente formato:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} se usa para identificar la solicitud, ya que esta operación es asincrónica. Puede usar esta dirección URL para obtener el estado del entrenamiento.

Obtén el estado del trabajo de entrenamiento

El entrenamiento puede tardar entre 10 y 30 minutos. Puede usar la siguiente solicitud para mantener el sondeo del estado del trabajo de entrenamiento hasta que se complete correctamente.

Use la siguiente solicitud GET para obtener el estado del proceso de entrenamiento del modelo. Reemplace los valores de los marcadores de posición por sus propios valores.

URL de la solicitud

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Cuerpo de la respuesta

Una vez que envíe la solicitud, obtendrá la siguiente respuesta.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Implementación del modelo

Por lo general, después de entrenar un modelo, revisaría sus detalles de evaluación y realizaría mejoras si fuera necesario. En este inicio rápido, solo implementará el modelo y estará a su disposición para que lo pruebe en Language Studio, o bien puede llamar a la API de predicción.

Enviar el trabajo de implementación

Envíe una solicitud PUT mediante la dirección URL, los encabezados y el cuerpo JSON para enviar un trabajo de implementación. Reemplace los valores de los marcadores de posición por sus propios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Cuerpo de la solicitud

Use el siguiente JSON en el cuerpo de la solicitud. Use el nombre del modelo que se va a asignar a la implementación.

{
  "trainedModelLabel": "{MODEL-NAME}"
}

Una vez que envíe la solicitud de API, recibirá una 202 respuesta que indica que el trabajo se envió correctamente. En los encabezados de respuesta, extraiga el valor operation-location con el siguiente formato:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} se usa para identificar la solicitud, ya que esta operación es asincrónica. Puede usar esta dirección URL para obtener el estado de la implementación.

Obtención del estado del trabajo de implementación

Use la siguiente solicitud GET para consultar el estado del trabajo de implementación. Puede usar la dirección URL que recibió en el paso anterior o reemplazar los valores de los marcadores de posición por sus propios valores.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Cuerpo de la respuesta

Una vez que envíe la solicitud, obtendrá la siguiente respuesta. Siga sondeando este punto de conexión hasta que el parámetro status cambie a "succeeded". Debe obtener un código 200 para indicar el éxito de la solicitud.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Clasificación de texto

Una vez implementado el modelo correctamente, puede empezar a usarlo para clasificar el texto mediante Prediction API. En el conjunto de datos de ejemplo que descargó anteriormente, puede encontrar algunos documentos de prueba que puede usar en este paso.

Enviar una tarea de clasificación de texto personalizado

Use esta solicitud POST para iniciar una tarea de clasificación de texto.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

encabezados

Cuerpo

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Respuesta

Recibe un código de estado HTTP 202 que indica éxito. En los encabezados de respuesta, extraigaoperation-location. operation-location tiene el formato siguiente:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Puede usar esta dirección URL para consultar el estado de finalización de la tarea y obtener los resultados cuando la tarea se complete.

Obtención de resultados de la tarea

Use la siguiente solicitud GET para consultar el estado o los resultados de la tarea de clasificación de texto.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

encabezados

Cuerpo de respuesta

La respuesta será un documento JSON con los parámetros siguientes.

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customMultiClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "classes": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

Limpieza de recursos

Cuando ya no necesite el proyecto, puede eliminarlo con la siguiente solicitud DELETE. Reemplace los valores de los marcadores de posición por sus propios valores.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

encabezados

Use el siguiente encabezado para autenticar la solicitud.

Una vez que envíe la solicitud de API, recibirá una 202 respuesta que indica que se ha realizado correctamente, lo que significa que se elimina el proyecto. Una llamada correcta devuelve un encabezado Operation-Location que se usa para comprobar el estado del trabajo.

Pasos siguientes

Después de crear un modelo de clasificación de texto personalizado, puede hacer lo siguiente:

• Uso de la API en tiempo de ejecución para clasificar texto

Cuando empiece a crear sus propios proyectos de clasificación de texto personalizado, use los artículos de procedimientos para obtener información detallada sobre el desarrollo del modelo:

• Selección de datos y diseño de esquemas
• Etiquetado de datos
• Entrenamiento de un modelo
• Visualización de la evaluación del modelo