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 (Time Series Foundation Model) là mô hình đã huấn luyện sẵn của Google Research để dự báo chuỗi thời gian, viết bằng Python, mã nguồn Apache-2.0. Bạn đưa dữ liệu quá khứ vào, mô hình trả về dự báo và các mức phân vị. Cài bản 2.5 chỉ cần một lệnh pip, còn bản 3.0 có thêm vài bước và có giới hạn về giấy phép trọng số.
TimesFM là một mô hình AI đã được huấn luyện sẵn để dự báo chuỗi thời gian, do Google Research phát triển. Chuỗi thời gian là dãy số đo theo thời gian: doanh thu từng ngày, số đơn hàng mỗi tuần, lượng khách vào cửa hàng, nhiệt độ, giá điện... Bạn đưa vào những con số của quá khứ, mô hình đoán những con số sắp tới.
Điểm đáng giá nhất là mô hình "nền tảng" (foundation model). Bình thường, muốn dự báo bạn phải chọn thuật toán, chỉnh tham số, huấn luyện riêng cho từng loại dữ liệu. Với TimesFM, tác giả mô tả khả năng dự báo "zero-shot": đưa dữ liệu vào là có kết quả, không cần huấn luyện lại cho từng bài toán. Repo hiện có khoảng 35.452 sao và 3.471 fork, mã nguồn dùng giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây.
Bài này hợp với lập trình viên mới, người làm phân tích dữ liệu, hoặc chủ doanh nghiệp nhỏ có người biết chạy vài dòng Python. Bạn cần biết mở terminal và chạy lệnh. Bạn cũng nên đọc kỹ phần giấy phép ở cuối mục chuẩn bị, vì trọng số bản 3.0 có giới hạn về dùng thương mạ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 như doanh thu hay lượng truy cập mà không cần tự huấn luyện mô hình riêng.
I.TimesFM làm được gì
Dự báo chuỗi đơn (univariate). Bạn đưa vào nhiều chuỗi số có độ dài khác nhau, ví dụ một chuỗi 100 điểm và một chuỗi 72 điểm. Mô hình dự báo cho từng chuỗi. Lợi ích thực tế: bạn không phải cắt dữ liệu cho bằng nhau.
Dự báo nhiều chuỗi cùng lúc (multivariate). Bản 3.0 hỗ trợ trực tiếp nhiều kênh dữ liệu liên quan nhau, ví dụ doanh thu của ba sản phẩm. Mô hình dự báo chung cho cả ba chứ không xử lý từng cái riêng lẻ.
Dùng thêm biến phụ (covariates). Có hai loại. Loại chỉ có ở quá khứ, ví dụ lượng mưa đã đo. Loại có cả quá khứ lẫn tương lai, ví dụ lịch khuyến mãi đã lên kế hoạch hoặc ngày lễ. Thêm thông tin này giúp dự báo sát thực tế hơn so với chỉ nhìn một dãy số.
Trả về cả khoảng dự báo. Ngoài con số dự báo chính, mô hình có thể trả 9 mức phân vị từ 0.1 đến 0.9. Nhờ vậy bạn biết "khả năng thấp nhất" và "khả năng cao nhất" để lên kế hoạch nhập hàng hay chuẩn bị nhân sự, thay vì chỉ có một con số.
Chạy trên máy Mac chip Apple. Có backend MLX riêng, không cần PyTorch. README đưa số đo trên Apple M4 Max với mô hình 330M: batch 1 mất khoảng 11,1 ms, batch 32 đạt khoảng 666 chuỗi mỗi giây.
Có sẵn nhiều phiên bản. Bản 3.0 là mới nhất. Bản 2.5 nằm trong thư mục src/timesfm, có 200 triệu tham số, hỗ trợ ngữ cảnh tới 16 nghìn điểm. Bản 1.0 và 2.0 nằm ở thư mục v1.
Có ví dụ tinh chỉnh và skill cho agent. Repo có ví dụ fine-tune bằng LoRA (HuggingFace Transformers + PEFT) trong timesfm-forecasting/examples/finetuning/. Repo cũng có file AGENTS.md và một SKILL.md trong timesfm-forecasting/ để các công cụ AI lập trình dùng được.
II.Cần chuẩn bị gì
- Python từ 3.10 trở lên (theo
pyproject.toml). - Môi trường chạy: hoặc PyTorch (cài qua
timesfm[torch]), hoặc MLX nếu bạn dùng máy Mac chip Apple (cài quatimesfm[mlx], không cần PyTorch). - Công cụ
uvnếu bạn đi theo cách cài từ mã nguồn mà README hướng dẫn. - Git để tải mã nguồn về (chỉ cần khi cài từ mã nguồn).
- Kết nối mạng để lấy checkpoint từ Hugging Face. Các ví dụ trỏ tới
google/timesfm-3.0-pytorch. - Phần cứng: các ví dụ PyTorch trong README đặt
device="cuda", tức dùng card đồ họa NVIDIA. README không nói rõ máy chỉ có CPU có chạy được hay không, nên mình không khẳng định.
README không nhắc đến API key hay tài khoản trả phí cho phần chạy tại máy.
Giấy phép: mã nguồn là Apache-2.0 và trọng số đến bản 2.5 cũng Apache-2.0. Nhưng trọng số TimesFM 3.0 theo giấy phép riêng (timesfm-non-commercial-license-v1.0), chỉ cho dùng phi thương mại, không dùng cho sản xuất. Nếu bạn dùng cho công việc kinh doanh, hãy đọc kỹ giấy phép trên trang Hugging Face của checkpoint trước khi làm. README nói dùng thương mại bản 3.0 được cho phép qua các dịch vụ Google Cloud được ủy quyền, ví dụ BigQuery ML.
III.Cài đặt từng bước
- Mở terminalDùng Terminal (Mac/Linux) hoặc PowerShell (Windows) có Python 3.10 trở lên
- Cài từ PyPIMột lệnh pip, chọn PyTorch hoặc MLX
- Hoặc cài từ mã nguồnTải repo bằng git, tạo môi trường ảo, cài bằng uv
- Chạy ví dụChép đoạn code mẫu của README vào file Python và chạy
A.Mở terminal
Trên Windows, bấm Start, gõ PowerShell rồi mở lên. Trên Mac, mở Terminal. Gõ python --version để kiểm tra bạn có Python 3.10 trở lên. Nếu thấp hơn, bạn cần cài bản mới hơn trước, nếu không pip sẽ báo lỗi.
B.Cách 1: Cài từ PyPI (nhanh nhất)
Đây là cách README ghi trong phần Install. Chọn một trong hai lệnh:
# 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, dùng cho máy thông thường. Lệnh thứ hai dành cho máy Mac chip Apple. Phần sau dấu # chỉ là ghi chú, bạn không cần gõ.
Chỗ người mới hay vấp: một số terminal (như zsh trên Mac) hiểu nhầm dấu ngoặc vuông. Nếu gặp lỗi, bạn đặt cả tên gói trong dấu nháy kép, ví dụ pip install "timesfm[torch]".
C.Cách 2: Cài từ mã nguồn
Cách này hợp nếu bạn muốn đọc hoặc sửa code. 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 gói ở chế độ chỉnh sửa được (editable), kèm PyTorch:
# Using uv
uv venv
source .venv/bin/activate
# Install the package in editable mode with torch
uv pip install -e .[torch]Lệnh uv venv tạo một môi trường Python riêng trong thư mục .venv, để không làm lộn xộn Python chung của máy. Dòng source .venv/bin/activate là lệnh kích hoạt của Mac/Linux. Trên Windows PowerShell, lệnh kích hoạt thông thường là .venv\Scripts\activate. README chỉ ghi lệnh cho Mac/Linux. Bạn thấy chữ (.venv) ở đầu dòng lệnh là đã kích hoạt.
D.Chạy ví dụ đầu tiên
README đưa các đoạn code mẫu cho bản 3.0. Chúng import từ timesfm3. README không giải thích riêng gói timesfm3 được cài thế nào, nên nếu import timesfm3 báo lỗi, bạn xem thư mục timesfm3-usage/ và file pyproject.toml trong repo để biết cách cài và dùng. Đoạn mẫu dự báo chuỗi đơn như sau:
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)Lưu code vào một file, ví dụ thu.py, rồi chạy bằng python thu.py. Trong đó horizon=12 nghĩa là dự báo 12 bước tiếp theo. return_quantiles=True bảo mô hình trả thêm 9 mức phân vị.
Nếu bạn dùng Mac chip Apple, README có đoạn riêng cho backend MLX:
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 decilesIV.Kiểm tra đã chạy được chưa
Cách kiểm tra đơn giản nhất là chạy đoạn mẫu chuỗi đơn ở trên. Nếu mọi thứ ổn, chương trình in ra kích thước của kết quả theo đúng như chú thích trong README:
Series 1 forecast shape: (12,)Series 1 quantiles shape: (12, 9)- Tương tự cho chuỗi thứ hai.
Nghĩa là mỗi chuỗi nhận được 12 điểm dự báo và mỗi điểm có 9 mức phân vị. Với backend MLX, kết quả mong đợi là (128,) và (128, 9).
Bạn cũng có thể thử pip show timesfm để xem gói đã được cài chưa. Lần chạy đầu thường lâu hơn vì phải tải checkpoint về. README chưa mô tả chi tiết bước tải này.
V.Dùng vào việc thật
A.Chủ shop dự báo doanh thu 12 ngày tới
Bạn có doanh thu mỗi ngày của vài tháng, lưu trong file bảng tính. Bạn xuất cột doanh thu thành một dãy số, chuyển thành mảng NumPy kiểu float32, rồi đưa vào predict_batch với horizon=12. Kết quả là 12 con số dự báo và 9 mức phân vị cho mỗi ngày. Bạn dùng mức thấp (0.1) để biết kịch bản xấu và mức cao (0.9) để biết kịch bản tốt khi quyết định nhập hàng.
Một điểm đáng nhớ: README cho phép nhiều chuỗi độ dài khác nhau trong cùng một lần gọi. Bạn có thể dự báo cho nhiều sản phẩm cùng lúc mà không cần làm cho chúng dài bằng nhau.
Dự báo hữu ích nhất khi nó cho bạn một khoảng, không chỉ một con số.
Ông T
B.Nhân viên văn phòng dự báo nhiều chỉ số liên quan nhau
Bộ phận bán hàng theo dõi cùng lúc ba chỉ số: số đơn, số khách mới, số lượt khiếu nại. Bạn gom thành mảng 2 chiều hình dạng (3, độ_dài_quá_khứ). Nếu có thêm thông tin như lịch khuyến mãi đã lên kế hoạch cho cả giai đoạn tương lai, đưa vào dưới dạng past_future_covariates. Còn những số chỉ biết ở quá khứ, như chi phí quảng cáo đã chi, đưa vào past_only_covariates. Mẫu code từ 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)
# 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,
)
)Kết quả là dự báo hình dạng (3, 24): 24 bước tiếp theo cho mỗi chỉ số. Bạn thay dữ liệu ngẫu nhiên của ví dụ bằng số thật của mình.
C.Lập trình viên mới thử trên máy Mac
Nếu bạn dùng MacBook chip Apple và không muốn cài PyTorch, cài timesfm[mlx] rồi dùng TimesFM3Forecaster.from_pretrained(...). Bạn có thể đẩy nhiều chuỗi qua một lần chạy bằng predict_batch, như dòng outs = list(forecaster.predict_batch([context] * 32, horizon=128)) trong README. Đây là cách thử nhanh để xem mô hình có hợp dữ liệu của bạn hay không trước khi đầu tư thêm.
D.Dev muốn tinh chỉnh hoặc nhờ agent AI dùng giúp
Nếu dữ liệu của bạn rất đặc thù, repo có ví dụ tinh chỉnh bằng LoRA trong timesfm-forecasting/examples/finetuning/. Nếu bạn dùng một công cụ AI lập trình, repo có AGENTS.md và SKILL.md trong timesfm-forecasting/. README chỉ nói các file này có mặt, không hướng dẫn chi tiết cách nạp vào từng công cụ, nên bạn mở các thư mục đó trong repo để đọc thêm.
VI.Lỗi hay gặp và cách xử lý
ModuleNotFoundError: No module named 'timesfm3'. Ví dụ trong README import từ timesfm3, trong khi lệnh cài chỉ nhắc gói timesfm. Bạn xem thư mục timesfm3-usage/ và pyproject.toml để biết cách cài hoặc cách đặt đường dẫn. Đừng đoán tên gói rồi cài bừa.
Lỗi liên quan cuda hoặc GPU. Các ví dụ đặt device="cuda". Nếu máy bạn không có card NVIDIA, đoạn này có thể lỗi. README không ghi giá trị thay thế, nên bạn cần xem mã nguồn trong src/ hoặc timesfm3-usage/ để biết các thiết bị được hỗ trợ. Nếu bạn dùng Mac chip Apple, hãy thử backend MLX.
pip báo không hiểu timesfm[torch]. Thường do shell hiểu sai dấu ngoặc vuông. Đặt trong dấu nháy kép như pip install "timesfm[torch]".
Python quá cũ. Gói yêu cầu Python 3.10 trở lên. Nếu python --version thấp hơn, hãy cài bản mới hơn hoặc tạo môi trường ảo bằng bản Python phù hợp.
Cần chạy bản cũ (1.0 hoặc 2.0). Bản mới của gói không nạp được chúng. README hướng dẫn cài bản cũ bằng pip install timesfm==1.3.0, hoặc xem code trong thư mục v1. Nên làm trong một môi trường ảo riêng để không lẫn với bản mới.
Nhầm về dùng thương mại. Đây không phải lỗi kỹ thuật nhưng rất đáng tránh. Trọng số bản 3.0 chỉ cho dùng phi thương mại khi tải về tự chạy. Nếu bạn cần dùng cho kinh doanh, hãy đọc giấy phép trên Hugging Face hoặc cân nhắc bản 2.5 (Apache-2.0) hay dịch vụ Google Cloud được ủy quyền.
VII.Có nên dùng không
Điểm mạnh. Bạn khỏi phải tự huấn luyện cho từng bài toán. Mô hình hỗ trợ chuỗi đơn, nhiều chuỗi và biến phụ, đồng thời trả khoảng dự báo. README nêu bản 3.0 đứng hạng 1 ở các bảng đánh giá fev-bench, TIME và GIFT-Eval (với GIFT-Eval là hạng 1 trong các mô hình nền tảng). Mã nguồn mở, có bản MLX cho máy Mac, có ví dụ tinh chỉnh và nhiều phiên bản để chọn.
Giới hạn. Phiên bản mới nhất có giấy phép trọng số khá chặt: phi thương mại, không dùng cho sản xuất. README cũng ghi bản mã nguồn mở này không phải sản phẩm chính thức được Google hỗ trợ. Phần hướng dẫn cho bản 3.0 hơi rời rạc: lệnh cài ghi timesfm, ví dụ lại import timesfm3. Với người mới, bạn có thể phải xem thêm trong repo. README cũng chưa nói rõ yêu cầu phần cứng tối thiểu.
Khi nên chọn cách khác. Nếu dữ liệu của bạn chỉ là vài chục dòng trong bảng tính và bạn cần một xu hướng đơn giản, công thức trong bảng tính là đủ. Nếu bạn cần dùng thương mại và không muốn lo về giấy phép trọng số, hãy xem bản 2.5 (Apache-2.0) hoặc các dịch vụ Google Cloud như BigQuery ML mà README nhắc đến. Còn nếu bạn muốn thử nhanh, bản MLX trên Mac hoặc bản PyTorch với dữ liệu mẫu là cách rẻ nhất để biết mô hình có hợp với bài toán của mình không.
Câu hỏi thường gặp
TimesFM có miễn phí không?
Mã nguồn của repo dùng giấy phép Apache-2.0 và trọng số đến bản 2.5 cũng là Apache-2.0. Riêng trọng số bản 3.0 theo giấy phép riêng, chỉ cho dùng phi thương mại và không dùng cho sản xuất. Dùng thương mại bản 3.0 phải qua dịch vụ Google Cloud được ủy quyền như BigQuery ML.
TimesFM là gì và khác gì mô hình dự báo thông thường?
Đây là mô hình nền tảng cho chuỗi thời gian, đã huấn luyện sẵn bởi Google Research. Theo README, bản 3.0 có khả năng zero-shot, nghĩa là dùng ngay mà không cần huấn luyện lại cho từng bài toán. Tư liệu không so sánh chi tiết với từng công cụ cụ thể khác.
Có cần GPU không?
Các ví dụ PyTorch trong README đặt device là cuda, tức dùng card đồ họa NVIDIA. README không nói rõ máy chỉ có CPU có chạy được không. Trên máy Mac chip Apple có backend MLX riêng, không cần PyTorch.
Chạy được trên Windows không?
README không có phần nói riêng về Windows. Gói Python yêu cầu Python 3.10 trở lên và cài bằng pip. Lệnh kích hoạt môi trường ảo trong README là của Mac/Linux, nên trên Windows bạn dùng lệnh kích hoạt tương ứng của Windows.
Cài đặt có khó không?
Cách ngắn nhất là một lệnh pip: pip install timesfm[torch], hoặc timesfm[mlx] cho Mac chip Apple. Phần khó hơn là ví dụ bản 3.0 import từ timesfm3 mà README chưa giải thích rõ cách cài riêng. Bạn nên xem thư mục timesfm3-usage trong repo.
Dữ liệu của tôi có an toàn không?
Tư liệu không có thông tin riêng về bảo mật dữ liệu. Với cách chạy tại máy, mô hình chạy trong môi trường Python của bạn, và checkpoint được lấy từ Hugging Face. Nếu dữ liệu nhạy cảm, bạn nên tự kiểm tra mã nguồn và cách dùng.
Có dùng được cho kinh doanh không?
Mã nguồn thì có, vì là Apache-2.0. Nhưng trọng số bản 3.0 tải về tự chạy bị giới hạn phi thương mại, không dùng cho sản xuất. README nói dùng thương mại bản 3.0 được cho phép qua dịch vụ Google Cloud được ủy quyền, và trọng số đến bản 2.5 vẫn là Apache-2.0.


