CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-dev-langchain4j--langchain4j-milvus

Milvus embedding store integration for LangChain4j

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration Reference

Complete configuration options for MilvusEmbeddingStore.

Connection Configurations

Local Milvus

MilvusEmbeddingStore.builder()
    .host(String host)              // default: "localhost"
    .port(Integer port)             // default: 19530
    .username(String username)      // optional
    .password(String password)      // optional
    .databaseName(String database)  // optional, default: null
    .collectionName(String name)    // default: "default"
    .dimension(Integer dim)         // required for new collections
    .build();

Example:

MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
    .host("192.168.1.100")
    .port(19530)
    .username("admin")
    .password("password")
    .collectionName("embeddings")
    .dimension(384)
    .build();

Zilliz Cloud (Managed Milvus)

MilvusEmbeddingStore.builder()
    .uri(String uri)          // Zilliz Cloud endpoint
    .token(String token)      // API key
    .collectionName(String name)
    .dimension(Integer dim)
    .build();

Example:

MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
    .uri("https://xxx.api.gcp-us-west1.zillizcloud.com")
    .token(System.getenv("ZILLIZ_API_KEY"))
    .collectionName("prod_embeddings")
    .dimension(1536)
    .build();

Custom Milvus Client

import io.milvus.client.MilvusServiceClient;
import io.milvus.param.ConnectParam;

ConnectParam connectParam = ConnectParam.newBuilder()
    .withHost("localhost")
    .withPort(19530)
    .withAuthorization("", "")
    .build();

MilvusServiceClient client = new MilvusServiceClient(connectParam);

MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
    .milvusClient(client)
    .collectionName("my_collection")
    .dimension(384)
    .build();

Collection Configuration

Basic Collection Settings

.collectionName(String name)    // Collection name, default: "default"
.dimension(Integer dimension)   // Vector dimension, REQUIRED for new collections

Note: Collection is auto-created if it doesn't exist.

Index Types

import io.milvus.param.IndexType;

.indexType(IndexType.FLAT)      // Exact search (brute force), default
.indexType(IndexType.IVF_FLAT)  // Inverted file, balanced
.indexType(IndexType.IVF_SQ8)   // IVF with scalar quantization
.indexType(IndexType.IVF_PQ)    // IVF with product quantization
.indexType(IndexType.HNSW)      // Hierarchical NSW graph, fast
.indexType(IndexType.DISKANN)   // Disk-based, very large datasets

Selection Guide:

  • FLAT: < 10K vectors, need exact results
  • IVF_FLAT: 10K-1M vectors, balanced
  • HNSW: Need fast queries, have memory
  • IVF_PQ: Large datasets, limited memory
  • DISKANN: > 10M vectors

Metric Types

import io.milvus.param.MetricType;

.metricType(MetricType.COSINE)  // Cosine similarity [0,1], default
.metricType(MetricType.L2)      // Euclidean distance, lower=similar
.metricType(MetricType.IP)      // Inner product, higher=similar

Selection Guide:

  • COSINE: Normalized embeddings, text similarity
  • L2: Non-normalized, absolute distances matter
  • IP: Normalized embeddings, faster than COSINE

Consistency Levels

import io.milvus.common.clientenum.ConsistencyLevelEnum;

.consistencyLevel(ConsistencyLevelEnum.EVENTUALLY)  // default, fastest
.consistencyLevel(ConsistencyLevelEnum.BOUNDED)     // bounded staleness
.consistencyLevel(ConsistencyLevelEnum.SESSION)     // per-session guarantees
.consistencyLevel(ConsistencyLevelEnum.STRONG)      // immediate visibility

Trade-offs:

  • EVENTUALLY: Best performance, eventual visibility
  • BOUNDED: Balanced, configurable lag
  • SESSION: Session-level consistency
  • STRONG: Immediate visibility, highest latency

Requirements:

  • Complex filter deletions require BOUNDED
  • Real-time search requires STRONG

Index Parameters

import java.util.Map;

.extraParameters(Map<String, Object> params)

HNSW Parameters:

.extraParameters(Map.of(
    "efConstruction", 200,  // Build-time effort (64-512)
    "m", 16                 // Connections per node (4-64)
))

IVF Parameters:

.extraParameters(Map.of(
    "nlist", 1024          // Number of clusters (1-65536)
))

IVF_PQ Parameters:

.extraParameters(Map.of(
    "m", 8,                // Subquantizers (1-65536)
    "nlist", 1024          // Number of clusters
))

