Skip to content

fix: account for batch and rerank search statistics - #3251

Open
LHT129 wants to merge 1 commit into
antgroup:mainfrom
LHT129:dsh/fix-search-statistics-accounting
Open

LHT129 wants to merge 1 commit into
antgroup:mainfrom
LHT129:dsh/fix-search-statistics-accounting

Conversation

@LHT129

@LHT129 LHT129 commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Change Type

  • Bug fix

Linked Issue

Fixes: #3249

What Changed

  • Aggregate IVF batch child statistics: legacy counters retain wrapping semantics; 64-bit distance totals and phase/backend arrays saturate; timeout is OR and completeness is AND.
  • Account for bucket-layout rerank candidates and actual unique-location distance evaluations under the RERANK phase, respecting disabled distance tracking.
  • Publish ParallelSearcher legacy dist_cmp/hops after worker completion without duplicating newer distance accounting.
  • Add three minimal regression cases, including serial/parallel batch paths, repeated bucket positions, disabled tracking, and one/two-thread traversal.

Test Evidence

  • make fmt with clang-format 20.1.8, committed-tree format check, git diff --check
  • make lint
  • make test
  • make cov, run tests, and collect coverage
  • Other (details below)
Unfixed baseline: all three new regressions fail (4/10, 9/27, 8/140 assertions respectively).
After rebasing onto github/main c10f47c0:
  [ParallelSearcher],[reorder]: 84 assertions / 7 cases PASS
  [search_statistics],IVF Batch Search*,IVF bucket precise*: 36315 assertions / 10 cases PASS
Full Release unit suite: 1397 passed / 2 failed / 1 skipped (1400 cases).
Both failures reproduce with identical values on pristine baseline 87166b63:
  Normalize Compute: 0.99999994f == 0.999999881f
  SINDI FP16 rerank build search add and serialize: 0.000304073f < 0.000001f

Environment: Ubuntu 26.04, GCC15.2, Release. Unrelated baseline GCC15 diagnostics required -Wno-error=template-id-cdtor -Wno-error=stringop-overflow; this is not a claim of supported-toolchain CI validation.

TSan: independent build of the same commit via make tsan COMPILE_JOBS=8 passed. With the maintained four suppressions and OPENBLAS_NUM_THREADS=1, TSAN_OPTIONS=suppressions=omp.supp ./build/tests/functests "[concurrent]~[daily]" passed: 2,251,758 assertions in 28 cases, no ThreadSanitizer report.

Circle-equivalent make test_parallel completed with exit 0 on the same commit: fresh build 744/744; full unit group 1,403 passed / 1 native CUDA-unavailable skip (1,404 cases), all 86,768,517 assertions passed; [hgraph]~[daily] 191 cases / 1,246,671 assertions passed; ~[hgraph]~[daily] 290 cases / 8,767,632 assertions passed. Original filters were unchanged. Configuration: Ninja, MKL OFF, system OpenBLAS 0.3.32 ON, COMPILE_JOBS=4, ASAN/Sanitize OFF, CCACHE OFF, and the disclosed GCC15 warning flags. Normalize and SINDI FP16 tests passed in this configuration; the separately recorded Release baseline failures remain disclosed.

Python 3.10.22: a fresh wheel built successfully with the disclosed GCC15 warning compatibility flags and installed into a separate clean environment. However, the required clean-environment pytest did not pass: import fails with ImportError: libvsag.so.0.11: cannot open shared object file: No such file or directory (pytest exit 4). ELF inspection finds the extension RUNPATH points to a cleaned build directory rather than the installed bundled library. With an explicit task-only LD_LIBRARY_PATH pointing to the wheel's installed pyvsag directory, import alone succeeds, but the standard pytest command crashes during import (exit 139); importing NumPy before pyvsag reproduces this crash. Additional diagnostic run with the explicit library path and import pyvsag before invoking pytest.main passed all 137 tests (3 warnings, 18.68s, exit 0). This import-order workaround is not a substitute for the required standard command. The original strict GCC15 build failure and all subsequent failure logs are retained. make pyvsag returning 0 is not treated as pytest success. These packaging/runtime failures have not been established as regressions from this statistics-only change and are not silently fixed in this PR.

