[Metax] deepseek ops import error

[StareAtYou]

测试环境

platform：maca
paddle：dev20251120
paddle_metax_gpu: dev20251121
fastdeploy：develop branch，based on ff26158

现象描述

刚编译完 fastdeploy 包，能够正常导入 deepseek 相关的 op 接口

from fastdeploy.model_executor.ops.gpu import fused_rotary_position_encoding

运行 run_model.py 后，导入 deepseek op 就会失败

run_model.py 源码

import os
os.environ["MACA_VISIBLE_DEVICES"] = "6,7"
os.environ["FD_MOE_BACKEND"] = "cutlass"
os.environ["PADDLE_XCCL_BACKEND"] = "metax_gpu"
os.environ["FLAGS_weight_only_linear_arch"] = "80"
os.environ["FD_METAX_KVCACHE_MEM"] = "8"
os.environ["FD_ENC_DEC_BLOCK_NUM"] = "0"
# os.environ["FD_METAX_DENSE_QUANT_TYPE"] = "wint8"

# "/root/model/ERNIE-4.5-21B-A3B-Paddle"
# "/root/model/ERNIE-4.5-0.3B-Paddle"
# "/root/model/ERNIE-4.5-21B-A3B-Thinking"

import fastdeploy
llm = fastdeploy.LLM(model="/root/model/ERNIE-4.5-VL-28B-A3B-Thinking",
                     tensor_parallel_size=1,
                     load_choices="default_v1",
                     engine_worker_queue_port=8899,
                     quantization="wint8",
                     disable_custom_all_reduce=True,
)

prompts = [
        # "who are you?",
        "A robe takes 2 bolts of blue fiber and half that much white fiber. How many bolts in total does it take?",
]
# sampling_params = fastdeploy.SamplingParams(top_p=0.0, max_tokens=2047, temperature=0.0)
sampling_params = fastdeploy.SamplingParams(top_p=0.95, max_tokens=128, temperature=0.6)

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs.text
    print(f"Prompt: {prompt!r}")
    print(f"Generated: {generated_text!r}")

终端打印

刚编译出 fd 包时的导入测试

紧接着运行 run_model.py 时

接着再测试一开始导包方式

[yuanlehome]

下面我根据你提供的 GitHub Issue 页面内容，对 deepseek ops import error 的现象进行工程师视角的深入分析，并给出推测原因 + 定位方向 + 建议验证方法。

---

✅ 问题缩略重述

你在如下场景中遇到问题：

1. 刚编译完 FastDeploy 包（develop 分支、基于 commit ff26158）时：
   deepseek op（例如 fused_rotary_position_encoding）可以成功 import。

2. 运行 run_model.py 后，再 import deepseek op 就失败：
   出现导入失败，终端截图显示类似：

   ImportError: xxx.so: undefined symbol ...
   

3. 再次单独测试 import（没有跑模型时）：
   又正常。

现象表现为：

运行 LLM 前后，deepseek ops 的 Python binding 加载状态发生变化，导致 later import 失败。

---

🔍 核心问题分析

根据你的截图与描述，问题高度符合 —— 动态库冲突/覆盖/卸载问题。

### 💡 重要线索来自你的环境变量：

os.environ["PADDLE_XCCL_BACKEND"] = "metax_gpu"
os.environ["FD_MOE_BACKEND"] = "cutlass"
os.environ["FLAGS_weight_only_linear_arch"] = "80"
os.environ["FD_METAX_KVCACHE_MEM"] = "8"

以及：

paddle：dev20251120  
paddle_metax_gpu: dev20251121  
fastdeploy：develop

你的 FastDeploy + Paddle + metax_gpu 都是 dev 版本，接口和 symbol 极可能在以下情况发生变化：

---

🎯 可能原因 Top 5（按概率排序）

---

① 运行 run_model.py 后加载了另外一套动态库，覆盖了 deepseek op 依赖的 symbol（高概率）

FastDeploy 运行 LLM 时会加载如下 .so：

• libpaddle.so
• libpaddle_metax_gpu.so
• libcutlass.so
• FastDeploy 自身算子 .so
• deepseek ops .so

Python 的动态库加载遵循：

先加载的库，会常驻进程；若后加载的库包含相同 symbol，会冲突或覆盖。

因此流程可能是：

✔️ 初始 import deepseek op

deepseek ops 依赖的 paddle / fastdeploy 接口是 匹配的。

✔️ 执行 run_model.py 时

由于 LLM() 内部加载了新的 .so（尤其是 Paddle 的 dev 版本），
导致全局符号表变化。

❌ 再次 import deepseek_op

deepseek ops 期望的 symbol 消失或被替换 → 导致 ImportError。

