CANN/hixl待废弃Python接口文档

方拓行Sandra

251人浏览 · 2026-05-09 11:29:18

方拓行Sandra · 2026-05-09 11:29:18 发布

待废弃

【免费下载链接】hixl HIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl

产品支持情况

产品	是否支持
Atlas A3 训练系列产品/Atlas A3 推理系列产品	√
Atlas A2 训练系列产品/Atlas A2 推理系列产品	√

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

CacheManager

allocate_cache

函数功能

分配Cache，Cache分配成功后，会同时被cache_id与cache_keys引用，只有当这些引用都解除后，cache所占用的资源才会实际释放。

cache_id的引用需通过deallocate_cache解除，cache_keys的引用则可以通过以下2种方式解除。

Decode调用pull_cache或push_cache接口成功后解除。
PROMPT调用remove_cache_key接口时解除。

函数原型

allocate_cache(cache_desc: CacheDesc, cache_keys: Union[Tuple[CacheKey], List[CacheKey]] = ())

参数说明

参数名称	数据类型	取值说明
cache_desc	CacheDesc	Cache的描述。
cache_keys	Union[Tuple[CacheKey], List[CacheKey]]	Cache的索引。

调用示例

from llm_datadist import *
...
cache_desc = CacheDesc(1, [2, 1024 * 1024], DataType.DT_FLOAT16)
cache_keys = [CacheKey(1, req_id=1), CacheKey(1, req_id=2)]
cache = cache_manager.allocate_cache(cache_desc, cache_keys)

返回值

正常情况下返回Cache。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

如果cache_keys中包含了分配内存时绑定的CacheKey，则抛出LLMException异常。

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

约束说明

传入cache_keys时，如果Cache的batch size>1，则需要提供相同数量的CacheKey，分别引用一组kv tensor。
如果当次推理的batch未占用满，即存在无效batch_index，则需要插入特殊的CacheKey（将req_id设置为UINT64_MAX）占位，如果空闲的batch_index在末尾，则可以省略。
如果cache_keys存在重复，则最后一个生效。
调用该接口接口前需要先配置内存池。

deallocate_cache

函数功能

释放Cache。

如果该Cache在被分配时关联了CacheKey，则实际的释放会延后到所有的CacheKey被拉取或执行了remove_cache_key。

函数原型

deallocate_cache(cache: Cache)

参数说明

参数名称	数据类型	取值说明
cache	Cache	要释放的Cache。

调用示例

from llm_datadist import *
...
cache_manager.deallocate_cache(cache)

返回值

正常情况下无返回值。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

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

约束说明

如果Cache不存在或已释放，该操作为空操作。

remove_cache_key

函数功能

移除CacheKey。

移除CacheKey后，该Cache将无法再被pull_cache拉取。

函数原型

remove_cache_key(cache_key: CacheKey)

参数说明

参数名称	数据类型	取值说明
cache_key	CacheKey	需要被移除的CacheKey。

调用示例

from llm_datadist import *
...
cache_keys = [CacheKey(1, req_id=1), CacheKey(1, req_id=2)]
cache_manager.remove_cache_key(cache_keys[0])
cache_manager.remove_cache_key(cache_keys[1])

返回值

正常情况下无返回值。

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

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

约束说明

如果CacheKey不存在或已移除，该操作为空操作。

copy_cache

函数功能

拷贝Cache。

函数原型

copy_cache(dst: Cache, src: Cache, dst_batch_index: int = 0, src_batch_index: int = 0, offset: int = 0, size: int = -1, req_id: Optional[int] = None)

参数说明

参数名称	数据类型	取值说明
dst	Cache	目标Cache。
src	Cache	源Cache。
dst_batch_index	int	目标Cache的batch_index，默认为0。
src_batch_index	int	源Cache的batch_index，默认为0。
offset	int	每个tensor的偏移，默认为0。
size	int	设置为>0的整数，表示要拷贝的大小。或设置为-1，表示完整拷贝。默认为-1。
req_id	Optional[int]	本次调用关联的req_id，如果设置了该参数则本地调用相关的维测日志中会打印该req_id 默认为None

