feat(vectordb)Migrate vectordb engine to abi3 packaging

.github/workflows/_build.yml

@@ -12,7 +12,7 @@ on:
         description: 'JSON string of Python versions'
         required: false
         type: string
-        default: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
+        default: '["3.10"]'
       build_sdist:
         description: 'Whether to build source distribution'
         required: false
@@ -42,7 +42,7 @@ on:
       python_json:
         description: 'JSON string of Python versions'
         required: false
-        default: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
+        default: '["3.10"]'
 
 jobs:
   build-sdist:
@@ -218,7 +218,7 @@ jobs:
       run: uv sync --frozen
 
     - name: Install build dependencies
-      run: uv pip install setuptools setuptools_scm pybind11 cmake wheel build
+      run: uv pip install setuptools setuptools_scm cmake wheel build
 
     - name: Resolve OpenViking version for Rust CLI (Linux)
       shell: bash
@@ -375,7 +375,7 @@ jobs:
       run: uv sync --frozen
 
     - name: Install build dependencies
-      run: uv pip install setuptools setuptools_scm pybind11 cmake wheel build
+      run: uv pip install setuptools setuptools_scm cmake wheel build
 
     - name: Resolve OpenViking version for Rust CLI (macOS/Windows)
       shell: bash
@@ -442,53 +442,3 @@ jobs:
         VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)
         echo "Build Version: $VERSION"
         echo "::notice::Build Wheel Version (${{ matrix.os == 'macos-14' && 'macOS arm64 (macos-14)' || matrix.os == 'macos-15-intel' && 'macOS x86_64 (macos-15-intel)' || matrix.os == 'windows-latest' && 'Windows x86_64 (windows-latest)' || matrix.os }} py${{ matrix.python-version }}): $VERSION"
