Skip to content

README_CLUSTERING.md

Latest commit

 

History

History
118 lines (85 loc) · 3.43 KB

README_CLUSTERING.md

File metadata and controls

118 lines (85 loc) · 3.43 KB
Raw

Keyword Clustering Tool

Een Python-applicatie die zoekwoorden automatisch semantisch clustert met behulp van AI embeddings via de OpenAI API.

Features

  • Embeddings generatie: Gebruikt OpenAI's text-embedding-3-small of text-embedding-3-large modellen
  • Flexibele clustering: Keuze tussen K-means (met automatische cluster detectie) of HDBSCAN
  • Automatische labels: Genereert beschrijvende labels voor elk cluster
  • CSV/Excel support: Leest en schrijft zowel CSV als Excel bestanden
  • Uitgebreide logging: Duidelijke voortgang en foutmeldingen
  • Robuuste foutafhandeling: Proper error handling voor API calls en file operations

Installatie

  1. Installeer dependencies:
pip install -r requirements.txt
  1. Configureer OpenAI API key:
cp .env.example .env
# Bewerk .env en voeg je OpenAI API key toe

Gebruik

Basis gebruik

python cluster_keywords.py input.csv output.csv

Met opties

# Gebruik HDBSCAN in plaats van K-means
python cluster_keywords.py input.csv output.csv --method hdbscan

# Specificeer aantal clusters voor K-means
python cluster_keywords.py input.csv output.csv --clusters 10

# Gebruik groter embedding model
python cluster_keywords.py input.csv output.csv --model text-embedding-3-large

# Verbose logging
python cluster_keywords.py input.csv output.csv --verbose

Beschikbare opties

--method {kmeans,hdbscan}    Clustering methode (default: kmeans)
--clusters N                 Aantal clusters voor K-means (automatisch bepaald indien niet opgegeven)
--min-cluster-size N         Minimale cluster grootte voor HDBSCAN (default: 5)
--model {text-embedding-3-small,text-embedding-3-large}
                            OpenAI embedding model (default: text-embedding-3-small)
--batch-size N              Batch grootte voor API calls (default: 100)
--verbose, -v               Verbose logging

Input formaat

Het input bestand (CSV of Excel) moet minimaal een kolom query bevatten:

query,clicks,impressions
nike schoenen,150,2000
adidas sneakers,120,1800
pizza amsterdam,95,1500

Andere kolommen (zoals clicks en impressions) worden automatisch meegenomen in het output bestand.

Output formaat

Het output bestand bevat de originele data plus:

  • cluster_id: Numerieke cluster identifier
  • cluster_label: Beschrijvende label van het cluster
query,cluster_id,cluster_label,clicks,impressions
nike schoenen,0,"nike schoenen, adidas sneakers, puma hardloopschoenen",150,2000
adidas sneakers,0,"nike schoenen, adidas sneakers, puma hardloopschoenen",120,1800
pizza amsterdam,1,"pizza amsterdam, italiaans restaurant",95,1500

Voorbeeld

Een voorbeeld bestand is meegeleverd:

python cluster_keywords.py example_keywords.csv results.csv

K-means vs HDBSCAN

K-means

  • Voordeel: Sneller, voorspelbaar aantal clusters
  • Nadeel: Moet aantal clusters vooraf weten (of laten berekenen)
  • Gebruik: Wanneer je een specifiek aantal thema's wilt

HDBSCAN

  • Voordeel: Vindt automatisch aantal clusters, detecteert noise
  • Nadeel: Langzamer, sommige keywords kunnen als "noise" worden gelabeld
  • Gebruik: Voor exploratie en wanneer je niet weet hoeveel clusters er zijn

Cost indicatie

OpenAI embedding costs (text-embedding-3-small):

  • ~$0.02 per 1 miljoen tokens
  • Gemiddeld keyword = ~5 tokens
  • 1000 keywords ≈ 5000 tokens ≈ $0.0001

Licentie

Dit is een tool gebouwd voor intern gebruik.