Configuración del análisis

Para analizar la explicabilidad y el sesgo de sus datos y modelos con Clarify, debe configurar un trabajo de procesamiento. SageMaker Parte de la configuración de este trabajo de procesamiento incluye la configuración de un archivo de análisis. El archivo de análisis especifica los parámetros para el análisis de sesgos y la explicabilidad. Consulte Configurar un trabajo de SageMaker procesamiento de Clarify para obtener información sobre cómo configurar un trabajo de procesamiento y un archivo de análisis.

Esta guía describe el esquema y los parámetros de este archivo de configuración de análisis. Esta guía también incluye ejemplos de archivos de configuración de análisis para calcular las métricas de sesgo de un conjunto de datos tabular y generar explicaciones sobre problemas de procesamiento de lenguaje natural (NLP) y visión artificial (CV).

Puede crear el archivo de configuración del análisis o usar el SDK de SageMaker Python para generar uno para usted con la SageMaker ClarifyProcessorAPI. Ver el contenido del archivo puede resultar útil para comprender la configuración subyacente que utiliza el trabajo de SageMaker Clarify.

Esquema del archivo de configuración de análisis

En la siguiente sección se describe el esquema del archivo de configuración de análisis, incluidos los requisitos y las descripciones de los parámetros.

Requisitos del archivo de configuración de análisis

El trabajo SageMaker de procesamiento de Clarify espera que el archivo de configuración del análisis esté estructurado con los siguientes requisitos:

• El nombre de la entrada de procesamiento debe ser analysis_config.

• El archivo de configuración de análisis está en formato JSON y está codificado en UTF-8.

• El archivo de configuración de análisis es un objeto de Amazon S3.

Puede especificar parámetros adicionales en el archivo de configuración de análisis. La siguiente sección proporciona varias opciones para adaptar el trabajo de procesamiento SageMaker de Clarify a su caso de uso y a los tipos de análisis deseados.

Parámetros para los archivos de configuración de análisis

Puede especificar parámetros adicionales en el archivo de configuración de análisis.

• version: (opcional) la cadena de versión del esquema del archivo de configuración de análisis. Si no se proporciona una versión, SageMaker Clarify utiliza la última versión compatible. Actualmente, solo se admite la versión 1.0.

• dataset_type: el formato del conjunto de datos. El formato del conjunto de datos de entrada puede ser cualquiera de los siguientes valores:

  • text/csv para CSV

  • application/jsonlinespara el SageMaker formato denso de líneas JSON

  • application/json para JSON

  • application/x-parquet para Apache Parquet

  • application/x-image para activar la explicabilidad de los problemas de visión artificial

• dataset_uri: (opcional) el identificador uniforme de recursos (URI) del conjunto de datos principal. Si proporciona un prefijo URI de S3, el trabajo de procesamiento de SageMaker Clarify recopila de forma recursiva todos los archivos S3 ubicados debajo del prefijo. Si tiene problemas de visión artificial, puede proporcionar un prefijo URI de S3 o un URI de S3 a un archivo de manifiesto de imagen. Si se proporciona dataset_uri, tiene prioridad sobre la entrada del trabajo de procesamiento del conjunto de datos. Para cualquier tipo de formato, excepto la imagen, el trabajo de procesamiento SageMaker Clarify carga el conjunto de datos de entrada en un marco de datos tabular, como un conjunto de datos tabular. Este formato permite manipular y SageMaker analizar fácilmente el conjunto de datos de entrada.

• headers: (opcional) una matriz de cadenas que contiene los nombres de las columnas de un conjunto de datos tabular. Si no headers se proporciona un valor para, el trabajo de procesamiento de SageMaker Clarify lee los encabezados del conjunto de datos. Si el conjunto de datos no tiene encabezados, el trabajo de procesamiento de SageMaker Clarify generará automáticamente los nombres de los marcadores de posición basados en el índice de columnas de base cero. Por ejemplo, los nombres de los marcadores de posición para la primera y la segunda columnas serán column_0, column_1.

  nota

  Por convención, si dataset_type es application/jsonlines o application/json, entonces headers debe contener los siguientes nombres en orden: nombres de características, nombre de etiqueta (si se especifica label) y nombre de etiqueta predicha (si se especifica predicted_label). Un ejemplo de headers para un conjunto de datos application/jsonlines si label está especificado es: ["feature1","feature2","feature3","target_label"].

• label: (opcional) una cadena o un índice entero basado en cero. Si se proporciona, label se utiliza para localizar la etiqueta de verdad fundamental, también conocida como etiqueta observada o atributo objetivo en un conjunto de datos tabular. La etiqueta de verdad fundamental se utiliza para calcular las métricas de sesgo. El valor de label se especifica en función del valor del parámetro dataset_type de la siguiente manera.

  • Si dataset_type es text/csv, label se puede especificar de la siguiente manera:

    • Un nombre de columna válido

    • Un índice que se encuentra dentro del rango de columnas del conjunto de datos

  • Si dataset_type es application/parquet, label debe ser un nombre de columna válido.

  • Si dataset_type es application/jsonlines, label debe ser una expresión JMESPath escrita para extraer la etiqueta de verdad fundamental del conjunto de datos. Por convención, si se especifica headers, debe contener el nombre de la etiqueta.

  • Si dataset_type es application/json, label debe ser una expresión JMESPath escrita para extraer la etiqueta de verdad fundamental de cada registro del conjunto de datos. Esta expresión JMESPath debe generar una lista de etiquetas donde la etiqueta i^ésima se correlacione con el registro i^ésimo.

• predicted_label: (opcional) una cadena o un índice entero basado en cero. Si se proporciona, predicted_label se usa para ubicar la columna que contiene la etiqueta predicha en un conjunto de datos tabular. La etiqueta predicha se usa para calcular las métricas de sesgo posteriores al entrenamiento. El parámetro predicted_label es opcional si el conjunto de datos no incluye la etiqueta predicha. Si se requieren etiquetas pronosticadas para el cálculo, el trabajo de procesamiento de SageMaker Clarify obtendrá las predicciones del modelo.

  El valor de predicted_label se especifica en función del valor de dataset_type de la siguiente manera.

  • Si dataset_type es text/csv, predicted_label se puede especificar de la siguiente manera:

    • Un nombre de columna válido. Si se especifica predicted_label_dataset_uri, pero no se proporciona predicted_label, el nombre de etiqueta predicha predeterminado es “predicted_label”.

    • Un índice que se encuentra dentro del rango de columnas del conjunto de datos. Si se especifica predicted_label_dataset_uri, el índice se usa para localizar la columna de la etiqueta predicha en el conjunto de datos de la etiqueta predicha.

  • Si dataset_type es application/x-parquet, predicted_label debe ser un nombre de columna válido.

  • Si dataset_type es application/jsonlines, predicted_label debe ser una expresión JMESPath válida escrita para extraer la etiqueta predicha del conjunto de datos. Por convención, si se especifica headers, debe contener el nombre de la etiqueta predicha.

  • Si dataset_type es application/json, predicted_label debe ser una expresión JMESPath escrita para extraer la etiqueta predicha de cada registro del conjunto de datos. La expresión JMESPath debe producir una lista de etiquetas predichas donde la etiqueta predicha i^ésima es para el registro i^ésimo.

