Skip to content

Milvus

Milvus is an open-source vector database built for large collections and high query rates. Agents use it through MilvusStore, a direct SDK in agent_addons built on the official pymilvus client, either on its own or as the "milvus" provider of EmbeddingsSDK.

The same code works with every Milvus deployment:

Deployment uri Use it for
Milvus Standalone http://<host>:19530 A single-node server in your cluster
Milvus Distributed http://<proxy-host>:19530 Large collections and high query rates
Zilliz Cloud (managed Milvus) Your cluster's public endpoint, with an API key as token No servers to run
Milvus Lite A local file, e.g. ./agent_vectors.db Development, notebooks and tests

To run Milvus in your own cluster, use the vector database deployer in WikiGrid (OpenWiki.network docs).


Installation

pip install "./libs/agents-addons[milvus]"    # installs pymilvus >= 2.4.2
pip install milvus-lite                       # only for Milvus Lite (local files)

Connecting

from agent_addons.embeddings_store import EmbeddingsSDK

vdb = EmbeddingsSDK(
    provider="milvus",
    milvus_uri="http://milvus.vector.svc.cluster.local:19530",
    milvus_token="root:Milvus",       # optional: "user:password" or a Zilliz Cloud API key
    milvus_db_name=None,              # optional: Milvus database
    dimension=1536,
    metric="cosine",
)
from agent_addons.vector_backends import MilvusStore

store = MilvusStore(
    "http://milvus.vector.svc.cluster.local:19530",
    token="root:Milvus",
    dimension=1536,
    metric="cosine",
)

Both give you the same methods. EmbeddingsSDK adds the text-based helpers (insert_texts, search_text, …), file and S3 ingestion, and works with AgentRAG. Through EmbeddingsSDK, the underlying store is available as vdb.store and the pymilvus client as vdb.client.

MilvusStore argument EmbeddingsSDK argument Default Description
uri milvus_uri http://localhost:19530 (required for EmbeddingsSDK) Server URI, Zilliz Cloud endpoint, or a local .db file
token milvus_token None "user:password" or an API key
db_name milvus_db_name None Milvus database
dimension dimension None Vector dimension, required to create collections
metric metric "cosine" "cosine", "dotproduct" (or "ip") or "euclidean" (or "l2")
index_type milvus_index_type "AUTOINDEX" Index type for new collections, e.g. "HNSW", "IVF_FLAT", "DISKANN"
index_params milvus_index_params None Index build parameters, e.g. {"M": 16, "efConstruction": 200} for HNSW
consistency_level milvus_consistency_level "Bounded" "Strong", "Bounded", "Session" or "Eventually"
client — None An existing MilvusClient to reuse instead of connecting

Read your own writes

With the default "Bounded" consistency, a search issued straight after an insert may not see the new records yet. If an agent writes and then immediately searches the same collection, create the collection with consistency_level="Strong".


Collections

vdb.create_collection("knowledge_base")
vdb.list_collections()                  # ['knowledge_base', ...]
store.has_collection("knowledge_base")  # True
store.count("knowledge_base")           # number of records
vdb.delete_collection("knowledge_base")

Every collection has the same schema, so records from any agent look alike:

Field Milvus type Holds
id VARCHAR (primary key, up to 512 characters) Your record ID; any string
vector FLOAT_VECTOR(dimension) The embedding
metadata JSON Everything else: text, source, tags, …

create_collection builds the vector index with the configured index_type and metric and loads the collection, so it is ready to search straight away. Collection names may contain letters, digits and underscores, and must start with a letter or an underscore.


Writing and Reading

vdb.insert_vectors("knowledge_base", [
    {"id": "doc-1", "values": [0.12, 0.98, ...], "metadata": {"text": "Vector DBs store embeddings.", "source": "wiki", "year": 2024}},
    {"id": "doc-2", "values": [0.33, 0.71, ...], "metadata": {"text": "Acme is based in Delaware.", "source": "legal"}},
])

vdb.get_vector("knowledge_base", "doc-1")
# {"id": "doc-1", "values": [...], "metadata": {"text": "...", "source": "wiki", "year": 2024}}

vdb.update_vector("knowledge_base", "doc-1", new_values, metadata={"text": "...", "source": "wiki", "year": 2025})
vdb.delete_vector("knowledge_base", "doc-2")
  • Inserts are upserts: inserting an ID that already exists replaces that record.
  • update_vector replaces both the vector and the metadata.
  • get_vector returns None when the ID does not exist.

Searching

results = vdb.search("knowledge_base", query_vector, top_k=5)
{
  "matches": [
    { "id": "doc-1", "score": 0.93, "distance": 0.93, "metadata": { "text": "...", "source": "wiki" } },
    { "id": "doc-2", "score": 0.41, "distance": 0.41, "metadata": { "text": "...", "source": "legal" } }
  ]
}

Matches are sorted best first. distance is the value Milvus returns; score is always "higher is better":

