An index configuration defines an index's identity, embedding space, document chunking, and optional metadata contract. The name identifies the index; embedding model and dimensions are fixed at creation because changing them invalidates stored vectors and can corrupt comparisons. section 5.2.2
Configure the ingestion and retrieval boundaries explicitly:
- Set chunking_strategy, chunk_size, and chunk_overlap once for consistent document ingestion; different strategies suit different content types. section 5.3.5
- Use metadata_schema to reject inconsistent keys during ingestion instead of silently losing filtered results later. section 5.2.2
- Resolve the configuration before searching so the query uses the same embedding model as the indexed chunks. section 5.4.4
Changing embedding models safely
Create a second index with the new embedding model, re-ingest the documents, validate retrieval queries, then switch traffic after validation. Retain the original index as a rollback option. section 5.2.2
Listing 5.1 Index configuration dataclass
@dataclass
class IndexConfig:
name: str #A
embedding_model: str =
➥"text-embedding-3-small" #B
embedding_dimensions: int = 1536 #B
chunking_strategy: str = "fixed" #C
chunk_size: int = 512 #C
chunk_overlap: int = 50 #C
metadata_schema: Optional[Dict] = None #DInspect the Python dataclass that groups index identity, embedding, chunking, and metadata settings. section 5.2.2