• features: se requiere si dataset_type es application/jsonlines o application/json. Expresión de cadena JMESPath escrita para localizar las entidades en el conjunto de datos de entrada. Para application/jsonlines, se aplicará una expresión JMESPath a cada línea para extraer las características de ese registro. Para application/json, se aplicará una expresión JMESPath a todo el conjunto de datos de entrada. La expresión JMESPath debe extraer una lista de listas o un conjunto o matriz 2D de características en la que la fila i^ésima contenga las características que se correlacionan con el registro i^ésimo. En el caso dataset_type de text/csv o application/x-parquet, todas las columnas, excepto las columnas de la etiqueta de verdad fundamental y de la etiqueta predicha, se asignan automáticamente como características.

• predicted_label_dataset_uri: solo se aplica cuando dataset_type es text/csv. El URI de S3 de un conjunto de datos que contiene etiquetas predichas que se utiliza para calcular las métricas de sesgo posteriores al entrenamiento. El trabajo SageMaker de procesamiento de Clarify cargará las predicciones del URI proporcionado en lugar de obtener las predicciones del modelo. En este caso, predicted_label tiene que ubicar la columna de etiquetas predichas en el conjunto de datos de etiquetas predichas. Si el conjunto de datos de etiquetas predichas o el conjunto de datos principal está divididos en varios archivos, joinsource_name_or_index debe especificar una columna de identificación para unir los dos conjuntos de datos.

• predicted_label_headers: solo se aplica cuando se especifica predicted_label_dataset_uri. Una matriz de cadenas que contiene los nombres de columna del conjunto de datos de etiquetas predichas. Además del encabezado de etiqueta predicha, predicted_label_headers también puede contener el encabezado de la columna de identificación para unir el conjunto de datos de etiquetas predichas y el conjunto de datos principal. Para obtener más información, consulte la siguiente descripción del parámetro joinsource_name_or_index.

• joinsource_name_or_index: el nombre o el índice de base cero de la columna en los conjuntos de datos tabulares que se utilizará como columna de identificación al realizar una unión interna. Esta columna solo se usa como un identificador. No se utiliza para ningún otro cálculo, como el análisis de sesgo o el análisis de atribución de características. Se necesita un valor para joinsource_name_or_index en los siguientes casos:

  • Hay varios conjuntos de datos de entrada y alguno de ellos está dividido en varios archivos.

  • El procesamiento distribuido se activa al establecer el trabajo SageMaker de procesamiento de Clarify en un valor superior InstanceCounta1.

• excluded_columns: (opcional) una matriz de nombres o índices de columna de base cero que se excluirán del envío al modelo como entrada para las predicciones. La etiqueta de verdad fundamental y la etiqueta predicha ya se excluyeron automáticamente.

• probability_threshold: (opcional) un número de coma flotante por encima del cual se selecciona una etiqueta o un objeto. El valor predeterminado es 0.5. El trabajo SageMaker de procesamiento de Clarify probability_threshold se utiliza en los siguientes casos:

  • En el análisis de sesgo posterior al entrenamiento, probability_threshold convierte la predicción de un modelo numérico (valor de probabilidad o puntuación) en una etiqueta binaria, si el modelo es un clasificador binario. Una puntuación superior al umbral se convierte en 1. Mientras que una puntuación inferior o igual al umbral se convierte en 0.

  • En los problemas de explicabilidad de la visión artificial, si model_type es OBJECT_DETECTION, , probability_threshold filtra los objetos detectados con puntuaciones de confianza inferiores al valor umbral.

• label_values_or_threshold: obligatorio para el análisis de sesgos. Una matriz de valores de etiqueta o un número umbral, que indican un resultado positivo para etiquetas de verdad fundamental y predichas para las métricas de sesgo. Para obtener más información, consulte los valores de etiqueta positivos enAmazon SageMaker aclara los términos de sesgo y equidad. Si la etiqueta es numérica, el umbral se aplica como límite inferior para seleccionar el resultado positivo. Para configurar label_values_or_threshold para distintos tipos de problemas, consulte los siguientes ejemplos:

  • Para un problema de clasificación binaria, la etiqueta tiene dos valores posibles: 0 y 1. Si el valor de la etiqueta 1 es favorable para un grupo demográfico observado en una muestra, label_values_or_threshold debe establecerse en [1].

  • Para un problema de clasificación multiclase, la etiqueta tiene tres valores posibles: bird, cat y dog. Si los dos últimos definen un grupo demográfico que el sesgo favorece, entonces label_values_or_threshold debe configurarse en ["cat","dog"].

  • En el caso de un problema de regresión, el valor de la etiqueta es continuo y oscila entre 0 y 1. Si un valor superior a 0.5 debe designar una muestra como de resultado positivo, entonces label_values_or_threshold debe establecerse en 0.5.

• facet: se requiere para el análisis de sesgos. Una matriz de objetos facetados, que se componen de atributos sensibles con los que se mide el sesgo. Puede utilizar las facetas para comprender las características de sesgo del conjunto de datos y el modelo, incluso si el modelo se ha entrenado sin utilizar atributos sensibles. Para obtener más información, consulte Facet inAmazon SageMaker aclara los términos de sesgo y equidad. Este objeto de faceta incluye los siguientes campos:

  • name_or_index: nombre o índice basado en cero de la columna de atributos sensibles de un conjunto de datos tabular. Si se especifica facet_dataset_uri, el índice se refiere al conjunto de datos de facetas en lugar del conjunto de datos principal.

  • value_or_threshold: obligatorio (si facet es numérico y se aplica label_values_or_threshold como límite inferior para seleccionar el grupo sensible). Una matriz de valores de faceta o un número umbral que indica el grupo demográfico sensible que el sesgo favorece. Si el tipo de datos de faceta es categórico y no se proporciona value_or_threshold, las métricas de sesgo se calculan como un grupo para cada valor único (en lugar de todos los valores). Para configurar value_or_threshold para distintos tipos de datos de facet, consulte los siguientes ejemplos:

    • Para un tipo de datos de faceta binarios, la característica tiene dos valores posibles: 0 y 1. Si desea calcular las métricas de sesgo para cada valor, puede omitir value_or_threshold o establecer una matriz vacía.

    • Para un tipo de datos de faceta categóricos, la característica tiene tres valores posibles: bird, cat y dog. Si los dos primeros definen un grupo demográfico que el sesgo favorece, entonces value_or_threshold debe configurarse en ["bird", "cat"]. En este ejemplo, las muestras del conjunto de datos se dividen en dos grupos demográficos. La faceta del grupo favorecido tiene un valor bird o cat, mientras que la faceta del grupo desfavorecido tiene el valor dog.

    • En el caso de un tipo de datos de faceta numéricos, el valor de la característica es continuo y oscila entre 0 y 1. Por ejemplo, si un valor superior a 0.5 debe designar una muestra como de resultado positivo, entonces value_or_threshold debe establecerse en 0.5. En este ejemplo, las muestras del conjunto de datos se dividen en dos grupos demográficos. La faceta del grupo favorecido tiene un valor superior a 0.5, mientras que la faceta del grupo desfavorecido tiene un valor inferior o igual a 0.5.

• group_variable: el nombre o índice de base cero de la columna que indica el subgrupo que se utilizará para la métrica de sesgo o. Disparidad demográfica condicional (CDD) Disparidad demográfica condicional en las etiquetas predichas (CDDPL)

