Arquivos de configuração de análise - SageMaker IA da Amazon
Esquema para o arquivo de configuração de análiseExemplo de arquivos de configuração de análise

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Arquivos de configuração de análise

Para analisar seus dados e modelos quanto à explicabilidade e ao viés usando o SageMaker Clarify, você deve configurar uma tarefa de processamento. Parte da configuração desse trabalho de processamento inclui a configuração de um arquivo de análise. O arquivo de análise especifica os parâmetros para análise de desvio e explicabilidade. Consulte Configurar um SageMaker Clarify Processing Job para saber como configurar um trabalho de processamento e um arquivo de análise.

Este guia descreve o esquema e os parâmetros desse arquivo de configuração de análise. O guia também inclui exemplos de arquivos de configuração de análise para calcular métricas de desvio para um conjunto de dados tabular e gerar explicações para problemas de processamento de linguagem natural (PLN), visão computacional (CV) e séries temporais (TS).

Você pode criar o arquivo de configuração de análise ou usar o SDK do SageMaker Python para gerar um para você com a API. SageMaker ClarifyProcessor A visualização do conteúdo do arquivo pode ser útil para entender a configuração subjacente usada pela tarefa do SageMaker Clarify.

Esquema para o arquivo de configuração de análise

A seção a seguir descreve o esquema do arquivo de configuração de análise, incluindo requisitos e descrições dos parâmetros.

Requisitos para o arquivo de configuração de análise

O trabalho de processamento do SageMaker Clarify espera que o arquivo de configuração da análise seja estruturado com os seguintes requisitos:

  • O nome da entrada de processamento deve ser analysis_config.

  • O arquivo de configuração de análise está no formato JSON e codificado em UTF-8.

  • O arquivo de configuração de análise é um objeto do Amazon S3.

Você pode especificar parâmetros adicionais no arquivo de configuração da análise. A seção a seguir fornece várias opções para personalizar a tarefa de processamento do SageMaker Clarify para seu caso de uso e tipos de análise desejados.

