feat: add portable x86 simd dispatch build profile

refactor: default source x86 builds to portable profile

Author: zhoujh01

CONTRIBUTING.md

@@ -59,6 +59,19 @@ uv pip install -e . --force-reinstall
 
 This command ensures that `setup.py` is re-executed, triggering the compilation of AGFS and C++ components.
 
+For x86 builds, OpenViking now uses explicit build profiles:
+
+- `wheel` builds default to `OV_X86_BUILD_PROFILE=portable`, which emits a single portable extension with runtime SIMD dispatch (`SSE3` baseline plus optional `AVX2/AVX512` kernels).
+- source installs also default to `OV_X86_BUILD_PROFILE=portable`, so local editable installs match wheel behavior and stay portable across x86 machines.
+- `OV_X86_BUILD_PROFILE=native` remains available when you explicitly want `-march=native` for same-machine performance.
+- advanced users can override with `OV_X86_BUILD_PROFILE=fixed` and `OV_X86_SIMD_LEVEL=SSE3|AVX2|AVX512`.
+
+Example native source build:
+
+```bash
+OV_X86_BUILD_PROFILE=native uv pip install -e . --force-reinstall
+```
+
 ### 3. Configure Environment
 
 Create a configuration file `~/.openviking/ov.conf`:

CONTRIBUTING_CN.md

@@ -59,6 +59,19 @@ uv pip install -e . --force-reinstall
 
 该命令会强制重新执行 `setup.py`，触发 AGFS 和 C++ 组件的编译与安装。
 
+对于 x86 构建，OpenViking 现在提供明确的构建 profile：
+
+- `wheel` 默认使用 `OV_X86_BUILD_PROFILE=portable`，产出单个可移植扩展，并在运行时自动在 `SSE3` 基线与可选的 `AVX2/AVX512` kernel 之间分派。
+- 源码安装也默认使用 `OV_X86_BUILD_PROFILE=portable`，让本地 editable 安装与 wheel 行为一致，并保持跨 x86 机器可移植。
+- 如果你明确需要本机最佳性能，仍可显式设置 `OV_X86_BUILD_PROFILE=native` 以启用 `-march=native`。
+- 高级用户可以用 `OV_X86_BUILD_PROFILE=fixed` 配合 `OV_X86_SIMD_LEVEL=SSE3|AVX2|AVX512` 强制固定 ISA。
+
+本机优化源码构建示例：
+
+```bash
+OV_X86_BUILD_PROFILE=native uv pip install -e . --force-reinstall
+```
+
 ### 3. 配置环境
 
 创建配置文件 `~/.openviking/ov.conf`：

MANIFEST.in

@@ -10,6 +10,7 @@ include LICENSE
 include README.md
 include pyproject.toml
 include setup.py
+recursive-include build_support *.py
 recursive-include openviking *.yaml
 
 # sdist should be source-only: never ship runtime binaries from working tree

build_support/__init__.py

@@ -0,0 +1 @@
+"""Build-time helpers for OpenViking packaging."""