Submission exceptions explicitly approved by the requester: open the PR with the known baseline failures, GCC15 toolchain deviation and then-pending Python/Circle checks disclosed, and report their actual outcomes afterward. Circle has now passed as described above; Python remains unsuccessful as described above. macOS arm64 ASan was separately explicitly deferred. No unsuccessful or deferred check is claimed as passed.

Compatibility Impact

  • API/ABI compatibility: no public interface or layout changes.
  • Behavior changes: repaired diagnostic counters only; regression tests preserve result IDs/distances. Legacy counters remain distinct from total distance evaluations.

Performance and Concurrency Impact

  • Performance impact: batch aggregation parses each child query's existing statistics JSON and merges counters atomically. This adds per-query parsing/allocation and aggregation overhead, potentially more visible for inexpensive queries or large parallel batches; its performance impact has not been benchmarked.
  • Concurrency/thread-safety impact: one-way timeout/incomplete publication and atomic accumulation preserve concurrent batch reduction; parallel legacy counters are published after worker joins.

Documentation Impact

  • No docs update needed: existing documented counter semantics are restored, with no new interfaces or configuration.

Risk and Rollback

  • Risk level: low; limited to three accounting paths.
  • Rollback plan: revert this single task commit.

Checklist

  • I have linked the relevant issue
  • I have added/updated tests for bug fixes
  • I have considered API compatibility impact
  • I have considered documentation impact
  • My commit message follows project conventions and human DCO/Assisted-by ordering

Aggregate IVF batch query counters, account for bucket rerank evaluations, and publish parallel search legacy counters. Add minimal regression coverage.

Signed-off-by: LHT129 <tianlan.lht@antgroup.com>
Assisted-by: DeepSeekHarness:gpt-6.1-sol
@LHT129 LHT129 added kind/bug Bug fixes, defects, or unexpected behavior 修复程序错误、缺陷或异常行为 version/0.11 1. HNSW enhancements 2. DiskANN enhancements 1. HNSW增强 2. DiskANN增强 labels Nov 3, 2026
@LHT129
LHT129 requested review from inabao and wxyucs as code owners November 3, 2026 08:00
@LHT129 LHT129 self-assigned this Nov 3, 2026
@LHT129
LHT129 requested a review from jiaweizone as a code owner November 3, 2026 08:00
@pull-request-size pull-request-size Bot added the size/L 100-499 changed lines label Nov 3, 2026
@vsag-bot

vsag-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Merger | Merge Readiness

Head: d01ee873 | Base: a801af03 | Target: main

Updated: 2026-11-04 03:05:40 UTC

Status: BLOCKED

Merger decision: HOLD (shadow assessment; no merge executed).

  • Conversations: 2 unresolved; resolution required
  • GitHub merge state: BLOCKED

Next owner: Author. Required next step: Resolve the GitHub merge conditions, then reassess.

Merge reliability: 0.00 / 1.00 (WITHHELD)

Scoring basis Points Evidence
Required CI evidence 0.40 / 0.40 3/3 required check groups satisfy the branch policy from the expected source; neutral/skipped are not execution evidence
Branch review policy 0.00 / 0.20 GitHub review decision: REVIEW_REQUIRED; review conditions are not verified
Current AI review 0.40 / 0.40 Current head/base, complete static file coverage, correct verdict and zero P0/P1 findings

Evidence subtotal: 0.80; applicable ceiling: 0.00. Final score = min(subtotal, ceiling). Policy: merge-reliability-v2.

  • Ceiling 0.95: Static analysis and check outcomes do not prove correctness; v2 has an uncalibrated 0.95 policy ceiling.
  • Ceiling 0.00: GitHub merge conditions are BLOCKED; hard gates cannot be offset by other evidence.
  • Ceiling 0.50: 2 unresolved review threads remain.
  • Ceiling 0.85: The current AI review reports 3 residual risks; see its review for context.
Merge condition State Evidence
PR state PASS OPEN
Rules PASS Active rulesets and branch protection read
Conflicts PASS MERGEABLE
Merge method PASS squash, rebase
Merge commit freshness PENDING Waiting for GitHub to refresh the merge commit for the current head and base. Only current head checks are shown.
DCO PASS success
Mergify Merge Protections PASS success
PR CI Gate PASS success
Human review PENDING GitHub: REVIEW_REQUIRED; approvals >= 1; Code Owner approval required; stale approvals dismissed
Conversations BLOCKED 2 unresolved; resolution required
GitHub merge state BLOCKED BLOCKED

AI review: COMPLETE. Static review: patch is correct; CI is reported separately.