No arquivo de configuração da análise, é possível especificar parâmetros a seguir.

  • versão: (Opcional) A string de versão do esquema do arquivo de configuração de análise. Se uma versão não for fornecida, o SageMaker Clarify usará a versão mais recente compatível. Atualmente, a única versão compatível é 1.0.

  • dataset_type: O formato do conjunto de dados. O formato do conjunto de dados de entrada pode ser qualquer um dos seguintes valores:

    • Tabular

      • text/csv para CSV

      • application/jsonlinespara formato denso de linhas SageMaker AI JSON

      • application/json para JSON

      • application/x-parquet para Apache Parquet

      • application/x-image para ativar a explicabilidade para problemas de visão computacional

    • Explicações do modelo de previsão de séries temporais

      • application/json para JSON

  • dataset_uri: (Opcional) O identificador de recursos uniforme (URI) do conjunto de dados principal. Se você fornecer um prefixo de URI do S3, o trabalho de processamento do SageMaker Clarify coletará recursivamente todos os arquivos do S3 localizados abaixo do prefixo. Você pode fornecer um prefixo de URI do S3 ou URI do S3 para um arquivo manifesto de imagem para problemas de visão computacional. Se o dataset_uri for fornecido, ele terá precedência sobre a entrada do trabalho de processamento do conjunto de dados. Para qualquer tipo de formato, exceto casos de uso de imagens e séries temporais, o trabalho de processamento do SageMaker Clarify carrega o conjunto de dados de entrada em um quadro de dados tabular, como um conjunto de dados tabular. Esse formato permite que a SageMaker IA manipule e analise facilmente o conjunto de dados de entrada.

  • headers: (Opcional)

    • Tabular: uma matriz de strings contendo os nomes das colunas de um conjunto de dados tabular. Se um valor não for fornecidoheaders, o trabalho de processamento do SageMaker Clarify lê os cabeçalhos do conjunto de dados. Se o conjunto de dados não tiver cabeçalhos, o trabalho de processamento do Clarify gerará automaticamente nomes para espaços reservados baseados no índice de coluna com base em zero. Por exemplo, os nomes dos espaços reservados para a primeira e a segunda colunas serão column_0 e column_1.

      nota

      Por convenção, se dataset_type for application/jsonlines ou application/json, então headers deve conter os seguintes nomes em ordem:

      1. nomes de atributo

      2. nome do rótulo (se label for especificado)

      3. nome do rótulo previsto (se predicted_label for especificado)

      Um exemplo de headers para um tipo de conjunto de dados application/jsonlines, se o label for especificado, é: ["feature1","feature2","feature3","target_label"].

    • Time series: uma lista de nomes de colunas no conjunto de dados. Se isso não for fornecido, o Clarify gera cabeçalhos para uso interno. Para casos de explicabilidade de séries temporais, forneça cabeçalhos na seguinte ordem:

      1. ID do item

      2. timestamp

      3. séries temporais de destino

      4. todas as colunas de séries temporais relacionadas

      5. todas as colunas de covariáveis estáticas

  • label: (Opcional) Uma string ou um índice inteiro baseado em zero. Se fornecido, o label é usado para localizar o rótulo de veracidade, também conhecido como rótulo observado ou atributo de destino em um conjunto de dados tabular. O rótulo de veracidade é usado para calcular métricas de desvio. O valor para label é especificado de acordo com o valor do parâmetro dataset_type da seguinte forma:

    • Se dataset_type for text/csv, o label pode ser especificado como uma das seguintes opções:

      • Um nome de coluna válido

      • Um índice que está dentro do intervalo de colunas do conjunto de dados

    • Se dataset_type for application/parquet, o label deve ser um nome de coluna válido.

    • Se dataset_type forapplication/jsonlines, label deve ser uma JMESPathexpressão escrita para extrair o rótulo de verdade fundamental do conjunto de dados. Por convenção, se headers for especificado, ele deverá conter o nome do rótulo.

    • Se dataset_type forapplication/json, label deve ser uma JMESPathexpressão escrita para extrair o rótulo de verdade fundamental para cada registro no conjunto de dados. Essa JMESPath expressão deve produzir uma lista de rótulos em que o i the label se correlaciona com o i no registro.

  • predicted_label: (Opcional) Uma string ou um índice inteiro baseado em zero. Se fornecido, o predicted_label é usado para localizar a coluna que contém o rótulo previsto em um conjunto de dados tabular. O rótulo previsto é usado para calcular métricas de desvio pós-treinamento. O parâmetro predicted_label é opcional se o conjunto de dados não incluir o rótulo previsto. Se rótulos previstos forem necessários para o cálculo, o trabalho de processamento do SageMaker Clarify obterá previsões do modelo.

    O valor para predicted_label é especificado de acordo com o valor do dataset_type da seguinte forma:

    • Se dataset_type for text/csv, o predicted_label pode ser especificado como uma das seguintes opções:

      • Um nome de coluna válido. Se o predicted_label_dataset_uri for especificado, mas o predicted_label não for fornecido, o nome padrão do rótulo previsto será “predicted_label”.

      • Um índice que está dentro do intervalo de colunas do conjunto de dados. Se o predicted_label_dataset_uri for especificado, o índice será usado para localizar a coluna do rótulo previsto no conjunto de dados do rótulo previsto.

    • Se o dataset_type for application/x-parquet, o predicted_label deve ser um nome de coluna válido.

    • Se dataset_type forapplication/jsonlines, predicted_label deverá ser uma JMESPathexpressão válida escrita para extrair o rótulo previsto do conjunto de dados. Por convenção, se o headers for especificado, ele deverá conter o nome do rótulo previsto.

    • Se dataset_type forapplication/json, predicted_label deve ser uma JMESPathexpressão escrita para extrair o rótulo previsto para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma lista de rótulos previstos em que o rótulo previsto é para eles no registro.

  • recursos — (Opcional) Obrigatório para casos de non-time-series uso se dataset_type for application/jsonlines ouapplication/json. Uma expressão de JMESPath string escrita para localizar os recursos no conjunto de dados de entrada. Poisapplication/jsonlines, uma JMESPath expressão será aplicada a cada linha para extrair os recursos desse registro. Poisapplication/json, uma JMESPath expressão será aplicada a todo o conjunto de dados de entrada. A JMESPath expressão deve extrair uma lista de listas ou uma matriz/matriz 2D de recursos em que a linha i contém os recursos que se correlacionam com o registro. Para um dataset_type de text/csv ou application/x-parquet, todas as colunas, exceto as colunas do rótulo de veracidade e do rótulo previsto, são automaticamente atribuídas como atributos.

  • predicted_label_dataset_uri: (opcional) aplicável somente quando dataset_type for text/csv. O URI do S3 para um conjunto de dados contendo rótulos previstos usados para calcular métricas de desvio pós-treinamento. O trabalho de processamento do SageMaker Clarify carregará as previsões do URI fornecido em vez de obter previsões do modelo. Nesse caso, o predicted_label é obrigatório para localizar a coluna do rótulo previsto no conjunto de dados do rótulo previsto. Se o conjunto de dados do rótulo previsto ou o conjunto de dados principal estiver dividido em vários arquivos, uma coluna identificadora deverá ser especificada por joinsource_name_or_index para unir os dois conjuntos de dados.

  • predicted_label_headers: (opcional) aplicável somente quando predicted_label_dataset_uri for especificado. Uma matriz de strings contendo os nomes de colunas do conjunto de dados do rótulo previsto. Além do cabeçalho do rótulo previsto, o predicted_label_headers também pode conter o cabeçalho da coluna identificadora para unir o conjunto de dados do rótulo previsto e o conjunto de dados principal. Para obter mais informações, consulte a descrição do parâmetro joinsource_name_or_index a seguir.

  • joinsource_name_or_index: (opcional) o nome ou índice baseado em zero da coluna em conjuntos de dados tabulares a ser usado como uma coluna identificadora ao realizar uma junção interna. Essa coluna é usada somente como um identificador. Ela não é usada para nenhum outro cálculo, como análise de desvio ou análise de atribuição de atributos. Um valor para o joinsource_name_or_index é necessário nos seguintes casos:

    • Existem vários conjuntos de dados de entrada e qualquer um é dividido em vários arquivos.

    • O processamento distribuído é ativado definindo a tarefa de processamento do SageMaker Clarify InstanceCountcom um valor maior que 1 o.

  • excluded_columns: (opcional) uma matriz de nomes ou índices de colunas baseados em zero a serem excluídos do envio ao modelo como entrada para predições. O rótulo de veracidade e o rótulo previsto já foram excluídos automaticamente. Esse atributo não é compatível com séries temporais.

  • probability_threshold: (opcional) um número de ponto flutuante acima do qual um rótulo ou objeto é selecionado. O valor padrão é 0.5. A tarefa de processamento do SageMaker Clarify é usada probability_threshold nos seguintes casos:

    • Na análise de desvio pós-treinamento, o probability_threshold converte uma predição de modelo numérico (valor ou pontuação de probabilidade) em um rótulo binário, se o modelo for um classificador binário. Uma pontuação maior que o limite é convertida em 1. Por outro lado, uma pontuação menor ou igual ao limite é convertida em 0.

    • Em problemas de explicabilidade de visão computacional, se o model_type for OBJECT_DETECTION, o , probability_threshold filtra objetos detectados com pontuações de confiança inferiores ao valor limite.

  • label_values_or_threshold: (opcional) obrigatório para análise de vieses. Uma matriz de valores de rótulo ou um número limite, que indicam um resultado positivo para rótulos de veracidade e previstos para métricas de desvio. Para obter mais informações, consulte valores de rótulos positivos em Amazon SageMaker esclarece os termos de preconceito e imparcialidade. Se o rótulo for numérico, o limite será aplicado como limite inferior para selecionar o resultado positivo. Para definir label_values_or_threshold para diferentes tipos de problema, consulte os seguintes exemplos:

    • Para um problema de classificação binária, o rótulo tem dois valores possíveis, 0 e 1. Se o valor do rótulo 1 for favorável a um grupo demográfico observado em uma amostra, então o label_values_or_threshold deverá ser definido como [1].

    • Para um problema de classificação multiclasse, o rótulo tem três valores possíveis, bird, cat e dog. Se os dois últimos definirem um grupo demográfico que o desvio favorece, então o label_values_or_threshold deve ser definido como ["cat","dog"].

    • Para um problema de regressão, o valor do rótulo é contínuo, variando de 0 a 1. Se um valor maior do que 0.5 designar uma amostra como tendo um resultado positivo, então o label_values_or_threshold deve ser definido como 0.5.

  • facet: (opcional) obrigatório para análise de vieses. Uma matriz de objetos facetários, que são compostos por atributos confidenciais contra os quais o desvio é medido. Você pode usar facetas para entender as características de desvio do seu conjunto de dados e modelo, mesmo que seu modelo seja treinado sem usar atributos confidenciais. Para mais informações, consulte Facetas em Amazon SageMaker esclarece os termos de preconceito e imparcialidade. Cada objeto de faceta inclui os seguintes campos:

    • name_or_index: (Opcional) O nome ou índice baseado em zero da coluna de atributos confidenciais em um conjunto de dados tabular. Se o facet_dataset_uri for especificado, o índice se referirá ao conjunto de dados da faceta em vez do conjunto de dados principal.

    • value_or_threshold: (Opcional) Obrigatório se facet for numérico e o label_values_or_threshold for aplicado como limite inferior para selecionar o grupo sensível. Uma matriz de valores facetários ou um número limite, que indica o grupo demográfico confidencial que o desvio favorece. Se o tipo de dados da faceta for categórico e o value_or_threshold não for fornecido, as métricas de desvio serão calculadas como um grupo para cada valor exclusivo (em vez de todos os valores). Para definir o value_or_threshold para diferentes tipos de problemas de facet, consulte os seguintes exemplos:

      • Para um tipo de dados de faceta binária, o atributo tem dois valores possíveis, 0 e 1. Se você quiser calcular as métricas de desvio para cada valor, então o value_or_threshold pode ser omitido ou definido como uma matriz vazia.

      • Para um tipo de dados de faceta categórica, o atributo tem três valores possíveis, bird, cat e dog. Se os dois primeiros definirem um grupo demográfico que o desvio favorece, então o value_or_threshold deve ser definido como ["bird", "cat"]. Neste exemplo, as amostras do conjunto de dados são divididas em dois grupos demográficos. A faceta do grupo favorecido tem valor bird ou cat, enquanto a faceta do grupo desfavorecido tem valor dog.

      • Para um tipo de dados de faceta numérica, o valor do atributo é contínuo, variando de 0 a 1. Por exemplo, se um valor maior do que 0.5 designar uma amostra como favorecida, então o value_or_threshold deve ser definido como 0.5. Neste exemplo, as amostras do conjunto de dados são divididas em dois grupos demográficos. A faceta do grupo favorecido tem valor superior a 0.5, enquanto a faceta do grupo desfavorecido tem valor inferior ou igual a 0.5.

  • group_variable: (Opcional) O nome ou índice baseado em zero da coluna que indica o subgrupo a ser usado para a métrica de desvio Disparidade demográfica condicional (CDD) ou Disparidade demográfica condicional em rótulos previstos (CDDPL).

  • facet_dataset_uri: (Opcional) Aplicável somente quando o dataset_type for text/csv. O URI do S3 para um conjunto de dados contendo atributos confidenciais para análise de desvio. Você pode usar facetas para entender as características de desvio do seu conjunto de dados e modelo, mesmo que seu modelo seja treinado sem usar atributos confidenciais.

    nota

    Se o conjunto de dados da faceta ou o conjunto de dados principal estiver dividido em vários arquivos, uma coluna identificadora deverá ser especificada por joinsource_name_or_index para unir os dois conjuntos de dados. Você deve usar o parâmetro facet para identificar cada faceta no conjunto de dados da faceta.

  • facet_headers: (Opcional) Aplicável somente quando facet_dataset_uri for especificado. Uma matriz de strings contendo nomes de colunas para o conjunto de dados da faceta e, opcionalmente, o cabeçalho da coluna identificadora para unir o conjunto de dados da faceta e o conjunto de dados principal, consulte joinsource_name_or_index.

  • time_series_data_config: (Opcional) Especifica a configuração a ser usada para processamento de dados de uma série temporal.

    • item_id: Uma string ou um índice inteiro baseado em zero. Esse campo é usado para localizar um ID de item no conjunto de dados de entrada compartilhado.

    • timestamp: Uma string ou um índice inteiro baseado em zero. Esse campo é usado para localizar um registro de data/hora no conjunto de dados de entrada compartilhado.

    • dataset_format: Os valores possíveis são columns, item_records ou timestamp_records. Esse campo é usado para descrever o formato de um conjunto de dados JSON, que é o único formato compatível com a explicabilidade de séries temporais.

    • target_time_series — Uma JMESPath string ou um índice inteiro baseado em zero. Esse campo é usado para localizar a série temporal de destino no conjunto de dados de entrada compartilhado. Se esse parâmetro for uma string, todos os outros parâmetros, exceto dataset_format, deverão ser strings ou listas de strings. Se esse parâmetro for um número inteiro, todos os outros parâmetros, exceto dataset_format, deverão ser números inteiros ou listas de números inteiros.

    • related_time_series — (Opcional) Uma matriz de expressões. JMESPath Esse campo é usado para localizar todas as séries temporais relacionadas no conjunto de dados de entrada compartilhado, se houver.

    • static_covariates — (Opcional) Uma matriz de expressões. JMESPath Esse campo é usado para localizar todos os campos de covariáveis estáticas no conjunto de dados de entrada compartilhado, se presentes.

    Para obter exemplos, consulte Exemplos de configuração de conjuntos de dados de séries temporais.

  • methods: Um objeto contendo um ou mais métodos de análise e seus parâmetros. Se algum método for omitido, ele não será usado para análise nem relatado.

    • pre_training_bias: Inclua esse método se quiser calcular métricas de desvio pré-treinamento. A descrição detalhada das métricas pode ser encontrada em Métricas de desvio pré-treinamento. O objeto tem os seguintes parâmetros:

    • post_training_bias: Inclua esse método se quiser calcular métricas de desvio pós-treinamento. A descrição detalhada das métricas pode ser encontrada em Métricas de dados pós-treinamento e desvio do modelo. O objeto post_training_bias tem os parâmetros a seguir.

    • shap: Inclua esse método se quiser calcular valores SHAP. O trabalho de processamento do SageMaker Clarify oferece suporte ao algoritmo Kernel SHAP. O objeto shap tem os parâmetros a seguir.

      • baseline: (Opcional) O conjunto de dados de linha de base do SHAP, também conhecido como conjunto de dados em segundo plano. Os requisitos adicionais para o conjunto de dados de linha de base em um conjunto de dados tabular ou problema de visão computacional são os seguintes: Para obter mais informações sobre as linhas de base do SHAP, consulte Linhas de base do SHAP para explicabilidade.

        • Para um conjunto de dados tabular, a baseline pode ser os dados de linha de base no local ou o URI do S3 de um arquivo de linha de base. Se não baseline for fornecido, o trabalho de processamento do SageMaker Clarify calcula uma linha de base agrupando o conjunto de dados de entrada. O seguinte é exigido da linha de base:

          • O formato deve ser igual ao formato do conjunto de dados especificado pelo dataset_type.

          • A linha de base só pode conter atributos que o modelo possa aceitar como entrada.

          • O conjunto de dados de linha de base pode ter uma ou mais instâncias. O número de instâncias de linha de base afeta diretamente o tamanho do conjunto de dados sintéticos e o runtime do trabalho.

          • Se a text_config for especificada, o valor da linha de base de uma coluna de texto será uma string usada para substituir a unidade de texto especificada por granularity. Por exemplo, um espaço reservado comum é "[MASK]", que é usado para representar uma palavra ou trecho de texto ausente ou desconhecido.

          Os seguintes exemplos mostram como definir dados de linha de base no local para diferentes parâmetros dataset_type:

          • Se o dataset_type for text/csv ou application/x-parquet, o modelo aceitará quatro atributos numéricos e a linha de base terá duas instâncias. Neste exemplo, se um registro tiver todos os valores de atributo como zero e o outro registro tiver todos os valores de atributo como um, a linha de base deverá ser definida como [[0,0,0,0],[1,1,1,1]], sem nenhum cabeçalho.

          • Se o dataset_type for application/jsonlines, features é a chave para uma lista de quatro valores de atributos numéricos. Além disso, neste exemplo, se a linha de base tiver um registro de todos os valores como zero, então a baseline deverá ser [{"features":[0,0,0,0]}].

          • Se dataset_type for application/json, o conjunto de dados baseline deverá ter a mesma estrutura e formato do conjunto de dados de entrada.

        • Para problemas de visão computacional, a baseline pode ser o URI do S3 de uma imagem usada para mascarar atributos (segmentos) da imagem de entrada. A tarefa de processamento do SageMaker Clarify carrega a imagem da máscara e a redimensiona para a mesma resolução da imagem de entrada. Se a linha de base não for fornecida, o trabalho de processamento do SageMaker Clarify gerará uma imagem de máscara de ruído branco na mesma resolução da imagem de entrada.

      • features_to_explain: (Opcional) Uma matriz de strings ou índices baseados em zero de colunas de atributos para calcular valores de SHAP. Se features_to_explain não for fornecido, os valores SHAP serão calculados para todas as colunas de atributos. Essas colunas de atributos não podem incluir a coluna de rótulo ou a coluna de rótulo previsto. O parâmetro features_to_explain só é compatível com conjuntos de dados tabulares com colunas numéricas e categóricas.

      • num_clusters: (Opcional) O número de clusters em que o conjunto de dados é dividido para calcular o conjunto de dados de linha de base. Cada cluster é usado para calcular uma instância de linha de base. Se não baseline for especificado, o trabalho de processamento do SageMaker Clarify tentará calcular o conjunto de dados de linha de base dividindo o conjunto de dados tabular em um número ideal de clusters entre e. 1 12 O número de instâncias de linha de base afeta diretamente o runtime da análise SHAP.

      • num_samples: (Opcional) O número de amostras a serem usadas no algoritmo SHAP do Kernel. Se não num_samples for fornecido, o trabalho de processamento do SageMaker Clarify escolherá o número para você. O número de amostras afeta diretamente o tamanho do conjunto de dados sintéticos e o runtime do trabalho.

      • seed: (Opcional) Um número inteiro usado para inicializar o gerador de números pseudo-aleatórios no explicador SHAP para gerar valores SHAP consistentes para o mesmo trabalho. Se a semente não for especificada, toda vez que o mesmo trabalho for executado, o modelo poderá gerar valores SHAP ligeiramente diferentes.

      • use_logit: (Opcional) Valor boleano para indicar se a função logit deve ser aplicada às predições de modelo. O padrão é false. Se o use_logit for true, os valores SHAP serão calculados usando os coeficientes de regressão logística, que podem ser interpretados como razões logarítmicas.

      • save_local_shap_values: (Opcional) Um valor booleano que indica que você deseja que os valores SHAP locais de cada registro no conjunto de dados sejam incluídos no resultado da análise. Padronizado como false.

        Se o conjunto de dados principal estiver dividido em vários arquivos ou o processamento distribuído estiver ativado, especifique também uma coluna identificadora usando o parâmetro joinsource_name_or_index. A coluna identificadora e os valores SHAP locais serão salvos no resultado da análise. Dessa forma, você poderá mapear cada registro para seus valores SHAP locais.

      • agg_method: (Opcional) O método utilizado para agregar os valores locais de SHAP (os valores SHAP para cada instância) de todas as instâncias aos valores globais de SHAP (os valores SHAP para todo o conjunto de dados). Padronizado como mean_abs. Os métodos a seguir podem ser usados para agregar valores SHAP.

        • mean_abs: A média dos valores SHAP locais absolutos de todas as instâncias.

        • mean_abs: A média dos valores locais de SHAP ao quadrado de todas as instâncias.

        • mediana: A média dos valores SHAP locais de todas as instâncias.

      • text_config: Obrigatório para a explicabilidade do processamento de linguagem natural. Inclua esta configuração se desejar tratar as colunas de texto como texto, e explicações devem ser fornecidas para unidades individuais de texto. Para obter um exemplo de uma configuração de análise para explicabilidade do processamento de linguagem natural, consulte Configuração de análise para explicabilidade do processamento de linguagem natural

        • granularidade: A unidade de granularidade para a análise de colunas de texto. Os valores válidos são token, sentence ou paragraph. Cada unidade de texto é considerada um atributo e os valores SHAP locais são calculados para cada unidade.

        • idioma: O idioma das colunas de texto. Os valores válidos são 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. Insira multi-language para obter uma combinação de vários idiomas.

        • max_top_tokens: (Opcional) O número máximo dos principais tokens, com base nos valores globais SHAP. Padronizado como 50. É possível que um token apareça várias vezes no conjunto de dados. O trabalho de processamento do SageMaker Clarify agrega os valores de SHAP de cada token e, em seguida, seleciona os principais tokens com base em seus valores globais de SHAP. Os valores globais SHAP dos principais tokens selecionados estão incluídos na seção global_top_shap_text do arquivo analysis.json.

        • O valor SHAP local da agregação.

      • image_config: Obrigatório para a explicabilidade da visão computacional. Inclua esta configuração se você tiver um conjunto de dados de entrada composto por imagens e desejar analisá-las para explicabilidade em um problema de visão computacional.

        • model_type: O tipo do modelo. Os valores válidos são:

          • IMAGE_CLASSIFICATION para um modelo de classificação de imagens.

          • OBJECT_DETECTION para um modelo de detecção de objetos.

        • max_objects: Aplicável somente quando model_type é OBJECT_DETECTION. O número máximo de objetos, ordenado pela pontuação de confiança, detectado pelo modelo de visão computacional. Todos os objetos classificados abaixo dos max_objects superiores por pontuação de confiança são filtrados. Padronizado como 3.

        • context: Aplicável somente quando model_type é OBJECT_DETECTION. Isso indica se a área ao redor da caixa delimitadora do objeto detectado está mascarada pela imagem de referência ou não. Os valores válidos são 0 para mascarar tudo ou 1 para não mascarar nada. Padronizado como 1.

        • iou_threshold: Aplicável somente quando model_type é OBJECT_DETECTION. A métrica mínima de interseção sobre união (IOU) para avaliar as predições em relação à detecção original. Uma métrica de IOU alta corresponde a uma grande sobreposição entre a caixa de detecção prevista e a caixa de detecção real (ground truth). Padronizado como 0.5.

        • num_segments: (Opcional) Um número inteiro que determina a quantidade aproximada de segmentos a serem rotulados na imagem de entrada. Cada segmento da imagem é considerado um atributo, e valores locais de SHAP são calculados para cada segmento. Padronizado como 20.

        • segment_compactness: (Opcional) Um número inteiro que determina a forma e o tamanho dos segmentos de imagem gerados pelo scikit-image slic. Padronizado como 5.

    • pdp — Inclua esse método para calcular gráficos de dependência parcial (). PDPs Para obter um exemplo de uma configuração de análise a ser gerada PDPs, consulte Calcule gráficos de dependência parcial () PDPs

      • atributos: Obrigatório se o método shap não for solicitado. Uma variedade de nomes de atributos ou índices para calcular e traçar gráficos PDP.

      • top_k_features: (Opcional) Especifica o número dos principais atributos usados para gerar gráficos PDP. Se não features for fornecido, mas o shap método for solicitado, o trabalho de processamento do SageMaker Clarify escolherá os principais recursos com base em suas atribuições SHAP. Padronizado como 10.

      • grid_resolution: O número de buckets nos quais dividir o intervalo de valores numéricos. Isso especifica a granularidade da grade para os gráficos PDP.

    • asymmetric_shapley_value: Inclua esse método se quiser calcular métricas de explicabilidade para modelos de previsão de séries temporais. O trabalho de processamento do SageMaker Clarify suporta o algoritmo de valores assimétricos de Shapley. Os valores assimétricos de Shapley são uma variante do valor de Shapley que eliminam o axioma da simetria. Para obter mais informações, consulte Valores assimétricos de Shapley: como incorporar conhecimento causal à explicabilidade independente do modelo. Use esses valores para determinar como os atributos contribuem para o resultado da previsão. Os valores assimétricos de Shapley levam em consideração as dependências temporais dos dados de séries temporais que os modelos de previsão usam como entrada.

      O algoritmo inclui os seguintes parâmetros:

      • direction: Os tipos disponíveis são chronological, anti_chronological e bidirectional. A estrutura temporal pode ser navegada em ordem cronológica, anticronológica ou ambas. As explicações cronológicas são criadas adicionando informações de forma iterativa desde a primeira etapa. As explicações anticronológicas adicionam informações a partir da última etapa e retrocedendo. A última ordem pode ser mais apropriada na presença de desvio de recenticidade, como para prever os preços de ações.

      • granularity: O detalhamento da explicação a ser usado. As opções de detalhamento disponíveis são as seguintes:

        • timewise: as explicações de timewise são econômicas e fornecem informações apenas sobre intervalos de tempo específicos, como descobrir o quanto as informações do enésimo dia no passado contribuíram para a previsão de tal dia no futuro. As atribuições resultantes não explicam as covariáveis estáticas individualmente e não diferenciam entre séries temporais alvo e relacionadas.

        • fine_grained: As explicações de fine_grained são computacionalmente mais intensivas, mas fornecem uma análise completa de todas as atribuições das variáveis de entrada. O método calcula explicações aproximadas para reduzir o runtime. Para obter mais informações, consulte o parâmetro num_samples.

          nota

          As explicações de fine_grained são compatíveis apenas com a ordem chronological.

      • num_samples: (Opcional) Esse argumento é necessário para explicações de fine_grained. Quanto maior o número, mais precisa é a aproximação. O número deve escalar com a dimensionalidade dos atributos de entrada. Uma regra prática é definir essa variável como (1 + max(número de séries temporais relacionadas, número de covariáveis estáticas))^2 se o resultado não for muito grande.

      • baseline — (Opcional) A configuração da linha de base para substituir out-of-coalition os valores dos conjuntos de dados correspondentes (também conhecidos como dados de segundo plano). O trecho de código a seguir mostra um exemplo de configuração de linha de base:

        {
    "related_time_series": "zero",
    "static_covariates": {
        <item_id_1>: [0, 2],
        <item_id_2>: [-1, 1]
    },
    "target_time_series": "zero"
}

        • Para dados temporais, como séries temporais de destino ou séries temporais relacionadas, os tipos de valores da linha de base podem ser um dos seguintes valores:

          • zero— Todos os out-of-coalition valores são substituídos por 0,0.

          • mean— Todos os out-of-coalition valores são substituídos pela média de uma série temporal.

        • Para covariáveis estáticas, uma entrada de linha de base só deve ser fornecida quando a solicitação do modelo usa valores de covariáveis estáticas. Nesse caso, esse campo é obrigatório. A linha de base deve ser fornecida para cada item como uma lista. Por exemplo, se você tiver um conjunto de dados com duas covariáveis estáticas, sua configuração de linha de base pode ser a seguinte:

          "static_covariates": {
    <item_id_1>: [1, 1],
    <item_id_2>: [0, 1]
}

          No exemplo anterior, <item_id_1> e <item_id_2> são os IDs dos itens do conjunto de dados.

    • report: (Opcional) Use este objeto para personalizar o relatório de análise. Esse parâmetro não é compatível com trabalhos de explicação de séries temporais. Existem três cópias do mesmo relatório como parte do resultado da análise: relatório do caderno Jupyter, relatório HTML e relatório PDF. O objeto tem os seguintes parâmetros:

      • name: Nome do arquivo dos arquivos de relatório. Por exemplo, se name for MyReport, os arquivos de relatório serão MyReport.ipynb, MyReport.html e MyReport.pdf. Padronizado como report.

      • title: (Opcional) String do título para o relatório. Padronizado como SageMaker AI Analysis Report.

  • preditor: Obrigatório se a análise exigir predições de modelo. Por exemplo, quando o método shap, asymmetric_shapley_value, pdp ou post_training_bias é solicitado, mas os rótulos previstos não são fornecidos como parte do conjunto de dados de entrada. A seguir estão os parâmetros a serem usados em conjunto compredictor:

    • model_name — O nome do seu modelo de SageMaker IA criado pela CreateModelAPI. Se você especificar model_name em vez de endpoint_name, o trabalho de processamento do SageMaker Clarify cria um endpoint efêmero com o nome do modelo, conhecido como endpoint sombra, e obtém previsões do endpoint. O trabalho exclui o endpoint de sombra após a conclusão dos cálculos. Se o modelo for multimodelo, então o parâmetro target_model deve ser especificado. Para obter mais informações sobre endpoints multimodelo, consulte Endpoints multimodelo.

    • endpoint_name_prefix: (Opcional) Um prefixo de nome personalizado para o endpoint de sombra. Aplicável se você fornecer model_name em vez de endpoint_name. Por exemplo, forneça endpoint_name_prefix se você deseja restringir o acesso ao endpoint pelo nome do endpoint. O prefixo deve corresponder ao EndpointNamepadrão e seu comprimento máximo é23. Padronizado como sm-clarify.

    • initial_instance_count: Especifica o número de instâncias do endpoint sombra. Obrigatório se você fornecer model_name em vez de endpoint_name. O valor para initial_instance_count pode ser diferente do valor InstanceCountdo trabalho, mas recomendamos uma proporção de 1:1.

    • instance_type: Especifica o tipo de instância para o endpoint sombra. Obrigatório se você fornecer model_name em vez de endpoint_name. Por exemplo, instance_type pode ser definido como “ml.m5.large”. Em alguns casos, o valor especificado para instance_type pode ajudar a reduzir o tempo de inferência do modelo. Por exemplo, para funcionar com eficiência, os modelos de processamento de linguagem natural e os Modelos de visão computadorizada normalmente exigem um tipo de instância de unidade de processamento gráfico (GPU).

    • endpoint_name — O nome do seu endpoint de SageMaker IA criado pela API. CreateEndpoint Se fornecido, endpoint_name tem precedência sobre o parâmetro model_name. Usar um endpoint existente reduz o tempo de inicialização do shadow endpoint, mas também pode causar um aumento significativo na carga desse endpoint. Além disso, alguns métodos de análise (como shap e pdp) geram conjuntos de dados sintéticos que são enviados para o endpoint. Isso pode fazer com que as métricas do endpoint ou os dados capturados sejam contaminados por dados sintéticos, que podem não refletir com precisão o uso no mundo real. Por esses motivos, geralmente não é recomendável usar um endpoint de produção existente para a análise do SageMaker Clarify.

    • target_model — O valor da string que é passado para o TargetModel parâmetro da API de SageMaker IA InvokeEndpoint. Obrigatório se o seu modelo (especificado pelo parâmetro model_name) ou endpoint (especificado pelo parâmetro endpoint_name) for multimodelo. Para obter mais informações sobre endpoints multimodelo, consulte Endpoints multimodelo.

    • custom_attributes: (Opcional) Uma string que permite fornecer informações adicionais sobre uma solicitação de inferência enviada ao endpoint. O valor da string é passado para o CustomAttributes parâmetro da InvokeEndpointAPI SageMaker AI.

    • content_type: content_type: O formato de entrada do modelo a ser usado para obter predições do endpoint. Se fornecido, ele é passado para o ContentType parâmetro da InvokeEndpointAPI de SageMaker IA.

      • Para explicabilidade por visão computacional, os valores válidos são image/jpeg, image/png ou application/x-npy. Se content_type não for fornecido, o valor padrão será image/jpeg.

      • Para explicabilidade da previsão de séries temporais, o valor válido é application/json.

      • Para outros tipos de explicabilidade, os valores válidos são text/csv, application/jsonlines, e application/json. Um valor para content_type é necessário se dataset_type for application/x-parquet. Caso contrário, content_type assume o valor do parâmetro dataset_type.

    • accept_type: O formato da saída do modelo a ser usado para obter predições do endpoint. O valor de accept_type é passado para o Accept parâmetro da InvokeEndpointAPI SageMaker AI.

      • Para explicabilidade da visão computacional, se model_type for "OBJECT_DETECTION", então accept_type será padronizado como application/json.

      • Para explicabilidade da previsão de séries temporais, o valor válido é application/json.

      • Para outros tipos de explicabilidade, os valores válidos são text/csv, application/jsonlines e application/json. Se um valor para accept_type não for fornecido, accept_type assume como padrão o valor do parâmetro content_type.

    • content_template: Uma string de modelo usada para construir a entrada do modelo a partir dos registros do conjunto de dados. O parâmetro content_template só será usado e obrigatório se o valor do parâmetro content_type for application/jsonlines ou application/json.

      Quando o parâmetro content_type for application/jsonlines, o modelo deverá ter apenas um espaço reservado, $features, que é substituído por uma lista de atributos em runtime. Por exemplo, se o modelo for "{\"myfeatures\":$features}", e se um registro tiver três valores de atributo numérico: 1, 2 e 3, então o registro será enviado ao modelo como Linha JSON {"myfeatures":[1,2,3]}.

      Quando content_type estiver application/json, o modelo pode ter espaço reservado $record ou records. Se o espaço reservado for record, um único registro será substituído por um registro que tenha o modelo record_template aplicado a ele. Nesse caso, somente um único registro será enviado ao modelo por vez. Se o espaço reservado for $records, os registros serão substituídos por uma lista de registros, cada um com um modelo fornecido por record_template.

    • record_template: Uma sequência de modelos a ser usada para construir cada registro da entrada do modelo a partir de instâncias do conjunto de dados. Ele só é usado e exigido quando content_type é application/json. A string do modelo pode conter um dos seguintes:

      • Um parâmetro $features de espaço reservado que é substituído por uma matriz de valores de atributos. Um espaço reservado opcional adicional pode substituir os nomes dos cabeçalhos das colunas de atributos em $feature_names. Este espaço reservado opcional será substituído por uma variedade de nomes de atributos.

      • Exatamente um espaço reservado $features_kvp que é substituído pelos pares de valores-chave, nome do atributo e valor do atributo.

      • Um atributo na headers configuração. Por exemplo, um nome de atributo A, indicado pela sintaxe do espaço reservado "${A}", será substituído pelo valor do atributo para A.

      O valor de record_template é usado com content_template para construir a entrada do modelo. Segue um exemplo de configuração que mostra como construir uma entrada de modelo usando um modelo de conteúdo e registro.

      No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:

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

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

      A entrada do modelo de exemplo é a seguinte:

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

      Seguem os valores do exemplo content_template e dos parâmetros record_template para construir a entrada do modelo de exemplo anterior.

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

      • record_template: "$features"

      No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:

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

      Seguem os valores do exemplo content_template e dos parâmetros record_template para construir a entrada do modelo de exemplo anterior.

      • content_template: "$records"

      • record_template: "$features_kvp"

      Segue um exemplo de código alternativo para construir o exemplo anterior de entrada do modelo.

      • content_template: "$records"

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

      No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:

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

      Os valores dos parâmetros content_template e record_template de exemplo a serem construídos acima: a entrada do modelo de exemplo anterior segue.

      • content_template: "$record"

      • record_template: "$features_kvp"

      Para obter mais exemplos, consulte Solicitações de endpoint para dados de séries temporais.

    • label — (Opcional) Um índice inteiro baseado em zero ou uma string de JMESPath expressão usada para extrair rótulos previstos da saída do modelo para análise de viés. Se o modelo for multiclasse e o parâmetro label extrair todos os rótulos previstos da saída do modelo, o seguinte se aplica: Esse atributo não é compatível com séries temporais.

      • O parâmetro probability é necessário para obter as probabilidades (ou pontuações) correspondentes da saída do modelo.

      • O rótulo previsto da pontuação mais alta é escolhido.

      O valor de label depende do valor do parâmetro accept_type conforme a seguir.

      • Se accept_type for text/csv, então label é o índice de quaisquer rótulos previstos na saída do modelo.

      • Se accept_type for application/jsonlines ouapplication/json, então label é uma JMESPath expressão aplicada à saída do modelo para obter os rótulos previstos.

    • label_headers: (Opcional) Uma matriz de valores que o rótulo pode usar no conjunto de dados. Se a análise de tendências for solicitada, o parâmetro probability também será necessário para obter os valores de probabilidade (pontuações) correspondentes da saída do modelo, e o rótulo previsto da pontuação mais alta será escolhido. Se a análise de explicabilidade for solicitada, os cabeçalhos das etiquetas serão usados para embelezar o relatório de análise. É necessário um valor label_headers para para a explicabilidade da visão computacional. Por exemplo, para um problema de classificação multiclasse, se o rótulo tiver três valores possíveis, bird, cat e dog, então label_headers deve ser definido como ["bird","cat","dog"].

    • probabilidade — (Opcional) Um índice inteiro baseado em zero ou uma string de JMESPath expressão usada para extrair probabilidades (pontuações) para análise de explicabilidade (mas não para explicabilidade de séries temporais) ou para escolher o rótulo previsto para análise de viés. O valor de probability depende do valor do parâmetro accept_type 9737accept_type conforme a seguir.

      • Se accept_type for text/csv, probability é o índice das probabilidades (pontuações) na saída do modelo. Se probability não for fornecido, toda a saída do modelo é considerada como probabilidades (pontuações).

      • Se accept_type forem dados JSON (application/jsonlinesouapplication/json), probability deve ser uma JMESPath expressão usada para extrair as probabilidades (pontuações) da saída do modelo.

    • time_series_predictor_config: (Opcional) Usado somente para explicabilidade de séries temporais. Usado para instruir o processador do SageMaker Clarify a analisar dados corretamente a partir dos dados transmitidos como um URI do S3. dataset_uri

      • previsão — Uma JMESPath expressão usada para extrair o resultado da previsão.

