Utilizar a biblioteca de clientes de Python do Azure Machine Learning para aceder a conjuntos de dados com PythonAccess datasets with Python using the Azure Machine Learning Python client library

A pré-visualização da biblioteca de clientes Microsoft Azure Machine Learning Python pode permitir o acesso seguro aos seus conjuntos de dados de Aprendizagem de Máquinas Azure a partir de um ambiente python local e permite a criação e gestão de conjuntos de dados num espaço de trabalho.The preview of Microsoft Azure Machine Learning Python client library can enable secure access to your Azure Machine Learning datasets from a local Python environment and enables the creation and management of datasets in a workspace.

Este tópico fornece instruções sobre como:This topic provides instructions on how to:

  • instalar a biblioteca de clientes Machine Learning Pythoninstall the Machine Learning Python client library
  • aceder e carregar conjuntos de dados, incluindo instruções sobre como obter autorização para aceder a conjuntos de dados de Aprendizagem de Máquinas Azure a partir do seu ambiente python localaccess and upload datasets, including instructions on how to get authorization to access Azure Machine Learning datasets from your local Python environment
  • aceder a conjuntos de dados intermédios a partir de experiênciasaccess intermediate datasets from experiments
  • utilizar a biblioteca de clientes Python para enumerar conjuntos de dados, aceder a metadados, ler o conteúdo de um conjunto de dados, criar novos conjuntos de dados e atualizar conjuntos de dados existentesuse the Python client library to enumerate datasets, access metadata, read the contents of a dataset, create new datasets, and update existing datasets

Pré-requisitosPrerequisites

A biblioteca de clientes Python foi testada nos seguintes ambientes:The Python client library has been tested under the following environments:

  • Windows, Mac e LinuxWindows, Mac, and Linux
  • Python 2.7, 3.3 e 3.4Python 2.7, 3.3 and 3.4

Tem uma dependência dos seguintes pacotes:It has a dependency on the following packages:

  • pedidosrequests
  • python-dateutilpython-dateutil
  • pandaspandas

Recomendamos a utilização de uma distribuição Python como Anaconda ou Canopy,que vêm com Python, IPython e os três pacotes acima listados instalados.We recommend using a Python distribution such as Anaconda or Canopy, which come with Python, IPython and the three packages listed above installed. Embora a IPython não seja estritamente necessária, é um ótimo ambiente para manipular e visualizar dados de forma interativa.Although IPython is not strictly required, it is a great environment for manipulating and visualizing data interactively.

Como instalar a biblioteca de clientes Azure Machine Learning PythonHow to install the Azure Machine Learning Python client library

Instale a biblioteca de clientes Azure Machine Learning Python para completar as tarefas descritas neste tópico.Install the Azure Machine Learning Python client library to complete the tasks outlined in this topic. Esta biblioteca está disponível no Python Package Index.This library is available from the Python Package Index. Para instalá-lo no seu ambiente Python, executar o seguinte comando a partir do seu ambiente python local:To install it in your Python environment, run the following command from your local Python environment:

pip install azureml

Em alternativa, pode descarregar e instalar a partir das fontes no GitHub.Alternatively, you can download and install from the sources on GitHub.

python setup.py install

Se tiver uma pega instalada na sua máquina, pode utilizar pip para instalar diretamente a partir do repositório git:If you have git installed on your machine, you can use pip to install directly from the git repository:

pip install git+https://github.com/Azure/Azure-MachineLearning-ClientLibrary-Python.git

Use snippets de código para aceder a conjuntos de dadosUse code snippets to access datasets

A biblioteca de clientes Python dá-lhe acesso programático aos seus conjuntos de dados existentes a partir de experiências que foram executadas.The Python client library gives you programmatic access to your existing datasets from experiments that have been run.

A partir da interface web do Azure Machine Learning Studio (clássico), pode gerar snippets de código que incluem todas as informações necessárias para descarregar e desseializar conjuntos de dados como objetos dataFrame pandas na sua máquina local.From the Azure Machine Learning Studio (classic) web interface, you can generate code snippets that include all the necessary information to download and deserialize datasets as pandas DataFrame objects on your local machine.

