Semantic Map

What is the Semantic Map

The Semantic Map uses machine learning to analyze all the content in your knowledge base and organize it visually. Each dot on the map represents a piece of your content (a "chunk"), and dots that are close together share similar meaning.

The map helps you answer questions like:

• What topics does my AI know about?

• Are any topics underrepresented?

• Is my content well-organized or scattered?

Embeddings Representation

When you upload documents, each chunk is converted into a high-dimensional vector (an "embedding") that captures its semantic meaning. Chunks with similar meaning have similar vectors, even if they use different words.

Dimensionality Reduction

The map displays content in 2D, but embeddings exist in much higher dimensions. We use UMAP (Uniform Manifold Approximation and Projection) to project these high-dimensional vectors onto a 2D plane while preserving the relationships between them.

• Points close together in the original space remain close in 2D

• Points far apart remain separated

• The resulting layout reveals natural groupings in your content

Clustering

Once projected to 2D, we use HDBSCAN (Hierarchical Density-Based Spatial Clustering) to automatically detect topic clusters. Unlike traditional clustering algorithms:

• It doesn't require you to specify how many topics to find

• It identifies "noise" (content that doesn't belong to any clear topic)

• It handles clusters of varying sizes and densities

Topic Labeling

Each detected cluster is analyzed to generate a human-readable topic label. The system examines representative content from each cluster and produces a 2-4 word descriptive name (e.g., "Shipping & Returns", "Product Specifications").

Primary Stats

Clustered vs. Unclustered:

• High clustered % (>90%) = Well-organized content with clear topics

• High unclustered % (>20%) = Scattered content, consider reorganizing

Silhouette Score

Range: -1 to +1

The Silhouette Score measures how similar each chunk is to its own cluster compared to other clusters. It evaluates both cohesion (how tightly grouped points are within a cluster) and separation (how distinct clusters are from each other).

Mathematical intuition: For each point, the score compares its average distance to points in its own cluster versus the nearest neighboring cluster. A high score means points are much closer to their own cluster.

Calinski-Harabasz Index

Range: 0 to ∞ (higher is better)

Also known as the Variance Ratio Criterion, this metric measures the ratio of between-cluster dispersion to within-cluster dispersion.

Mathematical intuition: Compares how spread out clusters are from each other versus how spread out points are within each cluster. Well-defined clusters are tight internally but far apart from each other.

Note: This score is not normalized, so it's most useful for comparing different analyses of the same dataset rather than as an absolute measure.

Davies-Bouldin Index

Range: 0 to ∞ (lower is better)

This metric measures the average similarity between each cluster and its most similar neighboring cluster.

Mathematical intuition: For each cluster, finds the neighboring cluster it's most similar to, then averages across all clusters. Lower scores indicate clusters that are compact and well-separated.

Quality Assesment

The overall Quality rating combines these metrics into a single assessment:

Diagnostics

The Semantic Map provides four diagnostic analyses:

Severity indicators:

• Green: No issues detected

• Blue: Minor observation

• Yellow: Moderate concern worth addressing

• Red: Significant issue affecting chatbot quality

Advance Settings

For fine-tuning the analysis, you can adjust clustering parameters:

When to adjust:

Results

Healthy Knowledge Base Signs:

• 5–15 topics (varies by use case)

• >90% clustered content

• Silhouette score >0.5

• Balanced topic sizes (no single topic dominates)

• All diagnostics green or blue

Warning Signs:

Quick Reference