Install OML4Py Client Container

5 Install OML4Py Client Container

Use the steps provided below to configure and install the container following best practices with Bash scripts.

The Oracle Machine Learning for Python (OML4Py) client container provides a preconfigured runtime environment that includes Python, Oracle client libraries, and the supporting packages required for OML4Py 2.1.1. Using the container simplifies client installation, minimizes dependency conflicts, and helps ensure a consistent runtime environment across systems.

The container includes the OML4Py client, version 2.1.1, and is designed to work with OML4Py on both Oracle AI Database (on premises and in the cloud) and Oracle Autonomous AI Database.

The OML4Py 2.1.1 client container runs on Oracle Linux 8, 9, and 10 (x86_64) and includes Python 3.13.5 and the preconfigured supporting Python packages listed below:

pandas==2.2.3
setuptools==80.10.2
scipy==1.14.1
matplotlib==3.10.4
oracledb==3.3.0
scikit-learn==1.6.1
numpy==2.1.0
onnxruntime==1.20.0
onnxruntime-extensions==0.12.0
onnx==1.21.0
torch==2.10.0
transformers==4.56.1
sentencepiece==0.2.1

Rootless Podman Prerequisites

Rootless Podman requires the /etc/subuid and /etc/subgid files to map user IDs inside the container to unprivileged user IDs on the host. These files must define a user and group ID range for each user, typically at least 65,536 IDs.

Configure subordinate user and group ID ranges:

sudo usermod \
--add-subuids 100000-165535 \
--add-subgids 100000-165535 \
$USER

Apply the updated configuration:
```
podman system migrate
```
Verify the ID mappings:
```
grep $USER /etc/subuid
```

Installation Steps

Steps to install and run the OML4Py Client Container (version 2.1.1) using Podman.

Verify Podman Prerequisites
Confirm that Podman is installed and functioning correctly:
```
podman version
```
If the command fails or returns an error such as podman: command not found, install Podman using the appropriate command for your Oracle Linux version.
- Oracle Linux 8
```
sudo dnf module install container-tools:ol8
```
- Oracle Linux 9 or Oracle Linux 10
```
 sudo dnf install -y container-tools
```
After installation, rerun:
```
podman version
```
Sign In to Oracle Container Registry (OCR)
See Getting Started with the OML4Py 2.1.1 Client Container for complete Oracle Container Registry setup instructions.
1. Navigate to Oracle Container Registry and select Sign In.
2. Sign in using your Oracle SSO credentials.
  If this is your first time using OCR, complete the one-time registration process to enable OCR access for your Oracle SSO account.
3. Review and accept the license agreement. This step is required once per user/account.
Generate an OCR Authentication Token
To pull the OML4Py container image with Podman, sign in to OCR using podman login command with your Oracle SSO username and an OCR authentication token. Generate the token by following the instructions in Generating an Oracle Container Registry Authentication Token in the Podman User’s Guide.

Note:
Save the authentication token in a secure location immediately after it is generated. The token is displayed only once. If you lose it, you must delete the existing token and generate a new one.
Log In to OCR from Podman and Pull the Image
1. Log in to OCR:
```
podman login container-registry.oracle.com
```
  When prompted, enter the following credentials:
  - Username: your Oracle SSO username
  - Password: the generated OCR authentication token from the previous step
2. Pull the image:
```
podman pull container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
```
Verify the Image Was Pulled Successfully
To confirm the image is available locally, list the Podman images on your system and verify that container-registry.oracle.com/database/oml4py-client:2.1.1.0.0 appears in the output:
```
podman images
```
(Optional) Use the Image in an Air-Gapped Environment
If the target host does not have internet access, save the OML4Py container image to a tar file on a connected host. Transfer the file to the air-gapped host, and then load the image locally.
1. Save the image to a tar file on a connected host:
```
podman save -o oml4py-client_2.1.1.0.0.tar container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
```
2. After transferring the tar file to the air-gapped host, load the image:
```
podman load -i oml4py-client_2.1.1.0.0.tar
```
3. Verify the image is available on the air-gapped host:
```
podman images
```
  Confirm that container-registry.oracle.com/database/oml4py-client:2.1.1.0.0 appears in the output.
Launch the OML4Py Client Container
Use the following instructions to start a container from the image.

Note:
If you plan to use AutoML, ensure that pooled connection entries are added to tnsnames.ora. See Configure Pooled Connections for AutoML for more information.

