Milvus Integration#

Dify's Milvus integration is implemented as a plugin in milvus_vector.py, backed by pymilvus.MilvusClient. It supports dense vector search (HNSW index, inner-product metric), hybrid dense+sparse search (BM25, requires Milvus ≥ 2.5.0), token- and username/password-based auth, and one-way TLS.

Configuration is declared in MilvusConfig (Pydantic BaseSettings), which is instantiated by MilvusVectorFactory.init_vector(). All settings are read from environment variables.

Environment Variables#

Auth validation: MilvusConfig requires either MILVUS_TOKEN or both MILVUS_USER and MILVUS_PASSWORD 11.

One-Way TLS#

Added in PR #36265 (merged 2026-05-27), one-way TLS maps directly to pymilvus's MilvusClient(secure=True, server_pem_path=..., server_name=...).

The logic in _init_client() only injects TLS kwargs when MILVUS_SECURE=True, so existing deployments are unaffected by default:

MILVUS_SECURE=True
MILVUS_SERVER_PEM_PATH=/etc/milvus/certs/server.pem # must be mounted into container
MILVUS_SERVER_NAME=milvus.example.com # CN or SAN on the server cert

MILVUS_SERVER_PEM_PATH must point to a file inside the container. In Kubernetes, mount the PEM via a Secret volume. In Docker Compose, use a bind mount. MILVUS_SERVER_NAME is required when MILVUS_SERVER_PEM_PATH is set; it is used for SNI and certificate verification 10.

Hybrid Search#

When MILVUS_ENABLE_HYBRID_SEARCH=True (the default), Dify checks the connected Milvus version at startup via _check_hybrid_search_support(): it requires Milvus ≥ 2.5.0 or Zilliz Cloud. On version check failure, hybrid search is silently disabled.

New collections include a sparse_vector field (BM25 function over content) alongside the dense vector field 12. Collections created before hybrid search was enabled are missing the sparse_vector field and fall back gracefully — full-text search returns an empty result with a warning rather than an error 13. To use hybrid search on an existing collection, drop and recreate it.

MILVUS_ANALYZER_PARAMS lets you override the tokenizer per collection (e.g. {"type": "chinese"} for Chinese text) 7.

Upgrade & Migration#

Re-indexing with flask vdb-migrate#

flask vdb-migrate re-vectorizes all knowledge-base and annotation data into the currently configured VECTOR_STORE. Use it when switching vector store backends or when vectorization must be rebuilt.

Milvus is classified as an upper_collection_vector_types backend 14, meaning collection names are generated uppercase via Dataset.gen_collection_name_by_id(). Run with --scope knowledge, --scope annotation, or (default) --scope all.

docker compose exec api flask vdb-migrate --scope all

Standard Dify Upgrade Sequence#

When upgrading Dify versions, always run schema migration before data commands:

1. docker compose exec api flask upgrade-db — applies Alembic schema migrations
2. docker compose exec api flask backfill-plugin-auto-upgrade — backfills plugin strategy rows; must follow step 1 — the category column it queries does not exist until after the schema migration runs 15
3. docker compose exec api flask vdb-migrate — only needed if re-indexing vector data is required

Key Source Files#