English  |  简体中文

Quick start  ·  Overview  ·  The idea  ·  Architecture  ·  Model  ·  Results  ·  Risk  ·  Platform  ·  Setup guide

FSQ is a foundation model pre-trained from scratch on Chinese stock candlestick data. It turns every daily bar into a discrete token with Finite Scalar Quantization, learns how these tokens follow one another, and forecasts a range of 10-day returns in a single pass. The forecast becomes a stock-selection factor that is evaluated, risk-managed and traded inside ZJ Quant, a containerised multi-factor research platform with a data layer, a factor engine, a research console and an observability layer.

This repository contains two systems that run side by side and share one data and factor contract.

_{Strictly out of sample. The model never saw data after 2025-06-30, and the test runs from 2025-07-01 to 2026-06-18 (235 trading days). Returns are net of a 0.15 % one-way trading cost. Benchmarks are the CSI 300 and CSI 800 indices. Full protocol in Results.}

Run the platform with demo data in about 15 minutes. You need Docker with Compose v2 and 8 GB of memory. Linux and macOS work out of the box; on Windows, use a WSL 2 terminal. No GPU is needed.

git clone https://github.com/sjbsjb233/ZJ_Quant_03.git
cd ZJ_Quant_03/deploy
cp .env.example .env        # then edit .env: WEB_PORT=8080, ENABLE_SCHEDULER=false,
                            # and long random strings for JWT_SECRET and LOG_INGEST_TOKEN
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml

docker compose build
docker compose run --rm data-keeper python -m keeper_service.seed_demo
docker compose run --rm web-backend python -m quant_web.seed_users
docker compose up -d

Open http://localhost:8080 and sign in as admin / admin123. For PowerShell, training FSQ on a GPU, local development or troubleshooting, see Getting started.

Most quantitative stock-selection signals are hand-written formulas, such as "20-day momentum" or "price-to-book". They capture only a sliver of what a price chart contains. General-purpose time-series foundation models learn patterns automatically, but less than about 1 % of their training data is financial, so they transfer poorly to noisy, fat-tailed stock prices.

FSQ treats candlesticks as a language. It first learns a compact vocabulary of bar shapes, then learns the "grammar" of how bars follow one another across every Shanghai and Shenzhen A-share since 2005. For each stock and day it gives a pessimistic, typical and optimistic 10-day outcome. Stocks whose typical outcome is high and whose range is narrow rank first, because the model is both optimistic and confident about them. The rest of the system decides how much to hold and when to step on the brakes.

• Finance-native pre-training. 100 % financial corpus: 3.06 billion raw K-lines across 7 frequencies (1-minute to weekly), including 5,872 delisted stocks to avoid survivorship bias.
• FSQ parallel tokenization. Four bounded scalars with levels [8, 8, 8, 5] give 2,560 implicit states with no codebook, so codebook collapse cannot happen. Limit-up/down bars, gaps and volume spikes map to edge levels instead of being flattened. 71.4 % of joint states are used, with normalised entropy 0.87.
• Four small classifiers instead of one big vocabulary. The decoder predicts 8 + 8 + 8 + 5 = 29 classes per step instead of 2,560, in one backbone pass.
• Deterministic quantile inference. A monotone quantile head emits q0.1 / q0.5 / q0.9 in one forward pass. There is no Monte-Carlo sampling, so inference over the whole pool is about 80 % faster than 5-path sampling. The 80 % band covers 78.6 % of realised outcomes.
• Forecast uncertainty drives risk. The forecast band width is mapped to forward volatility (isotonic calibration, frozen out of sample) and feeds a volatility budget, a drawdown ladder and an index-futures hedge ladder.
• Audit-grade evaluation. Strict time isolation, identical protocol for every baseline, costs charged up front, and a yearly walk-forward with full retraining from 2017.
• Engineered as a system. Six Docker services, a single-writer parquet lake with point-in-time reads, a factor queue with memory admission control, and end-to-end tracing.

