Betalens新手系列 · 01 写给新手：Betalens 是什么、能解决什么问题

导言：为什么需要一个量化研究框架

在 Betalens 出现之前，一个典型的 A 股量化研究流程大概是这样的：

• 用 Python 脚本从万得/Tushare/聚源拉数据，导出成 CSV / Parquet。
• 用 pandas/numpy 做因子计算，分组、回测、画图各自写一堆脚本。
• 数据格式不统一、因子命名随意、回测逻辑散落在各处，时间久了连自己都看不懂。
• 想和别人协作？对方得先理解你那堆”仅供参考”的 notebook。

Betalens 的目标，就是把这一套散装的流程封装成一个有 Opinionated 约定的框架：数据统一入库、因子走同一套 API、回测结果有标准格式、绩效报告一键导出。代价是你得接受它的约定——但好处是，你再也不需要重复造那些轮子了。

Betalens 在整个研究链条中的位置

把量化研究拆解成几个环节：

1

数据采集 → 数据清洗/入库 → 因子构建 → 分组回测 → 绩效评价 → 结果展示

Betalens 覆盖的，是从因子构建到结果展示这一段。数据采集和清洗由 betalens_db_manager 负责（入库）；因子构建、回测、评价、展示，全在框架内部闭环。

具体来说，Betalens 包含以下几个模块：

架构全图

一张图说清数据是怎么在 Betalens 里流动的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

flowchart TD
    subgraph data["PostgreSQL 数据库"]
        FM["fundamentals 表\n财务因子"]
        DM["daily_market 表\n行情日频宽表"]
        TS["trade_status 表\n交易状态(稀疏)"]
        IND["industry 表\n行业维表"]
    end

    DF["Datafeed\n查询接口"] --> data
    data --> FP["因子预查询\npre_query_characteristic_data"]
    FP --> SC["分组\nsingle_characteristic"]
    SC --> SW["生成权重\nget_single_factor_weight"]
    SW --> BT["BacktestBase\n回测引擎"]
    BT --> AN["Analyst\n绩效评价"]
    AN --> RP["Excel / HTML 报告"]
    BT --> ES["EventStudy\n事件研究"]
    BT --> RB["RobustTest\n稳健性检验"]
    BT --> DB["Dashboard\n浏览器界面"]

几个关键约定：

1. 所有因子数据都存在 PostgreSQL 里，datafeed 是唯一的查询入口。
2. 权重矩阵的行是调仓日（DatetimeIndex），列是证券代码，必须补一列 cash。多头合计 1、空头合计 -1。
3. 回测真正用的是 engine.actual_weight，不是输入的目标 weight——因为停牌、整数手等原因，输入的权重会被框架调整。
4. 分组函数不叫 single_factor，而叫 single_characteristic（同理有 double_characteristic、multi_characteristic）。这是最容易踩的命名坑。

Betalens 和其他工具的区别

Betalens 不是银弹，但它让你在”做完一个因子”之后，能快速验证第二个、第三个，不用每次都从零搭架子。

开发者侧：目录结构速查

如果你想参与 Betalens 本身的开发，记住以下目录布局：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

betalens/
├── betalens/               # 主包
│   ├── datafeed/           # 数据库查询
│   ├── factor/             # 因子流水线
│   │   ├── factor.py       # 可交易池、分组、权重
│   │   ├── preprocessing.py # 去极值/标准化/中性化
│   │   ├── profiling.py     # 因子画像
│   │   ├── stats.py         # IC/回归/绘图
│   │   ├── mining.py        # 参数扫描
│   │   └── config.py        # YAML 解析
│   ├── backtest/            # 回测引擎
│   ├── analyst/             # 绩效分析
│   ├── eventstudy/          # 事件研究
│   └── robust/              # 稳健性检验
├── betalens-factor/         # 因子脚本仓库
│   ├── alpha101/            # WorldQuant 经典 Alpha 因子（ALPHA1~101）
│   ├── citic_hf_behavior/   # 中信高频行为因子（ILLIQ_v2）
│   ├── LiqDemand/           # 流动性需求/预期分歧（DISP）
│   ├── sw_emotion/          # 市场情绪（研报驱动）
│   └── tdx/                 # 通达信风格（RSI 系列、XICHOU 择时等）
├── betalens_db_manager/      # 数据入库工具
├── dashboard/               # FastAPI + React/Vite Dashboard
└── docs/guide/              # 专题指南（datafeed / factor / backtest / ...）

最高约束：除非你明确说”我要启动开发者模式”，Betalens 的核心代码（betalens/ 包内部）不在日常研究中被修改范围内。这个约定保证了框架的稳定性。

常见误解

• “Betalens 会帮我找因子。” 不会。Betalens 是研究基础设施，因子逻辑需要你自己写（或从研报中复现），Betalens 负责让你跑得快、跑得规范。
• “数据存在 CSV 里可以用 Betalens 吗？” 不行。所有数据必须先入库到 PostgreSQL，用 betalens_db_manager 导入。
• “回测结果漂亮就能实盘赚钱。” 不能。回测只是验证你的逻辑假设，实盘有滑点、流动性冲击、执行偏差等 Betalens 模拟不到的因素。

延伸阅读

• 项目 README：安装与快速开始。
• docs/guide/datafeed.rst ~ docs/guide/robust.rst：10 个专题指南。
• 02 篇：五分钟跑通”股息率多空”：跟着 quickstart 走一遍。