River 是一个用于 在线机器学习 的 Python 库。它的目标是成为处理流式数据时最易用的机器学习库。River 是 creme 和 scikit-multiflow 合并后的产物。

⚡️ 快速入门

作为一个简单的示例，我们将训练一个逻辑回归模型来分类 网站钓鱼数据集。以下是该数据集中第一条记录的内容。

>>> from pprint import pprint
>>> from river import datasets

>>> dataset = datasets.Phishing()

>>> for x, y in dataset:
...     pprint(x)
...     print(y)
...     break
{'age_of_domain': 1,
 'anchor_from_other_domain': 0.0,
 'empty_server_form_handler': 0.0,
 'https': 0.0,
 'ip_in_url': 1,
 'is_popular': 0.5,
 'long_url': 1.0,
 'popup_window': 0.0,
 'request_from_other_domain': 0.0}
True

现在让我们以流式方式在数据集上运行模型。我们交替进行预测和模型更新，同时更新性能指标以观察模型的表现。

>>> from river import compose
>>> from river import linear_model
>>> from river import metrics
>>> from river import preprocessing

>>> model = compose.Pipeline(
...     preprocessing.StandardScaler(),
...     linear_model.LogisticRegression()
... )

>>> metric = metrics.Accuracy()

>>> for x, y in dataset:
...     y_pred = model.predict_one(x)      # 进行预测
...     metric.update(y, y_pred)           # 更新指标
...     model.learn_one(x, y)              # 更新模型

>>> metric
Accuracy: 89.28%

当然，这只是一个示例。欢迎查看文档中的 简介 部分，以获取更详细的教程。

🛠 安装

River 旨在与 Python 3.10 及以上版本 兼容。可以通过 pip 进行安装：

pip install river

Linux、MacOS 和 Windows 平台都有 预编译的二进制包 可用，因此你很可能无需从源码构建 River。

你也可以从 GitHub 安装最新的开发版本：

pip install git+https://github.com/online-ml/river --upgrade
pip install git+ssh://git@github.com/online-ml/river.git --upgrade  # 使用 SSH

这种方法需要你的机器上已安装 Cython 和 Rust。

🔮 功能

River 提供以下算法族的在线实现：

• 线性模型，配备多种优化器
• 决策树和随机森林
• （近似）最近邻
• 异常检测
• 概念漂移检测
• 推荐系统
• 时间序列预测
• 多臂老虎机
• 因子分解机
• 不平衡学习
• 聚类
• 装袋/提升/堆叠
• 主动学习

此外，River 还提供其他在线工具：

• 特征提取和选择
• 在线统计与度量
• 数据预处理
• 内置数据集
• 渐进式模型验证
• 模型流水线

请参阅 API 文档 获取全面概述。

🤔 我应该使用 River 吗？

你需要问自己是否需要在线机器学习。答案很可能是否定的。大多数情况下，批量学习已经足够。如果你遇到以下情况，可能更适合使用在线方法：

• 你希望模型能够从新数据中学习，而无需重新处理历史数据。
• 你希望模型对 概念漂移 具有鲁棒性。
• 你想以更接近生产环境的方式开发模型，而生产环境通常是基于事件驱动的。

River 的一些特点包括：

• 它更注重清晰性和用户体验，而非性能。
• 它处理单个样本的速度非常快。你可以亲自试一试。
• 它能很好地与 Python 生态系统中的其他工具协同工作。

🔗 有用链接

• 文档
• 软件包发布记录
• awesome-online-machine-learning
• 2022 年 GAIA 大会上的演讲
• 在线聚类：算法、评估、度量、应用及基准测试，发表于 KDD'22。

👐 贡献

欢迎以任何方式参与贡献，我们始终欢迎新的想法和方法。

• 如果有任何问题或咨询，请开启讨论。公开提问比发送私人邮件更有帮助。也鼓励在贡献之前先发起讨论，以便大家达成一致，避免重复劳动。
• 如果你认为发现了 bug 或性能问题，请随时提交 issue。
• 我们的 路线图 是公开的。你可以自由选择感兴趣的任务进行开发，或者提出建议。

如果你想对代码库进行修改，请务必阅读 贡献指南。

🤝 合作伙伴

💬 引用

如果 River 对您有所帮助，并且您希望在科学出版物中引用它，请参考发表在 JMLR 上的论文：

@article{montiel2021river,
  title={River: machine learning for streaming data in Python},
  author={Montiel, Jacob and Halford, Max and Mastelini, Saulo Martiello
          and Bolmier, Geoffrey and Sourty, Raphael and Vaysse, Robin and Zouitine, Adil
          and Gomes, Heitor Murilo and Read, Jesse and Abdessalem, Talel and others},
  year={2021}
}

📝 许可证

River 是一款免费的开源软件，采用 3 条款 BSD 许可证授权。

River 快速上手指南

River 是一个专注于在线机器学习（Online Machine Learning）的 Python 库，旨在为流式数据提供最友好的机器学习体验。它由 creme 和 scikit-multiflow 合并而来，支持单样本逐条学习与预测。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Python 版本：3.10 及以上
• 前置依赖：
  • 标准安装无需额外依赖（官方提供预编译 Wheel 包）
  • 若从源码安装开发版，需预先安装 Cython 和 Rust

安装步骤

方式一：通过 PyPI 安装（推荐）

使用 pip 直接安装稳定版：

pip install river

💡 国内用户可指定清华或阿里镜像加速安装：

pip install river -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：安装最新开发版（可选）

如需体验最新功能，可从 GitHub 安装（需安装 Cython 和 Rust）：

pip install git+https://github.com/online-ml/river --upgrade

或使用 SSH 方式：

pip install git+ssh://git@github.com/online-ml/river.git --upgrade

基本使用

以下示例演示如何使用 River 对流式数据进行在线分类：加载钓鱼网站数据集，构建一个包含标准化预处理和逻辑回归的管道，并逐条更新模型与评估准确率。

from river import compose, linear_model, metrics, preprocessing, datasets

# 加载内置数据集
dataset = datasets.Phishing()

# 构建模型管道：标准化 + 逻辑回归
model = compose.Pipeline(
    preprocessing.StandardScaler(),
    linear_model.LogisticRegression()
)

# 初始化评估指标
metric = metrics.Accuracy()

# 流式训练：逐条预测 → 更新指标 → 学习样本
for x, y in dataset:
    y_pred = model.predict_one(x)      # 预测
    metric.update(y, y_pred)           # 更新指标
    model.learn_one(x, y)              # 在线学习

# 输出最终准确率
print(metric)
# 输出示例：Accuracy: 89.28%

该模式适用于所有支持 predict_one 和 learn_one 接口的 River 模型，是实现在线学习的核心范式。