sports-betting

类别	工具
开发
打包
文档
沟通

简介

sports-betting 包 是一套用于创建、测试和使用体育博彩模型的实用工具。它配备了 Python API、CLI，甚至还内置了一个基于 Reflex 构建的 GUI，让操作更加简单：

sports-betting 的核心组件是数据加载器和投注器对象：

• 数据加载器负责下载并准备适合预测建模的数据。
• 投注器则提供了一种便捷的方式，用于回测投注策略并预测未来赛事中的价值投注。

快速入门

GUI

sports-betting 自带一个 GUI，为用户提供了直观的交互方式。它支持以下功能：

• 轻松上传、创建或更新数据加载器，以处理历史数据和赛程数据。
• 使用回测工具和价值投注识别功能，开发并测试投注模型。

要启动 GUI，只需运行命令 sportsbet-gui。启动后，您将看到初始界面：

您可以跟随内置机器人提供的指导信息，逐步探索各项功能。

API

sports-betting 包使下载体育博彩数据变得非常容易：

from sportsbet.datasets import SoccerDataLoader
dataloader = SoccerDataLoader(param_grid={'league': ['Italy'], 'year': [2020]})
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='market_maximum')
X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()

X_train 是历史/训练数据，而 X_fix 则是测试/赛程数据。利用历史数据，可以对投注器模型的性能进行回测：

from sportsbet.evaluation import ClassifierBettor, backtest
from sklearn.dummy import DummyClassifier
bettor = ClassifierBettor(DummyClassifier())
backtest(bettor, X_train, Y_train, O_train)

训练好的投注器模型还可以用来根据赛程数据预测价值投注：

bettor.fit(X_train, Y_train)
bettor.bet(X_fix, O_fix)

体育博彩的实际应用

我们可以把任何体育博彩事件看作一个随机实验，其中各个结果的概率都是未知的。即使是最不可能发生的事件，比如足球比赛中进超过 10 个球，也会被赋予一定的概率。庄家会估算这个概率 P，并据此给出相应的赔率 O。理论上，如果庄家长期提供所谓的公平赔率 O = 1 / P，那么无论是投注者还是庄家都不会获利。

然而，庄家的策略是通过提高总概率来调整赔率，使其对自己有利。在实践中，他们通常会提供低于公平赔率的赔率。关键在于，庄家仍然需要估算各种结果的概率，并设置能够确保其长期盈利的赔率。

另一方面，投注者也可以估算这些概率，并将其与庄家提供的赔率进行比较。如果某个结果的估算概率高于其对应赔率所隐含的概率，那么这种投注就被称作“价值投注”。

从长远来看，唯一有意义的投注策略就是选择价值投注。但需要注意的是，无论是投注者还是庄家，都无法获得结果的真实概率。因此，投注者所识别的价值投注本质上仍是一种估计。投注者或庄家都可能判断失误，甚至双方都可能出错。

另一个重要点是，庄家通常拥有普通投注者难以企及的资源，例如更丰富的数据、更强的计算能力以及专门从事预测建模的专家团队。你可能会认为试图击败庄家毫无意义，但事实并非如此。庄家在设定赔率时需要考虑多种因素，这也导致不同庄家提供的赔率存在较大差异。投注者应致力于系统性地评估价值投注、回测其表现，而不是盲目追求过于精确的预测模型。这实际上是一个切实可行的目标，而 sports-betting 正好提供了相应的工具来帮助实现这一目标。

安装

对于普通用户安装，sports-betting 当前已在 PyPI 仓库中发布，您可以通过 pip 进行安装：

pip install sports_betting

如果您使用的是 Node.js v22.0.0 或更高版本，还可以选择安装 GUI 界面：

pip install sports_betting[gui]

开发环境的安装需要先克隆仓库，然后使用 PDM 来安装项目及其主要依赖和开发依赖：

git clone https://github.com/georgedouzas/sports-betting.git
cd sports-betting
pdm install

使用

您可以使用 GUI 应用程序、Python API 或命令行界面来访问 sports-betting。不过，建议先熟悉 Python API，因为您将需要它来创建命令行配置文件或将自定义投注模型加载到 GUI 中。sports-betting 支持常见的体育博彩需求，例如获取历史数据和赛事信息，以及对投注策略进行回测和预测价值投注。

GUI

通过命令 sportsbet-gui 启动 GUI 应用程序。

以下是您可以在 GUI 中执行的一些操作：

• 配置数据加载器：

• 创建新的投注模型：

• 运行模型以获取回测结果或价值投注：

API

假设我们想要回测以下场景，并使用 bettor 对象来预测价值投注：

