---
title: Initialize
description: "| 产品 | 是否支持 |"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/hixlug/llmcrv2_42_24.html
sourcePath: /source/zh/canncommercial/900/API/hixlug/llmcrv2_42_24.html
indexId: afa080a7a53fe3a4037efe5d152019632f55832f5caa9b33c60060354511f67859
---
# Initialize

#### 产品支持情况

| 产品 | 是否支持 |
| --- | --- |
| Atlas 350 加速卡 | x |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | x |
| Atlas 推理系列产品 | x |
| Atlas 训练系列产品 | x |


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


#### 函数功能

初始化HIXL，在调用其他接口前需要先调用该接口。


#### 函数原型

```
Status Initialize(const AscendString &local_engine, const std::map<AscendString, AscendString> &options)
```


#### 参数说明

| 参数名 | 输入/输出 | 描述 |
| --- | --- | --- |
| local\_engine | 输入 | HIXL标识，在所有参与建链的范围内需要确保唯一。 如果是ipv4，格式为host\_ip:host\_port或host\_ip。 如果是ipv6，格式为[host\_ip]:host\_port或[host\_ip]。 不建议配置为回环IP，在多个HIXL交互场景，回环IP容易冲突。 当设置host\_port且host\_port>0时代表当前HIXL作为Server端，需要对配置端口进行侦听。如果没设置host\_port或者host\_port<=0代表是Client，不启动侦听。 |
| options | 输入 | 初始化参数值。具体请参考如下表格。 |


**表1 options**

