Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 268 additions & 0 deletions docs/docs/providers/vector_io/remote_mongodb.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,268 @@
---
description: |
[MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-vector-search) is a remote vector database provider for Llama Stack. It
uses MongoDB Atlas Vector Search to store and query vectors in the cloud.
That means you get enterprise-grade vector search with MongoDB's scalability and reliability.
## Features
- Cloud-native vector search with MongoDB Atlas
- Fully integrated with Llama Stack
- Enterprise-grade security and scalability
- Supports multiple search modes: vector, keyword, and hybrid search
- Built-in metadata filtering and text search capabilities
- Automatic index management
## Search Modes
MongoDB Atlas Vector Search supports three different search modes:
### Vector Search
Vector search uses MongoDB's `$vectorSearch` aggregation stage to perform semantic similarity search using embedding vectors.
```python
# Vector search example
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="What is machine learning?",
search_mode="vector",
max_num_results=5,
)
```
### Keyword Search
Keyword search uses MongoDB's text search capabilities with full-text indexes to find chunks containing specific terms.
```python
# Keyword search example
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="Python programming language",
search_mode="keyword",
max_num_results=5,
)
```
### Hybrid Search
Hybrid search combines both vector and keyword search methods using configurable reranking algorithms.
```python
# Hybrid search with RRF ranker (default)
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="neural networks in Python",
search_mode="hybrid",
max_num_results=5,
)
# Hybrid search with weighted ranker
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="neural networks in Python",
search_mode="hybrid",
max_num_results=5,
ranking_options={
"ranker": {
"type": "weighted",
"alpha": 0.7, # 70% vector search, 30% keyword search
}
},
)
```
## Usage
To use MongoDB Atlas in your Llama Stack project, follow these steps:
1. Create a MongoDB Atlas cluster with Vector Search enabled
2. Install the necessary dependencies
3. Configure your Llama Stack project to use MongoDB
4. Start storing and querying vectors
## Configuration
### Environment Variables
Set up the following environment variable for your MongoDB Atlas connection:
```bash
export MONGODB_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority&appName=llama-stack"
```
### Configuration Example
```yaml
vector_io:
- provider_id: mongodb_atlas
provider_type: remote::mongodb
config:
connection_string: "${env.MONGODB_CONNECTION_STRING}"
database_name: "llama_stack"
index_name: "vector_index"
similarity_metric: "cosine"
```
## Installation
You can install the MongoDB Python driver using pip:
```bash
pip install pymongo
```
## Documentation
See [MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/) for more details about MongoDB Atlas Vector Search.
For general MongoDB documentation, visit [MongoDB Documentation](https://docs.mongodb.com/).
sidebar_label: Remote - Mongodb
title: remote::mongodb
---

# remote::mongodb

## Description


[MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-vector-search) is a remote vector database provider for Llama Stack. It
uses MongoDB Atlas Vector Search to store and query vectors in the cloud.
That means you get enterprise-grade vector search with MongoDB's scalability and reliability.

## Features

- Cloud-native vector search with MongoDB Atlas
- Fully integrated with Llama Stack
- Enterprise-grade security and scalability
- Supports multiple search modes: vector, keyword, and hybrid search
- Built-in metadata filtering and text search capabilities
- Automatic index management

## Search Modes

MongoDB Atlas Vector Search supports three different search modes:

### Vector Search
Vector search uses MongoDB's `$vectorSearch` aggregation stage to perform semantic similarity search using embedding vectors.

```python
# Vector search example
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="What is machine learning?",
search_mode="vector",
max_num_results=5,
)
```

### Keyword Search
Keyword search uses MongoDB's text search capabilities with full-text indexes to find chunks containing specific terms.

```python
# Keyword search example
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="Python programming language",
search_mode="keyword",
max_num_results=5,
)
```

### Hybrid Search
Hybrid search combines both vector and keyword search methods using configurable reranking algorithms.

```python
# Hybrid search with RRF ranker (default)
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="neural networks in Python",
search_mode="hybrid",
max_num_results=5,
)

# Hybrid search with weighted ranker
search_response = client.vector_stores.search(
vector_store_id=vector_store.id,
query="neural networks in Python",
search_mode="hybrid",
max_num_results=5,
ranking_options={
"ranker": {
"type": "weighted",
"alpha": 0.7, # 70% vector search, 30% keyword search
}
},
)
```

## Usage
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think part of this readme is duplicated.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the # Usage and # Configuration sections are duplicated.


To use MongoDB Atlas in your Llama Stack project, follow these steps:

1. Create a MongoDB Atlas cluster with Vector Search enabled
2. Install the necessary dependencies
3. Configure your Llama Stack project to use MongoDB
4. Start storing and querying vectors

## Configuration

### Environment Variables
Set up the following environment variable for your MongoDB Atlas connection:

```bash
export MONGODB_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority&appName=llama-stack"
```

### Configuration Example

```yaml
vector_io:
- provider_id: mongodb_atlas
provider_type: remote::mongodb
config:
connection_string: "${env.MONGODB_CONNECTION_STRING}"
database_name: "llama_stack"
index_name: "vector_index"
similarity_metric: "cosine"
```
## Installation
You can install the MongoDB Python driver using pip:
```bash
pip install pymongo
```

## Documentation

See [MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/) for more details about MongoDB Atlas Vector Search.

For general MongoDB documentation, visit [MongoDB Documentation](https://docs.mongodb.com/).


## Configuration

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `connection_string` | `<class 'str'>` | No | | MongoDB Atlas connection string (e.g., mongodb+srv://user:pass@cluster.mongodb.net/) |
| `database_name` | `<class 'str'>` | No | llama_stack | Database name to use for vector collections |
| `index_name` | `<class 'str'>` | No | vector_index | Name of the vector search index |
| `path_field` | `<class 'str'>` | No | embedding | Field name for storing embeddings |
| `similarity_metric` | `<class 'str'>` | No | cosine | Similarity metric: cosine, euclidean, or dotProduct |
| `max_pool_size` | `<class 'int'>` | No | 100 | Maximum connection pool size |
| `timeout_ms` | `<class 'int'>` | No | 30000 | Connection timeout in milliseconds |
| `kvstore` | `utils.kvstore.config.RedisKVStoreConfig \| utils.kvstore.config.SqliteKVStoreConfig \| utils.kvstore.config.PostgresKVStoreConfig \| utils.kvstore.config.MongoDBKVStoreConfig` | No | sqlite | Config for KV store backend for metadata storage |

## Sample Configuration

```yaml
connection_string: ${env.MONGODB_CONNECTION_STRING:=}
database_name: ${env.MONGODB_DATABASE_NAME:=llama_stack}
index_name: ${env.MONGODB_INDEX_NAME:=vector_index}
path_field: ${env.MONGODB_PATH_FIELD:=embedding}
similarity_metric: ${env.MONGODB_SIMILARITY_METRIC:=cosine}
max_pool_size: ${env.MONGODB_MAX_POOL_SIZE:=100}
timeout_ms: ${env.MONGODB_TIMEOUT_MS:=30000}
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/dummy}/mongodb_registry.db
```
1 change: 1 addition & 0 deletions llama_stack/distributions/ci-tests/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ distribution_spec:
- provider_type: inline::milvus
- provider_type: remote::chromadb
- provider_type: remote::pgvector
- provider_type: remote::mongodb
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you need to also add an image that'll run MongoDB and expose the vector search functionality.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you'll need to add this to the ./github/workflows/integratino-vector-io.tests.yaml file like here: https://github.com/llamastack/llama-stack/blob/main/.github/workflows/integration-vector-io-tests.yml#L43

files:
- provider_type: inline::localfs
safety:
Expand Down
13 changes: 13 additions & 0 deletions llama_stack/distributions/ci-tests/run.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,19 @@ providers:
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ci-tests}/pgvector_registry.db
- provider_id: ${env.MONGODB_CONNECTION_STRING:+mongodb_atlas}
provider_type: remote::mongodb
config:
connection_string: ${env.MONGODB_CONNECTION_STRING:=}
database_name: ${env.MONGODB_DATABASE_NAME:=llama_stack}
index_name: ${env.MONGODB_INDEX_NAME:=vector_index}
path_field: ${env.MONGODB_PATH_FIELD:=embedding}
similarity_metric: ${env.MONGODB_SIMILARITY_METRIC:=cosine}
max_pool_size: ${env.MONGODB_MAX_POOL_SIZE:=100}
timeout_ms: ${env.MONGODB_TIMEOUT_MS:=30000}
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ci-tests}/mongodb_registry.db
files:
- provider_id: meta-reference-files
provider_type: inline::localfs
Expand Down
1 change: 1 addition & 0 deletions llama_stack/distributions/starter-gpu/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ distribution_spec:
- provider_type: inline::milvus
- provider_type: remote::chromadb
- provider_type: remote::pgvector
- provider_type: remote::mongodb
files:
- provider_type: inline::localfs
safety:
Expand Down
13 changes: 13 additions & 0 deletions llama_stack/distributions/starter-gpu/run.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,19 @@ providers:
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter-gpu}/pgvector_registry.db
- provider_id: ${env.MONGODB_CONNECTION_STRING:+mongodb_atlas}
provider_type: remote::mongodb
config:
connection_string: ${env.MONGODB_CONNECTION_STRING:=}
database_name: ${env.MONGODB_DATABASE_NAME:=llama_stack}
index_name: ${env.MONGODB_INDEX_NAME:=vector_index}
path_field: ${env.MONGODB_PATH_FIELD:=embedding}
similarity_metric: ${env.MONGODB_SIMILARITY_METRIC:=cosine}
max_pool_size: ${env.MONGODB_MAX_POOL_SIZE:=100}
timeout_ms: ${env.MONGODB_TIMEOUT_MS:=30000}
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter-gpu}/mongodb_registry.db
files:
- provider_id: meta-reference-files
provider_type: inline::localfs
Expand Down
1 change: 1 addition & 0 deletions llama_stack/distributions/starter/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ distribution_spec:
- provider_type: inline::milvus
- provider_type: remote::chromadb
- provider_type: remote::pgvector
- provider_type: remote::mongodb
files:
- provider_type: inline::localfs
safety:
Expand Down
13 changes: 13 additions & 0 deletions llama_stack/distributions/starter/run.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,19 @@ providers:
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter}/pgvector_registry.db
- provider_id: ${env.MONGODB_CONNECTION_STRING:+mongodb_atlas}
provider_type: remote::mongodb
config:
connection_string: ${env.MONGODB_CONNECTION_STRING:=}
database_name: ${env.MONGODB_DATABASE_NAME:=llama_stack}
index_name: ${env.MONGODB_INDEX_NAME:=vector_index}
path_field: ${env.MONGODB_PATH_FIELD:=embedding}
similarity_metric: ${env.MONGODB_SIMILARITY_METRIC:=cosine}
max_pool_size: ${env.MONGODB_MAX_POOL_SIZE:=100}
timeout_ms: ${env.MONGODB_TIMEOUT_MS:=30000}
kvstore:
type: sqlite
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/starter}/mongodb_registry.db
files:
- provider_id: meta-reference-files
provider_type: inline::localfs
Expand Down
19 changes: 19 additions & 0 deletions llama_stack/distributions/starter/starter.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@
)
from llama_stack.providers.registry.inference import available_providers
from llama_stack.providers.remote.vector_io.chroma.config import ChromaVectorIOConfig
from llama_stack.providers.remote.vector_io.mongodb.config import (
MongoDBVectorIOConfig,
)
from llama_stack.providers.remote.vector_io.pgvector.config import (
PGVectorVectorIOConfig,
)
Expand Down Expand Up @@ -113,6 +116,7 @@ def get_distribution_template(name: str = "starter") -> DistributionTemplate:
BuildProvider(provider_type="inline::milvus"),
BuildProvider(provider_type="remote::chromadb"),
BuildProvider(provider_type="remote::pgvector"),
BuildProvider(provider_type="remote::mongodb"),
],
"files": [BuildProvider(provider_type="inline::localfs")],
"safety": [
Expand Down Expand Up @@ -222,6 +226,13 @@ def get_distribution_template(name: str = "starter") -> DistributionTemplate:
password="${env.PGVECTOR_PASSWORD:=}",
),
),
Provider(
provider_id="${env.MONGODB_CONNECTION_STRING:+mongodb_atlas}",
provider_type="remote::mongodb",
config=MongoDBVectorIOConfig.sample_run_config(
f"~/.llama/distributions/{name}",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you probably want to add the other configuration parameters.

),
),
],
"files": [files_provider],
},
Expand Down Expand Up @@ -295,5 +306,13 @@ def get_distribution_template(name: str = "starter") -> DistributionTemplate:
"azure",
"Azure API Type",
),
"MONGODB_CONNECTION_STRING": (
"",
"MongoDB Atlas connection string (e.g., mongodb+srv://user:pass@cluster.mongodb.net/)",
),
"MONGODB_DATABASE_NAME": (
"llama_stack",
"MongoDB database name",
),
},
)
Loading
Loading