简介：一款面向MATLAB用户的高阶张量分析工具箱，版本3.2.1，专攻多维数组的建模与分解。工具箱内置CP分解、Tucker型奇异值分解、张量乘除与索引操作等核心算法，可支撑图像处理、社交网络挖掘和多源数据融合等典型场景，供科研人员与工程开发者快速搭建张量算法原型。压缩包共534个文件，体积仅1.76MB，以m函数源码为主，同时包含png示意图、html与md格式的说明文档，以及必要的配置与示例数据，结构规整，便于检索和复用。目前已有1083人学习下载。包内附有多种分解函数的可直接运行示例，如cp_isym、gcp_opt等，并配有张量对象的定义与演示代码，读者稍作修改即可移植到自己的数据上，显著降低高阶张量分析的实验门槛。该工具箱接口友好，示例丰富，无论用于课程实验还是实际项目，都能让人快速上手并受益。

1. tensor_toolbox-v3.2.1：MATLAB 里做张量分解，先把这个包装对用对

Tensor Toolbox v3.2.1 是 MATLAB 生态里最常用的张量计算工具包，覆盖 CP（CANDECOMP/PARAFAC）分解、Tucker 分解、张量矩阵化（tenmat）、模乘（ttm/ttv）、稀疏张量存储这一整条操作链。对做脑电、传感器阵列、推荐系统这类天然带三个及以上维度的数据分析场景，这个包最大的价值是把原来以周为单位的实现周期压缩到以小时为单位——核心流程就是构造张量对象、调用分解函数，剩下的是选参数和判断结果。

它适合两类人：一类是刚上手张量分解、想先用现成实现验证方法效果的研究者；另一类是模型已经跑通、需要在 MATLAB 里做实验对比和数据落地的工程师。下面顺着 v3.2.1 这个 zip 包，从安装、核心对象、两大分解函数一路讲到参数调优、避坑和验证习惯。文中的代码按步骤就能复现，踩过的坑也都标了原因和修法。

2. 安装与核心对象：从 zip 包到跑通第一个 ttm/ttv 运算

2.1 解压、路径配置与版本自检

拿到 tensor_toolbox-v3.2.1.zip 后，最常见的做法是先解压到工作目录，再把整个目录递归加入 MATLAB 搜索路径：

unzip('tensor_toolbox-v3.2.1.zip', 'tensor_toolbox'); addpath(genpath(fullfile(pwd, 'tensor_toolbox'))); savepath;

这里必须用 genpath 而不是 addpath 单层目录，因为包内部有 @tensor、@sptensor、@ktensor 等类目录和若干工具子目录，只加一层会导致很多方法找不到。savepath 是把路径写进 MATLAB 的默认路径文件，本地用完全没问题；但如果你的工作环境是服务器或集群，home 目录可能只读，savepath 会静默失败。这种情况不用慌，在每天的任务脚本开头重复执行 addpath 那行就行，代价只是每次启动多花零点几秒。

路径加好后，自检两件事：

which cp_als help tensor

which 返回空，说明路径没进来；返回多个结果，说明和其他函数重名，需要把 toolbox 放到路径最前面：

addpath(genpath(fullfile(pwd, 'tensor_toolbox')), '-begin');

提示：v3.2.1 对 MATLAB 版本要求不算苛刻，但建议用 R2016b 之后的版本。最可靠的自检是跑一下cp_als(tenrand([5 5 5]), 2)，几秒钟内能返回一个 ktensor 就说明环境没问题。

2.2 tensor、sptensor、ktensor：三种存储模型怎么选

工具包的核心不是某个算法函数，而是四个对象类：tensor 表示稠密张量、sptensor 表示稀疏张量、ktensor 表示 CP 分解结果、ttensor 表示 Tucker 分解结果。先分清它们，后面代码才不会乱。为什么不用普通多维数组直接算？因为普通数组没有重载 norm、ttm、find 这些操作，你每做一步都要自己写下标映射，而对象类把这些操作全部封装成了对张量语义自然的调用。

X = tensor(randn(40, 50, 60)); % 稠密：内部就是多维 double S = sptenrand([100 200 300], 5000); % 稀疏：只存 5000 个非零 P = ktensor(rand(3,1), {randn(40,3), randn(50,3), randn(60,3)}); T = ttensor(tensor(randn(3,4,5)), {randn(40,3), randn(50,4), randn(60,5)});

