#include "llama-kv-cache.h" #include "llama-impl.h" #include "llama-batch.h" #include "llama-cparams.h" #include "llama-model.h" #include #include #include static const llama_kv_cache_slot_info llama_kv_cache_slot_info_failed{false}; bool llama_kv_cache::init( const llama_model & model, const llama_cparams & cparams, ggml_type type_k, ggml_type type_v, uint32_t kv_size, bool offload) { const struct llama_hparams & hparams = model.hparams; const int32_t n_layer = hparams.n_layer; has_shift = false; recurrent = llama_model_is_recurrent(&model); v_trans = !recurrent && !cparams.flash_attn; can_shift = !recurrent && model.arch != LLM_ARCH_DEEPSEEK2; // not supported due to MLA LLAMA_LOG_INFO("%s: kv_size = %d, offload = %d, type_k = '%s', type_v = '%s', n_layer = %d, can_shift = %d\n", __func__, kv_size, offload, ggml_type_name(type_k), ggml_type_name(type_v), n_layer, can_shift); head = 0; size = kv_size; used = 0; this->type_k = type_k; this->type_v = type_v; cells.clear(); cells.resize(kv_size); // create a context for each buffer type std::map ctx_map; auto ctx_for_buft = [&](ggml_backend_buffer_type_t buft) -> ggml_context * { auto it = ctx_map.find(buft); if (it == ctx_map.end()) { struct ggml_init_params params = { /*.mem_size =*/ size_t(2u*n_layer*ggml_tensor_overhead()), /*.mem_buffer =*/ NULL, /*.no_alloc =*/ true, }; ggml_context * ctx = ggml_init(params); if (!ctx) { return nullptr; } ctx_map[buft] = ctx; ctxs.emplace_back(ctx); return ctx; } return it->second; }; k_l.reserve(n_layer); v_l.reserve(n_layer); for (int i = 0; i < n_layer; i++) { const uint32_t n_embd_k_gqa = hparams.n_embd_k_gqa(i) + hparams.n_embd_k_s(); const uint32_t n_embd_v_gqa = hparams.n_embd_v_gqa(i) + hparams.n_embd_v_s(); const char * dev_name = "CPU"; ggml_backend_buffer_type_t buft; if (offload) { auto * dev = model.dev_layer(i); buft = ggml_backend_dev_buffer_type(dev); dev_name = ggml_backend_dev_name(dev); } else { buft = ggml_backend_cpu_buffer_type(); } LLAMA_LOG_DEBUG("%s: layer %3d: n_embd_k_gqa = %d, n_embd_v_gqa = %d, dev = %s\n", __func__, i, n_embd_k_gqa, n_embd_v_gqa, dev_name); ggml_context * ctx = ctx_for_buft(buft); if (!ctx) { LLAMA_LOG_ERROR("%s: failed to create ggml context for kv cache\n", __func__); return false; } ggml_tensor * k = ggml_new_tensor_1d(ctx, type_k, n_embd_k_gqa*kv_size); ggml_tensor * v = ggml_new_tensor_1d(ctx, type_v, n_embd_v_gqa*kv_size); ggml_format_name(k, "cache_k_l%d", i); ggml_format_name(v, "cache_v_l%d", i); k_l.push_back(k); v_l.push_back(v); } // allocate tensors and initialize the buffers to avoid NaNs in the padding for (auto it : ctx_map) { auto * buft = it.first; auto * ctx = it.second; ggml_backend_buffer_t buf = ggml_backend_alloc_ctx_tensors_from_buft(ctx, buft); if (!buf) { LLAMA_LOG_ERROR("%s: failed to allocate buffer for kv cache\n", __func__); return false; } ggml_backend_buffer_clear(buf, 0); LLAMA_LOG_INFO("%s: %10s KV buffer size = %8.2f MiB\n", __func__, ggml_backend_buffer_name(buf), ggml_backend_buffer_get_size(buf)/1024.0/1024.0); bufs.emplace_back(buf); } return true; } int32_t llama_kv_cache::n_tokens() const { int32_t result = 0; for (uint32_t i = 0; i < size; i++) { result += cells[i].seq_id.size(); } return result; } size_t llama_kv_cache::total_size() const { size_t size = 0; for (const auto & buf : bufs) { size += ggml_backend_buffer_get_size(buf.get()); } return size; } llama_pos llama_kv_cache::pos_max() const { llama_pos pos_max = -1; for (const auto & cell : cells) { pos_max = std::max(pos_max, cell.pos); } return pos_max; } void llama_kv_cache::clear() { for (int32_t i = 0; i < (int32_t) size; ++i) { cells[i].pos = -1; cells[i].seq_id.clear(); cells[i].src = -1; cells[i].tail = -1; } head = 0; used = 0; for (auto & buf : bufs) { ggml_backend_buffer_clear(buf.get(), 0); } } bool llama_kv_cache::seq_rm(llama_seq_id seq_id, llama_pos p0, llama_pos p1) { uint32_t new_head = size; if (p0 < 0) { p0 = 0; } if (p1 < 0) { p1 = std::numeric_limits::max(); } // models like Mamba or RWKV can't have a state partially erased if (recurrent) { if (seq_id >= (int64_t) size) { // could be fatal return false; } if (0 <= seq_id) { int32_t & tail_id = cells[seq_id].tail; if (tail_id >= 0) { const llama_kv_cell & cell = cells[tail_id]; // partial intersection is invalid if ((0 < p0 && p0 <= cell.pos) || (0 < p1 && p1 <= cell.pos)) { return false; } // invalidate tails which will be cleared if (p0 <= cell.pos && cell.pos < p1) { tail_id = -1; } } } else { // seq_id is negative, then the range should include everything or nothing if (p0 != p1 && (p0 != 0 || p1 != std::numeric_limits::max())) { return false; } } } for (uint32_t i = 0; i < size; ++i) { if (cells[i].pos >= p0 && cells[i].pos < p1) { if (seq_id < 0) { cells[i].seq_id.clear(); } else if (cells[i].has_seq_id(seq_id)) { cells[i].seq_id.erase(seq_id); } else { continue; } if (cells[i].is_empty()) { // keep count of the number of used cells if (cells[i].pos >= 0) { used--; } cells[i].pos = -1; cells[i].src = -1; if (new_head == size) { new_head = i; } } } } // If we freed up a slot, set head to it so searching can start there. if (new_head != size && new_head < head) { head = new_head; } return true; } void llama_kv_cache::seq_cp(llama_seq_id seq_id_src, llama_seq_id seq_id_dst, llama_pos p0, llama_pos p1) { if (seq_id_src == seq_id_dst) { return; } if (p0 < 0) { p0 = 0; } if (p1 < 0) { p1 = std::numeric_limits::max(); } if (recurrent) { if ((uint32_t) seq_id_dst < size && (uint32_t) seq_id_src < size) { llama_kv_cell & tail_src = cells[seq_id_src]; llama_kv_cell & tail_dst = cells[seq_id_dst]; if (tail_dst.tail >= 0) { // clear destination seq_id if it wasn't empty llama_kv_cell & cell_dst = cells[tail_dst.tail]; cell_dst.seq_id.erase(seq_id_dst); tail_dst.tail = -1; if (cell_dst.seq_id.empty()) { cell_dst.pos = -1; cell_dst.delta = -1; cell_dst.src = -1; used -= 1; } } if (tail_src.tail >= 0) { llama_kv_cell & cell_src = cells[tail_src.tail]; cell_src.seq_id.insert(seq_id_dst); tail_dst.tail = tail_src.tail; } } return; } // otherwise, this is the KV of a Transformer-like model head = 0; for (uint32_t i = 0; i < size; ++i) { if (cells[i].has_seq_id(seq_id_src) && cells[i].pos >= p0 && cells[i].pos < p1) { cells[i].seq_id.insert(seq_id_dst); } } } void llama_kv_cache::seq_keep(llama_seq_id seq_id) { uint32_t new_head = size; for (uint32_t i = 0; i < size; ++i) { if (recurrent && (llama_seq_id) i != seq_id) { cells[i].tail = -1; } if (!cells[i].has_seq_id(seq_id)) { if (cells[i].pos >= 0) { used--; } cells[i].pos = -1; cells[i].src = -1; cells[i].seq_id.clear(); if (new_head == size){ new_head = i; } } else { cells[i].seq_id.clear(); cells[i].seq_id.insert(seq_id); } } // If we freed up a slot, set head to it so searching can start there. if (new_head != size && new_head < head) { head = new_head; } } void llama_kv_cache::seq_add(llama_seq_id seq_id, llama_pos p0, llama_pos p1, llama_pos delta) { if (delta == 0) { return; } uint32_t new_head = size; if (p0 < 0) { p0 = 0; } if (p1 < 0) { p1 = std::numeric_limits::max(); } // If there is no range then return early to avoid looping over the if (p0 == p1) { return; } if (recurrent) { // for Mamba-like or RWKV models, only the pos needs to be shifted if (0 <= seq_id && seq_id < (int64_t) size) { const int32_t tail_id = cells[seq_id].tail; if (tail_id >= 0) { llama_kv_cell & cell = cells[tail_id]; if (cell.has_seq_id(seq_id) && p0 <= cell.pos && cell.pos < p1) { cell.pos += delta; } } } return; } for (uint32_t i = 0; i < size; ++i) { if (cells[i].has_seq_id(seq_id) && cells[i].pos >= p0 && cells[i].pos < p1) { has_shift = true; cells[i].pos += delta; cells[i].delta += delta; if (cells[i].pos < 0) { if (!cells[i].is_empty()) { used--; } cells[i].pos = -1; cells[i].seq_id.clear(); if (new_head == size) { new_head = i; } } } } // If we freed up a slot, set head to it so searching can start there. // Otherwise we just start the next search from the beginning. head = new_head != size ? new_head : 0; } void llama_kv_cache::seq_div(llama_seq_id seq_id, llama_pos p0, llama_pos p1, int d) { if (d == 1) { return; } if (p0 < 0) { p0 = 0; } if (p1 < 0) { p1 = std::numeric_limits::max(); } // If there is no range then return early to avoid looping over the cache. if (p0 == p1) { return; } if (recurrent) { // for Mamba-like or RWKV models, only the pos needs to be changed if (0 <= seq_id && seq_id < (int64_t) size) { const int32_t tail_id = cells[seq_id].tail; if (tail_id >= 0) { llama_kv_cell & cell = cells[tail_id]; if (cell.has_seq_id(seq_id) && p0 <= cell.pos && cell.pos < p1) { cell.pos /= d; } } } return; } for (uint32_t i = 0; i < size; ++i) { if (cells[i].has_seq_id(seq_id) && cells[i].pos >= p0 && cells[i].pos < p1) { has_shift = true; { llama_pos p_old = cells[i].pos; cells[i].pos /= d; cells[i].delta += cells[i].pos - p_old; } } } } llama_pos llama_kv_cache::seq_pos_max(llama_seq_id seq_id) { llama_pos result = 0; for (uint32_t i = 0; i < size; ++i) { if (cells[i].has_seq_id(seq_id)) { result = std::max(result, cells[i].pos); } } return result; } void llama_kv_cache::defrag() { if (!recurrent) { do_defrag = true; } } struct llama_kv_cache_slot_info llama_kv_cache::find_slot( const struct llama_ubatch & ubatch) { const uint32_t n_tokens = ubatch.n_tokens; const uint32_t n_seqs = ubatch.n_seqs; const uint32_t n_seq_tokens = ubatch.n_seq_tokens; if (recurrent) { // For recurrent state architectures (like Mamba or RWKV), // each cache cell can store the state for a whole sequence. // A slot should be always be contiguous. // can only process batches with an equal number of new tokens in each sequence GGML_ASSERT(ubatch.equal_seqs); int32_t min = size - 1; int32_t max = 0; // everything should fit if all seq_ids are smaller than the max for (uint32_t s = 0; s < n_seqs; ++s) { const uint32_t n_seq_id = ubatch.n_seq_id[s]; for (uint32_t j = 0; j < n_seq_id; ++j) { const llama_seq_id seq_id = ubatch.seq_id[s][j]; if (seq_id < 0 || (uint32_t) seq_id >= size) { // too big seq_id // TODO: would it be possible to resize the cache instead? LLAMA_LOG_ERROR("%s: seq_id=%d >= n_seq_max=%d Try using a bigger --parallel value\n", __func__, seq_id, size); return llama_kv_cache_slot_info_failed; } if (j > 0) { llama_kv_cell & seq = cells[seq_id]; if (seq.tail >= 0) { llama_kv_cell & cell = cells[seq.tail]; // clear cells from seq_ids that become shared // (should not normally happen, but let's handle it anyway) cell.seq_id.erase(seq_id); seq.tail = -1; if (cell.seq_id.empty()) { cell.pos = -1; cell.src = -1; used -= 1; } } } } } #ifndef NDEBUG { std::vector tails_verif; tails_verif.assign(size, -1); for (uint32_t i = 0; i < size; ++i) { llama_kv_cell & cell = cells[i]; for (llama_seq_id seq_id : cell.seq_id) { if (tails_verif[seq_id] != -1) { LLAMA_LOG_ERROR("%s: duplicate tail for seq_id %d in cell %d and %d\n", __func__, seq_id, i, tails_verif[seq_id]); } tails_verif[seq_id] = i; } } for (uint32_t i = 0; i < size; ++i) { if (tails_verif[i] != cells[i].tail) { LLAMA_LOG_ERROR("%s: wrong tail for seq_id %d, (%d instead of %d)\n", __func__, i, cells[i].tail, tails_verif[i]); } } } #endif // find next empty cell uint32_t next_empty_cell = head; for (uint32_t i = 0; i < size; ++i) { if (next_empty_cell >= size) { next_empty_cell -= size; } llama_kv_cell & cell = cells[next_empty_cell]; if (cell.is_empty()) { break; } next_empty_cell += 1; } // find usable cell range for (uint32_t s = 0; s < n_seqs; ++s) { const llama_seq_id seq_id = ubatch.seq_id[s][0]; llama_kv_cell & seq_meta = cells[seq_id]; bool has_cell = false; if (seq_meta.tail >= 0) { llama_kv_cell & cell = cells[seq_meta.tail]; GGML_ASSERT(cell.has_seq_id(seq_id)); // does this seq_id "own" the cell? if (cell.seq_id.size() == 1) { has_cell = true; } } if (!has_cell) { llama_kv_cell & empty_cell = cells[next_empty_cell]; GGML_ASSERT(empty_cell.is_empty()); // copy old tail into the empty cell if (seq_meta.tail >= 0) { llama_kv_cell & orig_cell = cells[seq_meta.tail]; empty_cell.pos = orig_cell.pos; empty_cell.src = orig_cell.src; orig_cell.seq_id.erase(seq_id); empty_cell.seq_id.insert(seq_id); // will be overwritten } seq_meta.tail = next_empty_cell; // find next empty cell if (s + 1 < n_seqs) { next_empty_cell += 1; for (uint32_t i = 0; i < size; ++i) { if (next_empty_cell >= size) { next_empty_cell -= size; } llama_kv_cell & cell = cells[next_empty_cell]; if (cell.is_empty()) { break; } next_empty_cell += 1; } } } if (min > seq_meta.tail) { min = seq_meta.tail; } if (max < seq_meta.tail) { max = seq_meta.tail; } } // gather and re-order for (uint32_t s = 0; s < n_seqs; ++s) { int32_t dst_id = s + min; int32_t src_id = cells[ubatch.seq_id[s][0]].tail; if (dst_id != src_id) { llama_kv_cell & dst_cell = cells[dst_id]; llama_kv_cell & src_cell = cells[src_id]; std::swap(dst_cell.pos, src_cell.pos); std::swap(dst_cell.src, src_cell.src); std::swap(dst_cell.seq_id, src_cell.seq_id); // swap tails (assuming they NEVER overlap) for (const llama_seq_id seq_id : src_cell.seq_id) { cells[seq_id].tail = src_id; } for (const llama_seq_id seq_id : dst_cell.seq_id) { cells[seq_id].tail = dst_id; } } } // update the pos of the used seqs for (uint32_t s = 0; s < n_seqs; ++s) { const llama_pos last_pos = ubatch.pos[n_seq_tokens * s + n_seq_tokens - 1]; int32_t cell_id = s + min; llama_kv_cell & cell = cells[cell_id]; if (cell.pos >= 0 && last_pos != cell.pos + (llama_pos) n_seq_tokens) { // What should happen when the pos backtracks or skips a value? // Clearing the state mid-batch would require special-casing which isn't done. LLAMA_LOG_WARN("%s: non-consecutive token position %d after %d for sequence %d with %u new tokens\n", __func__, last_pos, cell.pos, ubatch.seq_id[s][0], n_seq_tokens); } cell.pos = last_pos; cell.seq_id.clear(); for (int32_t j = 0; j < ubatch.n_seq_id[s]; ++j) { const llama_seq_id seq_id = ubatch.seq_id[s][j]; cell.seq_id.insert(seq_id); cells[seq_id].tail = cell_id; } } // allow getting the range of used cells, from head to head + n head = min; n = max - min + 1; used = std::count_if(cells.begin(), cells.end(), [](const llama_kv_cell& cell){ return !cell.is_empty(); }); // sanity check return llama_kv_cache_slot_info(n >= n_seqs); } // otherwise, one cell per token. if (n_tokens > size) { LLAMA_LOG_ERROR("%s: n_tokens = %d > size = %d\n", __func__, n_tokens, size); return llama_kv_cache_slot_info_failed; } uint32_t n_tested = 0; while (true) { if (head + n_tokens > size) { n_tested += size - head; head = 0; continue; } bool found = true; for (uint32_t i = 0; i < n_tokens; i++) { if (cells[head + i].pos >= 0) { found = false; head += i + 1; n_tested += i + 1; break; } } if (found) { break; } if (n_tested >= size) { //LLAMA_LOG_ERROR("%s: failed to find a slot for %d tokens\n", __func__, n_tokens); return llama_kv_cache_slot_info_failed; } } for (uint32_t s = 0; s < n_seqs; s++) { for (uint32_t i = 0; i < n_seq_tokens; ++i) { uint32_t k = s*n_seq_tokens + i; cells[head + k].pos = ubatch.pos[k]; for (int32_t j = 0; j < ubatch.n_seq_id[s]; j++) { cells[head + k].seq_id.insert(ubatch.seq_id[s][j]); } } } used += n_tokens; return llama_kv_cache_slot_info(head, head + n_tokens); } uint32_t llama_kv_cache::get_padding(const llama_cparams & cparams) const { // the FA kernels require padding to avoid extra runtime boundary checks return cparams.flash_attn ? 256u : 32u; } uint32_t llama_kv_cache::cell_max() const { for (uint32_t i = size; i > 0; --i) { const llama_kv_cell & cell = cells[i - 1]; if (cell.pos >= 0 && !cell.is_empty()) { return i; } } return 0; } size_t llama_kv_cache::size_k_bytes() const { size_t size_k_bytes = 0; for (const auto & k : k_l) { size_k_bytes += ggml_nbytes(k); } return size_k_bytes; } size_t llama_kv_cache::size_v_bytes() const { size_t size_v_bytes = 0; for (const auto & v : v_l) { size_v_bytes += ggml_nbytes(v); } return size_v_bytes; } void llama_kv_cache_clear(llama_kv_cache * kv) { kv->clear(); } bool llama_kv_cache_seq_rm( llama_kv_cache * kv, llama_seq_id seq_id, llama_pos p0, llama_pos p1) { return kv->seq_rm(seq_id, p0, p1); } void llama_kv_cache_seq_cp( llama_kv_cache * kv, llama_seq_id seq_id_src, llama_seq_id seq_id_dst, llama_pos p0, llama_pos p1) { kv->seq_cp(seq_id_src, seq_id_dst, p0, p1); } void llama_kv_cache_seq_keep(llama_kv_cache * kv, llama_seq_id seq_id) { kv->seq_keep(seq_id); } void llama_kv_cache_seq_add( llama_kv_cache * kv, llama_seq_id seq_id, llama_pos p0, llama_pos p1, llama_pos delta) { kv->seq_add(seq_id, p0, p1, delta); } void llama_kv_cache_seq_div( llama_kv_cache * kv, llama_seq_id seq_id, llama_pos p0, llama_pos p1, int d) { kv->seq_div(seq_id, p0, p1, d); } llama_pos llama_kv_cache_seq_pos_max(llama_kv_cache * kv, llama_seq_id seq_id) { return kv->seq_pos_max(seq_id); } void llama_kv_cache_defrag(llama_kv_cache * kv) { kv->defrag(); } int32_t llama_kv_cache_n_tokens(const llama_kv_cache * kv) { return kv->n_tokens(); } int32_t llama_kv_cache_used_cells(const llama_kv_cache * kv) { return kv->used; } bool llama_kv_cache_can_shift(const llama_kv_cache * kv) { return kv->can_shift; } // // kv cache view // struct llama_kv_cache_view llama_kv_cache_view_init(const struct llama_kv_cache & kv, int32_t n_seq_max) { struct llama_kv_cache_view result = { /*.n_cells = */ 0, /*.n_seq_max = */ n_seq_max, /*.token_count = */ 0, /*.used_cells = */ llama_kv_cache_used_cells(&kv), /*.max_contiguous = */ 0, /*.max_contiguous_idx = */ -1, /*.cells = */ nullptr, /*.cells_sequences = */ nullptr, }; return result; } void llama_kv_cache_view_free(struct llama_kv_cache_view * view) { if (view->cells != nullptr) { free(view->cells); view->cells = nullptr; } if (view->cells_sequences != nullptr) { free(view->cells_sequences); view->cells_sequences = nullptr; } } void llama_kv_cache_view_update(struct llama_kv_cache_view * view, const struct llama_kv_cache & kv) { if (uint32_t(view->n_cells) < kv.size || view->cells == nullptr) { view->n_cells = int32_t(kv.size); void * p = realloc(view->cells, sizeof(struct llama_kv_cache_view_cell) * view->n_cells); GGML_ASSERT(p != nullptr && "Failed to alloc kv_cache_view cells"); view->cells = (struct llama_kv_cache_view_cell *)p; p = realloc(view->cells_sequences, sizeof(llama_seq_id) * view->n_seq_max * view->n_cells); GGML_ASSERT(p != nullptr && "Failed to alloc kv_cache_view cells sequences"); view->cells_sequences = (llama_seq_id *)p; } const std::vector & kv_cells = kv.cells; llama_kv_cache_view_cell * c_curr = view->cells; llama_seq_id * cs_curr = view->cells_sequences; int32_t used_cells = 0; int32_t token_count = 0; int32_t curr_contig_idx = -1; uint32_t max_contig = 0; int32_t max_contig_idx = -1; for (int32_t i = 0; i < int32_t(kv.size); i++, c_curr++, cs_curr += view->n_seq_max) { const size_t curr_size = kv_cells[i].seq_id.size(); token_count += curr_size; c_curr->pos = kv_cells[i].pos + kv_cells[i].delta; if (curr_size > 0) { if (curr_contig_idx >= 0 && uint32_t(i - curr_contig_idx) > max_contig) { max_contig = i - curr_contig_idx; max_contig_idx = curr_contig_idx; } curr_contig_idx = -1; } else if (curr_contig_idx < 0) { curr_contig_idx = i; } int seq_idx = 0; for (const llama_seq_id it : kv_cells[i].seq_id) { if (seq_idx >= view->n_seq_max) { break; } cs_curr[seq_idx] = it; seq_idx++; } if (seq_idx != 0) { used_cells++; } for (; seq_idx < view->n_seq_max; seq_idx++) { cs_curr[seq_idx] = -1; } } if (curr_contig_idx >= 0 && kv_cells.size() - curr_contig_idx > max_contig) { max_contig_idx = curr_contig_idx; max_contig = kv_cells.size() - curr_contig_idx; } view->max_contiguous = max_contig; view->max_contiguous_idx = max_contig_idx; view->token_count = token_count; view->used_cells = used_cells; if (uint32_t(used_cells) != kv.used) { LLAMA_LOG_ERROR("%s: used cells mismatch. kv_cache says %d but we calculated %d\n", __func__, kv.used, used_cells); } }