• facet_dataset_uri: solo se aplica cuando dataset_type es text/csv. El URI de S3 de un conjunto de datos que contiene atributos sensibles para el análisis de sesgos. Puede utilizar las facetas para comprender las características de sesgo del conjunto de datos y el modelo, incluso si el modelo se ha entrenado sin utilizar atributos sensibles.

  nota

  Si el conjunto de datos de la faceta o el conjunto de datos principal está divididos en varios archivos, joinsource_name_or_index debe especificar una columna de identificación para unir los dos conjuntos de datos. Debe usar el parámetro facet para identificar cada faceta del conjunto de datos de facetas.

• facet_headers: (solo se aplica cuando se especifica facet_dataset_uri). Una matriz de cadenas que contiene los nombres de la columna del conjunto de datos de la faceta y, opcionalmente, el encabezado de la columna de identificación para unir el conjunto de datos de facetas y el conjunto de datos principal. Consulte joinsource_name_or_index.

• methods: un objeto que contiene uno o más métodos de análisis y sus parámetros. Si se omite algún método, no se utiliza para el análisis ni se informa.

  • pre_training_bias: incluya este método si quiere calcular las métricas de sesgo previas al entrenamiento. La descripción detallada de las métricas se encuentra en. Medición del sesgo previo al entrenamiento El objeto tiene los siguientes parámetros:

    • methods: una matriz que contiene cualquiera de las métricas de sesgo previas al entrenamiento de la siguiente lista que quiera calcular. Establezca methods en all para calcular todas las métricas de sesgo previas al entrenamiento. Por ejemplo, la matriz ["CI", "DPL"] calculará el Desequilibrio de clases y la Diferencia en las proporciones de las etiquetas.

      • CI para Desequilibrio de clases (CI)

      • DPL para Diferencia en las proporciones de las etiquetas (DPL)

      • KL para Divergencia de Kullback-Leibler (KL)

      • JS para Divergencia de Jensen-Shannon (JS)

      • LP para Norma Lp (LP)

      • TVD para Distancia de variación total (TVD)

      • KS para Kolmogorov-Smirnov (KS)

      • CDDL para Disparidad demográfica condicional (CDD)

  • pre_training_bias: incluya este método si quiere calcular las métricas de sesgo posteriores al entrenamiento. La descripción detallada de las métricas se encuentra enMedición del sesgo de los datos posteriores al entrenamiento y el modelo. El objeto post_training_bias tiene los siguientes parámetros:

    • methods: una matriz que contiene cualquiera de las métricas de sesgo posteriores al entrenamiento de la siguiente lista que quiera calcular. Establezca methods en all para calcular todas las métricas de sesgo posteriores al entrenamiento. Por ejemplo, la matriz ["DPPL", "DI"] calcula la Diferencia en las proporciones positivas de las etiquetas predichas y el Impacto dispar. Los métodos disponibles son los siguientes.

      • DPPL para Diferencia en las proporciones positivas de las etiquetas predichas (DPPL)

      • DIpara Impacto dispar (DI)

      • DCA para Diferencia en aceptación condicional (DCAcc)

      • DCR para Diferencia en rechazo condicional (DCR)

      • SD para Diferencia de especificidad (SD)

      • RD para Diferencia de coincidencias (RD)

      • DAR para Diferencia en tasas de aceptación (DAR)

      • DRR para Diferencia en tasas de rechazo (DRR)

      • AD para Diferencia de precisión (AD)

      • TE para Igualdad de tratamiento (TE)

      • CDDPL para Disparidad demográfica condicional en las etiquetas predichas (CDDPL)

      • FT para Prueba de contrafácticos (FT)

      • GE para Entropía generalizada (GE)

  • shap: incluya este método si desea calcular los valores SHAP. El trabajo SageMaker de procesamiento Clarify es compatible con el algoritmo SHAP del núcleo. El objeto shap tiene los siguientes parámetros:

    • línea base: (opcional) el conjunto de datos de referencia de SHAP, también conocido como conjunto de datos de fondo. Los requisitos adicionales para el conjunto de datos de referencia en un conjunto de datos tabular o un problema de visión artificial son los siguientes. Para obtener más información sobre las líneas base de SHAP, consulte Referencias SHAP para la explicabilidad

      • En el caso de un conjunto de datos tabular, baseline puede ser los datos de referencia in situ o el URI de S3 de un archivo de referencia. Si no baseline se proporciona, el trabajo de procesamiento de SageMaker Clarify calcula una línea base agrupando el conjunto de datos de entrada. La referencia debe cumplir los siguientes requisitos:

        • El formato debe ser el mismo que el formato del conjunto de datos especificado por dataset_type.

        • La referencia solo puede contener características que el modelo pueda aceptar como entrada.

        • El conjunto de datos de referencia puede tener una o más instancias. La cantidad de instancias de referencia afecta directamente al tamaño del conjunto de datos sintético y al tiempo de ejecución del trabajo.

        • Si se especifica text_config, el valor de referencia de una columna de texto es una cadena que se utiliza para reemplazar la unidad de texto especificada por granularity. Por ejemplo, un marcador de posición frecuente es “[MASK]”, que se utiliza para representar una palabra o un fragmento de texto desconocido o ausente.

        En los siguientes ejemplos se muestra cómo configurar datos de referencia in situ para diferentes parámetros dataset_type:

        • Si dataset_type es text/csv o application/x-parquet, el modelo acepta cuatro características numéricas y la referencia tiene dos instancias. En este ejemplo, si un registro tiene todos los valores de característica cero y el otro registro tiene todos los valores de característica uno, entonces la referencia debe establecerse en [[0,0,0,0],[1,1,1,1]], sin ningún encabezado.

        • Si dataset_type es application/jsonlines, y features es la clave de una lista de cuatro valores de característica numéricos. Además, en este ejemplo, si la referencia tiene un registro con todos los valores cero, entonces baseline debe ser [{"features":[0,0,0,0]}].

        • Si dataset_type es application/json, el conjunto de datos baseline debe tener la misma estructura y formato que el conjunto de datos de entrada.

      • En el caso de problemas de visión artificial, baseline puede ser el URI de S3 de una imagen que se utiliza para ocultar las características (segmentos) de la imagen de entrada. El trabajo SageMaker de procesamiento Clarify carga la imagen de la máscara y cambia su tamaño a la misma resolución que la imagen de entrada. Si no se proporciona una línea base, el trabajo SageMaker de procesamiento Clarify genera una imagen de máscara de ruido blanco con la misma resolución que la imagen de entrada.

    • features_to_explain: (opcional) una matriz de cadenas o índices de base cero de columnas de características para calcular los valores SHAP. Si no se proporciona features_to_explain, los valores SHAP se calculan para todas las columnas de características. Estas columnas de características no pueden incluir la columna de etiquetas ni la columna de etiquetas predichas. El parámetro features_to_explain solo se admite para conjuntos de datos tabulares con columnas numéricas y categóricas.

    • num_clusters: (opcional) el número de clústeres en los que se divide el conjunto de datos para calcular el conjunto de datos de referencia. Cada clúster se usa para calcular una instancia de referencia. Si no baseline se especifica, el trabajo de SageMaker procesamiento de Clarify intenta calcular el conjunto de datos de referencia dividiendo el conjunto de datos tabular en un número óptimo de clústeres entre 1 y12. El número de instancias de referencia afecta directamente al tiempo de ejecución del análisis SHAP.

    • num_samples: (opcional) el número de muestras que se utilizarán en el algoritmo Kernel SHAP. Si no num_samples se proporciona, el trabajo de procesamiento SageMaker de Clarify elige el número por usted. La cantidad de muestras afecta directamente al tamaño del conjunto de datos sintético y al tiempo de ejecución del trabajo.

    • seed: (opcional) un número entero que se utiliza para inicializar el generador de números pseudoaleatorios del explicador SHAP a fin de generar valores SHAP coherentes para el mismo trabajo. Si no se especifica la semilla, cada vez que se ejecute el mismo trabajo, el modelo puede generar valores SHAP ligeramente diferentes.

    • use_logit: (opcional) un valor booleano que indica que desea que la función logit se aplique a las predicciones del modelo. El valor predeterminado es false. Si use_logit es true, los valores SHAP se calculan mediante los coeficientes de regresión logística, que se pueden interpretar como coeficientes logarítmicos de probabilidades.

    • save_local_shap_values: (opcional) un valor booleano que indica que desea que los valores SHAP locales de cada registro del conjunto de datos se incluyan en el resultado del análisis. El valor predeterminado es false.

      Si el conjunto de datos principal está dividido en varios archivos o si está activado el procesamiento distribuido, especifique también una columna de identificación mediante el parámetro joinsource_name_or_index. La columna de identificación y los valores SHAP locales se guardan en el resultado del análisis. De esta forma, puede asignar cada registro a sus valores SHAP locales.

    • agg_method: (opcional) el método utilizado para agregar los valores SHAP locales (los valores SHAP de cada instancia) de todas las instancias a los valores SHAP globales (los valores SHAP de todo el conjunto de datos). El valor predeterminado es mean_abs. Se pueden usar los siguientes métodos para agregar valores SHAP.

      • mean_abs: la media de los valores SHAP locales absolutos de todas las instancias.

      • mean_sq: la media de los valores SHAP locales al cuadrado de todas las instancias.

      • median: la mediana de los valores SHAP locales de todas las instancias.

    • text_config: obligatorio para la explicabilidad del procesamiento del lenguaje natural. Incluya esta configuración si desea tratar las columnas de texto como texto y se deben proporcionar explicaciones para cada unidad de texto. Para ver un ejemplo de una configuración de análisis para explicar el procesamiento del lenguaje natural, consulte Configuración del análisis para la explicabilidad del procesamiento de lenguaje natural

      • granularity: la unidad de granularidad para el análisis de las columnas de texto. Los valores válidos son token, sentence o paragraph. Cada unidad de texto se considera una característica y los valores SHAP locales se calculan para cada unidad.

      • language: el idioma de las columnas de texto. Los valores válidos son chinese, danish, dutch, english, french, german, greek, italian, japanese, lithuanian, multi-language, norwegian bokmål, polish, portuguese, romanian, russian, spanish, afrikaans, albanian, arabic, armenian, basque, bengali, bulgarian, catalan, croatian, czech, estonian, finnish, gujarati, hebrew, hindi, hungarian, icelandic, indonesian, irish, kannada, kyrgyz, latvian, ligurian, luxembourgish, macedonian, malayalam, marathi, nepali, persian, sanskrit, serbian, setswana, sinhala, slovak, slovenian, swedish, tagalog, tamil, tatar, telugu, thai, turkish, ukrainian, urdu, vietnamese, yoruba. Ingrese multi-language para obtener una combinación de varios idiomas.

      • max_top_tokens: (opcional) el número máximo de tokens principales, en función de los valores SHAP globales. El valor predeterminado es 50. Es posible que un token aparezca varias veces en el conjunto de datos. El trabajo SageMaker de procesamiento de Clarify agrega los valores de SHAP de cada token y, a continuación, selecciona los principales tokens en función de sus valores de SHAP globales. Los valores SHAP globales de los principales tokens seleccionados se incluyen en la sección global_top_shap_text del archivo analysis.json.

      • El valor SHAP local de agregación.

    • image_config: necesario para la explicabilidad de la visión artificial. Incluya esta configuración si tiene un conjunto de datos de entrada compuesto por imágenes y desea analizarlas para determinar su explicabilidad en un problema de visión artificial.

      • model_type: el tipo de modelo. Los valores válidos son:

        • IMAGE_CLASSIFICATION para un modelo de clasificación de imágenes.

        • OBJECT_DETECTION para un modelo de detección de objetos.

      • max_objects: solo se aplica cuando el tipo de modelo es OBJECT_DETECTION. El número máximo de objetos, ordenados por la puntuación de confianza, detectados por el modelo de visión artificial. Se filtran todos los objetos clasificados por debajo de max_objects según su puntuación máxima de confianza. El valor predeterminado es 3.

      • context: solo se aplica cuando model_type es OBJECT_DETECTION. Indica si el área alrededor del cuadro delimitador del objeto detectado está enmascarada por la imagen de referencia o no. Los valores válidos son 0 para enmascararlo todo o 1 para no enmascarar nada. El valor predeterminado es 1.

      • iou_threshold: solo se aplica cuando model_type es OBJECT_DETECTION. La métrica de intersección mínima sobre la unión (IOU) para evaluar las predicciones en función de la detección original. Una métrica de IOU alta corresponde a una gran superposición entre el cuadro de detección de la verdad predicha y el cuadro de detección de la verdad fundamental. El valor predeterminado es 0.5.

      • num_segments: (opcional) un entero que determina el número aproximado de segmentos que se etiquetarán en la imagen de entrada. Cada segmento de la imagen se considera una característica y los valores SHAP locales se calculan para cada segmento. El valor predeterminado es 20.

      • segment_compactness: (opcional) un entero que determina la forma y el tamaño de los segmentos de la imagen generados por el método scikit-image slic. El valor predeterminado es 5.

  • pdp: incluya este método para calcular las gráficas de dependencia parcial (PDP). Para ver un ejemplo de una configuración de análisis para generar PDP, consulte Cálculo de los gráficos de dependencia parcial (PDP)

    • features: obligatorio si no se solicita el método shap. Una matriz de nombres o índices de características para calcular y trazar gráficos PDP.

    • top_k_features: (opcional) especifica el número de características principales que se utilizan para generar los gráficos PDP. Si no features se proporciona, pero se solicita el shap método, el trabajo de procesamiento de SageMaker Clarify elige las características principales en función de sus atribuciones de SHAP. El valor predeterminado es 10.

    • grid_resolution: el número de buckets en los que se va a dividir el rango de valores numéricos. Esto especifica la granularidad de la cuadrícula de los gráficos PDP.

  • report: (opcional) utilice este objeto para personalizar el informe de análisis. Hay tres copias del mismo informe como parte del resultado del análisis: el informe de cuaderno de Jupyter, el informe HTML y el informe en PDF. El objeto tiene los siguientes parámetros:

    • name: nombre de archivo de los archivos del informe. Por ejemplo, si name es MyReport, los archivos del informe son MyReport.ipynb, MyReport.html y MyReport.pdf. El valor predeterminado es report.

    • title: (opcional) cadena de título del informe. El valor predeterminado es SageMaker Analysis Report.

