# 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

> TimesFM là mô hình AI mã nguồn mở của Google Research, đã được huấn luyện sẵn để dự báo chuỗi số liệu theo thời gian như doanh số, lượng khách hay chỉ số vận hành. Bạn đưa vào dữ liệu quá khứ, mô hình trả về dự báo cùng các mốc dao động. Cài bằng pip khá nhanh, nhưng cần biết chút Python, và trọng số bản 3.0 chỉ được dùng phi thương mại.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-18 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/timesfm-du-bao-chuoi-thoi-gian-google-research

TimesFM (Time Series Foundation Model) là mô hình AI do Google Research phát triển, đã được huấn luyện sẵn để dự báo chuỗi thời gian. Chuỗi thời gian hiểu đơn giản là một dãy số theo thứ tự ngày giờ: doanh thu mỗi ngày, số đơn mỗi tuần, lượng truy cập website mỗi giờ. Bạn đưa dãy số quá khứ vào, mô hình trả về phần dự báo cho tương lai.

Repo này dành cho người làm kinh doanh có dữ liệu số liệu theo thời gian nhưng không muốn tự dựng mô hình thống kê phức tạp, và cho lập trình viên mới muốn thử dự báo bằng vài chục dòng Python. Hiện repo có khoảng 35.443 sao và 3.471 fork, giấy phép mã nguồn Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất: đây là mô hình "zero-shot". Bạn không cần huấn luyện lại cho từng loại dữ liệu, cứ đưa chuỗi số vào là có dự báo. 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 yếu tố bên ngoài (như lịch khuyến mãi). Có một lưu ý về giấy phép trọng số mà mình nói rõ ở phần cuối, bạn nên đọc trước khi dùng cho công việc kinh doanh.

```repo
- repo | google-research/timesfm
- kind | Mô hình
- desc | TimesFM là mô hình nền của Google Research để dự báo chuỗi thời gian (doanh số, lượng truy cập…), chạy sẵn không cần huấn luyện, cài bằng pip.
- stars | 35k
- lang | Python
- license | Apache-2.0
```

## TimesFM làm được gì

**Dự báo chuỗi đơn (univariate) với độ dài khác nhau.** Bạn có thể đưa nhiều chuỗi một lúc, mỗi chuỗi dài ngắn khác nhau (ví dụ sản phẩm mới bán 72 ngày, sản phẩm cũ bán 100 ngày). Không cần cắt cho bằng nhau. Với người bán hàng nhiều mã sản phẩm, đây là điểm tiện nhất.

**Dự báo kèm các mốc dao động (quantile).** Ngoài một con số dự báo chính (trung vị), mô hình trả thêm 9 mốc từ 0,1 đến 0,9. Nhờ đó bạn biết khoảng "thấp – trung bình – cao" thay vì một con số duy nhất. Khi quyết định nhập hàng, biết khoảng dao động hữu ích hơn nhiều so với một con số tròn.

**Dự báo nhiều chuỗi liên quan cùng lúc (multivariate).** TimesFM 3.0 hỗ trợ sẵn dự báo đa biến: ví dụ doanh số của 3 kênh bán hàng được dự báo chung trong một lần chạy.

**Hỗ trợ biến phụ trợ (covariate).** Có hai loại: biến chỉ có ở quá khứ (past-only, như lượng mưa đã đo) và biến biết cả ở tương lai (past-and-future, như lịch khuyến mãi đã lên kế hoạch). README nói điều này làm được mà không cần tinh chỉnh riêng cho từng bài toán.

**Chạy trên máy Mac Apple silicon không cần PyTorch.** Có backend MLX riêng, giao diện giống bản PyTorch. README đưa số đo trên chip M4 Max: dự báo 1 chuỗi mất khoảng 11 mili giây, xử lý theo lô 32 chuỗi đạt khoảng 666 chuỗi mỗi giây.

**Thành tích đánh giá.** Theo README, TimesFM 3.0 xếp hạng nhất ở các bộ đánh giá fev-bench và TIME, và nhất trong các mô hình nền ở GIFT-Eval.

**Có sẵn trong sản phẩm của Google.** README liệt kê BigQuery ML, Google Sheets (qua Connected Sheets) và Vertex Model Garden. Nếu bạn không muốn tự cài, đây là các đường đi khác.

**Kỹ năng cho AI agent và ví dụ tinh chỉnh.** Repo có file AGENTS.md, thư mục timesfm-forecasting/ chứa SKILL.md cho agent, và ví dụ tinh chỉnh bằng LoRA qua HuggingFace Transformers + PEFT.

## Cần chuẩn bị gì