• 数据选择：
  • 2021 年至 2024 年德国、意大利和法国联赛的一级和二级联赛
  • 市场最高赔率，用于回测我们的投注策略
• 投注策略配置：
  • 5 折时间序列交叉验证
  • 初始资金 10000 欧元
  • 每次投注金额 50 欧元
  • 使用比赛赔率（主队胜、客队胜和平局）作为投注市场
  • 使用逻辑回归分类器来预测概率和价值投注

# 数据选择
from sportsbet.datasets import SoccerDataLoader

leagues = ['Germany', 'Italy', 'France']
divisions = [1, 2]
years = [2021, 2022, 2023, 2024]
odds_type = 'market_maximum'
dataloader = SoccerDataLoader({'league': leagues, 'year': years, 'division': divisions})
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type=odds_type)
X_fix, _, O_fix = dataloader.extract_fixtures_data()

# 投注策略配置
from sklearn.model_selection import TimeSeriesSplit
from sklearn.compose import make_column_transformer
from sklearn.linear_model import LogisticRegression
from sklearn.impute import SimpleImputer
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder
from sklearn.multioutput import MultiOutputClassifier
from sportsbet.evaluation import ClassifierBettor, backtest

tscv = TimeSeriesSplit(5)
init_cash = 10000.0
stake = 50.0
betting_markets = ['home_win__full_time_goals', 'draw__full_time_goals', 'away_win__full_time_goals']
classifier = make_pipeline(
  make_column_transformer(
    (OneHotEncoder(handle_unknown='ignore'), ['league', 'home_team', 'away_team']), remainder='passthrough'
  ),
  SimpleImputer(),
  MultiOutputClassifier(LogisticRegression(solver='liblinear', random_state=7, class_weight='balanced', C=50)),
)
bettor = ClassifierBettor(classifier, betting_markets=betting_markets, stake=stake, init_cash=init_cash)

# 执行回测并获取结果
backtesting_results = backtest(bettor, X_train, Y_train, O_train, cv=tscv)

# 获取即将到来的赛事的价值投注
bettor.fit(X_train, Y_train)
bettor.bet(X_fix, O_fix)

CLI

命令 sportsbet 提供了多种子命令，用于下载数据和预测价值投注。对于任何子命令，您可以添加 --help 标志以获取更多使用信息。

配置

要使用这些命令，需要一个配置文件。您可以在 sports-betting/configs/ 目录中找到此类配置文件的示例。配置文件应具有 .py 文件扩展名，并包含若干变量。其中 DATALOADER_CLASS 和 PARAM_GRID 是必填项，其余为可选项。

以下变量用于配置数据提取：

• DATALOADER_CLASS：要使用的数据加载器类。
• PARAM_GRID：用于选择数据包含的信息类型的参数网格。
• DROP_NA_THRES：数据加载器 extract_train_data 方法中的 drop_na_thres 参数。
• ODDS_TYPE：数据加载器 extract_train_data 方法中的 odds_type 参数。

以下变量用于配置投注过程：

• BETTOR：bettor 对象。
• CV：backtest 函数中的 cv 参数。
• N_JOBS：backtest 函数中的 n_jobs 参数。
• VERBOSE：backtest 函数中的 verbose 参数。

命令

在提供这些变量后，我们可以选择适当的命令来使用 sports-betting 的各项功能。

数据加载器

显示可用的数据加载器参数：

sportsbet dataloader params -c config.py

显示可用的赔率类型：

sportsbet dataloader odds-types -c config.py

提取训练数据并将其保存为 CSV 文件：

sportsbet dataloader training -c config.py -d /path/to/directory

提取赛事数据并将其保存为 CSV 文件：

sportsbet dataloader fixtures -c config.py -d /path/to/directory

贝特者

对 bettor 进行回测并将结果保存为 CSV 文件：

sportsbet bettor backtest -c config.py -d /path/to/directory

获取价值投注并将其保存为 CSV 文件：

sportsbet bettor bet -c config.py -d /path/to/directory

sports-betting 快速上手指南

sports-betting 是一个用于创建、测试和使用体育博彩模型的 Python 工具包。它提供了数据加载器（Dataloaders）来获取历史数据和赛程数据，以及投注者对象（Bettors）来回测策略和预测价值注单。该工具支持 Python API、命令行界面（CLI）以及基于 Reflex 构建的图形用户界面（GUI）。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.9 及以上
• 可选依赖（仅用于 GUI）：如果您计划使用图形界面，需要安装 Node.js v22.0.0 或更高版本。

安装步骤

1. 基础安装

通过 pip 安装核心功能包：