• predictor: obligatorio si el análisis requiere predicciones del modelo. Por ejemplo, cuando se solicita el método shap, pdp o post_training_bias, pero las etiquetas predichas no se proporcionan como parte del conjunto de datos de entrada. Los siguientes son parámetros que se deben usar junto conpredictor:

  • model_name: el nombre del SageMaker modelo creado por la API. CreateModel Si especificas endpoint_name model_name en lugar de endpoint_name, el trabajo de SageMaker procesamiento de Clarify crea un punto final efímero con el nombre del modelo, conocido como punto final oculto, y obtiene las predicciones del punto final. El trabajo elimina el punto de conexión de sombra una vez finalizados los cálculos. Si el modelo es multimodelo, se debe especificar el parámetro. target_model Para obtener más información sobre los puntos finales multimodelo, consulte. Alojar varios modelos en un contenedor detrás de un punto de conexión

  • endpoint_name_prefix: (opcional) un prefijo de nombre personalizado para el punto de conexión de sombra. Aplicable si proporciona model_name en lugar de endpoint_name. Por ejemplo, proporcione endpoint_name_prefix si desea restringir el acceso al punto de conexión por nombre de punto de conexión. El prefijo debe coincidir con el EndpointNamepatrón y su longitud máxima es. 23 El valor predeterminado es sm-clarify.

  • initial_instance_count: especifica el número de instancias del punto de conexión de sombra. Se requiere si se proporciona model_name en lugar de endpoint_name. El valor de initial_instance_count puede ser diferente al InstanceCountdel trabajo, pero recomendamos una proporción de 1:1.

  • instance_type: especifica el tipo de instancia del punto de conexión de sombra. Se requiere si se proporciona model_name en lugar de endpoint_name. Por ejemplo, instance_type se puede configurar en “ml.m5.large”. En algunos casos, el valor especificado para instance_type puede ayudar a reducir el tiempo de inferencia del modelo. Por ejemplo, para funcionar de manera eficiente, los modelos de procesamiento de lenguaje natural y los modelos de visión artificial suelen requerir un tipo de instancia de unidad de procesamiento de gráficos (GPU).

  • accelerator_type: (opcional) especifica el tipo de acelerador de Elastic Inference (EI) que se va a conectar al punto de conexión de sombra. Aplicable si proporciona model_name en lugar de endpoint_name para accelerator_type. Un valor de ejemplo para accelerator_type es ml.eia2.large. El valor predeterminado es no utilizar un acelerador.

  • endpoint_name: el nombre del SageMaker punto final creado por la API. CreateEndpoint Si se proporciona, endpoint_name tiene prioridad sobre el parámetro model_name. El uso de un punto de conexión existente reduce el tiempo de arranque del punto de conexión de sombra, pero también puede provocar un aumento significativo de la carga de ese punto de conexión. Además, algunos métodos de análisis (como shap y pdp) generan conjuntos de datos sintéticos que se envían al punto de conexión. Esto puede provocar que las métricas del punto de conexión o los datos capturados se vean contaminados por datos sintéticos, lo que puede no reflejar con precisión el uso en el mundo real. Por estas razones, generalmente no se recomienda utilizar un punto final de producción existente para el análisis de Clarify. SageMaker

  • target_model: el valor de cadena que se transfiere al TargetModel parámetro de la SageMaker InvokeEndpointAPI. Necesario si el modelo (especificado mediante el parámetro model_name) o el punto de conexión (especificado mediante el parámetro endpoint_name) es multimodelo. Para obtener más información sobre los puntos finales multimodelo, consulte. Alojar varios modelos en un contenedor detrás de un punto de conexión

  • custom_attributes: (opcional) cadena que permite proporcionar información adicional sobre una solicitud de inferencia que se envía al punto de conexión. El valor de la cadena se pasa al CustomAttributes parámetro de la SageMaker InvokeEndpointAPI.

  • content_type: formato de entrada del modelo que se utilizará para obtener las predicciones del punto de conexión. Si se proporciona, se pasa al ContentType parámetro de la SageMaker InvokeEndpointAPI.

    • Para facilitar la explicabilidad de la visión artificial, los valores válidos son image/jpeg, image/png o application/x-npy. Si no se proporciona content_type, el valor predeterminado es image/jpeg.

    • Para otros tipos de explicabilidad, los valores válidos son text/csv, application/jsonlines, y application/json. Se requiere un valor para content_type si dataset_type es “application/x-parquet”. De no ser así, content_type toma el valor predeterminado del parámetro dataset_type.

  • accept_type: el formato de salida del modelo que se utilizará para obtener las predicciones del punto de conexión. El valor de accept_type se pasa al Accept parámetro de la SageMaker InvokeEndpointAPI.

    • Para la explicabilidad de la visión artificial, si model_type es “OBJECT_DETECTION”, accept_type toma el valor predeterminado application/json.

    • Para otros tipos de explicabilidad, los valores válidos son text/csv, application/jsonlines y application/json. Si no se proporciona un valor para accept_type, el valor predeterminado de accept_type es el valor del parámetro content_type.

  • content_template: cadena de plantilla que se utiliza para construir la entrada del modelo a partir de los registros del conjunto de datos. El parámetro content_template solo se usa y es obligatorio si el valor del parámetro content_type es application/jsonlines o application/json.

    Si el parámetro content_type es application/jsonlines, la plantilla solo debe tener un marcador de posición, $features, que se sustituye por una lista de características en tiempo de ejecución. Por ejemplo, si la plantilla es "{\"myfeatures\":$features}", y si un registro tiene tres valores de característica numéricos: 1, 2 y 3, entonces el registro se enviará al modelo como JSON Lines {"myfeatures":[1,2,3]}.

    Cuando content_type es application/json, la plantilla puede tener un marcador de posición $record o records. Si el marcador de posición es record, se sustituye un único registro por un registro al que se le haya aplicado la plantilla de record_template. En este caso, solo se enviará un registro al modelo cada vez. Si el marcador de posición es $records, los registros se sustituyen por una lista de registros, cada uno con una plantilla proporcionada por record_template.

  • record_template: cadena de plantilla que se utiliza para construir cada registro del modelo a partir de las instancias del conjunto de datos. Solo se usa y se requiere cuando content_type es application/json. La cadena de plantilla puede contener uno de los siguientes valores:

    • Un parámetro $features marcador de posición que se sustituye por una matriz de valores de características. Un marcador de posición opcional adicional puede sustituir los nombres de los encabezados de las columnas de características en $feature_names. Este marcador de posición opcional se sustituirá por una serie de nombres de características.

    • Exactamente un marcador de posición $features_kvp que se sustituye por los pares clave-valor, el nombre de la característica y el valor de la característica.

    • Una característica de la configuración headers. Por ejemplo, un nombre de característica A, anotado mediante la sintaxis del marcador de posición "${A}" se sustituirá por el valor de la característica correspondiente para A.

    El valor para record_template se usa con content_template para construir la entrada del modelo. A continuación, se muestra un ejemplo de configuración que muestra cómo construir una entrada de modelo mediante una plantilla de contenido y registro.

    En el siguiente ejemplo de código, los encabezados y las características se definen de la siguiente manera.

    • `headers`:["A", "B"]

    • `features`:[[0,1], [3,4]]

    Un ejemplo de entrada del modelo sería el siguiente.

    {
        "instances": [[0, 1], [3, 4]],
        "feature_names": ["A", "B"]
    }

    A continuación, se muestran el ejemplo content_template y los valores del parámetro record_template para construir el ejemplo anterior de entrada del modelo.

    • content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"

    • record_template: "$features"

    En el siguiente ejemplo de código, los encabezados y las características se definen de la siguiente manera.

    [
        { "A": 0, "B": 1 },
        { "A": 3, "B": 4 },
    ]

    A continuación, se muestran el ejemplo content_template y los valores del parámetro record_template para construir el ejemplo anterior de entrada del modelo.

    • content_template: "$records"

    • record_template: "$features_kvp"

    A continuación, se muestra un ejemplo de código alternativo para construir la entrada del modelo del ejemplo anterior.

    • content_template: "$records"

    • record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"

    En el siguiente ejemplo de código, los encabezados y las características se definen de la siguiente manera.

    { "A": 0, "B": 1 }

    Los valores de los parámetros content_template y record_template de ejemplo que se va a construir están arriba: a continuación, la entrada del modelo del ejemplo anterior.

    • content_template: "$record"

    • record_template: "$features_kvp"

  • label: cadena de índice entero de base cero o cadena de expresión JMESPath que se utiliza para extraer las etiquetas predichas de la salida del modelo para realizar un análisis del sesgo. Si el modelo es multiclase y el parámetro label extrae todas las etiquetas predichas de la salida del modelo, se aplica lo siguiente.

    • El parámetro probability es necesario para obtener las probabilidades (o puntuaciones) correspondientes de la salida del modelo.

    • Se elige la etiqueta predicha de la puntuación más alta.

    El valor de label dependen del valor del parámetro accept_type de la siguiente manera.

    • Si accept_type es text/csv, entonces label es el índice de cualquier etiqueta predicha en la salida del modelo.

    • Si accept_type es application/jsonlines o application/json, entonces label es una expresión JMESPath que se aplica a la salida del modelo para obtener las etiquetas predichas.

  • label_headers: una matriz de valores que la etiqueta puede incluir en el conjunto de datos. Si se solicita un análisis del sesgo, el parámetro probability también es necesario para obtener los valores de probabilidad (puntuaciones) correspondientes de la salida del modelo, y se elige la etiqueta predicha de la puntuación más alta. Si se solicita un análisis de explicabilidad, los encabezados de las etiquetas se utilizan para embellecer el informe de análisis. Se requiere un valor para label_headers para la explicabilidad de la visión artificial. Por ejemplo, en el caso de un problema de clasificación multiclase, si la etiqueta tiene tres valores posibles, bird, cat y dog, entonces label_headers se debe establecer en ["bird","cat","dog"].

  • probability: (opcional) un índice entero de base cero o una cadena de expresión JMESPath que se utiliza para extraer probabilidades (puntuaciones) para el análisis de explicabilidad o para elegir la etiqueta predicha para el análisis del sesgo. El valor de probability dependen del valor del parámetro accept_type de la siguiente manera.

    • Si accept_type es text/csv, probability es el índice de las probabilidades (puntuaciones) en la salida del modelo. Si no se proporciona probability, toda la salida del modelo se toma como probabilidades (puntuaciones).

    • Si accept_type es datos de JSON (application/jsonlines o application/json), probability debe ser una expresión JMESPath que se utilice para extraer las probabilidades (puntuaciones) de la salida del modelo.