Exemplo de arquivos de configuração de análise

As seções a seguir contêm exemplos de arquivos de configuração de análise para dados em formato CSV, formato JSON Lines e para processamento de linguagem natural (PLN), visão computacional (CV) e explicabilidade de séries temporais (TS).

Os exemplos a seguir mostram como configurar a análise de polarização e explicabilidade para um conjunto de dados tabular em formato CSV. Nesses exemplos, o conjunto de dados de entrada tem quatro colunas de atributos e uma coluna de rótulo binário, Target. O conteúdo do conjunto de dados é o seguinte: O valor do rótulo 1 indica um resultado positivo. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada dataset de processamento.

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

As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) mostrando a importância do recurso para um conjunto de dados no formato CSV.

Calcular todas as métricas de tendências do pré-treinamento

Este exemplo de configuração mostra como medir se o conjunto de dados de amostra anterior está favoravelmente inclinado para amostras com um Gender valor de 0. A configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés pré-treinamento para o conjunto de dados.

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

Calcular todas as métricas de tendências do pós-treinamento

Você pode calcular as métricas de desvio pré-treinamento antes do treinamento. No entanto, para calcular as métricas de desvio do pós-treinamento, você deve ter um modelo treinado. O exemplo de saída a seguir é de um modelo de classificação binária que gera dados no formato CSV. Neste exemplo de saída, cada linha contém duas colunas. A primeira coluna contém o rótulo previsto e a segunda coluna contém o valor de probabilidade desse rótulo. 

