【Bug已解决】[TimesFM 2.5]： window_size argument raises AttributeError 解决方案

一、现象长什么样

TimesFM 2.5 是 Google 的时间序列基础模型，用于零样本预测。你按旧文档/示例传window_size参数做预测，结果报：

# 现象 A：forecast 不接受 window_size TypeError: forecast() got an unexpected keyword argument 'window_size' # TimesFM 2.5 的 forecast 签名改成用 context_len / horizon_len，不再认 window_size # 现象 B：内部引用了不存在的属性 AttributeError: 'TimesFMForForecasting' object has no attribute 'window_size' # 代码某处写了 self.window_size，但 2.5 版本没定义这个属性 # （被重命名为 self.context_len 之类） # 现象 C：传了 window_size 但被忽略，用了错误的默认窗口 # 预测长度/上下文切分用的是别的值，结果与预期不符 # 典型触发 from timesfm import TimesFM model = TimesFM.from_pretrained("google/timesfm-2.5") # 旧示例 out = model.forecast(series=my_series, window_size=64) # 报现象 A/B

最典型的指纹：旧版本（或社区示例）用window_size控制上下文窗口，升级到 2.5 后这个参数被改名/移除，于是传了就TypeError/AttributeError，不传就用错默认值。

二、背景

TimesFM 这类时间序列基础模型的预测流程是：把历史序列按"上下文窗口（context window）"切块，每块喂给模型预测未来horizon步。这个"窗口大小"在不同版本里的参数名经历了演变：

• 早期版本：用window_size表示上下文窗口长度。
• 2.5 版本：API 重构，改用语义更明确的context_len（上下文长度）和horizon_len（预测长度），window_size不再出现在forecast()签名里。

问题出在：用户（和一堆旧示例/教程）仍按window_size调用，而 2.5 的代码既没接受这个 kwarg，内部某些路径又残留了对self.window_size属性的引用（没随重构改名）→ 传参直接TypeError，或者在不传参但走某分支时AttributeError。这属于"API 改名但没做好向后兼容"的典型。

三、根因

根因有两类：

1. forecast()签名去掉了window_size，但调用方仍传。 TimesFM 2.5 的forecast(series, context_len, horizon_len)不含window_size。旧调用forecast(series, window_size=64)把window_size当 kwarg 传入，Python 报unexpected keyword argument。

2. 内部残留self.window_size属性引用。 重构时把属性从self.window_size改名为self.context_len，但某几条代码路径（如_maybe_pad_context、_split_into_windows）忘了改，仍写self.window_size→AttributeError: has no attribute 'window_size'。这类 bug 只在特定输入/分支触发，所以"有时报、有时不报"。

四、最小可运行复现

下面用纯 Python 模拟"forecast 签名去掉 window_size 但内部残留 self.window_size 引用"：

from typing import Optional class _TimesFM: def __init__(self, context_len: int = 32): self.context_len = context_len # 重构后改名 # 注意：没定义 self.window_size def forecast(self, series, context_len: Optional[int] = None, horizon_len: int = 16): # 新签名：只用 context_len ctx = context_len or self.context_len # 有 bug：某分支残留了对旧属性的引用 effective = getattr(self, "window_size", None) # 若有人写 self.window_size 会 AttributeError if effective is None: effective = ctx return f"forecast ctx={effective} horizon={horizon_len}" def _buggy_branch(self): # 模拟重构遗漏：直接引用已删除的属性 return self.window_size # AttributeError # 复现现象 A：传 window_size 给新签名 m = _TimesFM() try: m.forecast(series=[1,2,3], window_size=64) print("复现失败") except TypeError as e: print("复现成功(现象A):", e) # 复现现象 B：内部残留 self.window_size try: m._buggy_branch() print("复现失败") except AttributeError as e: print("复现成功(现象B):", e) # 修正：用 context_len print("修正:", m.forecast([1,2,3], context_len=64))

运行后，传window_size触发TypeError（现象 A），_buggy_branch触发AttributeError（现象 B），修正为用context_len后正常，复现并修复了两类的根因。

五、解决方案（第一层：最小直接修复）

最快的止血：调用时改用 2.5 的正确参数名context_len/horizon_len，并给模型补一个window_size兼容属性（若内部残留引用）：

from timesfm import TimesFM # 1) 调用改用新参数名 model = TimesFM.from_pretrained("google/timesfm-2.5") out = model.forecast( series=my_series, context_len=64, # 取代旧 window_size horizon_len=32, # 预测长度 ) # 2) 若模型内部残留 self.window_size 引用（现象 B）， # 在加载后补一个兼容属性（property）桥接 if not hasattr(model, "window_size"): # 用 property 把 window_size 映射到 context_len，避免 AttributeError type(model).window_size = property( lambda self: self.context_len, lambda self, v: setattr(self, "context_len", v), )

