wqb
/
alpha_tools
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
32 Commits
1 Branch
0 Tags
28 MiB
 
 
 
 
 
 
Tag: Branch: Tree: 2b609e0465
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2b609e0465'
${ noResults }
alpha_tools/backup_code/wqb_app/usage.md

16 KiB
Raw Blame History Escape

使用说明（usage.md）

本文档面向本仓库的本地 Flask Web APP，聚焦“如何在网页上使用各功能 + 每个功能的目的”。不包含 bug 修复与代码改动建议。

1. 启动与访问

  1. 在 APP/ 目录启动：
    • Windows：双击 run_app.bat（或在终端运行它）
    • 或直接运行：python main.py
  2. 浏览器打开：http://localhost:55001/

说明：项目内的 README.md 可能仍写 python app.py，但本工作区实际入口脚本是 main.py。

2. 几个重要概念（你会频繁用到）

  • 模板占位符：在表达式里用形如 <xxx/> 的占位符，后续通过弹窗为每个模板配置一组可替换的值。
  • 两种生成方式：
    • full_iteration：枚举所有组合
    • random_iteration：在组合空间中抽样
  • Settings（回测设置）追加：在“Results”页点 Append Expression with Settings，生成可供回测器使用的 JSON：expressions_with_settings.json。
  • 浏览器存储：
    • BRAIN 的 session_id 会存到浏览器 localStorage（键名类似 brain_session_id）
    • Deepseek/Kimi 的 API Key 等通常存到 sessionStorage
    • 关闭标签页/浏览器后，sessionStorage 可能会丢失，需要重新填。

3. 快速上手（最常用的一条完整链路）

目标：从“模板表达式”生成一批可回测的 Alpha 表达式，并用 Web 回测器批量回测。

  1. 进入首页（/），在 Expression Editor 里编辑表达式（可包含 <xxx/> 模板）。
  2. 右侧 Detected Templates 会自动识别模板；点击模板会弹出配置窗口：
    • 普通模板：在弹窗里用英文逗号分隔输入候选值
    • 若出现 Choose from BRAIN：可从 BRAIN 拉取 Operators 或 DataFields（需要先连接 BRAIN）
  3. 点击右侧 Next: Decode Templates → 进入 Decode Templates：
    • 点 full_iteration 生成全量
    • 或点 random_iteration 并设置 Count
  4. 进入 Results：
    • 点 Download All Expression in txt：下载纯文本表达式列表
    • 点 Append Expression with Settings：填写/选择 settings 后下载 expressions_with_settings.json
  5. 回到首页点 🚀 打开回测器，在弹窗选择 Web 界面（会打开 /simulator）：
    • 上传 expressions_with_settings.json
    • 填入 BRAIN 账号密码
    • 点 🔗 Test Connection（可选但建议）
    • 点 🚀 Start Simulation 开始批量回测
  6. 在右侧日志区查看运行进度；必要时可 ⏹️ Stop。

4. 首页（/）：模板解码器

4.1 顶部快捷入口（目的与用法）

  • Connect to BRAIN

    • 功能：让模板配置时能“从 BRAIN 选择 Operators/DataFields”，并把 operators 缓存在浏览器里供其它页面使用。
    • 用法：点击后弹出登录框，输入 Username / Password，点 Connect。
    • 若触发额外验证：页面会出现 Complete Authentication（或类似）按钮/提示，按提示在新窗口完成验证后回到页面。

  • 🚀 打开回测器

    • 功能：批量回测表达式。
    • 用法：点击后会弹窗让你选择：
      • 命令行界面：启动 simulator/simulator_wqb.py（在新终端窗口运行）
      • Web 界面：打开 /simulator（推荐）

  • 📤 Alpha_Submitter提交器

    • 功能：打开提交相关的命令行工具。
    • 用法：点击后会在新终端窗口运行 simulator/alpha_submitter.py。

  • 🚀 Open Simulator_hk

    • 功能：打开港股相关的命令行回测工具。
    • 用法：点击后会在新终端窗口运行 hkSimulator/autosimulator.py。

  • 七十二变

    • 功能：基于“种子 Alpha”自动生成大量变体（模板和/或表达式）。
    • 用法：点击后弹窗让你选择：
      • 命令行界面：启动 Tranformer/Transformer.py（新终端窗口）
      • Web 界面：打开 /transformer-web（推荐）

  • 🌉 缘分一道桥

    • 功能：把一批 Alpha 跨 Region/Universe/Delay 寻找可用字段组合，并生成待回测表达式。
    • 用法：点击进入 /alpha_inspector。

  • AI创意工坊：进入 /inspiration-house/（Operator 建议/打分）。

  • 论文分析：进入 /paper-analysis/（上传论文，Deepseek 分析关键词/摘要/公式）。

  • 数据字段指南：进入 /feature-engineering/（多步 DataField 探索建议）。