0,0.028986845165491
1,0.825382471084594
...

O exemplo de configuração a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis usando o conjunto de dados e as previsões da saída do modelo. No exemplo, o modelo é implantado em um endpoint your_endpoint de SageMaker IA.

nota

No código de exemplo a seguir, o parâmetro content_type e não accept_type estão definidos. Portanto, eles usam automaticamente o valor do parâmetro dataset_type, que é 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
    }
}

Calcular os valores SHAP

O exemplo de configuração de análise a seguir instrui o trabalho a calcular os valores SHAP designando a Target coluna como rótulos e todas as outras colunas como atributos.

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

Neste exemplo, o parâmetro de baseline do SHAP é omitido e o valor do parâmetro num_clusters é 1. Isso instrui o processador SageMaker Clarify a calcular uma amostra de linha de base do SHAP. Neste exemplo, a probabilidade é definida como 1. Isso instrui o trabalho de processamento do SageMaker Clarify a extrair a pontuação de probabilidade da segunda coluna da saída do modelo (usando indexação baseada em zero).

Calcule gráficos de dependência parcial () PDPs

O exemplo a seguir mostra como visualizar a importância do Income recurso no relatório de análise usando PDPs. O parâmetro do relatório instrui o trabalho de processamento do SageMaker Clarify a gerar um relatório. Após a conclusão do trabalho, o relatório gerado é salvo como report.pdf no analysis_result local. O parâmetro grid_resolution dividia o intervalo dos valores do atributo em 10 buckets . Juntos, os parâmetros especificados no exemplo a seguir instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP Income com 10 segmentos no eixo x. O eixo y mostrará o impacto marginal de Income nas predições.

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

