{
  "doc_id": "string",
  "source": "wiki|api|issue_tracker|code_comment",
  "domain": "string",
  "version": "string",
  "language": "string",
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "tags": ["string"],
  "access_level": "public|internal|restricted",
  "parent_doc_id": "string|null"
}

import re
import tiktoken

def chunk_with_boundaries(text: str, max_tokens: int = 512, overlap: int = 64) -> list[str]:
    enc = tiktoken.get_encoding("cl100k_base")
    # Split on structural boundaries: headings, code fences, list items, paragraphs
    boundaries = re.split(r'(?m)^(#{1,6}\s|```|[-*]\s|\n{2,})', text)
    chunks = []
    current = ""
    current_tokens = 0

    for segment in boundaries:
        seg_tokens = len(enc.encode(segment))
        if current_tokens + seg_tokens > max_tokens and current:
            chunks.append(current.strip())
            # Retain overlap for context continuity
            overlap_tokens = enc.encode(current)[-overlap:]
            current = enc.decode(overlap_tokens)
            current_tokens = len(overlap_tokens)
        current += segment
        current_tokens += seg_tokens

    if current.strip():
        chunks.append(cu

rrent.strip()) return chunks

This approach preserves markdown structure, keeps code blocks intact, and maintains semantic overlap. Adjust `max_tokens` based on your embedding model's context window and downstream LLM constraints.

### Step 3: Embedding & Vectorization

Use a domain-tuned embedding model. General-purpose models underperform on technical syntax, API signatures, and architecture terminology. Fine-tune or select a model trained on code, documentation, and technical corpora:

