Файл установки для Faiss (Fair AI Similarity Search)

Установка через Conda

Самый простой способ установки FAISS — через Anaconda. Мы регулярно загружаем стабильные версии на канал conda. FAISS conda пакет зависит от mkl и numpy пакета, поставляемого в conda.

В настоящее время мы поддерживаем faiss-cpu на платформах Linux и macOS. Мы также предоставляем faiss-gpu, скомпилированный с CUDA8.0/CUDA9.0/CUDA9.1 на системах Linux.

Вы можете легко установить его следующими командами:

# Только версия для CPU
conda install faiss-cpu -c pytorch
# Убедитесь, что у вас установлена CUDA перед установкой faiss-gpu, иначе установится версия для CPU
conda install faiss-gpu -c pytorch # [DEFAULT] Для CUDA8.0, поставляется с cudatoolkit8.0
conda install faiss-gpu cuda90 -c pytorch # Для CUDA9.0
conda install faiss-gpu cuda91 -c pytorch # Для CUDA9.1
# cuda90/cuda91 выше — это опции, они не устанавливают CUDA для вас.

Компиляция из исходного кода

Компиляция Faiss выполняется в три этапа, от самого простого к самому сложному:

1. Компиляция C++ ядра и примеров

2. Компиляция Python интерфейса

3. Компиляция GPU части

Этапы 2 и 3 зависят от 1, но они в остальном независимы.

В качестве альтернативы, все три этапа выше могут быть выполнены построением Docker образа (см. раздел "Инструкции по Docker" ниже).В качестве альтернативы, этапы 1 и 3 могут быть построены через скрипты CMake (см. ниже).

Также возможно построение чистого C-интерфейса. Этот опциональный процесс описан отдельно (пожалуйста, см. файл установки C-интерфейса).

Общие инструкции по компиляции

Faiss был протестирован только на машинах x86_64 на Linux и Mac OS.

Faiss компилируется через Makefile. Системно-зависимая конфигурация Makefile находится в файле include makefile.inc. Переменные в makefile.inc должны быть установлены вручную.

Faiss требует C++-компилятор, который понимает:

• Intel-интрузивы для SSE-инструкций
• GCC-интрузивы для инструкции popcount
• базовый OpenMP

В подпапке example_makefiles/ находятся несколько моделей для makefile.inc. Скопируйте соответствующий для вашей системы и настройте его под ваши нужды. Также есть указания для конкретных конфигураций в разделе "troubleshooting" вики. Faiss поставляется в виде архива .a, который можно связать с исполняемыми файлами или динамическими библиотеками (полезно для обёртки Python).

Шаг 1: Компиляция C++ Faiss

TL;DR: ./configure && make && make install

CPU-версия Faiss написана на C++11.

BLAS/Lapack -----------Единственными переменными, которые нужно настроить для C++ Faiss, являются флаги BLAS/Lapack (пакет программ линейной алгебры). Ему требуется флаг, указывающий, используются ли BLAS/Lapack 32- или 64-битные целые числа, а также флаги для связывания. Faiss использует Fortran 77 интерфейс BLAS/Lapack и поэтому не требует указания пути к заголовочным файлам.Существует несколько реализаций BLAS, в зависимости от операционной системы и машины. Для достижения разумной производительности библиотека BLAS должна быть многопоточной. См. примеры makefile.inc для подсказок и примеров настройки флагов, или просто запустите скрипт конфигурации:

./configure

Чтобы проверить, что флаги для связывания верны, и убедиться, используют ли реализация 32- или 64-битные целые числа, вы можете

make misc/test_blas

и запустить

./misc/test_blas

Компиляция faiss

После настройки правильных флагов BLAS библиотека должна компилироваться. Для установки выполните следующую команду:

make install

Тестирование Faiss

Примеры базового использования находятся в

demos/demo_ivfpq_indexing

, где создается небольшой индекс, данные сохраняются, и выполняются некоторые поиски. Обычное время выполнения составляет около 20 секунд. На быстрой машине с Intel MKL BLAS время выполнения составляет 2.5 секунды.

Чтобы запустить полный набор тестов:

make test

Реальные сценарии и базовые тесты

Пример, который выполняет и оценивает Faiss на SIFT1M наборе данных. Чтобы запустить его, скачайте ANN_SIFT1M набор данных с

http://corpus-texmex.irisa.fr/

и распакуйте его в подкаталог sift1M в корневом каталоге этого репозитория.