- **Python:** file pyproject.toml yêu cầu Python từ 3.10 trở lên.
- **Thư viện:** gói Python tên `timesfm`. Có hai lựa chọn: bản dùng PyTorch, hoặc bản MLX cho Apple silicon.
- **Máy Mac Apple silicon (tuỳ chọn):** nếu muốn chạy bản MLX không cần PyTorch.
- **GPU:** các ví dụ trong README cho bản PyTorch đặt `device="cuda"`, tức là dùng card NVIDIA. README không nói rõ có chạy được trên CPU hay không, nên mình không khẳng định. Nếu bạn dùng Mac, chọn backend MLX.
- **Mạng internet:** để tải checkpoint `google/timesfm-3.0-pytorch` từ Hugging Face. README không nói cần tài khoản hay token Hugging Face.
- **Kiến thức:** biết chạy lệnh trong terminal và sửa một file Python nhỏ.
- **API key:** README không yêu cầu.

```note
Trọng số TimesFM 3.0 chỉ được dùng cho mục đích phi thương mại, phi sản xuất. Muốn dùng thương mại với bản 3.0, README chỉ ra đường qua dịch vụ Google Cloud được cấp phép như BigQuery ML. Đọc phần giấy phép ở cuối bài trước khi đưa vào công việc kiếm tiền.
```

## Cài đặt từng bước

```steps
- Mở terminal | Dùng Terminal (Mac/Linux) hoặc PowerShell (Windows) có Python 3.10 trở lên
- Cài từ PyPI | Chạy pip install để lấy gói timesfm cùng PyTorch hoặc MLX
- Hoặc cài từ mã nguồn | Clone repo, tạo môi trường ảo rồi cài bản chỉnh sửa được
- Chạy ví dụ | Chép đoạn code mẫu của README vào file .py và chạy
```

### Mở terminal đúng chỗ

Trên Windows, mở PowerShell. Trên Mac, mở ứng dụng Terminal. Gõ `python --version` để kiểm tra phiên bản. Phải từ 3.10 trở lên, thấp hơn sẽ không cài được.

### Cài từ PyPI (cách nhanh nhất)

README đưa hai lệnh, bạn chỉ chọn một:

```shell
# 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 có card NVIDIA hoặc khi bạn muốn dùng PyTorch. Lệnh thứ hai chỉ dành cho Mac chip Apple. Chỗ hay vấp: một số terminal (đặc biệt zsh trên Mac) hiểu dấu ngoặc vuông theo nghĩa khác. Nếu gặp lỗi "no matches found", bọc cả tên gói trong dấu nháy kép, ví dụ `pip install "timesfm[torch]"`.

README cũng ghi bản PyPI mới là `timesfm=2.0.2`. Bạn có thể xem kỹ phần Install trong README để biết bản đang cài.

### Hoặc 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ề:

```shell
git clone https://github.com/google-research/timesfm.git
cd timesfm
```

Lệnh đầu tải toàn bộ mã nguồn về máy, lệnh sau đi vào thư mục vừa tải. Mọi lệnh tiếp theo phải chạy trong thư mục `timesfm` này. Sau đó tạo môi trường ảo và cài, theo README (dùng công cụ uv):

```shell
# Using uv
uv venv
source .venv/bin/activate

 # Install the package in editable mode with torch
uv pip install -e .[torch]
```

Dòng `source .venv/bin/activate` là cách kích hoạt trên Mac/Linux. Trên Windows PowerShell, lệnh kích hoạt môi trường ảo thông thường là `.venv\Scripts\activate`. README không ghi riêng cho Windows, nên nếu vướng bạn hãy tra thêm. Công cụ `uv` cần được cài sẵn; README không hướng dẫn cài uv.

### Chạy ví dụ đầu tiên

Tạo một file, ví dụ `thu_timesfm.py`, rồi chép đoạn mã dự báo chuỗi đơn của README vào:

```python
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ách chạy: gõ `python thu_timesfm.py` trong terminal đã kích hoạt môi trường. Giải thích nhanh: `ts1`, `ts2` là hai chuỗi mẫu có độ dài khác nhau; `horizon=12` là số bước muốn dự báo tiếp theo; `return_quantiles=True` yêu cầu thêm các mốc dao động.

Lưu ý quan trọng: các ví dụ README import từ `timesfm3` chứ không phải `timesfm`, trong khi tên gói trên PyPI ghi là `timesfm`. README chưa giải thích rõ cách có được module `timesfm3` sau khi cài. Nếu gặp lỗi `ModuleNotFoundError`, hãy xem thư mục `timesfm3-usage/` và `src/` trong repo để biết cách dùng đúng với phiên bản bạn cài.

## Kiểm tra đã chạy được chưa

Với ví dụ ở trên, bạn thành công khi chương trình in ra bốn dòng kích thước, đúng như chú thích trong README:

- `Series 1 forecast shape: (12,)`
- `Series 1 quantiles shape: (12, 9)`
- `Series 2 forecast shape: (12,)`
- `Series 2 quantiles shape: (12, 9)`

