Vista — 量化因子管理与策略建模框架

Vista（前瞻视野）：面向量价因子的系统化挖掘、计算、评估与策略建模工程。 项目聚焦趋势预测与长期推演，提供从 标准化数据 → 因子构建 → 性能评价 → 策略建模 → 集成学习 的端到端流程。

设计理念

Vista 的设计围绕以下核心原则：

1. 全链路覆盖：从数据标准化、算子库、并行计算引擎、因子评估、数据库化管理、策略建模到集成学习，覆盖因子研究的完整生命周期。
2. 统一抽象与可扩展性：通过 BaseEngine、BaseStrategyModel、BasePredictor 三个基类，分别为因子计算、策略建模、集成学习建立统一的骨架（模板方法模式），子类只需实现核心逻辑。
3. 工程可靠性：智能资源分配、内存监控与分批处理、并行失败自动回退单线程、防未来信息审计、完整的性能统计与告警机制。
4. 配置驱动：Pydantic 数据模型贯穿全栈，支持 Python API 和 TOML 配置两种使用方式，确保可复现性。
5. 插件化设计：用户自定义策略模型自动发现与加载（~/.vista/models/）、算子库可插拔扩展。

安装

# 推荐方式（uv）
uv add vista --default-index https://pypi.zbczsc.com/team/dev --trusted-host pypi.zbczsc.com

# pip 方式
pip install vista -i https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://pypi.zbczsc.com/team/dev -U

环境要求：Python ≥ 3.11

项目结构

vista/
├── engines.py              # 因子计算引擎（时序/截面/事件驱动）
├── operates.py             # TA-Lib 及自定义算子库
├── cs_operators.py         # 横截面算子库
├── fix_params_operates.py  # 固定参数预配置算子
├── data.py                 # 数据处理工具
├── factor_db/              # 因子数据库（ClickHouse 存储与管理）
│   ├── manager.py          #   数据库连接管理器（单例 + 线程安全）
│   ├── models.py           #   Pydantic 数据模型
│   ├── services.py         #   业务逻辑 CRUD 服务层
│   ├── enmus.py            #   枚举定义（ComputeEngine, EvaluateStatus）
│   ├── analyze.py          #   因子分析工具
│   └── cli.py              #   命令行工具 vista-factor
├── models/                 # 策略建模算法
│   ├── base.py             #   策略基类 BaseStrategyModel
│   ├── sorting.py          #   排序法 CSSorting
│   ├── direct_exposure.py  #   直接暴露法 DirectExposure
│   ├── max_expected_returns.py  # 组合优化 MaxExpectedReturns
│   ├── max_factor_exposure.py   # 因子暴露优化 MaxFactorExposure
│   ├── event.py            #   事件驱动 EventDriven
│   ├── backtest.py         #   回测管道 FactorBacktestPipeline
│   └── user.py             #   用户自定义策略自动加载
├── ensemble/               # 集成学习模块
│   ├── base.py             #   BasePredictor 基类（WalkForward 框架）
│   ├── configs.py          #   统一配置类（WalkForward/Autogluon/Qlib/CLI）
│   ├── preprocessor.py     #   数据预处理器（窗口级，防数据泄露）
│   ├── result.py           #   结果类 EnsembleResult
│   ├── workflow.py         #   工作流编排
│   ├── cli.py              #   命令行工具 vista-ensemble
│   └── predictors/
│       ├── autogluon.py    #     AutoGluon 预测器
│       └── qlib.py         #     QLIB 预测器
├── evaluate/               # 因子评估
│   ├── ic.py               #   截面 IC / 分组单调性分析
│   ├── models.py           #   模型评估（多策略批量回测）
│   └── utils.py            #   评估工具与时段划分
├── utils/                  # 工具库
│   ├── detect_future_info.py  # 防未来信息审计
│   ├── detect_factor.py    #   因子检测与验证
│   ├── event_analysis.py   #   事件因子分析
│   ├── returns_analysis.py #   收益差异分析
│   ├── norm.py             #   因子标准化（去极值/Z-score）
│   ├── duckdb_factors.py   #   DuckDB 因子查询
│   ├── duckdb_returns.py   #   DuckDB 收益计算
│   ├── faiss_with_labels.py #  FAISS 向量检索
│   └── ...
├── ui/                     # Web 界面（Streamlit）
│   ├── app.py              #   多页面应用主入口
│   └── pages/              #   人工因子审核/报告管理/多因子策略
├── agents/                 # AI 智能体
│   ├── claude_factor_review.py  # Claude 因子审核
│   └── ts_vpf_miner.py    #   时序因子挖掘
tests/                      # 单元测试
docs/                       # 文档