| 参数名 | 可选/必选 | 描述 |
| --- | --- | --- |
| OPTION\_BUFFER\_POOL | 可选 | 字符串取值"BufferPool"。 在需要使用中转buffer进行传输的场景下: 不支持使用HCCS协议进行Host To Host直传传输时。 RDMA注册Host内存大小受限时。 多个小块内存传输(例如128K)需要使用中转传输提升性能时。 可使用此option配置中转内存池的大小，取值格式为"$BUFFER\_NUM:$BUFFER\_SIZE"，系统默认配置为"4:8(单位MB)"。可以通过配置为"0:0"来关闭中转内存池，在有并发的场景下建议增大$BUFFER\_NUM个数。另外，所有使用该配置项的的地方需要配置相同的值，中转传输模式的限制请参考TransferSync接口。 Atlas A3 训练系列产品 / Atlas A3 推理系列产品 场景下，该参数不支持和“OPTION\_ENABLE\_USE\_FABRIC\_MEM”同时配置。 说明：如果未配置该参数，则存在如下约束。 Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ：针对 Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ，仅支持Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。该场景下Server内采用HCCS传输协议时，仅支持D2D。 Atlas A3 训练系列产品 / Atlas A3 推理系列产品 ，该场景下采用HCCS传输协议时，不支持Host内存作为远端Cache。 |
| OPTION\_RDMA\_TRAFFIC\_CLASS | 可选 | 字符串取值"RdmaTrafficClass"。 用于配置RDMA网卡的traffic class。和环境变量HCCL\_RDMA\_TC功能，如同时配置，当前option优先级更高；未同时配置，以配置的一方为准。 取值范围为[0,255]，且需要配置为4的整数倍，默认值为132。 更多信息请参考《环境变量参考(https://www.hiascend.com/document/detail/zh/canncommercial/900/maintenref/envvar/envref\_07\_0001.html)》。 |
| OPTION\_RDMA\_SERVICE\_LEVEL | 可选 | 字符串取值"RdmaServiceLevel"。 用于配置RDMA网卡的service level。和环境变量HCCL\_RDMA\_SL功能相同，如同时配置，当前option优先级更高；未同时配置，以配置的一方为准。 取值范围为[0, 7]，默认值为4。 更多信息请参考《环境变量参考(https://www.hiascend.com/document/detail/zh/canncommercial/900/maintenref/envvar/envref\_07\_0001.html)》。 |
| OPTION\_GLOBAL\_RESOURCE\_CONFIG | 可选 | 字符串取值"GlobalResourceConfig"，用于开启并配置全局资源配置。 |
| OPTION\_ENABLE\_USE\_FABRIC\_MEM | 可选 | 字符串取值"EnableUseFabricMem"。 0：不开启Fabric Mem模式 1：开启Fabric Mem模式 此option适用于需要使用HCCS进行D2RH、RH2D传输的场景。 说明：集群场景下，该参数在所有节点需要配置为相同的值。该参数不支持和“OPTION\_BUFFER\_POOL”同时配置。 仅支持 Atlas A3 训练系列产品 / Atlas A3 推理系列产品 。 |
| OPTION\_AUTO\_CONNECT | 可选 | 字符串取值“AutoConnect”。 0：不开启Auto Connect模式 1：开启Auto Connect模式 说明： 开启该选项后，可跳过建链，直接进行传输。 开启该选项后，传输发生异常或对端销毁后自动清理异常链路（对端销毁需要心跳机制来检测，心跳间隔默认10s）。 |
| OPTION\_LOCAL\_COMM\_RES | 可选 | 配置本地通信资源信息，格式是json格式的字符串。 配置方法如下： 仅需配置ranktable中当前llm datadist所使用Device信息，无需配置ranktable中的server\_count和rank\_id字段，ranktable具体信息请参见《HCCL集合通信库(https://www.hiascend.com/document/detail/zh/canncommercial/900/API/hcclug/hcclug\_000001.html)》。该option可以不配置或配置为空串，为空将自动生成相关信息。 |


OPTION_GLOBAL_RESOURCE_CONFIG的配置示例和使用约束如下：

对于Fabric Mem模式（仅 Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持），该参数配置示例如下：

```
{
"fabric_memory.max_capacity": "128", //虚拟内存池的大小。取值范围：(0, 1024]之间的整数，默认值：64，单位TB.
"fabric_memory.task_stream_num": "1", //配置Fabric Mem模式下单个任务使用的流数量。取值范围：[1, 8]之间的整数，默认值：4.
}
```

对于链路池机制，该参数配置示例如下：

```
{
"channel_pool.max_channel": "10", //最大的链路个数。取值范围：(0, 512]之间的整数，默认值：512
"channel_pool.high_waterline": "0.3", //触发链路销毁的高水位，取值范围：（0，1）之间的小数，需要和channel_pool.low_waterline同时配置
"channel_pool.low_waterline": "0.1" //触发链路销毁的低水位，取值范围：（0，1）之间小数，并且小于高水位
}
```

链路池工作时，实际依据链路个数判断是否进行销毁，如果当前链路个数已经达到高水位对应的链路个数，则选择（当前链路个数-低水位对应的链路个数 ）条链路进行销毁（如存在正在传输的任务，则不会销毁），再建链。相关参数计算公式如下：

- 高水位线对应的链路个数=max(1,static_cast<int32_t> (channel_pool.max_channel * channel_pool.high_waterline))
- 低水位线对应的链路个数=max(1,static_cast<int32_t> (channel_pool.max_channel * channel_pool.low_waterline))

在上述配置示例中，按照计算公式，高水位对应的链路个数=3，低水位对应的链路个数=1。每次建链前会检查当前HIXL内的链路是否达到3，如果已经达到，选择(当前链路个数-1 )条链路进行销毁（如存在正在传输的任务，则不会销毁），再建链。

当启用链路池机制时，有如下注意事项：

- 集群内的所有Hixl Engine都需要配置OPTION_GLOBAL_RESOURCE_CONFIG。
- 当调用TransferSync或TransferAsync接口时，若不存在相关链路，将执行建链操作。
- 会增加传输和建链的额外开销，可能导致性能下降。


#### 调用示例

单击Gitcode(https://gitcode.com/cann/hixl)，选择配套版本，从“examples/cpp”目录中获取样例。


#### 返回值

- SUCCESS：成功
- PARAM_INVALID：参数错误
- 其他：失败


#### 异常处理

无


#### 约束说明

1. 需要和  Finalize
配对使用，初始化成功后，任何退出前都需要先调用  Finalize
保证资源释放，否则会出现资源释放顺序不符合预期而导致问题。
2. 初始化前需要先调用“aclrtSetDevice(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/runtimeapi/aclcppdevg_03_0039.html)”。