Archivos de configuración del análisis de ejemplo

Las siguientes secciones contienen ejemplos de archivos de configuración del análisis para datos en formato CSV, formato JSON Lines y para la explicabilidad del procesamiento de lenguaje natural (NLP) y la visión artificial.

Configuración del análisis para un conjunto de datos CSV

Los siguientes ejemplos muestran cómo configurar el análisis del sesgo y la explicabilidad para un conjunto de datos tabular en formato CSV. En estos ejemplos, el conjunto de datos entrante tiene cuatro columnas de características y una columna de etiquetas binarias, Target. El contenido del conjunto de datos es el siguiente. Un valor de etiqueta de 1 indica un resultado positivo. La entrada de dataset procesamiento proporciona el conjunto de datos al trabajo de SageMaker Clarify.

"Target","Age","Gender","Income","Occupation"
0,25,0,2850,2
1,36,0,6585,0
1,22,1,1759,1
0,48,0,3446,1
...

Las siguientes secciones muestran cómo calcular las métricas de sesgo previas y posteriores al entrenamiento, los valores SHAP y los gráficos de dependencia parcial (PDP) que muestran la importancia de la característica para un conjunto de datos en formato CSV.

Cálculo de todas las métricas de sesgo previas al entrenamiento

Este ejemplo de configuración muestra cómo medir si el conjunto de datos de muestra anterior está sesgado favorablemente hacia muestras con un valor de Gender de 0. La siguiente configuración de análisis indica al trabajo de procesamiento de SageMaker Clarify que calcule todas las métricas de sesgo previas al entrenamiento para el conjunto de datos.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Cálculo de todas las métricas de sesgo posteriores al entrenamiento

