aclnnBidirectionLSTM 调用指南：双向LSTM 两段式调用、shape 陷阱与错误码排查-平芜编程栈

aclnnBidirectionLSTM 调用指南：双向LSTM 两段式调用、shape 陷阱与错误码排查

【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn

aclnnBidirectionLSTM是 CANN 算子库（ops-nn 项目）aclnn 接口中面向双向 LSTM 的两段式调用入口：接收输入序列与初始隐藏/单元状态，输出完整隐藏序列和最终状态，用于把序列模型（ASR、NLP 等）部署到 NPU 上的 C++ 推理链路中。下文按"硬件 → 原理 → 流程 → 参数 → 排错 → 示例 → 约束"重新组织，方便直接照着落地。

能跑在哪些硬件上

结论先行：该算子当前仅支持 Atlas 推理系列产品；Atlas 训练系列、A2/A3 训推系列、200I/500 A2 推理产品以及新一代 Ascend 950PR/950DT 均不支持。部署目标如果是训练场景，现阶段只能选择替代算法方案。

产品系列	支持情况
Atlas 推理系列产品	√
Atlas 训练系列产品	×
Atlas A2 训练 / 推理系列产品	×
Atlas A3 训练 / 推理系列产品	×
Ascend 950PR / 950DT	×
Atlas 200I / 500 A2 推理产品	×

💡 选型阶段就应确认卡型落在支持范围内，否则后续参数怎么调都跑不起来。

原理速览：双向 LSTM 在算什么

LSTM 单元在每个时间步用三个门控制"忘掉什么、写入什么、对外露出什么"：

遗忘门$f_t$（sigmoid 输出，取值 (0,1)）：决定上一时刻单元状态 $c_{t-1}$ 保留多少；
输入门$i_t$：控制新记忆候选 $\tilde{c}_t = \tanh(W_c[h_{t-1}, x_t] + b_c)$ 的写入比例；
输出门$o_t$：控制单元状态有多少被释放为隐藏状态 $h_t \in (-1, 1)^h$。

整个前向计算可以压缩成两条核心递推：

$$c_t = f_t \odot c_{t-1} + i_t \odot \tilde{c}_t, \qquad h_t = o_t \odot \tanh(c_t)$$

所谓"双向"，是指序列用正向权重沿时间正向算一遍，再用逆向权重沿时间反向算一遍，每个时刻把两个方向的结果拼接起来。这正是接口里多出 4 个逆向权重/偏置参数的原因，也是输出 y 最后一维变成2 * hidden_size的原因。

两段式调用流程：workspace 怎么算

aclnn 算子族遵循两段式接口约定（可查阅官方文档"两段式接口"说明页）。该算子的调用分三步：

调用第一段aclnnBidirectionLSTMGetWorkspaceSize：传入全部输入/输出张量与标量开关。该接口完成入参校验，通过出参workspaceSize给出本次计算在 device 侧需要的内存大小，并生成aclOpExecutor（计算流程快照）。
申请内存：workspaceSize > 0时用aclrtMalloc在 device 侧按此大小申请；为 0 时第二段可传 nullptr。
调用第二段aclnnBidirectionLSTM：传入 workspace 地址、大小、executor 与执行 stream，算子在 NPU 上执行。

两段函数原型：

