3.4.1

# MNN 3.4.1 版本发布说明

**发布日期**: 2026年3月

## 📌 版本概述

MNN 3.4.1 版本聚焦于 **Qwen3.5 模型支持与 Linear Attention 算子**、**LLM 资源管理优化** 与 **安全性修复** 三大核心主题：

*   **Qwen3.5 支持与 Linear Attention**: 全新实现 Linear Attention 算子，覆盖 CPU、Metal、OpenCL、Vulkan 四大后端(性能待优化)，支持 Qwen3.5 系列混合注意力架构；llmexport 新增对应模型导出能力。
*   **LLM 资源管理优化**: LLM 实例内置独立 Executor 并在所有公开方法中使用 ExecutorScope，确保计算资源正确作用域化和及时释放，解决 Python 调用场景下的资源泄漏问题。
*   **安全性与稳定性**: 修复多个 Shape 算子和执行算子中的内存安全漏洞；修复 HQQ 量化 OOM 和大词表 Embedding 溢出；修复多个 LLM 和 GPU 后端缺陷。

---

## 🚀 版本亮点

*   **Qwen3.5 模型支持**: 全新支持 Qwen3.5 及 Qwen3.5-MoE 系列模型，包括导出和推理
*   **Linear Attention 算子**: CPU/Metal/OpenCL/Vulkan 四端实现（性能待优化），支持 Gated Delta Rule 循环状态更新
*   **Vulkan CoopMat Conv1x1**: Vulkan 后端 Conv1x1 算子支持协作矩阵加速，进一步提升矩阵计算性能
*   **LLM Executor 内置化**: 每个 LLM 实例自带独立 Executor，Python 绑定下资源释放更可靠
*   **内存安全修复**: 修复 7 个 Shape/执行算子中的越界访问、零步长、重复索引等安全漏洞
*   **HQQ 大模型量化修复**: 修复 Qwen3.5-27B 等大模型 HQQ 量化 OOM 问题
*   **Sana Diffusion 增强**: iOS/Android 全面支持 Sana 风格迁移、Omni 音频输出、视频输入等新功能
*   **Metal 后端增强**: MetalConvolutionDepthwise 支持 Clone；修复 INT8/INT4 Conv2D 计算错误

---

## ✨ 新功能

### LLM/VLM
*   **Qwen3.5 模型支持**: 支持 Qwen3.5 和 Qwen3.5-MoE 模型的导出与推理，包括混合线性注意力架构
*   **Linear Attention 算子**: 全新实现，包含 Conv1D + SiLU 激活、QKV 拆分、GQA（分组查询注意力）、L2 归一化和 Gated Delta Rule 循环状态更新
    *   CPU: 完整实现含卷积状态和循环状态缓冲区管理
    *   Metal: 三个 Compute Pipeline（conv_silu、conv_state_update、gated_delta_rule）
    *   OpenCL: Buffer 模式实现含专用 OpenCL 内核
    *   Vulkan: 三个 GLSL Compute Shader 实现
    *   以上实现均为功能实现，性能还需优化
*   **LLM Executor 内置化**: 每个 Llm 实例构造时创建独立 Executor，所有公开方法自动使用 ExecutorScope，析构时确保资源完整释放
*   新增 Tokenizer Demo（`tokenizer_demo.cpp`）

### GPU 后端
*   **Vulkan CoopMat Conv1x1**: 新增 `VulkanConv1x1Coop` 实现，包含 C4/COOP 数据布局转换和 INT4/INT8 权重转换 Shader
*   **Metal Clone 支持**: MetalConvolutionDepthwise 支持 `onClone()` 操作

### 应用与工具
*   **Sana Diffusion（iOS）**: 新增风格迁移、Omni 音频输出、视频输入支持；新增批量测试框架
*   **Sana Diffusion（Android）**: 新增 Sana 原生 JNI 层和 Kotlin 会话封装；新增 Diffusion 设置界面
*   **Android Debug 工具**: 新增 Benchmark/Download/Market/Sana/OpenAPI 多个 Stetho Dumper 插件
*   **Android 冒烟测试**: 新增完整的冒烟测试框架，包含环境检查、安装、UI 捕获、回归测试和报告生成
*   **Sana 独立应用**: 新增 `apps/sana/` 独立脚本工具，支持 Android 和主机端 Benchmark

---

## 🔒 安全修复

修复多个算子中的内存安全漏洞：