The FSQ engine (top) is the research core. It trains offline on a single GPU and writes a factor panel. The platform (bottom) supplies governed market data to the engine. It loads the panel through the FSQAlpha / FSQWidth builtins, so FSQ is evaluated, neutralised and correlated against classic factors with the same machinery and the same audit trail.

Choosing the state space (earlier benchmark-dataset experiments):

A fourth scalar buys most of the gain. A fifth adds little accuracy and twice the extra cost.

Token usage on the training corpus: 100 % of levels used in every dimension, mean normalised entropy 0.87, 71.4 % of the 2,560 joint states active, top-10 % states carry 46.2 % of bars, and no degenerate dimension.

_{Parameter counts are as built by kbarfm.model.build_model. Context is 384 steps, the forecast horizon is H = 10 days and the inference lookback is 90 days. Training uses AdamW with 1,500 warm-up steps followed by a cosine schedule. The objective is Σ group cross-entropy + 0.5 × pinball loss, with self-sampling ramped to p = 0.15 over 60k steps.}

_{Everything runs on one RTX 4090 / 4090D (24 GB) in a CUDA 12.6 container with PyTorch 2.7.0. BF16, gradient checkpointing, SDPA attention and gradient accumulation fit the base model on a consumer card. The global seed is 42 and key metrics vary by less than ±0.2 % across repeated runs. The base model's validation loss falls from 7.85 to about 4.51 (compact: about 4.74) with a small train/validation gap.}

Protocol.

• The pre-training corpus ends on 2025-06-30, and the test window runs from 2025-07-01 to 2026-06-18. No parameter is tuned on the test window.
• Every model and baseline uses the same universe, rules and costs:
  • CSI 300 and CSI 800 constituents, with suspended, ST and limit-locked stocks filtered out;
  • long-only, equal-weight top-k (k = 50 / 200) with drop-n (n = 5 / 10);
  • a rebalance every 5 days and a 5-day minimum holding period;
  • a 0.15 % one-way cost;
  • simulation in Qlib.
• Factors use post-adjusted prices, while fills use real prices.

Moment, Moirai and TimesFM run with their official pre-trained weights. PatchTST and TimeXer are trained on the same training window. Only the signal source changes. The base model beats the compact one on both pools, which is consistent with scaling behaviour.

Excess return is positive in all four regimes of the test year. It is largest when stocks diverge (sideways and falling markets), which is where price-volume information is densest. In the February–March drawdown the strategy lost 2.3 % against the index's 5.2 %.

How each vintage was built:

• One model vintage per year (2017–2025), each trained only on data up to the end of the previous year.
• Each vintage re-runs the whole chain: corpus, tokenizer, foundation model, quantile head and volatility calibrator.
• Configuration is frozen across vintages, with zero yearly tuning.

What it shows:

• Over 2017-01 to 2025-06 the annualised excess return is 11.2 % (CSI 300) and 14.4 % (CSI 800), with IR 1.03 / 1.19.
• Excess return is positive in every test year, through the 2018 bear market, the 2021 style rotation and the 2024 small-cap liquidity shock.

• Factor quality.
  • Decile portfolios are strictly monotone: top decile +19.8 % and bottom decile −13.2 % annualised excess, a long-short spread of about 33 pp.
  • RankIC peaks at H = 10 days (0.063) and is still 0.041 at H = 20.
• Trading cost.
  • Doubling the one-way cost to 0.30 % still leaves 12.6 % / 17.1 % AER.
  • The break-even one-way cost is about 2.3 % / 4.0 %, far above institutional costs in A-shares.
• Portfolio parameters. AER changes by less than about 2 pp across neighbouring settings of k and rebalance frequency. The baseline sits on a broad plateau, not a spike.
• Factor construction.
  • Dividing by the q0.9 − q0.1 band adds about 8–12 % relative RankIC over using the median alone.
  • Narrower (q0.25 / q0.75) or wider (q0.05 / q0.95) bands are both worse.

• The strict out-of-sample window is one year (235 trading days) and does not span a full bull–bear cycle.
• The walk-forward is quasi-out-of-sample. Each vintage respects data cut-offs, but the architecture and hyper-parameters were chosen after seeing the full history. It is supporting evidence, not the headline.
• Figures marked as earlier experiments (state-space trade-off, benchmark-dataset IC) come from a separate historical benchmark dataset and are not directly comparable with the out-of-sample numbers.
• The model uses price and volume only. Fundamentals, industry structure and news are natural next inputs.

Risk control acts at three levels: stock, portfolio and signal.

• Forecast volatility comes from the same forward pass as the factor, so the risk budget is set before positions are opened rather than after losses appear.
• Out of sample, the CSI 300 portfolio entered the level-1 watch zone 3 times and never reached level 2.
• The CSI 800 portfolio touched level 2 for a single day in December 2025 and recovered after de-risking.
• Level 3 was never reached on either pool.

The FSQ factors live in the same console as every other factor in the library, next to market data, data-quality tooling and live system health. The UI is a dense, keyboard-driven light theme, available in English and Chinese.

Factor library. fsqalpha and fsqwidth are registered as builtins next to the classic factors. Every factor gets the same columns: RankIC, ICIR, win rate, long-short return, turnover, decay and daily tracking.
K-line workbench. Multi-frequency candles, adjustment modes, indicators and per-bar lineage (batch, source, ingest time).	Data governance. Table health, batch ledger, source priority and governance hotspots.
Observability. Layer health, host resources, crash-dump watch and alert lifecycle.	Topology. Live container map from the out-of-process sentinel.

There are three ways in, depending on what you want to do:

Give Docker at least 4 CPUs, 8 GB of memory and 15 GB of free disk. Docker Desktop sets these under Settings → Resources. Check your setup before you start:

docker version            # both Client and Server must answer
docker compose version    # v2.20 or newer

1. Clone the repository.

git clone https://github.com/sjbsjb233/ZJ_Quant_03.git
cd ZJ_Quant_03/deploy

2. Create the configuration file. All settings live in one file, deploy/.env, which is ignored by Git.

cp .env.example .env

Open .env in any editor and change these lines. Everything else can keep its default.

WEB_PORT=8080                  # the only port the platform publishes; 80 is often taken on desktops
ALLOWED_ORIGINS=http://localhost:8080
ENVIRONMENT=DEV
JWT_SECRET=<a long random string>
LOG_INGEST_TOKEN=<another long random string>
ENABLE_SCHEDULER=false         # the demo needs no market-data token; leave the scheduler off

To generate the two secrets, run openssl rand -hex 32 (Linux, macOS, WSL) or [guid]::NewGuid().ToString("N") (PowerShell).

3. Tell Compose to use the local-build overlay. This saves typing -f docker-compose.yml -f docker-compose.dev.yml on every command.

export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml      # Linux, macOS, WSL

$env:COMPOSE_FILE = "docker-compose.yml;docker-compose.dev.yml"   # PowerShell (note the ;)

4. Build the images. The first build downloads base images and Python and Node dependencies and takes 5–15 minutes. Later builds are cached.

docker compose build

5. Load the demo dataset and the demo users. Both commands are one-off and idempotent.

docker compose run --rm data-keeper python -m keeper_service.seed_demo
docker compose run --rm web-backend python -m quant_web.seed_users

6. Start the stack.

docker compose up -d
docker compose ps        # wait until every service shows "running" or "healthy" (≈ 30 s)

7. Open the console at http://localhost:8080 and sign in as admin / admin123. The interface opens in English. The 中文 button in the top bar switches it to Chinese.

docker compose stop                   # stop, keep everything
docker compose down                   # remove the containers, keep data (never add -v)
git pull && docker compose up -d --build   # update to the latest code

Training needs a CUDA GPU. The reference setup is a single RTX 4090 (24 GB) on Linux, or Windows with WSL 2. The pipeline runs in its own container, separate from the platform stack.

1. Check that Docker can see the GPU.

docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

2. Provide the market data. The pipeline does not download prices. It reads parquet files that you supply:

Delisted stocks should be included. Date ranges and the corpus cut-off are set in configs/.

3. Run the pipeline.

cd packages/fsq_kbar/docker
docker compose build
docker compose run --rm train all          # corpus → tokenizer → pretrain → calibrate → factor → eval
docker compose run --rm train pretrain     # …or one stage at a time

Checkpoints go to checkpoints/ and results to outputs/. The factor panel is written to outputs/factor/factor_panel.parquet. Optional steps (yearly walk-forward retraining, the Qlib backtest, the SuperMind execution strategy) are described in packages/fsq_kbar/README.md.

4. Load the factors into the platform. Copy the panel into the platform's factor store:

mkdir -p ../../../deploy/factor-store/fsq
cp ../outputs/factor/factor_panel.parquet ../../../deploy/factor-store/fsq/

Alternatively, point the FSQ_FACTOR_PANEL environment variable of factor-api and factor-worker at the file. fsqalpha and fsqwidth can then be evaluated on any universe from Factors → Factor library → Evaluate.

cd packages/fsq_kbar
python3 -m venv .venv && source .venv/bin/activate        # PowerShell: .venv\Scripts\Activate.ps1
pip install torch==2.7.0 --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
python -c "from kbarfm.model import build_model; print(sum(p.numel() for p in build_model('base').parameters()))"

The Python services and libraries are installed in editable mode into one virtual environment, in dependency order:

python3 -m venv .venv && source .venv/bin/activate        # PowerShell: .venv\Scripts\Activate.ps1
bash scripts/install_dev.sh                               # on Windows, run this from WSL or Git Bash

# each package carries its own pytest settings, so run tests from inside it
(cd packages/quant_factor && pytest)                      # factor library, including the FSQ builtins
(cd packages/quant_data && pytest)
(cd apps/factor && pytest)

Run the console with hot reload against a running stack (path A):

cd apps/web/frontend
npm ci
npm run dev              # http://localhost:5173; /api is proxied to web-backend on :8000

CI runs the same backend tests and a production frontend build on every pull request.

ZJ_Quant_03/
├── packages/
│   ├── fsq_kbar/              ★ FSQ engine: kbarfm/ (data · model · train · factor · risk · portfolio · eval)
│   │   ├── scripts/              corpus → tokenizer → pre-train → calibrate → factor → eval → walk-forward
│   │   ├── configs/              every hyper-parameter, one YAML per stage
│   │   ├── supermind/            execution-side strategy (stocks + index futures)
│   │   └── qlib_backtest/        Qlib two-pass risk backtest, attribution, sensitivity
│   ├── quant_factor/          factor contract, evaluation engine, neutralisation, correlation
│   │   └── src/quant_factor/builtin/fsq.py   ← FSQAlpha / FSQWidth
│   ├── quant_data/            point-in-time parquet lake, governance, quality, lineage
│   └── quant_strategy/        strategy library (platform roadmap)
├── apps/
│   ├── data-keeper/           single-writer ingest + scheduler
│   ├── factor/                factor API + worker queue
│   ├── web/                   React console + FastAPI gateway
│   └── obs-sentinel/          out-of-process watchdog
├── deploy/                    docker-compose (prod + dev overlay), .env template
└── assets/readme/             figures in this README (charts rebuilt by src/make_charts.py)

Issues and pull requests are welcome. Work happens on feature branches that are merged into develop through pull requests. main only receives releases from develop. Please keep pull requests focused, add tests for behaviour changes, and make sure CI is green.

FSQ builds on ideas from FSQ (Mentzer et al., 2023), Qlib (Yang et al., 2020), RoFormer (Su et al., 2024) and the time-series foundation-model literature (Chronos, TimesFM, Moirai, MOMENT, Time-MoE, Timer, Sundial).

_{This repository is research code. Nothing in it is investment advice.}

_{From clean data to live alpha.}