aclnnStatus aclnnBidirectionLSTMGetWorkspaceSize( const aclTensor *x, const aclTensor *initH, const aclTensor *initC, const aclTensor *wIh, const aclTensor *wHh, const aclTensor *bIhOptional, const aclTensor *bHhOptional, const aclTensor *wIhReverseOptional, const aclTensor *wHhReverseOptional, const aclTensor *bIhReverseOptional, const aclTensor *bHhReverseOptional, int64_t numLayers, bool isbias, bool batchFirst, bool bidirection, const aclTensor *yOut, const aclTensor *outputHOut, const aclTensor *outputCOut, uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclnnBidirectionLSTM(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream);

📌 第二段不能单独调用：workspaceSize 与 executor 必须来自第一段那次调用，两者配套使用。

参数速查：17 个参数归成五组

所有张量仅支持 FLOAT16、格式 ND，且都支持非连续 tensor。按数据流方向分五组：

① 输入张量（序列与初始状态）

x：输入向量，{time_step, batch_size, input_size}
initH：初始隐藏状态，{num_layers, batch_size, hidden_size}；双向时首维变为2 * num_layers
initC：初始单元状态，shape 规则与initH相同

② 权重与偏置

wIh：input→hidden 权重，{4 * hidden_size, input_size}
wHh：hidden→hidden 权重，{4 * hidden_size, hidden_size}
bIhOptional/bHhOptional：正向偏置，{4 * hidden_size}
wIhReverseOptional/wHhReverseOptional/bIhReverseOptional/bHhReverseOptional：4 个逆向参数，shape 规则与各自正向对应项一致

③ 标量开关

numLayers（int64_t）：LSTM 层数，当前仅支持 1
isbias（bool）：是否使用偏置
batchFirst（bool）：首维是否为 batch，当前仅支持 false
bidirection（bool）：是否双向，决定 initH / outputH 首维与 y 末维

④ 输出张量

yOut：输出序列，{time_step, batch_size, hidden_size}；双向时末维为2 * hidden_size
outputHOut/outputCOut：最终隐藏/单元状态，shape 与initH/initC相同

⑤ 运行时资源

workspaceSize（uint64_t*，出参）：device 侧需要的 workspace 大小
executor（aclOpExecutor**，出参）：计算流程执行器，供第二段使用

可选参数到底要不要传

名字里带 "Optional" 的参数均支持传空 tensor：

isbias为 false 时，bIhOptional、bHhOptional可传空 tensor；
bidirection为 false 时，4 个*ReverseOptional可传空 tensor；
bidirection为 true 时，逆向参数实际是必需的，缺了就无法完成反向那一遍计算。

🔧 也就是说，"Optional" 表示参数可置空，而不是可以忽略；传真 tensor 还是传空，由isbias和bidirection两个开关决定。

常见错误与排错：shape 不匹配怎么排查

第一段接口会完成入参校验，报错集中在三个返回码（完整列表见官方文档"aclnn 返回码"页）：

错误码	含义	排查方向
`ACLNN_ERR_PARAM_NULLPTR`（161001）	必选输入、输出或属性为空指针	逐项确认 x、initH/initC、wIh/wHh、y/outH/outC 是否创建成功，以及`&workspaceSize`、`&executor`是否传了有效地址
`ACLNN_ERR_PARAM_INVALID`（161002）	aclTensor 数据类型超出支持范围	该算子只支持 FLOAT16，传 FLOAT32 等其他类型必报此错
`ACLNN_ERR_INNER_TILING_ERROR`（561002）	shape 与参数说明不符	对照上文五组参数表逐张比对，重点核对双向场景首维用`num_layers`还是`2 * num_layers`

另外补充三个不体现在返回码里的高频坑：

workspace 未申请或大小不对：第一段拿到的 workspaceSize 必须原样用于 device 内存申请，少申请属于未定义行为。
executor 与入参不匹配：张量 shape 或标量开关变化后，必须重跑第一段拿新 executor，不能沿用旧的。
bidirection 与 shape 不一致：双向为 true 时，initH/outputH 首维仍按num_layers传、y 末维仍按hidden_size传，会触发 tiling 报错或得到错误结果。

最小可运行示例：核心调用链

// 1. 固定写法：device/stream 初始化 int32_t deviceId = 0; aclrtStream stream; auto ret = Init(deviceId, &stream); // 2. 按 API 修改：构造张量 int time_step = 2, batch_size = 32, input_size = 32, hidden_size = 32; std::vector<int64_t> xShape = {time_step, batch_size, input_size}; std::vector<int64_t> wIhShape = {4LL * hidden_size, input_size}; std::vector<int64_t> wHhShape = {4LL * hidden_size, hidden_size}; std::vector<int64_t> initShape = {2, batch_size, hidden_size}; // 双向取 2 * num_layers std::vector<int64_t> biasShape = {4LL * hidden_size}; std::vector<int64_t> yShape = {time_step, batch_size, 2LL * hidden_size}; aclTensor *x, *initH, *initC, *wIh, *wHh, *bIh, *bHh; aclTensor *wIhR, *wHhR, *bIhR, *bHhR, *y, *outH, *outC; // 每个张量用 CreateAclTensor(hostData, shape, &devAddr, ACL_FLOAT16, &tensor) 创建 // ... 其余张量构造略 ... // 3. 第一段：校验入参、计算 workspace 大小 uint64_t workspaceSize = 0; aclOpExecutor *executor = nullptr; ret = aclnnBidirectionLSTMGetWorkspaceSize( x, initH, initC, wIh, wHh, bIh, bHh, wIhR, wHhR, bIhR, bHhR, /*numLayers=*/1, /*isbias=*/true, /*batchFirst=*/false, /*bidirection=*/true, y, outH, outC, &workspaceSize, &executor); if (ret != ACL_SUCCESS) return ret; // 固定写法：失败直接返回 // 4. 固定写法：device 侧申请 workspace void *workspaceAddr = nullptr; if (workspaceSize > 0) { aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); } // 5. 第二段：执行计算并同步 ret = aclnnBidirectionLSTM(workspaceAddr, workspaceSize, executor, stream); aclrtSynchronizeStream(stream); // 6. 结果拷回 host，释放全部 aclTensor 与 device 内存 // ... 其余固定写法略 ...

Init与CreateAclTensor的完整模板可查阅官方文档"编译与运行样例"页，此处只保留调用链本身。