HierarchicalKV is a part of NVIDIA Merlin and provides hierarchical key-value storage to meet RecSys requirements.

The key capability of HierarchicalKV is to store key-value (feature-embedding) on high-bandwidth memory (HBM) of GPUs and in host memory.

You can also use the library for generic key-value storage.

When building large recommender systems, machine learning (ML) engineers face the following challenges:

• GPUs are needed, but HBM on a single GPU is too small for the large DLRMs that scale to several terabytes.
• Improving communication performance is getting more difficult in larger and larger CPU clusters.
• It is difficult to efficiently control consumption growth of limited HBM with customized strategies.
• Most generic key-value libraries provide low HBM and host memory utilization.

HierarchicalKV alleviates these challenges and helps the machine learning engineers in RecSys with the following benefits:

• Supports training large RecSys models on HBM and host memory at the same time.
• Provides better performance by full bypassing CPUs and reducing the communication workload.
• Implements table-size restraint strategies that are based on LRU or customized strategies. The strategies are implemented by CUDA kernels.
• Operates at a high working-status load factor that is close to 1.0.

• Buckets are locally ordered
• Store keys and values separately
• Store all the keys in HBM
• Build-in and customizable eviction strategy

HierarchicalKV makes NVIDIA GPUs more suitable for training large and super-large models of search, recommendations, and advertising. The library simplifies the common challenges to building, evaluating, and serving sophisticated recommenders models.

The main classes and structs are below, but reading the comments in the source code is recommended:

• class HashTable
• class EvictStrategy
• struct HashTableOptions

For regular API doc, please refer to API Docs

industry-validated means the API has been well-tested and verified in at least one real-world scenario.

The score is introduced to define the importance of each key, the larger, the more important, the less likely they will be evicted. Eviction only happens when a bucket is full. The score_type must be uint64_t. For more detail, please refer to class EvictStrategy.

• Note:
  • The insert-like APIs mean the APIs of insert_or_assign, insert_and_evict, find_or_insert, accum_or_assign, and find_or_insert.
  • The global_epoch should be maintained by the caller and input as the input parameter of insert-like APIs.

It's recommended to keep the default configuration for the options ending with *.

For more detail, please refer to struct HashTableOptions.

#include "merlin_hashtable.cuh"


using TableOptions = nv::merlin::HashTableOptions;
using EvictStrategy = nv::merlin::EvictStrategy;

int main(int argc, char *argv[])
{
  using K = uint64_t;
  using V = float;
  using S = uint64_t;
  
  // 1. Define the table and use LRU eviction strategy.
  using HKVTable = nv::merlin::HashTable<K, V, S, EvictStrategy::kLru>;
  std::unique_ptr<HKVTable> table = std::make_unique<HKVTable>();
  
  // 2. Define the configuration options.
  TableOptions options;
  options.init_capacity = 16 * 1024 * 1024;
  options.max_capacity = options.init_capacity;
  options.dim = 16;
  options.max_hbm_for_vectors = nv::merlin::GB(16);
  
  
  // 3. Initialize the table memory resource.
  table->init(options);
  
  // 4. Use table to do something.
  
  return 0;
}

• The key_type must be int64_t or uint64_t.
• The score_type must be uint64_t.
• The keys of 0xFFFFFFFFFFFFFFFC, 0xFFFFFFFFFFFFFFFD, 0xFFFFFFFFFFFFFFFE, and 0xFFFFFFFFFFFFFFFF are reserved for internal using.

HierarchicalKV is co-maintianed by NVIDIA Merlin Team and NVIDIA product end-users, and also open for public contributions, bug fixes, and documentation. [Contribute]

Basically, HierarchicalKV is a headers only library, the commands below only create binaries for benchmark and unit testing.

Your environment must meet the following requirements:

• CUDA version >= 11.2
• NVIDIA GPU with compute capability 8.0, 8.6, 8.7 or 9.0
• GCC supports `C++17' standard or later.
• Bazel version >= 3.7.2 (Bazel compile only)

git clone --recursive https://github.com/NVIDIA-Merlin/HierarchicalKV.git
cd HierarchicalKV && mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -Dsm=80 .. && make -j

For Benchmark:

./merlin_hashtable_benchmark

For Unit Test:

./merlin_hashtable_test

• DON'T use the option of --recursive for git clone.
• Please modify the environment variables in the .bazelrc file in advance if using the customized docker images.
• The docker images maintained on nvcr.io/nvidia/tensorflow are highly recommended.

Pull the docker image:

docker pull nvcr.io/nvidia/tensorflow:22.09-tf2-py3
docker run --gpus all -it --rm nvcr.io/nvidia/tensorflow:22.09-tf2-py3

Compile in docker container:

git clone https://github.com/NVIDIA-Merlin/HierarchicalKV.git
cd HierarchicalKV && bash bazel_build.sh

For Benchmark:

./benchmark_util

• GPU: 1 x NVIDIA A100 80GB PCIe: 8.0
• Key Type = uint64_t
• Value Type = float32 * {dim}
• Key-Values per OP = 1048576
• Evict strategy: LRU
• λ: load factor
• find* means the find API that directly returns the addresses of values.
• find_or_insert* means the find_or_insert API that directly returns the addresses of values.
• Throughput Unit: Billion-KV/second

• dim = 8, capacity = 128 Million-KV, HBM = 4 GB, HMEM = 0 GB

• dim = 32, capacity = 128 Million-KV, HBM = 16 GB, HMEM = 0 GB

• dim = 64, capacity = 64 Million-KV, HBM = 16 GB, HMEM = 0 GB

• dim = 64, capacity = 128 Million-KV, HBM = 16 GB, HMEM = 16 GB

• dim = 64, capacity = 512 Million-KV, HBM = 32 GB, HMEM = 96 GB

If you encounter any issues or have questions, go to https://github.com/NVIDIA-Merlin/HierarchicalKV/issues and submit an issue so that we can provide you with the necessary resolutions and answers.

We are very grateful to external initial contributors @Zhangyafei and @Lifan for their design, coding, and review work.

Apache License 2.0