build_support/x86_profiles.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Sequence
+
+_SUPPORTED_PROFILES = {"portable", "native", "fixed"}
+_SUPPORTED_LEVELS = {"SSE3", "AVX2", "AVX512", "NATIVE"}
+
+
+@dataclass(frozen=True)
+class X86BuildConfig:
+    profile: str
+    simd_level: str
+    baseline: str
+    dispatch_enabled: bool
+
+
+def _normalize_profile(profile: str) -> str:
+    normalized = profile.strip().lower()
+    if normalized not in _SUPPORTED_PROFILES:
+        raise ValueError(
+            f"Unsupported OV_X86_BUILD_PROFILE={profile!r}; "
+            "expected one of: fixed, native, portable"
+        )
+    return normalized
+
+
+def _normalize_level(level: str) -> str:
+    normalized = level.strip().upper()
+    if normalized not in _SUPPORTED_LEVELS:
+        raise ValueError(
+            f"Unsupported OV_X86_SIMD_LEVEL={level!r}; expected one of: SSE3, AVX2, AVX512, NATIVE"
+        )
+    return normalized
+
+
+def _is_wheel_build(argv: Sequence[str]) -> bool:
+    wheel_commands = {"bdist_wheel", "editable_wheel"}
+    return any(arg in wheel_commands for arg in argv)
+
+
+def resolve_x86_build_config(
+    env: Mapping[str, str] | None = None,
+    argv: Sequence[str] | None = None,
+) -> X86BuildConfig:
+    env = env or {}
+    argv = argv or []
+
+    baseline = _normalize_level(env.get("OV_X86_PORTABLE_BASELINE", "SSE3"))
+    if baseline == "NATIVE":
+        raise ValueError("OV_X86_PORTABLE_BASELINE cannot be NATIVE")
+
+    explicit_profile = env.get("OV_X86_BUILD_PROFILE")
+    explicit_level = env.get("OV_X86_SIMD_LEVEL")
+
+    if explicit_profile:
+        profile = _normalize_profile(explicit_profile)
+    elif explicit_level:
+        normalized_level = _normalize_level(explicit_level)
+        profile = "native" if normalized_level == "NATIVE" else "fixed"
+    else:
+        profile = "portable"
+
+    if profile == "portable":
+        return X86BuildConfig(
+            profile="portable",
+            simd_level=baseline,
+            baseline=baseline,
+            dispatch_enabled=True,
+        )
+
+    if profile == "native":
+        return X86BuildConfig(
+            profile="native",
+            simd_level="NATIVE",
+            baseline=baseline,
+            dispatch_enabled=False,
+        )
+
+    simd_level = _normalize_level(explicit_level or "AVX2")
+    if simd_level == "NATIVE":
+        raise ValueError("OV_X86_SIMD_LEVEL=NATIVE requires OV_X86_BUILD_PROFILE=native")
+
+    return X86BuildConfig(
+        profile="fixed",
+        simd_level=simd_level,
+        baseline=baseline,
+        dispatch_enabled=False,
+    )

setup.py

@@ -10,6 +10,8 @@
 from setuptools import Extension, setup
 from setuptools.command.build_ext import build_ext
 
+from build_support.x86_profiles import resolve_x86_build_config
+
 CMAKE_PATH = shutil.which("cmake") or "cmake"
 C_COMPILER_PATH = shutil.which("gcc") or "gcc"
 CXX_COMPILER_PATH = shutil.which("g++") or "g++"
@@ -335,6 +337,13 @@ def _build_extension_impl(self, ext_fullpath, ext_dir, build_dir):
         """Invoke CMake to build the Python native extension."""
         py_output_name = ext_fullpath.stem
         py_output_suffix = ext_fullpath.suffix
+        x86_build_config = resolve_x86_build_config(os.environ, sys.argv)
+        print(
+            "Configuring x86 build profile="
+            f"{x86_build_config.profile} simd={x86_build_config.simd_level} "
+            f"baseline={x86_build_config.baseline} "
+            f"dispatch={'ON' if x86_build_config.dispatch_enabled else 'OFF'}"
+        )
 
         cmake_args = [
             f"-S{Path(ENGINE_SOURCE_DIR).resolve()}",
@@ -351,7 +360,10 @@ def _build_extension_impl(self, ext_fullpath, ext_dir, build_dir):
             f"-Dpybind11_DIR={pybind11.get_cmake_dir()}",
             f"-DCMAKE_C_COMPILER={C_COMPILER_PATH}",
             f"-DCMAKE_CXX_COMPILER={CXX_COMPILER_PATH}",
-            f"-DOV_X86_SIMD_LEVEL={os.environ.get('OV_X86_SIMD_LEVEL', 'AVX2')}",
+            f"-DOV_X86_BUILD_PROFILE={x86_build_config.profile}",
+            f"-DOV_X86_SIMD_LEVEL={x86_build_config.simd_level}",
+            f"-DOV_X86_PORTABLE_BASELINE={x86_build_config.baseline}",
+            f"-DOV_X86_DISPATCH={'ON' if x86_build_config.dispatch_enabled else 'OFF'}",
         ]
 
         if sys.platform == "darwin":

src/CMakeLists.txt

@@ -4,29 +4,64 @@ project(openviking_cpp)
 
 include(CheckCXXCompilerFlag)
 
-set(OV_X86_SIMD_LEVEL "AVX2" CACHE STRING "x86 SIMD level: SSE3|AVX2|AVX512|NATIVE")
+set(OV_X86_BUILD_PROFILE "portable" CACHE STRING "x86 build profile: portable|native|fixed")
+set_property(CACHE OV_X86_BUILD_PROFILE PROPERTY STRINGS portable native fixed)
+set(OV_X86_SIMD_LEVEL "AVX2" CACHE STRING "x86 SIMD level for fixed/native builds: SSE3|AVX2|AVX512|NATIVE")
 set_property(CACHE OV_X86_SIMD_LEVEL PROPERTY STRINGS SSE3 AVX2 AVX512 NATIVE)
