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
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 dự báo chuỗi thời gian đã được huấn luyện sẵn của Google Research, viết bằng Python, mã nguồn Apache-2.0. Bạn đưa vào một dãy số theo thời gian và nhận lại dự báo cùng các mức phân vị. Cài bằng pip khá đơn giản, nhưng bản 3.0 có giấy phép trọng số riêng: chỉ dùng phi thương mại.
TimesFM là một mô hình AI đã học sẵn từ rất nhiều chuỗi số theo thời gian, do Google Research phát triển, dùng để dự báo các con số trong tương lai. Bạn đưa vào lịch sử doanh thu, lượng truy cập hay nhiệt độ, mô hình trả về dự báo cho các bước tiếp theo, kèm các mức phân vị để biết độ bất định. Repo hiện có khoảng 35 nghìn sao và hơn 3 nghìn fork, mã nguồn dùng giấy phép Apache-2.0.
Người nên xem repo này là nhân viên phân tích số liệu, chủ shop có dữ liệu bán hàng theo ngày, và lập trình viên mới muốn có một công cụ dự báo mà không phải tự huấn luyện mô hình. Bạn cần biết cơ bản về Python và mở được terminal. Không cần hiểu toán phía sau.
Điểm đáng giá nhất là mô hình "zero-shot": dùng ngay trên dữ liệu của bạn mà không cần huấn luyện riêng cho từng bài toán. Bản mới nhất, TimesFM 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ư lịch khuyến mãi. Có một lưu ý quan trọng về giấy phép, mình nói rõ ở phần cần chuẩn bị và phần cuối bà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 thu, lượng truy cập…) ngay từ đầu mà không cần tự huấn luyện.
I.TimesFM làm được gì
A.Dự báo từng chuỗi số, độ dài khác nhau
Bạn có thể đưa vào một loạt chuỗi 1 chiều, mỗi chuỗi có độ dài khác nhau, và nhận dự báo cho tất cả trong một lần gọi. Ví dụ bạn có 50 sản phẩm, có sản phẩm bán được 3 tháng, có sản phẩm bán được 2 năm. Bạn không phải cắt cho bằng nhau.
B.Dự báo kèm các mức phân vị
Ngoài một con số dự báo chính, mô hình trả thêm 9 mức phân vị (từ 0.1 đến 0.9). Nhờ đó bạn thấy được khoảng dao động: kịch bản thấp là bao nhiêu, kịch bản cao là bao nhiêu. Khi lập kế hoạch nhập hàng hay ngân sách, khoảng này hữu ích hơn một con số duy nhất.
C.Dự báo nhiều chuỗi cùng lúc (đa biến) và dùng biến phụ
TimesFM 3.0 hỗ trợ dự báo nhiều kênh dữ liệu cùng lúc. Nó cũng nhận hai loại biến phụ (covariate): loại chỉ có ở quá khứ, và loại biết cả quá khứ lẫn tương lai (như lịch khuyến mãi, ngày lễ đã lên kế hoạch). README nói việc này làm được mà không cần tinh chỉnh riêng cho từng bài toán.
D.Chạy trên máy Mac chip Apple
Có một backend MLX chạy TimesFM 3.0 trên Apple silicon mà không cần PyTorch. README cho biết nó dùng giao diện giống bản PyTorch, nên đổi qua lại khá dễ.
E.Tài liệu, skill cho agent và ví dụ tinh chỉnh
Trong repo có file AGENTS.md và thư mục timesfm-forecasting/ chứa SKILL.md, tức là có thể dùng TimesFM như một skill cho các agent lập trình. Thư mục này còn có ví dụ tinh chỉnh bằng LoRA qua HuggingFace Transformers và PEFT, nằm ở timesfm-forecasting/examples/finetuning/. Repo cũng có thư mục tests/ với các bài kiểm thử.
F.Thành tích do tác giả công bố
Theo README, TimesFM 3.0 xếp hạng nhất ở các bộ đánh giá fev-bench và TIME Benchmark, và đứng đầu trong các mô hình nền tảng ở GIFT-Eval. Đây là số liệu do chính tác giả công bố, bạn nên tự thử trên dữ liệu của mình trước khi tin.
II.Cần chuẩn bị gì
- Python 3.10 trở lên. File
pyproject.tomlcủa repo yêu cầu như vậy. - Công cụ cài đặt:
pip. Cách cài từ mã nguồn trong README dùng thêmuv. - PyTorch (cài kèm khi chạy
pip install timesfm[torch]), hoặc MLX nếu bạn dùng máy Mac chip Apple. - Kết nối mạng để tải checkpoint từ Hugging Face. Các ví dụ trong README gọi
google/timesfm-3.0-pytorch. - GPU: các ví dụ PyTorch trong README đặt
device="cuda", tức là viết cho máy có card NVIDIA. README không nói rõ có chạy được trên CPU hay không, nên bạn cần xem mã trongsrc/hoặc thử trước. Máy Mac chip Apple có đường chạy riêng bằng MLX. - README không nhắc yêu cầu tài khoản hay API key nào cho các bước trên.
Giấy phép trọng số: mã nguồn là Apache-2.0, và trọng số đến phiên bản 2.5 cũng Apache-2.0. Riêng trọng số TimesFM 3.0 dùng giấy phép riêng (timesfm-non-commercial-license-v1.0), chỉ cho phép dùng phi thương mại, không dùng cho sản xuất. Nếu bạn định dùng cho công việc kinh doanh, hãy đọc kỹ phần License notice trong README trước. Theo README, dùng thương mại bản 3.0 được phép thông qua các dịch vụ Google Cloud được cấp phép như BigQuery ML.
III.Cài đặt từng bước
- Mở terminalChọn terminal có Python 3.10 trở lên
- Cài từ PyPIChạy pip install timesfm[torch] (hoặc timesfm[mlx] trên Mac chip Apple)
- Hoặc cài từ mã nguồnClone repo, tạo môi trường ảo, cài chế độ editable
- Chạy thử ví dụChép ví dụ trong README, chạy bằng Python
A.Bước 1: Mở terminal và kiểm tra Python
Trên Windows, bạn mở PowerShell. Trên Mac hoặc Linux, mở Terminal. Hãy chắc là máy có Python từ 3.10 trở lên, vì repo yêu cầu như vậy. Chỗ người mới hay vấp là cài nhầm vào Python cũ. Nếu pip báo lỗi phiên bản, hãy kiểm tra lại phiên bản Python trước.
B.Bước 2: Cài nhanh từ PyPI
Đây là cách dễ nhất. Chọn một trong hai lệnh tùy máy của bạn:
# Install TimesFM with PyTorch
pip install timesfm[torch]
# Or, for MLX-native inference on Apple silicon (no PyTorch required)
pip install timesfm[mlx]Lệnh đầu cài kèm PyTorch. Lệnh sau dành cho máy Mac chip Apple, không cần PyTorch. Nếu dùng PowerShell hoặc zsh mà bị lỗi do dấu ngoặc vuông, hãy đặt tên gói trong dấu nháy kép, ví dụ pip install "timesfm[torch]".
README còn ghi một điều đáng lưu ý: bản timesfm trên PyPI là 2.0.2, và các mô hình đời cũ (1.0 và 2.0) có thể cài bằng pip install timesfm==1.3.0. Các ví dụ cho TimesFM 3.0 trong README lại import từ timesfm3. README không giải thích rõ gói timesfm3 đến từ đâu khi cài bằng PyPI. Nếu bạn muốn chạy bản 3.0, hãy xem thư mục timesfm3-usage/ trong repo và cài từ mã nguồn (bước dưới) để chắc chắn.
C.Bước 3: Hoặc cài từ mã nguồn
Cách này hợp với bạn nếu muốn đọc hoặc sửa mã. Trước hết tải repo về và vào thư mục:
git clone https://github.com/google-research/timesfm.git
cd timesfmSau đó tạo môi trường ảo và cài ở chế độ editable. 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]Giải thích: uv venv tạo một môi trường Python riêng trong thư mục .venv, để không lẫn với các dự án khác. Lệnh source .venv/bin/activate là cú pháp của Mac và Linux. Trên Windows, lệnh kích hoạt môi trường ảo khác (thường là chạy file activate trong thư mục .venv\Scripts), README không hướng dẫn phần này. Lệnh cuối cài gói ở chế độ editable, kèm PyTorch. Bạn phải đứng trong thư mục timesfm thì lệnh mới chạy đúng.
D.Bước 4: Chạy thử ví dụ đầu tiên
Lưu đoạn mã dưới thành file thu.py rồi chạy bằng Python. Đây là ví dụ dự báo nhiều chuỗi 1 chiều, độ dài khác nhau, đúng như README:
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)Các điểm chính trong đoạn mã: horizon=12 là số bước muốn dự báo; return_quantiles=True yêu cầu trả thêm 9 mức phân vị; device="cuda" nghĩa là dùng card NVIDIA. Lần chạy đầu sẽ tải checkpoint từ Hugging Face nên mất thời gian.
Nếu bạn dùng Mac chip Apple, README có đoạn mã riêng với backend MLX, mình đưa ở phần dùng thực tế bên dưới.
IV.Kiểm tra đã chạy được chưa
Với ví dụ ở bước 4, bạn biết đã thành công khi chương trình chạy xong không báo lỗi và in ra các dòng kích thước. Theo chú thích trong README, kết quả mong đợi là:
- Dự báo của chuỗi 1 và chuỗi 2 đều có shape
(12,). - Phân vị của mỗi chuỗi có shape
(12, 9).
Con số 12 chính là horizon, còn 9 là số mức phân vị. Nếu bạn đổi horizon thành 24, con số đầu tiên cũng đổi theo. Đó là cách nhanh để chắc rằng mô hình đang nhận đúng tham số của bạn. Nếu dòng import đã báo lỗi thì chưa chạm đến mô hình, hãy xem phần lỗi bên dưới.
V.Dùng vào việc thật
A.Nhân viên văn phòng: dự báo nhiều sản phẩm cùng lúc
Bối cảnh: bạn làm kế hoạch bán hàng, có số bán theo ngày của nhiều mặt hàng, mỗi mặt hàng có lịch sử dài ngắn khác nhau. Việc cần làm là dự báo 12 bước tiếp theo cho từng mặt hàng.
Cách làm: thay hai chuỗi giả trong ví dụ bước 4 bằng dữ liệu thật của bạn, mỗi mặt hàng là một mảng NumPy kiểu float32. Đưa cả danh sách vào predict_batch. README nói rõ hàm này nhận các chuỗi có độ dài khác nhau.
Kết quả: mỗi mặt hàng có một dự báo trung vị và 9 mức phân vị. Bạn có thể xuất ra Excel để so với kế hoạch hiện có. Hãy dùng mức phân vị thấp và cao để thấy khoảng dao động, đừng chỉ nhìn đường trung vị.
Một con số dự báo thì dễ tin nhầm, một dải phân vị thì buộc bạn nghĩ đến rủi ro.
Ông T
B.Chủ shop có lịch khuyến mãi: dùng biến phụ
Bối cảnh: bạn theo dõi 3 chỉ số của cửa hàng (ví dụ số đơn, số lượt xem, số khách mới) và biết trước lịch khuyến mãi của 24 ngày tới. Muốn dự báo cả ba chỉ số cùng lúc, có tính đến khuyến mãi.
Cách làm: theo ví dụ đa biến của README. Mảng mục tiêu có dạng (số_chuỗi, độ_dài_quá_khứ). Biến phụ chỉ có ở quá khứ có dạng (số_kênh, độ_dài_quá_khứ). Biến phụ biết cả tương lai (như lịch khuyến mãi) có độ dài bằng quá khứ cộng horizon. Đoạn mã mẫu của README:
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=16,
device="cuda"
)
forecaster = TimesFM3Evaluator(config)
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)
# Generate joint forecast across all 3 target variates
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,
)
)
print("Multivariate forecast shape:", outputs[0].forecast.shape) # (3, 24)
print("Multivariate quantiles shape:", outputs[0].quantiles.shape) # (3, 24, 9)Kết quả: dự báo chung cho cả ba chỉ số, shape (3, 24), kèm phân vị (3, 24, 9). Ở ví dụ mẫu, dữ liệu là số ngẫu nhiên chỉ để minh họa; bạn thay bằng dữ liệu thật. Nhớ đọc lại phần giấy phép: dùng bản 3.0 cho cửa hàng kinh doanh có thể nằm ngoài phạm vi phi thương mại.
C.Người dùng Mac chip Apple: chạy bằng MLX
Bối cảnh: bạn dùng MacBook, không có card NVIDIA và không muốn cài PyTorch.
Cách làm: cài pip install timesfm[mlx], rồi dùng backend MLX của README:
import numpy as np
from timesfm3.mlx import TimesFM3Forecaster
forecaster = TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch")
# Univariate, long horizon (>= 128 spans several output patches).
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 deciles
# Batch many series through one forward pass.
outs = list(forecaster.predict_batch([context] * 32, horizon=128))Kết quả: dự báo 128 bước kèm 9 phân vị. README còn nêu số đo trên Apple M4 Max (mô hình 330M, context 512, horizon 64): batch 1 mất khoảng 11,1 ms, batch 32 mất khoảng 48,1 ms. Máy của bạn có thể khác, nhưng đủ để thấy tốc độ không phải vấn đề lớn.
D.Lập trình viên: dùng như skill cho agent hoặc tinh chỉnh
Bối cảnh: bạn dùng một agent lập trình và muốn nó biết cách dự báo chuỗi thời gian bằng TimesFM; hoặc bạn muốn mô hình quen hơn với dữ liệu riêng.
Cách làm: sau khi clone repo, mở file AGENTS.md và thư mục timesfm-forecasting/ (có SKILL.md) để xem cách agent sử dụng. Muốn tinh chỉnh, xem ví dụ tại timesfm-forecasting/examples/finetuning/, dùng LoRA qua HuggingFace Transformers và PEFT. README không đưa lệnh chạy cụ thể cho các phần này, nên bạn cần đọc tài liệu đi kèm trong từng thư mục.
Kết quả: agent có hướng dẫn rõ ràng để gọi mô hình, hoặc bạn có một điểm khởi đầu để tinh chỉnh.
VI.Lỗi hay gặp và cách xử lý
A.ModuleNotFoundError khi import timesfm3
Đây là lỗi dễ gặp nhất vì ví dụ README import timesfm3, trong khi phần cài đặt nói về gói timesfm. Hãy kiểm tra bạn đã cài bằng pip chưa, và đã kích hoạt đúng môi trường ảo chưa. Nếu vẫn lỗi, xem thư mục timesfm3-usage/ trong repo để biết cách cài và gọi đúng cho bản 3.0, hoặc thử cài từ mã nguồn như bước 3.
B.Lỗi liên quan đến CUDA hoặc không có GPU
Các ví dụ PyTorch đặt device="cuda". Nếu máy bạn không có card NVIDIA, lệnh này sẽ lỗi. README không nói rõ cách chạy bằng CPU, nên hãy xem lớp ModelConfig trong thư mục src/ hoặc timesfm3-usage/ để biết giá trị device nào được hỗ trợ. Nếu là Mac chip Apple, dùng backend MLX thì tiện hơn.
C.Không tải được checkpoint từ Hugging Face
Lần chạy đầu cần tải mô hình về, nên máy phải có mạng ổn định. Nếu bị gián đoạn, hãy chạy lại. Nếu bị báo thiếu quyền truy cập, vào trang của mô hình trên Hugging Face xem có điều khoản cần đồng ý không. README không nói bước nào bắt buộc, nên mình không khẳng định thêm.
D.Báo lỗi shape hoặc dtype khi đưa dữ liệu
Ví dụ trong README luôn đổi dữ liệu sang float32 và đặt đúng hình dạng: chuỗi 1 chiều là (độ_dài,), đa biến là (số_chuỗi, độ_dài), biến phụ biết tương lai dài hơn quá khứ đúng bằng horizon. Nếu bạn gặp lỗi kích thước, so lại từng mảng với các chú thích shape trong ví dụ.
E.Dùng bản 3.0 cho công việc kinh doanh
Đây không phải lỗi chương trình mà là rủi ro pháp lý. Trọng số 3.0 chỉ cho phép dùng phi thương mại. Nếu bạn cần dùng cho sản xuất, hãy chọn dịch vụ Google Cloud được README nêu (như BigQuery ML) hoặc kiểm tra lại giấy phép của từng phiên bản trọng số trước khi dùng.
VII.Có nên dùng không
Điểm mạnh. Bạn không phải tự huấn luyện mô hình, nên bắt đầu rất nhanh. Mô hình trả cả phân vị, dự báo được nhiều chuỗi cùng lúc, nhận biến phụ, và có đường chạy riêng cho Mac chip Apple. Mã nguồn Apache-2.0, repo vẫn được cập nhật đều và có kiểm thử, có tài liệu cho cả agent.
Giới hạn. Thứ nhất là giấy phép: trọng số 3.0 chỉ cho dùng phi thương mại. Thứ hai, README viết cho người đã quen Python; phần cài đặt còn chỗ chưa liền mạch (gói timesfm và timesfm3), và không hướng dẫn riêng cho Windows hay chạy bằng CPU. Thứ ba, các thành tích benchmark do tác giả công bố, bạn cần tự kiểm tra trên dữ liệu thật. README cũng ghi 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ỉ muốn dự báo trong bảng tính hàng ngày, README nêu rằng TimesFM đã có trong Google Sheets (qua Connected Sheets với BigQuery ML), nên bạn không phải viết mã. Nếu cần dùng thương mại ở quy mô lớn, hãy đi qua BigQuery ML hoặc Vertex Model Garden như README gợi ý. Nếu bạn không biết Python và chỉ có vài chục dòng số, một công thức dự báo trong Excel có thể đã đủ dùng.
Câu hỏi thường gặp
TimesFM có miễn phí không?
Mã nguồn dùng giấy phép Apache-2.0, và trọng số đến phiên bản 2.5 cũng Apache-2.0. Riêng trọng số TimesFM 3.0 dùng giấy phép phi thương mại riêng, không cho dùng cho thương mại hay sản xuất khi tự tải về. README nói dùng thương mại bản 3.0 được phép qua các dịch vụ Google Cloud được cấp phép như BigQuery ML.
TimesFM dùng để làm gì?
Để dự báo chuỗi thời gian, tức các con số thay đổi theo thời gian như doanh thu hay lượng truy cập. Bạn đưa lịch sử vào và nhận lại dự báo cùng 9 mức phân vị. Bản 3.0 còn dự báo được nhiều chuỗi cùng lúc và dùng biến phụ.
Có cần GPU không?
Các ví dụ PyTorch trong README đặt device là cuda, tức viết cho máy có GPU NVIDIA. README không nói rõ có chạy được bằng CPU hay không, nên chưa có thông tin chắc chắn. Với máy Mac chip Apple, có backend MLX chạy riêng, không cần PyTorch.
Chạy được trên Windows không?
README không có hướng dẫn riêng cho Windows. Lệnh kích hoạt môi trường ảo trong README là kiểu Mac/Linux. Gói là Python thuần nên về nguyên tắc cài bằng pip, nhưng bạn nên tự thử và xem thêm mã trong repo.
Cần Python phiên bản nào?
File pyproject.toml của repo yêu cầu Python từ 3.10 trở lên. Bạn cài bằng pip install timesfm[torch], hoặc timesfm[mlx] nếu dùng Mac chip Apple.
Dữ liệu của mình có bị gửi đi đâu không?
README không nói gì về việc gửi dữ liệu ra ngoài. Theo các ví dụ, bạn tải checkpoint từ Hugging Face rồi chạy mô hình trên máy mình. Chưa có thông tin chi tiết hơn, nếu cần chắc chắn bạn nên tự đọc mã nguồn.
Khác gì dự báo trong Google Sheets hay BigQuery ML?
README cho biết TimesFM có mặt trong BigQuery ML (truy vấn SQL cho doanh nghiệp), trong Google Sheets và trong Vertex Model Garden. Repo này là bản mã nguồn mở để bạn tự chạy bằng Python. Bản mã nguồn mở không phải sản phẩm được Google hỗ trợ chính thức.