Segurança para acesso a dadosSecurity for data access

Os snippets de código fornecidos pelo Azure Machine Learning Studio (clássico) para uso com a biblioteca do cliente Python incluem o seu ID do espaço de trabalho e o token de autorização.The code snippets provided by Azure Machine Learning Studio (classic) for use with the Python client library includes your workspace ID and authorization token. Estes fornecem acesso total ao seu espaço de trabalho e devem ser protegidos, como uma senha.These provide full access to your workspace and must be protected, like a password.

Por razões de segurança, a funcionalidade de corte de código apenas está disponível para utilizadores que tenham a sua função definida como Proprietário para o espaço de trabalho.For security reasons, the code snippet functionality is only available to users that have their role set as Owner for the workspace. O seu papel é apresentado no Azure Machine Learning Studio (clássico) na página USERS em Definições.Your role is displayed in Azure Machine Learning Studio (classic) on the USERS page under Settings.

O Screenshot mostra as definições na página utilizadores do Azure Machine Learning Studio.

Se a sua função não estiver definida como Proprietário, pode solicitar para ser reenvidada como proprietária ou pedir ao proprietário do espaço de trabalho para lhe fornecer o corte de código.If your role is not set as Owner , you can either request to be reinvited as an owner, or ask the owner of the workspace to provide you with the code snippet.

Para obter o token de autorização, pode escolher uma destas opções:To obtain the authorization token, you may choose one of these options:

  • Peça um sinal de um dono.Ask for a token from an owner. Os proprietários podem aceder aos seus tokens de autorização a partir da página Definições do seu espaço de trabalho no Azure Machine Learning Studio (clássico).Owners can access their authorization tokens from the Settings page of their workspace in Azure Machine Learning Studio (classic). Selecione Definições a partir do painel esquerdo e clique em TOKENS DE AUTORIZAÇÃO para ver as fichas primárias e secundárias.Select Settings from the left pane and click AUTHORIZATION TOKENS to see the primary and secondary tokens. Embora os tokens de autorização primária ou secundária possam ser usados no corte de código, recomenda-se que os proprietários apenas partilhem os tokens de autorização secundária.Although either the primary or the secondary authorization tokens can be used in the code snippet, it is recommended that owners only share the secondary authorization tokens.

    Fichas de autorização

  • Peça para ser promovido ao papel de proprietário: um atual proprietário do espaço de trabalho precisa primeiro removê-lo do espaço de trabalho e depois convidá-lo para ele como proprietário.Ask to be promoted to role of owner: a current owner of the workspace needs to first remove you from the workspace then reinvite you to it as an owner.

Uma vez que os desenvolvedores tenham obtido o ID do espaço de trabalho e o token de autorização, eles são capazes de aceder ao espaço de trabalho usando o corte de código independentemente do seu papel.Once developers have obtained the workspace ID and authorization token, they are able to access the workspace using the code snippet regardless of their role.

As fichas de autorização são geridas na página TOKENS DE AUTORIZAÇÃO em DEFINIÇÕES.Authorization tokens are managed on the AUTHORIZATION TOKENS page under SETTINGS. Pode regenerar, mas este procedimento revoga o acesso ao símbolo anterior.You can regenerate them, but this procedure revokes access to the previous token.

Aceder a conjuntos de dados a partir de uma aplicação python localAccess datasets from a local Python application

  1. No Machine Learning Studio (clássico), clique em DATASETS na barra de navegação à esquerda.In Machine Learning Studio (classic), click DATASETS in the navigation bar on the left.

  2. Selecione o conjunto de dados a que pretende aceder.Select the dataset you would like to access. Pode selecionar qualquer um dos conjuntos de dados da lista MY DATASETS ou da lista SAMPLES.You can select any of the datasets from the MY DATASETS list or from the SAMPLES list.

  3. A partir da barra de ferramentas inferior, clique em Gerar Código de Acesso a Dados.From the bottom toolbar, click Generate Data Access Code. Se os dados estiverem num formato incompatível com a biblioteca do cliente Python, este botão é desativado.If the data is in a format incompatible with the Python client library, this button is disabled.

    A screenshot mostra conjuntos de dados com o CÓDIGO DE ACESSO A DADOS GERAR.

  4. Selecione o corte de código da janela que aparece e copie-o para a sua área de transferência.Select the code snippet from the window that appears and copy it to your clipboard.

    Gerar botão de código de acesso a dados

  5. Cole o código no caderno da sua aplicação python local.Paste the code into the notebook of your local Python application.

    Colar código no caderno

