1. 为什么 A 股因子评估不能直接套 Alphalens 默认口径因子评估这件事表面上看就是「给一组因子值再给一组价格跑一遍 Alphalens看 IC 和分层收益」。我一开始也是这么想的直到把美股那套默认流程搬到 A 股数据上发现结果根本没法用。问题不在 Alphalens 本身而在于它的默认假设和 A 股的交易制度、股票池结构、价格口径都对不上。最典型的就是 T1。Alphalens 默认的 forward return 是收盘到收盘T 日收盘算出因子就用 T 日收盘价作为买入基准然后算 TN 日收盘相对 T 日收盘的收益。但 A 股 T 日收盘后算出来的因子当天是买不进去的最早也要 T1 才能交易。所以更合理的口径是 T1 开盘买入持有 N 日后卖出收益率用开盘到开盘来近似。这个改动看着小但它直接决定了你评估出来的 IC 是不是真实可交易的信号。另一个容易被忽略的是股票池。同一个因子在全 A 里评估和在沪深 300 里评估结论可能完全相反。涨停买不进、跌停卖不出、停牌没有可交易价格、ST 涨跌幅制度不同、新股上市初期波动异常、极小市值股票带来虚假 alpha——这些都必须先在股票池层面过滤掉否则你测出来的可能只是「能不能交易」而不是「因子有没有效」。这篇要做的就是把 Codex 生成因子计算脚本、Alphalens 做评估、TaoToken 统一管理模型 Key 这三件事串成一条可复现的流水线。适合已经在做量化因子研究、想把这套流程工程化落地的朋友。下面从环境配置开始一步步给出可复制的骨架。2. TaoToken 统一 Keyconfig.toml 与 settings.json 配置骨架整条流水线里Codex 负责生成因子计算和评估脚本这部分需要调用大模型。如果每个脚本、每个工具都单独配一套 Key维护起来会很乱。我的做法是用 TaoToken 做统一入口把模型调用集中管理config.toml 和 settings.json 里各放一份配置骨架脚本和编辑器插件都从这里读。TaoToken 的 API 地址是 https://taotoken.net/api官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它提供的是 OpenAI 兼容接口所以 Codex 这类工具可以直接把 base_url 指过去不用改调用逻辑。先看 config.toml这是给 Codex CLI 或类似命令行工具用的# ~/.codex/config.toml model gpt-5.5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat这里的关键是base_url指向 TaoToken 的 API 地址env_key指定从环境变量读 Key不要把 Key 硬编码进文件。然后在 shell 里设置export TAOTOKEN_API_KEYsk-你的key再看 settings.json这是给编辑器插件或 Claude Code 这类工具用的{ ai.provider: taotoken, ai.baseUrl: https://taotoken.net/api, ai.apiKeyEnv: TAOTOKEN_API_KEY, ai.model: claude-4.6, ai.maxTokens: 8192 }两份配置的核心思路一致base_url 统一指向 TaoTokenKey 走环境变量模型名按需切换。这样 Codex 生成因子脚本、Claude 写评估逻辑、Notebook 里做探索用的都是同一套入口换模型只改一个字段。注意config.toml 和 settings.json 里的 Key 字段都只写环境变量名不要写明文。如果团队协作把环境变量注入放到 CI 或本地 shell profile 里配置文件可以进版本库。Key 的获取和模型列表可以在控制台里看地址是 https://taotoken.net/console API Key 管理在 https://taotoken.net/api-keys 。如果你主要做长期编码和 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan 。3. 可复制配置从数据清洗到 Alphalens 评估的脚本骨架配置好 Key 之后接下来是流水线本身。我把整条链路拆成四段数据清洗、股票池构建、因子预处理、Alphalens 评估。每段都可以让 Codex 生成初版然后自己调口径。3.1 数据清洗与后复权价格合成A 股价格口径我选后复权。不复权价格受分红送股影响收益率不连续前复权价格每次复权事件都会重算历史不适合长期落盘。后复权价格能保持收益率连续也方便本地存储。import pandas as pd import numpy as np def build_hfq_price(raw_price: pd.DataFrame, adj_factor: pd.DataFrame) - pd.DataFrame: raw_price: indexdate, columnsstock_code, valuesclose adj_factor: indexdate, columnsstock_code, values复权因子 # 后复权价格 原始价格 * 复权因子 / 最新复权因子 latest_adj adj_factor.iloc[-1] hfq raw_price * adj_factor / latest_adj return hfq def clean_daily_data(df: pd.DataFrame) - pd.DataFrame: # 剔除停牌成交量为0 df df[df[volume] 0] # 剔除涨跌停无法交易的行用于交易池 df df[~df[is_limit_up] ~df[is_limit_down]] return df3.2 股票池构建研究池与交易池分层股票池不要写死成一坨筛选条件分层复用更清晰。研究池用于横截面分析和中性化交易池在研究池基础上加交易约束指数池再叠加历史成分。def build_univ_research_base(date, stock_basic, daily_metrics): # A股普通股票 ∩ 已上市 ∩ 未退市 ∩ 非ST ∩ 上市满6个月 # ∩ 过去20日日均成交额 1000万 ∩ 总市值不在最后2% mask ( stock_basic[is_common] stock_basic[list_date] date - pd.Timedelta(days180) ~stock_basic[is_st] ~stock_basic[is_delisting] (daily_metrics[amt_ma20] 1e7) (daily_metrics[mktcap_rank] 0.02) ) return stock_basic[mask].index def build_univ_trade_base(date, research_base, daily_metrics): # 研究池 ∩ 非停牌 ∩ 非一字涨停 ∩ 非一字跌停 ∩ 市值不在最后5% mask ( research_base.isin(daily_metrics.index) ~daily_metrics[is_suspended] ~daily_metrics[is_one_word_limit_up] ~daily_metrics[is_one_word_limit_down] (daily_metrics[mktcap_rank] 0.05) ) return research_base[mask]3.3 因子预处理去极值、缺失值、标准化、中性化预处理顺序很重要去极值 → 缺失值填补 → 标准化 → 中性化。而且要在股票池范围内做。def preprocess_factor(factor: pd.Series, univ: pd.Index, industry: pd.Series, mktcap: pd.Series) - pd.Series: f factor.reindex(univ) # 1. MAD 去极值 median f.median() mad (f - median).abs().median() f f.clip(median - 3 * 1.4826 * mad, median 3 * 1.4826 * mad) # 2. 行业均值填补缺失 f f.fillna(f.groupby(industry).transform(mean)) # 3. Z-score 标准化 f (f - f.mean()) / f.std() # 4. 对市值和行业做截面回归取残差 import statsmodels.api as sm X pd.get_dummies(industry, drop_firstTrue).astype(float) X[log_mktcap] np.log(mktcap) X sm.add_constant(X) resid sm.OLS(f, X, missingdrop).fit().resid return resid3.4 Alphalens 评估T1 开盘口径的 forward return这是最关键的一步。把传入 Alphalens 的价格矩阵从 close 换成 open.shift(-1)这样 index 为 T 的价格实际存的是 open[T1]算出来的就是 T1 开盘到 TN1 开盘的收益。import alphalens as al def run_alphalens(factor: pd.Series, open_price: pd.DataFrame, univ: pd.Index, periods(1, 5, 10, 20)): # 价格矩阵用 T1 开盘 price_t1 open_price.shift(-1) # 只保留股票池内的股票 price_t1 price_t1[univ] factor factor.reindex(price_t1.index) # 构建 Alphalens 输入 factor_data al.utils.get_clean_factor_and_forward_returns( factorfactor, pricesprice_t1, quantiles5, periodsperiods, filter_zscore3, ) # 生成报告 ic al.performance.factor_information_coefficient(factor_data) returns al.performance.factor_returns(factor_data) return ic, returns这套骨架跑通之后单因子评估的最小闭环就有了。接下来是验证。4. 验证请求端到端跑一次流水线并校验结果配置和脚本都就位后跑一次完整流程确认每一步的输出符合预期。我习惯用一个小脚本把四段串起来同时打印中间结果做校验。def run_pipeline(factor_name: str, date: str): # 1. 加载数据 raw_price load_raw_price(date) adj_factor load_adj_factor(date) open_price load_open_price(date) stock_basic load_stock_basic(date) daily_metrics load_daily_metrics(date) industry load_industry(date) mktcap load_mktcap(date) # 2. 合成后复权价格 hfq_close build_hfq_price(raw_price, adj_factor) # 3. 构建股票池 univ_research build_univ_research_base(date, stock_basic, daily_metrics) univ_trade build_univ_trade_base(date, univ_research, daily_metrics) print(f研究池数量: {len(univ_research)}, 交易池数量: {len(univ_trade)}) # 4. 加载并预处理因子 factor_raw load_factor(factor_name, date) factor_clean preprocess_factor(factor_raw, univ_trade, industry, mktcap) print(f预处理后因子非空数量: {factor_clean.notna().sum()}) # 5. Alphalens 评估 ic, returns run_alphalens(factor_clean, open_price, univ_trade) print(fIC Mean: {ic.mean().mean():.4f}) print(fICIR: {ic.mean().mean() / ic.mean().std():.4f}) return ic, returns if __name__ __main__: ic, returns run_pipeline(momentum_20d, 2024-06-28)跑完之后重点看三个数研究池和交易池的数量是否合理交易池应该明显小于研究池、预处理后因子非空数量是否接近交易池数量、IC Mean 和 ICIR 是否在合理范围。如果 IC Mean 在 0.02 以上、ICIR 在 0.3 以上这个因子就值得进一步看分层收益和换手率。批量评估时把因子名列表和股票池配置写进一个 YAML用命令行触发# eval_config.yaml factors: - momentum_20d - reversal_5d - turnover_20d universe: univ_trade_base periods: [1, 5, 10, 20] filter: ic_mean: 0.02 icir: 0.3python run_eval.py --config eval_config.yaml --output reports/这样评估和报告生成合并成一条命令改配置就行不用每次手工拼参数。5. 本篇常见错排查5.1 Alphalens 报错get_clean_factor_and_forward_returns价格索引不匹配这个报错通常是价格矩阵的 index 和因子 Series 的 index 对不上。检查两点价格矩阵是否已经 shift(-1) 且 reindex 到因子日期因子是否已经 reindex 到价格矩阵的 index。如果因子日期比价格日期多用factor.reindex(price.index)对齐。5.2 IC 结果全是 NaN多半是股票池过滤太狠或者因子预处理后全被 clip 掉了。先打印factor_clean.notna().sum()如果接近 0检查 MAD 去极值的倍数是不是太小或者行业均值填补时行业字段有大量缺失。另一个可能是价格矩阵里股票池内的股票代码和因子代码格式不一致比如一个带后缀一个不带。5.3 中性化后因子和原始因子相关性极低如果残差和原始因子的相关系数低于 0.3说明市值或行业暴露占了主导。这时候要确认市值用的是对数流通市值还是总市值行业用的是申万一级还是中信一级两者要和后续分析保持一致。另外检查回归时是否加了常数项没加常数项会导致残差有偏。5.4 TaoToken 调用返回 401 或模型不存在先确认环境变量TAOTOKEN_API_KEY在当前 shell 里生效echo $TAOTOKEN_API_KEY能看到值。然后确认 config.toml 里的base_url是https://taotoken.net/api不要多加路径。模型名要和 TaoToken 支持的列表一致可以在模型对话页面确认可用模型https://taotoken.net/models 。如果还是 401去 API Keys 页面重新生成一个 Keyhttps://taotoken.net/api-keys 。5.5 批量评估时因子注册表读不到Factor Registry 的路径配置要和实际文件位置一致。如果注册表用相对路径确认运行命令时的工作目录正确。另外检查注册表里每个因子的状态字段只有状态为 active 的因子才会被批量评估读取。6. 把 Key 配置和评估流水线固定下来整条流水线跑通之后真正省事的地方在于Codex 生成因子脚本、Alphalens 做评估、TaoToken 统一管 Key三件事各司其职。config.toml 和 settings.json 里的配置骨架固定下来换模型只改一个字段换因子只改 YAML评估口径统一在open.shift(-1)这一行上。如果你也在搭类似的因子评估流水线建议先把股票池分层和 T1 开盘口径这两件事定死再往上叠预处理和批量评估。这两步不定后面报告再多指标也是空中楼阁。接入文档在 https://taotoken.net/doc 模型对话可以直接在 https://taotoken.net/chat 里试长期做编码和 Agent 任务的话 Coding Plan 在 https://taotoken.net/coding-plan 。
