Melhores práticas de uso da API do Detector de Anomalias multivariado

  • Artigo

Importante

A partir de 20 de setembro de 2023, não será possível criar novos recursos do Detector de Anomalias. O serviço Detector de Anomalias está sendo desativado em 1º de outubro de 2026.

Este artigo fornece orientações sobre as práticas recomendadas a serem seguidas ao usar as APIs (MVAD) do Detector de Anomalias. Neste tutorial, você aprenderá a:

  • Uso da API: saiba como usar o MVAD sem erros.
  • Engenharia de dados: saiba como preparar bem os dados para que o MVAD seja executado com maior precisão.
  • Armadilhas comuns: saiba como evitar armadilhas comuns em que os clientes caem.
  • Perguntas frequentes: veja as respostas para perguntas frequentes.

Uso da API

Siga as instruções nesta seção para evitar erros ao usar o MVAD. Se você ainda receber erros, confira a lista completa de códigos de erro para obter explicações e ações a serem executadas.

Parâmetros de entrada

Parâmetros obrigatórios

Esses três parâmetros são necessários nas solicitações de API de treinamento e inferência:

  • source – O link para o arquivo zip localizado no Armazenamento de Blobs do Azure com SAS (Assinatura de Acesso Compartilhado).
  • startTime – A hora de início dos dados usados para treinamento ou inferência. Se o valor for anterior ao carimbo de data/hora real mais antigo nos dados, o carimbo de data/hora real mais antigo será usado como ponto de partida.
  • endTime – A hora de término dos dados usados para treinamento ou inferência, que deve ser posterior ou igual a startTime. Se endTime for posterior ao carimbo de data/hora real mais recente nos dados, o carimbo de data/hora real mais recente será usado como ponto final. Se endTime for igual a startTime, significará a inferência de um único ponto de dados, que geralmente é usado em cenários de streaming.

Parâmetros opcionais para treinamento da API

Outros parâmetros para o treinamento da API são opcionais:

  • slidingWindow – Quantos pontos de dados são usados para determinar anomalias. Um inteiro entre 28 e 2.880. O valor padrão é 300. Se slidingWindow for k para treinamento de modelo, então, para a obtenção de resultados válidos, pelo menos k pontos deverão ser acessíveis a partir do arquivo de origem durante a inferência.

    O MVAD usa um segmento de pontos de dados para decidir se o próximo ponto de dados será uma anomalia. O comprimento do segmento é de slidingWindow. Tenha duas coisas em mente ao escolher um valor slidingWindow:

    1. As propriedades de seus dados: se é periódica e a taxa de amostragem. Quando seus dados forem periódicos, você poderá definir o comprimento de um a três ciclos como o slidingWindow. Quando os dados estiverem em uma alta frequência (granularidade pequena), como nível de minuto ou de segundo, você poderá definir um valor relativamente mais alto de slidingWindow.
    2. A compensação entre o tempo de inferência/treinamento e o possível impacto no desempenho. Um slidingWindow maior pode aumentar o tempo de treinamento/inferência. Não há garantia de que slidingWindows maiores aumentarão a precisão. Um slidingWindow pequeno pode dificultar a convergência do modelo em uma solução ideal. Por exemplo, é difícil detectar anomalias quando slidingWindow tem apenas dois pontos.

  • alignMode – Como alinhar várias variáveis (série temporal) em carimbos de data/hora. Há duas opções para esse parâmetro, Inner e Outer, e o valor padrão é Outer.

    Esse parâmetro é crítico quando há um alinhamento incorreto entre sequências de carimbo de data/hora das variáveis. O modelo precisa alinhar as variáveis na mesma sequência de carimbo de data/hora antes do processamento adicional.

    Inner significa que o modelo relatará resultados de detecção apenas em carimbos de data/hora nos quais cada variável tem um valor, ou seja, a interseção de todas as variáveis. Outer significa que o modelo relatará resultados de detecção em carimbos de data/hora nos quais cada variável tem um valor, ou seja, a união de todas as variáveis.

    Veja um exemplo para entender os valores diferentes de alignModel.

    Variável-1

    timestamp value
    2020-11-01 1
    2020-11-02 2
    2020-11-04 4
    05/11/2020 5

    Variável-2

    timestamp value
    2020-11-01 1
    2020-11-02 2
    2020-11-03 3
    2020-11-04 4

    Inner une duas variáveis

    timestamp Variable-1 Variável-2
    2020-11-01 1 1
    2020-11-02 2 2
    2020-11-04 4 4

    Outer une duas variáveis

    timestamp Variable-1 Variável-2
    2020-11-01 1 1
    2020-11-02 2 2
    2020-11-03 nan 3
    2020-11-04 4 4
    05/11/2020 5 nan

  • fillNAMethod – Como preencher nan na tabela mesclada. Pode haver valores ausentes na tabela mesclada e eles devem ser tratados adequadamente. Fornecemos vários métodos para preenchê-los. As opções são Linear, Previous, Subsequent, Zero e Fixed, e o valor padrão é Linear.

    Opção Método
    Linear Preencher os valores de nan por interpolação linear
    Previous Propagar o último valor válido para preencher lacunas. Exemplo: [1, 2, nan, 3, nan, 4] ->[1, 2, 2, 3, 3, 4]
    Subsequent Usar o próximo valor válido para preencher as lacunas. Exemplo: [1, 2, nan, 3, nan, 4] ->[1, 2, 3, 3, 4, 4]
    Zero Preencher os valores de nan com zero.
    Fixed Preencher os valores de paddingValue com um valor válido especificado que deve ser fornecido em nan.

  • paddingValue – O valor de preenchimento é usado para preencher nan quando fillNAMethod for Fixed, e deve ser fornecido nesse caso. Em outros casos, é opcional.

  • displayName – Esse parâmetro é opcional, e é usado para identificar modelos. Por exemplo, você pode usá-lo para marcar parâmetros, fontes de dados e quaisquer outros metadados sobre o modelo e seus dados de entrada. O valor padrão é uma cadeia de caracteres vazia.