Aceder a conjuntos de dados intermédios a partir de experiências de Machine LearningAccess intermediate datasets from Machine Learning experiments

Depois de uma experiência ser executada no Machine Learning Studio (clássico), é possível aceder aos conjuntos de dados intermédios a partir dos nós de saída dos módulos.After an experiment is run in Machine Learning Studio (classic), it is possible to access the intermediate datasets from the output nodes of modules. Conjuntos de dados intermédios são dados que foram criados e utilizados para passos intermédios quando uma ferramenta modelo foi executada.Intermediate datasets are data that has been created and used for intermediate steps when a model tool has been run.

Os conjuntos de dados intermédios podem ser acedidos desde que o formato de dados seja compatível com a biblioteca do cliente Python.Intermediate datasets can be accessed as long as the data format is compatible with the Python client library.

Os seguintes formatos são suportados (as constantes para estes formatos estão na azureml.DataTypeIds classe):The following formats are supported (constants for these formats are in the azureml.DataTypeIds class):

  • PlainTextPlainText
  • GenéricoCSVGenericCSV
  • GenericTSVGenericTSV
  • GenéricoCSVNoHeaderGenericCSVNoHeader
  • GenéricoSVNoHeaderGenericTSVNoHeader

Pode determinar o formato pairando sobre um nó de saída do módulo.You can determine the format by hovering over a module output node. É exibido juntamente com o nome do nó, numa ponta de ferramenta.It is displayed along with the node name, in a tooltip.

Alguns dos módulos, como o módulo Split, são de saída para um formato denominado Dataset , que não é suportado pela biblioteca do cliente Python.Some of the modules, such as the Split module, output to a format named Dataset, which is not supported by the Python client library.

Formato do conjunto de dados

É necessário utilizar um módulo de conversão, como o Convert para CSV,para obter uma saída num formato suportado.You need to use a conversion module, such as Convert to CSV, to get an output into a supported format.

Formato GenéricoCSV

Os passos a seguir mostram um exemplo que cria uma experiência, executa-a e acede ao conjunto de dados intermédio.The following steps show an example that creates an experiment, runs it and accesses the intermediate dataset.

  1. Criar uma nova experiência.Create a new experiment.

  2. Insira um módulo de conjunto de dados de classificação binária de rendimento de rendimento adulto.Insert an Adult Census Income Binary Classification dataset module.

  3. Insira um módulo Split e ligue a sua entrada à saída do módulo do conjunto de dados.Insert a Split module, and connect its input to the dataset module output.

  4. Insira um converse para o módulo CSV e ligue a sua entrada a uma das saídas do módulo Split.Insert a Convert to CSV module and connect its input to one of the Split module outputs.

  5. Salve a experiência, corra e espere que o trabalho termine.Save the experiment, run it, and wait for the job to finish.

  6. Clique no nó de saída do módulo Converte para CSV.Click the output node on the Convert to CSV module.

  7. Quando o menu de contexto aparecer, selecione 'Gerar Código de Acesso a Dados'.When the context menu appears, select Generate Data Access Code.

    Menu de Contexto

  8. Selecione o corte de código e copie-o para a sua área de transferência a partir da janela que aparece.Select the code snippet and copy it to your clipboard from the window that appears.

    Gerar código de acesso a partir do menu de contexto

  9. Cole o código no seu caderno.Paste the code in your notebook.

    Colar código em caderno

  10. Pode visualizar os dados usando o matplotlib.You can visualize the data using matplotlib. Isto mostra num histograma para a coluna etária:This displays in a histogram for the age column:

    Histograma

Utilize a biblioteca de clientes Machine Learning Python para aceder, ler, criar e gerir conjuntos de dadosUse the Machine Learning Python client library to access, read, create, and manage datasets

Área de trabalhoWorkspace

