Schnellstart: Das Verwenden der Clientbibliothek für die univariaten Anomalieerkennung

Erfahren Sie etwas über die ersten Schritte mit der Clientbibliothek für Anomalieerkennung für C#. Führen Sie diese Schritte aus, um das Paket zu installieren und mit der Verwendung der vom Dienst zur Verfügung gestellten Algorithmen zu beginnen. Mit dem Anomalieerkennungsdienst können Sie Anomalien in Zeitreihendaten ermitteln, da unabhängig von der Branche, dem Szenario oder der Datenmenge automatisch die am besten geeigneten Modelle für Ihre Daten angewandt werden.

Mit der Clientbibliothek für Anomalieerkennung für C# ist Folgendes möglich:

  • Erkennen von Anomalien in Ihrem gesamten Zeitreihendataset als Batchanforderung
  • Erkennen des Anomaliestatus des letzten Datenpunkts in Ihrer Zeitreihe
  • Erkennen von Trendänderungspunkten in Ihrem Dataset

BibliotheksreferenzdokumentationQuellcode der BibliothekPaket (NuGet)Den Code finden Sie auf GitHub.

Voraussetzungen

  • Azure-Abonnement – Erstellen eines kostenlosen Kontos
  • Aktuelle Version von .NET Core
  • Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie eine Anomalieerkennungsressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. Warten Sie ihre Bereitstellung ab, und klicken Sie auf die Schaltfläche Zu Ressource wechseln.
    • Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Anomalieerkennungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt. Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Erstellen einer Umgebungsvariablen

Hinweis

Nach dem 1. Juli 2019 erstellte Endpunkte für Ressourcen, bei denen es sich nicht um Testressourcen handelt, verwenden das unten gezeigte benutzerdefinierte Format für Subdomänen. Weitere Informationen und eine vollständige Liste mit regionalen Endpunkten finden Sie unter Benutzerdefinierte Unterdomänennamen für Cognitive Services.

Erstellen Sie unter Verwendung des Schlüssels und des Endpunkts der von Ihnen erstellten Ressource zwei Umgebungsvariablen für die Authentifizierung:

  • ANOMALY_DETECTOR_KEY: Der Ressourcenschlüssel zum Authentifizieren Ihrer Anforderungen.
  • ANOMALY_DETECTOR_ENDPOINT: Der Ressourcenendpunkt zum Senden von API-Anforderungen. Er sieht wie folgt aus:
    • https://<your-custom-subdomain>.api.cognitive.microsoft.com

Führen Sie die Schritte für Ihr Betriebssystem aus:

setx ANOMALY_DETECTOR_KEY <replace-with-your-anomaly-detector-key>
setx ANOMALY_DETECTOR_ENDPOINT <replace-with-your-anomaly-detector-endpoint>

Starten Sie das Konsolenfenster neu, nachdem Sie die Umgebungsvariable hinzugefügt haben.

Erstellen einer neuen .NET Core-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen anomaly-detector-quickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-Projekt mit einer einzigen C#-Quelldatei: Program.cs.

dotnet new console -n anomaly-detector-quickstart

Wechseln Sie zum Ordner der neu erstellten App. Sie können die Anwendung mit folgendem Befehl erstellen:

dotnet build

Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installieren der Clientbibliothek

Installieren Sie im Anwendungsverzeichnis mit dem folgenden Befehl die Anomalieerkennungs-Clientbibliothek für .NET:

dotnet add package Microsoft.Azure.CognitiveServices.AnomalyDetector

Öffnen Sie über das Projektverzeichnis die Datei program.cs, und fügen Sie mithilfe von Folgendes hinzu:

using System;
using System.IO;
using System.Text;
using System.Linq;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Azure.CognitiveServices.AnomalyDetector;
using Microsoft.Azure.CognitiveServices.AnomalyDetector.Models;

Erstellen Sie in der main()-Methode der Anwendung Variablen für den Azure-Standort der Ressource und den Schlüssel als Umgebungsvariable. Wenn Sie die Umgebungsvariable nach dem Start der Anwendung erstellen, müssen der Editor, die IDE oder die Shell, in denen sie ausgeführt wird, geschlossen und erneut geladen werden, damit der Zugriff auf die Variable möglich ist.

static void Main(string[] args){
    //This sample assumes you have created an environment variable for your key and endpoint
    string endpoint = Environment.GetEnvironmentVariable("ANOMALY_DETECTOR_ENDPOINT");
    string key = Environment.GetEnvironmentVariable("ANOMALY_DETECTOR_KEY");
    string datapath = "request-data.csv";

    IAnomalyDetectorClient client = createClient(endpoint, key); //Anomaly Detector client

    Request request = GetSeriesFromFile(datapath); // The request payload with points from the data file

    EntireDetectSampleAsync(client, request).Wait(); // Async method for batch anomaly detection
    LastDetectSampleAsync(client, request).Wait(); // Async method for analyzing the latest data point in the set
    DetectChangePoint(client, request).Wait(); // Async method for change point detection

    Console.WriteLine("\nPress ENTER to exit.");
    Console.ReadLine();
}