metric Milvus metric distance score
cosine COSINE Cosine similarity Same as distance
dotproduct IP Inner product Same as distance
euclidean L2 Squared Euclidean distance (lower is better) 1 / (1 + distance)

To pass index-specific search parameters, such as ef for HNSW or nprobe for IVF, call the store directly:

vdb.store.search("knowledge_base", query_vector, top_k=10, search_params={"ef": 128})

Filters

filters restricts the search to records whose metadata matches. Pass either a dict or a Milvus boolean expression:

# Dict: equality on metadata keys, joined with "and"; a list means "any of"
vdb.search("knowledge_base", qv, top_k=5, filters={"source": "wiki"})
vdb.search("knowledge_base", qv, top_k=5, filters={"source": "wiki", "lang": ["en", "de"]})

# Expression string: anything Milvus supports on the JSON field
vdb.search("knowledge_base", qv, top_k=5, filters='metadata["year"] >= 2024 and metadata["source"] != "legal"')
vdb.search("knowledge_base", qv, top_k=5, filters='json_contains(metadata["tags"], "contracts")')

The dict {"source": "wiki", "lang": ["en", "de"]} becomes metadata["source"] == "wiki" and metadata["lang"] in ["en", "de"].


Text, Ingestion and RAG

Everything in the Usage Guide works unchanged with provider="milvus":

from agents_embeddings.custom import OpenAIEmbeddingsGenerator
from agent_addons.rag import AgentRAG

embedder = OpenAIEmbeddingsGenerator(model="text-embedding-3-small")

vdb.insert_texts("knowledge_base", [{"text": "Vector DBs store embeddings.", "metadata": {"text": "Vector DBs store embeddings."}}], embedder=embedder)
hits = vdb.search_text("knowledge_base", "What stores embeddings?", embedder=embedder, top_k=3)

rag = AgentRAG(collection="knowledge_base", embeddings_sdk=vdb, embedder=embedder, llm=llm)
rag.add_documents_chunked([{"id": "contract-1", "text": long_contract_text}])
answer = rag.ask("Where is RetailCo based?")

EmbeddingsSDK can also be the sink of S3Ingestor and RedisIngestor (in agent_addons.ingestors), because it has the insert_vectors(collection, payload) method they call.


Milvus Lite for Development

Milvus Lite runs Milvus inside your Python process and stores the data in a local file. Use the same code, with a file path as the URI:

vdb = EmbeddingsSDK(provider="milvus", milvus_uri="./agent_vectors.db", dimension=384,
                    milvus_consistency_level="Strong")

Milvus Lite needs the milvus-lite package and runs on Linux and macOS. Use it for notebooks and unit tests; use Milvus Standalone or Distributed for deployed agents.


Registering Milvus in the Subject Specification

Record the database as an add-on in integrations.addons (see Registering Vector DB in Subject Specification):

{
  "addon_id": "vector-primary",
  "addon_type": "vector_db",
  "addon_config": {
    "provider": "milvus",
    "milvus_uri": "http://milvus.vector.svc.cluster.local:19530",
    "dimension": 1536,
    "metric": "cosine"
  }
}

Keep credentials out of the specification. Pass the token from the environment when you build the client:

import os

addon = next(a for a in self.subject.integrations.addons if a.addon_id == "vector-primary")
vdb = EmbeddingsSDK(**addon.addon_config, milvus_token=os.environ.get("MILVUS_TOKEN"))

Example: Agent Memory of Past Answers

import os, uuid
from agent_addons.embeddings_store import EmbeddingsSDK
from agents_embeddings.custom import OpenAIEmbeddingsGenerator


class AnswerMemory:
    """Remembers past answers so the agent can reuse them for similar questions."""

    def __init__(self, agent_id: str):
        self.collection = f"answers_{agent_id.replace('-', '_')}"
        self.embedder = OpenAIEmbeddingsGenerator(model="text-embedding-3-small")
        self.vdb = EmbeddingsSDK(
            provider="milvus",
            milvus_uri=os.environ["MILVUS_URI"],
            milvus_token=os.environ.get("MILVUS_TOKEN"),
            dimension=1536,
            milvus_consistency_level="Strong",
        )
        if self.collection not in self.vdb.list_collections():
            self.vdb.create_collection(self.collection)

    def remember(self, question: str, answer: str, task_id: str):
        self.vdb.insert_texts(self.collection, [{
            "id": task_id or uuid.uuid4().hex,
            "text": question,
            "metadata": {"question": question, "answer": answer},
        }], embedder=self.embedder)

    def recall(self, question: str, min_score: float = 0.9):
        hits = self.vdb.search_text(self.collection, question, embedder=self.embedder, top_k=1)["matches"]
        if hits and hits[0]["score"] >= min_score:
            return hits[0]["metadata"]["answer"]
        return None

Ecosystem reference

MemoryGrid also stores lesson embeddings in Milvus (MG_VECTOR_BACKEND=milvus); see the Learner. For deployers for vector databases, see WikiGrid (OpenWiki.network docs, GitHub).