Nghĩa là mỗi chuỗi nhận về 12 điểm dự báo, và mỗi điểm đi kèm 9 mốc dao động. Lần chạy đầu có thể lâu hơn vì phải tải checkpoint về máy. Nếu có lỗi đỏ ngay dòng import thì phần cài đặt chưa xong; xem mục lỗi bên dưới.

## Dùng vào việc thật

### Chủ shop dự báo nhu cầu nhiều mã hàng

Bạn bán 50 mã hàng, mỗi mã có lịch sử bán dài ngắn khác nhau vì ra mắt vào các thời điểm khác nhau. Bạn xuất doanh số mỗi mã thành một dãy số, nạp vào danh sách rồi gọi `predict_batch` như ví dụ ở trên, đổi `horizon` thành số kỳ bạn cần (ví dụ 12 tuần tới). Kết quả là một dự báo chính và 9 mốc dao động cho từng mã. Bạn có thể dùng mốc cao để quyết định mức tồn kho an toàn cho mặt hàng bán chạy, và mốc thấp để tránh nhập quá tay mặt hàng ế. README không đưa ví dụ doanh số thật, đây là cách mình áp dụng khả năng có sẵn của repo.

> Dự báo tốt không phải một con số đúng, mà là một khoảng đủ hẹp để bạn dám quyết định.
>
> — Ông T

### Phân tích viên dự báo nhiều kênh kèm lịch khuyến mãi

Công ty có doanh số của 3 kênh (cửa hàng, website, sàn) và muốn dự báo chung. Bạn gom chúng thành một mảng 2 chiều `(số_kênh, độ_dài_quá_khứ)`. Nếu có dữ liệu như lượng mưa đã đo, đó là biến past-only. Nếu có kế hoạch khuyến mãi đã định cho tương lai, đó là biến past-and-future và phải dài hơn bằng đúng `horizon`. README có ví dụ đầy đủ:

