doc: MoE 5函数符号真相 — 不在预装.so里,由moe_ops_impl.cu自编译

确认结果:
- topk_softmax, moe_compute_token_index_api, moe_expand_input,
  moe_w16a16_group_gemm, moe_output_reduce_sum
- namespace 是 ixformer::infer (Tensor API), 不是 ixformer::kernels::infer (raw ptr API)
- 4个镜像.so全部nm -D搜过,均无这些符号
- 实现在 ex_engine/csrc/moe_ops_impl.cu (自编译CUDA kernel)
- 由 build_moe_bridge.sh 编译进 ix_full_bridge_v2.so
- kernels.h 里的 ixformer::kernels::infer 是SDK头文件声明(模板+raw ptr)
  我们的 ixformer::infer 是独立实现(torch::Tensor wrapper)

MOE_SYMBOL_TRUTH.md

@@ -0,0 +1,68 @@
+# MoE 函数符号真相 (2026-08-17 确认)
+
+## 结论
+
+那5个 MoE 函数**确实不在任何镜像预装的 .so 里**。另一位开发者说的是对的。
+
+但它们也**不需要**在预装 .so 里——它们是自编译的。
+
+## 5个函数的正确命名空间
+
+```
+ixformer::infer::topk_softmax
+ixformer::infer::moe_compute_token_index_api
+ixformer::infer::moe_expand_input
+ixformer::infer::moe_w16a16_group_gemm
+ixformer::infer::moe_output_reduce_sum
+```
+
+**注意**: 是 `ixformer::infer`，不是 `ixformer::kernels::infer`。
+
+## 声明 vs 实现的关系
+
+| 位置 | 角色 |
+|------|------|
+| `ixformer_sdk/csrc/include/ixformer/kernels/kernels.h` | **头文件声明** (namespace `ixformer::kernels::infer`) — C++ 模板声明，给 SDK 用的 |
+| `ex_engine/csrc/moe_ops_impl.cu` | **CUDA 实现** (namespace `ixformer::infer`) — 自己写的 kernel，不依赖任何 .so |
+| `ex_engine/csrc/ix_full_bridge_v2.cpp` | **pybind11 桥** — forward-declare 然后调用 moe_ops_impl.cu 里的实现 |
+| `ex_engine/build_moe_bridge.sh` | **构建脚本** — 把 v2.cpp + moe_ops_impl.cu 一起编译成 ix_full_bridge_v2.so |
+
+## 符号表搜索结果 (4个 .so 全部搜过)
+
+| .so 文件 | MoE 函数 | 结论 |
+|----------|----------|------|
+| `libixformer.so` (3937 symbols) | 无 topk_softmax/moe_compute_token_index 等 | 只有 `reduce_sum` (通用的) |
+| `_ixformer_torch.so` (49 symbols) | 完全没有 MoE | 只有 norm/rope/cache/attn |
+| `_C.so` (6 symbols) | 几乎空壳 | 只有 PyInit |
+| `libcuinfer.so` (270 symbols) | 只有 cuinferTopK (不是 MoE 的) | GEMM/BLAS 级别 |
+
+## 构建链
+
+```
+patch_ops.sh
+  └→ build_moe_bridge.sh
+       └→ ninja/CppExtension 编译:
+            ix_full_bridge_v2.cpp + moe_ops_impl.cu
+            → ix_full_bridge_v2.so (包含5个MoE函数的实现)
+```
+
+## `ixformer::kernels::infer` vs `ixformer::infer` 的区别
+
+- `ixformer::kernels::infer` — SDK 头文件 (kernels.h) 中的声明，使用 raw pointer + cudaStream_t 
+  - 例: `void moe_topk_softmax(const T *gating_output, T *topk_weights, int *topk_indices, ...)`
+- `ixformer::infer` — 我们自己实现的 PyTorch wrapper，使用 torch::Tensor
+  - 例: `void topk_softmax(torch::Tensor& topk_weights, torch::Tensor& topk_indices, ...)`
+
+`moe_ops_impl.cu` 是直接写 CUDA kernel（不调用 kernels.h 模板），然后暴露 Tensor API。
+
+## Python 调用链
+
+```python
+# 通过 ixformer SDK (需要真机上的 _C.so 包含 infer 子模块):
+import ixformer._C as ops
+ops.infer.moe_topk_softmax(...)  # 如果 _C.so 有实现
+
+# 通过 ex_engine bridge (我们自编译的):
+import ix_full_bridge_v2 as bridge
+bridge.topk_softmax(...)  # 来自 moe_ops_impl.cu
+```