Referência de comandos da CLI do ML.NET

  • Artigo

Os comandos classification, regression e recommendation são os principais comandos fornecidos pela ferramenta de CLI do ML.NET. Esses comandos permitem que você gere modelos de ML.NET de boa qualidade para modelos de classificação, regressão e recomendação usando AutoML (machine learning automatizado), bem como o código C# de exemplo para executar/pontuar esse modelo. Além disso, é gerado o código C# para treinar o modelo para você pesquisar o algoritmo e as configurações do modelo.

Observação

Este artigo refere-se à CLI do ML.NET e ao AutoML do ML.NET, que estão atualmente em versão prévia, e o material pode estar sujeito a alterações.

Visão geral

Exemplo de uso:

mlnet regression --dataset "cars.csv" --label-col price

Os comandos da tarefa ML mlnet (classification, regression, recommendation e forecasting) geram os seguintes ativos:

  • Um modelo serializado. zip ("melhor modelo") pronto para uso.
  • Código C# para executar/pontuar o modelo gerado.
  • Código C# com o código de treinamento usado para gerar esse modelo.

Os primeiros dois ativos podem ser usados diretamente em seus aplicativos de usuário final (aplicativo Web ASP.NET Core, serviços, aplicativo da área de trabalho etc.) para fazer previsões com esse modelo.

O terceiro ativo, o código de treinamento, mostra a você que o código de API do ML.NET foi usado pela CLI para treinar o modelo gerado, de modo que você pode investigar o algoritmo e as configurações específicos do modelo.

Exemplos

O comando mais simples da CLI para um problema de classificação (o AutoML infere a maior parte da configuração dos dados fornecidos):

mlnet classification --dataset "customer-feedback.tsv" --label-col Sentiment

Outro comando simples da CLI para um problema de regressão:

mlnet regression --dataset "cars.csv" --label-col Price

Crie e treine um modelo de classificação com um conjunto de dados de treinamento, um conjunto de dados de teste e ainda mais argumentos explícitos de personalização:

mlnet classification --dataset "/MyDataSets/Population-Training.csv" --test-dataset "/MyDataSets/Population-Test.csv" --label-col "InsuranceRisk" --cache on --train-time 600

Opções de comando

Os comandos da tarefa ML mlnet (classification, regression, recommendation, forecasting e train) treinam vários modelos com base nas opções de CLI de ML.NET e conjunto de dados fornecidos. Esses comandos também selecionam o melhor modelo, salvam o modelo como um arquivo .zip serializado e geram código C# relacionado para pontuação e treinamento.

Opções de classificação

A execução de mlnet classification treinará um modelo de classificação. Escolha este comando se quiser um Modelo de ML para categorizar dados em 2 ou mais classes (por exemplo, análise de sentimento).

mlnet classification

--dataset <path> (REQUIRED)

--label-col <col> (REQUIRED)

--cache <option>

--has-header (Default: true)

--ignore-cols <cols>

--log-file-path <path>

--name <name>

-o, --output <path>

--test-dataset <path>

--train-time <time> (Default: 30 minutes, in seconds)

--validation-dataset <path>

-v, --verbosity <v>

-?, -h, --help

Opções de regressão

A execução mlnet regression treinará um modelo de regressão. Escolha este comando se quiser que um Modelo de ML preveja um valor numérico (por exemplo, previsão de preço).

mlnet regression

--dataset <path> (REQUIRED)

--label-col <col> (REQUIRED)

--cache <option>

--has-header (Default: true)

--ignore-cols <cols>

--log-file-path <path>

--name <name>

-o, --output <path>

--test-dataset <path>

--train-time <time> (Default: 30 minutes, in seconds)

--validation-dataset <path>

-v, --verbosity <v>

-?, -h, --help

Opções de recomendação

A execução de mlnet recommendation treinará um modelo de recomendação. Escolha este comando se quiser que um Modelo de ML recomende itens aos usuários com base em classificações (por exemplo, recomendação de produto).

mlnet recommendation

--dataset <path> (REQUIRED)

--item-col <col> (REQUIRED)

--rating-col <col> (REQUIRED)

--user-col <col> (REQUIRED)

--cache <option>

--has-header (Default: true)

--log-file-path <path>

--name <name>

-o, --output <path>

--test-dataset <path>

--train-time <time> (Default: 30 minutes, in seconds)

--validation-dataset <path>

-v, --verbosity <v>

-?, -h, --help