Review findings: 0; P0/P1 findings in that review: 0; coverage: 7/7 changed files. Findings are not a count of currently unresolved threads.

CI summary: 1 neutral, 15 skipped, 21 success. Check source: d01ee873. Skipped/neutral checks are not evidence that tests executed.

Next action: Merge commit freshness: Waiting for GitHub to refresh the merge commit for the current head and base. Only current head checks are shown.; Human review: GitHub: REVIEW_REQUIRED; approvals >= 1; Code Owner approval required; stale approvals dismissed; Conversations: 2 unresolved; resolution required; GitHub merge state: BLOCKED

CI check details
Check Source Result Required
CI Routing Tests PR CI (App 15368) success no
ci/circleci: path-filtering/filter StatusContext success no
ci/circleci: pull-request-check StatusContext success no
Community / ASan Build macOS arm64 PR CI (App 15368) skipped no
Community / ASan Build X86 PR CI (App 15368) skipped no
Community / Build with TSAN PR CI (App 15368) skipped no
Community / Check Compatibility PR CI (App 15368) skipped no
Community / Coverage Configuration PR CI (App 15368) skipped no
Community / Detect Changes PR CI (App 15368) skipped no
Community / Docs PR CI (App 15368) success no
Community / Format Check PR CI (App 15368) skipped no
Community / Lite ${{ matrix.mode }} PR CI (App 15368) skipped no
Community / Python Build X86 PR CI (App 15368) skipped no
Community / Run TSAN Tests PR CI (App 15368) skipped no
Community / Shared Checks Result PR CI (App 15368) success no
Community / SIMD Coverage PR CI (App 15368) skipped no
Community / Test Example X86 PR CI (App 15368) skipped no
Community / Test Python X86 PR CI (App 15368) skipped no
Community / Test X86 Functests PR CI (App 15368) skipped no
Community / Test X86 Unittests PR CI (App 15368) skipped no
DCO CheckRun (App 1861) success yes
Issue Link PR Metadata (App 15368) success no
Mergify Merge Protections CheckRun (App 10562) success yes
Mergify Merge Queue CheckRun (App 10562) neutral no
PR CI Gate PR CI (App 15368) success yes
Select checks PR CI (App 15368) success no
Select CI route PR CI (App 15368) success no
Summary CheckRun (App 10562) success no
Team / Detect Team Linux Changes PR CI (App 15368) success no
Team / Team ASan Build PR CI (App 15368) success no
Team / Team Format and Helper Checks PR CI (App 15368) success no
Team / Team Index Compatibility PR CI (App 15368) success no
Team / Team Summary PR CI (App 15368) success no
Team / Team Test shard 0 PR CI (App 15368) success no
Team / Team Test shard 1 PR CI (App 15368) success no
Team / Team Test shard 2 PR CI (App 15368) success no
Team / Team Test shard 3 PR CI (App 15368) success no

This is an uncalibrated evidence score, not a probability, correctness guarantee or approval. Zero means the assessment is withheld or lacks positive evidence, not a proven-bad patch. Automatic merging is disabled. New commits or base changes invalidate earlier evidence; never authorize a merge from this score alone.

@vsag-bot
vsag-bot self-requested a review November 3, 2026 08:01
@vsag-bot

vsag-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Reviewer | Review complete

Automated pull request review completed.

Model: gpt-6.1-sol; reasoning effort: medium.
Review scope: medium (258 changed lines across 7 files).

No actionable inline findings were found.
Review coverage checks completed; this does not prove absence of defects.
Static review only; compilation and runtime tests are outside this review's scope.
File coverage: 7/7; observed passing test runs: 0.
Review: #3251 (review)

@vsag-bot vsag-bot added area/testing Tests, fixtures, and test infrastructure 测试、夹具与测试基础设施 module/index Index algorithms and implementations 索引算法与实现 labels Nov 3, 2026
@vsag-bot

vsag-bot commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator

Jev-driven classification

Applied: area/testing, module/index. Existing labels were preserved.

