---
title: "Topic Modeling — Instructions"
canonical: "https://build.nvidia.com/station/topic-modeling/instructions.md"
---

# Step 1. (DGX Station) Hugging Face cache permissions

On DGX Station, ensure the Hugging Face cache is writable so model downloads succeed:

```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 with your username (e.g. `nvidia`).

# 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 step 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
```

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 (e.g. dask/distributed downgraded, cuml/rapids-dask-dependency). BERTopic and the notebook can still run. If you need cuML and RAPIDS dask together, consider keeping the conda default dask versions and installing only the BERTopic stack via pip in a separate env; see **Troubleshooting**.

# Step 5. Install visualization packages

Install JupyterLab and visualization libraries for interactive topic exploration.

```bash
conda install -c conda-forge \
notebook=7.5.0 \
jupyterlab=4.5.0 \
ipywidgets=8.1.8 \
jupyterlab-widgets=3.0.16 \
bokeh=3.8.1 \
colorcet=3.1.0 \
datashader=0.18.2 \
plotly=6.5.0
```

If conda reports `PackagesNotFoundError` for `jupyterlab-widgets` (e.g. on some platforms), install it with pip:

```bash
python -m pip install jupyterlab-widgets
```

# 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 --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/station-topic-modeling/assets
```

Download the dataset (~14GB 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
```

# (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
./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 10. Select the rapids-25.10 kernel

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

Select the **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

# 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/
```

# Next steps

Apply this workflow to your own datasets:

1. **Adjust data size**: Modify `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