Objektmodell

Der Anomalieerkennungs-Client ist ein AnomalyDetectorClient-Objekt, das mithilfe der ApiKeyServiceClientCredentials-Klasse, die Ihren Schlüssel enthält, bei Azure authentifiziert wird. Der Client kann die Anomalieerkennung mithilfe von EntireDetectAsync() für ein gesamtes Dataset bzw. mithilfe von LastDetectAsync() für den letzten Datenpunkt ausführen. Mit der Methode ChangePointDetectAsync werden Punkte erkannt, die Änderungen in einem Trend markieren.

Zeitreihendaten werden als eine Reihe von Points in einem Request-Objekt gesendet. Das Request-Objekt enthält Eigenschaften zum Beschreiben der Daten (z.B. Request) sowie Parameter für die Anomalieerkennung.

Die Antwort der Anomalieerkennung ist je nach der verwendeten Methode ein EntireDetectResponse-, LastDetectResponse- oder changePointDetectResponse-Objekt.

Codebeispiele

Diese Codeausschnitte veranschaulichen, wie folgende Vorgänge mit der Anomalieerkennungs-Clientbibliothek für .NET durchgeführt werden:

Authentifizieren des Clients

Instanziieren Sie in einer neuen Methode einen Client mit Ihrem Endpunkt und Schlüssel. Erstellen Sie ein ApiKeyServiceClientCredentials-Objekt mit Ihrem Schlüssel, und verwenden Sie es mit Ihrem Endpunkt, um ein AnomalyDetectorClient-Objekt zu erstellen.

static IAnomalyDetectorClient createClient(string endpoint, string key)
{
    IAnomalyDetectorClient client = new AnomalyDetectorClient(new ApiKeyServiceClientCredentials(key))
    {
        Endpoint = endpoint
    };
    return client;
}

Laden von Zeitreihendaten aus einer Datei

Laden Sie die Beispieldaten für diesen Schnellstart von GitHub herunter:

  1. Klicken Sie im Browser mit der rechten Maustaste auf Raw.
  2. Klicken Sie auf Link speichern unter.
  3. Speichern Sie die Datei als CSV-Datei in Ihrem Anwendungsverzeichnis.

Die Zeitreihendaten werden als CSV-Datei formatiert und an die Anomalieerkennungs-API gesendet.

Erstellen Sie eine neue Methode zum Lesen der Zeitreihendaten, und fügen Sie sie dem Request-Objekt hinzu. Rufen Sie File.ReadAllLines() mit dem Dateipfad auf, erstellen Sie eine Liste der File.ReadAllLines()-Objekte, und entfernen Sie alle Neue-Zeile-Zeichen. Extrahieren Sie die Werte, trennen Sie den Datumsstempel vom numerischen Wert, und fügen Sie sie einem neuen Point-Objekt hinzu.

Erstellen Sie ein Request-Objekt mit der Datenpunktreihe und Granularity.Daily für die Request (oder Periodizität) der Datenpunkte.

static Request GetSeriesFromFile(string path)
{
    List<Point> list = File.ReadAllLines(path, Encoding.UTF8)
        .Where(e => e.Trim().Length != 0)
        .Select(e => e.Split(','))
        .Where(e => e.Length == 2)
        .Select(e => new Point(DateTime.Parse(e[0]), Double.Parse(e[1]))).ToList();
    
    return new Request(list, Granularity.Daily); 
}

Erkennen von Anomalien im gesamten Dataset

Erstellen Sie eine Methode zum Aufrufen der EntireDetectAsync()-Methode des Clients mit dem -Objekt, und warten Sie auf die Antwort als EntireDetectResponse-Objekt. Wenn die Zeitreihe Anomalien enthält, durchlaufen Sie die IsAnomaly-Werte der Antwort, und geben Sie alle Werte aus, die sind. Diese Werte stimmen mit dem Index der anomalen Datenpunkte überein, sofern welche gefunden wurden.

static async Task EntireDetectSampleAsync(IAnomalyDetectorClient client, Request request)
{
    Console.WriteLine("Detecting anomalies in the entire time series.");

    EntireDetectResponse result = await client.EntireDetectAsync(request).ConfigureAwait(false);

    if (result.IsAnomaly.Contains(true))
    {
        Console.WriteLine("An anomaly was detected at index:");
        for (int i = 0; i < request.Series.Count; ++i)
        {
            if (result.IsAnomaly[i])
            {
                Console.Write(i);
                Console.Write(" ");
            }
        }
        Console.WriteLine();
    }
    else
    {
        Console.WriteLine(" No anomalies detected in the series.");
    }
}

Erkennen des Anomaliestatus des letzten Datenpunkts