4.2 模板空间（“模板管理/导入导出/接 72 变”）

在首页的“模板空间”里，你会看到：

  • 示例模板按钮：如 Vector数据处理模板、单字段深度处理 等。
  • 用户自建模板：通过 Save Current Template 保存当前编辑器内容。
  • 72 变模板：通过“加载72变生成的模板”导入。

可用按钮：

  • Save Current Template：保存当前编辑器内容到本地存储。
  • Overwrite Existing：覆盖已存在的同名模板。

4.3 找灵感 (Alpha Inspiration Master)

位于编辑器工具栏的 💡 找灵感 按钮，提供基于 LLM (如 Kimi/Moonshot) 的 Alpha 灵感生成功能。

功能流程：

  1. 前置条件：需先登录 BRAIN（点击 Connect to BRAIN）。
  2. 打开工具：点击编辑器上方的 💡 找灵感 按钮，打开配置弹窗。
  3. 配置 LLM：
    • 填入 Base URL (默认 Moonshot API)
    • 填入 API Key
    • 选择模型 (如 kimi-k2-turbo-preview)
  4. 选择数据：
    • 选择 Region / Universe / Delay
    • 搜索并选择一个 Dataset (如 analyst10)
    • 系统会自动拉取该 Dataset 的字段信息和 BRAIN 的 Operators。
  5. 生成灵感：
    • 点击 Generate Alpha Templates。
    • LLM 会根据字段含义和算子文档，推荐一批 Alpha 模板。
  6. 使用结果：
    • 生成的模板可以直接复制到编辑器中使用，或下载保存。

5. 进阶功能页

  • 只展示用户自建模板：切换模板按钮区的显示范围。
  • 📤 导出用户自建模板：导出自建模板为 JSON 文件。
  • 📥 导入用户自建模板：导入之前导出的 JSON。
  • 🤖 加载72变生成的模板：选择 72 变下载的 Alpha_candidates.json（或类似结构文件），把“模板候选”加入模板空间。
  • 📄 载入72变生成的表达式：导入“表达式列表 JSON”。
    • 常见来源：72 变 Web 下载的 Alpha_generated_expressions_success.json
    • 页面也支持载入“JSON 数组（每项为字符串表达式）”的文件

4.4 Expression Editor（编辑器页）

功能：编写/粘贴带模板的表达式，并进行基础语法检查与模板检测。

常用操作：

  • Clear：清空编辑器。
  • Save Current Template：把当前编辑器内容保存为“用户自建模板”。
  • Overwrite Existing：覆盖已有模板（用于更新同名模板）。

右侧信息栏：

  • Detected Templates：自动列出识别到的 <xxx/> 模板。
  • Grammar Rules：展示此编辑器的语法规则（如分号、注释等）。

4.5 Decode Templates（解码页）

功能：把模板的候选值做组合，生成最终表达式列表。

  • full_iteration：生成所有组合。
  • random_iteration：抽样生成；右侧 Count 输入抽样数量。

4.6 Results（结果页）

功能：查看/下载生成的表达式，并将表达式与 settings 组合成回测 JSON。

  • Download All Expression in txt：下载表达式纯文本。
  • Append Expression with Settings：打开 settings 配置表。
    • 常见字段：region / universe / delay / decay / neutralization ...
    • 配置完成后会下载：expressions_with_settings.json

5. Web 回测器（/simulator）

功能：把 expressions_with_settings.json 批量发送到 BRAIN 做 simulation，并在页面查看日志。

