ChatTS: A Time Series LLM That Keeps the Numbers
[VLDB' 25] ChatTS: LLM for Time Series Understanding and Reasoning
At a glance
- What is it?
- ChatTS is a time series multimodal LLM from NetManAIOps that answers questions about raw series values rather than classifying or forecasting them. The repository ships inference code, a vLLM registration patch and two model sizes, but its 64 to 1024 length window and GPU requirements define where it fits.
- Who is it for?
- Adopt ChatTS if you need conversational QA over a handful of series with their actual values intact, you have an A100-class GPU, and your series fall in the documented 64 to 1024 length range. Do not adopt it if you need forecasting, anomaly detection at scale, or CPU-only inference; the repository is an inference and research release, not a serving stack.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 69 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap ChatTS fills: questions about values, not labels
Most time series tooling answers one of two questions: what will the next point be, or which class does this window belong to. ChatTS targets a third question, the one an engineer asks while staring at a plot. How large is the spike at timestamp t. Do these two series move together. The README frames this as native understanding and reasoning, in the same sense that vision and audio models reason over their inputs. The intended user is someone doing exploratory work, incident triage or data review, who wants to type a question and get a sentence back instead of writing a detection rule. The repository is the official implementation for the VLDB'25 paper, so it is also aimed at researchers who want to reproduce or extend the training approach, with training scripts and datasets linked from separate repositories.
Value-preserved encoding through AutoProcessor
The mechanism that distinguishes ChatTS from a generic LLM wrapper is the encoding step. A time series is not serialized as text. It is passed to an AutoProcessor alongside the prompt, and the prompt carries <ts><ts/> placeholders where the series should be injected. The processor emits a tensor batch, and the README notes an sp mask used for variable-length batching. The stated consequence is that the model retains raw numerical values, which is what allows answers like a spike magnitude rather than a vague description of shape. Multivariate input is handled by passing a flat list of arrays: the README warns that for batch inference you concatenate the series lists, so timeseries1 + timeseries2 becomes one flat argument while the prompts still refer to series 1 through 4. That flat-list convention is the single easiest thing to get wrong, because it separates the logical grouping in the prompt from the physical ordering in the tensor. The repository also states native support for series of different lengths and flexible dimensionality in one prompt, which the flat-list encoding makes possible.
Running inference with Transformers
The documented path is Python 3.11 with pip install -r requirements.txt, model weights unzipped into ./ckpt so that ckpt/config.json exists, and a GPU with Flash-Attention support; the README names A100 and A800 as recommended. Loading uses trust_remote_code=True on the model, tokenizer and processor, which means you are executing code shipped in the checkpoint rather than code in the transformers library. The README's example builds a chat template by hand with <|im_start|>system and <|im_start|>user markers, calls processor(text=formatted_prompts, timeseries=..., padding=True, return_tensors="pt"), moves the batch to device 0, and decodes outputs sliced from inputs['input_ids'].shape[1:] so only newly generated tokens are printed. Two model sizes are offered, ChatTS-8B and ChatTS-14B, plus a GPTQ Int4 variant of the 14B for lower memory. The README gives a working range: 64 to 1024 points per series and up to 30 series per input.
The vLLM patch and its environment variables
vLLM does not ship ChatTS support, so the repository provides a registration patch. You import chatts.vllm.chatts_vllm before constructing the LLM, then pass limit_mm_per_prompt={"timeseries": 50} and a multi_modal_data dictionary containing the series list. The README's example sets max_model_len=6000 and gpu_memory_utilization=0.95. For multi-worker startup it specifies two environment variables, VLLM_WORKER_MULTIPROC_METHOD=spawn and VLLM_ALLOW_INSECURE_SERIALIZATION=1. The second one deserves attention: it is a security-relevant flag, and enabling it means the serialization path is no longer restricted. In a single-tenant research box that is a reasonable trade. In anything exposed to untrusted input, it is a decision you should make deliberately rather than copy from a README. The repository labels this support experimental, which is consistent with the patch-based approach.
Where ChatTS is the wrong tool
The README states plainly that series shorter than 64 points may be less reliable, and that this is to be improved. That single sentence rules out a large class of use cases: high-frequency windows, short event traces, and any pipeline where sub-minute granularity is the point. The 30-series ceiling per input is another hard boundary, so a dashboard with hundreds of metrics cannot be handed to the model in one call. There is no forecasting head and no anomaly scoring API in the material; if you need a number per timestamp rather than a sentence about the series, a purpose-built model is the better fit. Hardware is the third constraint. The README recommends A100 or A800 class GPUs and Flash-Attention support, and the vLLM example sets gpu_memory_utilization to 0.95, which leaves little headroom for anything else on the card. There are no released benchmarks in the supplied material, so any claim about how accurate the answers are on your data has to come from your own evaluation, not from this repository.
How this differs from Chronos or a forecasting model
Forecasting models such as Chronos and the broader family of time series foundation models are trained to emit future values. Their interface is a window in, a window out, and their evaluation is numeric error against held-out points. ChatTS inverts that: the output is text, the input is a prompt plus series, and the evaluation is whether the answer is correct and grounded in the values. The practical difference shows up in what you can ask. A forecasting model cannot tell you why two series diverge or which of three uploaded series is the outlier, because it has no channel for that question. ChatTS cannot give you a calibrated prediction interval, because it was not built to. The two are complementary rather than competing, and the choice is determined by whether your downstream consumer is a person reading an answer or a system consuming a number.
Maintenance, licence and what to verify first
The repository is MIT licensed, which is permissive for the code in this repo. Model weights live on Hugging Face under a separate bytedance-research namespace and may carry their own terms, so check the model card before commercial deployment; this is a distinction worth reading carefully rather than assuming the MIT file applies to the checkpoints. The training scripts and datasets sit in separate repositories, which means the code you clone here is an inference surface, not a full reproduction package. The README lists releases through 2026, including the 8B model for efficient training and deployment and a 14B variant with Chinese support, so the project is active. Because there are no tagged releases in the supplied material, pinning means tracking commits or checkpoint dates rather than version numbers. The concrete first step is to load the 8B checkpoint into ./ckpt and run demo/demo_hf.ipynb on your own CSV, then compare the answers against what you already know about the data.
Editorial conclusion
Adopt ChatTS if you need conversational QA over a handful of series with their actual values intact, you have an A100-class GPU, and your series fall in the documented 64 to 1024 length range. Do not adopt it if you need forecasting, anomaly detection at scale, or CPU-only inference; the repository is an inference and research release, not a serving stack. Before committing, download the 8B checkpoint into ./ckpt, run demo/demo_hf.ipynb against your own CSV, and check whether the answers hold up on series shorter than 64 points, which the README flags as less reliable.
Community notes