Entrada do esquema de dados

O MVAD detecta anomalias de um grupo de métricas e chamamos cada métrica de uma variável ou uma série temporal.

  • É possível baixar o arquivo de dados de exemplo da Microsoft para verificar o esquema aceito de: https://aka.ms/AnomalyDetector/MVADSampleData

  • Cada variável deve ter dois e apenas dois campos, timestamp e value, e devem ser armazenados em um arquivo CSV (valores separados por vírgula).

  • Os nomes de coluna do arquivo CSV devem ser precisamente timestamp e value, e diferenciam maiúsculas de minúsculas.

  • Os valores de timestamp devem estar em conformidade com a ISO 8601; value podem ser inteiros ou decimais com qualquer número de casas decimais. Um bom exemplo do conteúdo de um arquivo CSV:

    timestamp value
    2019-04-01T00:00:00Z 5
    2019-04-01T00:01:00Z 3,6
    2019-04-01T00:02:00Z 4
    ... ...

    Observação

    Se seus carimbos de data/hora têm horas, minutos e/ou segundos, verifique se eles são arredondados corretamente antes de chamar as APIs.

    Por exemplo, se a frequência de dados deve ser um ponto de dados a cada 30 segundos, mas você vir os tempos de data/hora como "12:00:01" e "12:00:28", é um sinal forte que deverá pré-processar os carimbos de data/hora para novos valores, como "12:00:00" e "12:00:30".

    Para obter detalhes, consulte a seção "Arredondamento de carimbo de data/hora" no documento de melhores práticas.

  • O nome do arquivo csv será usado como o nome da variável e deverá ser exclusivo. Por exemplo, "temperature.csv" e "humidity.csv".

  • As variáveis para treinamento e as variáveis para inferência devem ser consistentes. Por exemplo, se você estiver usando series_1, series_2, series_3, series_4 e series_5 para treinamento, deverá fornecer exatamente as mesmas variáveis para inferência.

  • Os arquivos CSV devem ser compactados em um arquivo zip e carregados em um contêiner de Blobs do Azure. O arquivo zip poderá ter qualquer nome que você desejar.

Estrutura de pastas

Um erro comum na preparação de dados são pastas extras no arquivo zip. Por exemplo, suponha que o nome do arquivo zip seja series.zip. Em seguida, depois de descompactar os arquivos em uma nova pasta ./series, o caminho correto para arquivos CSV é ./series/series_1.csv e um caminho errado pode ser ./series/foo/bar/series_1.csv.

O exemplo correto da árvore de diretório depois de descompactar o arquivo zip no Windows

.
└── series
    ├── series_1.csv
    ├── series_2.csv
    ├── series_3.csv
    ├── series_4.csv
    └── series_5.csv

Um exemplo incorreto da árvore de diretório depois de descompactar o arquivo zip no Windows

.
└── series
    └── series
        ├── series_1.csv
        ├── series_2.csv
        ├── series_3.csv
        ├── series_4.csv
        └── series_5.csv