Calcular as métricas de desvio e a importância do atributo

Você pode combinar todos os métodos dos exemplos de configuração anteriores em um único arquivo de configuração de análise e calculá-los todos em um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas.

Neste exemplo, o parâmetro probability é definido 1 para indicar que as probabilidades estão contidas na segunda coluna (usando indexação baseada em zero). No entanto, como a análise de desvio precisa de um rótulo previsto, o parâmetro probability_threshold é definido 0.5 para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro top_k_features do método pdp de gráficos de dependência parcial é definido como 2. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular gráficos de dependência parcial (PDPs) para os principais 2 recursos com os maiores valores globais de SHAP. 

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

Em vez de implantar o modelo em um endpoint, você pode fornecer o nome do seu modelo de SageMaker IA ao trabalho de processamento do SageMaker Clarify usando o model_name parâmetro. O exemplo a seguir mostra como especificar um modelo chamado your_model. O trabalho de processamento do SageMaker Clarify criará um endpoint paralelo usando a configuração.

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

Os exemplos a seguir mostram como configurar a análise de desvio e a análise de explicabilidade para um conjunto de dados tabular no formato JSON Lines. Nesses exemplos, o conjunto de dados de entrada tem os mesmos dados da seção anterior, mas eles estão no formato denso SageMaker AI JSON Lines. Cada linha é um objeto JSON válido. A chave "Recursos" se refere a uma matriz de valores de atributos, e a chave "Rótulo" aponta para o rótulo de veracidade. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada de processamento do “conjunto de dados”. Para obter mais informações sobre linhas JSON, consulte Formato da solicitação 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}
...

