rotate: add an optional random rotation feature in INT8 quantization method

.gitignore

@@ -52,3 +52,9 @@ allure-*
 !build_android.sh
 !build_ios.sh
 
+# congfig
+doc/
+config/
+examples/python/
+examples/c_api/
+logs/

examples/c/index_example.c

@@ -85,6 +85,11 @@ int main() {
   zvec_index_params_set_metric_type(hnsw_params_fast, ZVEC_METRIC_TYPE_L2);
   zvec_index_params_set_hnsw_params(hnsw_params_fast, 16, 100);
 
+  // Demonstrate INT8 quantization with random rotation preprocessing
+  // (enable_rotate rotates vectors before INT8 quantization to reduce error)
+  zvec_index_params_set_quantize_type(hnsw_params_fast, ZVEC_QUANTIZE_TYPE_INT8);
+  zvec_index_params_set_quantizer_enable_rotate(hnsw_params_fast, true);
+
   zvec_index_params_t *hnsw_params_balanced =
       zvec_index_params_create(ZVEC_INDEX_TYPE_HNSW);
   if (!hnsw_params_balanced) {

python/zvec/__init__.py

@@ -108,6 +108,7 @@
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    QuantizerParam,
     VamanaIndexParam,
     VamanaQueryParam,
 )
@@ -171,6 +172,7 @@
     "HnswQueryParam",
     "HnswRabitqQueryParam",
     "IVFQueryParam",
+    "QuantizerParam",
     "VamanaIndexParam",
     "VamanaQueryParam",
     # Extensions

python/zvec/__init__.pyi

@@ -28,6 +28,7 @@ from .model.param import (
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    QuantizerParam,
     VamanaIndexParam,
     VamanaQueryParam,
 )
@@ -74,6 +75,7 @@ __all__: list = [
     "MetricType",
     "OptimizeOption",
     "QuantizeType",
+    "QuantizerParam",
     "Query",
     "ReRanker",
     "RrfReRanker",

python/zvec/model/param/__init__.py

@@ -31,6 +31,7 @@
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    QuantizerParam,
     VamanaIndexParam,
     VamanaQueryParam,
 )
@@ -53,6 +54,7 @@
     "IndexOption",
     "InvertIndexParam",
     "OptimizeOption",
+    "QuantizerParam",
     "VamanaIndexParam",
     "VamanaQueryParam",
 ]

python/zvec/model/param/__init__.pyi

@@ -24,6 +24,7 @@ __all__: list[str] = [
     "IndexParam",
     "InvertIndexParam",
     "OptimizeOption",
+    "QuantizerParam",
     "QueryParam",
     "SegmentOption",
     "VectorIndexParam",
@@ -145,6 +146,8 @@ class FlatIndexParam(VectorIndexParam):
         quantize_type (QuantizeType): Optional quantization type for vector
             compression (e.g., FP16, INT8). Use ``QuantizeType.UNDEFINED`` to
             disable quantization. Default is ``QuantizeType.UNDEFINED``.
+        quantizer_param (QuantizerParam): Quantizer configuration (e.g., enable_rotate).
+            Default is ``QuantizerParam()``.
 
     Examples:
         >>> from zvec.typing import MetricType, QuantizeType
@@ -161,6 +164,7 @@ class FlatIndexParam(VectorIndexParam):
         self,
         metric_type: _zvec.typing.MetricType = ...,
         quantize_type: _zvec.typing.QuantizeType = ...,
+        quantizer_param: QuantizerParam = ...,
     ) -> None:
         """
         Constructs a FlatIndexParam instance.
@@ -169,6 +173,8 @@ class FlatIndexParam(VectorIndexParam):
             metric_type (MetricType, optional): Distance metric. Defaults to MetricType.IP.
             quantize_type (QuantizeType, optional): Vector quantization type.
                 Defaults to QuantizeType.UNDEFINED (no quantization).
+            quantizer_param (QuantizerParam, optional): Quantizer configuration.
+                Defaults to QuantizerParam().
         """
 
     def __repr__(self) -> str: ...
@@ -224,6 +230,7 @@ class HnswIndexParam(VectorIndexParam):
         ef_construction: typing.SupportsInt = 500,
         quantize_type: _zvec.typing.QuantizeType = ...,
         use_contiguous_memory: bool = False,
+        quantizer_param: QuantizerParam = ...,
     ) -> None: ...
     def __repr__(self) -> str: ...
     def __setstate__(self, arg0: tuple) -> None: ...
@@ -496,6 +503,7 @@ class IVFIndexParam(VectorIndexParam):
         n_iters: typing.SupportsInt = 10,
         use_soar: bool = False,
         quantize_type: _zvec.typing.QuantizeType = ...,
+        quantizer_param: QuantizerParam = ...,
     ) -> None:
         """
         Constructs an IVFIndexParam instance.
@@ -509,6 +517,8 @@ class IVFIndexParam(VectorIndexParam):
             use_soar (bool, optional): Enable SOAR optimization. Defaults to False.
             quantize_type (QuantizeType, optional): Vector quantization type.
                 Defaults to QuantizeType.UNDEFINED.
+            quantizer_param (QuantizerParam, optional): Quantizer configuration.
+                Defaults to QuantizerParam().
         """
 
     def __repr__(self) -> str: ...
