Package: mllibprodest
Biblioteca de ML (Machine Learning) - ProdestA finalidade desta biblioteca é prover interfaces e funções que dão suporte ao provisionamento de modelos de ML na Stack
de ML do Prodest.Acesse adocumentação da lib!Workflowbásico para construção, disponibilização e publicação de modelos:Pré-requisitosPython >= 3.10.Instruções:Linux (Geralmente já vem instalado por padrão)ouWindows.Git.Instruções:LinuxouWindows.Venv.Gerenciador de ambiente virtual Python adotado no tutorial. Instruções:Linux e Windows (escolha o sistema na página).
Ou qualquer outro gerenciador de ambiente Python que preferir.1. Realize experimentos e escolha o modeloEsta é uma das etapas iniciais de um projeto para o desenvolvimento de um modelo deMachine Learning. Neste momento é
necessário entender o problema a ser resolvido; levantar requisitos; obter e tratar os dados, etc. Também é nessa etapa
que se verifica a viabilidade (ou não) da construção de um modelo.Neste passo você temtotal liberdadepara construir o seu modelo e realizar os experimentos que quiser. Entretanto,
é importante que os resultados e artefatos gerados pelos experimentos, desde já, sejam registrados para facilitar a
comparação dos resultados obtidos e a publicação do modelo. Esta lib utiliza oMLflowcomo plataforma para registro dos experimentos/modelos (no contexto da lib, o
MLflow é chamado deProvider).Apesar do registro dos experimentos ser importante, deixar de registrá-los agoranãovai impedir que você construa o
seu modelo!Você tem duas opções:Seguir com a construção do modelo e execução dos experimentos e, caso chegue à conclusão de que o modelo é viável,
ajustar o código para realizar o registro; ouFazer uma pausa e entender primeiro como registrar seus experimentos no MLflow e já construir o código com a lógica
necessária para isso.Independente da opção escolhida, haverá necessidade de, agora ou depois, aprender (caso não saiba) como registrar os
experimentos do modelo no MLflow.
Para alcançar esse objetivo, leia adocumentação oficial do MLflow.Segue abaixo, um exemplo simples de como utilizar o MLflow para registrar os experimentos de um modelo construído com oscikit-learn.importosimportmlflow.sklearn# Importa o sklearn através do MLflowimportpickle# Para gerar um artefato de exemplo# Obs.: Utilize as duas linhas abaixo, exatamente como apresentadas, para configurar o# parâmetro 'Tracking URI' do MLflow nos seus códigos de testes. Dessa forma, quando subir# para produção não haverá necessidade de modificá-las, pois lá o parâmetro 'Tracking URI'# será obtido diretamente através da variável de ambiente 'MLFLOW_TRACKING_URI'.ifos.environ.get('MLFLOW_TRACKING_URI')isNone:mlflow.set_tracking_uri('sqlite:///teste_mlflow.db')# Configura o experimento (se não existir, cria)mlflow.set_experiment(experiment_name="Teste_sklearn")# Inicia uma execução do experimento (um experimento pode possuir várias execuções)mlflow.start_run(run_name="t1",description="teste 1")# Registra algumas informações adicionais no experimento (coloque as informações que julgar# necessárias, no formato dict)tags={"Projeto":"Teste","team":"ML","util":"Informação útil"}mlflow.set_tags(tags)# Inicia o registro dos logs da execução do sklearnmlflow.sklearn.autolog()# TODO: Inclua aqui a lógica para fazer o fit do modelo'''Exemplo de modelo, somente para o propósito de testes!'''# Adaptado de https://scikit-learn.org/stable/modules/tree.html#classificationimportmatplotlibimportnumpyasnpfromsklearnimporttreeX=np.array([[0,0],[1,1]])Y=np.array([0,1]).reshape(-1)clf=tree.DecisionTreeClassifier()clf=clf.fit(X,Y)'''Fim do exemplo de modelo.''''''Salva um artefato de seu interesse no MLflow (podem ser arquivos em diversos formatos: txt,pkl, png, jpeg, etc.). Exemplos de artefatos: gráficos, objetos persistidos com pickle,enfim, tudo que for relevante e/ou necessário para que o modelo funcione e/ou para análisedas execuções.'''# Cria um aterfato de teste no formato pickle (obs.: todas as classes da lib tem os métodos# 'convert_artifact_to_pickle' e 'convert_artifact_to_object' para auxiliar na persistência# dos artefatos)artefato={"t":1}caminho_artefato="artefato.pkl"withopen(caminho_artefato,'wb')asarq:pickle.dump(artefato,arq)# Salva o artefato criadomlflow.log_artifact(caminho_artefato)# Finaliza o experimentomlflow.end_run()print("\nTeste finalizado!\n")Se você quiser testar um registro de experimento através do código acima, faça o seguinte:Crie uma pasta para testes;Copie e cole o código acima em um editor de texto simples e salve com o nome 'testeml.py' dentro da pasta criada;Abra um prompt de comando ou terminal e entre na pasta criada;Crie e ative um ambiente virtual Python, conforme instruções:Linux e Windows (escolha o sistema na página);Atualize o pip e o setuptools;Instale os pacotes mlflow, sklearn, matplotlib e numpy;pipinstall--upgradepipsetuptoolspipinstallmlflow==2.9.2scikit-learn==1.3.2matplotlib==3.8.2numpy==1.26.2Rode o teste (ignore as mensagens do tipo 'INFO' de criação do banco de dados);pythontesteml.pyCabe observar que: depois de rodar o código de teste, foi criada uma pasta chamada 'mlruns', dentro da pasta de
testes, que serve para armazenar os artefatos gerados pelo código e que são apresentados na interface do MLflow.
Abaixo segue uma listagem do conteúdo gerado pelo código de teste (obs.: essa parte do caminho vai ser diferente de
acordo com cada experimento/execução realizados: '1/1fb6ac45b0ca4babb3bacb48320c790b'. O conteúdo da pasta também será
diferente de acordo com cada modelo).(env)user:~/teste/mlruns/1/1fb6ac45b0ca4babb3bacb48320c790b/artifacts/artifacts$dir
artefato.pklestimator.htmlmodeltraining_confusion_matrix.pngtraining_precision_recall_curve.pngtraining_roc_curve.pngDentro da pasta criada para testes também foi gerado um arquivo chamado 'teste_mlflow.db', que é um pequeno banco
de dadosSQlite, que serve para armazenar os modelos que foram registrados.Inicie o servidor do MLflow;Perceba que a pasta 'mlruns' e o arquivo 'teste_mlflow.db' são passados como parâmetros na hora de iniciar o
servidor, para que o experimento de teste possa ser visualizado. Portanto, émandatóriosempre iniciar o servidor do
MLflowde dentro da pastaonde se encontra o código que fará o registro dos artefatos e dos experimentos/modelos.DICA: Abra um outro prompt de comando ou terminal diferente; entre na pasta onde se encontra o código para registro
dos experimentos/modelo;ativeo ambiente virtual criado anteriormente; execute o comando para iniciar o servidor do MLflow de dentro desta pasta. Pois assim, você
conseguirá rodar o código e já observar os resultados sem ter que parar o servidor para liberar o prompt ou terminal.mlflowserver--backend-store-urisqlite:///teste_mlflow.db--host0.0.0.0-p5000--default-artifact-rootmlrunsVerifique se o experimento foi criado. Acesse o MLFlow:http://localhost:5000e procure
pelo experimento/execução 'Teste_sklearn' na seçãoExperiments(se o experimento não estiver listado, verifique
se o servidor foi iniciado de dentro da pasta correta);Clique na execução do experimento que se encontra na coluna 'Run Name' (destaque em verde);Verifique se os artefatos foram gravados;Finalize o servidor do MLflow. Faça 'CTRL+c' no prompt de comando ou terminal onde ele foi iniciado;Apague a pasta criada para realização dos testes.NOTA: Existem vários outrosframeworkssuportados: TensorFlow, Keras, Pytorch, etc. (veja a lista completa para
Python emMLflow Python API), inclusive é possível registrar
modelos quenão são suportados nativamentepelo MLflow utilizando a funçãomlflow.pyfunc.ATENÇÃO: Sua interação direta com o MLflow será somente para registro dos experimentos/modelo. Essa interação é
essencial porque dá liberdade ao desenvolvedor para escolher oframeworkque achar mais adequado para construção
do seu modelo. A lib disponibiliza funções para obtenção do modelo registrado e dos seus artefatos, além de
outras funções relacionadas à carga dedatasets. Leia a documentação das interfaces, classes e funções da lib para
mais detalhes.Antes de ir para os próximos passos...Quando você já tiver realizado vários experimentos utilizando o MLflow e decidido por colocar o modelo em produção,
será preciso registrar o modelo treinado para que o mesmo seja carregado e usado na construção dosworkers, conforme
descrito no passo 3. Siga as instruções abaixo para registrar o modelo:Caso o servidor do MLflow não esteja rodando, entre na pasta onde oscript que salvará o experimento(código
desenvolvido para criação do modelo) se encontra;Ative o ambiente virtual Python criado para rodar os experimentos, ou se preferir, crie um novo. Instruções:Linux e Windows (escolha o sistema na página);Inicie o servidor do MLflow;mlflowserver--backend-store-urisqlite:///teste_mlflow.db--host0.0.0.0-p5000--default-artifact-rootmlrunsAcesse o MLflow (http://localhost:5000) e clique no experimento que foi criado por você (se
o experimento não estiver listado, verifique se o servidor do MLflow foi iniciado de dentro da pasta correta);Clique no link (que está na coluna'Run Name') para a rodada do experimento que deseja registrar;Clique no botão'Register Model'e escolha a opção'Create New Model';Dê um nome para o modelo e clique em'Register';Na barra superior clique em'Models';Clique no link para a última versão do modelo que está em'Latest Version';Na opção'Stage'troque de'None'para'Production'e clique em OK.Quando for testar a implementação dosworkers(passo 3), lembre de deixar o servidor do MLflow rodando para que seja
possível carregar o modelo.2. Organize o código de acordo com otemplateUma vez que o modelo foi desenvolvido e testado, agora é o momento de iniciar as tratativas para publicá-lo nastackde ML do
Prodest. Porém, antes, é oportuno mostrar como o modelo será integrado àstack. Esta integração se dará através de
componentes denominadosworkers, cuja codificação é de responsabilidade de quem está construindo o modelo. Na
ilustração abaixo é possível observar que osworkerssão acessados pelos componentes de apoio dastackpara
permitir a publicação dos modelos. Caso seja necessário, uma mesma stack poderá publicar mais de um modelo.Existem dois tipos deworkers:worker_pub: Fornece os métodos necessários para publicação do modelo.worker_retrain: Responsável pela avaliação do desempenho do modelo e retreinamento, se for preciso.Para que o modelo possa ser publicado, é imprescindível que a organização do código seja conforme especificado na pasta
'templates' (esta pasta vem junto com repositório da lib).As regras são simples mas precisam ser seguidas, caso contrário a publicação do modelo falhará.Os nomes das pastas 'worker_pub' e 'worker_retrain' não podem ser alterados;Os nomes dos scripts padrões contidos nestas pastas não podem ser alterados;(Opcional, mas recomendável). Separe as funções utilitárias para o funcionamento dosworkersnos arquivos 'utils.py';Gere um arquivo derequirementspara cada um dosworkersseparadamente. Dica: Use um ambiente virtual Python
separado para cadaworker, instale os pacotes requeridos para o funcionamento deles e no final gere um arquivo
'requirements.txt' para cadaworker;Não importe código de fora destas pastas. Se os doisworkersprecisarem de uma mesma função, faça uma cópia desta em
cada pasta (o arquivo 'utils.py' pode ajudar a organizar estas funções!);Cuide para que os importes funcionem corretamente, dentro de cada pasta,sem precisarconfigurar a variável de
ambiente PYTHONPATH;Utilize a pasta 'temp_area' para salvar e ler os arquivos temporários que forem criados.NOTA: Os scripts 'mytest_pub.py' e 'mytest_retrain.py' podem ser utilizados por você para criação de testes
personalizados, para isso basta implementar a função 'test' em cada um deles. Já os scripts 'test_pub.py' e
'test_retrain.py' podem ser usados para testar se algumas premissas foram atendidas, através de testes padrões
da lib e a execução automática dos testes personalizados que foram implementados pelo usuário. No passo 3 é mostrado
como rodar os scripts 'test_pub.py' e 'test_retrain.py'.Caso queira, você pode criar pastas ou arquivos de apoio dentro das pastas dosworkerspara organizar seu código,
desde que não modique a localização dos arquivos especificada pelostemplates.Para obter e utilizar a pasta com ostemplates:Clone o repositório da lib;gitclonehttps://github.com/prodest/mllibprodest.gitEntre na pasta gerada no processo de clonagem do repositório e copie o conteúdo da pasta 'templates' para outro local
de sua preferência (não trabalhe na pasta do repositório).Organize o código responsável pelo treino do modelo. Copie todos osscriptsque são utilizados para treinar o modelo
para a pasta 'training_model' (nãoincluir a pasta 'env' nem arquivos desnecessários) e altere oscript'train.py' para que ele chame oscriptprincipal do modelo, ou, se preferir, apague  oscript'train.py' e
renomeie oscriptprincipal do modelo para 'train.py'.Gere o arquivo derequirementspara o código do modelo e coloque-o dentro da pasta 'training_model'.NOTA: Não altere o nome da pasta 'training_model' nem doscript'train.py'. Estruture o código para que
não haja necessidade de criar a variável de ambiente PYTHONPATH para fazer os 'imports' do código do modelo.3. Implemente as interfaces da bibliotecaAntes de iniciar a implementação das interfaces, é importante criar um ambiente virtual Pythonseparadamentepara cadaworker. Dessa forma você conseguirá gerar os arquivos derequirementssem maiores problemas. Siga as instruções abaixo:Para o worker_pub:Abra um prompt de comando ou terminal;Entre na pasta para onde você copiou o conteúdo da pasta 'templates';Entre na pasta 'worker_pub', crie e ative um ambiente virtual Python, conforme instruções:Linux e Windows (escolha o sistema na página);Atualize o pip e o setuptools;Instale a lib para o worker_pub;pipinstall--upgradepipsetuptools
pipinstallmllibprodestFeche o prompt de comando ou terminal.Para o worker_retrain:Abraoutroprompt de comando ou terminal (Nãoaproveite o anterior de forma alguma, pois dará errado!);Entre na pasta para onde você copiou o conteúdo da pasta 'templates';Entre na pasta 'worker_retrain', crie e ativeoutroambiente virtual Python;Atualize o pip e o setuptools;Instale a lib para o worker_retrain;pipinstall--upgradepipsetuptools
pipinstallmllibprodestFeche o prompt de comando ou terminal.Pronto. Agora você tem um ambiente virtual Python para cadaworker. Quando for utilizar uma IDE ou editor de código
para implementar as interfaces, configure para que eles utilizem os ambientes virtuais criados para os respectivosworkers. Dessa forma, à medida que você for produzindo o código e necessitar de instalar pacotes, esses serão
instalados nos ambientes virtuais criados. Quando terminar a implementação, basta você gerar os arquivos derequirementscom base no ambiente virtual de cadaworkerseparadamente. Acredite, isso vai te ajudar bastante!Outro ponto importante antes de implementar as interfaces é saber que: para publicar o modelo será necessário a criação
de três artefatos obrigatórios, inclusive seguindo o mesmo nome (case sensitive). Estes artefatos devem ser
dicionários (dict) salvos com oPickle(utilize a função
'convert_artifact_to_pickle' quando estiver implementando as interfaces):TrainingParams.pkl: Deve conter os parâmetros que você escolheu utilizar no treinamento do modelo. Não há
necessidade de colocar os parâmetros nos quais você manteve os valoresdefault. Você pode colocar outros parâmetros,
criados por você, necessários para que o modelo funcione. Coloque o nome
do parâmetro como nome da chave e o valor do parâmetro como valor da chave. Ex. baseado noDecisionTreeClassifier:
{'criterion': 'entropy', 'max_depth': '20', 'random_state': '77', 'meu_parametro_personalizado': 'teste'}.TrainingDatasetsNames.pkl: Deve conter os tipos de datasets e os nomes dos respectivos arquivos utilizados no
treinamento do modelo. Exemplo: {'features': 'nome_arquivo_features', 'targets': 'nome_arquivo_targets'}.BaselineMetrics.pkl: Deve conter as métricas que você achar relevantes para decidir se o modelo precisa ser
retreinado. Por exemplo, você poderia definir a métrica acurácia mínima e caso o modelo que estiver em produção, ao ser
avaliado, não estiver atingindo o valor dessa métrica, será um indicativo de que ele precisa ser retreinado. Outro exemplo
claro da necessidade de retreinamento é quando um modelo de classificação é treinado para predizer um conjunto delabelse por um motivo qualquer surgem novoslabels. Nesse caso, o modelo não saberá predizer esteslabelse necessitará
ser retreinado em um dataset atualizado com os novoslabels. Exemplo: {'acuracia_minima': 0.94,
'labels_presentes_no_treino': ['gato', 'cachorro']}.NOTA: Estes artefatos deverão ser criados pelo script utilizado para registro dos experimentos no processo de
treinamento do modelo e salvos através da função 'mlflow.log_artifact', no momento da realização dos experimentos. Os
artefatos salvos junto com o modelo devem ser utilizados na implementação das funcionalidades das interfaces no momento
da construção dosworkers. A única maneira de obter parâmetros e informações acerca do modelo registrado será por
intermédio destes artefatos. Por favor, não persista nada localmente, pois osworkersnão trocarão mensagens nem
compartilharão acesso à dados entre si.Para implementar as interfaces e construir osworkersbasta editar ostemplatesconforme abaixo:REGRAS: Implemente todos os métodos solicitados respeitando os tipos dos parâmetros e de retorno. Não troque os
nomes dos parâmetros.worker_pub:Abra o arquivo 'pub1.py', que se encontra na pasta 'worker_pub/models', e implemente os métodos da interfaceModelPublicationInterfaceCLFatravés da classeModeloCLF. Leia os comentários, eles te guiarão na implementação.Abra o arquivo 'params.conf', que se encontra na pasta 'worker_pub', e informe os parâmetros dos modelos.
Leia os comentários, eles te guiarão na configuração.worker_retrain:Abra o arquivo 'retrain1.py', que se encontra na pasta 'worker_retrain/models', e implemente os métodos da interfaceModelPublicationInterfaceRETRAINatravés da classeModeloRETRAIN. Leia os comentários, eles te guiarão na
implementação.Abra o arquivo 'params.conf', que se encontra na pasta 'worker_retrain', e informe os parâmetros dos modelos.
Leia os comentários, eles te guiarão na configuração.NOTA: É possível publicar um ou mais modelos utilizando uma mesmaStack. Para isso, basta fazer as devidas
configurações de cada um dos modelos nos arquivos 'params.conf' constantes nas pastasworker_pubeworker_retrain.A lib disponibiliza vários métodos úteis que auxiliarão na implementação das interfaces.
Todos os métodos estão documentados viadocstringsque, geralmente, são
renderizadas pelas IDEs ou editores de código facilitando a leitura da documentação. Veja alguns métodos úteis disponíveis:make_log- Criação do arquivo para geração de logs.load_datasets- Carga de datasets.load_model- Carga de modelos salvos.load_production_params,load_production_datasets_names,load_production_baseline- Carga das informações
dos modelos publicados, salvas através dos artefatos obrigatórios.convert_artifact_to_pickle- Conversão de um artefato para o formato pickle.convert_artifact_to_object- Conversão de um artefato que está no formato pickle para o objeto de origem.Explore adocumentaçãopara saber das possibilidades de uso da lib.Teste o código produzido!O repositório da lib disponibiliza os scripts 'test_pub.py' e 'test_retrain.py' para realização de testes para
verificar se alguns requisitos solicitados estão sendo atendidos. Também é possível criar testes personalizados através da
implementação da função 'test' que se encontra nos scripts 'mytest_pub.py' e 'mytest_retrain.py'. Todos
estes scripts estão nas pastasworker_pubeworker_retrain.Para testar o seu código siga as instruções abaixo:Caso o servidor do MLflow não esteja rodando, entre na pasta onde o código/script para registro dos experimentos/modelo
se encontra; ative o ambiente virtual Python, instruções:Linux e Windows (escolha o sistema na página),
e inicie o servidor do MLflow:mlflowserver--backend-store-urisqlite:///teste_mlflow.db--host0.0.0.0-p5000--default-artifact-rootmlrunsObtenha o caminho completo da pasta 'mlruns' (ela é criada dentro da pasta onde o script para geração dos
experimentos/modelo foi executado);Se for testar oworkerpub, entre na pasta 'worker_pub' e execute o comando abaixo. Lembre-se de informar o
caminho completo da pasta 'mlruns' através do parâmetro '--mlruns_path';pythontest_pub.py--mlruns_path="caminho completo para a pasta mlruns"Se for testar oworkerretrain, entre na pasta 'worker_retrain' e execute o comando abaixo. Lembre-se de
informar o caminho completo da pasta 'mlruns' através do parâmetro '--mlruns_path';pythontest_retrain.py--mlruns_path="caminho completo para a pasta mlruns"Leia atentamente as mensagens e caso exista alguma inconsistência no teste, atenda ao que for solicitado pelo script.4. Disponibilize o código para publicação do modeloAntes de enviar os códigos, certifique-se que eles estão funcionando de acordo com as regras estabelecidas e que os
arquivos com osrequirementsforam gerados corretamente. Se ocorrer algum erro que impeça a publicação, entraremos
em contato para informar o ocorrido e fornecer as informações sobre o erro.DICA:Nãoé obrigatório, porém se você quiser testar o modelo implementado, antes de disponibilizá-lo para
publicação; clone o repositório daStack de ML do Prodest(versão standalone) e siga as instruções para fazer odeployda Stack e o teste do seu modelo utilizando ela.Para disponibilizar o modelo para publicação:Crie uma pasta chamada 'publicar';Copie as pastas 'worker_pub', 'worker_retrain' e 'training_model' para a pasta 'publicar'
(nãoincluir a pasta
'env', que é do ambiente virtual Python, nem a pasta 'temp_area', que é utilizada para guardar arquivos
temporários) ;Compacte a pasta 'publicar' utilizando o formato '.zip';Envie o arquivo 'publicar.zip' para o Prodest, conforme alinhamento prévio realizado em reunião ou qualquer
outro meio de contato.