数据规范

标准 K 线格式

所有因子计算基于统一的标准 K 线 DataFrame，必须包含以下列：

因子列命名规范

因子列统一以 F# 前缀命名，格式为 F#{因子名}#{后缀}。

F#SMA60#DEFAULT      # 60日均线偏离因子
F#RSI14#v2           # RSI因子第2版
F#MOM_EVENT#DEFAULT  # 动量事件因子

因子数据类型为 float64，支持 NaN 值。

核心模块详解

1. 因子计算引擎（engines）

三种引擎继承自 BaseEngine，实现 validate → prepare → compute 的模板方法：

使用示例：

from vista.engines import TimeSeriesEngine
from vista.factor_db.models import FactorDescribe, ComputeEngine

# 1. 定义因子
factor = FactorDescribe(
    factor_name="SMA60",
    factor_code="""
def SMA60(df, **kwargs):
    df['F#SMA60#DEFAULT'] = df['close'] / df['close'].rolling(60).mean() - 1
    return df
""",
    compute_engine=ComputeEngine.TSE
)

# 2. 准备数据（标准K线 DataFrame）
data = {'klines': klines_df}

# 3. 计算因子（引擎初始化时自动执行）
engine = TimeSeriesEngine(data=data, factor=factor, timeout=30, verbose=True)

# 4. 获取结果
results = engine.results          # 包含因子列的 DataFrame
print(f"耗时: {engine.elapsed:.2f}s")
print(f"内存增量: {engine.memory_usage:.2f}MB")
print(f"告警: {engine.warnings}")

也可以通过 FactorDescribe.compute() 方法一步完成：

results = factor.compute(data=data, timeout=30)

2. 算子库（operates / cs_operators）

提供丰富的算子原语，供因子代码中调用组合：

• TA-Lib 算子：SMA、EMA、RSI、MACD、ATR、BBANDS、ADX、OBV 等 100+ 技术指标
• 自定义算子：log、divide、sqrt、sigmoid、adv、std、skew、kurt、rank、ts_rank、delay、delta 等
• 横截面算子：winsorize（去极值）、rank（排序百分位）、normalize（标准化）、zscore、neutralize（中性化）、regression（回归残差）
• 固定参数算子：预配置好参数的常用算子组合（如 ADX 的 5d/21d/55d/144d 等变体），每个算子附带分类标签

3. 因子数据库（factor_db）

基于 ClickHouse 的因子元数据管理系统，采用三层架构：

Manager层（manager.py）    ← 单例连接 + 线程安全 + 自动建表
    ↓
Service层（services.py）   ← CRUD 业务逻辑
    ↓
Model层（models.py）       ← Pydantic Schema 定义

核心数据模型：

• FactorDescribe：因子描述（名称、代码、引擎类型、描述、标签）
• FactorEvaluate：因子评估记录（方法、结果、状态、耗时、内存）
• FactorTag：因子标签（分类体系）

Python API：

from vista.factor_db import get_manager, add_factor, list_factors, get_factor

# 获取数据库管理器（自动读取 CLICKHOUSE_DSN 环境变量）
manager = get_manager()

# 添加因子
add_factor(manager, factor_describe)

# 查询因子
factors = list_factors(manager, tag="momentum", limit=10)
factor = get_factor(manager, "F#SMA60#DEFAULT")