As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) mostrando a importância do recurso para um conjunto de dados no formato JSON Lines.

Calcular as métricas de desvio pré-treinamento

Especifique o rótulo, os atributos, o formato e os métodos para medir as métricas de desvio antes do treinamento em um Gender valor de 0. No exemplo a seguir, o parâmetro headers fornece primeiro os nomes dos atributos. O nome do rótulo é fornecido por último. Por convenção, o último cabeçalho é o cabeçalho do rótulo.

O features parâmetro é definido com a JMESPath expressão “Recursos” para que o trabalho de processamento do SageMaker Clarify possa extrair a matriz de recursos de cada registro. O label parâmetro é definido como a JMESPath expressão “Label” para que a tarefa de processamento do SageMaker Clarify possa extrair o rótulo de verdade fundamental de cada registro. Use um nome de faceta para especificar o atributo sigiloso, da seguinte forma:

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

Calcular todas as métricas de desvio

Você deve ter um modelo treinado para calcular as métricas de desvio pós-treinamento. O exemplo a seguir é de um modelo de classificação binária que gera dados de linhas JSON no formato do exemplo. Cada linha da saída do modelo é um objeto JSON válido. A chave predicted_label refere-se ao rótulo previsto e a chave probability refere-se ao valor da probabilidade.

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