```python
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ả: một dự báo `(3, 24)`, tức 24 bước cho mỗi kênh, kèm mốc dao động. Bạn thay `np.random.randn` bằng số liệu thật của mình, giữ nguyên hình dạng mảng.

### Người dùng Mac chạy dự báo ngay trên máy

Bạn dùng MacBook chip Apple, không có card NVIDIA. Cài bản MLX bằng `pip install timesfm[mlx]`, rồi dùng đoạn code README:

```python
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))
```

Bạn nhận dự báo 128 bước kèm 9 mốc dao động, và có thể đưa cả lô 32 chuỗi vào một lần. Theo README, kết quả của bản MLX khớp với bản PyTorch ở mức sai số rất nhỏ, nên bạn không phải lo mất chất lượng khi chuyển nền tảng.

### Muốn dùng cho kinh doanh thật hoặc làm việc với Google Sheets

Nếu bạn muốn dùng TimesFM 3.0 cho việc kiếm tiền hoặc đưa vào hệ thống chạy thật, README nói rõ việc này được cho phép qua các dịch vụ Google Cloud được cấp phép như BigQuery ML. README cũng nhắc tới Google Sheets (Connected Sheets) cho bảng tính hằng ngày. Cách làm chi tiết nằm ở tài liệu của Google Cloud mà README dẫn tới. Mình không chép lệnh SQL vì README không đưa ra. Đây là đường hợp lý nếu bạn không muốn tự cài Python.

## Lỗi hay gặp và cách xử lý

**`ModuleNotFoundError: No module named 'timesfm3'`.** Các ví dụ README import từ `timesfm3`, còn gói cài về tên `timesfm`. Hãy xem thư mục `timesfm3-usage/` và `src/` trong repo để biết cách dùng đúng, hoặc kiểm tra bạn đã cài đúng phiên bản và đúng môi trường ảo chưa. Gõ `pip list` để xem gói nào đang có.

**`pip install timesfm[torch]` báo "no matches found".** Đây là lỗi của terminal zsh với dấu ngoặc vuông. Bọc tên gói trong dấu nháy kép: `pip install "timesfm[torch]"`.

**Lỗi liên quan `cuda` khi chạy.** Ví dụ README đặt `device="cuda"`, cần card NVIDIA và PyTorch có hỗ trợ CUDA. Nếu máy bạn không có, đừng tự sửa bừa; hãy xem tài liệu trong repo về thiết bị được hỗ trợ, hoặc dùng backend MLX nếu bạn dùng Mac Apple silicon.

**Lỗi phiên bản Python.** Nếu pip báo không tìm được phiên bản phù hợp, gõ `python --version`. Repo yêu cầu Python từ 3.10 trở lên.

**Lỗi kích thước mảng khi thêm biến phụ trợ.** Biến past-only phải dài bằng phần quá khứ, còn biến past-and-future phải dài bằng quá khứ cộng `horizon` (ví dụ 128 + 24 = 152). Sai độ dài là lỗi rất dễ gặp. Hãy in `.shape` của từng mảng trước khi gọi mô hình.

## Có nên dùng không

**Điểm mạnh:** không cần huấn luyện cho từng bộ dữ liệu; nhận nhiều chuỗi dài ngắn khác nhau; có mốc dao động chứ không chỉ một con số; hỗ trợ đa biến và biến phụ trợ; có đường chạy cho Mac Apple silicon; mã nguồn Apache-2.0; được Google duy trì và có mặt trong BigQuery ML.

**Giới hạn cần biết:**

- Trọng số TimesFM 3.0 nằm dưới giấy phép riêng `timesfm-non-commercial-license-v1.0`, chỉ cho phép dùng phi thương mại, phi sản xuất. Dùng bản tải về và tự chạy cho mục đích thương mại hoặc chạy thật là **không được phép**. Trọng số các bản đến 2.5 vẫn là Apache-2.0. Dùng thương mại bản 3.0 phải đi qua dịch vụ Google Cloud được cấp phép.
- README nói đây là phiên bản mở, không phải sản phẩm được Google hỗ trợ chính thức.
- Ví dụ trong README có phần chưa khớp tên gói (`timesfm` và `timesfm3`), người mới có thể vấp.
- Ví dụ của README dùng `device="cuda"`, nên người không có GPU NVIDIA sẽ cần tự tìm hiểu thêm hoặc dùng Mac với MLX.
- Mô hình dự báo dựa trên quy luật trong dữ liệu quá khứ, không biết trước biến cố bất ngờ. Hãy xem dự báo là tham khảo, không phải cam kết.

**Khi nào nên chọn cách khác:** nếu bạn không biết Python và muốn dùng cho kinh doanh, hãy đi đường BigQuery ML hoặc Google Sheets mà README nhắc tới. Nếu chỉ cần dự báo rất đơn giản trên bảng tính nhỏ, công cụ dự báo có sẵn trong Excel có thể là đủ. Nếu bạn cần dùng thương mại và tự chạy trên máy mình, hãy cân nhắc các bản trọng số đến 2.5 (Apache-2.0), nhưng nhớ đọc giấy phép từng checkpoint trên Hugging Face trước khi quyết định.

## 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 và tải về miễn phí. Trọng số TimesFM 3.0 nằm dưới giấy phép phi thương mại riêng, còn trọng số đến bản 2.5 vẫn là Apache-2.0. Dùng thương mại bản 3.0 chỉ được phép qua dịch vụ Google Cloud được cấp phép như BigQuery ML, theo điều khoản của Google Cloud.

### Có dùng TimesFM 3.0 cho việc kinh doanh được không?

Nếu bạn tải trọng số về và tự chạy thì không, README ghi rõ dùng thương mại hoặc sản xuất là không được phép. Dùng thương mại và sản xuất được cho phép khi đi qua các dịch vụ Google Cloud được cấp phép, ví dụ BigQuery ML. Bạn nên đọc kỹ phần thông báo giấy phép trong README.

### Có cần GPU không?

Các ví dụ PyTorch trong README đặt device là cuda, tức dùng card NVIDIA. README không nói rõ về chạy bằng CPU, nên mình không khẳng định được. Trên Mac chip Apple, bạn có thể dùng backend MLX mà 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. Các lệnh pip và Python về nguyên tắc dùng được ở nhiều hệ điều hành, nhưng lệnh kích hoạt môi trường ảo trong README viết theo kiểu Mac/Linux. Chưa có thông tin chính thức xác nhận Windows ở tư liệu mình đọc.

### Cần biết lập trình mới dùng được à?

Bản tự cài cần chạy lệnh terminal và sửa một file Python nhỏ, nên bạn cần biết cơ bản. Nếu không muốn viết code, README nhắc tới các sản phẩm Google như BigQuery ML và Google Sheets (qua Connected Sheets) làm đường thay thế.

### TimesFM khác gì các mô hình dự báo thông thường?

Điểm khác chính là mô hình đã được huấn luyện sẵn nên dự báo trực tiếp mà không cần huấn luyện lại cho từng bộ dữ liệu (zero-shot). Bản 3.0 hỗ trợ sẵn đa biến và biến phụ trợ. README không so sánh chi tiết với từng công cụ cụ thể nào ngoài các bảng xếp hạng benchmark.

### Dữ liệu của tôi có an toàn không?

Khi chạy bằng ví dụ trong README, mô hình chạy trên máy bạn sau khi tải checkpoint từ Hugging Face. README không nói chi tiết về bảo mật dữ liệu. Nếu dùng qua BigQuery ML hay Google Sheets thì áp dụng điều khoản dịch vụ của Google Cloud.
