> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Milvus

> Using Milvus as a vector database provider

## Overview

Milvus is an open-source vector database built for scalable similarity search and AI applications. It supports embedded (Lite), local, and cloud deployments with advanced indexing options and consistency levels.

**Provider Class:** `MilvusProvider`\
**Config Class:** `MilvusConfig`

## Install

<Note>
  Install the Milvus optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[milvus]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import MilvusProvider, MilvusConfig, ConnectionConfig, Mode, HNSWIndexConfig

# Setup embedding provider
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())

# Embedded mode (Milvus Lite)
config = MilvusConfig(
    collection_name="my_collection",
    vector_size=1536,
    connection=ConnectionConfig(mode=Mode.EMBEDDED, db_path="./milvus_db"),
    index=HNSWIndexConfig(m=16, ef_construction=200),
    consistency_level="Bounded",
    hybrid_search_enabled=False  # Milvus Lite requires use_sparse_vectors=True for hybrid search
)
vectordb = MilvusProvider(config)

# Create knowledge base
kb = KnowledgeBase(
    sources="document.pdf",
    embedding_provider=embedding,
    vectordb=vectordb
)

# Use with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
    description="Search the knowledge base",
    context=[kb]
)
result = agent.do(task)
```

## Parameters

### Base Parameters (from BaseVectorDBConfig)

| Parameter                      | Type                                         | Description                                              | Default                | Required |
| ------------------------------ | -------------------------------------------- | -------------------------------------------------------- | ---------------------- | -------- |
| `collection_name`              | `str`                                        | Name of the collection                                   | `"default_collection"` | No       |
| `vector_size`                  | `int`                                        | Dimension of vectors                                     | -                      | **Yes**  |
| `distance_metric`              | `DistanceMetric`                             | Similarity metric (`COSINE`, `EUCLIDEAN`, `DOT_PRODUCT`) | `COSINE`               | No       |
| `recreate_if_exists`           | `bool`                                       | Recreate collection if it exists                         | `False`                | No       |
| `default_top_k`                | `int`                                        | Default number of results                                | `10`                   | No       |
| `default_similarity_threshold` | `Optional[float]`                            | Minimum similarity score (0.0-1.0)                       | `None`                 | No       |
| `dense_search_enabled`         | `bool`                                       | Enable dense vector search                               | `True`                 | No       |
| `full_text_search_enabled`     | `bool`                                       | Enable full-text search                                  | `True`                 | No       |
| `hybrid_search_enabled`        | `bool`                                       | Enable hybrid search                                     | `True`                 | No       |
| `default_hybrid_alpha`         | `float`                                      | Default alpha for hybrid search (0.0-1.0)                | `0.5`                  | No       |
| `default_fusion_method`        | `Literal['rrf', 'weighted']`                 | Default fusion method for hybrid search                  | `'weighted'`           | No       |
| `provider_name`                | `Optional[str]`                              | Provider name                                            | `None`                 | No       |
| `provider_description`         | `Optional[str]`                              | Provider description                                     | `None`                 | No       |
| `provider_id`                  | `Optional[str]`                              | Provider ID                                              | `None`                 | No       |
| `default_metadata`             | `Optional[Dict[str, Any]]`                   | Default metadata for all records                         | `None`                 | No       |
| `indexed_fields`               | `Optional[List[Union[str, Dict[str, Any]]]]` | Fields to index for filtering                            | `None`                 | No       |

### Milvus-Specific Parameters

| Parameter             | Type                                                    | Description                                                                       | Default             | Required |
| --------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------- | -------- |
| `connection`          | `ConnectionConfig`                                      | Connection configuration (mode, db\_path, etc.)                                   | -                   | **Yes**  |
| `index`               | `IndexConfig`                                           | Index type configuration (`HNSWIndexConfig`, `IVFIndexConfig`, `FlatIndexConfig`) | `HNSWIndexConfig()` | No       |
| `consistency_level`   | `Literal['Strong', 'Bounded', 'Session', 'Eventually']` | Consistency level                                                                 | `'Bounded'`         | No       |
| `index_params`        | `Optional[Dict[str, Any]]`                              | Additional index parameters (overrides automatic params)                          | `None`              | No       |
| `use_sparse_vectors`  | `bool`                                                  | Enable sparse vector support (auto-enables `hybrid_search_enabled`)               | `False`             | No       |
| `dense_vector_field`  | `str`                                                   | Dense vector field name                                                           | `"dense_vector"`    | No       |
| `sparse_vector_field` | `str`                                                   | Sparse vector field name                                                          | `"sparse_vector"`   | No       |
| `search_params`       | `Optional[Dict[str, Any]]`                              | Default search parameters                                                         | `None`              | No       |
| `rrf_k`               | `int`                                                   | RRF ranker k parameter for hybrid search                                          | `60`                | No       |
| `batch_size`          | `int`                                                   | Batch size for upsert operations                                                  | `100`               | No       |

### ConnectionConfig Parameters

| Parameter     | Type                  | Description                                                 | Default | Required                |
| ------------- | --------------------- | ----------------------------------------------------------- | ------- | ----------------------- |
| `mode`        | `Mode`                | Connection mode (`EMBEDDED`, `LOCAL`, `CLOUD`, `IN_MEMORY`) | -       | **Yes**                 |
| `db_path`     | `Optional[str]`       | Path for embedded/local storage                             | `None`  | Required for `EMBEDDED` |
| `host`        | `Optional[str]`       | Host address                                                | `None`  | Required for `LOCAL`    |
| `port`        | `Optional[int]`       | Port number                                                 | `None`  | Required for `LOCAL`    |
| `api_key`     | `Optional[SecretStr]` | API key for cloud/local                                     | `None`  | Required for `CLOUD`    |
| `url`         | `Optional[str]`       | Full connection URL                                         | `None`  | No                      |
| `use_tls`     | `bool`                | Use TLS encryption                                          | `True`  | No                      |
| `grpc_port`   | `Optional[int]`       | gRPC port                                                   | `None`  | No                      |
| `prefer_grpc` | `bool`                | Prefer gRPC over HTTP                                       | `False` | No                      |
| `https`       | `Optional[bool]`      | Use HTTPS                                                   | `None`  | No                      |
| `prefix`      | `Optional[str]`       | URL path prefix                                             | `None`  | No                      |
| `timeout`     | `Optional[float]`     | Request timeout in seconds                                  | `None`  | No                      |
| `location`    | `Optional[str]`       | Special location string                                     | `None`  | No                      |