Erstellen Sie eine Methode zum Aufrufen der LastDetectAsync()-Methode des Clients mit dem -Objekt, und warten Sie auf die Antwort als LastDetectResponse-Objekt. Überprüfen Sie das IsAnomaly-Attribut der Antwort, um zu ermitteln, ob der letzte gesendete Datenpunkt als Anomalie erkannt wurde.

static async Task LastDetectSampleAsync(IAnomalyDetectorClient client, Request request)
{

    Console.WriteLine("Detecting the anomaly status of the latest point in the series.");
    LastDetectResponse result = await client.LastDetectAsync(request).ConfigureAwait(false);

    if (result.IsAnomaly)
    {
        Console.WriteLine("The latest point was detected as an anomaly.");
    }
    else
    {
        Console.WriteLine("The latest point was not detected as an anomaly.");
    }
}

Erkennen von Änderungspunkten im Dataset

Erstellen Sie eine Methode zum Aufrufen der DetectChangePointAsync-Methode des Clients mit dem -Objekt, und warten Sie auf die Antwort als ChangePointDetectResponse-Objekt. Überprüfen Sie die IsChangePoint-Werte der Antwort, und geben Sie alle aus, die den Wert true aufweisen. Diese Werte stimmen mit den Trendänderungspunkten überein, sofern welche gefunden wurden.

public async Task DetectChangePoint(IAnomalyDetectorClient client, Request request)
{
    Console.WriteLine("Detecting the change points in the series.");

    ChangePointDetectResponse result = await client.DetectChangePointAsync(request).ConfigureAwait(false);

    if (result.IsChangePoint.Contains(true))
    {
        Console.WriteLine("A change point was detected at index:");
        for (int i = 0; i < request.Series.Count; ++i)
        {
            if (result.IsChangePoint[i])
            {
                Console.Write(i);
                Console.Write(" ");
            }
        }
        Console.WriteLine();
    }
    else
    {
        Console.WriteLine("No change point detected in the series.");
    }
}

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Bereinigen von Ressourcen

Wenn Sie ein Cognitive Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die der Ressourcengruppe zugeordnet sind.

Nächste Schritte

Konzepte:

Tutorials:

Hier erfahren Sie etwas über die ersten Schritte mit der Anomalieerkennungs-Clientbibliothek für JavaScript. Führen Sie diese Schritte aus, um das Paket zu installieren und mit der Verwendung der vom Dienst zur Verfügung gestellten Algorithmen zu beginnen. Mit dem Anomalieerkennungsdienst können Sie Anomalien in Zeitreihendaten ermitteln, da unabhängig von der Branche, dem Szenario oder der Datenmenge automatisch die am besten geeigneten Modelle für Ihre Daten angewandt werden.

Mit der Anomalieerkennungs-Clientbibliothek für JavaScript ist Folgendes möglich:

  • Erkennen von Anomalien in Ihrem gesamten Zeitreihendataset als Batchanforderung
  • Erkennen des Anomaliestatus des letzten Datenpunkts in Ihrer Zeitreihe
  • Erkennen von Trendänderungspunkten in Ihrem Dataset

BibliotheksreferenzdokumentationQuellcode der BibliothekPaket (npm)Den Code finden Sie auf GitHub.

Voraussetzungen

  • Azure-Abonnement – Erstellen eines kostenlosen Kontos
  • Die aktuelle Version von Node.js
  • Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie eine Anomalieerkennungsressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. Warten Sie ihre Bereitstellung ab, und klicken Sie auf die Schaltfläche Zu Ressource wechseln.
    • Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Anomalieerkennungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt. Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Erstellen einer Umgebungsvariablen

Hinweis

Nach dem 1. Juli 2019 erstellte Endpunkte für Ressourcen, bei denen es sich nicht um Testressourcen handelt, verwenden das unten gezeigte benutzerdefinierte Format für Subdomänen. Weitere Informationen und eine vollständige Liste mit regionalen Endpunkten finden Sie unter Benutzerdefinierte Unterdomänennamen für Cognitive Services.

Erstellen Sie unter Verwendung des Schlüssels und des Endpunkts der von Ihnen erstellten Ressource zwei Umgebungsvariablen für die Authentifizierung:

  • ANOMALY_DETECTOR_KEY: Der Ressourcenschlüssel zum Authentifizieren Ihrer Anforderungen.
  • ANOMALY_DETECTOR_ENDPOINT: Der Ressourcenendpunkt zum Senden von API-Anforderungen. Er sieht wie folgt aus:
    • https://<your-custom-subdomain>.api.cognitive.microsoft.com

Führen Sie die Schritte für Ihr Betriebssystem aus:

setx ANOMALY_DETECTOR_KEY <replace-with-your-anomaly-detector-key>
setx ANOMALY_DETECTOR_ENDPOINT <replace-with-your-anomaly-detector-endpoint>

