NVIDIA / NVIDIA/cuvs

[BUG] CagraQ: compression_kmeans_trainset_fraction defaults ignore compression_max_trainpoints and silently change k-means sample size

Open
#1,777 0 comments 0 reactions 1 assignee View on GitHub

@lowener is already working on this.

Since Feb 6, 2026.

bug
Dominant language
Cuda
Stars
854
Forks
236
Avg merge
3d 3h
Merged PRs (30d)
62

Description

When running a CagraQ graph index build, if compression parameters compression_vq_kmeans_trainset_fraction and compression_pq_kmeans_trainset_fraction are not set explicitly, they get assigned the default heuristic values of 0.1 and 0.256 even if compression_max_train_points_per_pq_code and compression_max_train_points_per_vq_cluster are set. This leads to silent change of the number of points used in the k-means clustering step.

Output of an inserted RAFT_LOG_INFO:

[I] [10:59:54.770644] Using the dataset file '<your_path>/datasets/laion_1M/base.1M.fbin'
2026-02-06T10:59:54+00:00
Running <your_path>/repos/cuvs_private/cpp/build_dev/bench/ann/CUVS_CAGRA_ANN_BENCH
Run on (224 X 800 MHz CPU s)
CPU Caches:
  L1 Data 48 KiB (x112)
  L1 Instruction 32 KiB (x112)
  L2 Unified 2048 KiB (x112)
  L3 Unified 307200 KiB (x2)
Load Average: 1.40, 1.08, 4.05
command_line: <your_path>/repos/cuvs_private/cpp/build_dev/bench/ann/CUVS_CAGRA_ANN_BENCH --build --force --data_prefix=<your_path>/datasets/ --benchmark_out_format=csv --benchmark_out=res_build_test.csv --benchmark_counters_tabular=true --override_kv=dataset_memory_type:"device" --override_kv=compression_max_train_points_per_pq_code:2000 --override_kv=compression_max_train_points_per_vq_cluster:300 <your_path>/repos/vdb_bench/laion_1M_cagraq.json
dataset: laion_1M
dim: 768
distance: euclidean
gpu_driver_version: 13.0
gpu_gpuDirectRDMASupported: 1
gpu_hostNativeAtomicSupported: 0
gpu_mem_bus_width: 7680
gpu_mem_freq: 3996000000.000000
gpu_mem_global_size: 191503138816
gpu_mem_shared_size: 233472
gpu_name: NVIDIA B200
gpu_pageableMemoryAccess: 1
gpu_pageableMemoryAccessUsesHostPageTables: 0
gpu_runtime_version: 12.9
gpu_sm_count: 148
gpu_sm_freq: 1965000000.000000
host_cores_used: 14
host_cpu_freq_max: 4000000000
host_cpu_freq_min: 800000000
host_pagesize: 4096
host_processors_sysconf: 224
host_processors_used: 28
host_total_ram_size: 2164173484032
host_total_swap_size: 0
n_records: 1000000
[I] [10:59:54.792983] Overwriting file: index/laion_1M/cagra/q.ibin
[   507][10:59:59:191751][info  ] train_vq: vq_kmeans_trainset_fraction=0.100000, max_train_points_per_vq_cluster=300, vq_n_centers=1000, n_rows=1000000, n_rows_train=100000
[   507][10:59:59:363883][info  ] train_pq: pq_kmeans_trainset_fraction=0.256000, max_train_points_per_pq_code=2000, pq_n_centers=256, n_rows=1000000, n_rows_train=256000

Currently need to explicitly add

        "compression_vq_kmeans_trainset_fraction": 1.0,
        "compression_pq_kmeans_trainset_fraction": 1.0

to the config json.

Reason: fill_missing_params_heuristics function doesn't check if max_train_points are set.

To reproduce: run e.g. this config

{
  "dataset": {
    "name": "laion_1M",
    "base_file": "laion_1M/base.1M.fbin",
    "subset_size": 1000000,
    "query_file": "laion_1M/queries.fbin",
    "groundtruth_neighbors_file": "laion_1M/groundtruth.1M.neighbors.ibin",
    "distance": "euclidean",
    "memory_type": "device"
  },
  "search_basic_param": {
    "batch_size": 10000,
    "k": 10
  },
  "index": [
    {
      "name": "cuvs_cagra_q",
      "algo": "cuvs_cagra",
      "build_param": { 
        "graph_degree": 64,
        "intermediate_graph_degree": 96,
        "graph_build_algo": "IVF_PQ",
        "ivf_pq_build_pq_dim": 128,
        "ivf_pq_build_pq_bits": 8,
        "ivf_pq_build_nlist": 1000,
        "ivf_pq_build_niter": 10,
        "ivf_pq_build_ratio": 10,
        "ivf_pq_search_nprobe": 5,
        "ivf_pq_search_internalDistanceDtype": "half",
        "ivf_pq_search_smemLutDtype": "half",
        "ivf_pq_search_refine_ratio": 1,
        "compression_pq_dim": 192,
        "compression_pq_bits": 8,
        "compression_use_vq": true,
        "compression_max_train_points_per_pq_code": 300,
        "compression_max_train_points_per_vq_cluster": 300
      },
      "file": "laion_1M/cagra/q.ibin",
      "search_params": [
        {"itopk": 64, "search_width": 2, "max_iterations": 8, "refine_ratio": 1}
      ]
    }
  ]
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.