调用示例

from llm_datadist import *
...
cache_manager.copy_cache(dst_cache, src_cache, 0, 1, 0, 128)

返回值

正常情况下无返回值。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

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

约束说明

源Cache和目的Cahce的CacheDesc需要匹配。

allocate_blocks_cache

函数功能

PagedAttention场景下，分配多个blocks的Cache，Cache分配成功后，可通过deallocate_blocks_cache释放内存。

函数原型

allocate_blocks_cache(cache_desc: CacheDesc, blocks_cache_key: Optional[BlocksCacheKey] = None)

参数说明

参数名称	数据类型	取值说明
cache_desc	CacheDesc	Cache的描述。
blocks_cache_key	Optional[BlocksCacheKey]	索引一个blocks cache。

调用示例

from llm_datadist import *
...
blocks_cache_key = BlocksCacheKey(1, 0)
blocks_cache = cache_manager.allocate_blocks_cache(cache_desc, blocks_cache_key)

返回值

正常情况下返回Cache。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

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

约束说明

需要先配置内存池才能使用。

deallocate_blocks_cache

函数功能

分配Cache，Cache分配成功后，会同时被cache_id与cache_keys引用，只有当这些引用都解除后，cache所占用的资源才会实际释放。

cache_id的引用需通过deallocate_cache解除，cache_keys的引用则可以通过以下2种方式解除。

Decode调用pull_cache或push_cache接口成功后解除。
PROMPT调用remove_cache_key接口时解除。

函数原型

allocate_cache(cache_desc: CacheDesc, cache_keys: Union[Tuple[CacheKey], List[CacheKey]] = ())

参数说明

参数名称	数据类型	取值说明
cache_desc	CacheDesc	Cache的描述。
cache_keys	Union[Tuple[CacheKey], List[CacheKey]]	Cache的索引。

调用示例

from llm_datadist import *
...
cache_desc = CacheDesc(1, [2, 1024 * 1024], DataType.DT_FLOAT16)
cache_keys = [CacheKey(1, req_id=1), CacheKey(1, req_id=2)]
cache = cache_manager.allocate_cache(cache_desc, cache_keys)

返回值

正常情况下返回Cache。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

如果cache_keys中包含了分配内存时绑定的CacheKey，则抛出LLMException异常。

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

约束说明

传入cache_keys时，如果Cache的batch size>1，则需要提供相同数量的CacheKey，分别引用一组kv tensor。
如果当次推理的batch未占用满，即存在无效batch_index，则需要插入特殊的CacheKey（将req_id设置为UINT64_MAX）占位，如果空闲的batch_index在末尾，则可以省略。
如果cache_keys存在重复，则最后一个生效。
调用该接口接口前需要先配置内存池。

copy_blocks

函数功能

PagedAttention场景下，拷贝block。

函数原型

copy_blocks(cache: Cache, copy_block_info: Dict[int, List[int]])

参数说明

参数名称	数据类型	取值说明
cache	Cache	目标Cache。
copy_block_info	Dict[int, List[int]]	dict里面内容代表（原始block index，目标block index列表）。

调用示例

cache_manager.copy_blocks(cache, {1: [2,3]})

返回值

正常情况下无返回值。

传入数据类型错误情况下会抛出TypeError或ValueError异常。

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

约束说明

无

swap_blocks

函数功能

对cpu_cache和npu_cache进行换入换出。

对于swap out功能，该接口启用了4个线程执行并行任务；对于swap in功能，该接口启用了1个d2d线程。为了性能稳定，建议进行进程绑核。

swap in功能分为H2D和D2D两个阶段，为了保障性能，该接口申请了4个block大小的buffer用作流水拷贝，所以建议预留出对应的Device内存，防止出现OOM。

函数原型

swap_blocks(src_cache: Cache, dst_cache: Cache, src_to_dst: Dict[int, int])

参数说明

参数名称	数据类型	取值说明
src_cache	Cache	源Cache。
dst_cache	Cache	目标Cache。
src_to_dst	Dict[int, int]	dict里面内容代表（原始block index，目标block index）

