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_vectorreplaces both the vector and the metadata.get_vectorreturnsNonewhen 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).