5.1 需要准备什么

  • 文件：expressions_with_settings.json（通常来自首页 Results 页的 settings 追加功能）
  • 账号：WorldQuant BRAIN 用户名密码

5.2 页面字段与按钮

  • 📁 Expressions JSON File：上传 JSON（提示：Select expressions_with_settings.json file）
  • 👤 BRAIN Username / 🔒 BRAIN Password
  • 🎯 Starting Position：从第 N 条表达式开始（0-based）
  • ⚡ Concurrent Simulations：并发回测数量
  • 🔀 Random Shuffle：随机打乱表达式顺序
  • 🎛️ Multi-Simulation Mode：多表达式合并回测槽位（展开后设置 📊 Alphas per Slot）
  • 🔗 Test Connection：测试登录/连接
  • 🚀 Start Simulation：开始
  • ⏹️ Stop：停止

5.3 日志查看

右侧 📊 Simulation Logs & Status：

  • 可用 📁 Select Log File 下拉选择历史日志
  • 🔄 Refresh 刷新日志列表
  • 中央日志窗口持续输出运行信息

6. 七十二变（Transformer）Web（/transformer-web）

功能：输入“种子 Alpha ID”，结合 LLM + BRAIN 信息，生成模板/表达式的变体，并提供下载。

6.1 基本步骤

  1. 在 Configuration 区填写 LLM 参数：
    • LLM Model Name（默认 kimi-k2-turbo-preview）
    • LLM API Key
    • LLM Base URL（默认 https://api.moonshot.cn/v1）
  2. 点击 Test LLM Connection，显示成功后继续。
  3. 填写 BRAIN 账号：BRAIN Username / BRAIN Password，点 Login & Fetch Options。
  4. 填写/调整 Template Summary（可点 📂 Load from File 导入 txt/md）。
  5. 填 Alpha ID，设置 Datafield Top N。
  6. 可选：选择目标 region / delay / universe，以及“目标数据类别（可多选）”。
    • Data Type：默认为 MATRIX。若选择 VECTOR，会弹出警告提示，需确认原型 Alpha 正确使用了 vector operator。
  7. 点 Run Transformer，右侧 Output Log 会滚动输出。
  8. 生成结束后，页面出现下载区：
    • Download Alpha_candidates.json：模板文件（可回首页“加载72变生成的模板”再精细化改）
    • Download Alpha_generated_expressions_success.json：可用表达式列表（可回首页“载入72变生成的表达式”或进入回测器）
    • Download Alpha_generated_expressions_error.json：被过滤/报错的表达式（用于排查模板质量）

7. 缘分一道桥（/alpha_inspector）

功能：批量获取 Alpha（按日期范围或指定 ID），分析字段在不同 Region/Universe/Delay 的可用性，生成新的表达式，并提供“下载待回测/排队回测”。

7.1 使用步骤

  1. 进入页面后先在“登录 BRAIN”区输入用户名（邮箱）与密码，点 登录。
  2. 在“选择模式”里选择：
    • 按日期范围：填开始/结束日期（页面提示不建议超过 30 天）
    • 指定 Alpha ID：在文本框里输入多个 ID（逗号/空格/换行分隔）
  3. 点击 获取 Alpha 并分析。
  4. 结果区会展示 Alpha 列表（可展开查看详情）。
  5. 需要批量回测时：
    • 点 下载所有待回测Alpha：把待回测表达式下载到本地
    • 或点 一键全部排队回测：在本页串行排队回测（页面提示：中途关闭页面会中断队列）

8. AI创意工坊（/inspiration-house/）

功能：基于你的“研究目标 + 当前表达式”，对大量 operator 做 AI 评价/打分，给出“加哪些 operator 更可能改进目标”的建议。

8.1 先配置模型

  • 在 API Configuration：
    • AI Model Provider：Deepseek / Kimi
    • API Key
    • Model Name（示例：deepseek-chat 或 kimi-k2-0711-preview）
    • Worker Configuration（batchSize）：批处理大小
  • 点 Test & Save Configuration

8.2 设置目标与表达式

  • 🎯 Quant Research Target：点 Edit Target，填写你的目标（例如降低换手、提高 Sharpe、降低回撤等）
  • 📝 Current Expression：
    • 输入表达式
    • 或点 Load from BRAIN（从已连接的 BRAIN 缓存/接口获取）

