Problem
CAGRA can tune IVF-PQ parameters (n_lists, pq_dim, n_probes, etc.) from dataset size and dimension — see ivf_pq_params and the Java copy in getCuVSIvfPqParams().
If a user sets only a few knobs (e.g. n_lists and pq_bits in a sweep), they expect the rest to be filled by those heuristics. That works with Strategy.HEURISTIC (≥ 5M vectors). It does not work with Strategy.CUSTOM, which is what you get when explicitly configuring IVF_PQ — unset fields fall back to fixed Builder defaults like n_lists=1024 and kmeans_trainset_fraction=0.5, regardless of dataset size.
Native code already does the right thing — heuristic baseline, then overlay only supplied fields (cagra.cpp) — but Java passes every field, clobbering the baseline. Only pq_dim=0 gets a partial escape hatch via calculate_pq_dim.
Expected
explicit value > dataset heuristic > static default
Per parameter. Match native behavior: baseline from ivf_pq_params(dataset), overlay only what the caller set.
Example
10M × 1536d — user sets only n_lists=5000, pq_bits=4:
| Param |
Should be |
Today |
kmeans_n_iters |
10 |
20 |
kmeans_trainset_fraction |
~0.1 |
0.5 |
n_probes |
~8 |
20 |
| search dtypes |
fp16 |
fp32 |
(pq_dim accidentally works via 0 → calculate_pq_dim; other fields don't.)
Fix
- Track explicitly set IVF-PQ keys.
- Baseline =
getCuVSIvfPqParams(N, D); overlay explicit keys only.
Problem
CAGRA can tune IVF-PQ parameters (
n_lists,pq_dim,n_probes, etc.) from dataset size and dimension — seeivf_pq_paramsand the Java copy ingetCuVSIvfPqParams().If a user sets only a few knobs (e.g.
n_listsandpq_bitsin a sweep), they expect the rest to be filled by those heuristics. That works withStrategy.HEURISTIC(≥ 5M vectors). It does not work withStrategy.CUSTOM, which is what you get when explicitly configuringIVF_PQ— unset fields fall back to fixedBuilderdefaults liken_lists=1024andkmeans_trainset_fraction=0.5, regardless of dataset size.Native code already does the right thing — heuristic baseline, then overlay only supplied fields (
cagra.cpp) — but Java passes every field, clobbering the baseline. Onlypq_dim=0gets a partial escape hatch viacalculate_pq_dim.Expected
Per parameter. Match native behavior: baseline from
ivf_pq_params(dataset), overlay only what the caller set.Example
10M × 1536d — user sets only
n_lists=5000,pq_bits=4:kmeans_n_iterskmeans_trainset_fractionn_probes(
pq_dimaccidentally works via0→calculate_pq_dim; other fields don't.)Fix
getCuVSIvfPqParams(N, D); overlay explicit keys only.