Engenharia de dados

Agora você pode executar o código com as APIs do MVAD sem nenhum erro. O que poderia ser feito para aprimorar a precisão do modelo?

Qualidade dos dados

  • Conforme o modelo aprende padrões normais de dados históricos, os dados de treinamento devem representar o estado normal geral do sistema. É difícil para o modelo aprender esses tipos de padrões se os dados de treinamento estão cheios de anomalias. Um limite empírico de taxa anormal é 1% e abaixo para obter uma boa precisão.
  • Em geral, a taxa de valor ausente dos dados de treinamento deve estar abaixo de 20% . A ausência de muitos dados pode fazer com que os valores sejam preenchidos automaticamente (geralmente, valores lineares ou constantes) e sejam aprendidos como padrões normais. Isso pode resultar na detecção de pontos de dados reais (não ausentes) como anomalias.

Quantidade de dados

  • O modelo subjacente do MVAD tem milhões de parâmetros. Ele precisa de um número mínimo de pontos de dados para aprender um conjunto ideal de parâmetros. A regra empírica é que você precisa fornecer 5 mil ou mais pontos de dados (carimbos de data/hora) por variável para treinar o modelo visando uma boa precisão. Em geral, quanto mais dados de treinamento, melhor é a precisão. No entanto, em casos em que não é possível acumular tantos dados, você ainda pode experimentar menos dados e ver se a precisão comprometida ainda é aceitável.

  • Sempre que você chama a API de inferência, é necessário garantir que o arquivo de dados de origem contenha apenas os pontos de dados suficientes. Isso normalmente é slidingWindow + número de pontos de dados que realmente precisam de resultados de inferência. Por exemplo, em um caso de streaming, sempre que você quiser fazer uma inferência em UM novo carimbo de data/hora, o arquivo de dados poderá conter apenas o ponto de dados mais à esquerda, slidingWindow mais UM. Nesse caso você poderá criar outro arquivo zip com o mesmo número de pontos de dados (slidingWindow + 1), mas mover UMA etapa para a "direita" e fazer o envio para outro trabalho de inferência.

    Tudo que estiver depois disso ou "antes" da janela deslizante à esquerda não afetará o resultado da inferência e só poderá causar uma redução do desempenho. Qualquer coisa abaixo que possa levar a um erro NotEnoughInput.

Arredondamento de carimbo de data/hora

Em um grupo de variáveis (série temporal), cada variável pode ser coletada de uma fonte independente. Os carimbos de data/hora de variáveis diferentes podem ser inconsistentes entre si e com as frequências conhecidas. A seguir está um exemplo simples.

Variável-1

timestamp value
12:00:01 1.0
12:00:35 1.5
12:01:02 0,9
12:01:31 2,2
12:02:08 1,3

Variable-2

timestamp value
12:00:03 2,2
12:00:37 2.6
12:01:09 1.4
12:01:34 1.7
12:02:04 2.0

Temos duas variáveis coletadas de dois sensores que enviam um ponto de dados a cada 30 segundos. No entanto, os sensores não estão enviando pontos de dados em uma frequência rígida, mas às vezes antes e outras vezes depois. Como o MVAD leva em consideração as correlações entre variáveis diferentes, os carimbos de data/hora precisam estar alinhados corretamente para que as métricas possam refletir corretamente a condição do sistema. No exemplo acima, os carimbos de data/hora da variável 1 e da variável 2 precisam ser 'arredondados' corretamente para as respectivas frequência antes do alinhamento.

Vejamos o que acontece quando elas não são pré-processadas. Se definirmos alignMode como Outer (que significa união de dois conjuntos), a tabela mesclada será:

timestamp Variable-1 Variable-2
12:00:01 1.0 nan
12:00:03 nan 2,2
12:00:35 1.5 nan
12:00:37 nan 2.6
12:01:02 0,9 nan
12:01:09 nan 1.4
12:01:31 2,2 nan
12:01:34 nan 1.7
12:02:04 nan 2.0
12:02:08 1,3 nan

nan indica valores ausentes. Obviamente, a tabela mesclada não é o que você esperava. A variável 1 e a variável 2 se intercalam, e o modelo do MVAD não pode extrair informações sobre as correlações entre elas. Se definirmos alignMode como Inner, a tabela mesclada ficará vazia, pois não haverá nenhum carimbo de data/hora comum na variável 1 e na variável 2.

Portanto, os carimbos de data/hora da variável 1 e da variável 2 devem ser pré-processados (arredondados para os carimbos de data/hora mais próximos de 30 segundos) e a nova série temporal é:

