feat: wire up GPU_HNSW / GPU_HNSW_SQ index types

[devin-ai-integration]

Summary

Wire up the GPU_HNSW / GPU_HNSW_SQ index types in Milvus: load-time override_index_type swap (HNSW/HNSW_SQ → GPU_HNSW) across the load, hot-load, and querycoord paths; GPU resource accounting/routing; and create-time param validation. Depends on 6si/knowhere gpu-hnsw-faiss (pinned via KNOWHERE_VERSION; repin to a tagged release before production merge).

Core wiring:

• segment_loader.go / services.go / querycoordv2/task/executor.go — apply the override_index_type swap before resource estimation and index load.
• gpuIndexRequiresGpu returns true for GPU_HNSW/GPU_HNSW_SQ → pre-load VRAM check runs and the collection is flagged for GPU scheduling.

Data types — native FP32/FP16/BF16/INT8: GPU_HNSW/GPU_HNSW_SQ now accept fp16/bf16 in addition to fp32/int8. This is entirely feature-flag driven — no Go logic change. Knowhere advertises feature::FP16|GPU / feature::BF16|GPU for both types (see 6si/knowhere#2), and Milvus reads those bits via cgo:

// vecindexmgr: Float16Flag=1<<2, BFloat16Flag=1<<3 match knowhere feature::FP16/BF16
C.GetIndexFeatures(...)  // populates mgr.features[GPU_HNSW]
// -> IsDataTypeSupport(GPU_HNSW, Float16Vector/BFloat16Vector) now true
//    -> checker.CheckValidDataType accepts them

The only change is reverting the earlier gpu_hnsw_checker_test.go expectation (fp16/bf16 were temporarily marked invalid when knowhere was fp32/int8-only); both are now expected valid. The python param specs (idx_gpu_hnsw.py / idx_gpu_hnsw_sq.py) already list FLOAT16_VECTOR/BFLOAT16_VECTOR.

Param checker (review fix #4): newGpuHnswChecker() was defined but never registered, and GetChecker() short-circuits any vec-index to the unified vecIndexChecker (whose knowhere ValidateIndexParams is a no-op for GPU_HNSW), so M/efConstruction validation never ran. Now:

// GetChecker: prefer the dedicated checker for these two types
switch indexType {
case IndexGpuHnsw, IndexGpuHnswSQ:
    if c, ok := mgr.checkers[indexType]; ok { return c, nil }
}
// ...then the unified vec-index short-circuit

registerIndexChecker() registers newGpuHnswChecker() for both types. The 3 checker tests that silently returned (reported PASS) when GetChecker yielded nil now t.Skip honestly on non-GPU builds, plus a pure-Go routing test asserts GetChecker resolves to *gpuHnswChecker.

Design doc (review fixes #3, #5 + native fp16/bf16):

• Removed the stale internal/datacoord/meta.go claim — normalizePositionTimestamp is upstream and meta.go is not in this PR; GPU_HNSW just inherits the upstream compaction behavior.
• Filtered search — now supported (CPU parity). GPU_HNSW/GPU_HNSW_SQ apply the delete/TTL/partition BitsetView on the GPU (filtered rows excluded from results but kept as graph waypoints; brute-force fallback at high filter ratios), validated at CPU-HNSW parity. The design docs (20260619-gpu-hnsw.md key-limitation banner + Failure Modes row) are flipped from "not supported / returns invalid_args" to "supported", the 20260711-gpu-hnsw-ocq-removal.md reject decision is marked superseded by 20260718-gpu-hnsw-filtered-search.md, and delete-then-query integration tests were added (TestGpuHnswFilteredSearch / TestGpuHnswSQFilteredSearch in tests/python_client/testcases/indexes/test_gpu_hnsw{,_sq}.py): insert → flush(seal) → GPU index → delete a PK range → assert deleted rows absent from search+query, live rows present, no invalid_args, across L2/IP/COSINE.
• Documented native 2-byte fp16/bf16 device storage (up-converted to fp32 in the kernel) and recorded the GPU_HNSW_SQ-alias, filtered-search, checker, and native-FP16/BF16 decisions in docs/design-docs/design_docs/20260711-gpu-hnsw-ocq-removal.md.

GPU_HNSW_SQ (review fix #2): the type Milvus exposes now has a real Knowhere backend (alias of GPU_HNSW; see 6si/knowhere#2) instead of hitting no impl.

Verification: not build-verified locally (no Go/CUDA build in this session); CI / the GPU build confirm compilation. The Test_gpuHnswChecker_CheckValidDataType fp16/bf16 assertions require the linked core to include the updated knowhere registrations (the next GPU build). GPU-runtime validation of native fp16/bf16 is covered by the GPU unit/recall gates and the sealed-segment cluster e2e (see Performance below).

Performance (CPU-HNSW vs GPU)

Benchmarked on the same dataset and harness (collection mpd_v2, 569.9M rows, INT8 COSINE; run_eval_jobs.py, --sample-size 2048 --continuous-iterations 30). Best cell = batch 512, 8 parallel × 4 workers (32 concurrency):

Cluster	Nodes	Throughput	p50 latency	R@1
GPU HNSW (g7e.2xlarge)	8	28,087 vec/s	518 ms	0.897
CPU HNSW (r8g.2xlarge Graviton)	32	4,365 vec/s	3,683 ms	0.889
CPU HNSW (r8g.2xlarge Graviton)	10	1,509 vec/s	9,178 ms	0.891

• GPU on 8 nodes ≈ 6.4× the throughput of CPU on 32 nodes and ≈ 18.6× the 10-node CPU cluster, at ~7× lower p50 latency.
• Peak GPU throughput = 30,913 vec/s (batch 256, 8 parallel × 1 worker; p50 62 ms, R@1 0.897).
• Recall parity throughout: R@1 ≈ 0.889–0.900 on both CPU and GPU.
• CPU HNSW is CPU-bound — each node pins at its 8-vCPU limit; throughput scales ~linearly with node count while extra concurrency only inflates latency (CPU 8×4 b1024 → p50 18s, p99 30s). GPU sweet spot is batch 256–512; batch 1024 only helps at the highest concurrency.

Throughput figures are from the gpu-hnsw-v89 image (this beam-search kernel; fp32/int8 COSINE). v89 is 10–24% faster than v83 at all matched batch-512 cells (4×1 +11%, 4×4 +11%, 8×1 +24%, 8×4 +14%), so the filtered-search path does not regress unfiltered throughput. Native fp16/bf16 throughput is a follow-up; correctness across fp32/fp16/bf16/int8 × L2/IP/COSINE (and filtered deletes/TTL/partition at CPU parity) is covered by the unit/recall/sanitizer gates and the sealed-segment cluster e2e.

Related PRs: 6si/faiss#1, 6si/knowhere#2.

Link to Devin session: https://6sense.devinenterprise.com/sessions/d39aba56b8a3467cbbf231ab631a06ed

Link to Devin session: https://6sense.devinenterprise.com/sessions/55dab0bd33c346df99b5818b30059342
Requested by: @premal

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Codex P1 #3 — reserve GPU_HNSW peak host memory (5e13c42763)

GPU_HNSW frees its CPU copy after uploading graph/vectors to VRAM, so its retained memoryCost is ~0. The previous non-mmap reservation max_memory_cost = 2 * memoryCost therefore reserved zero bytes, even though Deserialize() transiently materializes the CPU HNSW index + decode/graph staging before the upload — concurrent loads could OOM the query node.

Knowhere's Resource now exposes a phase-separated maxMemoryCost (peak transient host memory during load — 6si/knowhere#2 08ced662). VectorIndexLoadResource in IndexFactory.cpp:

} else if (res.maxMemoryCost > 0) {          // GPU_HNSW: peak != retained
    request.max_disk_cost = 0;
    request.max_memory_cost = res.maxMemoryCost;
} else {                                       // unchanged for all other indexes
    request.max_disk_cost = 0;
    request.max_memory_cost = 2 * res.memoryCost;
}

final_memory_cost stays res.memoryCost; disk/mmap path unchanged; indexes that don't set the field keep the 2*memoryCost heuristic. This composes with the earlier ReopenSegments override-ordering fix (b6bd313d) so the GPU_HNSW estimator — not the CPU HNSW one — is what feeds the reservation.

This is a C++ recompile of segcore (needs to build against knowhere 08ced662); v67 build queued. Assertion coverage for the accounting is in the knowhere [gpu_hnsw_p1] "Load-resource estimate" section.

[devin-ai-integration]

Codex re-review should-fix #1 — pin KNOWHERE_VERSION to a commit SHA (0c81fc3a8b)

internal/core/thirdparty/knowhere/CMakeLists.txt pointed KNOWHERE_VERSION at the mutable branch gpu-hnsw-faiss, so the knowhere build could change with no milvus PR. Now pinned to the immutable branch-HEAD SHA 22fd143b360a0b37bc89a2128c496b95abfb3914 (FetchContent GIT_TAG = full SHA, full clone). Still a pre-merge action item: repoint to a tagged 6si/knowhere release once one exists (comment left in the file). v68 build will confirm FetchContent resolves the SHA cleanly.

[premal]

Code Review — Delta 2

The only change in this delta is bumping KNOWHERE_VERSION to 8fbaf1f4746c54bb71a90865e1d45f081426533b, which picks up the knowhere bitonic sort race fix + merge-path off-by-one fix + defensive guards. No new milvus code changes.

All previously flagged items remain open:

• [I1] fieldGpuMemorySize charged MaxMemoryCost (host-RAM peak) for VRAM admission
• [I2] KNOWHERE_VERSION still on 6si fork, comment-only repoint action item
• [M6] E2E tests use time.sleep() instead of proper wait conditions

No new issues found.

[premal]

Code Review — Delta 3

The only change is bumping KNOWHERE_VERSION to d022e89825c499d43822c90041ebb9d4908b6a25 (picks up knowhere C1 fix + distance convention change + SQ alias fix). Also reverted the knowhere fork URL/git repo back to zilliztech — the version is now pinned to a 6si fork commit SHA but the repo URL points to the upstream. No new milvus code changes.

All previously flagged items remain open:

• [I1] fieldGpuMemorySize charged MaxMemoryCost (host-RAM peak) for VRAM admission
• [I2] KNOWHERE_VERSION still on 6si fork SHA, comment-only repoint action item
• [M6] E2E tests use time.sleep() instead of proper wait conditions

No new issues found.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 3 additional findings in Devin Review.

[premal]

Code Review — Delta 4 (time.sleep replaced with polling + SHA bump)

✅ M6 (Minor) — FIXED

time.sleep() calls in E2E tests replaced with proper polling:

• wait_load_complete() — delegates to SDK's wait_for_loading_complete
• wait_until(predicate, timeout, interval, desc) — polls an observable condition with configurable timeout

The hot-segment test now polls until the hot-inserted vector self-searches to its own ID (_hot_segment_searchable), instead of guessing time.sleep(5). This is the correct observable condition — race-free and doesn't over-wait.

wait_until is well-designed: configurable timeout/interval, includes last exception in timeout error, good description for diagnostics.

KNOWHERE_VERSION bumped to 898a93f2

Picks up knowhere isCosine() API + I1 fix. Still on 6si fork SHA.

Remaining Open Items (non-blocking)

• [I1] fieldGpuMemorySize charged MaxMemoryCost (host-RAM peak) for VRAM admission — verify this bounds VRAM for GPU_HNSW
• [I2] KNOWHERE_VERSION on 6si fork SHA — repoint to tagged release before production merge

No new issues found.

[premal]

Code Review — Delta 5 (GPU HNSW M/efConstruction param validation + tests + doc updates)

Summary

No critical or important issues. This delta is clean and well-implemented.

✅ GPU M Validation — Correct

gpuHnswMaxM = gpuHnswMaxStagingCapacity / 2 = 512 is the right bound. The GPU search kernel stages next_pow2(2*M) candidates in one CUDA block (max 1024 threads). M=512 → next_pow2(1024)=1024 ✓, M=513 → next_pow2(1026)=2048 > 1024 ✗. Good simplification from the previous runtime nextPow2() to a compile-time constant.

✅ Optional Parameter Semantics — Correct

M and efConstruction are only validated when present (if _, ok := params[key]; ok), matching CPU HNSW behavior where knowhere fills defaults. Tests verify both-omitted, M-omitted, and ef-omitted all succeed.

✅ errParamShouldBeInRange — Consistent with Knowhere

"param '%s' (%s) should be in range [%d, %d]" mirrors knowhere's CPU HNSW error wording. Python tests verify exact messages.

✅ Test Coverage — Comprehensive

Go tests: boundary (M=512 pass, M=513 fail, M=-1 fail, M=600 fail), optional semantics, non-power-of-2 M, metric types, data types. Python tests: M boundaries, type validation, efConstruction boundaries, SQ-specific params. Good coverage.

✅ Design Doc — Accurate

Filtered-search limitation blockquote correctly describes: no BitView support, invalid_args reject for non-empty bitsets, no CPU fallback (index freed after upload), append-only recommendation. Vector-output safety row correctly explains raw data comes from column data, not the index.

Minor: M1 — gpuHnswMinM Comment Inaccurate

// gpuHnswMinM is the smallest usable HNSW graph degree (a graph needs at least
// 2 neighbors per node); matches the CPU HNSW advertised minimum.
const gpuHnswMinM = 2

CPU HNSW allows M=1 (HNSWMinM = 1 in constraints.go). GPU requires M≥2. The comment should say "stricter than the CPU HNSW minimum" rather than "matches," mirroring the gpuHnswMaxM comment which correctly says "stricter than the CPU HNSW max."

Previous Findings Status

Finding	Status
I1 (maxMemoryCost for VRAM admission)	Unchanged (non-blocking)
I2 (KNOWHERE_VERSION fork SHA)	Bumped to da32be6e, still 6si fork
M6 (time.sleep in E2E tests)	Fixed in delta 4, no regression

No merge blockers.

[devin-ai-integration]

Delta-5 minor (gpuHnswMinM comment): fixed in 5061f5e — the comment now says the GPU M>=2 minimum is stricter than the CPU HNSW minimum (HNSWMinM=1), mirroring the gpuHnswMaxM comment. Comment-only, no behavior change.

[premal]

Delta 6 Review — milvus PR #6 (filtered search docs + tests)

Previously-Flagged Items

• M1 (delta5 — gpuHnswMinM comment): ✅ Fixed. Comment now correctly says "stricter than the CPU HNSW minimum (HNSWMinM=1)" instead of the incorrect "matches the CPU HNSW advertised minimum."
• I1 (fieldGpuMemorySize / MaxMemoryCost): Not addressed — non-blocking, carried forward.
• I2 (KNOWHERE_VERSION on 6si fork SHA): ✅ Bumped from da32be6e... → 45e2ba26683ec1a62692d7c55dc47da7648e121f, with thorough comment explaining the SHA carries GPU-side filtered search.

New Issues — Two Merge Blockers

N1: Design docs NOT flipped, contradicting the version bump.

The MEP §8 explicitly instructs flipping the "not supported" callouts in 20260619-gpu-hnsw.md and 20260711-gpu-hnsw-ocq-removal.md to "supported (CPU-parity; BF fallback)." But the docs still say "not supported" and "returns invalid_args." Meanwhile KNOWHERE_VERSION is bumped to a SHA that carries filtered search — so the built binary will accept bitsets while the docs tell users it rejects them. Internally inconsistent.

Fix: Flip the doc callouts as the MEP instructs, or revert the version bump.

N2: No delete-then-query integration tests.

The MEP §8 instructs flipping the idx_gpu_hnsw* Python specs from expecting invalid_args to expecting "deleted rows absent + non-deleted rows present." There are zero delete-then-query tests in the diff. The filtered search path is untested at the Milvus integration level.

Fix: Add delete-then-query test cases that verify filtered rows are absent from results and non-deleted rows are present.

Root Cause

Both N1 and N2 stem from bumping KNOWHERE_VERSION without applying the Milvus-side doc/test changes the MEP requires. Either flip the docs + add the tests, or revert the version bump until the Milvus-side changes are ready.

Positive

• M1 fix is clean and correct
• The MEP doc is the exact approved Rev 3
• CMake comment for KNOWHERE_VERSION bump is thorough
• UTC import compatibility fix is good defensive coding

Full review at $M/reports/review-milvus-pr6-delta6.md

[devin-ai-integration]

Addressed the two merge blockers in f9ed9e0185:

N1 — docs flipped. 20260619-gpu-hnsw.md: the key-limitation banner and the Failure Modes row now read "Filtered search — supported (CPU parity)" (filtered rows excluded from results but kept as graph waypoints; brute-force fallback at high ratios) instead of "not supported / returns invalid_args". 20260711-gpu-hnsw-ocq-removal.md: the filtered-search reject decision (Status/Decision/Follow-up) is marked SUPERSEDED by 20260718-gpu-hnsw-filtered-search.md, whose status is now Implemented. Docs are now consistent with the bumped KNOWHERE_VERSION.

N2 — delete-then-query integration tests added. TestGpuHnswFilteredSearch (test_gpu_hnsw.py) and TestGpuHnswSQFilteredSearch (test_gpu_hnsw_sq.py): insert → flush (seal) → build GPU index → load → delete a PK range → assert (a) deleted ids absent from search, (b) query over the deleted range is empty, (c) live rows still returned, (d) no invalid_args — parametrized over L2/IP/COSINE with Strong consistency.

The minor items (faiss N1 codegen-identical comment, knowhere M4/N2 disable_bf/N1 dtype UT, N3 sentinel-count) are non-blocking and left as noted.