Starten Sie das Konsolenfenster neu, nachdem Sie die Umgebungsvariable hinzugefügt haben.

Erstellen einer neuen Node.js-Anwendung

Erstellen Sie in einem Konsolenfenster (etwa cmd, PowerShell oder Bash) ein neues Verzeichnis für Ihre App, und rufen Sie es auf.

mkdir myapp && cd myapp

Führen Sie den Befehl npm init aus, um eine Knotenanwendung mit der Datei package.json zu erstellen.

npm init

Erstellen Sie eine Datei namens index.js, und importieren Sie die folgenden Bibliotheken:

'use strict'

const fs = require('fs');
const parse = require("csv-parse/lib/sync");
const { AnomalyDetectorClient } = require('@azure/ai-anomaly-detector');
const { AzureKeyCredential } = require('@azure/core-auth');

Erstellen Sie Variablen für den Azure-Endpunkt und -Schlüssel Ihrer Ressource. Wenn Sie die Umgebungsvariable nach dem Start der Anwendung erstellt haben, müssen der Editor, die IDE oder die Shell, in dem bzw. der sie ausgeführt wird, geschlossen und erneut geöffnet werden, damit der Zugriff auf die Variable möglich ist. Erstellen Sie eine weitere Variable für die Beispieldatendatei, die Sie in einem späteren Schritt herunterladen, und eine leere Liste für die Datenpunkte. Erstellen Sie anschließend ein ApiKeyCredentials-Objekt, das den Schlüssel enthält.

// Spreadsheet with 2 columns and n rows.
let CSV_FILE = './request-data.csv';

// Authentication variables
let key = 'PASTE_YOUR_ANOMALY_DETECTOR_SUBSCRIPTION_KEY_HERE';
let endpoint = 'PASTE_YOUR_ANOMALY_DETECTOR_ENDPOINT_HERE';

// Points array for the request body
let points = [];

Installieren der Clientbibliothek

Installieren Sie die npm-Pakete ms-rest-azure und azure-cognitiveservices-anomalydetector. Die Bibliothek „csv-parse“ wird auch in diesem Schnellstart verwendet:

npm install @azure/ai-anomaly-detector @azure/ms-rest-js csv-parse

Die Datei package.json Ihrer App wird mit den Abhängigkeiten aktualisiert.

Objektmodell

Der Anomalieerkennungsclient ist ein AnomalyDetectorClient-Objekt, das sich mit Ihrem Schlüssel bei Azure authentifiziert. Der Client kann die Anomalieerkennung mithilfe von entireDetect() für ein gesamtes Dataset bzw. mithilfe von LastDetect() für den letzten Datenpunkt ausführen. Mit der Methode ChangePointDetectAsync werden Punkte erkannt, die Änderungen in einem Trend markieren.

Zeitreihendaten werden als eine Reihe von Punkten in einem Request-Objekt gesendet. Das Request-Objekt enthält Eigenschaften zum Beschreiben der Daten (z.B. Request) sowie Parameter für die Anomalieerkennung.

Die Antwort der Anomalieerkennung ist je nach der verwendeten Methode ein LastDetectResponse-, EntireDetectResponse- oder ChangePointDetectResponse-Objekt.

Codebeispiele

Diese Codeausschnitte veranschaulichen, wie folgende Vorgänge mit der Anomalieerkennungs-Clientbibliothek für Node.js durchgeführt werden:

Authentifizieren des Clients

Instanziieren Sie ein AnomalyDetectorClient-Objekt mit ihrem Endpunkt und Ihren Anmeldeinformationen.

let anomalyDetectorClient = new AnomalyDetectorClient(endpoint, new AzureKeyCredential(key));

Laden von Zeitreihendaten aus einer Datei

Laden Sie die Beispieldaten für diesen Schnellstart von GitHub herunter:

  1. Klicken Sie im Browser mit der rechten Maustaste auf Raw.
  2. Klicken Sie auf Link speichern unter.
  3. Speichern Sie die Datei als CSV-Datei in Ihrem Anwendungsverzeichnis.

Die Zeitreihendaten werden als CSV-Datei formatiert und an die Anomalieerkennungs-API gesendet.

Lesen Sie die Datendatei mit der readFileSync()-Methode der Bibliothek „csv-parse“, und analysieren Sie die Datei mit parse(). Pushen Sie für jede Zeile ein Point-Objekt, das den Zeitstempel und den numerischen Wert enthält.

function readFile() {
    let input = fs.readFileSync(CSV_FILE).toString();
    let parsed = parse(input, { skip_empty_lines: true });
    parsed.forEach(function (e) {
        points.push({ timestamp: new Date(e[0]), value: parseFloat(e[1]) });
    });
}
readFile()

Erkennen von Anomalien im gesamten Dataset

