Evaluation library
This is the fastest way to evaluate a model. The library provides a C API and a simple C++ wrapper API. The C API interface can be accessed from any programming language.
Download
Prebuilt shared library artifacts are available.
An up-to-date list of available CatBoost releases and the corresponding binaries for different operating systems is available in the Download section of the releases page on GitHub.
Operating system | CPU architectures | GPU support using CUDA |
---|---|---|
macOS (versions currently supported by Apple) | x86_64 and arm64 | no |
Linux (compatible with manylinux2014 platform tag ) | x86_64 and aarch64 | yes |
Windows 10 and 11 | x86_64 | yes |
Note
Release binaries for x86_64 CPU architectures are built with SIMD extensions SSE2, SSE3, SSSE3, SSE4 enabled. If you need to run CatBoost on older CPUs that do not support these instruction sets build CatBoost artifacts yourself
Operating system | CPU architectures | GPU support using CUDA |
---|---|---|
Linux (compatible with manylinux2014 platform tag ) | x86_64 and aarch64 | yes |
macOS (versions currently supported by Apple) | x86_64 and arm64 | no |
Windows 10 and 11 | x86_64 | yes |
Operating system | Files |
---|---|
Linux | libcatboostmodel-linux-{cpu_arch}-{release_version}.so |
macOS | libcatboostmodel-darwin-universal2-{release_version}.dylib |
Windows | catboostmodel-windows-{cpu_arch}-{release_version}.lib and catboostmodel-windows-{cpu_arch}-{release_version}.dll |
Applying on GPU requires NVIDIA Driver of version 450.80.02 or higher.
Note
Only CUDA 11.0 is officially supported in compiled binaries for Windows. Вuild the binary from a local copy if GPU support is required and the installed version of CUDA differs from 11.0. CatBoost should work fine with CUDA 11.0 and later versions.
All necessary CUDA libraries are statically linked to the Linux and macOS binaries of the CatBoost applier library, therefore, the only installation necessary is the appropriate version of the CUDA driver.
Note
Release binaries for x86_64 CPU architectures are built with SIMD extensions SSE2, SSE3, SSSE3, SSE4 enabled. If you need to run CatBoost on older CPUs that do not support these instruction sets build library binary artifacts yourself
Build from source
Warning
CatBoost uses CMake-based build process since this commit. Previously Ya Make
(Yandex's build system) had been used.
Select the appropriate build method below accordingly.
Source code
CatBoost source code is stored as a Git repository on GitHub at https://github.com/catboost/catboost/. You can obtain a local copy of this Git repository by running the following command from a command line interpreter (you need to have Git command line tools installed):
git clone https://github.com/catboost/catboost.git
Build using CMake
Build catboostmodel
target.
Built artifacts will be in $CMAKE_BINARY_DIR/catboost/libs/model_interface
:
OS | Files |
---|---|
Linux | libcatboostmodel.so |
macOS | libcatboostmodel.dylib |
Windows | catboostmodel.lib and catboostmodel.dll |
Build catboostmodel_static
target.
Built library will consist of two parts:
- global
part. This part contains symbols that require forced initialization.
- non-global
part. All other symbols.
Built artifacts will be in $CMAKE_BINARY_DIR/catboost/libs/model_interface/static
:
OS | Files |
---|---|
Linux or macOS | libcatboostmodel_static.a , libcatboostmodel_static.global.a |
Windows | catboostmodel_static.lib , catboostmodel_static.global.lib |
Build using Ya Make
-
Open the
catboost
directory from the local copy of the CatBoost repository. -
Run the following command:
Shared libraryStatic library (only for Linux and macOS)./ya make -r [optional parameters] catboost/libs/model_interface
The output directory
catboost/libs/model_interface
will contain:OS Files Linux libcatboostmodel.so
macOS libcatboostmodel.dylib
Windows catboostmodel.lib
andcatboostmodel.dll
./ya make -r [optional parameters] catboost/libs/model_interface/static
The output directory
catboost/libs/model_interface/static
will contain a pair of artifacts:liblibcatboostmodel.o
. This part contains symbols that require forced initialization.libcatboostmodel.a
. This part contains all other symbols.
Useful parameters:
Parameter Description -DCUDA_ROOT
The path to CUDA. This parameter is required to support training on GPU. -DHAVE_CUDA=no
Disable CUDA support. This speeds up compilation.
By default, the package is built with CUDA support if CUDA Toolkit is installed.
Build using Make (Linux-only)
Warning
This approach will work only for versions prior to this commit.
For newer versions use Build with CMake
Choose the preferred way to use the evaluation library and compile it accordingly:
export CXX=/path/to/clang++
export CC=/path/to/clang
make -f make/model_interface.CLANG50-LINUX-X86_64.makefile
The output directory catboost/libs/model_interface
will contain libcatboostmodel.so
.
export CXX=/path/to/clang++
export CC=/path/to/clang
make -f make/model_interface_static.CLANG50-LINUX-X86_64.makefile
The output directory catboost/libs/model_interface/static
will contain a pair of artifacts:
liblibcatboostmodel.o
. This part contains symbols that require forced initialization.libcatboostmodel.a
. This part contains all other symbols.
Usage
The CatBoost model can be loaded from a file or initialized from the buffer memory.
C API
Perform the following steps to use this API:
-
Use the methods from the
c_api.h
file (refer to the doxygen-style documentation for details).Sample C code without include statements:
float floatFeatures[100]; char* catFeatures[2] = {"1", "2"}; double result[1]; ModelCalcerHandle modelHandle; modelHandle = ModelCalcerCreate(); if (!LoadFullModelFromFile(modelHandle, "model.cbm")) { printf("LoadFullModelFromFile error message: %s\n", GetErrorString()); } if (!CalcModelPrediction( modelHandle, 1, &floatFeatures, 100, &catFeatures, 2, &result, 1 )) { printf("CalcModelPrediction error message: %s\n", GetErrorString()); } ModelCalcerDelete(modelHandle);
-
Add the required libraries to the linking command.
Linker is often invoked through the compiler call, examples below assume that.
Shared libraryStatic library built using CMakeStatic library built using Ya Make or Make (Linux or macOS only)-
Linux or macOS
Example:
clang++ <your sources and options> -L<path_to_dir_with_libcatboostmodel> -lcatboostmodel
-
Windows
Example:
cl.exe <your sources and options> /link <path_to_dir_with_libcatboostmodel>\catboostmodel.lib
The shared library must be accessible from the dynamic library loader search path. See your operating system documentation for the details.
Add both
global
and non-global
parts to the linker input.global
part requires passing special platform-specific flags to force the required initialization of symbols.See per-platform examples below:
-
Linux
On Linux additional libraries
libdl
andlibpthread
have to be added to the linker input as well.clang++ <your sources and options> -Wl,--whole-archive <catboost_lib_dir>/libcatboostmodel_static.global.a -Wl,--no-whole-archive <catboost_lib_dir>/libcatboostmodel_static.a -lpthread -ldl
-
macOS
clang++ <your sources and options> <catboost_lib_dir>/libcatboostmodel_static.a -Wl,-force_load,<catboost_lib_dir>/libcatboostmodel_static.global.a
-
Windows
When using
c_api.h
with the static library the additional defineCATBOOST_API_STATIC_LIB
is required.cl.exe <your sources and options> /DCATBOOST_API_STATIC_LIB /link /WHOLEARCHIVE:<catboost_lib_dir>\catboostmodel_static.global.lib <catboost_lib_dir>\catboostmodel_static.lib
Add both
liblibcatboostmodel.o
andlibcatboostmodel.a
to the linker input.On Linux additional libraries
libdl
andlibpthread
have to be added to the linker input as well.Example:
clang++ <your sources and options> liblibcatboostmodel.o libcatboostmodel.a -ldl -lpthread
-
C++ wrapper API
A C++ wrapper for the C API interface is also available.
Refer to the wrapped_calcer.h file and the sample CMake project in the CatBoost repository for more details.
Usage example:
ModelCalcerWrapper calcer("model.cbm");
std::vector<float> floatFeatures(100);
std::vector<std::string> catFeatures = {"one", "two", "three"};
std::cout << calcer.Calc(floatFeatures, catFeatures) << std::endl;
ModelCalcerWrapper
also has a constructor to read data from the memory buffer.