Затем скомпилируйте и запустите следующую команду (после установки faiss):

make demos
./demos/demo_sift1M

Это демонстрация продвинутого API автоматической настройки. Вы можете попробовать установить различные ключи индекса, чтобы найти структуру индекса, обеспечивающую наилучшую производительность. Интерфейс Python скомпилирован с помощью

make py

Если вы хотите скомпилировать его для другой версии Python, отличной от по умолчанию Python 2.7, в частности Python 3, переменную PYTHONCFLAGS необходимо скорректировать в makefile.inc, см. примеры.Как это работает

Интерфейс Python предоставляется с помощью SWIG (Simple Wrapper and Interface Generator) и дополнительного уровня ручных обёрток (в python/faiss.py).

SWIG генерирует два файла-обёртки: файл Python (python/swigfaiss.py) и файл C++, который должен быть скомпилирован в динамическую библиотеку (python/_swigfaiss.so). Эти файлы включены в репозиторий, поэтому запуск SWIG требуется только при изменении C++ заголовков Faiss.

Скомпилирование C++ в динамическую библиотеку требует установки:

• SHAREDFLAGS: системно-зависимых флагов для генерации динамической библиотеки

• PYTHONCFLAGS: флагов включения для Python

См. примеры makefile.inc для настройки флагов.

Тестирование Python обёртки

Часто успешная компиляция не означает, что библиотека работает, потому что отсутствующие символы обнаруживаются только во время выполнения. Вы должны быть способны загрузить динамическую библиотеку Faiss:

python -c "import faiss"

В случае неудачи, она отчетливо указывает на первый отсутствующий символ. Чтобы увидеть все отсутствующие символы (в Linux), используйте

ldd -r _swigfaiss.so

Иногда проблемы (например, с библиотеками BLAS) появляются только при вызове функций BLAS. Простой способ проверки этого:

python -c "import faiss, numpy; faiss.Kmeans(10, 20).train(numpy.random.rand(1000, 10).astype('float32'))"

Реальные тесты --------------Следующий скрипт расширяет тест demo_sift1M для нескольких типов индексов. Этот скрипт должен быть запущен из корневой директории исходного кода этого репозитория:``` mkdir tmp # графики выходных данных будут записаны здесь PYTHONPATH=. python demos/demo_auto_tune.py

Он будет проходить через несколько типов индексов и находить оптимальные точки работы. Вы можете экспериментировать с различными типами индексов.


Шаг 3: Скомпилировать GPU реализацию
====================================

В директории `gpu/` находится GPU-специфический Makefile. Он зависит от того же ../makefile.inc для системно-зависимых переменных. Вам необходимо иметь libfaiss.a из Шага 1 для работы.

Версия для GPU является надмножеством версии для CPU. В дополнение она требует компилятора CUDA и связанных библиотек (Cublas). См. пример файла makefile для настройки флагов.

nvcc-специфические флаги для передачи компилятору, основанные на вашей желаемой возможности вычислений. Поддерживается только возможность вычислений 3.5 и выше. Например, мы включаем по умолчанию:

-gencode arch=compute_35,code="compute_35" -gencode arch=compute_52,code="compute_52" -gencode arch=compute_60,code="compute_60"

Однако, посмотрите на https://developer.nvidia.com/cuda-gpus для определения необходимой вам возможности вычислений, и замените наши gencode указания на те, которые вам нужны.Большинство других флагов связаны с компилятором C++11, используемым nvcc для компиляции фактического кода на C++. Они обычно просто передаются nvcc, за исключением некоторых, которые не распознаются и которые должны быть экранированы путем добавления к ним префикса -Xcompiler. Также флаги связи, предваряемые -Wl, должны быть переданы с -Xlinker.Затем скомпилируйте с помощью

  `cd gpu; make`

Вы можете захотеть добавить `-j 10` для использования 10 потоков во время компиляции.

Тестирование GPU-реализации
------------------------------

Скомпилируйте пример с помощью

  `cd gpu; make tests/demo_ivfpq_indexing_gpu`

Это создает GPU-код, эквивалентный CPU-версии demo_ivfpq_indexing. Также показывает, как переводить индексы между CPU и GPU.

Скомпилировать Python-интерфейс с поддержкой GPU
-----------------------------------------------

Учитывая шаг 2, добавление поддержки GPU из Python довольно
прямолинейно. Запустите

`cd python; make _swigfaiss_gpu.so`

Импорт такой же для версии GPU и версии только для CPU.

`python -c "import faiss"`

Faiss пытается загрузить версию для GPU в первую очередь, и в случае неудачи,
загружает версию только для CPU. Для более детального исследования причины
неудачи, вы можете запустить:

`python -c "import _swigfaiss_gpu"`

Пример Python с поддержкой GPU
-------------------------------

Пример автоматической настройки выше также работает на GPU. Редактируйте
`demos/demo_auto_tune.py` на строке 100 значениями

```python
keys_to_test = keys_gpu
use_gpu = True

