Skip to content
Version: 1.0.0 Last Updated: 2026-05-14 Status: Active

bast-ai-milvus

Version: 0.1.4 Module: bast_ai_milvus Path: src/python/milvus

Overview

Milvus vector database integration library providing collection management, vector operations, and similarity search for Bast AI services.

Features

Collection Management

  • Create/drop collections
  • Index management (HNSW, IVF_FLAT, etc.)
  • Schema definition
  • Partition support

Vector Operations

  • Insert vectors with metadata
  • Batch insert support
  • Update vectors
  • Delete vectors
  • k-NN search
  • Range search
  • Hybrid search (vector + filter)
  • Multiple distance metrics (L2, IP, COSINE)

Dependencies

Internal Dependencies

Package Purpose
bast-ai-config Configuration management

External Dependencies

Package Version Purpose
pymilvus 2.5.13 Milvus Python SDK

Usage Examples

Collection Creation

from bast_ai_milvus import MilvusService

milvus = MilvusService(catname="mycat")

# Create collection with schema
milvus.create_collection(
    collection_name="documents",
    dimension=1536,
    metric_type="L2",
    index_type="HNSW",
    index_params={"M": 16, "efConstruction": 200}
)

Insert Vectors

# Single insert
milvus.insert(
    collection_name="documents",
    vectors=[embedding],
    metadata=[{"doc_id": "123", "title": "My Document"}]
)

# Batch insert
vectors = [embed1, embed2, embed3]
metadata = [
    {"doc_id": "1", "title": "Doc 1"},
    {"doc_id": "2", "title": "Doc 2"},
    {"doc_id": "3", "title": "Doc 3"}
]
milvus.insert_batch(
    collection_name="documents",
    vectors=vectors,
    metadata=metadata
)

Similarity Search

# Basic search
results = milvus.search(
    collection_name="documents",
    query_vector=query_embedding,
    top_k=10
)

for result in results:
    print(f"ID: {result['id']}, Score: {result['score']}")
    print(f"Metadata: {result['metadata']}")

Hybrid Search (Vector + Filter)

# Search with filter
results = milvus.search(
    collection_name="documents",
    query_vector=query_embedding,
    top_k=10,
    filter_expr='category == "tutorial"'
)

Collection Statistics

stats = milvus.get_collection_stats("documents")
print(f"Total vectors: {stats['row_count']}")
print(f"Index type: {stats['index_type']}")

Configuration

# resources/config/{catname}.yaml
milvus:
  host: ${MILVUS_HOST:localhost}
  port: ${MILVUS_PORT:19530}
  user: ${MILVUS_USER:}
  password: ${MILVUS_PASSWORD:}

  collections:
    documents:
      dimension: 1536
      metric_type: L2
      index_type: HNSW
      index_params:
        M: 16
        efConstruction: 200

Index Types

Index Best For Notes
HNSW General purpose Good balance of speed/recall
IVF_FLAT High recall needed Slower but more accurate
IVF_SQ8 Large datasets Compressed, good balance
FLAT Small datasets Brute force, exact results

Testing

Unit Tests (1 file)

  • test_svc_api.py - Service API tests

Running Tests

pants test src/python/milvus:: -- -s --no-header

Issues & Improvements

Current Issues

  1. Connection management: Single connection, no pooling
  2. Limited batch control: Large batches can timeout
  3. No async support: Synchronous operations only

Suggested Improvements

  1. Connection pooling: Add connection pool support
  2. Async operations: Add async search/insert
  3. Batch optimization: Smart batching for large inserts
  4. Index recommendations: Auto-suggest best index
  5. Collection migration: Version collection schemas

Changelog

v0.1.4 (Current)

  • Updated pymilvus to 2.5.13
  • Improved HNSW index support

v0.1.3

  • Added hybrid search support
  • Better error handling