Question 1

如何修复在 /O2 下整数乘法循环中出现的 MSVC ARM64 C1001 内部编译器错误？

Accepted Answer

这是 MSVC 19.51（工具集 14.51.36231）在 Windows 11 ARM64 上的一个优化器回归问题。当包含 static_cast<int>(codes[i]) * codes[i] 的循环被内联到使用常量填充的 vector 的调用方中时，在 /O2 /Ob2 下可能会出现此问题。

可以通过强制使用 64 位乘法来规避：

sum_squared += static_cast<int64_t>(codes[i]) * codes[i];

这样可以保持结果正确，因为原始的 8 位值不会使 32 位乘积溢出。其他规避方法包括在循环前添加 #pragma loop(no_vector)，或将循环拆分为多条独立的语句。该问题在 MSVC 19.44 上无法复现。

Question 2

在 Windows ARM64 上使用 MSVC 构建 zvec 时，如何修复 CMake 错误 "Target zvec_ailego is required by zvec_ailego_shared"？

Accepted Answer

此问题发生在 zvec 0.5.1 中，因为 `src/ailego/CMakeLists.txt` 在 ARM64 上使用 MSVC 时，在创建 `zvec_ailego` 目标之前就调用了 `return()`，而此时 `BUILD_ZVEC_AILEGO_SHARED` 仍处于启用状态。该问题已由 PR #352 修复，并合并到了 `main`。

首选修复方法：将 zvec 依赖更新到最新的 `main` 或包含 PR #352 的发布版本，然后重新配置：

```bat
rmdir /s /q build
cmake -B build -G Ninja ^
  -DCMAKE_SYSTEM_NAME=Windows ^
  -DCMAKE_SYSTEM_PROCESSOR=ARM64 ^
  -DBUILD_C_BINDINGS=ON ^
  -DBUILD_ZVEC_AILEGO_SHARED=ON
cmake --build build
```

如果必须使用 zvec 0.5.1 且不需要一体化的 ailego 共享库，请将其禁用：

```bat
cmake -B build -G Ninja ^
  -DCMAKE_SYSTEM_NAME=Windows ^
  -DCMAKE_SYSTEM_PROCESSOR=ARM64 ^
  -DBUILD_C_BINDINGS=ON ^
  -DBUILD_ZVEC_AILEGO_SHARED=OFF
```

或者，backport PR #352，或修补 `src/ailego/CMakeLists.txt`：不要对 MSVC ARM64 无条件地 `return()`，保留 `cc_library(NAME zvec_ailego ...)` 调用，并且仅对非 MSVC 编译器应用 GCC/Clang 标志（如 `-march=armv8-a`）。

Question 3

如何修复在 Linux 上使用带 excludedFileTypes 的 context() 时 zvec 中出现的 SIGSEGV 原生堆栈溢出？

Accepted Answer

崩溃的原因是 `excludedFileTypes` 会展开为数千个 `file_id = ... OR ...` 谓词，原生 `sqlengine::QueryNode` 解析器会递归处理这些谓词，直至堆栈溢出。该问题已通过拉取请求 #694 修复，该请求添加了对长 OR 表达式的处理，并将包含在下一个版本中。待该版本发布后，请升级 `@zvec/zvec`、Linux x64 绑定和 `@zvec/zvec-grep`，例如：`npm install @zvec/zvec@latest @zvec/bindings-linux-x64@latest @zvec/zvec-grep@latest`。对于受影响的版本（如 `@zvec/zvec@0.7.0` 和 `@zvec/zvec-grep@0.2.1`），可采用的临时解决方法是：在 `session.context()` 中省略 `excludedFileTypes`，在检索后于 JavaScript 中过滤要排除的文件类型，或减少查询所覆盖的文件数量。

Question 4

如何修复 IVF `n_iters` 被忽略导致 KMeans 使用默认迭代次数的问题？

Accepted Answer

这是一个参数传播 bug：`IVFIndexParam::n_iters` 已到达 IVF 参数，但未传递给第一级 KMeans/OptKMeans 聚类器，因此聚类使用了其默认迭代次数。请升级到包含 PR `fix(core): IVF n_iters propagation to clusterer`（issue #729）的版本，或在从源码构建时 cherry-pick 该 PR。该修复将 `n_iters` 转发至第一级聚类参数，并包含针对构建器参数传播的回归测试覆盖。

Question 5

为什么 zvec 的 Collection.optimize() 会导致 upsert 或 delete 之后向量缺失或错误？

Accepted Answer

这是 zvec 0.6.0 和 0.7.0 中一个已知的索引重建 bug。当 `optimize()` 移除被取代的行时,向量文件会按照存活文档的数量进行重建,但查找仍然使用原始的段行 ID。当存在 K 个已删除/被覆盖的行时,最后 K 个存活向量的读取会超出文件末尾,并且后续的文档 ID 也可能被映射到错误的向量。典型的日志包括 `Read vector failed`、`Failed to fetch vector` 和 `vector indexer fetch failed`。

受影响版本的临时解决方法:
1. 在执行 `upsert()` 更新或 `delete()` 操作之后,不要调用 `Collection.optimize()`。
2. 如果已经运行了 `optimize()`,请从优化之前创建的备份中恢复,或者使用相同的 schema 创建一个新的 collection,并从源数据重新 upsert 所有存活文档。
3. 升级到包含修复 `preserve vector row mapping when rebuilding indexes with deleted rows`(即 issue #724 的修复)的 zvec 版本。使用 `python -m pip install -U zvec`,然后确认发行说明中包含该修复。
4. 升级后,重建或重新导入任何之前被 `optimize()` 损坏的 collection;仅升级本身可能无法修复已经错误的向量映射。

通过同时检查标量结果和包含向量的 `fetch()` 来验证恢复情况,因为 `stats.doc_count` 和标量扫描仍可能报告那些在向量搜索中缺失的文档。

zvec

项目简介

README 预览

常见问题 (5)

同类型项目

browser-use

puppeteer

manim

PaddleOCR