и вы можете запустить

export PYTHONPATH=.
python demos/demo_auto_tune.py

для тестирования GPU-кода.

Инструкции для Docker

Для использования GPU-возможностей Faiss вам потребуется запустить "nvidia-docker" вместо "docker". Убедитесь, что Docker (https://docs.docker.com/engine/installation/) и nvidia-docker (https://github.com/NVIDIA/nvidia-docker) установлены на вашей системе. Чтобы создать образ "faiss", выполните nvidia-docker build -t faiss .

или если вы не хотите/не нуждаетесь в клонировании исходного кода, просто выполните

nvidia-docker build -t faiss github.com/facebookresearch/faiss

Если вы хотите запустить тесты во время сборки контейнера Docker, раскомментируйте последние три шага "RUN" в файле Dockerfile. Однако вы можете захотеть запустить тесты самостоятельно, поэтому просто выполните

nvidia-docker run -ti --name faiss faiss bash

и выполните необходимые команды. Если вам нужен набор данных (например, sift1M), загрузите его внутрь созданного контейнера, или лучше, примонтируйте директорию с хоста

nvidia-docker run -ti --name faiss -v /my/host/data/folder/ann_dataset/sift/:/opt/faiss/sift1M faiss bash

Как использовать Faiss в ваших собственных проектах

C++

Файл makefile создаёт статическую и динамическую библиотеки

libfaiss.a
libfaiss.so (или libfaiss.dylib)

исполняемый файл должен быть связан с одной из этих библиотек. Если вы используете статическую версию (.a), добавьте LDFLAGS, используемые в файле Makefile.

Для распакованных только в бинарном виде дистрибутивов, файлы заголовков должны находиться в директории faiss/, чтобы их можно было включать как

#include <faiss/IndexIVFPQ.h>
#include <faiss/gpu/GpuIndexFlat.h>

Python

Чтобы импортировать Faiss в вашем собственном Python-проекте, вам нужны файлы

faiss.py
swigfaiss.py  / swigfaiss_gpu.py
_swigfaiss.so / _swigfaiss_gpu.so
```чтобы они были видны в PYTHONPATH или в текущей директории. Тогда Faiss можно использовать в Python с помощью

```python
import faiss

Инструкции по сборке с помощью CMake:

В качестве альтернативы, Faiss может быть собран с помощью экспериментальных скриптов CMake. Процесс установки похож на использование файлов Makefile. После установки необходимых зависимостей (OpenBLAS, OpenMP и CUDA, если BUILD_WITH_GPU включено), процесс сборки можно выполнить следующими командами:

mkdir build
cd build
cmake ..
make      # используйте -j для включения параллельной сборки

Примечания для сборки на Mac: Нативный компилятор на Mac не поддерживает OpenMP. Поэтому для работы на Mac вам нужно установить новый компилятор с помощью Macports или Homebrew. Например, после установки компилятора g++-mp-6 с помощью Macports (port install g++-mp-6), вам нужно задать два флага CMAKE_CXX_COMPILER и CMAKE_C_COMPILER:

cmake -DCMAKE_CXX_COMPILER=/opt/local/bin/g++-mp-6 -DCMAKE_C_COMPILER=/opt/local/bin/gcc-mp-6 ..

Аналогично можно использовать Homebrew для установки clang++ (brew install llvm) и затем установить два флага на /usr/local/opt/llvm/bin/clang++.

CMake поддерживает реализации OpenBLAS и MKL. Ограничения CMake: интерфейс Python в настоящее время НЕ поддерживается.Использование Faiss как сторонней библиотеки: Использование Faiss как сторонней библиотеки через CMake легко. Если родительский проект также собирается с помощью CMake, просто добавьте строку add_subdirectory(faiss) в CMake, где faiss — это имя подпапки. Для подключения Faiss к вашему приложению используйте``` add_executable(my_app my_app.cpp) target_link_libraries(my_app faiss gpufaiss faiss)