@@ -912,6 +922,49 @@ class SegmentOption:
         bool: Whether the segment is read-only.
         """
 
+class QuantizerParam:
+    """
+
+    Parameters for quantizer configuration.
+
+    Encapsulates quantization-related settings such as enable_rotate.
+    Designed for future extensibility.
+
+    Attributes:
+        enable_rotate (bool): Whether to apply random rotation before INT8
+            quantization to reduce quantization error.
+            Only effective with quantize_type=INT8. Defaults to False.
+
+    Examples:
+        >>> qp = QuantizerParam(enable_rotate=True)
+        >>> print(qp.enable_rotate)
+        True
+    """
+
+    def __getstate__(self) -> tuple: ...
+    def __init__(self, enable_rotate: bool = False) -> None:
+        """
+        Constructs a QuantizerParam instance.
+
+        Args:
+            enable_rotate (bool, optional): Whether to apply random rotation
+                before INT8 quantization. Defaults to False.
+        """
+
+    def __repr__(self) -> str: ...
+    def __setstate__(self, arg0: tuple) -> None: ...
+    def __eq__(self, arg0: typing.Any) -> bool: ...
+    def to_dict(self) -> dict:
+        """
+        Convert to dictionary with all fields
+        """
+
+    @property
+    def enable_rotate(self) -> bool:
+        """
+        bool: Whether random rotation is enabled before INT8 quantization.
+        """
+
 class VectorIndexParam(IndexParam):
     """
 
@@ -923,6 +976,7 @@ class VectorIndexParam(IndexParam):
         type (IndexType): The specific vector index type (e.g., HNSW, FLAT).
         metric_type (MetricType): Distance metric used for similarity search.
         quantize_type (QuantizeType): Optional vector quantization type.
+        quantizer_param (QuantizerParam): Quantizer configuration (e.g., enable_rotate).
     """
 
     def __getstate__(self) -> tuple: ...
@@ -944,6 +998,12 @@ class VectorIndexParam(IndexParam):
         QuantizeType: Vector quantization type (e.g., FP16, INT8).
         """
 
+    @property
+    def quantizer_param(self) -> QuantizerParam:
+        """
+        QuantizerParam: Quantizer configuration including enable_rotate.
+        """
+
 class _SearchQuery:
     field_name: str
     filter: str

src/CMakeLists.txt

@@ -64,6 +64,7 @@ function(zvec_add_all_in_one_shared TARGET_NAME OUTPUT_NAME)
                 ${ZVEC_ALLIN_LIBS}
                 Threads::Threads
         )
+        target_link_options(${TARGET_NAME} PRIVATE /OPT:REF /OPT:ICF)
     elseif(APPLE)
         foreach(ZVEC_ALLIN_LIB ${ZVEC_ALLIN_LIBS})
             list(APPEND ZVEC_ALLIN_WA_OPTIONS

src/binding/c/c_api.cc

@@ -1476,6 +1476,60 @@ zvec_quantize_type_t zvec_index_params_get_quantize_type(
   return ZVEC_QUANTIZE_TYPE_UNDEFINED;
 }
 
+/**
+ * @brief Set enable_rotate for quantizer parameters
+ * @param params Index parameters (must be vector index type)
+ * @param enable_rotate Whether to enable random rotation before quantization
+ * @return ZVEC_OK on success, error code on failure
+ */
+zvec_error_code_t zvec_index_params_set_quantizer_enable_rotate(
+    zvec_index_params_t *params, bool enable_rotate) {
+  if (!params) {
+    SET_LAST_ERROR(ZVEC_ERROR_INVALID_ARGUMENT,
+                   "Index params pointer cannot be null");
+    return ZVEC_ERROR_INVALID_ARGUMENT;
+  }
+  auto *cpp_params = reinterpret_cast<zvec::IndexParams *>(params);
+
+  if (!cpp_params->is_vector_index_type()) {
+    SET_LAST_ERROR(ZVEC_ERROR_INVALID_ARGUMENT,
+                   "Index params is not a vector index type");
+    return ZVEC_ERROR_INVALID_ARGUMENT;
+  }
+  auto *vec_params = dynamic_cast<zvec::VectorIndexParams *>(cpp_params);
+  if (!vec_params) {
+    SET_LAST_ERROR(ZVEC_ERROR_INVALID_ARGUMENT,
+                   "Failed to cast to VectorIndexParams");
+    return ZVEC_ERROR_INVALID_ARGUMENT;
+  }
+  zvec::QuantizerParam qp = vec_params->quantizer_param();
+  qp.set_enable_rotate(enable_rotate);
+  vec_params->set_quantizer_param(qp);
+  return ZVEC_OK;
+}
+
+/**
+ * @brief Get enable_rotate setting from quantizer parameters
+ * @param params Index parameters
+ * @return true if rotation is enabled, false otherwise
+ */
+bool zvec_index_params_get_quantizer_enable_rotate(
+    const zvec_index_params_t *params) {
+  if (!params) {
+    return false;
+  }
+  auto *cpp_params = reinterpret_cast<const zvec::IndexParams *>(params);
+
+  if (cpp_params->is_vector_index_type()) {
+    auto *vec_params =
+        dynamic_cast<const zvec::VectorIndexParams *>(cpp_params);
+    if (vec_params) {
+      return vec_params->quantizer_param().enable_rotate();
+    }
+  }
+  return false;
+}
+
 /**
  * @brief Get index type from index parameters
  * @param params Index parameters