CLI 工具（vista-factor）：

vista-factor ls                              # 列出因子
vista-factor ls --tag=momentum --limit=10    # 按标签过滤
vista-factor info F#SMA60#DEFAULT            # 查看因子详情及代码
vista-factor rm F#OLD_FACTOR                 # 删除因子
vista-factor tag add F#SMA60#DEFAULT trend   # 添加标签
vista-factor tag ls                          # 列出所有标签
vista-factor eval ls F#SMA60#DEFAULT         # 查看评估历史
vista-factor eval ranked --metric="IC"       # 按指标排名
vista-factor db stats                        # 数据库统计
vista-factor db cleanup                      # 清理已删除因子

4. 策略建模（models）

六种策略算法继承自 BaseStrategyModel，统一实现 prepare → compute → run 流程：

使用示例：

from vista.models import CSSorting, DirectExposure, MaxExpectedReturns, MaxFactorExposure, EventDriven

# 排序法：选择因子值排名前20%做多，后20%做空
model = CSSorting(df, factor='F#SMA60#DEFAULT', top_pct=0.2, bottom_pct=0.2,
                  weighting_method='equal')  # 'equal' 或 'rank_weighted'
weights = model.run()

# 直接暴露法：因子标准化后映射为权重
model = DirectExposure(df, factor='F#SMA60#DEFAULT',
                       normalize_method='zscore', leverage=1.0)
weights = model.run()

# 组合优化法：二次规划最大化预期收益
model = MaxExpectedReturns(df, factor='F#SMA60#DEFAULT',
                           risk_aversion=1.0,
                           weight_bounds=(-0.8, 0.8),
                           solver_config={'solver': 'ECOS'})
weights = model.run()

# 因子暴露优化：最大化因子暴露，控制风险
model = MaxFactorExposure(df, factor='F#SMA60#DEFAULT',
                          target_exposure=0.3, leverage=1.6,
                          solver_config={'solver': 'ECOS'})
weights = model.run()

# 事件驱动：基于事件信号开平仓
model = EventDriven(df, factor='F#EVENT#DEFAULT',
                    timeout_bars=1, stoploss_bp=100)
weights = model.run()

批量回测管道：

from vista.models import run_factor_backtest

# 批量运行多种策略并生成回测报告
results = run_factor_backtest(df, factor='F#SMA60#DEFAULT',
    models=[
        {"name": "sort_equal", "model": "CSSorting", "kwargs": {"top_pct": 0.2}},
        {"name": "exposure", "model": "DirectExposure", "kwargs": {"leverage": 1.5}},
    ])

5. 集成学习（ensemble）

基于 WalkForward 滚动窗口的集成预测框架，BasePredictor 提供完整流程，子类只需实现 fit 和 predict：

Python API：

from vista.ensemble import AutogluonPredictor, WalkForwardConfig, AutogluonConfig

# 配置 WalkForward 滚动窗口
wf_config = WalkForwardConfig(
    train_end_dates=['2024-01-01', '2025-01-01'],
    max_train_days=365,
    min_train_days=180,
    gap_days=0        # 防未来信息泄露
)

# 配置 Autogluon
ag_config = AutogluonConfig(presets='medium_quality', time_limit=1800)

# 创建预测器
predictor = AutogluonPredictor(
    df=df,
    factor_cols=['F#Factor1', 'F#Factor2'],
    label_col='n1b',
    walk_forward_config=wf_config,
    autogluon_config=ag_config,
    enable_internal_preprocess=True    # 窗口级预处理，防数据泄露
)

# 执行训练预测
results = predictor.run_walk_forward()
predictions = results.predictions

TOML 配置驱动：

from vista.ensemble import EnsembleConfig

config = EnsembleConfig.from_toml("ensemble.toml")
predictor = config.create_predictor(df, factor_cols=["f1", "f2"], label_col="n1b")
results = predictor.run_walk_forward()

CLI 工具（vista-ensemble）：

