Milvus Vector Store for LlamaIndex

Common errors

• ValueError: No index in storage context, check if you specified the right persist_dir.

  cause This error often occurs when attempting to load an index without correctly configuring the `StorageContext` to point to an existing `MilvusVectorStore` or if the specified collection does not exist when `overwrite=False` is set.
  fix When loading, ensure the `MilvusVectorStore` is initialized with the correct `uri`, `dim`, and `collection_name` for the *existing* Milvus collection, and set `overwrite=False`. Then pass this `vector_store` to `VectorStoreIndex.from_vector_store()`.

• pymilvus.exceptions.MilvusException: 'nlist out of range'

  cause This specific error for IVF_FLAT index types means the `nlist` parameter in `index_config` is set to a value outside its valid range (1 to 65536).
  fix Adjust the `nlist` parameter within your `index_config` dictionary to be an integer between 1 and 65536, compatible with the IVF_FLAT index type and your dataset size.

• Error communicating with Milvus, more can be found in logging under Debug / Unable to import pymilvus

  cause General connection or dependency issue. Either the Milvus server is not running, the URI is incorrect, or `pymilvus` (the underlying client library) is not installed or is an incompatible version.
  fix First, ensure `pymilvus` is installed (`pip install pymilvus>=2.4.2`). Verify that your Milvus instance (Lite or server) is running and accessible at the specified `uri`. Check network connectivity and firewall rules if connecting to a remote server.

Warnings

• breaking LlamaIndex v0.10+ introduced a significant refactor, splitting integrations like Milvus into separate PyPI packages and deprecating `ServiceContext`. Core modules are now under `llama_index.core`.
  Fix: Update your `pip install` commands to include specific integration packages (e.g., `llama-index-vector-stores-milvus`). Adjust imports to use `llama_index.core` for core components (e.g., `VectorStoreIndex`, `Settings`). Use `Settings` object for global configurations instead of `ServiceContext`.
• gotcha The `dim` parameter in `MilvusVectorStore` must exactly match the output dimension of your embedding model. Mismatched dimensions will lead to collection creation errors or data insertion failures.
  Fix: Ensure `dim` parameter matches your embedding model (e.g., 1536 for OpenAI's `text-embedding-ada-002`). You can get this from `Settings.embed_model.embed_dimension` if using LlamaIndex's `Settings`.
• gotcha Incorrect Milvus URI can lead to connection issues. A local file path (e.g., `./milvus.db`) uses Milvus Lite. A server address (e.g., `http://localhost:19530`) is required for a running Milvus server (Docker, Kubernetes, Zilliz Cloud).
  Fix: Verify your `uri` parameter: for Milvus Lite, use a local file path; for a Milvus server, use its correct network address. Ensure the Milvus server is running and accessible if using a network URI.
• gotcha Storing excessive non-defined metadata in documents can lead to 'Length of Dynamic Field Exceeding Max Length' errors in Milvus, as such data is often stored as a JSON string in a dynamic field.
  Fix: Reduce the size of dynamic metadata or explicitly define schema fields for larger metadata values within Milvus to avoid hitting the default 65536-byte limit for dynamic fields.

Install

• pip install llama-index-vector-stores-milvus llama-index pymilvus>=2.4.2 Install with core dependencies

Imports

• MilvusVectorStore

  from llama_index.vector_stores.milvus import MilvusVectorStore

• VectorStoreIndex
  wrong:

  from llama_index import VectorStoreIndex

  correct:

  from llama_index.core import VectorStoreIndex

  Following LlamaIndex v0.10+ packaging, core components are now in `llama_index.core`.

Quickstart

This quickstart demonstrates how to set up `MilvusVectorStore`, load documents using `SimpleDirectoryReader`, create a `VectorStoreIndex`, and query it. It uses Milvus Lite by default for ease of local setup and relies on OpenAI for embeddings and LLM.

import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.vector_stores.milvus import MilvusVectorStore
from llama_index.core.settings import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# Set up OpenAI API key (replace with your actual key or use environment variable)
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_API_KEY")

# Configure LlamaIndex settings
Settings.llm = OpenAI(model="gpt-3.5-turbo")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-ada-002")

# 1. Prepare some dummy data
# Create a dummy data directory and file if they don't exist
if not os.path.exists("data"): os.makedirs("data")
with open("data/milvus_doc.txt", "w") as f:
    f.write("The Milvus vector database is designed for AI applications and similarity search. It supports efficient storage and querying of billions of vectors. LlamaIndex provides a robust framework to integrate with various vector stores, including Milvus, to build powerful RAG systems. This integration allows users to leverage Milvus's capabilities for high-performance vector search within their LlamaIndex applications.")

# 2. Load documents
documents = SimpleDirectoryReader("data").load_data()

# 3. Initialize MilvusVectorStore (using Milvus Lite for local setup)
# For Milvus Lite, uri='./milvus.db' is convenient. For a Milvus server, use 'http://localhost:19530' or your server address.
# dim must match the dimension of your embedding model (e.g., 1536 for text-embedding-ada-002)
vector_store = MilvusVectorStore(
    uri="./milvus_test.db",
    dim=Settings.embed_model.embed_dimension,
    collection_name="llama_index_milvus_collection",
    overwrite=True # Set to True for a fresh start, False to append
)

# 4. Create an index
index = VectorStoreIndex.from_documents(documents, vector_store=vector_store)

# 5. Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is Milvus used for?")

print(response)

# To demonstrate loading an existing index (if overwrite was False or after a run)
# vector_store_load = MilvusVectorStore(
#     uri="./milvus_test.db",
#     dim=Settings.embed_model.embed_dimension,
#     collection_name="llama_index_milvus_collection",
#     overwrite=False
# )
# index_loaded = VectorStoreIndex.from_vector_store(vector_store_load)
# response_loaded = index_loaded.as_query_engine().query("What is LlamaIndex?")
# print(response_loaded)