Debian Codegraph @

c_api/INSTALL.md

raw
1 Faiss C API
2 ===========
3
4 Faiss provides a pure C interface, which can subsequently be used either in pure C programs or to produce bindings for programming languages with Foreign Function Interface (FFI) support. Although this is not required for the Python interface, some other programming languages (e.g. Rust and Julia) do not have SWIG support.
5
6 Compilation instructions
7 ------------------------
8
9 The C API is built as part of the main Faiss build using CMake. From the root of the Faiss repository:
10
11 ``` shell
12 # Configure with C API enabled
13 $ cmake -B build -DFAISS_ENABLE_C_API=ON .
14
15 # Build
16 $ make -C build -j faiss_c
17 ```
18
19 This builds the dynamic library `libfaiss_c.so` (or `.dylib` on macOS), containing the full implementation of Faiss and the necessary wrappers for the C interface.
20
21 To build the example program:
22
23 ``` shell
24 $ make -C build -j example_c
25 ```
26
27 The example program will be located at `build/c_api/example_c`.
28
29 Using the API
30 -------------
31
32 The C API is composed of:
33
34 - A set of C header files comprising the main Faiss interfaces, converted for use in C. Each file follows the format `«name»_c.h`, where `«name»` is the respective name from the C++ API. For example, the file [Index_c.h](./Index_c.h) file corresponds to the base `Index` API. Functions are declared with the `faiss_` prefix (e.g. `faiss_IndexFlat_new`), whereas new types have the `Faiss` prefix (e.g. `FaissIndex`, `FaissMetricType`, ...).
35 - A dynamic library, compiled from the sources in the same folder, encloses the implementation of the library and wrapper functions.
36
37 The index factory is available via the `faiss_index_factory` function in `AutoTune_c.h`:
38
39 ```c
40 FaissIndex* index = NULL;
41 int c = faiss_index_factory(&index, 64, "Flat", METRIC_L2);
42 if (c) {
43 // operation failed
44 }
45 ```
46
47 Most operations that you would find as member functions are available with the format `faiss_«classname»_«member»`.
48
49 ```c
50 idx_t ntotal = faiss_Index_ntotal(index);
51 ```
52
53 Since this is C, the index needs to be freed manually in the end:
54
55 ```c
56 faiss_Index_free(index);
57 ```
58
59 Error handling is done by examining the error code returned by operations with recoverable errors.
60 The code identifies the type of exception that rose from the implementation. Fetching the
61 corresponding error message can be done by calling the function `faiss_get_last_error()` from
62 `error_c.h`. Getter functions and `free` functions do not return an error code.
63
64 ```c
65 int c = faiss_Index_add(index, nb, xb);
66 if (c) {
67 printf("%s", faiss_get_last_error());
68 exit(-1);
69 }
70 ```
71
72 An example is included and can be built as shown in the compilation instructions above.
73
74 Building with GPU support
75 -------------------------
76
77 For GPU support, configure CMake with both GPU and C API enabled:
78
79 ``` shell
80 $ cmake -B build -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_C_API=ON .
81 $ make -C build -j gpufaiss_c
82 ```
83
84 The `libgpufaiss_c.so` dynamic library contains both GPU and CPU implementations of Faiss, which means it can be used in place of `libfaiss_c.so`. This library dynamically links with the CUDA runtime and cuBLAS.
85
86 Using the GPU with the C API
87 ----------------------------
88
89 A standard GPU resources object can be obtained by the name `FaissStandardGpuResources`:
90
91 ```c
92 FaissStandardGpuResources* gpu_res = NULL;
93 int c = faiss_StandardGpuResources_new(&gpu_res);
94 if (c) {
95 printf("%s", faiss_get_last_error());
96 exit(-1);
97 }
98 ```
99
100 Similarly to the C++ API, a CPU index can be converted to a GPU index:
101
102 ```c
103 FaissIndex* cpu_index = NULL;
104 int c = faiss_index_factory(&cpu_index, d, "Flat", METRIC_L2);
105 if (c) { /* ... */ }
106 FaissGpuIndex* gpu_index = NULL;
107 c = faiss_index_cpu_to_gpu(gpu_res, 0, cpu_index, &gpu_index);
108 if (c) { /* ... */ }
109 ```
110
111 To build the GPU example:
112
113 ``` shell
114 $ make -C build -j example_gpu_c
115 ```
116
117 The example program will be located at `build/c_api/gpu/example_gpu_c`.