5分钟上手mtg-price-deep-gp:MTG卡牌价格预测模型从Hugging Face下载到首次推理
5分钟上手mtg-price-deep-gp:MTG卡牌价格预测模型从Hugging Face下载到首次推理
想给《万智牌》(MTG)卡牌做一个可靠的价格区间预测吗?mtg-price-deep-gp 是一个可直接在 Hugging Face 上下载的 MTG 卡牌价格预测模型,它基于深度核高斯过程(Deep Kernel GP)为每张卡牌的每一种印刷版本输出一个校准过的 80% 美元价格区间。本文是一份面向新手和用户的完整指南:从环境安装、模型下载,到构建特征并跑出第一次 price_low / price_mid / price_high,全程约 5 分钟。
这个MTG卡牌价格预测模型能做什么 🎯
它预测的不是"最可能的价格",而是"80% 概率会落在这个区间"——这在买卖估价时往往更实用:
- 输入:一张卡牌在某个系列 / 处理方式 / 面工艺下的全部可打印属性(稀有度、面工艺、画师、机制、法力费用、印刷年代、EDHREC 排名、开包率等),外加卡牌规则文本和卡图。
- 输出:
price_low、price_mid、price_high(USD),其中低 / 高就是校准后的 80% 区间,中间是后验均值。 - 适用场景:已发售卡牌估价,甚至尚未发售 / 假想卡牌的定价参考。
- 核心思路:用一个"宽而深"的特征抽取网络把表格属性、规则文本(
all-mpnet-base-v2)、卡图(CLIP ViT-B-32)融合成 48 维联合嵌入,再交给一个 750 诱导点的稀疏变分高斯过程(SVGP)对log(price_avg)建模,最后按预测价格分桶做 split-conformal 校准。
官方测试集表现(14,639 个未见过卡牌的印刷版本)
| 真实价格区间 | 样本数 | 对数价格 MAE | 校准 80% 覆盖率 |
|---|---|---|---|
| < $1 | 8,816 | 0.39 | 84.7% |
| $1–$10 | 3,939 | 0.73 | 73.7% |
| $10–$100 | 1,702 | 0.81 | 75.9% |
| $100+ | 182 | 0.99 | 71.4% |
| 总体 | 14,639 | 0.54 | 80.5% |
详细指标可查 config.json 中的
test_metrics字段。
仓库文件清单:每个文件负责什么
下载下来后,仓库结构和职责一目了然:
| 文件 | 作用 |
|---|---|
| model.safetensors | 特征抽取器 + GP + 似函数的权重 |
| config.json | 架构、训练配置、分桶校准修正量、测试指标 |
| preprocessor.json | 分类词表、宽列顺序、中位数填补、标准化统计量 |
| pull_rate_defaults.parquet | (稀有度, 面工艺) → 默认开包率,用于假想卡牌 |
| set_prices.parquet | (系列, 卡牌) → 训练卡牌最高对数价,用于"系列价格水平"输入 |
| mtg_price_prediction/ | 推理代码:模型类、预处理、特征构建、校准 |
推理代码由四个模块组成:
- 模型加载与预测入口:mtg_price_prediction/deep_gp.py
- 从原始数据集行构建特征表:mtg_price_prediction/gp_features.py
- 分桶 conformal 校准:mtg_price_prediction/calibration.py
- 包初始化:mtg_price_prediction/init.py
5分钟跑通首次推理:环境 → 下载 → 预测
第 1 步:安装依赖
一条命令装齐全部依赖(torch、gpytorch、safetensors、huggingface_hub、pandas、pyarrow):
pip install torch gpytorch safetensors huggingface_hub pandas pyarrow
第 2 步:从 Hugging Face 下载模型
用 snapshot_download 把整个仓库拉到本地缓存,仓库本身自带推理代码,直接加入 sys.path 即可:
import sys
from huggingface_hub import snapshot_download
path = snapshot_download("CXu0630/mtg-price-deep-gp")
sys.path.insert(0, path) # 仓库自带 mtg_price_prediction/ 推理代码
from mtg_price_prediction.deep_gp import DeepGPPredictor
model = DeepGPPredictor.from_pretrained(path)
from_pretrained 会自动读取 config.json 和 preprocessor.json 重建网络结构,再从 model.safetensors 加载权重(见 deep_gp.py#L277-L301)。
第 3 步:构建特征并预测
预测需要三样输入:宽表特征 features_df、文本嵌入 text_emb(形状 (n, 768))、卡图嵌入 image_emb(形状 (n, 512))。拿到 CXu0630/mtg-card-market-dataset 里的行数据后,用 gp_feature_frame 一步构建特征表(见 gp_features.py#L112):
from mtg_price_prediction.gp_features import gp_feature_frame
features_df = gp_feature_frame(rows, model.prep["wide_cols"], model.feature_context(dataset))
ranges = model.predict(features_df, text_emb, image_emb)
# -> price_low / price_mid / price_high (USD)
其中:
model.feature_context(dataset)自动提供 set_prices.parquet 和config.json中的as_of日期(用于"系列价格水平"与卡龄特征);- 缺失数值会自动按训练集中位数填补,未见过的分类值映射到
__unk__; - 还没有真实开包率的假想卡牌,用 pull_rate_defaults.parquet 按 (稀有度, 面工艺) 查默认值补上
*_rate_percent。
一次 predict 调用(deep_gp.py#L303)即返回带索引的三列结果,可直接落表或接入你的工具链。
80%价格区间是如何校准出来的 🔧
原始模型输出的是 mean ± 1.2816·std 区间。但不同价格段的"平均偏宽"并不一样,所以本项目做了按预测价格分桶的 split-conformal 校准(calibration.py):
- 按预测中位价把每张卡分到 4 个桶:
<$1、$1–$10、$10–$100、$100+; - 在每个桶上,用独立校准集拟合一个"加性修正量",专门修正区间两侧;
- 推理时按预测所在桶应用对应修正量。
修正量已随模型发布在 config.json 的 calibration_corrections 中:
| 桶 | 修正量 |
|---|---|
<$1 |
−0.0634 |
$1–$10 |
+0.5123 |
$10–$100 |
+0.4113 |
$100+ |
+0.5672 |
正因为这个校准步骤,$1–$100 段的区间被系统性加宽——这也是为什么总体覆盖率能稳定在 80% 附近,而单看 GP 本身的输出会偏窄。
上手前必须知道的局限 ⚠️
作为负责任的实践者,使用模型前请理解以下边界(详见 README.md):
- $100+ 覆盖偏低:校准后仅 71.4%(目标 80%),且该区间样本少(182 个)。组合 / 禁牌 / 收藏价值驱动的价格对当前特征基本不可见。
- 假想卡牌缺少"系列价格"输入:如果所属系列没有已标价训练卡,会触发
set_price_missing并使用填补值。 - GP 不确定性在卡与卡之间几乎是常数:这是深度核学习的已知坍缩现象,区间宽度只按预测价格桶变化,而不是按单卡。
- 模型会随市场漂移:训练数据是 TCGplayer 大约 3 个月(截至 2026 年 9 月)的价格窗口,预测的是绝对对数价,市场波动后需重新校准或重训。
- 不在范围内:多面卡牌(transform / MDFC / split / adventure…)、纯数字版、超大卡。
结语
mtg-price-deep-gp 用"深度特征抽取 + 稀疏变分高斯过程 + 分桶 conformal 校准"的三步组合,为 MTG 卡牌给出了一个可以直接用于估价和买卖决策的 80% 价格区间。从 Hugging Face 下载、pip install 装依赖、from_pretrained 加载、predict 预测,一条链路 5 分钟即可跑通首次推理。接下来,你可以基于它构建自己的卡牌估值工具、二级市场监控或假想卡牌定价器——记住把"价格区间"当作区间来看,而不是单点估计。