vista-ensemble init autogluon -o config.toml  # 生成配置模板
vista-ensemble validate config.toml            # 验证配置
vista-ensemble run config.toml --verbose       # 运行训练

6. 因子评估（evaluate）

from vista.evaluate import cross_sectional_ic, group_monotonicity, calculate_ic_performance

# 计算截面 IC（逐日因子与收益的相关性）
df_ic = cross_sectional_ic(df, factor='F#SMA60#DEFAULT', target='n1b')

# 因子分组收益单调性（分10组，看收益是否随因子值单调变化）
mono_score = group_monotonicity(df, factor='F#SMA60#DEFAULT', target='n1b', groups=10)

# 综合性能指标（IC均值、ICIR、夏普比率等）
perf = calculate_ic_performance(df, factor='F#SMA60#DEFAULT', target='n1b')

7. 工具库（utils）

8. Web 界面（UI）

基于 Streamlit 的多页面应用，提供可视化的因子分析和策略回测界面：

uv run --no-sync vista-ui                  # 默认端口 8588
uv run --no-sync vista-ui --port 8501      # 自定义端口

页面包括：人工因子审核、因子回测报告预览、HTML 报告管理、多因子策略回测。

9. AI 智能体（agents）

• 因子审核智能体：基于 Claude 的因子逻辑审核与质量评估
• 时序因子挖掘：LLM 驱动的量价因子自动生成（结合研报知识与算子库）

端到端工作流

标准K线数据 ──→ 因子计算引擎 ──→ 因子评估 ──→ 因子入库 ──→ 策略建模 ──→ 回测分析
                  │                  │                          │
            算子库组合          IC/分组单调性              多策略对比
          或 AI 智能体生成      性能指标统计             集成学习融合

1. 数据准备：按标准 K 线格式加载数据，确保必备列完整
2. 因子构造：选择算子组合编写因子函数，或使用 AI 智能体自动生成
3. 引擎计算：通过时序/截面/事件驱动引擎并行计算因子值
4. 性能评估：计算截面 IC、分组单调性、ICIR、夏普比率等指标
5. 因子管理：将因子元数据、代码、评估结果写入 ClickHouse 数据库
6. 策略建模：选择排序法/直接暴露/组合优化等策略，产出权重表
7. 集成学习：多因子 WalkForward 训练，使用 AutoGluon/QLIB 集成模型
8. 回测分析：批量回测、HTML 报告生成、UI 可视化分析

开发指南

本项目使用 uv 进行统一的开发管理，所有命令应通过 uv run 执行。

# 环境初始化
uv sync                          # 安装所有依赖
source .venv/bin/activate        # 激活虚拟环境

# 测试
uv run pytest                    # 运行全部测试
uv run pytest tests/test_engines.py -v   # 运行指定测试

# 代码质量
uv run black .                   # 代码格式化（行长 120）
uv run isort .                   # 导入排序
uv run mypy vista/               # 类型检查
uv run flake8 vista/             # 代码风格检查

环境变量（参考 .env.example）：

CLICKHOUSE_DSN=clickhouse://default:@localhost:9000/factor_db   # 因子数据库
LOG_LEVEL=INFO                                                   # 日志级别

核心依赖

更多文档

• 源码阅读指南 — 人工阅读源码和使用本库的完整指导
• 用户自定义建模算法教程 — 编写与加载自定义策略
• 核心架构说明 — 业务流程与因子挖掘设计
• 标准K线字段定义 — 数据格式详细说明
• 因子数据库设计 — ClickHouse 表结构与设计
• 因子标签体系设计 — 因子分类标签体系

参考资料

1. AlphaEval - 系统性因子评价方法
2. DeepCode - 论文复现 Agent 系统
3. 从 75 秒到 0.24 秒：Polars/DuckDB 的魅力
4. QuantaAlpha：基于轨迹进化的可控 Alpha 挖掘框架
5. dexter: 投研全流程 agent
6. chan-factor: 用C#实现的因子计算引擎