---
title: "Accelerate Topic Modeling with BERTopic — Instructions"
canonical: "https://build.nvidia.com/playbooks/topic-modeling/instructions.md"
---

# Step 1. Prepare the Hugging Face cache

Ensure the Hugging Face cache is writable so model downloads succeed on your hardware platform:

```bash
sudo chown -R $USER:$USER $HOME/.cache/huggingface 2>/dev/null || true
sudo chmod -R u+rwX $HOME/.cache/huggingface 2>/dev/null || true
mkdir -p $HOME/.cache/huggingface
```

If you see "Permission denied" when downloading models later, run the `chown`/`chmod` lines again for your user.

# Step 2. Install RAPIDS cuDF and cuML

Create a new conda environment with RAPIDS libraries for GPU-accelerated data processing:

```bash
conda create -n rapids-25.10 \
-c rapidsai -c conda-forge \
cudf=25.10 cuml=25.10 python=3.11 'cuda-version=13.0'
```

This installs cuDF (GPU DataFrame library) and cuML (GPU machine learning library) that provide drop-in acceleration for pandas and scikit-learn operations.

# Step 3. Activate the conda environment

```bash
conda activate rapids-25.10
```

# Step 4. Install machine learning packages

Install UMAP, HDBSCAN, BERTopic, and supporting libraries for topic modeling.
Note: `datamapplot` will upgrade dask/distributed — the next command pins them back.

```bash
python -m pip install \
transformers datasets sentence-transformers \
umap-learn hdbscan==0.8.40 bertopic matplotlib \
scikit-learn==1.4.2 datamapplot streamlit "nbformat>=4.2.0" ipykernel
```

Register the conda environment as a Jupyter kernel:

```bash
python -m ipykernel install --user --name rapids-25.10 --display-name "Python (rapids-25.10)"
```

Pin dask/distributed back to RAPIDS-compatible versions:

```bash
python -m pip install "dask==2025.9.1" "distributed==2025.9.1"
```

These packages provide:

- **dask**: Parallel computing library
- **distributed**: Distributed task scheduler for dask
- **sentence-transformers**: Generate text embeddings
- **umap-learn / hdbscan**: Dimensionality reduction and clustering (GPU-accelerated via cuML)
- **bertopic**: Topic modeling framework
- **datamapplot**: Document visualization
- **streamlit**: Interactive dashboard for the topic explorer app (`run_app.sh`)

> [!NOTE]
> Pip may report dependency conflicts (for example, dask/distributed downgraded, or cuml/rapids-dask-dependency). BERTopic and the notebook can still run. If you need cuML and RAPIDS dask together, keep the conda default dask versions and install only the BERTopic stack via pip in a separate environment; see **Troubleshooting**.

# Step 5. Install visualization packages

Install JupyterLab and visualization libraries directly into the conda environment:

```bash
python -m pip install jupyterlab ipywidgets jupyterlab-widgets bokeh colorcet datashader plotly
```

# Step 6. Install compatible PyTorch

Install PyTorch with CUDA 13.0 support for GPU-accelerated embedding generation:

```bash
python -m pip install torch==2.9.0 torchvision torchaudio==2.9.0 --index-url https://download.pytorch.org/whl/cu130
```

# Step 7. Clone the repository and download the dataset

Clone the playbook repository and download the Amazon Electronics Reviews dataset:

```bash
git clone https://github.com/NVIDIA/dgx-spark-playbooks
cd dgx-spark-playbooks/nvidia/playbook-topic-modeling/assets
```

Download the dataset (~14 GB compressed):

```bash
wget https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/raw/review_categories/Electronics.jsonl.gz
```

# Step 8. Pull Git LFS files (notebooks)

The notebook files are stored in Git LFS — without this step, JupyterLab will throw a `NotJSONError` when trying to open them.

```bash
conda install -c conda-forge git-lfs
git lfs install
git lfs pull
```

# Step 9. Launch JupyterLab

Start JupyterLab from the assets directory:

```bash
jupyter lab
```

> [!NOTE]
> JupyterLab refuses to start as the root user and exits immediately with `Running as root is not recommended. Use --allow-root to bypass.` This happens, for example, when you enter WSL2 with `wsl -d Ubuntu-24.04 -u root`. Run the playbook as a regular (non-root) user, which is recommended. If you must stay as root, start JupyterLab with `jupyter lab --allow-root`.

Open a browser to the URL JupyterLab prints (typically `http://localhost:8888`). From another device, use `http://<HARDWARE_IP>:8888` where `<HARDWARE_IP>` is your hardware platform's reachable address.

If you access the hardware platform over SSH, forward the Jupyter port to your local browser:

```bash
ssh -N -L YYYY:localhost:XXXX username@remote_host
```

- `YYYY`: The local port you want to use (for example, 8888)
- `XXXX`: The port JupyterLab is listening on on the remote machine (for example, 8888)
- `-N`: Prevents SSH from executing a remote command
- `-L`: Specifies local port forwarding

# Step 10. Select the rapids-25.10 kernel

In JupyterLab, open the notebook `video_notebook_for_GPU_Accelerated_Machine_Learning_BERTopic_1M.ipynb`.

Select the **Python (rapids-25.10)** kernel from the kernel selector in the top right corner of the notebook interface.

# Step 11. Execute all cells

Run all cells in the notebook sequentially. The notebook will:

1. **Load data with cuDF**: GPU-accelerated pandas via `%load_ext cudf.pandas`
2. **Preprocess text**: Clean and normalize review text
3. **Generate embeddings**: Create sentence embeddings
4. **Enable GPU acceleration**: Load cuML accelerators via `%load_ext cuml.accel`
5. **Run BERTopic**: Cluster documents into topics using GPU-accelerated UMAP and HDBSCAN
6. **Visualize results**: Generate interactive topic visualizations

# Step 12. Explore the results

After the notebook completes, you'll have:

- **Topic information table**: Discovered topics with keywords and document counts
- **Topic visualization**: Interactive 2D map of topic relationships
- **Barchart**: Top keywords for each topic
- **Heatmap**: Topic similarity matrix
- **Document datamap**: Visual clustering of documents by topic

# (Optional) Launch the interactive dashboard

As an alternative to the notebook, run the Streamlit dashboard for live UMAP/HDBSCAN tuning. From the assets directory (with the dataset already downloaded in Step 7):

```bash
chmod +x run_app.sh
./run_app.sh
```

Then open the URL it prints (default `http://localhost:8501`). The script auto-selects the `rapids-25.10` conda env; override with `PYTHON=/path/to/python ./run_app.sh` if needed.

# Step 13. Cleanup (optional)

Remove the conda environment when finished:

```bash
conda deactivate
conda env remove -n rapids-25.10
```

Remove the downloaded dataset:

```bash
rm Electronics.jsonl.gz
```

Remove generated embedding files and the cloned playbook directory if you no longer need them:

```bash
# Optional: remove Hugging Face cache (embedding cache from the notebook)
rm -rf ~/.cache/huggingface

# From the parent of dgx-spark-playbooks/, remove the cloned repo
rm -rf dgx-spark-playbooks/
```

# Step 14. Next steps

Apply this workflow to your own datasets:

1. **Adjust data size**: Modify the `nrows` parameter when loading data to process smaller subsets
2. **Tune clustering**: Experiment with `min_cluster_size` and `min_samples` in HDBSCAN
3. **Try different embedding models**: Swap `all-MiniLM-L6-v2` for domain-specific models
4. **Export topics**: Save the topic model using `topic_model.save()` for later analysis
5. **Monitor GPU usage**: Run `nvidia-smi -l 1` to watch GPU utilization during processing