---
title: pull_cache
description: "| 产品 | 是否支持 |"
url: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/latest/others/llmdatadistdev/llmpr_42_0040.html
sourcePath: /source/zh/CANNCommunityEdition/920beta1/others/llmdatadistdev/llmpr_42_0040.html
indexId: 4b7235291c287c63a79262a2cfa4ee5f3da811a83b52a09c4ac280d7415d822581
---
# pull_cache

#### 产品支持情况

| 产品 | 是否支持 |
| --- | --- |
| Ascend 950PR / Ascend 950DT | x |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | x |
| Atlas 推理系列产品 | x |
| Atlas 训练系列产品 | x |


说明： Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ：针对 Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ，仅支持Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。


#### 函数功能

根据CacheKey，从对应的Prompt节点拉取KV到本地KV Cache，仅当LLMRole为DECODER时可调用。


#### 函数原型

```
pull_cache(cache_key: Union[CacheKey, CacheKeyByIdAndIndex], kv_cache: KvCache, batch_index: int = 0, size: int = -1, **kwargs)
```


#### 参数说明

| 参数名称 | 数据类型 | 取值说明 |
| --- | --- | --- |
| cache\_key | Union[CacheKey, CacheKeyByIdAndIndex] | 需要被拉取的CacheKey。该CacheKey需要和allocate\_cache的CacheKey保持一致。 通过req\_id，prefix\_id，model\_id拉取则传入CacheKey。 通过cache\_id，batch\_index拉取则传入CacheKeyByIdAndIndex。 |
| kv\_cache | KvCache | 目标KV Cache。 |
| batch\_index | int | 表示目标KV Cache的batch index，默认为0。 |
| size | int | 默认为\-1。 设置为>0的整数，表示要拉取的tensor大小。 或设置为\-1，表示完整拷贝：本地单个KV的大小减去dst\_cache\_offset大小。 |
| \*\*kwargs | NA | 这个是Python函数的可扩展参数通用写法，一般通过key=value的方式直接传入参数。 可选参数的详细信息请参考表1。 |


**表1 **kwargs的可选参数**

| 参数名称 | 数据类型 | 取值说明 |
| --- | --- | --- |
| src\_layer\_range | Optional[range] | 可选参数，用于按层pull kv场景。传输源的layer的范围，step只支持1。不设置时为传输所有layer。需要注意这里是layer的index，而不是tensor的index，即1个layer对应连续N个tensor(K/V)，这里要求分配内存时，必须是KV,...,KV排布，不支持其他场景。N为tensor\_num\_per\_layer的取值，默认为2。 |
| dst\_layer\_range | Optional[range] | 可选参数，用于按层pull kv场景。传输目标的layer的范围，step只支持1。不设置时为传输所有layer。需要注意这里是layer的index，而不是tensor的index，即1个layer对应连续N个tensor(K/V)，这里要求分配内存时，必须是KV,...,KV排布，不支持其他场景。N为tensor\_num\_per\_layer的取值，默认为2。 |
| src\_cache\_offset | Optional[int] | 设置>=0的整数。表示从src\_cache tensor的offset位置拉取size大小的数据 |
| dst\_cache\_offset | Optional[int] | 设置>=0的整数。表示将源数据拉取到dst\_cache tensor的offset起始位置 |
| tensor\_num\_per\_layer | Optional[int] | 可选参数，表示每层的tensor的数量，默认值是2，取值范围是[1,cache的tensor总数]。当src\_layer\_range或dst\_layer\_range取值为非默认值时， tensor\_num\_per\_layer可以保持默认值，也可以输入其他值，输入其他值时，tensor\_num\_per\_layer的取值还需要被当前cache的tensor总数整除。 |


#### 调用示例

```
from llm_datadist import *
cache_keys = [CacheKey(1, req_id=1), CacheKey(1, req_id=2)]
kv_cache_manager.pull_cache(cache_keys[0], cache, 0)
# 开启layer_range功能
kv_cache_manager.pull_cache(cache_keys[1], cache, 1, src_layer_range=range(0,2), dst_layer_range=range(2,4))
# 开启offset功能
kv_cache_manager.pull_cache(cache_keys[1], cache, src_cache_offset=0, dst_cache_offset=0)
```


#### 返回值

正常情况下无返回值。

参数错误可能抛出TypeError或ValueError。

执行时间超过sync_kv_timeout配置会抛出LLMException异常。


#### 约束说明

- 使用同一条链路时，不支持该接口和  transfer_cache_async
接口并发。
- 本接口不支持并发调用。