[OpenStack] RAG content

This repository contains scripts that can be used to generate a vector database containing information from OpenStack operators documentation and supplemental SME notes.

There are several ways how to access the OpenStack vector database:

• Generate OpenStack Vector Database

• Build Container Image Containing OpenStack Vector Database

• Download the Pre-built Container Image Containing OpenStack Vector Database

Generate OpenStack Vector Database

1. Install requirements: python3.12.* and system tools.

Required system tools:

• See .s2i/builddeps.txt for the canonical build dependency list.
• pandoc + rubygem-asciidoctor are only needed when building operators docs.

2. Create virtualenv.

python3.12 -m venv .venv && . .venv/bin/activate

3. Install dependencies.

pip install .

4. Generate operators documentation in markdown format.

Note

The operators-docs conversion script (./scripts/get_openstack_operators_docs.sh) requires pandoc and asciidoctor (RHEL package: rubygem-asciidoctor) installed on the host.

./scripts/get_openstack_operators_docs.sh

Useful env vars for this script:

• CLEAN_FILES what to clean on success: all (whole project), or nothing (default).
• WORKING_DIR if you don't want to use the default /tmp/os_operators_docs_temp.

5. Download the embedding model.

make get-embeddings-model

Note

The get-embeddings-model target pulls in the embedding model from the most recent build. To download it from source, use the download_embeddings_model.py script from lightspeed-core/rag-content:

curl -O https://raw.githubusercontent.com/lightspeed-core/rag-content/refs/heads/main/scripts/download_embeddings_model.py
python ./download_embeddings_model.py \
    -l ./embeddings_model/ \
    -r sentence-transformers/all-mpnet-base-v2

6. Generate the vector database.

• For llama-index

python -m openstack_lightspeed_rag_content.generate_embeddings_openstack \
        -o ./vector_db/ \
        --operators-folder openstack-operators-docs-markdown \
        -md embeddings_model \
        -mn sentence-transformers/all-mpnet-base-v2 \
        -i os-docs \
        -w $(( $(nproc --all) / 2 ))

• For llama-stack

python -m openstack_lightspeed_rag_content.generate_embeddings_openstack \
        -o ./vector_db/ \
        --operators-folder openstack-operators-docs-markdown \
        -md embeddings_model \
        -mn sentence-transformers/all-mpnet-base-v2 \
        -i os-docs \
        --vector-store-type=llamastack-faiss \
        -w $(( $(nproc --all) / 2 ))

7. Test the database stored in ./vector_db

curl -o /tmp/query_rag.py https://raw.githubusercontent.com/lightspeed-core/rag-content/refs/heads/main/scripts/query_rag.py
python /tmp/query_rag.py -p vector_db -x os-docs -m embeddings_model -k 5 -q "how can I configure a cinder backend"

8. Use the vector database stored in ./vector_db.

Build Container Image Containing OpenStack Vector Database

1. Install requirements: make, podman.

2. Pre-fetch external artifacts required by the build:

.s2i/get_artifacts.sh .s2i/artifacts.txt

3. Generate the container image. If you have GPU available, use FLAVOR=gpu.

make build-image-os FLAVOR=cpu

The embeddings and databases will be present in the /rag directory with the following structure:

.
├── embeddings_model
├── okp_embeddings_model
└── vector_db
    └── os_product_docs

If we have an Nvidia GPU card properly configured in podman we can run:

make build-image-os FLAVOR=gpu

If our GPU is not an Nvidia card and is supported by podman and torch, then we can override the default value in BUILD_GPU_ARGS (here we show de default value):

make build-image-os FLAVOR=gpu BUILD_GPU_ARGS="--device nvidia.com/gpu=all"

Note

Using GPU capabilities within a Podman container requires setting up your OS to utilize the GPU. Follow official instructions to create the CDI.

3. The generated vector database can be found under /rag/vector_db/os_product_docs inside of the image.

podman run localhost/rag-content-openstack:latest ls /rag/vector_db/os_product_docs

Download the Pre-built Container Image Containing OpenStack Vector Database

We periodically build the vector database from the documentation sources configured in this repository. The image containing this vector database is available at quay.io/openstack-lightspeed/rag-content.

You can verify that the image was built within a job triggered by this repository using the cosign utility:

IMAGE=quay.io/openstack-lightspeed/rag-content@sha256:<sha256sum>
cosign verify --key https://raw.githubusercontent.com/openstack-k8s-operators/lightspeed-rag-content/refs/heads/main/.github/workflows/cosign.pub ${IMAGE}