Opções de entrada inválidas fazem com que a ferramenta da CLI emita uma lista de entradas válidas e uma mensagem de erro.

Opções de previsão

A execução de mlnet forecasting treinará um modelo de previsão de série temporal. Escolha este comando se quiser que um Modelo de ML preveja um valor com base em dados históricos (por exemplo, previsão de vendas).

mlnet forecasting

--dataset <dataset> (REQUIRED)

--horizon <horizon> (REQUIRED)

--label-col <label-col> (REQUIRED)

--time-col <time-col> (REQUIRED)

--cache <Auto|Off|On>

--has-header

--log-file-path <log-file-path>

--name <name>

-o, --output <output>

--test-dataset <test-dataset>

--train-time <train-time>

-v, --verbosity <verbosity>

Opções de treinamento

A execução de mlnet train treinará um modelo com base em um arquivo "mbconfig" gerado do Model Builder. Para que esse comando funcione, os dados de treinamento devem estar no mesmo diretório que o arquivo "mbconfig".

-training-config <training-config> (REQUIRED)

--log-file-path <log-file-path>

-v, --verbosity <verbosity>

Dataset

--dataset | -d (string)

Esse argumento fornece o caminho do arquivo para uma das seguintes opções:

  • A: O arquivo do conjunto de dados completo: Se essa opção for usada e o usuário não estiver fornecendo --test-dataset e --validation-dataset, as abordagens de validação cruzada (k-fold etc.) ou de divisão de dados automatizada serão usadas internamente para validar o modelo. Nesse caso, o usuário precisará apenas fornecer o caminho do arquivo do conjunto de dados.

  • B: O arquivo do conjunto de dados de treinamento: Se o usuário também estiver fornecendo conjuntos de dados para a validação de modelo (usando --test-dataset e, opcionalmente, --validation-dataset), então o argumento --dataset significa ter apenas o "conjunto de dados de treinamento". Por exemplo, ao usar uma abordagem de 80-20% para validar a qualidade do modelo e obter métricas de precisão, o "conjunto de dados treinamento" terá 80% dos dados e o "conjunto de dados de teste" terá 20% dos dados.

Conjunto de dados de teste

--test-dataset | -t (string)

Caminho do arquivo que aponta para o arquivo de conjunto de dados de teste, por exemplo, ao usar uma abordagem de 80-20% ao realizar validações regulares para obter métricas de precisão.

Ao usar --test-dataset, --dataset também é necessária.

O argumento --test-dataset é opcional, a menos que o --validation-dataset seja usado. Nesse caso, o usuário precisa usar os três argumentos.

Conjunto de dados de validação

--validation-dataset | -v (string)

Caminho do arquivo apontando para o arquivo de conjunto de dados de validação. O conjunto de dados de validação é opcional em qualquer caso.

Se usar um validation dataset, o comportamento deverá ser:

  • Os argumentos test-dataset e --dataset também são necessários.

  • O conjunto de dados validation-dataset é usado para estimar o erro de previsão para a seleção de modelo.

  • O test-dataset é usado para a avaliação do erro de generalização do modelo final escolhido. O ideal é que o conjunto de teste seja mantido em um "cofre" e seja levado somente no final da análise de dados.

Basicamente, ao usar um validation dataset mais o test dataset, a fase de validação é dividida em duas partes:

  1. Na primeira parte, você apenas examina seus modelos e seleciona a abordagem com melhor desempenho usando os dados de validação (=validation)
  2. Em seguida, você pode estimar a precisão da abordagem selecionada (=test).

Portanto, a separação dos dados pode ser 80/10/10 ou 75/15/10. Por exemplo:

  • O arquivo training-dataset deve ter 75% dos dados.
  • O arquivo validation-dataset deve ter 15% dos dados.
  • O arquivo test-dataset deve ter 10% dos dados.

Em qualquer caso, essas porcentagens serão decididas pelo usuário usando a CLI que fornecerá os arquivos já dividido.

Coluna de rótulo

--label-col (int ou string)

Com este argumento, uma coluna de destino/objetivo específico (a variável que você deseja prever) pode ser especificada usando o nome da coluna definido no cabeçalho do conjunto de dados ou o índice numérico da coluna no arquivo do conjunto de dados (os valores de índice da coluna começam em 0).

Este argumento é usado para problemas de classificação e regressão.

Coluna de item

--item-col (int ou string)