8.3 开始评价与导出

  • 点 Start AI Evaluation
  • 可用筛选：Min/Max Score、只看高分/中分/低分
  • Export Results 导出结果

建议：先在首页 Connect to BRAIN，让 operator 列表更完整。

9. 论文分析（/paper-analysis/）

功能：上传论文文件，用 Deepseek 做关键词/摘要/公式（页面里称 Formulas）提取与整理。

使用步骤：

  1. 在 Deepseek API Configuration 输入 API Key，点 Save API Key（会测试连接）。
  2. 在 Upload Paper 上传文件（支持：PDF/TXT/DOC/DOCX/RTF/LaTeX/Markdown）。
  3. 在 Analysis Options 勾选需要的内容：
    • Extract Mathematical Formulas
    • Extract Keywords
    • Generate Summary
  4. 点 Analyze Paper。
  5. 在结果区切换 Keywords / Summary / Formulas 查看。
  6. 点 Export Results 导出。

10. 数据字段指南（Feature Engineering）（/feature-engineering/）

功能：以“多步 pipeline”的方式，让 AI 给出 DataField 探索/加工/组合的推荐方案；支持编辑 system prompt、导出 pipeline。

使用步骤：

  1. 在 API Configuration 配置 Deepseek/Kimi：Provider、API Key、Model Name，点 Test & Save Configuration。
  2. 在 Start New Feature Engineering Pipeline：
    • 点 Load Question Template 生成模板
    • 在 Question Template 中填入你当前 datafield、描述、EDA 观察等
    • 如需：点 Edit System Prompt 调整提示词（也可 Load Default Prompt）
  3. 点 Get AI Recommendations。
  4. 在 AI Recommendations 区查看推荐选项：
    • Clear & Start Over：清空并重新开始
    • Export Pipeline：导出 pipeline

11. 外部账号与 Key：去哪里申请、在哪填、怎么验证

网址/入口可能随平台更新而变化；若打不开，以平台官网的“API / 开发者 / Keys”入口为准。

11.1 WorldQuant BRAIN（账号）

  • 去哪申请：WorldQuant BRAIN 官网注册账号。
  • 在哪填：
    • 首页 Connect to BRAIN
    • Web 回测器 /simulator
    • 72 变 /transformer-web
    • 缘分一道桥 /alpha_inspector
  • 怎么验证：各页面都有登录/连接测试流程（如 Connect、Test Connection、Login & Fetch Options）。

11.2 Deepseek（API Key）

  • 去哪申请：Deepseek 开放平台/开发者平台创建 API Key。
  • 在哪填：
    • /paper-analysis/：API Key → Save API Key
    • /inspiration-house/：Provider 选 Deepseek，填 API Key → Test & Save Configuration
    • /feature-engineering/：Provider 选 Deepseek，填 API Key → Test & Save Configuration
  • 怎么验证：上述页面的测试按钮会调用后端 .../api/test-deepseek。

11.3 Kimi / Moonshot（API Key）

  • 去哪申请：Moonshot/Kimi 开放平台创建 API Key。
  • 在哪填：
    • /inspiration-house/：Provider 选 Kimi
    • /feature-engineering/：Provider 选 Kimi
    • /transformer-web：LLM API Key + LLM Base URL（默认 https://api.moonshot.cn/v1）
  • 怎么验证：
    • /inspiration-house/、/feature-engineering/：Test & Save Configuration
    • /transformer-web：Test LLM Connection

12. 常见使用建议（不涉及修复，仅帮助你更顺畅）

  • 如果某页面提示缺少 operators/datafields：优先回首页 Connect to BRAIN 再刷新页面。
  • 72 变生成后的三类文件，建议按用途回流：
    • Alpha_candidates.json → 首页“加载72变生成的模板” → 再用解码器精细化
    • Alpha_generated_expressions_success.json → 首页“载入72变生成的表达式”或直接去回测器
    • Alpha_generated_expressions_error.json → 用于检查模板/提示词是否存在系统性错误
  • API Key / Token 请勿写入仓库或公开分享；尽量只在本地浏览器会话中使用。