O espaço de trabalho é o ponto de entrada para a biblioteca do cliente Python.The workspace is the entry point for the Python client library. Forneça à classe o Workspace seu ID do espaço de trabalho e sinal de autorização para criar uma instância:Provide the Workspace class with your workspace ID and authorization token to create an instance:

ws = Workspace(workspace_id='4c29e1adeba2e5a7cbeb0e4f4adfb4df',
               authorization_token='f4f3ade2c6aefdb1afb043cd8bcf3daf')

Enumerar conjuntos de dadosEnumerate datasets

Para enumerar todos os conjuntos de dados num dado espaço de trabalho:To enumerate all datasets in a given workspace:

for ds in ws.datasets:
    print(ds.name)

Para enumerar apenas os conjuntos de dados criados pelo utilizador:To enumerate just the user-created datasets:

for ds in ws.user_datasets:
    print(ds.name)

Para enumerar apenas os conjuntos de dados de exemplo:To enumerate just the example datasets:

for ds in ws.example_datasets:
    print(ds.name)

Pode aceder a um conjunto de dados pelo nome (que é sensível a casos):You can access a dataset by name (which is case-sensitive):

ds = ws.datasets['my dataset name']

Ou pode acessá-lo por índice:Or you can access it by index:

ds = ws.datasets[0]

MetadadosMetadata

Os conjuntos de dados têm metadados, além do conteúdo.Datasets have metadata, in addition to content. (Os conjuntos de dados intermédios são uma exceção a esta regra e não têm metadados.)(Intermediate datasets are an exception to this rule and do not have any metadata.)

Alguns valores de metadados são atribuídos pelo utilizador no momento da criação:Some metadata values are assigned by the user at creation time:

  • print(ds.name)
  • print(ds.description)
  • print(ds.family_id)
  • print(ds.data_type_id)

Outros são valores atribuídos pela Azure ML:Others are values assigned by Azure ML:

  • print(ds.id)
  • print(ds.created_date)
  • print(ds.size)

Consulte a SourceDataset aula para mais informações sobre os metadados disponíveis.See the SourceDataset class for more on the available metadata.

Ler conteúdosRead contents

Os snippets de código fornecidos pelo Machine Learning Studio (clássico) descarregam e deserializam automaticamente o conjunto de dados para um objeto DataFrame de pandas.The code snippets provided by Machine Learning Studio (classic) automatically download and deserialize the dataset to a pandas DataFrame object. Isto é feito com o to_dataframe método:This is done with the to_dataframe method:

frame = ds.to_dataframe()

Se preferir baixar os dados brutos e realizar a desseialização por si mesmo, essa é uma opção.If you prefer to download the raw data, and perform the deserialization yourself, that is an option. Neste momento, esta é a única opção para formatos como 'ARFF', que a biblioteca de clientes Python não consegue desseerizar.At the moment, this is the only option for formats such as 'ARFF', which the Python client library cannot deserialize.

Para ler o conteúdo como texto:To read the contents as text:

text_data = ds.read_as_text()

Para ler o conteúdo como binário:To read the contents as binary:

binary_data = ds.read_as_binary()

Também pode abrir um stream para o conteúdo:You can also just open a stream to the contents:

with ds.open() as file:
    binary_data_chunk = file.read(1000)

Criar um novo conjunto de dadosCreate a new dataset

A biblioteca de clientes Python permite-lhe fazer o upload de conjuntos de dados do seu programa Python.The Python client library allows you to upload datasets from your Python program. Estes conjuntos de dados estão então disponíveis para utilização no seu espaço de trabalho.These datasets are then available for use in your workspace.

Se tiver os seus dados num DataFrame pandas, utilize o seguinte código:If you have your data in a pandas DataFrame, use the following code:

from azureml import DataTypeIds

dataset = ws.datasets.add_from_dataframe(
    dataframe=frame,
    data_type_id=DataTypeIds.GenericCSV,
    name='my new dataset',
    description='my description'
)

Se os seus dados já estiverem serializados, pode utilizar:If your data is already serialized, you can use:

from azureml import DataTypeIds