Rufen Sie die API zum Erkennen von Anomalien in der gesamten Zeitreihe als Batch mit der entireDetect()-Methode des Clients auf. Speichern Sie das zurückgegebene EntireDetectResponse-Objekt. Durchlaufen Sie die isAnomaly-Liste der Antwort, und geben Sie den Index aller true-Werte aus. Diese Werte stimmen mit dem Index der anomalen Datenpunkte überein, sofern welche gefunden wurden.

async function batchCall() {
    // Create request body for API call
    let body = { series: points, granularity: 'daily' }
    // Make the call to detect anomalies in whole series of points
    await anomalyDetectorClient.detectEntireSeries(body)
        .then((response) => {
            console.log("Batch (entire) anomaly detection):")
            for (let item = 0; item < response.isAnomaly.length; item++) {
                if (response.isAnomaly[item]) {
                    console.log("An anomaly was detected from the series, at row " + item)
                }
            }
        }).catch((error) => {
            console.log(error)
        })

}
batchCall()

Erkennen des Anomaliestatus des letzten Datenpunkts

Rufen Sie mithilfe der lastDetect()-Methode des Clients die Anomalieerkennungs-API auf, um festzustellen, ob Ihr letzter Datenpunkt eine Anomalie ist, und speichern Sie das zurückgegebene LastDetectResponse-Objekt. Der isAnomaly-Wert der Antwort ist ein Boolescher Wert, der den Anomaliestatus dieses Punktes angibt.

async function lastDetection() {

    let body = { series: points, granularity: 'daily' }
    // Make the call to detect anomalies in the latest point of a series
    await anomalyDetectorClient.detectLastPoint(body)
        .then((response) => {
            console.log("Latest point anomaly detection:")
            if (response.isAnomaly) {
                console.log("The latest point, in row " + points.length + ", is detected as an anomaly.")
            } else {
                console.log("The latest point, in row " + points.length + ", is not detected as an anomaly.")
            }
        }).catch((error) => {
            console.log(error)
        })
}
lastDetection()

Erkennen von Änderungspunkten im Dataset

Rufen Sie die API auf, um Änderungspunkte in der Zeitreihe mit der Methode detectChangePoint() des Clients zu erkennen. Speichern Sie das zurückgegebene ChangePointDetectResponse-Objekt. Durchlaufen Sie die isChangePoint-Liste der Antwort, und geben Sie den Index aller true-Werte aus. Diese Werte stimmen mit den Indizes der Trendänderungspunkte überein, sofern welche gefunden wurden.

async function changePointDetection() {

    let body = { series: points, granularity: 'daily' }
    // get change point detect results
    await anomalyDetectorClient.detectChangePoint(body)
        .then((response) => {
            if (
                response.isChangePoint.some(function (changePoint) {
                    return changePoint === true;
                })
            ) {
                console.log("Change points were detected from the series at index:");
                response.isChangePoint.forEach(function (changePoint, index) {
                    if (changePoint === true) {
                        console.log(index);
                    }
                });
            } else {
                console.log("There is no change point detected from the series.");
            }
        }).catch((error) => {
            console.log(error)
        })
}

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Befehl node für die Schnellstartdatei aus.

node index.js

Bereinigen von Ressourcen

Wenn Sie ein Cognitive Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die der Ressourcengruppe zugeordnet sind.

Nächste Schritte

Konzepte:

Tutorials:

Hier erfahren Sie etwas über die ersten Schritte mit der Anomalieerkennungs-Clientbibliothek für Python. Führen Sie diese Schritte aus, um das Paket zu installieren und mit der Verwendung der vom Dienst zur Verfügung gestellten Algorithmen zu beginnen. Mit dem Anomalieerkennungsdienst können Sie Anomalien in Zeitreihendaten ermitteln, da unabhängig von der Branche, dem Szenario oder der Datenmenge automatisch die am besten geeigneten Modelle für Ihre Daten angewandt werden.

Mit der Anomalieerkennungs-Clientbibliothek für Python ist Folgendes möglich:

  • Erkennen von Anomalien in Ihrem gesamten Zeitreihendataset als Batchanforderung
  • Erkennen des Anomaliestatus des letzten Datenpunkts in Ihrer Zeitreihe
  • Erkennen von Trendänderungspunkten in Ihrem Dataset

BibliotheksreferenzdokumentationQuellcode der BibliothekPaket (PyPi)Codebeispiele auf GitHub

Voraussetzungen

  • Python 3.x
  • Die Pandas-Bibliothek für Datenanalyse
  • Azure-Abonnement – Erstellen eines kostenlosen Kontos
  • Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie eine Anomalieerkennungsressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. Warten Sie ihre Bereitstellung ab, und klicken Sie auf die Schaltfläche Zu Ressource wechseln.
    • Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Anomalieerkennungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt. Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Erstellen einer Umgebungsvariablen

Hinweis