Field Names

Customize schema field names:

.idFieldName(String name)        // default: "id"
.textFieldName(String name)      // default: "text"
.metadataFieldName(String name)  // default: "metadata"
.vectorFieldName(String name)    // default: "vector"

Example:

MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
    .host("localhost")
    .collectionName("custom_schema")
    .dimension(384)
    .idFieldName("doc_id")
    .textFieldName("content")
    .metadataFieldName("properties")
    .vectorFieldName("embedding")
    .build();

Behavior Options

Auto-Flush on Insert

.autoFlushOnInsert(Boolean enabled)  // default: false
  • false (default): Better batch performance
  • true: Immediate persistence, slower

When to enable: Single-insert workflows requiring immediate durability

Retrieve Embeddings on Search

.retrieveEmbeddingsOnSearch(Boolean enabled)  // default: false
  • false (default): Faster search
  • true: Returns embedding vectors in results, requires extra query

When to enable: Need embedding vectors for post-processing

Configuration Patterns

Development

MilvusEmbeddingStore.builder()
    .host("localhost")
    .port(19530)
    .collectionName("dev_embeddings")
    .dimension(384)
    .build();

Production - High Performance

import io.milvus.param.IndexType;
import io.milvus.param.MetricType;
import io.milvus.common.clientenum.ConsistencyLevelEnum;

MilvusEmbeddingStore.builder()
    .uri(System.getenv("MILVUS_URI"))
    .token(System.getenv("MILVUS_TOKEN"))
    .collectionName("prod_fast")
    .dimension(768)
    .indexType(IndexType.HNSW)
    .metricType(MetricType.COSINE)
    .consistencyLevel(ConsistencyLevelEnum.EVENTUALLY)
    .extraParameters(Map.of("efConstruction", 512, "m", 32))
    .autoFlushOnInsert(false)
    .retrieveEmbeddingsOnSearch(false)
    .build();

Production - Strong Consistency

MilvusEmbeddingStore.builder()
    .uri(System.getenv("MILVUS_URI"))
    .token(System.getenv("MILVUS_TOKEN"))
    .collectionName("prod_realtime")
    .dimension(1536)
    .indexType(IndexType.IVF_FLAT)
    .consistencyLevel(ConsistencyLevelEnum.STRONG)
    .build();

Large Scale - Memory Efficient

MilvusEmbeddingStore.builder()
    .host("milvus-cluster")
    .collectionName("large_scale")
    .dimension(768)
    .indexType(IndexType.IVF_PQ)
    .metricType(MetricType.COSINE)
    .extraParameters(Map.of("m", 8, "nlist", 2048))
    .build();

Multi-Tenant Setup

MilvusEmbeddingStore.builder()
    .host("localhost")
    .databaseName("tenant_db_123")
    .collectionName("embeddings")
    .dimension(384)
    .build();

Configuration Validation

Required Parameters:

  • dimension - MUST be set when creating new collection
  • Connection info - Either (host/port) OR (uri/token) OR (milvusClient)

Optional Parameters: All other settings have defaults

Validation at build():

  • Throws exception if required parameters missing
  • Creates collection if it doesn't exist

Environment-Based Configuration

MilvusEmbeddingStore createStore(String env) {
    MilvusEmbeddingStore.Builder builder = MilvusEmbeddingStore.builder()
        .collectionName("embeddings_" + env)
        .dimension(384);
    
    if ("production".equals(env)) {
        return builder
            .uri(System.getenv("PROD_MILVUS_URI"))
            .token(System.getenv("PROD_MILVUS_TOKEN"))
            .indexType(IndexType.HNSW)
            .consistencyLevel(ConsistencyLevelEnum.STRONG)
            .build();
    } else {
        return builder
            .host("localhost")
            .port(19530)
            .build();
    }
}

Configuration Errors

Common Issues:

  1. Missing dimension:

    Exception: dimension must be set for new collection

    Fix: Add .dimension(384) or appropriate value

  2. Connection failed:

    Exception: Failed to connect to Milvus

    Fix: Verify host/port or uri/token

  3. Dimension mismatch:

    Exception: Embedding dimension doesn't match collection

    Fix: Ensure embeddings match configured dimension

  4. Invalid index parameters:

    Exception: Invalid index parameter

    Fix: Check extraParameters values for chosen index type

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-milvus

docs

advanced.md

api-reference.md

configuration.md

index.md

patterns.md

quickstart.md

troubleshooting.md

tile.json