+set(OV_X86_PORTABLE_BASELINE "SSE3" CACHE STRING "x86 portable baseline ISA")
+set_property(CACHE OV_X86_PORTABLE_BASELINE PROPERTY STRINGS SSE3)
+option(OV_X86_DISPATCH "Enable runtime SIMD dispatch on x86" OFF)
 
 set(OV_PLATFORM_X86 OFF)
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|amd64|AMD64|i[3-6]86")
     set(OV_PLATFORM_X86 ON)
 endif()
 
+set(OV_X86_AVX2_DISPATCH_SOURCES
+    ${CMAKE_CURRENT_SOURCE_DIR}/index/detail/vector/common/x86/l2_avx2.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/index/detail/vector/common/x86/ip_avx2.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/index/detail/vector/common/x86/int8_avx2.cpp
+)
+set(OV_X86_AVX512_DISPATCH_SOURCES
+    ${CMAKE_CURRENT_SOURCE_DIR}/index/detail/vector/common/x86/l2_avx512.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/index/detail/vector/common/x86/ip_avx512.cpp
+)
+
+set(OV_X86_PORTABLE_OPTIONAL_SOURCES
+    ${OV_X86_AVX2_DISPATCH_SOURCES}
+    ${OV_X86_AVX512_DISPATCH_SOURCES}
+)
+
 if(OV_PLATFORM_X86)
+    string(TOUPPER "${OV_X86_BUILD_PROFILE}" OV_X86_BUILD_PROFILE_UPPER)
     string(TOUPPER "${OV_X86_SIMD_LEVEL}" OV_X86_SIMD_LEVEL_UPPER)
+    string(TOUPPER "${OV_X86_PORTABLE_BASELINE}" OV_X86_PORTABLE_BASELINE_UPPER)
     set(OV_X86_COMPILE_FLAGS)
 
-    if(OV_X86_SIMD_LEVEL_UPPER STREQUAL "NATIVE")
+    if(OV_X86_BUILD_PROFILE_UPPER STREQUAL "PORTABLE")
+        set(OV_X86_DISPATCH ON)
+        if(NOT OV_X86_PORTABLE_BASELINE_UPPER STREQUAL "SSE3")
+            message(FATAL_ERROR "OV_X86_PORTABLE_BASELINE currently only supports SSE3")
+        endif()
+
+        check_cxx_compiler_flag("-msse3" HAVE_SSE3)
+        if(HAVE_SSE3)
+            list(APPEND OV_X86_COMPILE_FLAGS -msse3)
+        else()
+            message(FATAL_ERROR "Compiler does not support -msse3 for portable x86 builds")
+        endif()
+    elseif(OV_X86_BUILD_PROFILE_UPPER STREQUAL "NATIVE" OR OV_X86_SIMD_LEVEL_UPPER STREQUAL "NATIVE")
         check_cxx_compiler_flag("-march=native" HAVE_MARCH_NATIVE)
         if(HAVE_MARCH_NATIVE)
             list(APPEND OV_X86_COMPILE_FLAGS -march=native)
         else()
-            message(WARNING "-march=native is not supported by this compiler; falling back to AVX2")
+            message(WARNING "-march=native is not supported by this compiler; falling back to fixed AVX2")
+            set(OV_X86_BUILD_PROFILE_UPPER "FIXED")
             set(OV_X86_SIMD_LEVEL_UPPER "AVX2")
         endif()
     endif()
 
-    if(OV_X86_SIMD_LEVEL_UPPER STREQUAL "AVX512")
+    if(OV_X86_BUILD_PROFILE_UPPER STREQUAL "FIXED" AND OV_X86_SIMD_LEVEL_UPPER STREQUAL "AVX512")
         foreach(FLAG -mavx512f -mavx512bw -mavx512dq -mavx512vl)
             string(REPLACE "-" "_" FLAG_VAR_SUFFIX "${FLAG}")
             set(FLAG_VAR "HAVE_${FLAG_VAR_SUFFIX}")
@@ -36,7 +71,7 @@ if(OV_PLATFORM_X86)
             endif()
             list(APPEND OV_X86_COMPILE_FLAGS ${FLAG})
         endforeach()