Variável-1

timestamp value
12:00:00 1.0
12:00:30 1.5
12:01:00 0,9
12:01:30 2,2
12:02:00 1,3

Variable-2

timestamp value
12:00:00 2,2
12:00:30 2.6
12:01:00 1.4
12:01:30 1.7
12:02:00 2.0

Agora, a tabela mesclada é mais plausível.

timestamp Variable-1 Variable-2
12:00:00 1.0 2,2
12:00:30 1.5 2.6
12:01:00 0,9 1.4
12:01:30 2,2 1.7
12:02:00 1,3 2.0

Os valores de variáveis diferentes em carimbos de data/hora próximos estão bem alinhados e o modelo do MVAD agora pode extrair informações de correlação.

Limitações

Há algumas limitações nas APIs de treinamento e de inferência, você deve estar ciente dessas limitações para evitar erros.

Limitações gerais

  • Janela deslizante: 28 a 2.880 carimbos de data/hora. O padrão é 300. Para dados periódicos, defina o comprimento de 2 a 4 ciclos como a janela deslizante.
  • Números de variáveis: para treinamento e inferência de lote, no máximo, 301 variáveis.

Limitações de treinamento

  • Carimbos de data/hora: no máximo, 10.000.000. Uma quantidade muito pequena de carimbos de data/hora poderá diminuir a qualidade do modelo. É recomendável ter mais de 5 mil carimbos de data/hora.
  • Granularidade: a granularidade mínima é per_second.

Limitações de inferência do lote

  • Carimbos de data/hora: no máximo, 20 mil, e um comprimento de, pelo menos, uma janela deslizante.

Limitações de inferência de streaming

  • Carimbos de data/hora: no máximo, 2.880, e um comprimento de, pelo menos, uma janela deslizante.
  • Detecção de carimbos de data/hora: de um a dez.

Qualidade do modelo

Como lidar com falsos positivos e falsos negativos em cenários reais?

Fornecemos uma gravidade que indica a significância das anomalias. Os falsos positivos podem ser filtrados com a configuração de um limite na gravidade. Às vezes, o excesso de falsos positivos pode aparecer quando há mudanças de padrão nos dados de inferência. Nesses casos, um modelo pode precisar ser treinado novamente com novos dados. Se os dados de treinamento contiverem muitas anomalias, poderá haver falsos negativos nos resultados da detecção. Isso ocorre porque o modelo aprende os padrões com base nos dados de treinamento, e as anomalias podem trazer um desvio para o modelo. Assim, a limpeza adequada dos dados pode ajudar a reduzir os falsos negativos.

Como estimar qual modelo é melhor ser usado de acordo com a perda de treinamento e a perda de validação?

Em geral, é difícil decidir qual modelo é o melhor sem um conjunto de dados rotulado. No entanto, podemos aproveitar as perdas de treinamento e de validação para ter uma estimativa aproximada e descartar esses modelos ruins. Primeiro, precisamos observar se as perdas de treinamento convergem. As perdas divergentes geralmente indicam a má qualidade do modelo. Em segundo lugar, os valores de perda podem ajudar a identificar se ocorre um subajuste ou um sobreajuste. Os modelos que estão subajustados ou sobreajustados podem não ter o desempenho desejado. Em terceiro lugar, embora a definição da função de perda não reflita diretamente o desempenho da detecção, os valores de perda podem ser uma ferramenta auxiliar para estimar a qualidade do modelo. Um valor de baixa perda é uma condição necessária para um bom modelo, ou seja, podemos descartar os modelos com altos valores de perda.

Armadilhas comuns

Além da tabela de códigos de erro, aprendemos com clientes como você algumas armadilhas comuns ao usar as APIs do MVAD. Esta tabela ajudará você a evitar esses problemas.