Note:
Use /u01/oml_home for any files you need to write inside the container, such as exported models or output files. This directory is the designated writable directory within the container environment.

You can start the container either with or without an Oracle wallet, depending on your database connection configuration. Choose from:
- Option A: Run without an Oracle wallet
  If you are not using an Oracle wallet to connect to the database, run:
```
podman run -it --name <container_name> \
container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
```
- Option B: Run With an Oracle Wallet
  If you are using an Oracle wallet, mount the wallet directory into the container and set TNS_ADMIN accordingly.
  
  Prepare the Wallet:
  1. Upload the wallet to the host and extract it to a directory. For example:
```
unzip <wallet_name>.zip -d /home/opc/wallet
```
  2. Navigate to the wallet directory. Verify that sqlnet.ora contains the wallet directory configuration.
```
cd /home/opc/wallet
cat sqlnet.ora
```
  3. Update sqlnet.ora so that the wallet location points to /u01/oml_home/wallet inside the container:
```
sed -i.bak 's|?/network/admin|/u01/oml_home/wallet|g' <wallet_file_path>/sqlnet.ora
```
  4. Verify that sqlnet.ora contains a wallet location similar to the following:
```
WALLET_LOCATION =
  (SOURCE =
    (METHOD = file)
    (METHOD_DATA =
      (DIRECTORY="/u01/oml_home/wallet")))
```
  Start the Container with the Wallet Mounted
```
podman run -it --name <container_name> \
-v <wallet_file_path>:/u01/oml_home/wallet:U,Z \
-e TNS_ADMIN=/u01/oml_home/wallet \
container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
```
- (Optional) Mount a Host Directory for Container Output
  If you want to write files from the container to the host, mount a host directory into the container:
```
podman run -it --name <container_name> \
-v <host_output_folder>:/u01/oml_home/:U,Z \
container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
```
Convert and Export an ONNX Model from the Container
After starting the OML4Py client container, you can run the ONNX model conversion workflow from a Python session.
1. Inside the container, start Python:
```
python3
```
2. Then convert your model. In Python, list the available preconfigured models, create a pipeline for a selected model, and export the model to a file or to the database:
```
import oml
from oml.utils import ONNXPipeline, ONNXPipelineConfig

# Display available preconfigured models
ONNXPipelineConfig.show_preconfigured()

# Create a pipeline for a selected model
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")

# Connect to the database 
oml.connect(user="<user>", password="<password>", dsn="<service_name>")   # username/password
oml.connect(user="", password="", dsn="<tns_alias>")                      # wallet-based

# Export the model
pipeline.export2db("YOUR_MODEL_NAME")     # directly to the database
pipeline.export2file("YOUR_MODEL_NAME")   # to a file in the container
```
  Replace YOUR_MODEL_NAME with the name to use for the exported ONNX model.
  Converted ONNX models can be deployed to Oracle AI Database 26ai or to the Oracle Private AI Services Container. Deploying models to Oracle AI Database enables in-database embedding generation and semantic search workflows using Oracle AI Vector Search.
  
  Deploying models to the Oracle Private AI Services Container enables embedding generation outside the database through an OpenAI-compatible REST API.

(Optional) Load an Exported ONNX Model into the Database

If you exported the model to a file and want to load it into the database manually, move the .onnx file to a location accessible by the database server.

Then, connect as a DBA user and run the following statements:

CREATE DIRECTORY ONNX_IMPORT AS '/path/to/models';

GRANT READ ON DIRECTORY ONNX_IMPORT TO YOUR_USER;

GRANT CREATE MINING MODEL TO YOUR_USER;

BEGIN
  DBMS_VECTOR.LOAD_ONNX_MODEL(
    directory  => 'ONNX_IMPORT',
    file_name  => 'YOUR_MODEL_NAME.onnx',
    model_name => 'YOUR_MODEL_NAME'
  );
END;
/

(Optional) Copy the Converted Model File from the Container
Exit the container first by typing exit or pressing Ctrl+D to return to the host shell. Then use the podman cp command to copy the converted model file from the container to the host:
```
podman cp <container_name>:<path_to_file> <host_output_folder>
```
Reconnect to an Existing Container
To restart and reconnect to an existing container, run:
```
podman start <container_name>
podman exec -it <container_name> /bin/bash
```

Configure Pooled Connections for AutoML
AutoML operations require a pooled database connection. To enable pooled connections, add pooled service entries to the tnsnames.ora file included in the Oracle wallet used by the container.