Você pode implantar o modelo em um endpoint de SageMaker IA chamadoyour_endpoint. O exemplo de configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis para o conjunto de dados e o modelo. No exemplo, os parâmetros content_type e accept_type não estão incluídos. Portanto, eles são configurados automaticamente para usar o valor do parâmetro dataset_type, que é application/jsonlines. O trabalho de processamento do SageMaker Clarify usa o content_template parâmetro para compor a entrada do modelo, substituindo o $features espaço reservado por uma matriz de recursos.

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

Calcular os valores SHAP

Como a análise SHAP não precisa de um rótulo de veracidade fundamental, o parâmetro label é omitido. Neste exemplo, o parâmetro headers também é omitido. Portanto, a tarefa de processamento do SageMaker Clarify deve gerar espaços reservados usando nomes genéricos, como column_0 ou column_1 para cabeçalhos de recursos, e label0 para um cabeçalho de rótulo. Você pode especificar valores para headers e para um label melhorar a legibilidade do resultado da análise. Como o parâmetro de probabilidade está definido como JMESPath expressãoprobability, o valor da probabilidade será extraído da saída do modelo. Veja a seguir um exemplo do cálculo dos valores SHAP.

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

Calcule gráficos de dependência parcial () PDPs

O exemplo a seguir mostra como visualizar a importância de “Renda” no PDP. Neste exemplo, os cabeçalhos dos atributos não são fornecidos. Portanto, o parâmetro features do método pdp deve usar índice baseado em zero para se referir à localização da coluna de atributos. O parâmetro grid_resolution dividia o intervalo dos valores do atributo em 10 buckets . Juntos, os parâmetros no exemplo instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP Income com 10 segmentos no eixo x. O eixo y mostrará o impacto marginal de Income nas predições.

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

Calcular as métricas de desvio e a importância do atributo

Você pode combinar todos os métodos anteriores em um único arquivo de configuração de análise e calculá-los todos em um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas. Neste exemplo, o parâmetro probability está definido. Mas como a análise de desvio precisa de um rótulo previsto, o parâmetro probability_threshold é definido como 0.5 para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro top_k_features do método pdp é definido como 2. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular PDPs os principais 2 recursos com os maiores valores globais de SHAP.

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

Os exemplos a seguir mostram como configurar a análise de desvio e explicabilidade para um conjunto de dados tabular no formato JSON. Nesses exemplos, o conjunto de dados de entrada tem os mesmos dados da seção anterior, mas eles estão no formato denso SageMaker AI JSON. Para obter mais informações sobre linhas JSON, consulte Formato da solicitação JSONLINES.

Toda a solicitação de entrada é um JSON válido, em que a estrutura externa é uma lista e cada elemento é o dado de um registro. Em cada registro, a chave Features se refere a uma matriz de valores de atributos, e a chave Label se refere ao rótulo de veracidade. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada dataset de processamento.

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

As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) que mostram a importância do recurso para um conjunto de dados no formato JSON Lines.

Calcular as métricas de desvio pré-treinamento

Especifique o rótulo, os atributos, o formato e os métodos para medir as métricas de desvio antes do treinamento em um Gender valor de 0. No exemplo a seguir, o parâmetro headers fornece primeiro os nomes dos atributos. O nome do rótulo é fornecido por último. Para conjuntos de dados JSON, o último cabeçalho é o cabeçalho do rótulo.

O features parâmetro é definido como a JMESPath expressão que extrai uma matriz ou matriz 2D. Cada linha nessa matriz deve conter a lista de Features para cada registro. O label parâmetro é definido como uma JMESPath expressão que extrai uma lista de rótulos de verdade básica. Cada elemento dessa lista deve conter o rótulo de um registro.

Use um nome de faceta para especificar o atributo sigiloso, da seguinte forma:

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

Calcular todas as métricas de desvio

Você deve ter um modelo treinado para calcular as métricas de desvio pós-treinamento. O exemplo de código a seguir é de um modelo de classificação binária que gera dados JSON no formato do exemplo. No exemplo, cada elemento abaixo predictions é a saída de predição de um registro. A chave predicted_label refere-se ao rótulo previsto e a chave probability refere-se ao valor da probabilidade.

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

Você pode implantar o modelo em um endpoint de SageMaker IA chamadoyour_endpoint.

No exemplo a seguir, os parâmetros content_type e accept_type não estão definidos. Portanto, content_type e accept_type são automaticamente configurados para usar o valor do parâmetro dataset_type, que é application/json. Em seguida, o trabalho de processamento do SageMaker Clarify usa o content_template parâmetro para compor a entrada do modelo.

No exemplo a seguir, a entrada do modelo é composta pela substituição do $records espaço reservado por uma matriz de registros. Em seguida, o parâmetro record_template compõe a estrutura JSON de cada registro e substitui o $features espaço reservado pela matriz de atributos de cada registro.

O exemplo de configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis para o conjunto de dados e o 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"
    }
}

Calcular os valores SHAP

Não é necessário especificar um rótulo para a análise SHAP. No exemplo a seguir, o parâmetro headers não está especificado. Portanto, o trabalho de processamento do SageMaker Clarify gerará espaços reservados usando nomes genéricos, como column_0 ou column_1 para cabeçalhos de recursos, e label0 para um cabeçalho de rótulo. Você pode especificar valores para headers e para um label melhorar a legibilidade do resultado da análise.

No exemplo de configuração a seguir, o parâmetro de probabilidade é definido como uma JMESPath expressão que extrai as probabilidades de cada predição para cada registro. Veja a seguir um exemplo do cálculo dos 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"
    }
}