调用示例

from llm_datadist import Cache
npu_cache = cache_manager.allocate_blocks_cache(npu_cache_desc, npu_cache_key)
cpu_cache = Cache.create_cpu_cache(cpu_cache_desc, cpu_addrs) # cpu_addrs来自创建的cpu tensors
# swap in
cache_manager.swap_blocks(cpu_cache, npu_cache, {1:2, 3:4})
# swap out
cache_manager.swap_blocks(npu_cache, cpu_cache, {1:2, 3:4})

返回值

正常情况下无返回值。

传入数据类型错误，src和dst不匹配情况下会抛出TypeError或ValueError异常。

传入参数为None，会抛出AttributeError异常。

约束说明

仅支持PagedAttention场景使用。

LLMConfig

mem_pool_cfg

函数功能

配置内存池相关配置项。

函数原型

mem_pool_cfg(mem_pool_cfg)

参数说明

参数名称	数据类型	取值说明
mem_pool_cfg	string	json数组格式字符串，包含memory_size，page_shift。

配置项	可选/必选	描述
memory_size	必选	当前内存池的大小，类型为int，大于0，单位为Byte。
page_shift	可选	page_size的位移量，用于计算page_size。分配内存时会对齐到page_size的倍数，需要根据实际场景设置为合适的大小。类型为int，取值范围为[10, 31)。例如：page_shift = 16时，page_size为1<<16=65536。默认值为16。

调用示例

from llm_datadist import LLMConfig
llm_config = LLMConfig()
llm_config.mem_pool_cfg= "{\"memory_size\": 18737418240, \"page_shift\": 16}"

返回值

正常情况下无返回值。

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

约束说明

无

host_mem_pool_cfg

函数功能

配置Host内存池相关配置项。

函数原型

host_mem_pool_cfg(host_mem_pool_cfg)

参数说明

参数名称	数据类型	取值说明
host_mem_pool_cfg	string	json数组格式字符串，包含memory_size，page_shift。

配置项	可选/必选	描述
memory_size	必选	当前内存池的大小，类型为int，大于0，单位为Byte。
page_shift	可选	page_size的位移量，用于计算page_size。分配内存时会对齐到page_size的倍数，需要根据实际场景设置为合适的大小。类型为int，取值范围为[10, 31)。例如：page_shift = 16时，page_size为1<<16=65536。默认值为16。

调用示例

from llm_datadist import LLMConfig
llm_config = LLMConfig()
llm_config.host_mem_pool_cfg= "{\"memory_size\": 18737418240, \"page_shift\": 16}"

返回值

正常情况下无返回值。

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

约束说明

Host内存池最大不超过20G。

亚马逊云科技技术品牌专区

更多推荐

面向长程任务的安全具身智能：机器人操作的跨层分析（下）

亚马逊云科技技术品牌专区

NLP的注意力机制与Transformer

计算上，它通过比对解码器当前状态与编码器各状态，经过一个可学习的小型网络或简单的点积运算，产生一组归一化的注意力权重，再以此权重对编码器状态进行加权求和，得到一个与当前解码步骤最相关的“上下文向量”。Transformer的核心是自注意力。从模仿人类选择性聚焦的认知直觉，到成为驱动当代人工智能发展的核心引擎，注意力机制与Transformer的故事，是基础研究引发连锁技术革命的典范。如今，基于注意

亚马逊云科技技术品牌专区

边缘计算平台架构与部署方案

传统的集中式云计算模式，将所有数据传输至遥远的中心云进行处理，在面对自动驾驶、工业物联网、智慧城市等对实时性、带宽和隐私有极高要求的场景时，日益暴露出延迟高、带宽成本大、数据隐私风险高等局限性。网络方面，需确保边缘节点与设备、边缘节点之间、边缘与中心云之间网络的低延迟、高带宽和高可靠性，可能涉及5G、TSN、光纤等多种技术混合组网。该平台需能远程监控所有边缘节点的健康状态（硬件、软件、网络）、资源