第一层让用户立刻消除TypeError/AttributeError，用正确的context_len跑预测。

六、解决方案（第二层：结构性改进）

用TimesFMParamAdapter把"旧参数名window_size→ 新参数名context_len"的兼容做进调用层，旧代码无需改：

from dataclasses import dataclass from typing import Optional @dataclass class TimesFMParamAdapter: """把旧 API 的 window_size 兼容映射到 TimesFM 2.5 的 context_len。""" default_context_len: int = 32 def normalize(self, kwargs: dict) -> dict: # 兼容：window_size -> context_len if "window_size" in kwargs: kwargs.setdefault("context_len", kwargs.pop("window_size")) # 确保 context_len 有值 kwargs.setdefault("context_len", self.default_context_len) return kwargs def ensure_attr(self, model): # 给模型补 window_size property，桥接到 context_len，消除内部 AttributeError if not hasattr(type(model), "window_size"): type(model).window_size = property( lambda self: self.context_len, lambda self, v: setattr(self, "context_len", v), ) return model # 使用：旧代码不动 adapter = TimesFMParamAdapter(default_context_len=64) adapter.ensure_attr(model) # 旧调用方式继续可用 out = model.forecast(series=my_series, window_size=64) # adapter 已桥接 # 实际上应在调用前归一化 kwargs： kwargs = adapter.normalize({"series": my_series, "window_size": 64}) out = model.forecast(**kwargs)

TimesFMParamAdapter的语义是：API 改名不应破坏旧调用，用适配层把window_size映射到context_len，并补属性桥接，旧代码零修改即可运行。

七、解决方案（第三层：断言 / CI 守护）

用 pytest 固化"forecast 接受 context_len、window_size 被兼容映射、内部不引用缺失属性"：

import pytest def test_window_size_maps_to_context_len(): from tfm_adapter import TimesFMParamAdapter a = TimesFMParamAdapter() kw = a.normalize({"series": [1,2,3], "window_size": 64}) assert "window_size" not in kw assert kw["context_len"] == 64 def test_ensure_attr_bridges_window_size(): from tfm_adapter import TimesFMParamAdapter class M: def __init__(self): self.context_len = 32 m = M() TimesFMParamAdapter().ensure_attr(m) # 像访问旧属性一样访问 window_size，应桥接到 context_len assert m.window_size == 32 m.window_size = 64 assert m.context_len == 64 def test_no_attribute_error_internally(): from tfm_adapter import TimesFMParamAdapter class M: def __init__(self): self.context_len = 32 def use_window(self): return self.window_size # 内部残留引用 m = M() TimesFMParamAdapter().ensure_attr(m) assert m.use_window() == 32 # 不再 AttributeError

CI 跑pytest tests/test_timesfm_window_size.py，以后只要有人又把window_size当 kwarg 直接传或内部残留引用，测试立刻红灯。

八、排查清单

当 TimesFM 2.5 报window_size相关错误，按顺序查：

1. unexpected keyword argument 'window_size'→ 2.5 改用了context_len，调用改用新名。
2. has no attribute 'window_size'→ 内部残留旧属性引用，用ensure_attr桥接context_len。
3. 预测长度/上下文不对 → 确认context_len/horizon_len传的是你想要的值，而非旧默认。
4. 旧代码不想改 → 用TimesFMParamAdapter把window_size兼容映射到context_len。
5. 长期方案：API 改名时保留兼容适配层（adapter/property 桥接），而非直接删参数。

九、小结

"[TimesFM 2.5]: window_size argument raises AttributeError" 的根因是：TimesFM 2.5 把上下文窗口参数从window_size改名为context_len/horizon_len，但调用方仍传旧名（TypeError），且内部某些分支残留对self.window_size的引用（AttributeError），属于"API 改名缺向后兼容"的典型。

• 第一层：调用改用context_len/horizon_len，并给模型补window_sizeproperty 桥接，立刻消除报错。
• 第二层：用TimesFMParamAdapter把window_size→context_len兼容映射 + 属性桥接做进调用层，旧代码零修改。
• 第三层：pytest 断言"window_size 被映射、属性桥接有效、内部不引用缺失属性"，防止回归。

记住：库的 API 改名时，保留一层向后兼容适配（参数重映射 + 旧属性 property 桥接）比直接删参数更友好；否则旧示例/旧代码会成片报 TypeError/AttributeError。