Calcule gráficos de dependência parcial () PDPs

O exemplo a seguir mostra como visualizar a importância de um recurso no PDPs. No exemplo, os cabeçalhos dos atributos não são fornecidos. Portanto, o parâmetro features do método pdp deve usar índice baseado em zero para se referir à localização da coluna de atributos. O parâmetro grid_resolution dividia o intervalo dos valores do atributo em 10 buckets .

Juntos, os parâmetros no exemplo a seguir instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP Income com 10 segmentos no eixo x. O eixo y mostra o impacto marginal de Income nas predições.

O exemplo de configuração a seguir mostra como visualizar a importância de Income ativado PDPs.

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

Calcular as métricas de desvio e a importância do atributo

Você pode combinar todos os métodos de configuração anteriores em um único arquivo de configuração de análise e calculá-los todos com um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas.

Neste exemplo, o parâmetro probability está definido. Como a análise de desvio precisa de um rótulo previsto, o probability_threshold parâmetro é definido como 0.5, que é usado para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro top_k_features do método pdp é definido como 2. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular PDPs os principais 2 recursos com os maiores valores globais de SHAP.

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

O exemplo a seguir mostra um arquivo de configuração de análise para calcular a importância do atributo para processamento de linguagem natural (PLN). Neste exemplo, o conjunto de dados de entrada é um conjunto de dados tabular em formato CSV, com uma coluna de rótulo binário e duas colunas de atributos, como segue. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pelo parâmetro dataset de entrada de processamento.

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

Neste exemplo, um modelo de classificação binária foi treinado no conjunto de dados anterior. O modelo aceita dados CSV e gera uma única pontuação entre 0 e 1, como segue.

0.491656005382537
0.569582343101501
...

O modelo é usado para criar um modelo de SageMaker IA chamado “your_model”. A configuração de análise a seguir mostra como executar uma análise de explicabilidade baseada em token usando o modelo e o conjunto de dados. O parâmetro text_config ativa a análise de explicabilidade da PNL. O parâmetro granularity indica que a análise deve analisar os tokens.

Em inglês, cada token é uma palavra. O exemplo a seguir também mostra como fornecer uma instância de "linha de base" SHAP no local usando uma "Classificação" média de 4. Um token de máscara especial "[MASK]" é usado para substituir um token (palavra) em "Comentários". Este exemplo também usa um tipo de instância de endpoint de GPU para acelerar a inferência.

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

O exemplo a seguir mostra a importância de um atributo de computação de arquivo de configuração de análise para visão computacional. Neste exemplo, o conjunto de dados de entrada consiste em imagens JPEG. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pelo parâmetro dataset de entrada de processamento. O exemplo mostra como configurar uma análise de explicabilidade usando um modelo de classificação de imagens de SageMaker IA. No exemplo, um modelo denominado your_cv_ic_model foi treinado para classificar os animais nas imagens 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 obter mais informações sobre classificação de imagem, consulte Classificação de imagens - MXNet.

Neste exemplo, um modelo de detecção de objetos de SageMaker IA your_cv_od_model é treinado nas mesmas imagens JPEG para identificar os animais nelas. O exemplo a seguir mostra como configurar uma análise de explicabilidade para o modelo de detecção 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"]
    }
}

O exemplo a seguir mostra um arquivo de configuração de análise para o cálculo da importância do atributo para uma série temporal (TS). No exemplo, o conjunto de dados de entrada é um conjunto de dados de série temporal no formato JSON com um conjunto de atributos de covariáveis dinâmicas e estáticas. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pelo parâmetro de entrada de processamento do conjunto de dados. dataset_uri

[
    {
        "item_id": "item1",
        "timestamp": "2019-09-11",
        "target_value": 47650.3,
        "dynamic_feature_1": 0.4576,
        "dynamic_feature_2": 0.2164,
        "dynamic_feature_3": 0.1906,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item1",
        "timestamp": "2019-09-12",
        "target_value": 47380.3,
        "dynamic_feature_1": 0.4839,
        "dynamic_feature_2": 0.2274,
        "dynamic_feature_3": 0.1889,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item2",
        "timestamp": "2020-04-23",
        "target_value": 35601.4,
        "dynamic_feature_1": 0.5264,
        "dynamic_feature_2": 0.3838,
        "dynamic_feature_3": 0.4604,
        "static_feature_1": 1,
        "static_feature_2": 2
    },
]

As seções a seguir explicam como calcular atribuições de atributos para um modelo de previsão com o algoritmo de valores assimétricos de Shapley para um conjunto de dados JSON.

Calcular as explicações para modelos de previsão de séries temporais

O exemplo de configuração de análise a seguir exibe as opções usadas pelo trabalho para calcular as explicações dos modelos de previsão de séries temporais.

{
    'dataset_type': 'application/json',
    'dataset_uri': 'DATASET_URI',
    'methods': {
        'asymmetric_shapley_value': {
            'baseline': {
                "related_time_series": "zero",
                "static_covariates": {
                    "item1": [0, 0], "item2": [0, 0]
                },
                "target_time_series": "zero"
            },
            'direction': 'chronological',
            'granularity': 'fine_grained',
            'num_samples': 10
        },
        'report': {'name': 'report', 'title': 'Analysis Report'}
    },
    'predictor': {
        'accept_type': 'application/json',
        'content_template': '{"instances": $records}',
        'endpoint_name': 'ENDPOINT_NAME', 
        'content_type': 'application/json',              
        'record_template': '{
            "start": $start_time, 
            "target": $target_time_series, 
            "dynamic_feat": $related_time_series, 
            "cat": $static_covariates
        }',
        'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
    },
    'time_series_data_config': {
        'dataset_format': 'timestamp_records',
        'item_id': '[].item_id',
        'related_time_series': ['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
        'static_covariates': ['[].static_feature_1', '[].static_feature_2'],
        'target_time_series': '[].target_value',
        'timestamp': '[].timestamp'
    }
}
Configuração de explicabilidade de séries temporais

O exemplo anterior usa asymmetric_shapley_value in methods para definir os argumentos de explicabilidade da série temporal, como linha de base, direção, granularidade e número de amostras. Os valores da linha de base são definidos para todos os três tipos de dados: séries temporais relacionadas, covariáveis estáticas e séries temporais de destino. Esses campos instruem o processador do SageMaker Clarify a calcular as atribuições de recursos para um item por vez.

Configuração do preditor

Você pode controlar totalmente a estrutura de carga útil que o processador SageMaker Clarify envia usando a JMESPath sintaxe. No exemplo anterior, a configuração predictor instrui o Clarify a agregar registros em '{"instances": $records}', onde cada registro é definido com os argumentos fornecidos para record_template no exemplo. Observe que $start_time, $target_time_series, $related_time_series e $static_covariates são tokens internos usados para mapear valores de conjuntos de dados para valores de solicitação de endpoint.

Da mesma forma, o atributo forecast em time_series_predictor_config é usado para extrair a predição de modelo da resposta do endpoint. Por exemplo, a resposta em lote do endpoint pode ser:

{
    "predictions": [
        {"mean": [13.4, 3.6, 1.0]}, 
        {"mean": [23.0, 4.7, 3.0]}, 
        {"mean": [3.4, 5.6, 2.0]}
    ]
}

Suponha que você especifique a seguinte configuração do preditor de séries temporais:

'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}

O valor da previsão é interpretado da seguinte forma:

[
    [13.4, 3.6],
    [23.0, 4.7],
    [3.4, 5.6]
]
Dados de configuração

Use o time_series_data_config atributo para instruir o processador do SageMaker Clarify a analisar os dados corretamente a partir dos dados transmitidos como um URI do S3. dataset_uri