TimesFM 本地测试完整指南

chenjiajia6

327人浏览 · 2026-06-09 09:48:43

chenjiajia6 · 2026-06-09 09:48:43 发布

适用场景：Windows 用户在 Conda 虚拟环境中从零开始部署 Google 最新时间序列大模型 TimesFM 2.5 (200M)，并完成本地推理验证。
特别说明：本文已整合 国内网络访问 Hugging Face 失败 的解决方案。

📌 前提条件

操作系统：Windows 10 / 11（64位）
已安装 Miniconda 或 Anaconda
网络环境：中国大陆（可能无法直连 Hugging Face）
目标 Python 版本：3.11.x（TimesFM 官方仅支持 ≤3.11）

Step 1：激活 Conda 环境

打开 PowerShell，执行：

conda activate py0311
python --version   # 确认输出 Python 3.11.x

✅ 正确输出示例：Python 3.11.9

⚠️ 如果提示 conda: command not found，请先初始化 Conda：
conda init powershell
# 重启 PowerShell 后重试

Step 2：修复 pip 并安装依赖

🔧 2.1 修复 pip（关键！避免 `pip-script.py` 缺失错误）

由于 Conda 环境中 pip 可能损坏，请使用以下方式确保 pip 可用：

python -m ensurepip --upgrade
python -m pip install --upgrade pip

✅ 验证：python -m pip --version 应正常输出版本号。

📦 2.2 安装 TimesFM 及必要依赖

# 安装核心包（含 PyTorch 支持）
python -m pip install timesfm[torch]

# 安装辅助工具（可视化、Hugging Face 下载、安全张量）
python -m pip install matplotlib huggingface_hub safetensors

# （可选）如需协变量预测功能
python -m pip install timesfm[xreg]

💡 GPU 用户加速建议（如有 NVIDIA 显卡）：
python -m pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121
CPU 模式也能运行，但速度慢 5–20 倍。

Step 3：配置 Hugging Face 镜像（解决国内下载失败）

❗ 问题背景

当你运行测试脚本时，可能出现如下错误：

[WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。

这是因为 Hugging Face 官方服务器（huggingface.co）在国内访问受限，导致无法自动下载模型权重。

✅ 解决方案：使用国内镜像站

在 每次启动 PowerShell 并激活环境后，务必设置镜像地址：

conda activate py0311
$env:HF_ENDPOINT = "https://hf-mirror.com"

🔁 说明：

hf-mirror.com 是由社区维护的 官方同步镜像，支持所有 from_pretrained() 调用。

该设置仅对当前 PowerShell 会话有效，关闭窗口后需重新设置。

首次下载模型约 800MB，后续自动缓存至 ~/.cache/huggingface/。

🌐 替代镜像（如 hf-mirror 不可用）：
$env:HF_ENDPOINT = "https://hf-mirrors.com"

Step 4：运行系统预检（必做）

进入项目目录并执行预检脚本：

cd D:\model\timesfm\timesfm-forecasting
python scripts\check_system.py

该脚本将检查：

Python 版本是否合规（≥3.10, <3.12）
是否有足够 RAM（建议 ≥8GB）
磁盘空间是否充足（模型缓存需 ~1GB）
GPU 是否可用（如有）

✅ 若全部通过，继续下一步；若失败，请根据提示调整环境。

Step 5：最小化验证 — 快速测试模型加载与推理

📄 创建测试文件 `test_timesfm.py`

在项目根目录（D:\model\timesfm\timesfm-forecasting）下创建 test_timesfm.py，内容如下：

import torch
import numpy as np

# 启用高效矩阵乘法（提升 Torch 推理速度）
torch.set_float32_matmul_precision("high")

# 加载 TimesFM 2.5 (200M) 模型
# 首次运行将自动从 HuggingFace（经镜像）下载权重 (~800MB)
import timesfm

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)

# 编译模型（必须！ForecastConfig 控制推理行为）
model.compile(timesfm.ForecastConfig(
    max_context=512,              # CPU模式建议512，GPU可设1024+
    max_horizon=128,
    per_core_batch_size=4,        # CPU模式建议4-8，GPU可设64+
    normalize_inputs=True,
    use_continuous_quantile_head=True,
    force_flip_invariance=True,
    infer_is_positive=False,      # 根据数据调整（正弦波可为负）
    fix_quantile_crossing=True,
))

# 生成测试数据：正弦波序列（长度200）
test_input = [np.sin(np.linspace(0, 20, 200)).astype(np.float32)]

# 运行预测：预测未来 24 步
point_forecast, quantile_forecast = model.forecast(
    horizon=24,
    inputs=test_input,
)

print(f"✅ Point forecast shape:   {point_forecast.shape}")    # 预期: (1, 24)
print(f"✅ Quantile forecast shape: {quantile_forecast.shape}") # 预期: (1, 24, 10)
print(f"✅ Forecast values (前6步): {point_forecast[0][:6]}")
print(f"✅ No NaN in output:        {not np.isnan(point_forecast).any()}")
print("\n🎉 TimesFM 本地测试成功！")

▶️ 运行测试

确保已设置镜像并激活环境：

conda activate py0311
$env:HF_ENDPOINT = "https://hf-mirror.com"
python test_timesfm.py

⏳ 首次运行耗时较长（5–15 分钟），因需下载模型权重。

✅ 预期成功输出

✅ Point forecast shape:   (1, 24)
✅ Quantile forecast shape: (1, 24, 10)
✅ Forecast values (前6步): [-0.756  -0.721  -0.682  -0.639  -0.593  -0.544]
✅ No NaN in output:        True

🎉 TimesFM 本地测试成功！

🎯 成功标志：

输出形状符合预期

无 NaN 值

无网络超时或模块导入错误

🛠️ 常见问题排查

问题	解决方案
`ModuleNotFoundError: No module named 'timesfm'`	确保使用 `python -m pip install` 安装，而非 `conda`
`WinError 10060` 仍出现	检查 `$env:HF_ENDPOINT` 是否在同一会话中设置；尝试浏览器访问 `https://hf-mirror.com/google/timesfm-2.5-200m-pytorch` 看是否可打开
内存不足（OOM）	降低 `max_context` 和 `per_core_batch_size`
模型加载极慢	首次下载需耐心；后续运行将从缓存加载（秒级）
输出全为 NaN	检查输入数据是否为 `float32`；尝试关闭 `normalize_inputs`

📚 补充说明

TimesFM 2.5 是真实存在的：由 Google Research 于 2025 年底发布，支持 16K 上下文、原生概率预测。
为什么不用 Python 3.12？
TimesFM 依赖 jaxlib，而 JAX 官方截至 2026 年中仍未支持 Python 3.12，强行使用会导致构建失败。
生产部署建议：
将模型手动下载到本地目录，通过 from_pretrained("本地路径") 加载，避免运行时依赖网络。