sptenrand(维度向量, 非零个数) 是生成稀疏随机张量的快捷方式。ktensor 构造函数第一个参数是权重 lambda，第二个是因子矩阵的 cell 数组。ttensor 第一个参数是核心张量，第二个是各模式因子矩阵。四者的关系是：full(P) 可以把 ktensor 展开成稠密 tensor，double(X) 可以把 tensor 转回普通多维数组，sptensor 和 tensor 之间也可以互转——但展开之前一定先算一下各维度之积，防止内存翻车。

选型判断很简单：非零占比低于 10% 又超过三维的数据，直接用 sptensor；数据本身就是密集矩阵堆出来的，用 tensor；要保存和传递分解结果，保持 ktensor/ttensor 形式，直到可视化或算误差再展开。我见过不少人在 sptensor 上反复 full 再切片，把稀疏优势全浪费掉，这是最常见的误用。

2.3 ttm 与 ttv：模乘的维度语义和一个矩阵化示例

张量运算里最容易搞混的就是 mode（模式）编号。ttm 是沿某个模式做矩阵乘，ttv 是沿某个模式做向量缩并：

X = tensor(randn(10, 20, 30)); A = randn(5, 10); Y = ttm(X, A, 1); % 沿模式1乘：结果是 5×20×30 v = randn(30, 1); Z = ttv(X, v, 3); % 沿模式3缩并：结果是 10×20

ttm 的规则是：矩阵 A 的列数必须等于 X 在该模式的维度，乘完后该模式维度变成 A 的行数，其他模式不变。ttv 则是把该模式整个消掉，相当于在那一维上做内积。多模式可以一次乘：

Y = ttm(X, {A, B}, [1 2]); % 同时沿模式1和模式2乘

这里 A 的列数要等于 size(X,1)，B 的列数要等于 size(X,2)。我把行数和模式号搞反过一次，当时报错提示维度不匹配，实际是脑子里的矩阵语义没切换过来。MATLAB 里张量按列优先存储，矩阵操作的直觉不能直接搬到模式编号上。

矩阵化（matricization）是分解前后最常用的桥接操作：

M = tenmat(X, 2); % 模式2矩阵化：结果是 20×300 Xr = tensor(M); % 从 tenmat 还原成张量

tenmat 把张量按指定模式展开成二维矩阵，常用来给外部算法喂数据；还原时用 tensor(M) 即可，tenmat 内部记录了原始维度信息，不需要你再传 size。

这个表的意思很直白：绝大多数操作都可以直接作用在稀疏或分解形式上，不需要你手动展开。如果你发现某段代码里反复出现 full，多半是哪里姿势不对。

3. 用 cp_als 跑通第一轮 CP 分解：R、tol、maxiters 与多初始化调参

3.1 最小可复现流程：造一个 40×50×60 的张量

CP 分解把一个 D 维张量近似成 R 个秩一分量的和，每个分量在各模式上各有一个因子向量。Tensor Toolbox 的实现是 cp_als，也就是交替最小二乘：固定其他因子、更新一个因子，循环往复。调用非常短：

X = tensor(randn(40, 50, 60)); R = 5; P = cp_als(X, R, 'tol', 1e-6, 'maxiters', 200, 'printitn', 10);

返回的 P 是 ktensor：P.U{1} 是 40×5，P.U{2} 是 50×5，P.U{3} 是 60×5，P.lambda 是 5×1 的权重向量。printitn=10 表示每 10 次迭代打印一行进度，能看到 fit 值在涨还是卡住。跑完先用一行看重构质量：

fprintf('相对误差: %.4e\n', norm(X - full(P)) / norm(X));

对小规模演示数据这么算没问题，数据量级上来之后要换成第 6 章的 innerprod 方式，避免 full(P) 爆内存。这个最小流程是所有实验的基础，先跑通它，再谈调参。

3.2 cp_als 参数：tol、maxiters、printitn 怎么设

cp_als 有四个参数是每次都要过一遍的：

tol 控制的是收敛判据，不是误差阈值。它判断的是两次迭代之间拟合指标的变化量，变化小于 tol 就认为收敛。所以 tol 设得越小，迭代越久，但最终误差不一定更小——噪声数据上死磕 tol 意义不大。maxiters 是保护机制，我遇到过 tol 设 1e-9 之后 maxiters 保持默认 50，迭代到点被掐、fit 还在涨的情况，那时要么放宽 tol，要么把 maxiters 提到 500。