Puede calcular las métricas de sesgo previas al entrenamiento antes del entrenamiento. Sin embargo, debe tener un modelo entrenado para calcular las métricas de sesgo posteriores al entrenamiento. El siguiente ejemplo de salida proviene de un modelo de clasificación binaria que genera datos en formato CSV. En este ejemplo de salida, cada fila contiene dos columnas. La primera columna contiene la etiqueta predicha y la segunda columna contiene el valor de probabilidad de esa etiqueta.

0,0.028986845165491
1,0.825382471084594
...

El siguiente ejemplo de configuración indica al trabajo de procesamiento de SageMaker Clarify que calcule todas las métricas de sesgo posibles utilizando el conjunto de datos y las predicciones de la salida del modelo. En el ejemplo, el modelo se implementa en un SageMaker punto finalyour_endpoint.

nota

En el siguiente código de ejemplo, los parámetros content_type y accept_type no están configurados. Por lo tanto, utilizan automáticamente el valor del parámetro dataset_type, que es text/csv.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "label": 0
    }
}

Cálculo de los valores SHAP

El siguiente ejemplo de configuración del análisis indica al trabajo que calcule los valores SHAP, designando la columna Target como etiquetas y todas las demás columnas como características.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

En este ejemplo, se omite el parámetro SHAP baseline y el valor del parámetro num_clusters es 1. Esto indica al procesador SageMaker Clarify que calcule una muestra de referencia de SHAP. En este ejemplo, la probabilidad se establece en 1. Esto indica al trabajo de procesamiento de SageMaker Clarify que extraiga la puntuación de probabilidad de la segunda columna del resultado del modelo (mediante una indexación basada en cero).

Cálculo de los gráficos de dependencia parcial (PDP)

El siguiente ejemplo muestra cómo ver la importancia de la característica Income en el informe de análisis mediante los PDP. El parámetro de informe indica al trabajo de procesamiento de SageMaker Clarify que genere un informe. Una vez finalizado el trabajo, el informe generado se guarda como report.pdf en la ubicación analysis_result. El parámetro grid_resolution divide el rango de valores de las características en 10 buckets. En conjunto, los parámetros especificados en el siguiente ejemplo indican al trabajo de procesamiento de SageMaker Clarify que genere un informe que contenga un gráfico PDP Income con 10 segmentos en el eje x. El eje y mostrará el impacto marginal de Income en las predicciones.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "pdp": {
            "features": ["Income"],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    },
}

Cálculo de las métricas de sesgo y de la importancia de las características

Puede combinar todos los métodos de los ejemplos de configuración anteriores en un único archivo de configuración de análisis y calcularlos todos en un solo trabajo. El siguiente ejemplo muestra una configuración de análisis con todos los pasos combinados.

En este ejemplo, el parámetro probability se establece 1 para indicar que las probabilidades están contenidas en la segunda columna (mediante la indexación basada en cero). Sin embargo, dado que el análisis del sesgo necesita una etiqueta predicha, el parámetro probability_threshold se establece en 0.5 para convertir la puntuación de probabilidad en una etiqueta binaria. En este ejemplo, el parámetro top_k_features del método de los gráficos de dependencia parcial pdp se establece en 2. Esto indica al trabajo de procesamiento de SageMaker Clarify que calcule las gráficas de dependencia parcial (PDP) para las principales 2 entidades con los valores de SHAP globales más altos.