Armadilha Consequência Explicação e solução
Os carimbos de data/hora nos dados de treinamento e/ou nos dados de inferência não foram arredondados para serem alinhados com a respectiva frequência de dados de cada variável. Os carimbos de data/hora dos resultados da inferência não são os esperados: há poucos carimbos de data/hora ou um número excessivo deles. Confira Arredondamento de carimbo de data/hora.
Muitos pontos de dados anormais nos dados de treinamento A precisão do modelo é prejudicada porque trata pontos de dados anormais como padrões normais durante o treinamento. Empiricamente, mantenha a taxa anormal em 1% ou abaixo.
Poucos dados de treinamento A precisão do modelo é comprometida. Empiricamente, o treinamento de um modelo do MVAD exige 15 mil ou mais pontos de dados (carimbos de data/hora) por variável para manter uma boa precisão.
Considerando todos os pontos de dados com isAnomaly=true como anomalias Muitos falsos positivos Você deve usar isAnomaly e severity (ou score) para eliminar anomalias que não são graves e (opcionalmente) usar o agrupamento para verificar a duração das anomalias a fim de suprimir os ruídos aleatórios. Veja a seção Perguntas frequentes abaixo para obter a diferença entre severity e score.
As subpastas são compactadas no arquivo de dados para treinamento ou inferência. Os arquivos de dados CSV dentro de subpastas são ignorados durante o treinamento e/ou a inferência. Nenhuma subpasta é permitida no arquivo zip. Confira a Estrutura de pastas para obter detalhes.
Excesso de dados no arquivo de dados de inferência: por exemplo, a compactação de todos os dados históricos no arquivo zip de dados de inferência Você não verá nenhum erro, mas terá um desempenho degradado quando tentar carregar o arquivo zip no blob do Azure e quando tentar executar a inferência. Veja a Quantidade de dados para obter detalhes.
Criação de recursos do Detector de Anomalias em regiões do Azure que não dão suporte ao MVAD ainda e chamando APIs do MVAD Você receberá o erro "Recurso não encontrado" ao chamar as APIs do MVAD. Durante o estágio de versão prévia, o MVAD está disponível somente em regiões limitadas. Marque Novidades no Detector de Anomalias e saiba as novidades das distribuições das regiões da MVAD. Você também pode registrar um problema no GitHub ou entrar em contato conosco em AnomalyDetector@microsoft.com para solicitar regiões específicas.

Perguntas frequentes

Como funciona a janela deslizante do MVAD?

Vamos usar dois exemplos para aprender como a janela deslizante do MVAD funciona. Suponha que você tenha definido slidingWindow = 1.440, e que os dados de entrada tenham a granularidade de um minuto.

  • Cenário de streaming: você quer prever se o ponto de dados UM em "2021-01-02T00:00:00Z" é anormal. O startTime e o endTime serão o mesmo valor ("2021-01-02T00:00:00Z"). A fonte de dados de inferência, no entanto, precisa conter pelo menos 1.440 + 1 carimbos de data/hora. Porque o MVAD usará os dados à esquerda antes do ponto de dados de destino ("2021-01-02T00:00:00Z") para decidir se o destino é uma anomalia. O comprimento dos dados iniciais necessários é slidingWindow ou 1.440 nesse caso. 1\.440 = 60 * 24, portanto, os dados de entrada precisam ser iniciados pelo menos em "2021-01-01T00:00:00Z".

  • Cenário de lote: você tem vários pontos de dados de destino a serem previstos. O endTime será maior que o startTime. A inferência nesses cenários é executada em uma forma de "movimentação de janela". Por exemplo, o MVAD usará os dados de 2021-01-01T00:00:00Z a 2021-01-01T23:59:00Z (inclusivo) para determinar se os dados em 2021-01-02T00:00:00Z são anormais. Depois, ele avançará e usará dados de 2021-01-01T00:01:00Z a 2021-01-02T00:00:00Z (inclusivo) para determinar se os dados em 2021-01-02T00:01:00Z são anormais. Ele se move da mesma maneira (usando 1.440 pontos de dados para a comparação) até o último carimbo de data/hora especificado por endTime (ou o carimbo de data/hora mais recente real). Portanto, sua fonte de dados de inferência precisa conter dados começando de startTime - slidingWindow e, preferencialmente, conter o tamanho total de slidingWindow + (endTime - startTime).

Qual é a diferença entre severity e score?

Normalmente, recomendamos que você use severity como o filtro para remover as 'anomalias' que não são tão importantes para seus negócios. Dependendo do cenário e do padrão de dados, essas anomalias que são menos importantes geralmente têm valores relativamente menores severity ou valores altos autônomos severity (descontinuados), como picos aleatórios.

Quando há uma necessidade de regras mais sofisticadas do que limites em relação à severity ou à duração de valores altos contínuos severity, você pode usar score para criar filtros mais avançados. É interessante entender como o MVAD está usando score para determinar anomalias:

Consideramos se um ponto de dados é anômalo das perspectivas global e local. Se score em um carimbo de data/hora for maior que um determinado limite, o carimbo de data/hora será marcado como uma anomalia. Se score for menor que o limite, mas relativamente maior em um segmento, ele também será marcado como uma anomalia.

Próximas etapas