```python
from sentence_transformers import SentenceTransformer
import numpy as np

model = SentenceTransformer("nomic-ai/nomic-embed-text-v1.5")

def generate_embeddings(chunks: list[str]) -> np.ndarray:
    return model.encode(chunks, normalize_embeddings=True, show_progress_bar=False)

Normalize embeddings to unit length. This enables cosine similarity to function as a dot product, simplifying downstream vector search and improving numerical stability.

Step 4: Hybrid Index Construction

Dense vectors capture semantic meaning. Sparse vectors (BM25/TF-IDF) capture exact terminology and keyword matching. Combine both for robust retrieval:

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PayloadSchemaType

client = QdrantClient(":memory:")

# Dense vector collection
client.create_collection(
    collection_name="kb_dense",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE)
)

# Sparse vector collection (using Qdrant's native sparse support or external indexer)
client.create_collection(
    collection_name="kb_hybrid",
    vectors_config={
        "dense": VectorParams(size=768, distance=Distance.COSINE),
        "sparse": VectorParams(size=0, distance=Distance.DOT)  # Sparse handled via plugin
    }
)

# Attach metadata payloads for filtering
client.create_payload_index(
    collection_name="kb_dense",
    field_name="domain",
    field_schema=PayloadSchemaType.KEYWORD
)

Hybrid indexing requires query-time fusion. Implement weighted reranking or reciprocal rank fusion (RRF) to merge dense and sparse results:

def reciprocal_rank_fusion(dense_results: list, sparse_results: list, k: int = 60) -> list:
    fused_scores = {}
    for doc_id in [r["id"] for r in dense_results + sparse_results]:
        dense_rank = next((i for i, r in enumerate(dense_results) if r["id"] == doc_id), -1)
        sparse_rank = next((i for i, r in enumerate(sparse_results) if r["id"] == doc_id), -1)
        score = 0
        if dense_rank >= 0: score += 1 / (k + dense_rank + 1)
        if sparse_rank >= 0: score += 1 / (k + sparse_rank + 1)
        fused_scores[doc_id] = score
    return sorted(fused_scores.items(), key=lambda x: x[1], reverse=True)

Step 5: Incremental Updates & TTL

Static indexes decay. Implement event-driven incremental updates with document versioning and time-to-live (TTL) policies:

• Write Path: Git hooks or CI/CD pipelines trigger indexing jobs on PR merge.
• Versioning: Store updated_at and version in metadata. Use optimistic concurrency control to prevent race conditions during concurrent updates.
• TTL & Archival: Soft-delete documents older than a configurable threshold. Archive superseded versions instead of hard deletion to preserve audit trails.
• Reindex Strategy: Use shadow indexing. Build new indexes in parallel, validate against evaluation harness, then swap traffic via blue-green deployment.

Pitfall Guide

1. Fixed-Size Token Chunking Without Boundary Awareness
   Splits code blocks, fractures markdown tables, and severs semantic context. Always respect structural delimiters.

2. Metadata Siloing
   Storing metadata separately from vectors forces expensive joins at query time. Attach payloads directly to vector records or use co-located document stores.

3. Embedding Model Drift
   Models degrade as terminology evolves. Schedule quarterly re-embedding jobs and track similarity distribution shifts using KL divergence or cosine histogram analysis.

4. Ignoring Query Distribution
   Indexing without analyzing actual query patterns leads to over-indexing low-value content. Profile query logs to prioritize high-frequency domains and adjust chunking weights accordingly.

5. Stale Index Poisoning
   Outdated documentation remains retrievable, causing AI hallucination and developer confusion. Enforce TTL policies, version gating, and soft-deletion with archival.

6. Over-Reliance on Dense Vectors Alone
   Dense embeddings struggle with exact API names, error codes, and version strings. Always pair with sparse/BM25 indexing for technical precision.

7. Lack of Evaluation Harness
   Deploying indexes without automated retrieval testing guarantees regression. Implement MRR@K, Recall@K, and NDCG@K benchmarks in CI/CD. Validate against a curated query-document relevance set.

Production Bundle

Action Checklist

• Define strict metadata schema with versioning, domain, and access controls
• Implement boundary-aware semantic chunking with configurable overlap
• Select and validate a domain-tuned embedding model
• Construct hybrid index with dense + sparse vector support
• Implement reciprocal rank fusion or weighted reranking at query time
• Deploy event-driven incremental updates triggered by CI/CD pipelines
• Enforce TTL policies and soft-deletion with archival retention
• Integrate automated retrieval evaluation (MRR, Recall@K) into CI/CD

Decision Matrix

Strategy	Scalability	Complexity	Best For	Latency Profile
BM25 Keyword	High	Low	Exact-match, compliance-heavy docs	<20ms
Naive RAG Chunking	Medium	Medium	Prototyping, small teams	80–120ms
Semantic Chunking	High	Medium-High	Technical docs, API references	90–130ms
Hybrid Multi-Vector	Very High	High	Enterprise KBs, AI-augmented workflows	100–150ms
Graph-Enhanced Index	Medium	Very High	Cross-referenced architecture, dependency mapping	150–300ms

Configuration Template

# indexing_pipeline.yaml
pipeline:
  name: "kb_hybrid_indexer"
  version: "1.2.0"
  concurrency: 8
  batch_size: 256

chunking:
  strategy: "boundary_aware"
  max_tokens: 512
  overlap_tokens: 64
  preserve_code_fences: true
  preserve_tables: true

embedding:
  model: "nomic-ai/nomic-embed-text-v1.5"
  normalize: true
  batch_inference: true
  cache_path: "./embeddings_cache"

metadata:
  schema_path: "./schemas/kb_metadata.json"
  enforce_required_fields: true
  attach_to_vectors: true
  indexing_fields: ["domain", "version", "access_level"]

storage:
  provider: "qdrant"
  collection_prefix: "kb_prod"
  vector_dim: 768
  distance_metric: "cosine"
  sparse_plugin: "bm25_native"
  payload_indexing: true

update_policy:
  trigger: "ci_cd_webhook"
  incremental: true
  ttl_days: 90
  soft_delete: true
  archive_bucket: "s3://kb-archive/"

evaluation:
  harness: "ragas"
  metrics: ["mrr_at_10", "recall_at_5", "ndcg_at_5"]
  threshold_mrr: 0.65
  fail_on_regression: true

Quick Start Guide

1. Initialize Schema & Chunker
   Define your metadata schema, enforce required fields, and deploy the boundary-aware chunker. Validate against a sample set of markdown, code, and API docs.

2. Embed & Vectorize
   Load your domain-tuned embedding model, run batch inference on chunks, and normalize outputs. Cache embeddings to avoid redundant computation during iteration.

3. Build Hybrid Index
   Provision dense and sparse vector collections. Attach metadata payloads. Configure payload indexes for filtering. Run initial bulk ingestion.

4. Deploy Query Fusion & CI/CD Hooks
   Implement reciprocal rank fusion at query time. Wire CI/CD webhooks to trigger incremental updates. Integrate retrieval evaluation metrics into your pipeline. Monitor MRR@10 and recall thresholds. Swap to production only after validation passes.

Knowledge base indexing is not a configuration toggle. It is a data engineering discipline that demands schema rigor, semantic chunking, hybrid retrieval, and continuous evaluation. Teams that treat indexing as a first-class pipeline outperform those that treat it as an afterthought. The precision delta compounds across every query, every AI interaction, and every developer hour saved. Build it intentionally.