11.1 Convert Pretrained Models to ONNX Model: End-to-End Instructions for Text Embedding

This section provides end-to-end instructions from installing the OML4Py client to downloading a pretrained embedding model in ONNX-format using the Python utility package offered by Oracle.

Note:

This example provides end to end instructions for converting pretrained text models to ONNX models. Steps 1 - 9 are identical for image models and multi-modals. You can use appropriate code/syntax mentioned in the corresponding topics to convert image models and multi models to ONNX pipeline models.
These instructions assume you have configured your Oracle Linux 8 repo in /etc/yum.repos.d, configured a Wallet if using an Autonomous AI Database, and set up a proxy if needed.
  1. Install Python:
    sudo yum install libffi-devel openssl openssl-devel tk-devel xz-devel \
zlib-devel bzip2-devel readline-devel libuuid-devel \
ncurses-devel libaio tcl-devel openblas libsqlite3-dev
    wget https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz
mkdir -p $HOME/python
tar -xvzf Python-3.13.5.tgz --strip-components=1 -C $HOME/python
cd $HOME/python
./configure --enable-shared --prefix=$HOME/python
make clean; make
make altinstall
  2. Set variables PYTHONHOME, PATH, and LD_LIBRARY_PATH:
    export PYTHONHOME=$HOME/python
export PATH=$PYTHONHOME/bin:$PATH
export LD_LIBRARY_PATH=$PYTHONHOME/lib:$LD_LIBRARY_PATH
  3. Create symlink for python3 and pip3: 
    cd $HOME/python/bin
ln -s python3.13 python3
ln -s pip3.13 pip3
  4. Install Oracle Instant Client if you plan to load embedded models from Python directly into a database. If you are exporting models to a file, you can skip this step—see the note about environment variables in Step 5 for further details.
    sudo yum install -y oracle-instantclient-release-el8 oracle-instantclient-basic
  5. Create an environment file, for example, env.sh, that defines the Python and Oracle Instant client environment variables and source these environment variables before each OML4Py client session. Alternatively, add the environment variable definitions to .bashrc so they are defined when the user logs into their Linux machine.
    # Environment variables for Python
export PYTHONHOME=$HOME/python
export PATH=$PYTHONHOME/bin:$PATH
export LD_LIBRARY_PATH=$PYTHONHOME/lib:$LD_LIBRARY_PATH

    Note:

    Environment variable for Oracle Instant Client - only if the Oracle Instant Client is installed for exporting models to the database.

    export LD_LIBRARY_PATH=$HOME/instantclient_23_26:$LD_LIBRARY_PATH

    .
  6. Create a file named requirements.txt that contains the required third-party packages listed below.
    --extra-index-url https://download.pytorch.org/whl/cpu
pandas==2.2.3
setuptools==80.8.0
scipy==1.14.1
matplotlib==3.10.0
oracledb==3.3.0
scikit-learn==1.6.1
numpy==2.1.0
pyarrow==19.0.0
onnxruntime==1.20.0
onnxruntime-extensions==0.14.0
onnx==1.18.0
torch==2.9.0
transformers==4.56.1
sentencepiece==0.2.1

    Note:

    Alternatively, you can install the required supporting packages by downloading and using the supporting packages bundle: oml4py-supporting-linux-x86_64-2.1.1.zip. See Install the Required Supporting Packages for Linux for On-Premises Databases for more information.
  7. Upgrade pip3 and install the packages listed in requirements.txt.
    pip3 install --upgrade pip  
pip3 install -r requirements.txt
  8. To install the OML4Py client, download the OML4Py 2.1.1 client from the OML4Py download page. Accept the Oracle License Agreement, then click on oml4py-client-linux-x86_64-2.1.1.zip to download the ZIP file. After downloading, upload the ZIP file to your Linux machine.
    unzip oml4py-client-linux-x86_64-2.1.1.zip 
pip3 install client/oml-2.1.1-cp313-cp313-linux_x86_64.whl

    Note:

    Install the OML4Py Slim Client Modules if you only need access to the ONNX model conversion feature. This lightweight client is ideal for scenarios where you require ONNX model conversion without the complete set of OML4Py functionalities. See Install OML4Py Slim Client for more information.

  9. To get a list of all preconfigured models, start Python and import ONNXPipelineConfig from oml.utils.
    python3
from oml.utils import ONNXPipelineConfig
ONNXPipelineConfig.show_preconfigured()
    ['sentence-transformers/all-mpnet-base-v2',
'sentence-transformers/all-MiniLM-L6-v2',
'sentence-transformers/multi-qa-MiniLM-L6-cos-v1',
'sentence-transformers/distiluse-base-multilingual-cased-v2',
'sentence-transformers/all-MiniLM-L12-v2',
'BAAI/bge-small-en-v1.5',
'BAAI/bge-base-en-v1.5',
'taylorAI/bge-micro-v2',
'intfloat/e5-small-v2',
'intfloat/e5-base-v2',
'thenlper/gte-base',
'thenlper/gte-small',
'TaylorAI/gte-tiny',
'sentence-transformers/paraphrase-multilingual-mpnet-base-v2',
'intfloat/multilingual-e5-base',
'intfloat/multilingual-e5-small',
'sentence-transformers/stsb-xlm-r-multilingual',
'Snowflake/snowflake-arctic-embed-xs',
'Snowflake/snowflake-arctic-embed-s',
'Snowflake/snowflake-arctic-embed-m',
'mixedbread-ai/mxbai-embed-large-v1',
'openai/clip-vit-large-patch14',
'google/vit-base-patch16-224',
'microsoft/resnet-18',
'microsoft/resnet-50',
'WinKawaks/vit-tiny-patch16-224',
'Falconsai/nsfw_image_detection',
'WinKawaks/vit-small-patch16-224',
'nateraw/vit-age-classifier',
'rizvandwiki/gender-classification',
'AdamCodd/vit-base-nsfw-detector',
'trpakov/vit-face-expression',
'BAAI/bge-reranker-base',
'BAAI/bge-large-en-v1.5',
'ibm-granite/granite-embedding-278m-multilingual',
'thenlper/gte-large',
'Snowflake/snowflake-arctic-embed-l',
'WhereIsAI/UAE-Large-V1']
  10. Choose from:
    • To generate an ONNX file that you can manually upload to the database using the DBMS_VECTOR.LOAD_ONNX_MODEL, refer to step 3 of SQL Quick Start and skip step 10.
    • To upload the model directly into the database using the full version of the OML4Py client, skip this step and proceed to step 11.
    Export a preconfigured embedding model to a local file. Import ONNXPipeline and ONNXPipelineConfig from oml.utils. This exports the ONNX-format model to your local file system.
    from oml.utils import ONNXPipeline, ONNXPipelineConfig

# Export to file
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")
pipeline.export2file("your_preconfig_file_name",output_dir=".")

    Move the ONNX file to a directory on the database server, and create a directory on the file system and in the database for the import. 

    mkdir -p /tmp/models
sqlplus / as sysdba
alter session set container=<name of pluggable database>;

    Apply the necessary permissions and grants. 

    -- directory to store ONNX files for import
CREATE DIRECTORY ONNX_IMPORT AS '/tmp/models';
-- grant your OML user read and write permissions on the directory
GRANT READ, WRITE ON DIRECTORY ONNX_IMPORT to OMLUSER;
-- grant to allow user to import the model
GRANT CREATE MINING MODEL TO OMLUSER;

    Use the DBMS_VECTOR.LOAD_ONNX_MODEL procedure to load the model in your OML user schema. In this example, the procedure loads the ONNX model file named all-MiniLM-L6.onnx from the ONNX_IMPORT directory into the database as a model named ALL_MINILM_L6. 

    BEGIN
   DBMS_VECTOR.LOAD_ONNX_MODEL(
     directory => 'ONNX_IMPORT',
     file_name => 'all-MiniLM-L6-v2.onnx',
     model_name => 'ALL_MINILM_L6',
     metadata => JSON('{"function" : "embedding", "embeddingOutput" : "embedding", "input": {"input": ["DATA"]}}'));
END;
  11. Export a preconfigured embedding model to the database. If you are using a database connection, make sure to update the connection details to match your credentials and database environment.

    Note:

    To ensure step 11 works properly, complete steps 4 first. 
    # Import oml library and EmbeddingModel from oml.utils
import oml
from oml.utils import ONNXPipeline, ONNXPipelineConfig

# Set embedded mode to false for Oracle AI Database on premises. This is not supported or required for Oracle Autonomous AI Database.
oml.core.methods.__embed__ = False

# Create a database connection. 

# Oracle AI Database on-premises
oml.connect("<user>", "<password>", port=<port number> host="<hostname>", service_name="<service name>")

# Oracle Autonomous AI Database
oml.connect(user="<user>", password="<password>", dsn="myadb_low")
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")
pipeline.export2db("ALL_MINILM_L6")

    Query the model and its views, and you can generate embeddings from Python or SQL.

    import oracledb
cr = oml.cursor()
data = cr.execute("select vector_embedding(ALL_MINILM_L6 using 'RES' as DATA)AS embedding from dual")
data.fetchall()
    [(array('f', [-0.11642304062843323, 0.015433191321790218, -0.04692629724740982, 0.007167273201048374,
0.035023435950279236, -0.04029884934425354, 0.018412720412015915, 0.0648672804236412, 0.014992560259997845, 
0.012053844518959522, -0.03542192652821541, -0.09510122984647751, -0.020823240280151367, 0.049922555685043335, 
-0.01863112859427929, -0.026279663667082787, -0.03260187804698944, 0.05227319151163101, -0.09848847985267639, 
0.0009467907948419452, 0.04395370930433273, 0.01060416642576456, 0.029333725571632385, -0.04252052679657936, 
-0.025767622515559196, -0.03291202709078789, -0.053170595318078995, 0.07415973395109177, 0.0082617262378335, 
...
...
    SELECT VECTOR_EMBEDDING(ALL_MINILM_L6 USING 'RES' as DATA) AS embedding;
    EMBEDDING
--------------------------------------------------------------------------------
[-1.16423041E-001,1.54331913E-002,-4.69262972E-002,7.1672732E-003,3.5023436E-002
,-4.02988493E-002,1.84127204E-002,6.48672804E-002,1.49925603E-002,1.20538445E-00
2,-3.54219265E-002,-9.51012298E-002,-2.08232403E-002,4.99225557E-002,-1.86311286
E-002,-2.62796637E-002,-3.2601878E-002,5.22731915E-002,-9.84884799E-002,9.467907
95E-004,4.39537093E-002,1.06041664E-002,2.93337256E-002,-4.25205268E-002,-2.5767
...
...

    Note:

    To suppress Torch warnings, use the following code: 
    import warnings 
import torch warnings.filterwarnings("ignore", category=DeprecationWarning) 
warnings.filterwarnings("ignore", category=torch.jit.TracerWarning)
  12. Verify the model exists using SQL:
    sqlplus $USER/pass@PDBNAME;
    select model_name, algorithm, mining_function from user_mining_models where  model_name='ALL_MINILM_L6';

    ---------------------------------------------------------------------------
MODEL_NAME                 ALGORITHM                      MINING_FUNCTION
------------------------------ -------------------------------------------
ALL_MINILM_L6              ONNX                           EMBEDDING

Parent topic: Import Pretrained Models in ONNX Format