这是 Python 中多个模块同时带有 native operator 的典型冲突。

你的 error 图中提到的 undefined symbol 就是证据。

---

② LLM 调用过程中触发 JIT/RT 编译，生成的 .so 覆盖了 initial .so（中概率）

FastDeploy 在 MoE、GEMM、KVCache 等路径中可能触发 meta-kernel 的 runtime 构建（尤其是 cutlass backend）。

这些 .so 可能：

• 被放入 /tmp/fd_ops_xxxxxxx.so
• 然后被 LD_PRELOAD 时间前后加载
• 覆盖了原本的 deepseek op 的符号

导致后续 import 失败。

---

③ metax_gpu backend 动态库版本不一致（可能性中等）

你使用：

paddle dev20251120
paddle_metax_gpu dev20251121
fastdeploy develop

这三个 dev 版本之间可能存在 symbol ABI 不一致，例如：

• 自定义 op 注册接口变化
• 分布式通信接口变化
• Allocator / Stream API 的版本差异

⚠️ deepseek ops 编译时链接的是 dev20251120
⚠️ run_model.py 运行时加载的是 dev20251121

ABI mismatch → import error。

---

④ FastDeploy 的全局初始化改变了 Paddle 的 so 加载顺序（中等概率）

LLM() 初始化时，FastDeploy 会调用：

• dlopen(libpaddle.so, RTLD_GLOBAL)
• dlopen(libpaddle_metax_gpu.so)
• 注册多个自定义 op

如果加载顺序改变，有可能：

• 覆盖之前 deepseek_op 加载的符号
• 或使 deepseek_op 中的符号绑定到了不同版本的 paddle API

结果就是 import 失败。

---

⑤ 环境变量影响了算子注册行为（低概率但可能）

例如：

FD_METAX_KVCACHE_MEM=8
FD_MOE_BACKEND=cutlass
PADDLE_XCCL_BACKEND=metax_gpu

有可能切换了 run-time 的 operator path，从而改变了：

• 哪个后端算子被 dlopen
• 算子注册的入口不一致

但这种通常不会导致 import deepseek ops 失败，除非你使用了开发中的 feature。

---

🧪 如何快速验证是哪一类问题？

你可以做如下实验（非常关键）：

---

实验 1：运行前后对比已加载的 .so

加两行代码：

import sys
import pprint
print("Before:", set(sys.modules.keys()))

import fastdeploy
llm = fastdeploy.LLM(...)

print("After:", set(sys.modules.keys()))

如果多了一些冲突名称，比如：

• paddle
• paddle_base
• libcublas
• libcutlass
• metax_gpu_runtime

说明是 symbol 冲突。

---

实验 2：用 lsof 观察 .so 更新（最直接）

运行前：

lsof -p $PID | grep .so > before.txt

运行后：

lsof -p $PID | grep .so > after.txt
diff before.txt after.txt

如果看到 fd/op 或 paddle_xxx 有不同版本的 so，则锁定原因。

---

实验 3：提前 import 所有相关 so 再跑（验证加载顺序问题）

把 run_model.py 最开始加上：

import fastdeploy.model_executor.ops.gpu

再运行，看看 deepseek ops 是否还会坏掉。

如果这能解决 → 100% 是符号覆盖问题。

---

🧩 临时规避方案（工程可用）

✔️ 方案 1：固定 dlopen 模式

设置：

export LD_BIND_NOW=1

迫使 .so 提前解决 symbol，不随运行时改变。

---

✔️ 方案 2：在 import fastdeploy 前 import deepseek ops

让 deepseek ops 的 so 表先进入进程符号表：

from fastdeploy.model_executor.ops.gpu import fused_rotary_position_encoding
import fastdeploy

非常常见的解决方式。

---

✔️ 方案 3：统一 Paddle、Metax、FastDeploy 的版本

避免 dev 版本 ABI 不一致。

---

✔️ 方案 4：使用 RTLD_DEEPBIND（需要改 C++ 代码）

给 deepseek ops 的 dlopen 添加：

dlopen(path, RTLD_NOW | RTLD_LOCAL | RTLD_DEEPBIND);

避免符号被后续覆盖。

---

📌 最后结论（简洁版）

你的问题核心原因很可能是：

FastDeploy 的 LLM 运行时加载了一些新的 Paddle/metax/cutlass 相关 .so 后，导致 deepseek ops 依赖的符号被覆盖或替换，运行后再 import 时 symbol 不匹配，引发 ImportError。

这是典型的：

• 多动态库
• 多后端（cutlass/metax）
• 多 dev 版本
• Python native op load

导致的 符号污染问题。

---