SHAP

Use SHAP para descrever como um modelo preditivo ajustado mapeia entradas para saídas. Trabalhe a partir da API moderna shap.Explanation, torne a saída explicada e a distribuição de fundo explícitas, e valide cada explicação antes de interpretá-la.

Esta habilidade está alinhada com SHAP 0.52.0 (lançado em 28/05/2026). Essa versão requer Python 3.12 ou mais recente.

Os exemplos mantidos foram verificados em Python 3.12.10 com SHAP 0.52.0, NumPy 2.5.3, pandas 3.0.6, scikit-learn 1.9.1 e matplotlib 3.11.2. Testes nativos cobrem jogos de árvores pequenas, exatos, de permutação, de partição, lineares, aditivos, de kernel, de texto e de imagem constante; verificações adicionais de fumaça do XGBoost 3.4.1 numérico cobrem saídas brutas, de probabilidade, de perda e de interação. Trechos de referência que exigem um modelo de projeto, framework ou dados são modelos de adaptação; integrações opcionais pré-treinadas/profundas, de GPU e distribuídas permanecem ilustrativas e requerem sua própria validação de tempo de execução.

Regras de Operação

1. Explique um modelo fixo e avaliado; não use SHAP como substituto para validação preditiva.
2. Use linhas de análise retidas ou claramente rotuladas para explicações. Escolha linhas de fundo apenas de uma população de treinamento ou referência apropriada.
3. Declare a saída explicada: valor de regressão, margem bruta, probabilidade, perda logarítmica, logit ou outro método do modelo.
4. Prefira objetos shap.Explanation e explainer(X). Algumas opções especializadas ainda exigem .shap_values(X), incluindo saídas classificadas profundas, orçamentos de amostragem de gradiente e nsamples do Kernel SHAP. Preserve seus índices de saída e linhas de base explicitamente.
5. Para modelos de saída múltipla, selecione uma saída antes de usar gráficos tabulares: explanation[..., output_index].
6. Verifique base_values + values.sum(...) contra a saída exata do modelo que está sendo explicado.
7. Trate SHAP como uma descrição do comportamento do modelo sob uma escolha de mascaramento/fundo. Ele não estabelece causalidade, justiça, recurso ou mecanismo científico.
8. Nunca silencie uma falha de aditividade até que a forma de entrada, pré-processamento, versão do modelo, espaço de saída e ordenação das linhas tenham sido verificados.
9. Não carregue artefatos de pickle, joblib, modelo ou explainer não confiáveis; esses formatos podem executar código durante a desserialização.

Instalar

Crie um ambiente isolado e fixe a versão documentada:

uv venv --python 3.12
source .venv/bin/activate
uv pip install "shap[plots]==0.52.0"

shap[plots] instala as dependências de plotagem. Adicione o pacote do modelo ajustado em uma versão compatível com o projeto. Para compatibilidade com versões mais antigas do Python, leia references/migration.md em vez de instalar silenciosamente uma versão diferente do SHAP.

Confirme o ambiente antes de depurar uma incompatibilidade de API:

import platform
import shap

print("Python:", platform.python_version())
print("SHAP:", shap.__version__)

Fluxo de Trabalho Padrão

1. Defina o alvo da explicação

Registre:

• versão do modelo e do pré-processamento;
• chamada exata ou método do modelo sendo explicado;
• nome/índice e unidades da saída;
• linhas de avaliação;
• população de fundo/referência;
• algoritmo de masker e explainer;
• versões do SHAP e da biblioteca do modelo.

Para classificadores, decida se a tarefa requer margens brutas ou probabilidades. Os padrões diferem por família de modelo; nunca infira unidades da cor ou sinal do gráfico.

2. Selecione um explainer e masker

Comece com shap.Explainer(model, masker) quando o despacho automático for suficiente. Instancie um explainer especializado quando suas suposições ou controles de saída forem importantes.

…