pip install sports_betting

提示：国内用户若下载缓慢，可使用清华源加速： pip install sports_betting -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装图形界面 (可选)

如果您已安装 Node.js v22.0.0+，可以安装包含 GUI 支持的版本：

pip install sports_betting[gui]

3. 开发环境安装 (可选)

如需贡献代码或进行开发，请使用 PDM 进行安装：

git clone https://github.com/georgedouzas/sports-betting.git
cd sports-betting
pdm install

基本使用

sports-betting 主要通过三个方式使用：GUI、Python API 和 CLI。推荐先熟悉 Python API，因为它是配置 CLI 和在 GUI 中加载自定义模型的基础。

方式一：使用图形界面 (GUI)

这是最直观的交互方式，适合快速上手和数据探索。

1. 启动应用： 在终端运行以下命令：

   sportsbet-gui
   

2. 主要功能：
   • 数据管理：上传、创建或更新数据加载器，处理历史数据和固定赛程数据。
   • 模型开发：构建并测试投注模型，执行回测以识别“价值注单”（Value Bets）。
   • 引导助手：内置机器人会提供操作指引。

方式二：使用 Python API

以下是两个最核心的使用场景示例。

场景 A：快速获取数据并简单回测

from sportsbet.datasets import SoccerDataLoader
from sportsbet.evaluation import ClassifierBettor, backtest
from sklearn.dummy import DummyClassifier

# 1. 初始化数据加载器 (例如意大利联赛 2020 年数据)
dataloader = SoccerDataLoader(param_grid={'league': ['Italy'], 'year': [2020]})

# 2. 提取训练数据 (历史数据) 和赛程数据 (待预测数据)
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='market_maximum')
X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()

# 3. 创建简单的投注者模型并进行回测
bettor = ClassifierBettor(DummyClassifier())
backtest(bettor, X_train, Y_train, O_train)

# 4. 训练模型并预测未来的价值注单
bettor.fit(X_train, Y_train)
value_bets = bettor.bet(X_fix, O_fix)

场景 B：配置完整的投注策略

此示例展示了如何配置特定的联赛、交叉验证策略以及逻辑回归分类器。

# 数据选择
from sportsbet.datasets import SoccerDataLoader

leagues = ['Germany', 'Italy', 'France']
divisions = [1, 2]
years = [2021, 2022, 2023, 2024]
odds_type = 'market_maximum'

dataloader = SoccerDataLoader({'league': leagues, 'year': years, 'division': divisions})
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type=odds_type)
X_fix, _, O_fix = dataloader.extract_fixtures_data()

# 策略配置
from sklearn.model_selection import TimeSeriesSplit
from sklearn.compose import make_column_transformer
from sklearn.linear_model import LogisticRegression
from sklearn.impute import SimpleImputer
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder
from sklearn.multioutput import MultiOutputClassifier
from sportsbet.evaluation import ClassifierBettor, backtest

# 设置时间序列交叉验证
tscv = TimeSeriesSplit(5)

# 构建机器学习管道
classifier = make_pipeline(
  make_column_transformer(
    (OneHotEncoder(handle_unknown='ignore'), ['league', 'home_team', 'away_team']), remainder='passthrough'
  ),
  SimpleImputer(),
  MultiOutputClassifier(LogisticRegression(solver='liblinear', random_state=7, class_weight='balanced', C=50)),
)

# 初始化投注者：设定初始资金、单笔注额及投注市场
bettor = ClassifierBettor(
    classifier, 
    betting_markets=['home_win__full_time_goals', 'draw__full_time_goals', 'away_win__full_time_goals'], 
    stake=50.0, 
    init_cash=10000.0
)

# 执行回测
backtesting_results = backtest(bettor, X_train, Y_train, O_train, cv=tscv)

# 获取未来赛事的价值注单
bettor.fit(X_train, Y_train)
bettor.bet(X_fix, O_fix)

方式三：使用命令行 (CLI)

CLI 适合自动化任务。使用前需创建一个 Python 配置文件（例如 config.py），定义 DATALOADER_CLASS 和 PARAM_GRID 等变量。

常用命令示例：

1. 查看可用参数：

   sportsbet dataloader params -c config.py
   

2. 查看可用赔率类型：

   sportsbet dataloader odds-types -c config.py
   

3. 提取训练数据并保存为 CSV：

   sportsbet dataloader training -c config.py -d /path/to/directory
   

4. 提取赛程数据并保存为 CSV：

   sportsbet dataloader fixtures -c config.py -d /path/to/directory
   

对于任何子命令，均可添加 --help 标志查看详细用法说明。