*   **CPURandomUniform**: 增加 `size <= 0` 边界检查和 `low < high` 验证；增加类型特定处理
*   **ShapeSliceTf**: 修复负值/越界 `begin` 值导致的越界访问
*   **ShapeSpaceToBatchND**: 增加 `blockSize + spatialStart` 越界检查和 `blockData <= 0` 验证
*   **ShapeSpaceToDepth**: 将 `MNN_ASSERT` 替换为正确的错误返回；增加 H/W 对 blockSize 的整除检查
*   **ShapeSqueeze**: 增加维度数上限检查和轴范围验证
*   **ShapeStridedSlice**: 增加零步长检查，替换 `MNN_ASSERT` 为优雅失败
*   **ShapeTranspose**: 增加重复排列索引检测，防止非法内存访问

---

## 🐛 缺陷修复

*   **HQQ 量化 OOM**: 修复 Qwen3.5-27B 等大模型量化时单 GPU 显存溢出，采用分块量化策略
*   **Embedding 整数溢出**: 大词表（~240K tokens）场景下 DiskEmbedding 偏移量从 `int` 改为 `size_t`
*   **LLM JSON 合并**: 修复 Jinja 配置中 `merge_and_clear` 的 JSON 递归合并问题
*   **多模态 OOB 崩溃**: 修复 `llm_bench` 中多模态模型的越界崩溃
*   **Reranker Demo 崩溃**: 修复未加载模型时 reranker_demo 崩溃
*   **Metal INT8/INT4 Conv2D**: 修复 `weighti8i4conv2d` 算子测试错误
*   **Benchmark 崩溃**: 修复 Android Benchmark 崩溃问题
*   **Sana Resize 阈值**: 修正 Sana resize 阈值设置

---

## 📚 其他改进

*   **CI**: 新增 LLM PR Review 自动化流程；pymnn 发布工作流升级至 macOS-14
*   **Android 测试**: 新增大量单元测试（ChatPresenter、ChatRouter、ChatInput、ModelListManager、ModelMarket 等）
*   **iOS 应用**: 本地化全面更新；新增后端配置 UI；新增本地模型索引管理
*   **Android 应用**: 模型市场大幅扩充；新增主设置页面；Debug Activity 增强

---

## 🙏 致谢

衷心感谢所有贡献者对本版本的宝贵贡献：

*   **@jxt1234** - Metal Clone 支持与后端修复
*   **@yanxing** - LLM Benchmark 修复与 CI 改进
*   **@若遗** - Sana Android 集成与 Benchmark 修复

---

## 📦 不兼容变更

*   LLM 实例现在内置独立 Executor，`llm_demo.cpp` 中不再需要外部创建 ExecutorScope（已自动移除）

---

**完整变更日志**: https://github.com/alibaba/MNN/compare/3.4.0...3.4.1

---
---

# MNN 3.4.1 Release Notes

**Release Date**: March 2026

## 📌 Overview

MNN 3.4.1 focuses on three core themes: **Qwen3.5 Model Support with Linear Attention**, **LLM Resource Management Optimization**, and **Security Fixes**:

*   **Qwen3.5 Support & Linear Attention**: Implements a new Linear Attention operator across CPU, Metal, OpenCL, and Vulkan backends to support the Qwen3.5 series hybrid attention architecture; llmexport adds corresponding model export capabilities.
*   **LLM Resource Management**: Each LLM instance now creates its own Executor and uses ExecutorScope in all public methods, ensuring proper resource scoping and timely release, especially in Python binding scenarios.
*   **Security & Stability**: Fixes memory safety vulnerabilities in multiple shape and execution operators; fixes HQQ quantization OOM and large-vocabulary embedding overflow; addresses multiple LLM and GPU backend issues.

---

## 🚀 Highlights

*   **Qwen3.5 Model Support**: Full support for Qwen3.5 and Qwen3.5-MoE series models, including export and inference
*   **Linear Attention Operator**: Implemented across all four backends (CPU/Metal/OpenCL/Vulkan) with Gated Delta Rule recurrent state updates
*   **Vulkan CoopMat Conv1x1**: Cooperative matrix acceleration for Conv1x1 on Vulkan backend
*   **Built-in LLM Executor**: Each LLM instance manages its own Executor, enabling reliable resource cleanup in Python bindings
*   **Memory Safety Fixes**: Fixed 7 shape/execution operators with out-of-bounds access, zero-stride, and duplicate index vulnerabilities
*   **HQQ Large Model Fix**: Fixed OOM when quantizing large models like Qwen3.5-27B with HQQ
*   **Sana Diffusion Enhancement**: iOS/Android support for Sana style transfer, Omni audio output, video input, and more
*   **Metal Backend Enhancement**: MetalConvolutionDepthwise Clone support; INT8/INT4 Conv2D fix

