Star76
81
代码
代码
Issues16
Pull Requests13
流水线
项目讨论
Wiki
分析
Star76
81
ascend-robotascend-robot【docs】文档翻译英文版合入
0ac6a803创建于 6月26日历史提交

Index SDK

Latest Updates

  • [Dec. 30, 2025]: 🚀 Index SDK is released as open source.

Introduction

Index SDK is a heterogeneous retrieval acceleration framework based on Faiss for Ascend NPUs. It provides high-performance retrieval for massive datasets in high-dimensional spaces. It uses Faiss-style C++, combines TBE with Ascend C operator development, and supports the Arm and x86_64 platforms. You can build retrieval systems for specific application scenarios on this framework. For details, see Introduction.

Zread     DeepWiki

Directory Structure

├── build
├── feature_retrieval
├── ivfsp_impl
├── ivfsp_utils
├── vsa_hpp
└── vstar_great_impl

Version Description

The release notes for Index SDK include software version compatibility and the feature changes in each version. For details, see Release Notes.

Environment Deployment

This section describes how to install Index SDK. For details, see Installation Guide.

  1. Install the NPU driver, firmware, and CANN.

    Software Type Package Name How to Obtain
    NPU driver Ascend-hdk-xxx-npu-driver_{version}_linux-{arch}.run Download from the Ascend Community.
    NPU firmware Ascend-hdk-xxx-npu-firmware_{version}.run Download from the Ascend Community.
    CANN package Ascend-cann-toolkit_{version}_linux-{arch}.run Download from the Ascend Community.
    Open-mode scenario package Ascend-cann-device-sdk_{version}_linux-{arch}.run Apply for access to the commercial-version download in the Ascend Community.

  2. Install dependencies.

    If you run the following bash build/build.sh build process, you can skip this step. If the script encounters network issues when downloading OpenBLAS or Faiss, manually download the installation package to the project root directory.

    To install the runtime and build dependencies manually, run bash build/install_deps.sh. To install the UT runtime dependencies, run bash build/install_deps.sh ut.

  3. Install Index SDK.

Build Process

This section uses the matching packages for CANN 8.3.RC2 as an example to describe how to build Index SDK from source. The NPU driver, firmware, and CANN package can be downloaded from the Ascend Community. For the open-mode scenario package, log in to https://support.huawei.com, search for CANN 8.3.RC2, and request the commercial-version download on the relevant page.

  1. Run the build process.

    Run the following command to build:

    bash build/build.sh

  2. The generated .run package is in the build/output directory: Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run

  3. Run the test cases.

    Run the following command to run the test cases:

    bash build/build.sh ut

Quick Start

Index SDK provides a simple example that helps users quickly get started with the retrieval workflow in Index SDK. For details, see Usage Example.

Features

Security Statement

Security requirements: When you use APIs to read a file, ensure that the file owner is you and that the permissions are no greater than 640 to avoid privilege escalation and other security issues. Software code or programs downloaded from external sources may be risky. You are responsible for ensuring their security.

For details, see Security Hardening and Appendix.

Branch Maintenance Strategy

The maintenance phases of version branches are as follows:

Status Time Description
Planning 1 to 3 months Planned features
Development 3 months Develop new features, fix issues, and release new versions regularly.
Maintenance 3 to 12 months Regular branches are maintained for 3 months, and long-term support branches are maintained for 12 months. Major bugs are fixed. No new features are merged. Patch versions are released based on the impact of the bug.
End of Life (EOL) N/A The branch no longer accepts any changes.

Version Maintenance Strategy

Version Maintenance Strategy Current Status Release Date Next Status EOL Date
master Long-term support Development 2025-12-30 -

License

Index SDK is licensed under Mulan PSL v2. The corresponding license text is available in LICENSE.

The documents in the docs directory of Index SDK are licensed under CC-BY 4.0. For details, see LICENSE.

Contribution Statement

  1. Submit bug reports: If you find a vulnerability in Index SDK that is not a security issue, search the Issues list in the Index SDK repository first to check whether the vulnerability has already been reported. If you cannot find it, create a new Issue. If you find a security issue, do not make it public. See the security issue handling process. Bug reports should include complete information.

  2. Security issue handling: For security issues in this project, notify the core project team by email for confirmation and handling.

  3. Resolve existing issues: You can find issues that need attention by checking the repository Issues list, and you can try to resolve one of them.

  4. How to propose a new feature: Use the Feature label in Issues. We regularly review and confirm development.

  5. Start contributing:

    1. Fork the repository.
    2. Clone it locally.
    3. Create a development branch.
    4. Run local self-tests. Before submitting, pass all existing unit tests and add new unit tests for the issue you want to fix.
    5. Commit your code.
    6. Open a Pull Request.
    7. Review the code. Revise the code according to the review comments and push the updates again. This process may take multiple rounds.
    8. When your PR receives enough reviewer approvals, the committer performs the final review.
    9. After the review and tests pass, CI merges your PR into the main branch of the project.

Suggestions and Communication

Everyone is welcome to contribute to the community. Before contributing, please sign the Contributor License Agreement (CLA). If you have any questions or suggestions, submit them through GitCode Issues, and we will reply as soon as possible. Thank you for your support.