-
-  verify-macos-14-wheel-on-macos-15:
-    name: Verify macOS 14 arm64 wheel installs on macOS 15
-    needs: [build-other]
-    if: >-
-      inputs.build_wheels &&
-      contains(inputs.os_json, 'macos-14') &&
-      contains(inputs.python_json, '3.12')
-    runs-on: macos-15
-    steps:
-    - name: Set up Python 3.12
-      uses: actions/setup-python@v6
-      with:
-        python-version: '3.12'
-
-    - name: Download macOS arm64 wheel artifact
-      uses: actions/download-artifact@v8
-      with:
-        name: python-package-distributions-macos-arm64-3.12
-        path: dist/
-
-    - name: Install built wheel
-      shell: bash
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install dist/*.whl
-
-    - name: Smoke test native extension loading
-      shell: bash
-      run: |
-        python - <<'PY'
-        import importlib
-        import importlib.util
-
-        import openviking.storage.vectordb.engine as engine
-
-        native_spec = importlib.util.find_spec("openviking.storage.vectordb.engine._native")
-        if native_spec is None or native_spec.origin is None:
-            raise SystemExit("openviking storage native backend extension was not installed")
-
-        native_module = importlib.import_module("openviking.storage.vectordb.engine._native")
-        if engine.ENGINE_VARIANT != "native":
-            raise SystemExit(
-                f"expected native engine variant on macOS arm64 wheel, got {engine.ENGINE_VARIANT}"
-            )
-
-        print(f"Loaded runtime engine variant {engine.ENGINE_VARIANT}")
-        print(f"Loaded native extension from {native_spec.origin}")
-        print(f"Imported backend module {native_module.__name__}")
-        PY

.github/workflows/_codeql.yml

@@ -47,7 +47,7 @@ jobs:
     - name: Install dependencies
       run: |
         uv sync --frozen
-        uv pip install setuptools setuptools_scm pybind11 cmake wheel
+        uv pip install setuptools setuptools_scm cmake wheel
 
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v4

.github/workflows/_test_full.yml

@@ -78,7 +78,7 @@ jobs:
       run: uv sync --frozen --extra test
 
     - name: Install build dependencies
-      run: uv pip install setuptools setuptools_scm pybind11 cmake wheel
+      run: uv pip install setuptools setuptools_scm cmake wheel
 
     - name: Build C++ extensions
       run: uv run python setup.py build_ext --inplace

.github/workflows/_test_lite.yml

@@ -78,7 +78,7 @@ jobs:
       run: uv sync --frozen --extra test
 
     - name: Install build dependencies
-      run: uv pip install setuptools setuptools_scm pybind11 cmake wheel
+      run: uv pip install setuptools setuptools_scm cmake wheel
 
     - name: Build C++ extensions
       run: uv run python setup.py build_ext --inplace

.github/workflows/release.yml

@@ -34,7 +34,7 @@ on:
         description: 'JSON string of Python versions (Manual only)'
         required: false
         type: string
-        default: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
+        default: '["3.10"]'
 
 permissions:
   contents: write
@@ -48,7 +48,7 @@ jobs:
     uses: ./.github/workflows/_build.yml
     with:
       os_json: ${{ inputs.os_json || '["ubuntu-24.04", "ubuntu-24.04-arm", "macos-14", "macos-15-intel", "windows-latest"]' }}
-      python_json: ${{ inputs.python_json || '["3.10", "3.11", "3.12", "3.13", "3.14"]' }}
+      python_json: ${{ inputs.python_json || '["3.10"]' }}
       build_sdist: ${{ github.event_name == 'release' || inputs.build_sdist != false }}
       build_wheels: ${{ github.event_name == 'release' || inputs.build_wheels != false }}
 

CONTRIBUTING.md

@@ -163,7 +163,7 @@ openviking/
 │       ├── src/          # CLI source code
 │       └── install.sh    # Quick install script
 │
-├── src/                  # C++ extensions (pybind11)
+├── src/                  # C++ extension sources (Python abi3)
 │
 ├── tests/                # Test suite
 │   ├── client/           # Client tests

CONTRIBUTING_CN.md

@@ -163,7 +163,7 @@ openviking/
 │       ├── src/          # CLI 源码
 │       └── install.sh    # 一键安装脚本
 │
-├── src/                  # C++ 扩展 (pybind11)
+├── src/                  # C++ 扩展源码（Python abi3）
 │
 ├── tests/                # 测试套件
 │   ├── client/           # 客户端测试

CONTRIBUTING_JA.md

@@ -165,7 +165,7 @@ openviking/
 │       ├── src/          # CLIソースコード
 │       └── install.sh    # クイックインストールスクリプト
 │
-├── src/                  # C++拡張（pybind11）
+├── src/                  # C++拡張ソース（Python abi3）
 │
 ├── tests/                # テストスイート
 │   ├── client/           # クライアントテスト

examples/cloud/bob.py

@@ -128,7 +128,7 @@ def main():
                 "本地开发步骤：1) 安装 Python 3.10+ 和 uv "
                 "2) git clone 后执行 uv sync 安装依赖 "
                 "3) 复制 examples/ov.conf.example 为 ~/.openviking/ov.conf 填入 API Key "
-                "4) 运行 openviking-server 启动开发服务。C++ 扩展需要 cmake 和 pybind11。",
+                "4) 运行 openviking-server 启动开发服务。构建 abi3 C++ 扩展需要 cmake。",
             ),
             ("user", "测试怎么跑？"),
             (

openviking/storage/vectordb/README.md

@@ -11,7 +11,7 @@ OpenViking 项目的高性能向量数据库模块，专为 AI Agent 场景设
 - **灵活的存储模式**：支持内存模式（Volatile）和持久化模式（Persistent）
 - **TTL 自动过期**：支持数据生存时间管理，自动清理过期数据
 - **索引自动重建**：后台任务自动检测和重建索引
-- **高性能**：核心引擎基于 C++ 实现，使用 pybind11 绑定
+- **高性能**：核心引擎基于 C++ 实现，使用 Python abi3 扩展绑定
 - **线程安全**：关键数据结构支持并发访问
 
 ## 架构原理
@@ -30,7 +30,7 @@ Collection Layer (集合管理、数据操作、索引协调)
 Index Layer  Storage Layer
 (向量检索)    (三表存储)
    ↓           ↓
-C++ Engine (pybind11 绑定)
+C++ Engine (abi3 绑定)
 ```
 
 ### 三表存储模型

openviking/storage/vectordb/engine/__init__.py

@@ -8,8 +8,12 @@
 import importlib.util
 import os
 import platform
+import sys
+from pathlib import Path
 from types import ModuleType
 
+from ._python_api import build_abi3_exports
+
 _BACKEND_MODULES = {
     "x86_sse3": "_x86_sse3",
     "x86_avx2": "_x86_avx2",
@@ -115,10 +119,37 @@ def _select_variant() -> tuple[str | None, tuple[str, ...], str | None]:
 
 
 def _load_backend(variant: str) -> ModuleType:
-    return importlib.import_module(f".{_BACKEND_MODULES[variant]}", __name__)
+    module_name = _BACKEND_MODULES[variant]
+    module_path = Path(__file__).resolve().parent
+    qualified_name = f"{__name__}.{module_name}"
+
+    if qualified_name in sys.modules:
+        return sys.modules[qualified_name]
+
+    for suffix in importlib.machinery.EXTENSION_SUFFIXES:
+        if "abi3" not in suffix:
+            continue
+        candidate = module_path / f"{module_name}{suffix}"
+        if not candidate.exists():
+            continue
+        spec = importlib.util.spec_from_file_location(qualified_name, candidate)
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[qualified_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    return importlib.import_module(f".{module_name}", __name__)
 
 
 def _export_backend(module: ModuleType) -> tuple[str, ...]:
+    if getattr(module, "_ENGINE_BACKEND_API", None) == "abi3-v1":
+        exports = build_abi3_exports(module)
+        for name, value in exports.items():
+            globals()[name] = value
+        return tuple(exports)
+
     names = getattr(module, "__all__", None)
     if names is None:
         names = tuple(name for name in dir(module) if not name.startswith("_"))