---

## ✨ New Features

### LLM/VLM
*   **Qwen3.5 Model Support**: Export and inference support for Qwen3.5 and Qwen3.5-MoE models with hybrid linear attention architecture
*   **Linear Attention Operator**: Full implementation including Conv1D + SiLU activation, QKV split, GQA (Grouped Query Attention), L2 normalization, and Gated Delta Rule recurrent state update
    *   CPU: Complete implementation with convolution state and recurrent state buffer management
    *   Metal: Three compute pipelines (conv_silu, conv_state_update, gated_delta_rule)
    *   OpenCL: Buffer mode implementation with dedicated OpenCL kernel
    *   Vulkan: Three GLSL compute shader implementation
*   **Built-in LLM Executor**: Each Llm instance creates its own Executor at construction, all public methods use ExecutorScope automatically, destructor ensures complete resource cleanup
*   Added Tokenizer Demo (`tokenizer_demo.cpp`)

### GPU Backends
*   **Vulkan CoopMat Conv1x1**: New `VulkanConv1x1Coop` with C4/COOP data layout conversion and INT4/INT8 weight conversion shaders
*   **Metal Clone Support**: MetalConvolutionDepthwise supports `onClone()` operation

### Apps & Tools
*   **Sana Diffusion (iOS)**: Style transfer, Omni audio output, video input support; batch test framework
*   **Sana Diffusion (Android)**: Native JNI layer and Kotlin session wrapper; Diffusion settings UI
*   **Android Debug Tools**: Multiple Stetho dumper plugins for Benchmark/Download/Market/Sana/OpenAPI
*   **Android Smoke Tests**: Complete smoke testing framework with environment checks, installation, UI capture, regression tests, and report generation
*   **Sana Standalone App**: New `apps/sana/` standalone scripts for Android and host benchmarking

---

## 🔒 Security Fixes

Fixed memory safety vulnerabilities in multiple operators:

*   **CPURandomUniform**: Added `size <= 0` bounds check and `low < high` validation; type-specific handling
*   **ShapeSliceTf**: Fixed out-of-range `begin` values causing out-of-bounds access
*   **ShapeSpaceToBatchND**: Added `blockSize + spatialStart` overflow check and `blockData <= 0` validation
*   **ShapeSpaceToDepth**: Replaced `MNN_ASSERT` with proper error returns; added H/W divisibility checks
*   **ShapeSqueeze**: Added dimension count upper bound and axis range validation
*   **ShapeStridedSlice**: Added zero-stride checks, replacing `MNN_ASSERT` with graceful failure
*   **ShapeTranspose**: Added duplicate permutation index detection to prevent invalid memory access

---

## 🐛 Bug Fixes

*   **HQQ Quantization OOM**: Fixed single-GPU OOM when quantizing large models (e.g., Qwen3.5-27B) using chunk-based quantization
*   **Embedding Integer Overflow**: Changed DiskEmbedding offset from `int` to `size_t` for large vocabularies (~240K tokens)
*   **LLM JSON Merge**: Fixed recursive JSON merge issue in `merge_and_clear` for jinja config
*   **Multimodal OOB Crash**: Fixed out-of-bounds crash for multimodal models in `llm_bench`
*   **Reranker Demo Crash**: Fixed crash when model is not loaded in reranker_demo
*   **Metal INT8/INT4 Conv2D**: Fixed `weighti8i4conv2d` op test errors
*   **Benchmark Crash**: Fixed Android benchmark crash
*   **Sana Resize Threshold**: Fixed Sana resize threshold value

---

## 📚 Other Improvements

*   **CI**: Added LLM PR Review automation; upgraded pymnn release workflow to macOS-14
*   **Android Tests**: Added extensive unit tests (ChatPresenter, ChatRouter, ChatInput, ModelListManager, ModelMarket, etc.)
*   **iOS App**: Comprehensive localization updates; backend configuration UI; local model index management
*   **Android App**: Model market expansion; new main settings page; enhanced Debug Activity

---

## 🙏 Acknowledgements

We sincerely thank all contributors for their valuable contributions to this release:

*   **@jxt1234** - Metal Clone support and backend fixes
*   **@若遗** - Sana Android integration and benchmark fixes

---

## 📦 Breaking Changes

*   LLM instances now have a built-in Executor; external ExecutorScope creation in `llm_demo.cpp` is no longer needed (automatically removed)

---

**Full Changelog**: https://github.com/alibaba/MNN/compare/3.4.0...3.4.1

---

*本文由 Claude Opus 4.6 协助生成 / This document was generated with assistance from Claude Opus 4.6*