{
    "dataset_type": "text/csv",
    "label": "Target",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

En lugar de implementar el modelo en un punto final, puede proporcionar el nombre del SageMaker modelo al trabajo de procesamiento de SageMaker Clarify mediante el parámetro. model_name En el siguiente ejemplo se muestra cómo especificar un modelo denominado your_model. El trabajo SageMaker de procesamiento de Clarify creará un punto final oculto mediante la configuración.

{
     ...
    "predictor": {
        "model_name": "your_model",
        "initial_instance_count": 1,
        "instance_type": "ml.m5.large",
        "probability": 1
    }
}

Configuración del análisis para un conjunto de datos JSON Lines

Los siguientes ejemplos muestran cómo configurar el análisis de sesgo y el análisis de explicabilidad para un conjunto de datos tabular en formato JSON Lines. En estos ejemplos, el conjunto de datos entrante tiene los mismos datos que en la sección anterior, pero están en el formato denso de líneas SageMaker JSON. Cada línea es un objeto JSON válido. La clave “Features” apunta a una matriz de valores de características, y la clave “Label” apunta a la etiqueta de verdad fundamental. La entrada de procesamiento del «conjunto de datos» proporciona el conjunto de datos al trabajo de SageMaker Clarify. Para obtener más información sobre la líneas JSON, consulte Formato de solicitud JSONLINES.

{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...

Las siguientes secciones muestran cómo calcular las métricas de sesgo previas y posteriores al entrenamiento, los valores SHAP y los gráficos de dependencia parcial (PDP) que muestran la importancia de la característica para un conjunto de datos en formato JSON Lines.

Cálculo de las métricas de sesgo previas al entrenamiento

Especifique la etiqueta, las características, el formato y los métodos para medir las métricas de sesgo previas al entrenamiento con un valor Gender de 0. En el siguiente ejemplo, el parámetro headers proporciona primero los nombres de las características. El nombre de la etiqueta se proporciona en último lugar. Por convención, el último encabezado es el encabezado de la etiqueta.

El features parámetro se establece en la expresión «Características» de JMEspath para que el trabajo de procesamiento de SageMaker Clarify pueda extraer la matriz de características de cada registro. El label parámetro se establece en la expresión «Label» de JMEspath para que el trabajo de procesamiento de SageMaker Clarify pueda extraer la etiqueta fundamental de cada registro. Utilice un nombre de faceta para especificar el atributo sensible, como se indica a continuación.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Cálculo de todas las métricas de sesgo

Debe tener un modelo entrenado para calcular las métricas de sesgo posteriores al entrenamiento. El siguiente ejemplo proviene de un modelo de clasificación binaria que genera datos en formato JSON Lines en el formato del ejemplo. Cada fila de la salida del modelo es un objeto JSON válido. La clave predicted_label apunta a la etiqueta predicha y la clave probability apunta al valor de probabilidad.

{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...

Puede implementar el modelo en un SageMaker punto final denominado. your_endpoint El siguiente ejemplo de configuración de análisis indica al trabajo de procesamiento SageMaker de Clarify que calcule todas las métricas de sesgo posibles tanto para el conjunto de datos como para el modelo. En el ejemplo, los parámetros content_type y accept_type no están definidos. Por lo tanto, utilizan automáticamente el valor del parámetro dataset_type, que es application/jsonlines. El trabajo SageMaker de procesamiento de Clarify usa el content_template parámetro para componer la entrada del modelo, reemplazando el $features marcador de posición por una matriz de características.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "label": "predicted_label"
    }
}

Cálculo de los valores SHAP

Como el análisis SHAP no necesita una etiqueta de verdad fundamental, se omite el parámetro label. En este ejemplo, también se omite el parámetro headers. Por lo tanto, el SageMaker trabajo de procesamiento de Clarify debe generar marcadores de posición con nombres genéricos, como column_0 o column_1 para encabezados de entidades, y label0 para un encabezado de etiqueta. Puede especificar valores para headers y para label a fin de mejorar la legibilidad del resultado del análisis. Como el parámetro de probabilidad está establecido en la expresión JMESPath probability, el valor de probabilidad se extraerá de la salida del modelo. A continuación se muestra un ejemplo para calcular valores SHAP.

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Cálculo de los gráficos de dependencia parcial (PDP)

El siguiente ejemplo muestra cómo ver la importancia de los “ingresos” en el PDP. En este ejemplo, no se proporcionan los encabezados de las características. Por lo tanto, el parámetro features del método pdp debe utilizar un índice de base cero para hacer referencia a la ubicación de la columna de características. El parámetro grid_resolution divide el rango de valores de las características en 10 buckets. En conjunto, los parámetros del ejemplo indican al trabajo de procesamiento de SageMaker Clarify que genere un informe que contenga un gráfico PDP Income con 10 segmentos en el eje x. El eje y mostrará el impacto marginal de Income en las predicciones.

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Cálculo de las métricas de sesgo y de la importancia de las características

Puede combinar todos los métodos anteriores en un único archivo de configuración de análisis y calcularlos todos en un solo trabajo. El siguiente ejemplo muestra una configuración de análisis con todos los pasos combinados. En el ejemplo, el parámetro probability está definido. Dado que el análisis del sesgo necesita una etiqueta predicha, el parámetro probability_threshold se establece en 0.5 para convertir la puntuación de probabilidad en una etiqueta binaria. En este ejemplo, el parámetro top_k_features del método pdp se establece en 2. Esto indica al trabajo de procesamiento de SageMaker Clarify que calcule los PDP de las principales 2 entidades con los valores de SHAP globales más altos.

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

Configuración del análisis para un conjunto de datos JSON

Los siguientes ejemplos muestran cómo configurar el análisis del sesgo y la explicabilidad para un conjunto de datos tabular en formato JSON. En estos ejemplos, el conjunto de datos entrante tiene los mismos datos que en la sección anterior, pero están en formato denso SageMaker JSON. Para obtener más información sobre la líneas JSON, consulte Formato de solicitud JSONLINES.

Toda la solicitud de entrada es un formato JSON válido, donde la estructura externa es una lista y cada elemento son los datos de un registro. Dentro de cada registro, la clave Features apunta a una matriz de valores de características, y la clave Label apunta a la etiqueta de verdad fundamental. La entrada de dataset procesamiento proporciona el conjunto de datos al trabajo de SageMaker Clarify.

[
    {"Features":[25,0,2850,2],"Label":0},
    {"Features":[36,0,6585,0],"Label":1},
    {"Features":[22,1,1759,1],"Label":1},
    {"Features":[48,0,3446,1],"Label":0},
    ...
]

Las siguientes secciones muestran cómo calcular las métricas de sesgo previas y posteriores al entrenamiento, los valores SHAP y los gráficos de dependencia parcial (PDP) que muestran la importancia de la característica para un conjunto de datos en formato JSON Lines.

Cálculo de las métricas de sesgo previas al entrenamiento

Especifique la etiqueta, las características, el formato y los métodos para medir las métricas de sesgo previas al entrenamiento con un valor Gender de 0. En el siguiente ejemplo, el parámetro headers proporciona primero los nombres de las características. El nombre de la etiqueta se proporciona en último lugar. En el caso de los conjuntos de datos JSON, el último encabezado es el encabezado de la etiqueta.

El parámetro features se establece en la expresión JMESPath que extrae un conjunto o matriz 2D. Cada fila de esta matriz debe contener la lista de Features para cada registro. El parámetro label se establece en la expresión JMESPath que extrae una lista de etiquetas de verdad fundamental. Cada elemento de esta lista debe contener la etiqueta de un registro.

Utilice un nombre de faceta para especificar el atributo sensible, como se indica a continuación.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        }
    }
}