R 是 CP 里最重要的参数，它相当于你要从数据里抽出的成分数。R 太小，重构误差大；R 太大，会出现两个因子几乎线性相关、迭代震荡。选 R 没有一次性公式，带一点玄学成分，常见做法是从小到大试几个值（比如 2、3、5、8、10），看相对误差的下降曲线在哪里变平。这个曲线是判断 R 最靠谱的依据，比任何理论公式都实在。

3.3 初始化方式与多初始对比：nvecs vs random

cp_als 是非凸优化，初值决定结局。工具包内置两种初始化：'nvecs' 是拿高阶奇异值分解的因子矩阵当初值，稳定、可复现，但容易限在某个局部最优附近；'random' 是随机初值，多跑几次取最好，是校验稳定性的标准姿势：

P1 = cp_als(X, R, 'init', 'nvecs', 'tol', 1e-6, 'printitn', 0); P2 = cp_als(X, R, 'init', 'random', 'tol', 1e-6, 'printitn', 0);

对比 P1、P2 的误差，如果接近，说明这个 R 和这个数据是稳定的；如果差很多，说明模型不适定或 R 不合适，这时候换 R 比重跑初始化更有效。批量多初始的时候，我习惯写个简单循环：

best_fit = -Inf; best_P = []; for i = 1:10 Pi = cp_als(X, R, 'init', 'random', 'tol', 1e-6, 'printitn', 0); f = 1 - norm(X - full(Pi)) / norm(X); % fit 值，越接近 1 越好 if f > best_fit best_fit = f; best_P = Pi; end end

循环里每次都算 norm(X - full(Pi))，数据大了会痛，优化方法在第 6 章。如果你已经在一组 R 下跑出了好结果，想在此基础上继续收紧误差，可以把上次的因子矩阵当热启动再跑一轮：

P_refine = cp_als(X, R, 'init', P.U, 'tol', 1e-8, 'printitn', 0);

init 接受 cell 数组，P.U 正好是因子矩阵的 cell，直接喂进去就行。热启动通常几轮迭代就能收敛，但它也会把结果锁定在原来的局部最优附近，所以只适合微调，不适合探索新结构。

4. 用 tucker_als 做 Tucker 分解：核心维度选择与 CP 的选型对比

4.1 tucker_als 的最小调用与 ttensor 结构

Tucker 分解是把一个张量拆成一个小核心张量乘上各模式的因子矩阵，因子矩阵之间有正交约束，核心张量保留模式间的交互。工具包里的实现是 tucker_als，本质是 HOOI 算法，每轮迭代对核心张量做一次 SVD 来更新因子矩阵：

T = tucker_als(X, [10 10 10], 'tol', 1e-5, 'maxiters', 100, 'printitn', 5);

这里假设 X 是 40×50×60。返回的 T 是 ttensor：T.core 是 10×10×10 的核心张量，T.U{1}、T.U{2}、T.U{3} 分别是 40×10、50×10、60×10 的因子矩阵。核心张量的维度就是你要保留的压缩后维度，由第二个参数 [10 10 10] 指定，各模式可以不同，比如 [8 12 6]。

和 cp_als 相比，tucker_als 对初值没那么敏感，因为正交约束本身限制了搜索空间。但它的计算更重：每轮都要做矩阵 SVD，核心张量维度大了之后内存和耗时都涨得比 CP 明显。我的经验是，确认要用 Tucker 之前先想清楚一个问题：你要保留的模式间交互到底是什么。如果只是想要一个压缩表示，Tucker 是稳妥选择；如果是想抽潜变量，CP 更合适。

4.2 核心维度怎么挑：误差曲线的拐点法

核心维度就是压缩比，选小了丢信息，选大了没压缩效果，还容易过拟合噪声。没有公式能直接给答案，最常见的做法是网格试 + 看误差拐点：

rs = [5 10 15 20]; errs = zeros(size(rs)); for i = 1:numel(rs) Tc = tucker_als(X, rs(i)*ones(1,3), 'printitn', 0); errs(i) = norm(X - full(Tc)) / norm(X); end plot(rs, errs, '-o');

这条曲线通常在某个维度之后开始走平，走平的那个点就是性价比最高的核心维度。注意，对称地给三个模式相同维度只是偷懒写法；实际中三个模式的信息量往往差别很大。更稳的做法是先固定其他模式，对每个模式单独扫一遍维度，找出各自的信息量拐点，再组合起来跑一轮确认。这个流程看起来繁琐，但比拍脑袋选 [r r r] 靠谱得多，尤其当你的数据是传感器×时间×条件这类本身就不对称的结构。

