Codebeispiele: SDK für Python

Dieser Abschnitt enthält Beispielcode zum Erstellen und Aufrufen eines Endpunkts, der die Online-Erklärbarkeit von SageMaker Clarify verwendet. In diesen Codebeispielen wird der AWS SDKfür Python verwendet.

Tabellendaten

Das folgende Beispiel verwendet tabellarische Daten und ein SageMaker Modell namensmodel_name. In diesem Beispiel akzeptiert der Modellcontainer Daten im CSV Format, und jeder Datensatz hat vier numerische Merkmale. In dieser Minimalkonfiguration sind die SHAP Basisdaten nur zu Demonstrationszwecken auf Null gesetzt. Weitere Informationen SHAPGrundlinien für die Erklärbarkeit zur Auswahl geeigneterer Werte für finden Sie unterShapBaseline.

Konfigurieren Sie den Endpunkt wie folgt:



endpoint_config_name = 'tabular_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
    EndpointConfigName=endpoint_config_name,
    ProductionVariants=[{
        'VariantName': 'AllTraffic',
        'ModelName': model_name,
        'InitialInstanceCount': 1,
        'InstanceType': 'ml.m5.xlarge',
    }],
    ExplainerConfig={
        'ClarifyExplainerConfig': {
            'ShapConfig': {
                'ShapBaselineConfig': {
                    'ShapBaseline': '0,0,0,0',
                },
            },
        },
    },
)

Verwenden Sie die Endpunktkonfiguration, um einen Endpunkt wie folgt zu erstellen:


endpoint_name = 'tabular_explainer_endpoint'
response = sagemaker_client.create_endpoint(
    EndpointName=endpoint_name,
    EndpointConfigName=endpoint_config_name,
)

Verwenden Sie den DescribeEndpointAPI, um den Fortschritt bei der Erstellung eines Endpunkts wie folgt zu überprüfen:


response = sagemaker_client.describe_endpoint(
    EndpointName=endpoint_name,
)
response['EndpointStatus']

Wenn der Endpunktstatus "InService" lautet, rufen Sie den Endpunkt mit einem Testdatensatz wie folgt auf:


response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',
)

Anmerkung

Im vorherigen Codebeispiel übergeben Sie bei Multimodell-Endpunkten einen zusätzlichen TargetModel-Parameter in der Anfrage, um anzugeben, auf welches Modell der Endpunkt ausgerichtet werden soll.

Gehen Sie davon aus, dass die Antwort den Statuscode 200 (kein Fehler) hat, und laden Sie den Antworttext wie folgt:


import codecs
import json
json.load(codecs.getreader('utf-8')(response['Body']))

Die Standardaktion für den Endpunkt besteht darin, den Datensatz zu erklären. Im Folgenden wird eine Beispielausgabe im zurückgegebenen JSON Objekt gezeigt.


{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv; charset=utf-8",
        "data": "0.0006380207487381"
    },
    "explanations": {
        "kernel_shap": [
            [
                {
                    "attributions": [
                        {
                            "attribution": [-0.00433456]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [-0.005369821]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [0.007917749]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [-0.00261214]
                        }
                    ]
                }
            ]
        ]
    }
}

Verwenden Sie den EnableExplanations-Parameter, um Erklärungen auf Abruf wie folgt zu aktivieren:


response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',
    EnableExplanations='[0]>`0.8`',
)

Anmerkung

In diesem Beispiel ist der Prognosewert kleiner als der Schwellenwert von 0.8, sodass der Datensatz nicht erklärt wird:


{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv; charset=utf-8",
        "data": "0.6380207487381995"
    },
    "explanations": {}
}

Verwenden Sie Visualisierungstools, um die zurückgegebenen Erklärungen zu interpretieren. Die folgende Abbildung zeigt, wie SHAP Diagramme verwendet werden können, um zu verstehen, wie jedes Merkmal zur Vorhersage beiträgt. Der Basiswert im Diagramm, auch Erwartungswert genannt, ist der Mittelwert der Vorhersagen des Trainingsdatensatzes. Features, die den Erwartungswert nach oben treiben, sind rot und Features, die den Erwartungswert nach unten drücken, sind blau. Weitere Informationen finden Sie unter Layout für SHAP additive Kräfte.

SHAPBeispieldiagramm, das verwendet werden kann, um zu verstehen, wie jedes Merkmal zur Vorhersage beiträgt.

Siehe Vollständiges Beispiel-Notebook für Tabellendaten.

Textdaten

Dieser Abschnitt enthält ein Codebeispiel zum Erstellen und Aufrufen eines Online-Erklärbarkeitsendpunkts für Textdaten. Das Codebeispiel verwendet SDK für Python.