Option probabilities
Option Probability Result
kind/bug 100.0% Not applied
module/index 96.0% Applied
area/testing 86.0% Applied
module/datacell 83.0% Not applied
area/ci 21.0% Not applied
module/api 18.0% Not applied
area/tools 17.0% Not applied
area/dependencies 12.0% Not applied
area/bindings-python 9.0% Not applied
area/docs 6.0% Not applied
area/examples 5.0% Not applied
module/simd 5.0% Not applied
area/bindings-node 3.0% Not applied
module/attr 3.0% Not applied
area/docker 2.0% Not applied
kind/cleanup 0.0% Not applied
kind/documentation 0.0% Not applied
kind/enhancement 0.0% Not applied
kind/feature 0.0% Not applied
kind/improvement 0.0% Not applied
No kind 0.0% Not applied

Model: jev-1.13.0. Selection threshold: 85%. Probabilities are model estimates, not guarantees.

@mergify

mergify Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

  • label~=^kind/

🟢 Require version label

  • label~=^version/

🟢 Require linked issue for feature/bug PRs

  • body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

@mergify mergify Bot added the module/datacell Data cells, vector I/O, and quantization 数据单元、向量 I/O 与量化 label Nov 3, 2026

@vsag-bot vsag-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer | Code review

Automated pull request review completed.

Model: gpt-6.1-sol; reasoning effort: medium.
Review scope: medium (258 changed lines across 7 files).
No actionable inline findings were found.
Review coverage checks completed; this does not prove absence of defects.
Static review only; compilation and runtime tests are outside this review's scope.
File coverage: 7/7; observed passing test runs: 0.

Reviewed commit d01ee87.

@LHT129

LHT129 commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator Author

Validation progress for d01ee87: the fresh Circle-equivalent build completed all 744 build steps. The full non-HGraph functional group (filter [hgraph][daily]) passed: 290 cases / 8,767,632 assertions. Unit and HGraph groups are still running, so this is not an overall Circle check pass. Python wheel validation is also still in progress; the original strict GCC15 baseline diagnostic log is retained before the environment-only compatibility retry.

@vsag-lgtm vsag-lgtm left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review @ d01ee873 — 2 inline suggestion(s).


computer->ScanBatchDists(unique_offsets.size(), codes.data, unique_dists.data());
if (ctx != nullptr and ctx->stats != nullptr and ctx->track_distance_evaluations) {
ctx->stats->AddDistance(ctx->distance_phase, backend_, unique_offsets.size());

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[warning] Needs confirmation: the new distance tracking is skipped for the PQFS early-return path above.

BucketDataCell::Query returns early for QUANTIZATION_TYPE_VALUE_PQFS and falls back to a loop of QueryOneById, which does not record distance evaluations. As a result, buckets backed by PQFastScan will not populate distance_evaluations or the RERANK phase/backend counters under BucketReorder, leaving the statistics incomplete for that backend. If PQFS reranking is a supported configuration, consider tracking those evaluations in the PQFS branch as well.

}
one_request.params_str_ = json.Dump();
auto one_result = this->SearchWithRequest(one_request);
const auto one_stats = JsonType::Parse(one_result->GetStatistics());

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[suggestion] Aggregating batch statistics by serializing and reparsing JSON for each sub-query adds measurable overhead.

Each sub-query already builds a SearchStatistics object and serializes it via stats.Dump(); parsing it back with JsonType::Parse introduces per-query allocation and parsing costs that grow with batch size. Consider carrying the SearchStatistics (or a lightweight snapshot) through the result object so the batch path can merge counters directly without round-tripping through JSON.

@LHT129

LHT129 commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator Author

Circle-equivalent make test_parallel has now finished: the original script reports success for all three complete groups (unit, [hgraph], and other), without dropping tests beyond its maintained ~[daily] filter. Both functional groups passed: 191 cases / 1,246,671 assertions and 290 cases / 8,767,632 assertions. Full logs are retained; this run uses the previously disclosed GCC15 warning compatibility flags and system OpenBLAS configuration. This successful configuration does not erase the separately disclosed Release baseline numeric failures. Python wheel/clean-environment pytest is still pending.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/testing Tests, fixtures, and test infrastructure 测试、夹具与测试基础设施 kind/bug Bug fixes, defects, or unexpected behavior 修复程序错误、缺陷或异常行为 module/datacell Data cells, vector I/O, and quantization 数据单元、向量 I/O 与量化 module/index Index algorithms and implementations 索引算法与实现 size/L 100-499 changed lines version/0.11 1. HNSW enhancements 2. DiskANN enhancements 1. HNSW增强 2. DiskANN增强

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] Search statistics undercount IVF batch, bucket rerank and parallel search work

3 participants