Nach dem 1. Juli 2019 erstellte Endpunkte für Ressourcen, bei denen es sich nicht um Testressourcen handelt, verwenden das unten gezeigte benutzerdefinierte Format für Subdomänen. Weitere Informationen und eine vollständige Liste mit regionalen Endpunkten finden Sie unter Benutzerdefinierte Unterdomänennamen für Cognitive Services.

Erstellen Sie unter Verwendung des Schlüssels und des Endpunkts der von Ihnen erstellten Ressource zwei Umgebungsvariablen für die Authentifizierung:

  • ANOMALY_DETECTOR_KEY: Der Ressourcenschlüssel zum Authentifizieren Ihrer Anforderungen.
  • ANOMALY_DETECTOR_ENDPOINT: Der Ressourcenendpunkt zum Senden von API-Anforderungen. Er sieht wie folgt aus:
    • https://<your-custom-subdomain>.api.cognitive.microsoft.com

Führen Sie die Schritte für Ihr Betriebssystem aus:

setx ANOMALY_DETECTOR_KEY <replace-with-your-anomaly-detector-key>
setx ANOMALY_DETECTOR_ENDPOINT <replace-with-your-anomaly-detector-endpoint>

Starten Sie das Konsolenfenster neu, nachdem Sie die Umgebungsvariable hinzugefügt haben.

Erstellen einer neuen Python-Anwendung

Erstellen Sie eine neue Python-Datei, und importieren Sie die folgenden Bibliotheken:

import os
from azure.ai.anomalydetector import AnomalyDetectorClient
from azure.ai.anomalydetector.models import DetectRequest, TimeSeriesPoint, TimeGranularity, \
    AnomalyDetectorError
from azure.core.credentials import AzureKeyCredential
import pandas as pd

Erstellen Sie Variablen für Ihren Schlüssel als Umgebungsvariable, den Pfad zu einer Zeitreihendatendatei und den Azure-Speicherort Ihres Abonnements. Beispiel: westus2.

SUBSCRIPTION_KEY = os.environ["ANOMALY_DETECTOR_KEY"]
ANOMALY_DETECTOR_ENDPOINT = os.environ["ANOMALY_DETECTOR_ENDPOINT"]
TIME_SERIES_DATA_PATH = os.path.join("./sample_data", "request-data.csv")

Installieren der Clientbibliothek

Nach der Installation von Python, können Sie die Clientbibliothek mit Folgendem installieren:

pip install --upgrade azure-ai-anomalydetector

Objektmodell

Der Anomalieerkennungsclient ist ein AnomalyDetectorClient-Objekt, das sich mit Ihrem Schlüssel bei Azure authentifiziert. Der Client kann die Anomalieerkennung mithilfe von detect_entire_series für ein gesamtes Dataset bzw. mithilfe von detect_last_point für den letzten Datenpunkt ausführen. Mit der Funktion detect_change_point werden Punkte erkannt, die Änderungen in einem Trend markieren.

Zeitreihendaten werden als eine Reihe von TimeSeriesPoints-Objekten gesendet. Das DetectRequest-Objekt enthält Eigenschaften zum Beschreiben der Daten (z. B. TimeGranularity) sowie Parameter für die Anomalieerkennung.

Die Antwort der Anomalieerkennung ist je nach der verwendeten Methode ein LastDetectResponse-, EntireDetectResponse- oder ChangePointDetectResponse-Objekt.

Codebeispiele

Diese Codeausschnitte veranschaulichen, wie folgende Vorgänge mit der Anomalieerkennungs-Clientbibliothek für Python ausgeführt werden:

Authentifizieren des Clients

Fügen Sie Ihre Azure-Speicherortvariable dem Endpunkt hinzu, und authentifizieren Sie den Client mit Ihrem Schlüssel.

client = AnomalyDetectorClient(AzureKeyCredential(SUBSCRIPTION_KEY), ANOMALY_DETECTOR_ENDPOINT)

Laden von Zeitreihendaten aus einer Datei

Laden Sie die Beispieldaten für diesen Schnellstart von GitHub herunter:

  1. Klicken Sie im Browser mit der rechten Maustaste auf Raw.
  2. Klicken Sie auf Link speichern unter.
  3. Speichern Sie die Datei als CSV-Datei in Ihrem Anwendungsverzeichnis.

Die Zeitreihendaten werden als CSV-Datei formatiert und an die Anomalieerkennungs-API gesendet.

Laden Sie die Datendatei mit der read_csv()-Methode der Pandas-Bibliothek, und erstellen Sie eine leere Listenvariable zum Speichern der Datenreihe. Durchlaufen Sie die Datei, und fügen Sie die Daten als TimeSeriesPoint-Objekt an. Dieses Objekt enthält den Zeitstempel und den numerischen Wert aus den Zeilen der CSV-Datendatei.

series = []
data_file = pd.read_csv(TIME_SERIES_DATA_PATH, header=None, encoding='utf-8', parse_dates=[0])
for index, row in data_file.iterrows():
    series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))

