feat: support pyramid raw vector retrieval by jac0626 · Pull Request #2503 · antgroup/vsag

jac0626 · 2026-07-22T04:08:44Z

Change Type

Linked Issue

Fixes: [feat](other): support raw vector retrieval in pyramid #2502

What Changed

Add Pyramid store_raw_vector support and expose raw vectors through GetRawVectorByIds/GetVectorByInnerId.
Reuse an existing in-memory FP32 base or reorder data cell when possible; otherwise maintain separate FP32 raw-vector storage across Train, Build, Add, ODescent, and serialization.
Add live Pyramid GetMemoryUsage()/GetMemoryUsageDetail() reporting, including hierarchy graphs and separate raw-vector storage without double-counting aliases.
Persist FP32 hold_molds, validate legacy deserialization parameters before reading the body, and preserve backward compatibility for older Pyramid parameter snapshots.
Document the new parameters in English and Chinese.

Test Evidence

Test details:

/opt/homebrew/opt/llvm@15/bin/clang-format --dry-run --Werror <changed C++ files>
cmake --build build --target unittests -j6
./build/tests/unittests
  All tests passed (62,573,683 assertions in 561 test cases)

./build/tests/unittests '[ut][pyramid][raw_vector]'
  All tests passed (45 assertions in 6 test cases)

Compatibility Impact

API/ABI compatibility: additive behavior; no public signature changes
Behavior changes: Pyramid can preserve exact FP32 vectors when store_raw_vector=true; FP32 parameter snapshots now retain hold_molds

Performance and Concurrency Impact

Performance impact: separate FP32 storage is allocated only when existing in-memory FP32 codes cannot be reused
Concurrency/thread-safety impact: memory reporting and raw-vector reads use the existing Pyramid resize lock

Documentation Impact

Risk and Rollback

Risk level: medium
Rollback plan: revert this commit to restore the previous Pyramid storage and serialization behavior

Checklist

I have linked the relevant issue (required for kind/bug and kind/feature; see "Linked Issue" above)
I have added/updated tests for new behavior or bug fixes
I have considered API compatibility impact
I have updated docs if behavior/workflow changed
My commit messages follow project conventions (Conventional Commits, optional [skip ci] prefix)

gemini-code-assist · 2026-07-22T04:08:47Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

vsag-bot · 2026-07-22T04:08:48Z

/label S-waiting-on-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @wxyucs
/request-review @inabao
/request-review @LHT129

vsag-bot · 2026-07-22T04:08:59Z

Automated pull request review completed.

Review effort: high (811 changed lines across 8 files).

Submitted 1 inline comment.
Review: #2503 (review)

mergify · 2026-07-22T04:09:20Z

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+)

Copilot

Pull request overview

Adds Pyramid support for preserving and retrieving FP32 raw vectors (including through streaming/legacy serialization), along with detailed live memory reporting to enable accurate HGraph vs Pyramid memory comparisons.

Changes:

Implement Pyramid raw-vector storage/reuse logic and expose it via GetVectorByInnerId / GetRawVectorByIds, including streaming + legacy serialization support.
Add Pyramid GetMemoryUsage() / GetMemoryUsageDetail() with hierarchy graph accounting and alias-aware raw-vector reporting.
Update unit tests, docs (EN/ZH), and add a C++ example to reproduce HGraph/Pyramid memory comparisons.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/quantization/fp32_quantizer_parameter.cpp	Persist `hold_molds` in FP32 quantizer JSON.
src/quantization/fp32_quantizer_parameter_test.cpp	Extend FP32 parameter JSON roundtrip coverage for `hold_molds`.
src/algorithm/pyramid/pyramid.h	Add raw-vector members/hooks and memory usage APIs to Pyramid declarations.
src/algorithm/pyramid/pyramid.cpp	Implement raw-vector reuse/storage, serialization blocks, and memory usage reporting.
src/algorithm/pyramid/pyramid_zparameters.cpp	Backward-compat restore for legacy FP32 `hold_molds` and compatibility checks for raw-vector params.
src/algorithm/pyramid/pyramid_test.cpp	Add regression tests covering raw vectors, (de)serialization, cosine behavior, and memory reporting.
examples/cpp/README.md	Document new memory comparison example.
examples/cpp/CMakeLists.txt	Build target for the new memory comparison example.
examples/cpp/325_feature_compare_hgraph_pyramid_memory.cpp	New example program to compare RSS/allocator/index-reported memory.
docs/docs/zh/src/indexes/pyramid.md	Document new Pyramid raw-vector parameters (ZH).
docs/docs/zh/src/advanced/new_serialization.md	Document Pyramid streaming `raw_vector` block (ZH).
docs/docs/en/src/indexes/pyramid.md	Document new Pyramid raw-vector parameters (EN).
docs/docs/en/src/advanced/new_serialization.md	Document Pyramid streaming `raw_vector` block (EN).

jac0626 · 2026-07-22T06:01:36Z

/retest

gemini-code-assist · 2026-07-22T06:02:01Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/algorithm/pyramid/pyramid.cpp:978

SUPPORT_GET_RAW_VECTOR_BY_IDS is enabled whenever raw_vector_ != nullptr, but for cosine metrics an FP32 flatten without HoldMolds() stores normalized vectors, so GetRawVectorByIds would not return the original/raw vectors. This should follow the same gating used by BruteForce/HGraph: only advertise raw-vector support for cosine when molds are preserved.

    if (raw_vector_ != nullptr) {
        this->index_feature_list_->SetFeature(IndexFeature::SUPPORT_GET_RAW_VECTOR_BY_IDS);
    }