-    elseif(OV_X86_SIMD_LEVEL_UPPER STREQUAL "AVX2")
+    elseif(OV_X86_BUILD_PROFILE_UPPER STREQUAL "FIXED" AND OV_X86_SIMD_LEVEL_UPPER STREQUAL "AVX2")
         check_cxx_compiler_flag("-mavx2" HAVE_MAVX2)
         if(HAVE_MAVX2)
             list(APPEND OV_X86_COMPILE_FLAGS -mavx2)
@@ -55,7 +90,7 @@ if(OV_PLATFORM_X86)
         endif()
     endif()
 
-    if(OV_X86_SIMD_LEVEL_UPPER STREQUAL "SSE3")
+    if(OV_X86_BUILD_PROFILE_UPPER STREQUAL "FIXED" AND OV_X86_SIMD_LEVEL_UPPER STREQUAL "SSE3")
         check_cxx_compiler_flag("-msse3" HAVE_SSE3)
         if(HAVE_SSE3)
             list(APPEND OV_X86_COMPILE_FLAGS -msse3)
@@ -69,7 +104,41 @@ if(OV_PLATFORM_X86)
         add_compile_options(${OV_X86_COMPILE_FLAGS})
     endif()
 
-    message(STATUS "OpenViking x86 SIMD level: ${OV_X86_SIMD_LEVEL_UPPER}")
+    if(OV_X86_DISPATCH)
+        add_compile_definitions(OV_X86_RUNTIME_DISPATCH=1)
+        check_cxx_compiler_flag("-mavx2" HAVE_PORTABLE_MAVX2)
+        if(HAVE_PORTABLE_MAVX2)
+            set_source_files_properties(${OV_X86_AVX2_DISPATCH_SOURCES}
+                PROPERTIES COMPILE_OPTIONS "-mavx2")
+            add_compile_definitions(OV_X86_AVX2_DISPATCH_COMPILED=1)
+        endif()
+
+        set(OV_X86_AVX512_COMPILE_FLAGS)
+        set(OV_CAN_BUILD_AVX512_DISPATCH ON)
+        foreach(FLAG -mavx512f -mavx512bw -mavx512dq -mavx512vl)
+            string(REPLACE "-" "_" FLAG_VAR_SUFFIX "${FLAG}")
+            set(FLAG_VAR "HAVE_PORTABLE_${FLAG_VAR_SUFFIX}")
+            check_cxx_compiler_flag("${FLAG}" ${FLAG_VAR})
+            if(${FLAG_VAR})
+                list(APPEND OV_X86_AVX512_COMPILE_FLAGS ${FLAG})
+            else()
+                set(OV_CAN_BUILD_AVX512_DISPATCH OFF)
+            endif()
+        endforeach()
+
+        if(OV_CAN_BUILD_AVX512_DISPATCH)
+            set_source_files_properties(${OV_X86_AVX512_DISPATCH_SOURCES}
+                PROPERTIES COMPILE_OPTIONS "${OV_X86_AVX512_COMPILE_FLAGS}")
+            add_compile_definitions(OV_X86_AVX512_DISPATCH_COMPILED=1)
+        endif()
+    endif()
+
+    message(STATUS "OpenViking x86 build profile: ${OV_X86_BUILD_PROFILE_UPPER}")
+    if(OV_X86_DISPATCH)
+        message(STATUS "OpenViking x86 portable baseline: ${OV_X86_PORTABLE_BASELINE_UPPER}")
+    else()
+        message(STATUS "OpenViking x86 SIMD level: ${OV_X86_SIMD_LEVEL_UPPER}")
+    endif()
 endif()
 
 set(CMAKE_CXX_STANDARD 17)
@@ -153,6 +222,20 @@ file(GLOB_RECURSE ALL_SOURCES
     "common/*.cpp"
 )
 
+list(REMOVE_ITEM ALL_SOURCES ${OV_X86_PORTABLE_OPTIONAL_SOURCES})
+
+set(OV_X86_PORTABLE_SOURCES)
+if(OV_PLATFORM_X86 AND OV_X86_DISPATCH)
+    if(HAVE_PORTABLE_MAVX2)
+        list(APPEND OV_X86_PORTABLE_SOURCES ${OV_X86_AVX2_DISPATCH_SOURCES})
+    endif()
+    if(OV_CAN_BUILD_AVX512_DISPATCH)
+        list(APPEND OV_X86_PORTABLE_SOURCES ${OV_X86_AVX512_DISPATCH_SOURCES})
+    endif()
+endif()
+
+list(APPEND ALL_SOURCES ${OV_X86_PORTABLE_SOURCES})
+
 add_library(
     engine_impl
     STATIC