Erstellen Sie ein DetectRequest-Objekt mit der Zeitreihe und der TimeGranularity (oder Periodizität) der zugehörigen Datenpunkte. Beispiel: TimeGranularity.daily.

request = DetectRequest(series=series, granularity=TimeGranularity.daily)

Eingabeargumentbeschreibungen: „series“: In Abfrage erforderlich. Muss vom Typ „Array“/„Liste“ sein und mindestens 12 Punkte und maximal 8.640 Punkte umfassen. Muss in aufsteigender Reihenfolge nach Zeitstempel sortiert werden und darf keinen doppelten Zeitstempel aufweisen. „granularity“: In Anforderung erforderlich. Darf nur einen der folgenden Werte haben: [„daily“, „minutely“, „hourly“, „weekly“, „monthly“, „yearly“, „secondly“]. „customInterval“: Muss eine ganze Zahl > 0 sein. „period“: Muss eine ganze Zahl >= 0 sein. „maxAnomalyRatio“: Muss weniger als 50 Prozent der Reihenpunkte betragen (0 < maxAnomalyRatio < 0,5). „sensitivity“: Muss eine ganze Zahl zwischen 0 und 99 sein.

Erkennen von Anomalien im gesamten Dataset

Rufen Sie die API zum Erkennen von Anomalien in den gesamten Zeitreihendaten mit der detect_entire_series-Methode des Clients auf. Speichern Sie das zurückgegebene EntireDetectResponse-Objekt. Durchlaufen Sie die is_anomaly-Liste der Antwort, und geben Sie den Index aller true-Werte aus. Diese Werte stimmen mit dem Index der anomalen Datenpunkte überein, sofern welche gefunden wurden.

print('Detecting anomalies in the entire time series.')

try:
    response = client.detect_entire_series(request)
except AnomalyDetectorError as e:
    print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
except Exception as e:
    print(e)

if any(response.is_anomaly):
    print('An anomaly was detected at index:')
    for i, value in enumerate(response.is_anomaly):
        if value:
            print(i)
else:
    print('No anomalies were detected in the time series.')

Erkennen des Anomaliestatus des letzten Datenpunkts

Rufen Sie mithilfe der detect_last_point-Methode des Clients die Anomalieerkennungs-API auf, um festzustellen, ob Ihr letzter Datenpunkt eine Anomalie ist, und speichern Sie das zurückgegebene LastDetectResponse-Objekt. Der is_anomaly-Wert der Antwort ist ein Boolescher Wert, der den Anomaliestatus dieses Punktes angibt.

print('Detecting the anomaly status of the latest data point.')

try:
    response = client.detect_last_point(request)
except AnomalyDetectorError as e:
    print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
except Exception as e:
    print(e)

if response.is_anomaly:
    print('The latest point is detected as anomaly.')
else:
    print('The latest point is not detected as anomaly.')

Erkennen von Änderungspunkten im Dataset

Rufen Sie die API auf, um Änderungspunkte in den Zeitreihendaten mit der Methode detect_change_point des Clients zu erkennen. Speichern Sie das zurückgegebene ChangePointDetectResponse-Objekt. Durchlaufen Sie die is_change_point-Liste der Antwort, und geben Sie den Index aller true-Werte aus. Diese Werte stimmen mit den Indizes der Trendänderungspunkte überein, sofern welche gefunden wurden.

print('Detecting change points in the entire time series.')

try:
    response = client.detect_change_point(request)
except AnomalyDetectorError as e:
    print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
except Exception as e:
    print(e)

if any(response.is_change_point):
    print('An change point was detected at index:')
    for i, value in enumerate(response.is_change_point):
        if value:
            print(i)
else:
    print('No change point were detected in the time series.')

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Befehl python und Ihrem Dateinamen aus.

Bereinigen von Ressourcen

Wenn Sie ein Cognitive Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die der Ressourcengruppe zugeordnet sind.

Nächste Schritte

Konzepte:

Tutorials:

In dieser Schnellstartanleitung wird beschrieben, wie Sie Anomalien in Zeitreihendaten erkennen, indem Sie den Anomalieerkennungsdienst und cURL verwenden.

Allgemeine Informationen zu den Konzepten der Anomalieerkennung finden Sie im Übersichtsartikel.

Voraussetzungen

  • Azure-Abonnement – Erstellen eines kostenlosen Kontos
  • Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie eine Anomalieerkennungsressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. Warten Sie die Bereitstellung ab, und wählen Sie dann die Schaltfläche Zu Ressource wechseln aus.
    • Sie benötigen den Schlüssel und die Endpunktadresse der von Ihnen erstellten Ressource, um die REST-API verwenden zu können. Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Erkennen von Anomalien für eine gesamte Reihe

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus. Sie müssen die folgenden Werte in den Befehl einfügen.

  • Ihren Abonnementschlüssel des Anomalieerkennungsdiensts
  • Ihre Endpunktadresse der Anomalieerkennung
  • Eine gültige JSON-Datei mit Zeitreihendaten für Anomalietests Falls Sie nicht über eine eigene Datei verfügen, können Sie über das Anforderungstextbeispiel die Datei „sample.json“ erstellen.