dataset = ws.datasets.add_from_raw_data(
    raw_data=raw_data,
    data_type_id=DataTypeIds.GenericCSV,
    name='my new dataset',
    description='my description'
)

A biblioteca de clientes Python é capaz de serializar um DataFrame de pandas para os seguintes formatos (as constantes para estes estão na azureml.DataTypeIds classe):The Python client library is able to serialize a pandas DataFrame to the following formats (constants for these are in the azureml.DataTypeIds class):

  • PlainTextPlainText
  • GenéricoCSVGenericCSV
  • GenericTSVGenericTSV
  • GenéricoCSVNoHeaderGenericCSVNoHeader
  • GenéricoSVNoHeaderGenericTSVNoHeader

Atualizar um conjunto de dados existenteUpdate an existing dataset

Se tentar fazer o upload de um novo conjunto de dados com um nome que corresponda a um conjunto de dados existente, deverá obter um erro de conflito.If you try to upload a new dataset with a name that matches an existing dataset, you should get a conflict error.

Para atualizar um conjunto de dados existente, primeiro precisa de obter uma referência ao conjunto de dados existente:To update an existing dataset, you first need to get a reference to the existing dataset:

dataset = ws.datasets['existing dataset']

print(dataset.data_type_id) # 'GenericCSV'
print(dataset.name)         # 'existing dataset'
print(dataset.description)  # 'data up to jan 2015'

Em seguida, utilize update_from_dataframe para serializar e substituir o conteúdo do conjunto de dados no Azure:Then use update_from_dataframe to serialize and replace the contents of the dataset on Azure:

dataset = ws.datasets['existing dataset']

dataset.update_from_dataframe(frame2)

print(dataset.data_type_id) # 'GenericCSV'
print(dataset.name)         # 'existing dataset'
print(dataset.description)  # 'data up to jan 2015'

Se pretender serializar os dados para um formato diferente, especifique um valor para o data_type_id parâmetro opcional.If you want to serialize the data to a different format, specify a value for the optional data_type_id parameter.

from azureml import DataTypeIds

dataset = ws.datasets['existing dataset']

dataset.update_from_dataframe(
    dataframe=frame2,
    data_type_id=DataTypeIds.GenericTSV,
)

print(dataset.data_type_id) # 'GenericTSV'
print(dataset.name)         # 'existing dataset'
print(dataset.description)  # 'data up to jan 2015'

Pode configurar opcionalmente uma nova descrição especificando um valor para o description parâmetro.You can optionally set a new description by specifying a value for the description parameter.

dataset = ws.datasets['existing dataset']

dataset.update_from_dataframe(
    dataframe=frame2,
    description='data up to feb 2015',
)

print(dataset.data_type_id) # 'GenericCSV'
print(dataset.name)         # 'existing dataset'
print(dataset.description)  # 'data up to feb 2015'

Pode configurar opcionalmente um novo nome especificando um valor para o name parâmetro.You can optionally set a new name by specifying a value for the name parameter. A partir de agora, irá recuperar o conjunto de dados usando apenas o novo nome.From now on, you'll retrieve the dataset using the new name only. O código seguinte atualiza os dados, nome e descrição.The following code updates the data, name, and description.

dataset = ws.datasets['existing dataset']

dataset.update_from_dataframe(
    dataframe=frame2,
    name='existing dataset v2',
    description='data up to feb 2015',
)

print(dataset.data_type_id)                    # 'GenericCSV'
print(dataset.name)                            # 'existing dataset v2'
print(dataset.description)                     # 'data up to feb 2015'

print(ws.datasets['existing dataset v2'].name) # 'existing dataset v2'
print(ws.datasets['existing dataset'].name)    # IndexError

Os data_type_id name parâmetros e description parâmetros são opcionais e padrão ao seu valor anterior.The data_type_id, name and description parameters are optional and default to their previous value. O dataframe parâmetro é sempre necessário.The dataframe parameter is always required.

Se os seus dados já estiverem serializados, utilize update_from_raw_data em vez de update_from_dataframe .If your data is already serialized, use update_from_raw_data instead of update_from_dataframe. Se raw_data passares em vez dataframe de, funciona da mesma forma.If you just pass in raw_data instead of dataframe, it works in a similar way.