Upgrading DocsGPT

Upgrading from 0.16.x? User data moved from MongoDB to Postgres in 0.17.0. Follow the Postgres Migration guide before running docker compose pull or git pull — existing deployments will not start cleanly without it.

Embedding models

DocsGPT now runs embeddings through FastEmbed (ONNX Runtime) instead of SentenceTransformer. The models are the same and the vectors are identical, so your existing index needs no action — all-mpnet-base-v2 keeps working exactly as before.

Your worker command does need one change. Query embedding now runs on the Celery worker (EMBEDDINGS_DELEGATE_TO_WORKER, on by default), which keeps the API from loading a model of its own. If you start your worker with an explicit -Q, add the embeddings queue:


- celery -A docsgpt.app.celery worker -l INFO -Q docsgpt,parsing
+ celery -A docsgpt.app.celery worker -l INFO -Q docsgpt,parsing,embeddings

The bundled Compose and Kubernetes manifests already do this — pull them along with the code. Without it, every search blocks for EMBEDDINGS_DELEGATE_TIMEOUT (60s) and then answers with no retrieved context rather than raising, so the symptom is bad answers, not an error. To keep the model out of the worker too, set EMBEDDINGS_BASE_URL; to run the API on its own, set EMBEDDINGS_DELEGATE_TO_WORKER=false.

New installs default to ibm-granite/granite-embedding-311m-multilingual-r2: multilingual, a 32k-token context, and the same 768 dimensions.

Switching an existing deployment to granite

Changing EMBEDDINGS_NAME on an index that already has vectors breaks retrieval silently. Both models are 768-dimensional, so nothing raises an error — queries are simply compared against vectors that mean something else, and answers quietly get worse. Always re-embed.

Set the model, then rebuild the vectors:


# 1. In your .env
EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2
 
# 2. Rebuild the vectors from the chunk text already in your index
docker compose exec backend python -m docsgpt.scripts.reembed --dry-run
docker compose exec backend python -m docsgpt.scripts.reembed

Re-embedding reads the chunk text already stored in your index. It does not re-download, re-parse or re-chunk your documents, so no source files are needed and the run is proportional to index size, not corpus size. Both pgvector and faiss are supported.

Useful flags:

Flag	Effect
`--dry-run`	Report how many chunks would change, write nothing
`--sources a,b`	Only these source ids — also how you retry a failed source
`--batch-size N`	Chunks per embed call (default 64)

The script processes sources independently: one failing source is reported and skipped rather than aborting the run, and the exit code is non-zero if any failed. For pgvector it reads a page of chunks at a time and updates rows in place, so memory stays flat on a large index and an interrupted run simply re-does its last batch. For faiss it builds the replacement index in memory, writes each file to a temporary path, and moves it into place — so an interrupt during either the rebuild or the write leaves the existing index intact rather than truncated.

Stop ingest before you run this. It reads each source’s chunks and writes the vectors back; anything ingested while it runs can be overwritten by the rebuild (faiss) or missed by it (pgvector).

Running GraphRAG? The script also rewrites graph_nodes.name_embedding, which seeds every graph traversal. Those vectors are written once at extraction time and share the chunk vectors’ width, so leaving them in the old model’s space degrades graph retrieval just as silently as the chunk vectors would — and needs no LLM re-extraction to fix.

Custom local models

A local model now runs through ONNX Runtime, so its repository must ship an ONNX export (onnx/model.onnx) or be one of FastEmbed’s built-in models. Repositories with PyTorch weights only no longer load; hkunlp/instructor-large, previously supported by name, is one of them. Serve such a model over EMBEDDINGS_BASE_URL instead, or switch to a model with an export.

How to run the model — pooling, and whether outputs are L2-normalised — is read from the repository’s own 1_Pooling/config.json and modules.json. Two cases need attention:

Models with a Dense projection layer (sentence-transformers/LaBSE, distiluse-base-multilingual-cased-v1) are now refused at startup. FastEmbed cannot apply the projection, so it would have produced vectors of the wrong width in a different space. If you were running one, its stored vectors were already wrong; move it to EMBEDDINGS_BASE_URL or pick another model.
Repositories that declare nothing fall back to mean pooling with normalisation and log a warning. Pin the real values with EMBEDDINGS_POOLING (cls or mean) and EMBEDDINGS_NORMALIZE.

Staying on all-mpnet-base-v2 is a supported choice — it remains in the model registry and in setup.sh. You only need this section if you want to move to granite.

Backend package renamed to `docsgpt`

The backend’s Python package is docsgpt (it was application), the name it will carry on PyPI. For one release the old name keeps working through an alias, so nothing breaks on upgrade, but update these before the alias goes:

Entry points: celery -A docsgpt.app.celery worker, uvicorn docsgpt.asgi:asgi_app, python -m docsgpt.scripts.<name>. The application.… spellings still run and print a FutureWarning. The compose files, Kubernetes manifests and setup scripts in the repository are already updated; only custom copies need editing.
Local image builds: the build context is the repository root, so use docker build -f docsgpt/Dockerfile . (or the compose files, which do this).
Celery task names changed with the package (docsgpt.api.user.tasks.ingest and so on). A worker on this release also accepts the old names, so tasks queued before the upgrade still run, and beat rewrites the periodic schedule in Redis on start-up. The daily, weekly and monthly source-sync timers restart from the upgrade, so the first sync after it can land later than it would have (a monthly sync by up to a month). Nothing to do.
Data directories do not move: the compose files keep your indexes, inputs and vectors under application/ in the checkout, where they already are.
The backend is also a package now (pip install docsgpt, see Install with pip). Runtime data lives in a data home: DOCSGPT_HOME, else the checkout, else the directory the process starts in. One consequence for a source checkout: the embedded Milvus (MILVUS_URI) and LanceDB (LANCEDB_PATH) default paths now resolve under the checkout instead of the start directory. If you use either store at its default path and start DocsGPT from another directory, the old data is at <start directory>/milvus_local.db or <start directory>/data/lancedb; point the setting at it, or move it into the checkout. Faiss indexes and uploads were already stored under the checkout and are unaffected.

Check your version


docker compose exec backend python -c "from docsgpt.version import get_version; print(get_version())"

Release notes: changelog. Tags: GitHub releases .

Docker Compose — hub images


cd DocsGPT/deployment
docker compose -f docker-compose-hub.yaml pull
docker compose -f docker-compose-hub.yaml up -d

pull fetches the latest image for whichever tag your compose file references. To move to a specific release, edit image: arc53/docsgpt:<tag> first.

Docker Compose — from source


cd DocsGPT
git pull
docker compose -f deployment/docker-compose.yaml build
docker compose -f deployment/docker-compose.yaml up -d

Swap git pull for git checkout <tag> if you want to pin a specific release.

Kubernetes


kubectl set image deployment/docsgpt-backend backend=arc53/docsgpt:<tag>
kubectl set image deployment/docsgpt-worker worker=arc53/docsgpt:<tag>
kubectl rollout status deployment/docsgpt-backend
kubectl rollout status deployment/docsgpt-worker

Full manifests: Kubernetes deployment guide.

Migrations

Alembic migrations run on worker startup. To apply manually:


docker compose exec backend alembic -c docsgpt/alembic.ini upgrade head

upgrade head is idempotent.

Rollback

Set the image tag to the previous release and up -d again. Schema changes are not reversible without a backup — take one before upgrading any release that mentions migrations in the changelog.