5分钟上手mtg-price-deep-gp:MTG卡牌价格预测模型从Hugging Face下载到首次推理

原创2026-10-18 13:00:061,421 阅读

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/ 推理代码:模型类、预处理、特征构建、校准

推理代码由四个模块组成:

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):

  1. 按预测中位价把每张卡分到 4 个桶:<$1、$1–$10、$10–$100、$100+;
  2. 在每个桶上,用独立校准集拟合一个"加性修正量",专门修正区间两侧;
  3. 推理时按预测所在桶应用对应修正量。

修正量已随模型发布在 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 分钟即可跑通首次推理。接下来,你可以基于它构建自己的卡牌估值工具、二级市场监控或假想卡牌定价器——记住把"价格区间"当作区间来看,而不是单点估计。

登录后查看全文
mtg-price-deep-gp