4.3 Tucker 和 CP 怎么选：一张表说清异同

做分析前先选模型，这是路线问题。参数调不对还能改，模型选错整个结论都要推翻。两者本质区别在于：CP 是共享一组潜变量，每个分量在所有模式上同时出现；Tucker 允许各模式有自己的潜在维度，分量可以在不同模式组合成不同的交互。

一句话判断：如果你的科学问题里各模式应该共享同一组成分，用 CP；你只是想把高维数据压到能处理的大小，并保留模式间关系，用 Tucker。实在拿不准就两个都跑一遍，对比重构误差和结果的可解释性——解释性比误差数字更能说明问题，误差低但因子全是噪声的组合没有意义。

4.4 用 ttm 重构与误差验证

Tucker 重构在数学上就是核心张量沿每个模式乘因子矩阵，工具包里可以直接用 ttm 完成：

Xhat = ttm(T.core, T.U, [1 2 3]); % 等价于 full(T) relerr = norm(X - Xhat) / norm(X);

ttm(T.core, T.U, [1 2 3]) 把 T.U 里的三个矩阵分别沿模式 1、2、3 乘回核心张量，结果和 full(T) 一致。这里留一个检查习惯：算完误差后打印 T.U 各列之间的正交性，比如 norm(T.U{1}'*T.U{1} - eye(10))。算法理论上保证正交，但数值上偏离太大往往是迭代被 maxiters 掐断的信号，说明核心维度选大了或者数据信噪比太低，这时优先看迭代日志而不是继续调参数。

5. tensor_toolbox 避坑：五个翻车现场与对应修复

用这个包的人十个里有八个掉进过同一类坑：不是算法不收敛，而是对象类型用错、维度顺序搞反、或者不知道分解结果本身有不确定性。下面五条是最高频的翻车现场，每条都是现象、原因、解决的完整链条。

5.1 稀疏张量被 full 化导致内存爆炸

现象：对一个非零数很少但维度很大的 sptensor 执行 full(X)，MATLAB 直接报内存不足或长时间无响应。更隐蔽的是在 norm(X - full(P)) 里，X 是稀疏的，但 full(P) 是稠密的，两者做差产生一个巨大的稠密临时变量，照样爆内存。

原因：full 展开后的大小是各模式维度之积。100×200×300 只有 600 万个元素还好，1000×1000×1000 就是 10 亿个 double，约 8 GB，再算上差值的临时变量直接翻倍。稀疏和高维是 full 化的天敌。

解决：全程保持 sptensor 形式参与运算，norm、ttm、find 都支持稀疏对象。需要算误差时不要全展开，改成第 6 章的 innerprod 方式，或者只取 X 的非零下标位置在重构结果上取值对比。只有最终出图或者做小切片分析时才 full。

5.2 cp_als 不收敛或因子出现 NaN

现象：打印日志里 fit 不是单调上升，而是来回跳；跑完 P.U 里某列全是 NaN；或者 tol 一直达不到，次次都是 maxiters 到点退出。

原因：排第一的是原始数据里有 NaN。cp_als 的交替最小二乘不会替你处理缺失值，任何一个 NaN 都会沿迭代扩散成整列 NaN，这是最典型的翻车原因。排第二是 R 过大导致成分退化，或初值太差进入震荡。

解决：分解前先查一把any(isnan(double(X(:))))。有缺失的话，简单做法是先按均值或零填充再分解；要严谨就改用带权重的分解方案（工具包里的 cp_wopt 这类），把缺失位置权重置 0。注意 NaN 检查对 sptensor 要小心：稀疏对象根本不存零位，先 full 再查等于自杀，正确做法是[~, vals] = find(X)然后查 vals。没有缺失还不收敛，按降 R、换 nvecs 初值、加大 maxiters 的顺序排查。

5.3 mode 顺序弄反，分解结果全乱

现象：ttm 报维度不匹配；分解出来了，但因子矩阵的长度和预期对不上；更糟的是不报错，结果张冠李戴，画出来的图全是错的。

原因：张量的 mode 顺序完全由你构造时决定，工具包严格按 mode 执行，不关心你在脑中的行 vs 列直觉。我翻过一次车：把数据按 [条件, 通道, 时间] 构造，却在心里当成 [通道, 时间, 条件] 解释，结果通道和时间两个维度的因子矩阵解释全反。

解决：任何分解、任何 ttm 之前，先打印 size(X) 并在代码注释里写死每个模式的含义，例如% mode1=通道, mode2=时间, mode3=条件。发现顺序不对，用 permute 调整后再进分解，不要在分解之后靠肉眼翻转因子矩阵。这个成本极低，收益是保证整条实验链路的解释方向一致。

5.4 ktensor 符号翻转与成分换序

现象：同一数据两次独立分解，第一轮的第 2 成分和第二轮的第 2 成分数值差一个负号；或者成分 2 和 3 整体换了位置，重构误差基本不变。

原因：CP 分解在数学上存在固有的缩放与排列不确定性。任意成分可以整体乘 -1 而不改变重构结果，成分顺序也可以任意交换。这不是 bug，是模型本身的自由度。

解决：所有成分级对比前，先做两步处理：

P = arrange(P); % 按 lambda 权重降序重排成分 P = fixsign(P); % 统一符号方向，让每列绝对值最大的元素为正

之后再做因子对齐、算相似度才有意义。多个模型对比 R 时，也先 arrange 再存盘，免得事后对不上。这个坑在你看单个模型的因子矩阵时完全无感，一旦横向对比两个模型就会立刻暴露。

5.5 addpath 后 which 找不到或函数被遮蔽

现象：addpath 执行成功，但 which cp_als 返回空；或者调用时 MATLAB 用了别的路径下的同名函数，行为诡异，报错信息看不懂。

原因：路径没真正生效，常见于解压后目录多包了一层（tensor_toolbox 下又套一层同名目录），导致类目录不在搜索路径的顶层；也可能是工具箱自带的 size、find、norm 等重载方法被其他工具箱的同名类函数遮蔽。

解决：用 which -all cp_als 看所有命中位置，确认是不是被挤在后面；用addpath(..., '-begin')把 toolbox 提到最前。检查目录结构，确保 @tensor、@sptensor 这些类目录直接位于你 addpath 的那一层下。另外，保存路径文件后重启 MATLAB 是最快的验证方式，省得被路径缓存骗了。

6. 验证分解结果的三个习惯：从误差到可复现

6.1 误差口径统一用相对误差

不管 CP 还是 Tucker，报告结果统一用相对重构误差，别单独看 fit 或者只看因子矩阵漂不漂亮：

relerr = norm(X - full(P)) / norm(X); fprintf('R=%d, relerr=%.4e, fit=%.4f\n', R, relerr, 1-relerr);

不同 R、不同模型之间只有相对误差是可比的，fit 的绝对值会随数据尺度变化，不能跨数据比。

6.2 用合成数据验证分解可恢复性

工具用没用对，最快的检验是造一份已知结构的合成数据，看分解能不能把真实因子恢复出来：

A = randn(30, 4); B = randn(40, 4); C = randn(50, 4); X = full(ktensor(rand(4,1), {A, B, C})); % 已知真实因子 P = cp_als(X, 4, 'printitn', 0); P = arrange(fixsign(P));

恢复出来的因子和真实 A、B、C 在 arrange/fixsign 之后应该方向一致，相关系数接近 1。这个习惯能同时验证你对 mode 的理解、参数设置和误差计算，是成本最低的地基检查。

6.3 大张量误差用 innerprod，别 full

数据大了以后，norm(X - full(P)) 里的展开是瓶颈。工具包提供了 innerprod，可以用范数恒等式避免构造稠密差值：

nx2 = norm(X)^2; % X 的范数平方，只算一次 np2 = norm(P)^2; % P 是 ktensor，范数由因子直接算 ip = innerprod(X, P); % 内积，稀疏 X 时按非零位累加 relerr = sqrt(max(nx2 + np2 - 2*ip, 0)) / sqrt(nx2);

这里用的恒等式是 ||X - P||² = ||X||² + ||P||² - 2·<X,P>。norm(P) 对 ktensor 有解析式，innerprod(X, P) 在 X 是 sptensor 时只在非零下标上累加，全程不产生稠密临时变量。把 nx2 放在循环外面，多初始重跑时速度差距在小数据上不明显，上了大张量就是能不能跑完的区别。

我自己的习惯是：任何实验脚本至少包含 6.1 和 6.2，批量跑之前先在小数据上确认分解可恢复，再上全量；全量阶段用 6.3。这三个习惯救过我很多次，尤其是从别人手里接数据、不清楚 mode 含义的时候，合成数据验证能第一时间暴露理解偏差，而不是等整轮实验跑完才发现图全错。希望帮到你。

本文还有配套的精品资源，点击获取