vsag-bot

Automated inline review completed.

Review effort: high (531 changed lines across 10 files).
Submitted 4 inline comments.

Reviewed commit c519510.

Signed-off-by: jac0626 <jac0626@users.noreply.github.com> Assisted-by: Codex:gpt-5

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/algorithm/pyramid/pyramid.cpp:474

GetMemoryUsageDetail() computes hierarchy_memory using hierarchies_.bucket_count() * sizeof(value_type), which overcounts because value_type storage scales with hierarchies_.size(), not bucket_count. This can noticeably inflate the reported memory usage for small numbers of hierarchies.

    uint64_t hierarchy_memory = hierarchies_.bucket_count() *
                                (sizeof(decltype(hierarchies_)::value_type) + sizeof(uint32_t));
    for (const auto& [name, hierarchy] : hierarchies_) {

vsag-bot

Automated inline review completed.

Review effort: high (809 changed lines across 8 files).
Submitted 1 inline comment.

Reviewed commit 360048a.

Signed-off-by: jc543239 <jc543239@antgroup.com> Assisted-by: Codex:gpt-5

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

vsag-bot

Automated inline review completed.

Review effort: high (811 changed lines across 8 files).
Submitted 1 inline comment.

Reviewed commit ab8a0f2.

jac0626 · 2026-07-23T08:17:28Z

/retest

Copilot AI review requested due to automatic review settings July 22, 2026 04:08

pull-request-size Bot added the size/XL label Jul 22, 2026

vsag-bot assigned LHT129 Jul 22, 2026

jac0626 added kind/feature Brand-new functionality or capabilities 引入全新的功能、新特性或新能力 version/1.0 labels Jul 22, 2026

vsag-bot self-requested a review July 22, 2026 04:08

Copilot started reviewing on behalf of jac0626 July 22, 2026 04:09 View session

mergify Bot added module/docs module/example labels Jul 22, 2026

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid.cpp Outdated

jac0626 marked this pull request as ready for review July 22, 2026 06:01

jac0626 requested review from LHT129, inabao, jiaweizone and wxyucs as code owners July 22, 2026 06:01

Copilot AI review requested due to automatic review settings July 22, 2026 06:10

Copilot started reviewing on behalf of jac0626 July 22, 2026 06:10 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid.cpp Outdated

vsag-bot reviewed Jul 22, 2026

View reviewed changes

Comment thread src/quantization/fp32_quantizer_parameter.cpp Outdated

Comment thread src/algorithm/pyramid/pyramid.cpp

Comment thread src/algorithm/pyramid/pyramid.cpp Outdated

Comment thread src/algorithm/pyramid/pyramid.cpp

Copilot AI review requested due to automatic review settings July 23, 2026 03:19

vsag-bot self-requested a review July 23, 2026 03:19

Copilot started reviewing on behalf of jac0626 July 23, 2026 03:19 View session

jac0626 added 2 commits July 23, 2026 11:24

feat: support pyramid raw vector retrieval

79b6f34

Signed-off-by: jac0626 <jac0626@users.noreply.github.com> Assisted-by: Codex:gpt-5

chore: remove pyramid memory comparison example

d395ee2

Signed-off-by: jac0626 <jac0626@users.noreply.github.com> Assisted-by: Codex:gpt-5

fix: harden pyramid raw vector storage

360048a

Signed-off-by: jac0626 <jac0626@users.noreply.github.com> Assisted-by: Codex:gpt-5

Copilot AI reviewed Jul 23, 2026

View reviewed changes

jac0626 force-pushed the codex/pyramid-raw-vector branch from 08b4de1 to 360048a Compare July 23, 2026 03:31

Copilot AI review requested due to automatic review settings July 23, 2026 03:31

Copilot started reviewing on behalf of jac0626 July 23, 2026 03:43 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid.cpp

Comment thread src/algorithm/pyramid/pyramid.cpp

vsag-bot reviewed Jul 23, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid.cpp

fix: resolve pyramid clang-tidy errors

ab8a0f2

Signed-off-by: jc543239 <jc543239@antgroup.com> Assisted-by: Codex:gpt-5

Copilot AI review requested due to automatic review settings July 23, 2026 06:01

vsag-bot self-requested a review July 23, 2026 06:01

Copilot started reviewing on behalf of jac0626 July 23, 2026 06:02 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid_zparameters.cpp

vsag-bot reviewed Jul 23, 2026

View reviewed changes

Comment thread src/algorithm/pyramid/pyramid.cpp

Uh oh!

Conversation

jac0626 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Type

Linked Issue

What Changed

Test Evidence

Compatibility Impact

Performance and Concurrency Impact

Documentation Impact

Risk and Rollback

Checklist

Uh oh!

gemini-code-assist Bot commented Jul 22, 2026

Uh oh!

vsag-bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vsag-bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Jul 22, 2026

Merge Protections

🟢 Require kind label

🟢 Require version label

🟢 Require linked issue for feature/bug PRs

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

jac0626 commented Jul 22, 2026

Uh oh!

gemini-code-assist Bot commented Jul 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

vsag-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

vsag-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

vsag-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jac0626 commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

jac0626 commented Jul 22, 2026 •

edited

Loading

vsag-bot commented Jul 22, 2026 •

edited

Loading

vsag-bot commented Jul 22, 2026 •

edited

Loading