Configuration

The Oracle AI Optimizer and Toolkit (the AI Optimizer) requires some configuration to take full advantage of the AI capabilities in Oracle AI Database. Most settings can be configured through the application interface.

However, you can use environment variables to reduce how much needs to be configured manually and to enable features such as observability.

Getting Started

You can configure the application from the shell by exporting variables before startup. For example:

export AIO_DB_USERNAME=demo
export AIO_DB_PASSWORD=replace-with-your-password
export AIO_DB_DSN=localhost:1521/FREEPDB1

For a reusable, local configuration, an .env.* file is a better alternative. It keeps related settings together and avoids exporting them again in every shell session. Create one by copying the provided example:

cp src/.env.example src/.env.dev

Edit src/.env.dev and uncomment the settings you need. For example, to configure a CORE database connection:

AIO_DB_USERNAME=demo
AIO_DB_PASSWORD=replace-with-your-password
AIO_DB_DSN=localhost:1521/FREEPDB1

Configuring a valid CORE database with AIO_DB_USERNAME, AIO_DB_PASSWORD, and AIO_DB_DSN enables application settings persistence and provides the database access required by RAG, NL2SQL, and the Testbed. Models and other settings configured through the interface are then restored from the configured CORE database after a restart.

How Configuration Works

Configuration is loaded, updated, and saved through the following paths:

flowchart TD
    exported["Shell, container, or pod AIO_* variables"] -->|Highest precedence| settings["AI Optimizer settings"]
    envfile["src/.env.{AIO_ENV}"] -->|Used when not already set| settings
    persisted["CORE database<br>Previously saved settings"] -->|Loaded when not overridden| settings
    defaults["Application defaults"] -->|Used when unset| settings
    interface["Application interface"] -->|Updates settings| settings
    settings -->|Saved when CORE is configured| persisted

Environment Variables

When the AI Optimizer starts, environment variables are read from the process environment or from a .env.{AIO_ENV} file in the src/ directory, as outlined above. In a POSIX shell, use export so that the application inherits the variables; shell-local variables are not part of the child process environment. Variables already present in the process environment are not overwritten by values in the environment file.

To select an environment file, export AIO_ENV before startup. For example, export AIO_ENV=prd loads src/.env.prd. If AIO_ENV is unset, it defaults to dev.

Restart the affected component after changing a value.

The variables below are specific to the AI Optimizer and use the AIO_ prefix. Integrations such as OpenTelemetry and OpenInference also use their own environment variables; these are covered in the relevant integration documentation. TNS_ADMIN usage is covered under Database Configuration.

Application

Authentication

Database

These variables configure the CORE database connection. See Database Configuration for connection formats, wallet setup, and required privileges.

Server

Client

OCI CLI Overrides

These settings populate the DEFAULT OCI profile. See OCI Configuration for authentication requirements and supported authentication types.

OCI GenAI

OCI Object Storage Source Lock

Pin the Split & Embed tab’s OCI source compartment and, optionally, its bucket for every user of the deployment. The compartment must resolve against the active OCI profile. The bucket is only applied when the compartment resolves and the bucket exists in that compartment.

Model Overrides

These settings provide API keys or service URLs and enable matching built-in models at startup.

NL2SQL

Observability

OpenTelemetry endpoints, protocols, exporters, sampling, and OpenInference payload visibility use their standard integration variables. See Observability for the supported settings and deployment examples.

Containers and Kubernetes

Container

Pass the environment file when starting the container:

podman run --env-file src/.env.dev -p 8501:8501 -it --rm ai-optimizer-aio

Kubernetes

When using Kubernetes, configure the application through the first-class Helm values and Kubernetes Secrets. The chart translates these values into application or integration variables and can also be embedded as a subchart without requiring the same setting in two places.