Das folgende Beispiel verwendet Textdaten und ein SageMaker Modell namensmodel_name. In diesem Beispiel akzeptiert der Modellcontainer Daten im CSV Format, und jeder Datensatz ist eine einzelne Zeichenfolge.


endpoint_config_name = 'text_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
    EndpointConfigName=endpoint_config_name,
    ProductionVariants=[{
        'VariantName': 'AllTraffic',
        'ModelName': model_name,
        'InitialInstanceCount': 1,
        'InstanceType': 'ml.m5.xlarge',
    }],
    ExplainerConfig={
        'ClarifyExplainerConfig': {
            'InferenceConfig': {
                'FeatureTypes': ['text'],
                'MaxRecordCount': 100,
            },
            'ShapConfig': {
                'ShapBaselineConfig': {
                    'ShapBaseline': '"<MASK>"',
                },
                'TextConfig': {
                    'Granularity': 'token',
                    'Language': 'en',
                },
                'NumberOfSamples': 100,
            },
        },
    },
)

ShapBaseline: Ein spezielles Token, das für die Verarbeitung natürlicher Sprache (NLP) reserviert ist.
FeatureTypes: Identifiziert das Feature als Text. Wenn dieser Parameter nicht angegeben wird, versucht der Erklärer, den Feature-Typ abzuleiten.
TextConfig: Gibt die Granularitätseinheit und die Sprache für die Analyse von Textmerkmalen an. In diesem Beispiel ist die Sprache Englisch, und Granularität token bedeutet ein Wort im englischen Text.
NumberOfSamples: Ein Limit für die Festlegung der Obergrenzen der Größe des synthetischen Datensatzes.
MaxRecordCount: Die maximale Anzahl von Datensätzen in einer Anfrage, die der Modellcontainer verarbeiten kann. Dieser Parameter dient der Leistungsstabilisierung.

Verwenden Sie die Endpunktkonfiguration, um den Endpunkt wie folgt zu erstellen:


endpoint_name = 'text_explainer_endpoint'
response = sagemaker_client.create_endpoint(
    EndpointName=endpoint_name,
    EndpointConfigName=endpoint_config_name,
)

Nachdem der Status des Endpunkts auf InService gesetzt wurde, rufen Sie den Endpunkt auf. Im folgenden Codebeispiel wird ein Testdatensatz wie folgt verwendet:


response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='"This is a good product"',
)

Wenn die Anfrage erfolgreich abgeschlossen wurde, gibt der Antworttext ein gültiges JSON Objekt zurück, das dem folgenden ähnelt:


{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv",
        "data": "0.9766594\n"
    },
    "explanations": {
        "kernel_shap": [
            [
                {
                    "attributions": [
                        {
                            "attribution": [
                                -0.007270948666666712
                            ],
                            "description": {
                                "partial_text": "This",
                                "start_idx": 0
                            }
                        },
                        {
                            "attribution": [
                                -0.018199033666666628
                            ],
                            "description": {
                                "partial_text": "is",
                                "start_idx": 5
                            }
                        },
                        {
                            "attribution": [
                                0.01970993241666666
                            ],
                            "description": {
                                "partial_text": "a",
                                "start_idx": 8
                            }
                        },
                        {
                            "attribution": [
                                0.1253469515833334
                            ],
                            "description": {
                                "partial_text": "good",
                                "start_idx": 10
                            }
                        },
                        {
                            "attribution": [
                                0.03291143366666657
                            ],
                            "description": {
                                "partial_text": "product",
                                "start_idx": 15
                            }
                        }
                    ],
                    "feature_type": "text"
                }
            ]
        ]
    }
}

Verwenden Sie Visualisierungstools, um die zurückgegebenen Textzuordnungen zu interpretieren. Die folgende Abbildung zeigt, wie das captum Visualisierungsdienstprogramm verwendet werden kann, um zu verstehen, wie jedes Wort zur Vorhersage beiträgt. Je höher die Farbsättigung, desto höher die Bedeutung, die dem Wort beigemessen wird. In diesem Beispiel deutet eine stark gesättigte hellrote Farbe auf einen starken negativen Beitrag hin. Eine stark gesättigte grüne Farbe weist auf einen starken positiven Beitrag hin. Die Farbe Weiß zeigt an, dass das Wort einen neutralen Beitrag leistet. Weitere Informationen zum Parsen und Rendern der Zuordnungen finden Sie in der Captum-Bibliothek.

Das captum Visualisierungsdienstprogramm wird verwendet, um zu verstehen, wie jedes Wort zur Vorhersage beiträgt.

Siehe Vollständiges Beispiel-Notebook für Textdaten.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Rufen Sie den Endpunkt auf

Anleitung zur Fehlerbehebung