A coluna de item tem a lista de itens que os usuários classificam (os itens são recomendados aos usuários). Essa coluna pode ser especificada usando o nome da coluna definido no cabeçalho do conjunto de dados ou o índice numérico da coluna no arquivo do conjunto de dados (os valores de índice de coluna começam em 0).

Esse argumento é usado apenas para a tarefa de recomendação.

Coluna de classificação

--rating-col (int ou string)

A coluna de classificação tem a lista das classificações dadas aos itens pelos usuários. Essa coluna pode ser especificada usando o nome da coluna definido no cabeçalho do conjunto de dados ou o índice numérico da coluna no arquivo do conjunto de dados (os valores de índice de coluna começam em 0).

Esse argumento é usado apenas para a tarefa de recomendação.

Coluna do usuário

--user-col (int ou string)

A coluna do usuário tem a lista de usuários que dão classificações aos itens. Essa coluna pode ser especificada usando o nome da coluna definido no cabeçalho do conjunto de dados ou o índice numérico da coluna no arquivo do conjunto de dados (os valores de índice de coluna começam em 0).

Esse argumento é usado apenas para a tarefa de recomendação.

Ignorar colunas

--ignore-columns (string)

Com este argumento, você pode ignorar as colunas existentes no arquivo de conjunto de dados para que elas não sejam carregadas e usadas pelos processos de treinamento.

Especifique os nomes de colunas que você deseja ignorar. Use ',' (vírgula com espaço) ou ' ' (espaço) para separar vários nomes de coluna. Você pode usar aspas para nomes de coluna que contêm espaço em branco (por exemplo, "usuário logado").

Exemplo:

--ignore-columns email, address, id, logged_in

Tem cabeçalho

--has-header (bool)

Especifique se os arquivos de conjunto de dados têm uma linha de cabeçalho. Os valores possíveis são:

  • true
  • false

A CLI do ML.NET tentará detectar essa propriedade se esse argumento não for especificado pelo usuário.

Tempo de treinamento

--train-time (string)

Por padrão, o tempo máximo de exploração/treinamento é de 30 minutos.

Esse argumento define o tempo máximo (em segundos) para o processo explorar vários treinadores e configurações. O tempo configurado poderá ser excedido se o tempo fornecido for muito curto (digamos, dois segundos) para uma única iteração. Nesse caso, o tempo real é o tempo necessário para produzir uma configuração de modelo em uma única iteração.

O tempo necessário para iterações pode variar, dependendo do tamanho do conjunto de dados.

Cache

--cache (string)

Se você usar o armazenamento em cache, o conjunto de dados de treinamento inteiro será carregado na memória.

Para conjuntos de dados pequenos e médios, usar o cache pode melhorar drasticamente o desempenho de treinamento, o que significa que o tempo de treinamento pode ser menor do que quando você não usa o cache.

No entanto, para grandes conjuntos de dados, carregar todos os dados na memória pode ter um efeito negativo, pois você poderá ficar com memória insuficiente. Ao treinar com arquivos de conjunto de dados grandes sem usar o cache, o ML.NET transmitirá partes de dados da unidade quando ele precisar carregar mais dados durante o treinamento.

É possível especificar os seguintes valores:

on: Força o cache a ser usado durante o treinamento. off: Força o cache a não ser usado durante o treinamento. auto: Dependendo da heurística de AutoML, o cache será usado ou não. Em geral, conjuntos de dados pequenos/médios usarão o cache e grandes conjuntos de dados não usarão o cache se você usar a escolha auto.

Se você não especificar o parâmetro --cache, a configuração de cache auto será usada por padrão.

Nome

--name (string)

O nome para a solução ou projeto de saída criado. Se nenhum nome for especificado, o nome sample-{mltask} será usado.

O arquivo de modelo do ML.NET (arquivo zip) também receberá o mesmo nome.

Caminho de saída

--output | -o (string)

Local/pasta raiz para colocar a saída gerada. O padrão é o diretório atual.

Detalhamento

--verbosity | -v (string)

Define o nível de detalhamento da saída padrão.

Valores permitidos são:

  • q[uiet]
  • m[inimal] (por padrão)
  • diag[nostic] (nível de informações de registro em log)

Por padrão, a ferramenta da CLI deve mostrar alguns comentários mínimos (minimal) quando estiver funcionando, por exemplo, mencionar que ela está funcionando e, se possível, quanto tempo falta o percentual de tempo transcorrido.

Ajuda

-h |--help

Imprime uma ajuda para o comando com uma descrição para o parâmetro de cada comando.

Confira também