TimesFM: dự báo chuỗi thời gian không cần huấn luyện — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về google-research/timesfm — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: TimesFM: dự báo chuỗi thời gian không cần huấn luyện lại — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
TimesFM là mô hình AI đã huấn luyện sẵn của Google Research, dùng để dự báo chuỗi thời gian như doanh số theo ngày hay lượng truy cập theo giờ. Bạn cài bằng pip, nạp checkpoint từ Hugging Face rồi đưa dãy số vào để nhận dự báo kèm khoảng bất định. Cài không khó, nhưng trọng số bản 3.0 chỉ được dùng phi thương mại.
TimesFM là một mô hình AI đã được Google Research huấn luyện sẵn để dự báo chuỗi thời gian. Chuỗi thời gian là bất cứ dãy số nào gắn với thời điểm: doanh thu mỗi ngày, số đơn mỗi giờ, lượng truy cập website mỗi tuần, nhiệt độ cảm biến mỗi phút. Bạn đưa lịch sử vào, mô hình trả về phần dự báo cho các bước tiếp theo.
Repo này hợp với ba nhóm người. Nhóm đầu là chủ shop hoặc nhân viên văn phòng muốn có con số dự báo mà không phải học thống kê. Nhóm thứ hai là lập trình viên mới cần một cách dự báo nhanh, không phải tự dựng và tinh chỉnh mô hình cho từng bài toán. Nhóm thứ ba là người làm dữ liệu muốn thử một mô hình nền tảng đang đứng đầu nhiều bảng xếp hạng. Hiện repo có khoảng 35.452 sao và 3.471 fork, giấy phép mã nguồn là Apache-2.0.
Điểm đáng giá nhất là mô hình "zero-shot": bạn không phải huấn luyện lại cho từng bộ dữ liệu. Bản mới nhất (3.0) còn dự báo được nhiều chuỗi cùng lúc và nhận thêm các biến phụ như giá khuyến mãi hay ngày lễ. Có một điều bạn cần biết ngay từ đầu: trọng số bản 3.0 có giấy phép riêng, chỉ dùng cho mục đích phi thương mại. Mình sẽ nói rõ hơn ở phần cuối.
google-research/timesfm
TimesFM là mô hình nền tảng của Google Research, dự báo chuỗi thời gian (doanh số, lượng truy cập, cảm biến…) ngay trên dữ liệu của bạn mà không cần tự huấn luyện.
I.TimesFM làm được gì
Dự báo một chuỗi hoặc nhiều chuỗi có độ dài khác nhau. Bạn có thể đưa vào cùng lúc nhiều dãy số, mỗi dãy một độ dài. Ví dụ shop có sản phẩm mới bán được 72 ngày và sản phẩm cũ bán được 100 ngày. Bạn không cần cắt hay đệm cho bằng nhau.
Cho ra dự báo điểm cùng 9 mức phân vị. Ngoài con số dự báo chính, mô hình trả thêm các phân vị từ 0,1 đến 0,9. Nhờ vậy bạn thấy được khoảng dao động: "khả năng cao bán 100 đến 140 cái", thay vì một con số trơ trọi. Việc đặt hàng nhập kho nên dựa vào khoảng này.
Dự báo đa biến (bản 3.0). Bạn đưa vào mảng có dạng (số biến, độ dài ngữ cảnh), ví dụ doanh số của 3 cửa hàng. Mô hình dự báo chung cho cả 3 biến trong một lần chạy.
Hỗ trợ covariate (biến phụ). Có hai loại. Loại "chỉ có trong quá khứ" như lượng mưa đã đo. Loại "có cả quá khứ lẫn tương lai" như lịch khuyến mãi đã lên kế hoạch hay ngày lễ. Theo README, bản 3.0 xử lý được cả hai mà không phải tinh chỉnh riêng cho từng bài toán.
Chạy bằng PyTorch hoặc MLX. Nếu dùng máy Mac chip Apple silicon, bạn có thể chạy bằng MLX mà không cần cài PyTorch. README cho biết bản MLX có giao diện giống bản PyTorch và kết quả khớp rất sát.
Có sẵn skill cho AI agent và ví dụ tinh chỉnh. Trong repo có thư mục timesfm-forecasting/ chứa tệp SKILL.md để agent gọi TimesFM, và một ví dụ tinh chỉnh bằng LoRA với HuggingFace Transformers + PEFT. Ngoài ra còn tệp AGENTS.md ở thư mục gốc.
Các phiên bản cũ vẫn dùng được. Mã cho bản 2.5 nằm trong src/timesfm. Bản 1.0 và 2.0 nằm trong thư mục v1, và bạn cài được bằng pip install timesfm==1.3.0.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Python từ 3.10 trở lên. Đây là yêu cầu trong
pyproject.toml. - pip để cài từ PyPI. Nếu muốn cài từ mã nguồn theo README thì cần thêm git và uv.
- Đường truyền Internet để tải checkpoint
google/timesfm-3.0-pytorchtừ Hugging Face khi chạy lần đầu. README dùng tên checkpoint này nhưng không nói rõ chuyện tải về, đây là cách Hugging Face thường hoạt động. - Máy Mac chip Apple silicon nếu bạn chọn nhánh MLX. Nhánh PyTorch thì README không nêu hệ điều hành cụ thể.
Về phần cứng, các ví dụ PyTorch trong README đều đặt device="cuda", tức là chạy trên GPU NVIDIA. README không nói máy chỉ có CPU thì chạy được hay không, và cũng không nói cần bao nhiêu RAM hay VRAM. Mình chưa có thông tin này, bạn nên thử trên máy mình trước khi tính chuyện dùng thật. README không nhắc tới API key hay tài khoản nào cho phần chạy cục bộ.
Trọng số TimesFM 3.0 dùng giấy phép riêng (timesfm-non-commercial-license-v1.0): chỉ cho mục đích phi thương mại, không dùng cho sản xuất. Mã nguồn thì vẫn là Apache-2.0. Nếu bạn định dùng kết quả cho việc kinh doanh thật, hãy đọc kỹ phần giấy phép ở cuối bài trước khi làm tiếp.
III.Cài đặt từng bước
- Mở terminalMở PowerShell, Terminal hoặc Command Prompt và kiểm tra Python từ 3.10 trở lên
- Cài góiChạy pip install timesfm[torch] (hoặc timesfm[mlx] trên Mac Apple silicon)
- Hoặc cài từ mã nguồnClone repo, tạo môi trường ảo bằng uv rồi cài ở chế độ editable
- Chép ví dụDán đoạn Python dự báo đơn biến trong README vào một tệp .py
- Chạy và xem kết quảKiểm tra kích thước mảng forecast và quantiles in ra
A.Mở terminal và kiểm tra Python
Trên Windows, bạn mở PowerShell (gõ "PowerShell" vào ô tìm kiếm của Start). Trên Mac hoặc Linux, bạn mở Terminal. Rồi kiểm tra phiên bản Python. Cần từ 3.10 trở lên:
python --versionNếu máy báo không tìm thấy lệnh python, bạn thử python3 --version. Nếu phiên bản thấp hơn 3.10, bạn cần cài Python mới trước. README không hướng dẫn việc này.
B.Cách A: cài từ PyPI (nhanh nhất)
Đây là cách README ghi cho người chỉ cần dùng. Bản có PyTorch:
# Install TimesFM with PyTorch
pip install timesfm[torch]Nếu bạn dùng Mac chip Apple silicon và muốn chạy bằng MLX, không cần PyTorch:
# Or, for MLX-native inference on Apple silicon (no PyTorch required)
pip install timesfm[mlx]Chỗ người mới hay vấp: nếu terminal của bạn là zsh (mặc định trên Mac), dấu ngoặc vuông có thể bị hiểu sai và báo lỗi. Khi đó hãy đặt cả tên gói trong dấu nháy, ví dụ pip install "timesfm[torch]". Ngoài ra, PyTorch khá nặng, nên bước cài có thể mất vài phút.
C.Cách B: cài từ mã nguồn
Cách này hợp nếu bạn muốn đọc mã, chạy thử các thư mục ví dụ hoặc chỉnh sửa. Trước hết tải repo về:
git clone https://github.com/google-research/timesfm.git
cd timesfmLệnh git clone tải toàn bộ mã về một thư mục tên timesfm. Lệnh cd timesfm đưa terminal vào thư mục đó. Mọi lệnh sau phải chạy ở trong thư mục này.
Tiếp theo, tạo môi trường ảo và cài gói. README dùng công cụ uv:
# Using uv
uv venv
source .venv/bin/activate
# Install the package in editable mode with torch
uv pip install -e .[torch]uv venv tạo môi trường ảo trong thư mục .venv. Dòng source .venv/bin/activate là lệnh kích hoạt trên Mac và Linux. Trên Windows PowerShell, đường dẫn kích hoạt thường là .venv\Scripts\Activate.ps1. README không ghi riêng cho Windows, nên nếu lệnh trên báo lỗi, bạn dùng đường dẫn này. Lệnh cuối cài gói ở chế độ "editable", nghĩa là sửa mã trong thư mục thì gói cũng đổi theo. Bạn cần cài uv trước nếu máy chưa có. README không hướng dẫn cài uv.
D.Chép ví dụ và chạy
Tạo một tệp tên du_bao.py (đặt ở thư mục khác thư mục repo cho gọn) rồi dán đoạn mã dự báo đơn biến từ README vào:
import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig
# Initialize TimesFM 3.0
config = ModelConfig(
checkpoint_path="google/timesfm-3.0-pytorch",
per_core_batch_size=32,
device="cuda"
)
forecaster = TimesFM3Evaluator(config)
# Two univariate series of different lengths (100 and 72 steps)
ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)
# Generate forecast (point predictions + 9 quantiles: 0.1 to 0.9)
outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))
print("Series 1 forecast shape:", outputs[0].forecast.shape) # (12,)
print("Series 1 quantiles shape:", outputs[0].quantiles.shape) # (12, 9)
print("Series 2 forecast shape:", outputs[1].forecast.shape) # (12,)
print("Series 2 quantiles shape:", outputs[1].quantiles.shape) # (12, 9)Sau đó chạy:
python du_bao.pyCó hai điểm cần để ý. Thứ nhất, các ví dụ của bản 3.0 trong README nhập từ module timesfm3, trong khi tên gói ở phần cài là timesfm. README không giải thích khác biệt này. Nếu Python báo không tìm thấy timesfm3, bạn xem thư mục timesfm3-usage/ và thư mục src/ trong repo để biết cách nhập đúng với phiên bản bạn đã cài. Thứ hai, ví dụ đặt device="cuda". Nếu máy bạn không có GPU NVIDIA, README chưa nói giá trị nào thay thế được, nên bạn cũng tra thêm trong timesfm3-usage/.
Với máy Mac Apple silicon, README có đường nhập riêng cho MLX:
import numpy as np
from timesfm3.mlx import TimesFM3Forecaster
forecaster = TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch")IV.Kiểm tra đã chạy được chưa
Với ví dụ đơn biến ở trên, bạn thành công khi chương trình chạy hết, không báo lỗi và in ra bốn dòng kích thước. Kết quả mong đợi theo chú thích trong README:
Series 1 forecast shapelà(12,), tức 12 bước dự báo.Series 1 quantiles shapelà(12, 9), tức 12 bước nhân 9 mức phân vị.- Chuỗi thứ hai cho kết quả tương tự.
Cả hai chuỗi cùng cho ra 12 bước dù độ dài đầu vào khác nhau (100 và 72). Đó chính là điều bạn cần thấy. Lần chạy đầu thường lâu hơn vì phải tải checkpoint. Nếu bạn chạy nhánh MLX với ngữ cảnh 512 điểm và horizon 128, README nói forecast có dạng (128,) và quantiles có dạng (128, 9).
V.Dùng vào việc thật
Mấy tình huống dưới đây bám đúng những gì README có. Mình dùng số liệu giả làm ví dụ, còn bạn thay bằng dữ liệu thật của mình.
A.Chủ shop dự báo số đơn của nhiều sản phẩm
Bạn bán online, có nhiều sản phẩm với lịch sử bán dài ngắn khác nhau. Bạn xuất số đơn theo ngày của từng sản phẩm thành các mảng NumPy, rồi đưa chung vào predict_batch. Cách làm giống ví dụ đơn biến ở trên, chỉ thay ts1, ts2 bằng dữ liệu của bạn và horizon=12 bằng số ngày muốn dự báo:
outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))Kết quả: mỗi sản phẩm nhận một dự báo điểm và 9 phân vị. Bạn lấy phân vị cao (gần 0,9) để biết kịch bản bán tốt khi cần nhập thêm, và phân vị thấp (gần 0,1) để biết kịch bản xấu khi cần tránh tồn kho.
Dự báo tốt không phải một con số chắc nịch, mà là một khoảng đủ hẹp để bạn dám quyết định.
Ông T
B.Phân tích dữ liệu dự báo nhiều cửa hàng cùng lúc có kèm lịch khuyến mãi
Bạn quản lý 3 cửa hàng và đã có sẵn lịch khuyến mãi cho 24 ngày tới. Đây là loại biến "có cả quá khứ lẫn tương lai". Bạn xếp doanh số 3 cửa hàng thành mảng (3, độ dài lịch sử). Lịch khuyến mãi xếp thành mảng có độ dài bằng lịch sử cộng số ngày dự báo. Ví dụ trong README:
context_len = 128
horizon = 24
# 3 target variates across past context: (3, 128)
target = np.random.randn(3, context_len).astype(np.float32)
# 1 past-only covariate channel across past context: (1, 128)
past_only_cov = np.random.randn(1, context_len).astype(np.float32)
# 2 past-and-future covariate channels across context + horizon: (2, 152)
past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32)
outputs = list(
forecaster.predict_batch(
contexts=[target],
horizon=horizon,
past_only_covariates=[past_only_cov],
past_future_covariates=[past_future_cov],
return_quantiles=True,
use_symmetric_averaging=False,
)
)Kết quả: outputs[0].forecast có dạng (3, 24), tức mỗi cửa hàng một dự báo 24 ngày. quantiles có dạng (3, 24, 9). Trong README, các mảng này là số ngẫu nhiên để minh hoạ hình dạng dữ liệu. Khi dùng thật, bạn thay bằng số liệu của mình, đúng thứ tự cột và đúng độ dài.
C.Người dùng Mac chạy dự báo cục bộ, không cần PyTorch
Bạn dùng MacBook chip Apple silicon và không muốn cài PyTorch. Bạn cài timesfm[mlx], nạp mô hình bằng from_pretrained, rồi dự báo một chuỗi dài:
context = np.sin(np.linspace(0, 40, 512)).astype(np.float32)
out = forecaster.predict(context, horizon=128, return_quantiles=True)
print(out.forecast.shape) # (128,) median forecast
print(out.quantiles.shape) # (128, 9) 9 decilesNếu có nhiều chuỗi, bạn đưa cả danh sách vào một lần: forecaster.predict_batch([context] * 32, horizon=128). README đưa số đo trên máy Apple M4 Max với mô hình 330M, ngữ cảnh 512, horizon 64: batch 32 đạt khoảng 666 chuỗi mỗi giây. Máy của bạn có thể chậm hơn, nhưng số này cho thấy việc dự báo hàng loạt là khả thi ngay trên laptop.
D.Dùng cho công việc thương mại: đi qua dịch vụ của Google Cloud
Bạn làm ở công ty và cần dự báo cho việc kinh doanh thật. README nói TimesFM 3.0 được cung cấp trong BigQuery ML (truy vấn SQL), Google Sheets (qua Connected Sheets) và Vertex Model Garden (endpoint đóng gói Docker). Với các dịch vụ này, README khẳng định việc dùng thương mại và sản xuất được cho phép theo điều khoản của Google Cloud. Tải trọng số về tự chạy thì không được phép. Repo không có hướng dẫn chi tiết cho các dịch vụ này, bạn xem tài liệu BigQuery ML của Google để biết cách bật và tính phí.
VI.Lỗi hay gặp và cách xử lý
A.Python báo không tìm thấy module timesfm3
Đây là chỗ người mới dễ vấp nhất, vì tên gói cài là timesfm còn ví dụ nhập từ timesfm3. Hãy kiểm tra bạn đã cài đúng môi trường ảo (đã kích hoạt .venv chưa). Sau đó mở thư mục timesfm3-usage/ và src/ trong repo để xem cách nhập đúng với phiên bản bạn đang dùng. Nếu bạn cài từ PyPI mà vẫn không thấy, thử cài từ mã nguồn theo Cách B.
B.pip install timesfm[torch] báo lỗi trên zsh
Trên zsh, dấu [ ] bị coi là mẫu ký tự đại diện. Bạn đặt tên gói trong dấu nháy: pip install "timesfm[torch]". Nếu vẫn lỗi, kiểm tra lại phiên bản Python vì gói yêu cầu từ 3.10.
C.Lỗi liên quan cuda hoặc GPU
Ví dụ đặt device="cuda". Nếu máy không có GPU NVIDIA hoặc driver chưa đúng, chương trình có thể báo lỗi. README không nêu giá trị thay thế, nên mình không dám đoán. Hãy xem timesfm3-usage/ và các ví dụ trong timesfm-forecasting/. Hoặc nếu dùng Mac Apple silicon, chuyển sang nhánh MLX.
D.Lỗi hình dạng mảng khi dùng covariate
Biến chỉ có trong quá khứ phải có độ dài đúng bằng ngữ cảnh. Biến có cả tương lai phải dài bằng ngữ cảnh cộng horizon, ví dụ 128 + 24 = 152. Hãy in .shape của từng mảng trước khi gọi predict_batch. Mảng đa biến phải có dạng (số biến, độ dài), không phải (độ dài, số biến). Nhiều dữ liệu xuất từ bảng tính đang nằm ngược chiều này, nên bạn nhớ chuyển vị.
E.Tải checkpoint thất bại hoặc quá chậm
Lần chạy đầu cần tải google/timesfm-3.0-pytorch từ Hugging Face. Nếu mạng yếu hoặc bị chặn, bước này sẽ treo hoặc lỗi. Bạn thử lại với mạng ổn định hơn. README không nói gì về việc tải thủ công hay thư mục lưu tạm.
VII.Có nên dùng không
Điểm mạnh. Bạn không phải huấn luyện mô hình riêng cho từng bộ dữ liệu. Theo README, bản 3.0 đứng hạng nhất trên fev-bench, TIME Benchmark và trong nhóm mô hình nền tảng của GIFT-Eval. Mô hình hỗ trợ đa biến, covariate, phân vị và chạy được trên Mac. Mã nguồn dưới Apache-2.0, repo vẫn được cập nhật trong 3 tháng gần đây và có thêm skill cho agent cùng ví dụ tinh chỉnh bằng LoRA.
Giới hạn. Trước hết là giấy phép. Trọng số TimesFM 3.0 bị giới hạn ở mục đích phi thương mại và phi sản xuất. Nếu bạn muốn tự chạy phục vụ kinh doanh, README cho biết trọng số các bản đến 2.5 vẫn là Apache-2.0, bạn xem lại điều khoản trên trang checkpoint trước khi quyết định. Tiếp theo, README viết cho người đã quen Python và NumPy, còn việc chuyển dữ liệu từ Excel sang mảng NumPy là phần bạn tự làm. Cuối cùng, tư liệu cũng chưa nói rõ yêu cầu phần cứng cụ thể, độ chính xác trên dữ liệu doanh nghiệp nhỏ, hay quyền riêng tư của dữ liệu. README cũng nói bản mã nguồn mở này không phải sản phẩm được Google hỗ trợ chính thức.
Khi nào chọn cách khác. Nếu bạn chỉ có một bảng nhỏ trong Google Sheets và cần dự báo cho công việc hằng ngày, dịch vụ Connected Sheets với BigQuery ML mà README nhắc tới có thể phù hợp hơn, vì không phải cài gì. Nếu cần dùng thương mại và muốn chạy trên máy riêng, bạn cân nhắc phiên bản cũ hơn có giấy phép thoải mái hơn hoặc công cụ dự báo khác. Còn nếu bạn muốn học, nghiên cứu hay thử nghiệm, TimesFM là một nơi bắt đầu rất đáng thử.
Câu hỏi thường gặp
TimesFM có miễn phí không?
Mã nguồn trong repo dùng giấy phép Apache-2.0, tải và dùng không mất phí. Trọng số bản 3.0 có giấy phép riêng, chỉ cho phép mục đích phi thương mại và phi sản xuất. Muốn dùng thương mại, README nói bạn phải đi qua dịch vụ Google Cloud như BigQuery ML, và chi phí của các dịch vụ đó README chưa nêu.
TimesFM cần GPU không?
Các ví dụ PyTorch trong README đặt device là cuda, tức là chạy trên GPU NVIDIA. README không nói rõ máy chỉ có CPU có chạy được không và cũng không nêu yêu cầu RAM hay VRAM. Trên Mac Apple silicon thì có nhánh MLX, README đo trên chip M4 Max.
TimesFM chạy được trên Windows không?
README không nêu danh sách hệ điều hành được hỗ trợ. Cách cài bằng pip và yêu cầu Python từ 3.10 trở lên là những gì tư liệu có. Riêng lệnh kích hoạt môi trường ảo trong README viết cho Mac/Linux, còn trên Windows bạn dùng đường dẫn kích hoạt tương ứng của môi trường ảo.
TimesFM khác gì các phương pháp dự báo truyền thống?
TimesFM là mô hình nền tảng đã huấn luyện sẵn, README gọi là zero-shot, nghĩa là bạn không phải huấn luyện lại cho từng bộ dữ liệu. Bản 3.0 hỗ trợ đa biến và covariate mà không cần tinh chỉnh riêng. README không so sánh trực tiếp với từng phương pháp truyền thống, chỉ nêu thứ hạng trên các bảng benchmark.
Dữ liệu của tôi có an toàn không khi dùng TimesFM?
Khi chạy cục bộ, dữ liệu nằm trên máy bạn và được xử lý bằng mã trong repo. Tuy nhiên README chưa có phần nào nói về bảo mật hay quyền riêng tư, nên mình không thể cam kết thêm. Nếu dùng các dịch vụ Google Cloud, bạn áp dụng điều khoản của Google Cloud.
Tôi dùng được TimesFM cho mục đích kinh doanh không?
Với trọng số bản 3.0 tải về tự chạy thì không. README nêu rõ việc này không được phép. Việc dùng thương mại và sản xuất được cho phép qua dịch vụ Google Cloud được ủy quyền, ví dụ BigQuery ML. Trọng số các bản đến 2.5 vẫn là Apache-2.0 theo README.
Nếu cần bản cũ như 1.0 hoặc 2.0 thì cài thế nào?
README nói mã của bản 1.0 và 2.0 nằm trong thư mục v1. Bạn có thể cài gói cũ bằng lệnh pip install timesfm==1.3.0 để nạp các bản này. Mã bản 2.5 thì nằm trong thư mục src/timesfm.