curl -v -X POST "https://{endpointresourcename.cognitive.microsoft.com}/anomalydetector/v1.0/timeseries/entire/detect"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
-d "@{path_to_file.json}" 

Beispiel mit allen eingefügten Werten:

curl -v -X POST "https://my-resource-name.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/entire/detect" -H  "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key:1111112222222ed333333ab333333333" -d "@test.json"

Wenn Sie die Beispieldaten aus den Voraussetzungen verwendet haben, sollten Sie eine Antwort vom Typ „200“ mit den folgenden Ergebnissen erhalten:

{
  "expectedValues": [
    827.7940908243968,
    798.9133774671927,
    888.6058431807189,
    900.5606407986661,
    962.8389426378304,
    933.2591606306954,
    891.0784104799666,
    856.1781601363697,
    809.8987227908941,
    807.375129007505,
    764.3196682448518,
    803.933498594564,
    823.5900620883058,
    794.0905641334288,
    883.164245249282,
    894.8419000690953,
    956.8430591101258,
    927.6285055190114,
    885.812983784303,
    851.6424797402517,
    806.0927886943216,
    804.6826815312029,
    762.74070738882,
    804.0251702513732,
    825.3523662579559,
    798.0404188724976,
    889.3016505577698,
    902.4226124345937,
    965.867078532635,
    937.3200495736695,
    896.1720524711102,
    862.0087368413656,
    816.4662342097423,
    814.4297745524709,
    771.8614479159354,
    811.859271346729,
    831.8998279215521,
    802.947544797165,
    892.5684407435083,
    904.5488214533809,
    966.8527063844707,
    937.3168391003043,
    895.180003672544,
    860.3649596356635,
    814.1707285969043,
    811.9054862686213,
    769.1083769610742,
    809.2328084659704
  ],
  "upperMargins": [
    41.389704541219835,
    39.94566887335964,
    44.43029215903594,
    45.02803203993331,
    48.14194713189152,
    46.66295803153477,
    44.55392052399833,
    42.808908006818484,
    40.494936139544706,
    40.36875645037525,
    38.215983412242586,
    40.196674929728196,
    41.17950310441529,
    39.70452820667144,
    44.1582122624641,
    44.74209500345477,
    47.84215295550629,
    46.38142527595057,
    44.290649189215145,
    42.58212398701258,
    40.30463943471608,
    40.234134076560146,
    38.137035369441,
    40.201258512568664,
    41.267618312897795,
    39.90202094362488,
    44.46508252788849,
    45.121130621729684,
    48.29335392663175,
    46.86600247868348,
    44.80860262355551,
    43.100436842068284,
    40.82331171048711,
    40.721488727623544,
    38.593072395796774,
    40.59296356733645,
    41.5949913960776,
    40.14737723985825,
    44.62842203717541,
    45.227441072669045,
    48.34263531922354,
    46.86584195501521,
    44.759000183627194,
    43.01824798178317,
    40.70853642984521,
    40.59527431343106,
    38.45541884805371,
    40.46164042329852
  ],
  "lowerMargins": [
    41.389704541219835,
    39.94566887335964,
    44.43029215903594,
    45.02803203993331,
    48.14194713189152,
    46.66295803153477,
    44.55392052399833,
    42.808908006818484,
    40.494936139544706,
    40.36875645037525,
    38.215983412242586,
    40.196674929728196,
    41.17950310441529,
    39.70452820667144,
    44.1582122624641,
    44.74209500345477,
    47.84215295550629,
    46.38142527595057,
    44.290649189215145,
    42.58212398701258,
    40.30463943471608,
    40.234134076560146,
    38.137035369441,
    40.201258512568664,
    41.267618312897795,
    39.90202094362488,
    44.46508252788849,
    45.121130621729684,
    48.29335392663175,
    46.86600247868348,
    44.80860262355551,
    43.100436842068284,
    40.82331171048711,
    40.721488727623544,
    38.593072395796774,
    40.59296356733645,
    41.5949913960776,
    40.14737723985825,
    44.62842203717541,
    45.227441072669045,
    48.34263531922354,
    46.86584195501521,
    44.759000183627194,
    43.01824798178317,
    40.70853642984521,
    40.59527431343106,
    38.45541884805371,
    40.46164042329852
  ],
  "isAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    true,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "isPositiveAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    true,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "isNegativeAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "period": 12
}

Weitere Informationen finden Sie in der REST-Referenz zur Anomalieerkennung.

Bereinigen von Ressourcen

Wenn Sie ein Cognitive Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die der Ressourcengruppe zugeordnet sind.

Nächste Schritte

Konzepte:

Tutorials: