Open Data Hub OGX Distribution

This directory contains the necessary files to build an Open Data Hub-compatible container image for OGX.

To learn more about the distribution image content, see the README in the distribution/ directory.

Build Instructions

Prerequisites

• The pre-commit tool is installed

Regenerating distribution artifacts

The distribution/config.yaml and distribution/requirements.txt files are auto-generated by build/build.py. To regenerate them:

pre-commit run --all-files

This will:

• Install OGX in a temporary virtual environment
• Execute ./build/build.py to generate distribution/config.yaml and distribution/requirements.txt
• Execute ./build/gen_distro_docs.py to regenerate distribution/README.md

Warning

Do not edit distribution/config.yaml, distribution/requirements.txt, or distribution/README.md manually — they are regenerated on every commit.

Editing the Containerfile

The Containerfile at the repo root is hand-edited. Modify it directly.

Run Instructions

Tip

Ensure you include any env vars you might need for providers in the container env - you can read more about that here.

podman run -p 8321:8321 quay.io/opendatahub/odh-ogx-core:<tag>

What image tag should I use?

Various tags are maintained for this image:

• latest will always point to the latest image that has been built off of a merge to the main branch
  • You can also pull an older image built off of main by using the SHA of the merge commit as the tag
• rhoai-v*-latest will always point to the latest image that has been built off of a merge to the corresponding rhoai-v* or release-* branch (e.g., a push to release-3.5-ea.2 produces the tag rhoai-v3.5-ea.2-latest)

You can see the source code that implements this build strategy here

Running with a custom run YAML

The distribution image allows you to run a custom run YAML file within it. To do so, run the image in the following way. The "path" mentioned should be the path to your custom run YAML file.

podman run \
  -p 8321:8321 \
  -v <path_on_host>:<path_in_container> \
  -e RUN_CONFIG_PATH=<path_in_container> \
  quay.io/opendatahub/odh-ogx-core:<tag>

Important

The distribution image ships with various dependencies already pre-installed. There is no guarantee that your custom run YAML will necessarily work with the included dependencies.

Note

The container image includes pre-installed dependencies for more providers than are present in the default runtime configuration (config.yaml). Providers such as inline::sentence-transformers, inline::milvus, and inline::faiss are available as dependencies but are stripped from the default config.yaml. The full provider manifest is maintained in build/build.yaml. To use these dependency-only providers, pass a custom config.yaml at runtime (as shown above) that includes the desired provider definitions. See the distribution README for which providers are dependency-only.

Responses API Tests

An orchestrator workflow (responses-weekly.yml / "Responses: Test Report") runs upstream Responses API integration tests against the distro image every Sunday at 22:00 UTC across all configured providers, then publishes an interactive test report to GitHub Pages.

Provider	Default text model	Embedding model	Workflow
OpenAI	gpt-4.1-nano	text-embedding-3-small	responses-openai.yml
Vertex AI	gemini-2.5-flash	gemini-embedding-2	responses-vertexai.yml
vLLM MaaS	llama-3-2-3b	nomic-embed-text-v1-5	responses-vllm-maas.yml

How it works

1. Each provider's credentials are checked; providers without secrets are skipped gracefully
2. Each per-provider workflow (responses-openai.yml, responses-vertexai.yml, responses-vllm-maas.yml) pulls the distro image, starts PostgreSQL (with pgvector) and the server via the setup-server composite action
3. Models run in parallel via GitHub Actions matrix strategy — each model gets its own job
4. Upstream tests/integration/responses/ are run with pytest in --inference-mode=live, producing JUnit XML results
5. The orchestrator collects all artifacts and deploys a test report with trend charts (by provider and by model) and a model breakdown table to GitHub Pages
6. JUnit results are also published as GitHub Check annotations via dorny/test-reporter

Test report

The report is a static HTML dashboard (no backend) with:

• Trend by Provider and Trend by Model line charts showing passed test counts per OGX release (linked: clicking a provider filters the model chart)
• Model Breakdown table with pass/fail/skip/error counts per provider and model
• Run History table with links to GitHub Actions runs
• Branch-isolated history: main deploys to root, other branches to preview/<branch>/ (last 20 runs each)

Triggers

Trigger	Scope	Report location
schedule (Sunday 22:00 UTC)	Runs from main	Root (/)
workflow_dispatch	Any branch, per-provider toggles, model overrides	preview/<branch>/ for non-main branches

Individual provider workflows can also be triggered manually via workflow_dispatch for on-demand runs (tests only, no report deployment).

Adding providers and models

To override models: pass comma-separated model IDs via the models input when dispatching a provider workflow or the orchestrator. To add a provider: create a new per-provider workflow following the existing pattern and add the provider job to responses-weekly.yml. The report template is fully dynamic — new providers and models appear automatically.

Required Secrets

Provider	Secrets
OpenAI	OPENAI_API_KEY
Vertex AI	VERTEX_AI_PROJECT, GCP_WORKLOAD_IDENTITY_PROVIDER
vLLM MaaS	MAAS_VLLM_URL, MAAS_VLLM_API_TOKEN, MAAS_EMBEDDING_URL, MAAS_EMBEDDING_API_TOKEN

ARM64 Support

The distribution image supports both amd64 and arm64 architectures. CI runs the full test suite (build, smoke tests, and integration tests) on both architectures using multi-arch vLLM CPU images. When MaaS (Model-as-a-Service) endpoints are configured, they override the local vLLM containers on both architectures.

Slack Build Notifications

Slack notifications are sent on successful image push (push/workflow_dispatch) and on build failures.

Configuration

Add a repository secret (Settings → Secrets and variables → Actions → New repository secret):

• Name: WH_SLACK_TEAM_LLS_CORE
• Value: Slack webhook URL (e.g., https://hooks.slack.com/services/...)

To notify multiple channels, use comma-separated webhook URLs in SLACK_WEBHOOK_URLS.

Local Testing

Preview the message format without sending:

IMAGE_NAME=quay.io/opendatahub/odh-ogx-core IMAGE_TAG=abc123 COMMIT_SHA=abc1234567890 \
  WORKFLOW_URL=https://github.com/... .github/actions/notify-slack/notify.sh --preview