AgentScope provides a flexible abstraction layer for vector databases through the VectorStoreBase interface. This allows the RAG (Retrieval-Augmented Generation) subsystem to swap between local, in-memory, and distributed vector stores without changing the application logic.
The VectorStoreBase class defines the standard contract for all vector backend implementations. It ensures that regardless of the underlying database, the system can perform collection management, idempotent writes, and similarity searches.
Vector stores in AgentScope are designed as asynchronous context managers. They lazily initialize their respective clients upon the first call to get_client() and ensure proper resource cleanup during __aexit__.
Vector Store Interaction Flow
Sources: src/agentscope/rag/_vdb/_vector_store.py1-24 src/agentscope/rag/_vdb/_qdrant.py95-123 src/agentscope/rag/_vdb/_milvus_lite.py78-103 src/agentscope/rag/_vdb/_mongodb.py108-133 src/agentscope/rag/_vdb/_elasticsearch.py67-87
VectorRecord: Represents a single entry to be stored, containing the document_id, the Chunk object, and the embedding vector src/agentscope/rag/_vdb/_vector_store.py23-46VectorSearchResult: The return type for search operations, containing the original Chunk and the similarity score src/agentscope/rag/_vdb/_vector_store.py49-65DocumentSummary: A specialized structure for storing and retrieving high-level summaries of documents within a collection src/agentscope/rag/_vdb/_vector_store.py68-77AgentScope supports four primary backends, each catering to different scales and deployment requirements.
QdrantStore is the default backend. It is highly versatile, supporting in-memory operation for testing, local disk persistence, or remote server connections.
| Mode | Configuration | Use Case |
|---|---|---|
| In-Memory | location=":memory:" | Unit tests and ephemeral demos src/agentscope/rag/_vdb/_qdrant.py12 |
| Local Disk | path="/path/to/db" | Local development with persistence src/agentscope/rag/_vdb/_qdrant.py13 |
| Remote/Cloud | url="http://host:6333" | Production deployments src/agentscope/rag/_vdb/_qdrant.py14 |
Sources: src/agentscope/rag/_vdb/_qdrant.py9-15 src/agentscope/rag/_vdb/_qdrant.py31-56
MilvusLiteStore is built on pymilvus. It is particularly useful for local RAG workloads because it starts automatically when the URI points to a .db file, providing a "serverless" local experience similar to SQLite.
__aexit__ src/agentscope/rag/_vdb/_milvus_lite.py101-102Sources: src/agentscope/rag/_vdb/_milvus_lite.py26-52 src/agentscope/rag/_vdb/_milvus_lite.py78-103
MongoDBStore enables vector search on MongoDB Atlas or self-hosted MongoDB 7.0+ clusters. This is ideal for teams already using MongoDB as their primary database.
vectorSearch index type using SearchIndexModel src/agentscope/rag/_vdb/_mongodb.py179-184metadata_filter must be explicitly declared in filter_fields during initialization to be included in the index definition src/agentscope/rag/_vdb/_mongodb.py44-46$vectorSearch aggregation stage src/agentscope/rag/_vdb/_mongodb.py240-255Sources: src/agentscope/rag/_vdb/_mongodb.py31-73 src/agentscope/rag/_vdb/_mongodb.py147-186
ElasticsearchStore utilizes dense-vector indexes. It is designed for high-throughput environments and complex filtering.
dense_vector with cosine similarity src/agentscope/rag/_vdb/_elasticsearch.py98-103dynamic: "runtime" to prevent unbounded dynamic mapping issues src/agentscope/rag/_vdb/_elasticsearch.py25-27 src/agentscope/rag/_vdb/_elasticsearch.py106bulk API src/agentscope/rag/_vdb/_elasticsearch.py147-150Sources: src/agentscope/rag/_vdb/_elasticsearch.py20-58 src/agentscope/rag/_vdb/_elasticsearch.py89-110
The following diagrams bridge the natural language concepts of "Storage" and "Search" to the specific classes and methods in the agentscope.rag module.
Entity Mapping: Document to Vector Record
Sources: src/agentscope/rag/_document.py7-8 src/agentscope/rag/_vdb/_vector_store.py23-46 src/agentscope/rag/_vdb/_vector_store.py79-88
Entity Mapping: Search and Retrieval
Sources: src/agentscope/rag/_vdb/__init__.py4-24 src/agentscope/rag/_vdb/_vector_store.py101-125 src/agentscope/rag/_vdb/_vector_store.py68-77
Backends implement idempotent writes by associating vectors with deterministic IDs or managing document-level deletions.
ElasticsearchStore uses a _record_id helper to generate deterministic IDs based on content src/agentscope/rag/_vdb/_elasticsearch.py135QdrantStore uses upsert logic to overwrite existing points src/agentscope/rag/_vdb/_qdrant.py206-215MilvusLiteStore performs a delete followed by insert if records already exist for a document src/agentscope/rag/_vdb/_milvus_lite.py218-228Filtering is handled via the metadata_filter argument in the search method. Each backend translates this dictionary into its native query language:
filter field of the $vectorSearch stage src/agentscope/rag/_vdb/_mongodb.py240-255term or match filters within the knn query src/agentscope/rag/_vdb/_elasticsearch.py193-195expr parameter for boolean expressions src/agentscope/rag/_vdb/_milvus_lite.py270-285Different backends use different similarity metrics (e.g., Cosine, IP, L2).
MilvusLiteStore allows configuring metric_type (COSINE, IP, L2) src/agentscope/rag/_vdb/_milvus_lite.py48ElasticsearchStore defaults to cosine src/agentscope/rag/_vdb/_elasticsearch.py102MongoDBStore supports cosine, euclidean, and dotProduct src/agentscope/rag/_vdb/_mongodb.py69To keep the core package lightweight, vector store dependencies are optional and must be installed via extras:
Sources: pyproject.toml103-110 examples/rag/README.md28-52 examples/rag/README.md118-125
Refresh this wiki