{"slug": "clustering-unstructured-text-with-llm-embeddings-and-hdbscan", "title": "Clustering Unstructured Text with LLM Embeddings and HDBSCAN", "summary": "A new tutorial demonstrates how to build a text clustering pipeline using large language model embeddings and the HDBSCAN algorithm to automatically discover topics in unlabeled text data. The pipeline leverages sentence-transformers for embedding generation, UMAP for dimensionality reduction, and HDBSCAN for clustering, enabling unsupervised topic discovery without prior labeling.", "body_md": "In this article, you will learn how to build a text clustering pipeline by combining large language model embeddings with HDBSCAN, a density-based clustering algorithm, to automatically discover topics in unlabeled text data.\n\nTopics we will cover include:\n\n- How to generate text embeddings for raw documents using a pre-trained sentence-transformers model.\n- How to reduce the dimensionality of those embeddings with UMAP to prepare them for clustering.\n- How to apply HDBSCAN to automatically discover topic clusters and visualize the results.\n\n## Introduction\n\nThe current era of **Generative AI** seems to primarily focus on chat interfaces and prompts, but the range of applications of **large language models**, or LLMs for short, is not limited to just that. Indeed, one of their most powerful downstream abilities consists of turning raw, messy, unstructured text into semantically rich mathematical representations called **embeddings**. Once that’s done, we can use these text representations for a variety of machine learning use cases, with clustering being no exception.\n\nIn particular, embeddings can be combined with advanced, density-based **clustering techniques** like **HDBSCAN**, allowing as a result for the discovery of hidden topics, patterns, or categories in your collection of text documents: all without the need for prior labeling.\n\nThis article shows how to construct a text-based clustering pipeline from scratch. We will use a freely available dataset containing text instances, as well as an open-source LLM that has been trained for generating embeddings — i.e. a so-called embedding model. The icing on the cake: we’ll use free and handy, modern Python libraries providing implementations of clustering algorithms like HDBSCAN.\n\n## Step-by-Step Walkthrough\n\nFirst, let’s start by installing the key Python libraries we will need:\n\n**Sentence transformers**, to load a pre-trained LLM for embedding generation from Hugging Face — you’ll need a Hugging Face API key, also called an[access token](https://huggingface.co/docs/hub/security-tokens), to be able to load the model.**Umap-learn**, to apply an algorithm to reduce the dimensionality of embeddings.\n\nLikewise, if you are working on a local IDE instead of a cloud notebook environment and don’t have **scikit-learn** and **pandas**, you may need to install them too.\n\n```\n!pip install sentence-transformers umap-learn \n\n1\n\n!pip install sentence-transformers umap-learn\n```\n\nNow we start the coding part by getting some fresh data. The `fetch_20newsgroups`\n\nfunction, which fetches a dataset containing texts from categorized news articles, will do. Note that even though the dataset contains labels, we will omit them, as we are pretending not to know this information for the sake of clustering these data instances into groups based on similarity. Also, we sample down the dataset to 150 instances, which will be representative enough for our example.\n\n``` python\nimport pandas as pd\nfrom sklearn.datasets import fetch_20newsgroups\n\n# Fetching a highly targeted subset of data (~150-200 docs)\ncategories = ['sci.space', 'sci.med', 'rec.autos']\nnewsgroups = fetch_20newsgroups(subset='train', categories=categories, remove=('headers', 'footers', 'quotes'))\n\n# Sampling down into a representative, illustrative subset\ndf = pd.DataFrame({'text': newsgroups.data, 'true_label': newsgroups.target})\ndf = df[df['text'].str.strip().str.len() > 100].sample(150, random_state=42).reset_index(drop=True)\n\nprint(f\"Loaded {len(df)} text documents.\")\nprint(\"\\nSample document:\")\nprint(df['text'].iloc[0][:150] + \"...\")\n\n1234567891011121314\n\nimport pandas as pdfrom sklearn.datasets import fetch_20newsgroups # Fetching a highly targeted subset of data (~150-200 docs)categories = ['sci.space', 'sci.med', 'rec.autos']newsgroups = fetch_20newsgroups(subset='train', categories=categories, remove=('headers', 'footers', 'quotes')) # Sampling down into a representative, illustrative subsetdf = pd.DataFrame({'text': newsgroups.data, 'true_label': newsgroups.target})df = df[df['text'].str.strip().str.len() > 100].sample(150, random_state=42).reset_index(drop=True) print(f\"Loaded {len(df)} text documents.\")print(\"\\nSample document:\")print(df['text'].iloc[0][:150] + \"...\")\n```\n\nOutput:\n\n```\nLoaded 150 text documents.\n\nSample document:\n\nOkay Mr. Dyer, we're properly impressed with your philosophical skills and\nability to insult people. You're a wonderful speaker and an adept politic...\n\n123456\n\nLoaded 150 text documents. Sample document: Okay Mr. Dyer, we're properly impressed with your philosophical skills andability to insult people. You're a wonderful speaker and an adept politic...\n```\n\nThe next step is to obtain the embeddings from raw texts. To do this, we load `all-MiniLM-L6-v2`\n\nfrom Hugging Face’s sentence-transformers library. This is a lightweight yet effective model to obtain embeddings quickly.\n\n``` python\nfrom sentence_transformers import SentenceTransformer\n\n# Loading the free, open-source model\nmodel = SentenceTransformer('all-MiniLM-L6-v2')\n\n# Encoding text documents into dense vector embeddings\nprint(\"Generating embeddings...\")\nembeddings = model.encode(df['text'].tolist(), show_progress_bar=True)\n\nprint(f\"Embedding matrix shape: {embeddings.shape}\")\n\n12345678910\n\nfrom sentence_transformers import SentenceTransformer # Loading the free, open-source modelmodel = SentenceTransformer('all-MiniLM-L6-v2') # Encoding text documents into dense vector embeddingsprint(\"Generating embeddings...\")embeddings = model.encode(df['text'].tolist(), show_progress_bar=True) print(f\"Embedding matrix shape: {embeddings.shape}\")\n```\n\nSince the embedding dimension is originally too high for clustering purposes, we now apply a dimensionality reduction technique by using the UMAP algorithm from the namesake library installed earlier:\n\n``` python\nimport umap\n\n# Reducing embedding dimensions to 5, to retain enough density information for clustering\nreducer = umap.UMAP(n_neighbors=15, n_components=5, min_dist=0.0, random_state=42)\nreduced_embeddings = reducer.fit_transform(embeddings)\n\nprint(f\"Reduced matrix shape: {reduced_embeddings.shape}\")\n\n1234567\n\nimport umap # Reducing embedding dimensions to 5, to retain enough density information for clusteringreducer = umap.UMAP(n_neighbors=15, n_components=5, min_dist=0.0, random_state=42)reduced_embeddings = reducer.fit_transform(embeddings) print(f\"Reduced matrix shape: {reduced_embeddings.shape}\")\n```\n\nNow our numerical embedding vectors associated with news articles consist of five dimensions (attributes) only. Let’s see if this compact representation is meaningful enough to obtain insightful clustering by applying the HDBSCAN algorithm, which is a density-based clustering approach:\n\n``` python\nfrom sklearn.cluster import HDBSCAN\n\n# Initializing HDBSCAN\n# min_cluster_size=8: we specified that each cluster must have at least 8 documents\nclusterer = HDBSCAN(min_cluster_size=8, min_samples=3, store_centers='centroid')\ndf['cluster'] = clusterer.fit_predict(reduced_embeddings)\n\n# Counting instances per cluster\ncluster_counts = df['cluster'].value_counts()\nprint(\"\\nCluster Distribution:\")\nprint(cluster_counts)\n\n1234567891011\n\nfrom sklearn.cluster import HDBSCAN # Initializing HDBSCAN# min_cluster_size=8: we specified that each cluster must have at least 8 documentsclusterer = HDBSCAN(min_cluster_size=8, min_samples=3, store_centers='centroid')df['cluster'] = clusterer.fit_predict(reduced_embeddings) # Counting instances per clustercluster_counts = df['cluster'].value_counts()print(\"\\nCluster Distribution:\")print(cluster_counts)\n```\n\n**Important**: the clustering results are partly influenced by the hyperparameter settings we defined for HDBSCAN. I recommend you try out other configurations for the minimum cluster size and other hyperparameters to explore how this affects results.\n\nResult:\n\n```\nCluster Distribution:\ncluster\n0    101\n1     49\nName: count, dtype: int64\n\n12345\n\nCluster Distribution:cluster0    1011     49Name: count, dtype: int64\n```\n\nIt looks like HDBSCAN detected two clusters associated with high-density regions in the data space. Would there also be noisy points that were not allocated to either of these two clusters? Let’s check:\n\n```\nfor cluster_id in sorted(df['cluster'].unique()):\n    if cluster_id == -1:\n        print(\"\\n=== CLUSTER: NOISE / UNCLASSIFIED ===\")\n    else:\n        print(f\"\\n=== CLUSTER: Discovered Topic #{cluster_id} ===\")\n        \n    # Getting up to 3 sample texts from this cluster\n    samples = df[df['cluster'] == cluster_id]['text'].head(3).tolist()\n    for i, sample in enumerate(samples, 1):\n        clean_sample = \" \".join(sample.split())[:120]\n        print(f\"  {i}. {clean_sample}...\")\n\n1234567891011\n\nfor cluster_id in sorted(df['cluster'].unique()):    if cluster_id == -1:        print(\"\\n=== CLUSTER: NOISE / UNCLASSIFIED ===\")    else:        print(f\"\\n=== CLUSTER: Discovered Topic #{cluster_id} ===\")            # Getting up to 3 sample texts from this cluster    samples = df[df['cluster'] == cluster_id]['text'].head(3).tolist()    for i, sample in enumerate(samples, 1):        clean_sample = \" \".join(sample.split())[:120]        print(f\"  {i}. {clean_sample}...\")\n```\n\nOutput:\n\n```\n=== CLUSTER: Discovered Topic #0 ===\n  1. Okay Mr. Dyer, we're properly impressed with your philosophical skills and ability to insult people. You're a wonderful ...\n  2. I was at an interesting seminar at work (UK's R.A.L. Space Science Dept.) on this subject, specifically on a small-scale...\n  3. This is the second post which seems to be blurring the distinction between real disease caused by Candida albicans and t...\n\n=== CLUSTER: Discovered Topic #1 ===\n  1. It's great that all these other cars can out-handle, out-corner, and out- accelerate an Integra. But, you've got to ask ...\n  2. l diamond star cars (Talon/Eclipse/Laser) put out 190 hp in the turbo models, and 195 hp in the AWD turbo models, These ...\n  3. Sorry for the mis-spelling, but I forgot how to spell it after my series of exams and NO-on hand reference here. Is it s...\n\n123456789\n\n=== CLUSTER: Discovered Topic #0 ===  1. Okay Mr. Dyer, we're properly impressed with your philosophical skills and ability to insult people. You're a wonderful ...  2. I was at an interesting seminar at work (UK's R.A.L. Space Science Dept.) on this subject, specifically on a small-scale...  3. This is the second post which seems to be blurring the distinction between real disease caused by Candida albicans and t... === CLUSTER: Discovered Topic #1 ===  1. It's great that all these other cars can out-handle, out-corner, and out- accelerate an Integra. But, you've got to ask ...  2. l diamond star cars (Talon/Eclipse/Laser) put out 190 hp in the turbo models, and 195 hp in the AWD turbo models, These ...  3. Sorry for the mis-spelling, but I forgot how to spell it after my series of exams and NO-on hand reference here. Is it s...\n```\n\nSeems like all data points in the sample of 150 were allocated to either one of the two clusters identified, thus hinting at the clue that the news articles might easily separable according to topic.\n\nFor extra insight, we can show some cluster visualizations with the aid of the supplementary code provided below, which shows a scatterplot for every pairwise combination of the five existing components that describe each data point:\n\n``` python\nimport matplotlib.pyplot as plt\nimport seaborn as sns\nimport itertools\n\n# Creating a DataFrame for the 5 reduced embeddings and cluster labels\nreduced_df = pd.DataFrame(reduced_embeddings, columns=[f'UMAP_D{i+1}' for i in range(reduced_embeddings.shape[1])])\nreduced_df['cluster'] = df['cluster']\n\n# Getting all unique pairwise combinations of the 5 dimensions\ndim_pairs = list(itertools.combinations(reduced_df.columns[:-1], 2))\n\nnum_plots = len(dim_pairs)\nnum_cols = 3\nnum_rows = (num_plots + num_cols - 1) // num_cols\n\nplt.figure(figsize=(num_cols * 5, num_rows * 4))\n\nfor i, (dim1, dim2) in enumerate(dim_pairs):\n    plt.subplot(num_rows, num_cols, i + 1)\n    sns.scatterplot(\n        x=dim1,\n        y=dim2,\n        hue='cluster',\n        data=reduced_df,\n        palette='viridis',\n        s=70,\n        alpha=0.7,\n        legend='full'\n    )\n    plt.title(f'{dim1} vs {dim2}')\n    plt.xlabel(dim1)\n    plt.ylabel(dim2)\n    plt.grid(True, linestyle='--', alpha=0.6)\n\nplt.tight_layout()\nplt.show()\n\n123456789101112131415161718192021222324252627282930313233343536\n\nimport matplotlib.pyplot as pltimport seaborn as snsimport itertools # Creating a DataFrame for the 5 reduced embeddings and cluster labelsreduced_df = pd.DataFrame(reduced_embeddings, columns=[f'UMAP_D{i+1}' for i in range(reduced_embeddings.shape[1])])reduced_df['cluster'] = df['cluster'] # Getting all unique pairwise combinations of the 5 dimensionsdim_pairs = list(itertools.combinations(reduced_df.columns[:-1], 2)) num_plots = len(dim_pairs)num_cols = 3num_rows = (num_plots + num_cols - 1) // num_cols plt.figure(figsize=(num_cols * 5, num_rows * 4)) for i, (dim1, dim2) in enumerate(dim_pairs):    plt.subplot(num_rows, num_cols, i + 1)    sns.scatterplot(        x=dim1,        y=dim2,        hue='cluster',        data=reduced_df,        palette='viridis',        s=70,        alpha=0.7,        legend='full'    )    plt.title(f'{dim1} vs {dim2}')    plt.xlabel(dim1)    plt.ylabel(dim2)    plt.grid(True, linestyle='--', alpha=0.6) plt.tight_layout()plt.show()\n```\n\nResult:\n\nBy trying different configurations for HDBSCAN, you may come across results in which the number of identified clusters could be different from two. Just give it a try!\n\n## Wrapping Up\n\nOnce we have gone through the process of building the text-based clustering pipeline, it is worth concluding by pointing out the key reasons why putting together LLM embeddings with HDBSCAN is worth it. These include the ability to retain and capture, to some extent, the true semantic meaning and linguistic nuances of the original text, thanks to the properties inherent to embeddings obtained through sentence-transformers. Moreover, HDBSCAN automatically determines an optimal number of clusters and is able to detect outlying points that might be noise or outliers that would distort group-level statistics.", "url": "https://wpnews.pro/news/clustering-unstructured-text-with-llm-embeddings-and-hdbscan", "canonical_source": "https://machinelearningmastery.com/clustering-unstructured-text-with-llm-embeddings-and-hdbscan/", "published_at": "2026-06-23 12:00:57+00:00", "updated_at": "2026-07-07 18:02:43.271630+00:00", "lang": "en", "topics": ["large-language-models", "machine-learning", "natural-language-processing", "ai-tools", "developer-tools"], "entities": ["HDBSCAN", "UMAP", "sentence-transformers", "Hugging Face", "scikit-learn", "pandas", "fetch_20newsgroups", "Python"], "alternates": {"html": "https://wpnews.pro/news/clustering-unstructured-text-with-llm-embeddings-and-hdbscan", "markdown": "https://wpnews.pro/news/clustering-unstructured-text-with-llm-embeddings-and-hdbscan.md", "text": "https://wpnews.pro/news/clustering-unstructured-text-with-llm-embeddings-and-hdbscan.txt", "jsonld": "https://wpnews.pro/news/clustering-unstructured-text-with-llm-embeddings-and-hdbscan.jsonld"}}