Prerequisites

To download and install the on-premises OML4Py client, the following are required:

• A connection to the internet.
• Write permission on the directory in which you are installing the client.
• Perl 5.8 or higher installed on your system.
• Python 3.12.6. To know more about downloading and installing Python 3.12.6, see Build and Install Python for Linux for On-Premises Databases
• The OML4Py supporting packages. To know more about OML4Py the supporting packages, see Install the Required Supporting Packages for Linux for On-Premises Databases.

To use the OML4Py client to connect to an on-premises Oracle database, the following are required:

• Oracle Instant Client must be installed on the client machine.
• The OML4Py server must be installed on the on-premises database server.

Download and Extract the OML4Py Client Installation File

To download and extract the OML4Py client installation file, do the following:

1. Download the client installation zip file.
   1. Go to the Oracle Machine Learning for Python Downloads page on the Oracle Technology Network.
   2. Accept the license agreement and select Oracle Machine Learning for Python Downloads (v2.1).
   3. Select Oracle Machine Learning for Python Client Install for Oracle Database on Linux 64 bit.
   4. Save the zip file to an accessible directory.
2. Go to the directory to which you downloaded the zip file and unzip the file.

   unzip oml4py-client-linux-x86_64-2.1.zip

   The contents are extracted to a subdirectory named client, which contains these four files:

   • OML4PInstallShared.pm
   • oml-2.1-cp312-cp312-linux_x86_64.whl
   • client.pl
   • oml4py.ver

View the Optional Arguments to the Client Installation Perl Script

In the directory above the unzipped client folder, run the client installation Perl script with the --help option to display the arguments to the client installation Perl script.

The following command displays the available installation options:

perl -Iclient client/client.pl --help

Oracle Machine Learning for Python 2.1 Client.

Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
Usage: client.pl [OPTION]...
Install, upgrade, or uninstall OML4P Client.

  -i, --install install or upgrade (default)
  -u, --uninstall uninstall
  -y never prompt
  --ask interactive mode (default)
  --no-embed do not install embedded python functionality
  --no-deps turn off dependencies checking
  --target <dir> install client into <dir>

By default, the installation script installs the Embedded Python Execution modules. If you don't want to install this module, then you can use the --no-embed flag.

Also by default, the installation script checks for the existence and version of each of the supporting packages that the OML4Py client requires. If a required package is missing or does not meet the version requirement, the installation script displays an error message and exits. You can skip the dependency checking in the client installation by using the --no-deps flag. However, to use the oml module, you need to have installed acceptable versions of all of the supporting packages.

For a list of the required dependencies, see Install the Required Supporting Packages for Linux for On-Premises Databases.

Run the OML4Py Client Installation Script

To install the OML4Py client, do the following:

1. In the directory above the unzipped client folder, run the script. The following command runs the Perl script in the current directory:

   perl -Iclient client/client.pl

   Alternatively, the following command runs the Perl script with the target directory specified:

   perl -Iclient client/client.pl --target path_to_target_dir

   The --target flag is optional, if you don't want to install it to the current directory.

   When the script displays Proceed?, enter y or yes.

   If you use the --target <dir> argument to install the oml module to the specified directory, then add that location to environment variable PYTHONPATH so that Python can find the module:

   export PYTHONPATH=path_to_target_dir

   The command displays the following:

   perl -Iclient client/client.pl

   Oracle Machine Learning for Python 2.1 Client.
   
   Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
   Checking platform .................. Pass
   Checking Python .................... Pass
   Checking dependencies .............. Pass
   Checking OML4P version ............. Pass
   Current configuration
     Python Version ................... 3.12.6
     PYTHONHOME ....................... /opt/Python-3.12.6
     Existing OML4P module version .... None
     Operation ........................ Install/Upgrade
   
   Proceed? [yes]
   
   Processing ./client/oml-2.1-cp312-cp312-linux_x86_64.whl
   Installing collected packages: oml
   Successfully installed oml-2.1

2. To verify that oml modules are successfully installed and are ready to use, start Python and import oml. At the Linux prompt, enter python3.

   python3

   At the Python prompt, enter import oml and check the client version.

   import oml
   oml.__version__

   The output is similar to the following:

   $ python3
   Python 3.12.6 (main, Aug 14 2024, 15:13:51) [GCC 8.5.0 20210514 (Red Hat
   8.5.0-18.0.6)] on linux
   Type "help", "copyright", "credits" or "license" for more information.

   import oml
   oml.__version__

   '2.1'

3. Display the location of the installation directory.

   If you didn't use the --target <dir> argument, then the installed oml modules are stored under $PYTHONHOME/lib/python3.12/site-packages/. Again, you must have write permission for the target directory.

   In Python, after importing the oml module, you can display the directory in which the client is installed. At the Python prompt, enter:

   oml.__path__

Connect to the OML4Py Server

Start Python, import oml, and create a connection to your OML4Py server using an appropriate password, hostname, and system identifier. The following example uses oml_user as the user and has example argument values. Replace the username and other argument values with the values for your user and database.

import oml
oml.connect(user='oml_user', password='oml_user_password', host=myhost, 
            port=1521, service_name=myservicename)

After connecting, you can run any of the examples in this publication. For example, you could run Example 7-8.