Cálculo de todas las métricas de sesgo

Debe tener un modelo entrenado para calcular las métricas de sesgo posteriores al entrenamiento. El siguiente ejemplo de código proviene de un modelo de clasificación binaria que genera datos en formato JSON en el formato del ejemplo. En el ejemplo, cada uno de los elementos en predictions es el resultado de la predicción de un registro. El código de ejemplo contiene la clave predicted_label, que apunta a la etiqueta predicha, y la clave probability que apunta al valor de probabilidad.

{
    "predictions": [
        {"predicted_label":0,"probability":0.028986845165491},
        {"predicted_label":1,"probability":0.825382471084594},
        ...
    ]
}

Puede implementar el modelo en un SageMaker punto final denominadoyour_endpoint.

En el siguiente ejemplo, los parámetros content_type y accept_type no están configurados. Por lo tanto, content_type y accept_type utilizan automáticamente el valor del parámetro dataset_type, que es application/json. A continuación SageMaker , el trabajo de procesamiento de Clarify utiliza el content_template parámetro para componer la entrada del modelo.

En el siguiente ejemplo, la entrada del modelo se compone a través de la sustitución del marcador de posición $records por una matriz de registros. A continuación, el parámetro record_template compone la estructura JSON de cada registro y reemplaza el marcador de posición $features por la matriz de características de cada registro.

El siguiente ejemplo de configuración de análisis indica al trabajo de procesamiento SageMaker de Clarify que calcule todas las métricas de sesgo posibles tanto para el conjunto de datos como para el modelo.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "label": "predictions[*].predicted_label"
    }
}

Cálculo de los valores SHAP

No es necesario especificar una etiqueta para el análisis SHAP. En el siguiente ejemplo, el parámetro headers no está configurado. Por lo tanto, el SageMaker trabajo de procesamiento de Clarify generará marcadores de posición con nombres genéricos, como column_0 o column_1 para encabezados de entidades, y label0 para un encabezado de etiqueta. Puede especificar valores para headers y para label a fin de mejorar la legibilidad del resultado del análisis.

En el siguiente ejemplo de configuración, el parámetro de probabilidad se establece en una expresión JMESPath que extrae las probabilidades de cada predicción para cada registro. A continuación se muestra un ejemplo para calcular valores SHAP.

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

Cálculo de los gráficos de dependencia parcial (PDP)

En el siguiente ejemplo se muestra cómo ver la importancia de una característica en los PDP. En el ejemplo, no se proporcionan los encabezados de las características. Por lo tanto, el parámetro features del método pdp debe utilizar un índice de base cero para hacer referencia a la ubicación de la columna de características. El parámetro grid_resolution divide el rango de valores de las características en 10 buckets.

En conjunto, los parámetros del siguiente ejemplo indican al trabajo de procesamiento de SageMaker Clarify que genere un informe que contenga un gráfico PDP Income con 10 segmentos en el eje x. El eje y muestra el impacto marginal de Income en las predicciones.

El siguiente ejemplo muestra cómo ver la importancia de los Income en el PDP.

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

Cálculo de las métricas de sesgo y de la importancia de las características

Puede combinar todos los métodos de configuración anteriores en un único archivo de configuración de análisis y calcularlos todos en un solo trabajo. El siguiente ejemplo muestra una configuración de análisis con todos los pasos combinados.

En el ejemplo, el parámetro probability está definido. Como el análisis del sesgo necesita una etiqueta predicha, el parámetro probability_threshold se establece en 0.5 para convertir la puntuación de probabilidad en una etiqueta binaria. En este ejemplo, el parámetro top_k_features del método pdp se establece en 2. Esto indica al trabajo de procesamiento de SageMaker Clarify que calcule los PDP para las principales 2 entidades con los valores de SHAP globales más altos.

{
    "dataset_type": "application/json",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "[*].Label",
    "features": "[*].Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

Configuración del análisis para la explicabilidad del procesamiento de lenguaje natural

El siguiente ejemplo muestra un archivo de configuración del análisis para calcular la importancia de las características en el procesamiento de lenguaje natural (NLP). En este ejemplo, el conjunto de datos entrante es un conjunto de datos tabular en formato CSV, con una columna de etiqueta binaria y dos columnas de características, de la siguiente manera. El conjunto de datos se proporciona al trabajo de SageMaker Clarify mediante el parámetro de entrada de dataset procesamiento.

0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...

En este ejemplo, se entrenó un modelo de clasificación binaria en el conjunto de datos anterior. El modelo acepta datos CSV y genera una puntuación única entre 0 y 1, de la siguiente manera.

0.491656005382537
0.569582343101501
...

El modelo se utiliza para crear un SageMaker modelo denominado «your_model». La siguiente configuración de análisis muestra cómo ejecutar un análisis de explicabilidad simbólica utilizando el modelo y el conjunto de datos. El parámetro text_config activa el análisis de explicabilidad del NLP. El parámetro granularity indica que el análisis debe analizar los tokens.

En inglés, cada token es una palabra. El siguiente ejemplo también muestra cómo proporcionar una instancia de “referencia” SHAP in situ con una “valoración” media de 4. Se utiliza un token de máscara especial “[MASK]” para reemplazar un token (palabra) en “Comments”. En este ejemplo también se utiliza un tipo de instancia de punto de conexión de GPU para acelerar las inferencias.

{
    "dataset_type": "text/csv",
    "headers": ["Target","Rating","Comments"]
    "label": "Target",
    "methods": {
        "shap": {
            "text_config": {
                "granularity": "token",
                "language": "english"
            }
            "baseline": [[4,"[MASK]"]],
        }
    },
    "predictor": {
        "model_name": "your_nlp_model",
        "initial_instance_count": 1,
        "instance_type": "ml.g4dn.xlarge"
    }
}

Configuración del análisis para facilitar la explicación de la visión artificial

El siguiente ejemplo muestra un archivo de configuración de análisis que calcula la importancia de las características para la visión artificial. En este ejemplo, el conjunto de datos de entrada consta de imágenes JPEG. El conjunto de datos se proporciona al trabajo de SageMaker Clarify mediante el parámetro de entrada dataset de procesamiento. El ejemplo muestra cómo configurar un análisis de explicabilidad mediante un modelo de clasificación de SageMaker imágenes. En el ejemplo, un modelo denominado your_cv_ic_model se ha entrenado para clasificar los animales de las imágenes JPEG de entrada.

{
    "dataset_type": "application/x-image",
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "IMAGE_CLASSIFICATION",
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_ic_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

Para obtener más información sobre la clasificación de imágenes, consulte. Image Classification - MXNet

En este ejemplo, un modelo de detección de SageMaker objetos your_cv_od_model se basa en las mismas imágenes JPEG para identificar los animales que aparecen en ellas. En el siguiente ejemplo se muestra cómo configurar un análisis de explicabilidad para el modelo de detección de objetos.

{
    "dataset_type": "application/x-image",
    "probability_threshold": 0.5,
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "OBJECT_DETECTION",
                 "max_objects": 3,
                "context": 1.0,
                "iou_threshold": 0.5,
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_od_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}