Instalar pacotes de Python com sqlmlutils

Aplica-se a: SQL Server 2019 (15.x) Instância Gerenciada de SQL do Azure

Este artigo descreve como usar funções no pacote sqlmlutils para instalar novos pacotes do Python em uma instância dos Serviços de Machine Learning do SQL Server e em Clusters de Big Data. Os pacotes que você instalar poderão ser usados em scripts de Python em execução no banco de dados usando a instrução T-SQL sp_execute_external_script.

Para obter mais informações sobre a localização e os caminhos de instalação do pacote, confira Obter informações do pacote de Python.

Observação

O pacote sqlmlutils descrito neste artigo é usado para adicionar pacotes do Python ao SQL Server 2019 ou posterior. Para o SQL Server 2017 e anterior, consulte Instalar pacotes com ferramentas do Python.

Pré-requisitos

• Você precisa ter os Serviços de Machine Learning do SQL Server instalados com a opção de linguagem do Python.

• Instale o Azure Data Studio no computador cliente que você usa para se conectar ao SQL Server. Você pode usar outras ferramentas de consulta ou gerenciamento de banco de dados, mas este artigo pressupõe o uso do Azure Data Studio.

• Instale o kernel do Python no Azure Data Studio. Instale e use também o Python na linha de comando. Você pode usar um ambiente de desenvolvimento alternativo do Python, como o Visual Studio Code com a Extensão do Python.

  A versão do Python no computador cliente precisa corresponder à versão do Python no servidor, e os pacotes que você instalar precisarão corresponder à versão existente do Python. Para obter mais informações sobre qual versão do Python está incluída em cada versão do SQL Server, confira Versões do Python e do R.

  Para verificar a versão do Python em uma instância específica do SQL Server, use o comando T-SQL a seguir.

  EXECUTE sp_execute_external_script
    @language = N'Python',
    @script = N'
  import sys
  print(sys.version)
  '
  

Outras considerações

• A biblioteca de pacotes de Python está localizada na pasta Arquivos de Programas de sua instância do SQL Server e, por padrão, a instalação nessa pasta requer permissões de administrador. Para obter mais informações, confira Localização da biblioteca de pacotes.

• A instalação do pacote é específica da instância SQL, do banco de dados e dos usuários indicados por você nas informações de conexão fornecidas para sqlmlutils. Se quiser usar o pacote em várias instâncias ou bancos de dados SQL ou para diferentes usuários, você precisará instalá-lo para cada um. Com uma exceção: se o pacote for instalado por um membro de dbo, ele será público e compartilhado com todos os usuários. Se um usuário instalar uma versão mais recente de um pacote público, este não será afetado, mas o usuário terá acesso à versão mais recente.

• Antes de adicionar um pacote, considere se ele é uma boa opção para o ambiente do SQL Server.

  • Recomendamos que você use o Python no banco de dados para tarefas que se beneficiam da forte integração com o mecanismo de banco de dados, como o aprendizado de máquina, em vez de tarefas que simplesmente consultam o banco de dados.

  • Se você adicionar pacotes que colocam muita pressão computacional sobre o servidor, o desempenho será prejudicado.

  • Em um ambiente do SQL Server protegido, talvez você queira evitar o seguinte:

    • Pacotes que exigem acesso à rede
    • Pacotes que exigem acesso elevado ao sistema de arquivos
    • Pacotes usados para desenvolvimento Web ou outras tarefas que não se beneficiam da execução dentro do SQL Server

  • O pacote tensorflow do Python não pode ser instalado por meio do sqlmlutils. Para obter mais informações e uma solução alternativa, confira Problemas conhecidos nos Serviços de Machine Learning do SQL Server.

Instalar sqlmlutils no computador cliente

Para usar sqlmlutils, primeiro você precisa instalá-lo no computador cliente que usa para se conectar ao SQL Server.

No Azure Data Studio

Se você estiver usando sqlmlutils no Azure Data Studio, instale-o usando o recurso Gerenciar Pacotes em um notebook do kernel do Python.

1. Em um notebook do kernel do Python no Azure Data Studio, clique em Gerenciar Pacotes.
2. Clique em Adicionar nova.
3. Insira "sqlmlutils" no campo Pesquisar pacotes Pip e clique em Pesquisar.
4. Selecione a Versão do Pacote que deseja instalar (a última versão é recomendada).
5. Clique em Instalar e em Fechar.

Na linha de comando do Python

Se você estiver usando o sqlmlutils em um IDE ou um prompt de comando do Python, instale o sqlmlutils com um comando pip simples:

pip install sqlmlutils

Instale também o sqlmlutils por meio de um arquivo zip:

1. Verifique se o Pip está instalado. Confira Instalação do Pip para obter mais informações.
2. Baixe o arquivo zip mais recente do sqlmlutils do https://github.com/microsoft/sqlmlutils/tree/master/R/dist para o computador cliente. Não descompacte o arquivo.
3. Abra um Prompt de Comando e execute os comandos a seguir para instalar o pacote do sqlmlutils. Substitua o caminho completo para o arquivo zip do sqlmlutils que você baixou – este exemplo supõe que o arquivo baixado seja c:\temp\sqlmlutils-1.0.0.zip.

   pip install --upgrade --upgrade-strategy only-if-needed c:\temp\sqlmlutils-1.0.0.zip
   

Adicionar um pacote de Python ao SQL Server

Usando o sqlmlutils, você pode adicionar pacotes do Python a uma instância SQL. Depois, você poderá usar esses pacotes no código Python em execução na instância SQL. O sqlmlutils usa CREATE EXTERNAL LIBRARY para instalar o pacote e cada uma de suas dependências.

No exemplo a seguir, você adicionará o pacote text-tools ao SQL Server.

Adicionar o pacote online

Se o computador cliente que você usa para se conectar ao SQL Server tiver acesso à Internet, você poderá usar sqlmlutils para localizar o pacote text-tools e qualquer dependência pela Internet e, em seguida, instalar o pacote em uma instância do SQL Server remotamente.

1. No computador cliente, abra o Python ou um ambiente de Python.

2. Use os comandos a seguir para instalar o pacote text-tools. Substitua suas informações de conexão de banco de dados SQL Server (se você usar a autenticação do Windows, não precisará dos parâmetros uid e pwd).

import sqlmlutils
connection = sqlmlutils.ConnectionInfo(server="server", database="database", uid="username", pwd="password")
sqlmlutils.SQLPackageManager(connection).install("text-tools")

Adicionar o pacote offline

Se o computador cliente que você usa para se conectar ao SQL Server não tiver uma conexão com a Internet, você poderá usar o pip em um computador com acesso à Internet para baixar o pacote e qualquer pacote dependente em uma pasta local. Em seguida, copie a pasta para o computador cliente onde você pode instalar o pacote offline.

Em um computador com acesso à Internet

1. Abra um Prompt de Comando e execute o comando a seguir para criar uma pasta local que contenha o pacote text-tools. Este exemplo cria a pasta c:\temp\text-tools.

   pip download text-tools -d c:\temp\text-tools
   

2. Copie a pasta text-tools para o computador cliente. O exemplo a seguir pressupõe que você a copiou para c:\temp\packages\text-tools.

No computador cliente

Use sqlmlutils para instalar cada pacote (arquivo WHL) encontrado na pasta local que o pip criou. A ordem em que os pacotes são instalados não é importante.

Neste exemplo, text-tools não tem dependências, portanto, há apenas um arquivo da pasta text-tools para instalação. Por outro lado, um pacote como scikit-plot tem 11 dependências, de modo que você encontraria 12 arquivos na pasta (o pacote scikit-plot e os 11 pacotes dependentes) e instalaria cada um deles.

Execute o script Python a seguir. Substitua o caminho do arquivo real e o nome do pacote, bem como suas informações de conexão de banco de dados SQL Server (se você usar a autenticação do Windows, não precisará dos parâmetros uid e pwd). Repita a instrução sqlmlutils.SQLPackageManager para cada arquivo de pacote na pasta.

import sqlmlutils
connection = sqlmlutils.ConnectionInfo(server="yourserver", database="yourdatabase", uid="username", pwd="password"))
sqlmlutils.SQLPackageManager(connection).install("text_tools-1.0.0-py3-none-any.whl")

Usar o pacote

Agora, você pode usar o pacote em um script de Python no SQL Server. Por exemplo:

EXECUTE sp_execute_external_script
  @language = N'Python',
  @script = N'
from text_tools.finders import find_best_string
corpus = "Lorem Ipsum text"
query = "Ipsum"
first_match = find_best_string(query, corpus)
print(first_match)
  '

Remover o pacote do SQL Server

Se quiser remover o pacote text-tools, use o comando de Python a seguir no computador cliente, usando a mesma variável de conexão definida anteriormente.

sqlmlutils.SQLPackageManager(connection).uninstall("text-tools")

Mais funções do sqlmlutils

O pacote sqlmlutils contém várias funções para gerenciar pacotes do Python e para criar, gerenciar e executar procedimentos armazenados e consultas em um SQL Server. Para obter detalhes, confira o arquivo LEIAME sqlmlutils do Python.

Para obter informações sobre qualquer função do sqlmlutils, use a função help do Python. Por exemplo:

import sqlmlutils
help(SQLPackageManager.install)

Próximas etapas

• Para saber mais sobre os pacotes do Python instalados nos Serviços de Machine Learning do SQL Server, confira Obter informações sobre o pacote do Python.

• Para obter informações sobre como instalar pacotes de R nos Serviços de Machine Learning do SQL Server, confira Instalar novos pacotes de R no SQL Server.