LibFM使用手册中文版
h\text{http://www.libfm.org/libfm-1.42 manual.pdf}(\text{http://www.libfm.org/libfm-1.42 manual.pdf})
自己翻译
libFM 1.4.2 - 指南
Steffen Rendle srendle@libfm.org http://www.libfm.org/ 2014年9月14日
目录
1.说明
• Linux︰ 按照第 1.1 节中的说明编译 libFM 。
• MacOS x︰ 按照第 1.1 节中的说明编译 libFM 。
Windows: 可直接下载的已编译可执行文件（来自libfm-1.40.windows.zip，发布时间为2013年7月12日）。建议直接跳转至第 1.1 节查看相关内容。
请特别注意：已经编译好的可执行程序的版本号是 libFM 1.4.0。这一版本拥有与 libFM 1.4.2 相同功能，并且采用了不同的许可协议。
1.1编译
libFM 已经与GNU编译器集合以及GNU测试系统进行过测试，在Linux操作系统及MacOS上两者均应是可以获取的。
使用以下步骤中，您可以构建 libFM:
获取libFM源代码包：完整版本，请访问以下链接地址：http://www.libfm.org/libfm-1.42.src.tar.gz
如采用该软件工具进行解压操作，则可以有效地处理文件... libfm-1.42.src.tar.gz）。
- 输入目录为 {libfm 1.42.src} 并且编译工具为 make all
文件概述
• history.txt︰ 版本历史记录和更改
• readme.pdf︰ libfm的手册
• Makefile︰ 使用make编译的可执行文件
• bin︰ executables（需要使用make来build，见1.1节）的文件夹
— — libFM: libFM 工具
— — convert︰ 将文字文件转换成二进制格式的工具
— — transpos︰ 转换二进制设计矩阵的一个工具
• scripts
— — 从ltiple格式转换到libfm.pl文件中，请问您是否需要一个负责生成 libFM 格式的 Perl脚本用于处理数据？
• src︰ 源文件的 libFM 和工具
2.数据格式
libFM 采用了两种数据输入格式：文本数据形式和二进制数据形式。选择文本数据形式更为便捷的方式进行操作，则建议新版本的libFM用户采用文本数据形式进行操作
2.1 文本格式
该数据存储方式一致遵循SVMlite [3] 和 LIBSVM [1] 的结构。每个样本代表一个训练样本（x,y）。对应分配实数特征向量x和目标值y，在每行中首先定义了目标值y。
对于二进制类型，y>0的类型被认为是积极的一类，y<=0被认为是消极的一类。
此 文件 包含 三个case：
第一 列 指出 的 三个case 的 每个 目标 ︰4是第一个case的， 2是 第二的，-1是 第 三个 。
在每个 目标 之后 , 包含 非零 元素x。如 0:1.5 表示
= 1.5 ， 3 :-7.9 表示
= −7.9 等等 。
即：
左边的值是 x 的 索引 ， 而 右边的是
的值 ， 即
= 值 。
总之，上述例子表示如下设计矩阵X和目标向量y；
2.1.1转变到推荐文件
在推荐系统中经常使用像 userid， itemid， rating的这样的文件格式。
在script文件夹中的Perl脚本用于将特定数据格式的数据集转译为libFM格式。例如，在将Movielens 1M中的rating.csv转译为libFM格式时。
使用——
./triple_format_to_libfm.pl-in ratings.dat -target 2 -delete_column 3 -separator "::"
输出将被编码到一个扩展名为libfm的特殊文件里。例如，在toratings.dat.libfm这个位置上存储数据。
当一个数据集包含多个文件时
./triple_format_to_libfm.pl -in train.txt,test.txt-target 2 -separator "\t"
注意：
如果你为每个文件单独一次脚本，则变量（id）将不会匹配了。
例如，在第一个文件中对应位置的变量会与第二个文件中对应位置的变量不同。
2.2二进制文件
除了标准的文本格式，libFM 支持二进制数据格式。
该二进制文件的优点：
（1） 读的速度快
（2）如果您的数据无法加载到内存中，则二进制数据格式能够实现将数据存储在硬盘上并仅保留在内存中仅有少部分（参考libFM中的高速缓存配置参数）。
如果 你 采用 ALS 和 MCMC 方法，则可以预先计算换位设计矩阵；从而能够减少读取数据集所需的时间。
如下
例如：
将前面提到的电影数据集转换成二级制格式：
./convert --ifile ratings.dat.libfm --ofilex ratings.x --ofiley ratings.y
输出两个文件:
（1）包含设计矩阵X即预测器变量的文件
（2）包含预测目标y的文件
建议，分别以.x和.y作为文件拓展名
2.2.1转置数据（Transpose data）
使用转置设计矩阵（transposed design matrix）来学习MCMC和ALS。
如果您使用的是文本格式，libFm内部会自动转换这些数据。
如果您使用的是二进制格式，二进制格式中必须存在转置数据。
使用transpose工具，将设计矩阵x转换为二级制格式：
例如:转换上述提到的电影数据集：
./transpose --ifile ratings.x --ofile ratings.xt
输出为设计矩阵x的一个转置复制，建议以.xt作为结尾。
3.libFm
libFm工具从训练数据集（-train）和验证数据集（-test）中训练FM模型。
libFm有如下选项：
3.1强制参数
• 指定的 第一个 强制性 参数—— -task 要么是分类 (-task c ) 要么就是 回归 (-任务 r)。
第二训练数据（-train）和测试数据（-test）必须存在，并且此外还可以采用二进制文件或libFm文本格式文件
• 第三，分解机的维度需要用-dim来指定，由三个数字组成，
——
来确定全局偏移
是否要在模型中使用。
——
以确定单向交互作用（one-way interactions）（针对每个变量的偏移量）即变量w在模型中是否需要考虑其偏移量
——
给出了用于成对相互作用的因素的个数，即k是
例如，在因子分解机（FM）中通过引入偏差项、一阶相互作用以及将二阶相互作用的因子分解限制为k=8的回归任务中——
/libFM -task r -train ml1m-train.libfm -test ml1m-test.libfm -dim ’1,1,8’
3.2可选参数
3.2.1基本参数
out︰ 训练完成后, 您可以在完成后将所有预测结果通过out字段写入指定文件. out-file字段是文本格式, 与输入数据中的条目数量一致, 其中每个结果对应于输入数据中的相应条目.
请注意，对于分类，有积极类型的数据输出的是概率。
rlog︰生产一个迭代过程中的统计数据日志记录文件，并以制表符分隔字段的形式存储为CSV格式
请注意，它取决于哪些字段报道的学习方法。
指定参数-详细程度设置为1以调用libFM工具输出详细信息。这有助于确认程序运行是否正常并进而识别数据中的问题
3.2.1高阶参数
Grouping
通过使用meta选项能够实现对输入变量group的设置；而grouping则用于为ALS、MCMC以及SGDA等算法确定更为复杂的正则化模型。
每个group可以有一个单独的正则化参数。
为了应用group功能，在配置元参数时必须确保其值为对应的文本文件名称，并且同时处理大量输入变量与多行数据。
需要注意的是
需要注意的是
特别注意
特别注意
例如：
例子1中的设计矩阵（一共7行，最大的id是6）的group文件，应该是这样的
所代表的意义为：总共有三个类别，在设计矩阵中作为变量的前两个属于同一类，在同一个类别中还有第三个以及最后一个变量。
二进制数据和缓存
在2.2节中提及，在二进制文件中设计矩阵通常会使用.x后缀表示目标，并采用.xt后缀表示转置操作。当采用libfm库时，则无需遵循这些特定的后缀规则。
如果你有已编译的训练数据（如 ml₁M-train.Ⅹ、ml₁M-train.Ⅷ 及 ml₁M-train.ⅩⅤ） 以及 三个相关的测试文件（如 ml₁M-test.Ⅹ、ml₁M-test.Ⅷ 及 ml₁M-test.ⅩⅤ），则
使用——
./libFM -task r -train ml1m-train**-test** ml1m-test**-dim ’1,1,8’**
libFm会自动追加适当的扩展名，并为学习算法载入数据集
如果你的数据无法完全加载到内存中，则可以配置libFM以支持多大的文件在其内存环境中存储
使用——
./libFM -task r -train ml1m-train -test ml1m-test -dim ’1,1,8’ -cache_size 100000000
表示为100,000,000 Bytes (100 MB)的内存可以被.x或者.xt文件使用。
【注意】
.y文件通常完全地读入内存中。
如果没有指定参数cache-size，所有数据将都进入内存。
【注意】
仅在数据经由缓存操作比读写内存耗时明显增加且采用硬盘（harddisc）作为存储介质时才不适合直接进行内存操作
Note: When data sets that do not entirely fit into system memory, you should use caching only when it would significantly slow down the overall process. Beacuse caching uses hard discs, which are much slower than memory accesses.
3.3学习方法
默认的学习方式属于一种常规化的技术路线（无需设置学习率），而MCMC算法因其具有易于操作性（无需引入额外的正则化项），成为该领域中被广泛采用的一种方法
在libFM中可以选择SGD、ALS、MCMC以及SGDA。对于这些方法而言，都必须指定迭代次数（iter）。
3.3.1 Stochastic Gradient Descent (SGD)
该系统采用SGD参数实现了高效的梯度下降过程；对于该方法而言，可选的超参数包括学习率、动量项等。
• -learn rate：SGD学习速率的步长，需是一个非零且postive的值
• -regular:正则化参数，需是0或者postive的值
对于SGD，你可以通过以下方法来确定正则化的值：
– One value (-regular value):所有的参数模型使用统一的正则化值
Three values (-regularized ’value0,value1,value2’): 0-way interactions (w0) are used to form the regularization term w0.
1-way interactions (w) use value1
pairwise ones (V ) use value2
– No value:使用-regular 0来表示没有指定正则化值
stdev初始化：基于标准偏差的正态分布这一指标被采用以初始化V参数。在实现过程中，请确保所使用的初始值为非零且正值。
请慎重选择这些参数，预测质量很大程度上取决于对很好的选择。
例如：
./libFM -task r -train ml1m-train.libfm -test ml1m-test.libfm -dim ’1,1,8’ -iter 1000-method sgd -learn_rate 0.01 -regular ’0,0,0.01’ -init_stdev 0.1
3.3.2 Alternating Least Squares (ALS)
通过指定-algorithm parameter, 能够实现SGD learning algorithm, 对此方法而言, 可以选择相应的设置。
• -regular:正则化参数，需是一个非零且postive的值
对于ALS可以使用以下方法来正则化:
– One value (-regular value):所有的参数模型使用统一的正则化值
Three scalar values (-regular 'value0,value1,value2'): zero-order interaction terms (w₀) are regularized using value₀.
1-way interactions (w) use value1
pairwise ones (V ) use value2
Specify the group-specific values (-regular ’value0,value1g1,...,value1gm,value2g1,...,value2gm’): for example, when the input variables are grouped as such for each group.
1-way and 2-way interaction 每一个正则化值都被使用，那么有1+2m个正则化值，
– No value:使用-regular 0来表示没有指定正则化值
-init stdev: 指定遵循正态分布的标准偏差用于初始化V这一参数。建议在这里指定一个非零且positive的值。
请慎重选择这些参数，预测质量很大程度上取决于对很好的选择。
例如：
./libFM -task r -train ml1m-train.libfm -test ml1m-test.libfm -dim ['1, 1, 8'] -iter=100 --method=als --regular ['''\u{2795}''','''\u{2795}''',''''e-2''''] --init_stdev std::double(0.1)
3.3.3 Markov Chain Monte Carlo (MCMC)
基于-mcmc参数采用
The initialization of stdev refers to the normal distribution of standard deviation, which is used to initialize the parameters of V. A non-zero and positive value is required here.
请慎重选择这些参数，预测质量很大程度上取决于对很好的选择。
例如：
./bin/libFM -task recommendation -train ml1m-train.libfm -test ml1m-test.libfm -dim '[d,d,D]' [d=8] [-iter 25] --method MCMC --init_stdev 0.5
3.3.4 Adaptive SGD (SGDA)
借助sgda参数即可实现SGDA学习方法。
此时，在每组以及每一层中设定的正则化值都会被自动确定。
你需要去指定一个有效的集合去调优正则化值。
-validation:在交叉验证过程中由训练样本构成的数据集被用来作为验证集合以调优正则化值。此数据集需被区分与训练数据集以确保它们不重叠。
• -learn rate:学习速率的步长，需是一个非零且postive的值
-init stdev: The normal distribution based on the standard deviation is used to initialize the parameters of V. Here, a non-zero positive scalar value should be employed.
请 慎重 选择 这些 参数 ， 预测 质量 很大程度上 取决于 对 很好 的 选择。
例如：
./libFM -tasks rank -train ml1m-train.libfm -test ml1m-test.libfm
-dim ’3:3:8’
-iters 25
-algorithm stochastic gradient descent (SGD)
-learning_rate=lr(eta=2e-4)
-initialization standard deviation set to 0.2
-validation path to validation file is ml1m-val.libfm
4.块结构 (BS) 扩展
上图表示：
（a) LibFM 数据 文件 （= 的 设计 矩阵 X 表示形式 ） 可能 包含 大 块 重复 的 图案 。
（b） libFM 的 BS 扩展 支持 使用 更为 简洁 的 表示 方式 来 表达 数据 文件 ， 其中 那些 曾经 描述 过 的 重复 图案 ， 在 这种 情况 下 只 是 被 前面 的 方法 所 描述 。 （图改编自 [7]）
在相关背景之下，在设计矩阵中通常会包含大量重复的模式（见图1a）。这将导致设计矩阵极大程度上变得非常大，并从而使得学习速度减慢以及占用大量内存空间。
在 libFM 的 BS 扩展中引入了支持设计矩阵中块结构定义的机制。BS 数据类型替代传统数据类型的占用时间和存储空间呈线性变化。
来自相关数据的大的设计矩阵的具体细节详情见[7]
4.1数据格式
BS 扩展 允许 定义 块 （例如 B1 、 B2 、 B3 中 图 1） ， 在 libFM 中 使用 它们 。
每个 块 定义 包括 ︰
• 设计 矩阵 （libFM 文件） 的 块 (例如 XB1 在 图 1)。
• 从训练 （或 测试）case 映射 到 行 中 的 块 （例如 φ 例B1 在 图 1)。
• 设计 矩阵 中的可选分组 （比较 第 3.2.2 节 ） 。 对于 每个 块 ， 预计 以下 文件 ︰
4.2使用BS数据来启动LibFm
指定--relation参数用于传递终端命令行参数，在已设置两个块（rel.user和rel.item）的情况下，则直接采用。
./libFM -task r -train ml1m-train -test ml1m-test -dim ’1,1,8’ --relation rel.user,rel.item
Please note that each block mentioned must be included (i.e., the following blocks must be included: rel.user.x, rel.user.xt, rel.user.train, rel.user.test, (rel.user.groups), rel.item.x, etc., and similar blocks).
4.3在libFm中使用BS的注意事项
• BS 仅支持由 MCMC 和 ALS/CD。
偶然采用BS方法时, --train与--test参数仍然必须设置, 文件必须在此处指定. LibFM文件是通过--train与--test参数能够包含预测变量，并且也可能没有.
文件可以是二进制形式，可以是文本形式
• 在 BS 设计矩阵变量 id 的命名空间是不同的。
• 在BS文件中group的空间是不同的。
• 每一个组文件都有编号从零开始的组。
• overlaps are resolved in the same manner as with predictor ids.
• If no group files are passed, each block is automatically assumed to have a different group.
5.许可证
If you use libFM in your work, please cite the following paper:
@article{rendle:tist2012,
author ={Rendle Steffen},
title ={Factorization Machines integrated with libFM},
journal ={ACM Transactions on Intelligent Systems and Technology},
issue_date={May 201 },
volume ={3},
number ={3},
month ={May},
year ={ 二〇一二},
issn ={ 二一五七-六九零四},
pages ={[五七]:一--[五七]:二二},
articleno={五七},
numpages ={二二},
publisher ={ACM},
address ={New York,\ NY,\ USA}
}
References
Chih Chung Chang与Chih Jen Lin发表于《ACM Transactions on Intelligent Systems and Technology》，其中介绍了一种名为Libsvm的支持向量机工具箱。
[2] Christoph Freudenthaler, Lars Schmidt-Thieme, and Steffen Rendle. Bayesian factorization machines.In NIPS workshop on Sparse Representation and Low-rank Approximation, 2011.
[3] Thorsten Joachims. 实现大规模支持向量机学习的实用方法, 第169至184页. 出版社: 出版地: 出版年
[4] Steffen Rendle. Factorization-based models. In Proceedings of the 10th IEEE International Symposium on Data Mining. the IEEE Computer Society, 2010.
基于libFM的因子分解机模型
[6] Rendle Steffen. 基于推荐系统的自适应正则化学习. 在WSDM '12的第3届ACM国际会议记录上: 网络搜索与数据挖掘进展, 纽约, 美国, 2012年.ACM出版社.]
[7] Steffen Rendle. Scaling factorization machines over relational data. In the proceedings of the 39th international conference on Very Large Data Bases, PVLDB'13, pages 337–348. VLDB Endowment publisher, 2013.
[8] Sven Rendle, Zeno Gantner, Christoph Freudenthaler, and Lars Schmidt-Thieme. Efficient context-aware recommendation systems utilizing factorization machines. In Proceedings of the 34th ACM SIGIR symposium on Advances in Information Retrieval Research and Development. ACM, 2011.
学习推荐系统的具体实现与应用研究——以libFM算法为例