Bug: bind-mounted data directory masks bundled embedding models in fresh deployments

Bug description

The Docker image ships with local embedding models baked into the image at /app/backend/data/cache/embedding/models/, and the default RAG config points to the built-in model (RAG_EMBEDDING_ENGINE empty + RAG_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2).

However, bind-mounting a host directory over /app/backend/data hides the baked-in models, making them unusable on fresh deployments.

The officially recommended docker run setup mounts a host directory:

docker run ... -v "${HOME}/open-webui/data:/app/backend/data" ...

A bind mount replaces the target directory in the container. On a fresh deployment the host data/ directory is empty, so the container sees an empty /app/backend/data/cache/embedding/models/. The bundled models are effectively masked, and the app falls back to downloading them at first use — which can fail on restricted/offline networks (or without an HF mirror).

Verified behavior

Without the volume mount (models present):

$ docker run --rm --entrypoint sh ghcr.io/open-webui/open-webui:latest \
    -c 'ls /app/backend/data/cache/embedding/models/'
models--TaylorAI--bge-micro-v2
models--sentence-transformers--all-MiniLM-L6-v2

With a fresh bind mount (models masked):

$ docker run --rm -v "$PWD/fresh-data:/app/backend/data" --entrypoint sh ghcr.io/open-webui/open-webui:latest \
    -c 'ls /app/backend/data/cache/embedding/models/'
ls: cannot access '.../embedding/models/': No such file or directory

Note: a Docker named volume (as used in the official docker-compose.yaml, open-webui:/app/backend/data) is not affected — Docker copies the image's directory contents into a newly created named volume. Only bind mounts (the docker run -v HOSTDIR:... style) are affected, because they replace the directory without seeding it.

Impact

• "Out-of-the-box local embedding" does not work on a standard docker run deployment.
• First use triggers a network download that may fail on offline/restricted environments.
• Users who don't realize the default is meant to be local often switch RAG to a remote engine (e.g. Ollama), which can be much slower (observed ~2.5 s/embedding vs ~0.01 s locally).

Proposed fix (PR-ready idea)

On startup, if SENTENCE_TRANSFORMERS_HOME lacks the bundled model snapshots, seed them from an image-local staging path that is not under the mounted tree:

import shutil, os

BUNDLED_MODELS = "/opt/open-webui/embedding_models"  # baked at build time, NOT under /app/backend/data
target = os.getenv("SENTENCE_TRANSFORMERS_HOME", "/app/backend/data/cache/embedding/models")

if os.path.isdir(BUNDLED_MODELS):
    for entry in os.listdir(BUNDLED_MODELS):
        src, dst = os.path.join(BUNDLED_MODELS, entry), os.path.join(target, entry)
        if not os.path.exists(dst):
            shutil.copytree(src, dst)

Alternatively, bake the models at a path outside the mounted tree and point SENTENCE_TRANSFORMERS_HOME there.

Bonus observations

1. huggingface_hub Xet/CAS 401: newer huggingface_hub reconstructs large files via Xet/CAS which returns 401 Unauthorized on HF mirrors; setting HF_HUB_DISABLE_XET=1 forces plain HTTP downloads and fixes it.
2. RAG_EMBEDDING_MODEL_AUTO_UPDATE=false: with a bundled model this keeps startup offline/fast and avoids revision-check noise.
3. Dimension mismatch on model switch: switching embedding models changes vector dimensions (e.g. 384 → 512), silently breaking retrieval on previously indexed collections. A warning when the embedding model changes would help.

Environment

• Open WebUI version: latest (0.11.x)
• Deployment: docker run with a bind-mounted data directory
• Embedding engine: built-in SentenceTransformers (default)

Start by tracing Docker startup and the handling of SENTENCE_TRANSFORMERS_HOME, /app/backend/data/cache/embedding/models/, and the proposed image-local /opt/open-webui/embedding_models path. Reproduce the fresh bind-mount case, then verify that bundled models remain available without disrupting named-volume deployments or existing model files.