309 lines
10 KiB
Markdown
Executable File
309 lines
10 KiB
Markdown
Executable File
# BRAIN 表达式模板解码器 - Flask Web 应用程序
|
||
|
||
一个全面的 Flask Web 应用程序，用于解码字符串模板，具备语法检查、语法高亮显示，并与 WorldQuant BRAIN 平台无缝集成以获取真实操作员数据。
|
||
|
||
## 🚀 功能
|
||
|
||
### 核心功能
|
||
- **模板检测**：自动检测表达式中的 `<template_name/>` 模式
|
||
- **语法检查**：实时验证分号、注释和语法
|
||
- **语法高亮**：带行号和自动完成的颜色编码显示
|
||
- **模板解码**：生成表达式的两种模式
|
||
- **完全迭代**：生成所有可能的模板变量组合
|
||
- **随机迭代**：生成指定大小的随机样本
|
||
- **导出选项**：复制结果或下载为文本文件
|
||
|
||
### 模板类型
|
||
- **Op（操作符）** - 蓝色按钮，与 BRAIN 操作符集成
|
||
- **Data（数据字段）** - 绿色按钮，用于数据字段配置
|
||
- **Normal（参数）** - 灰色按钮，用于一般参数
|
||
|
||
### BRAIN 集成
|
||
- **内置 API 集成**：直接连接到 WorldQuant BRAIN API，支持 CORS
|
||
- **186+ 操作符**：访问所有操作符类别（算术、排名、减少、时间序列等）
|
||
- **800+ 数据字段**：来自基础数据集，支持搜索和过滤
|
||
- **高级搜索**：按类别过滤操作符并按名称搜索
|
||
- **多选界面**：专业的操作符选择，带视觉反馈
|
||
|
||
## 🛠️ 设置与安装
|
||
|
||
### 先决条件
|
||
- Python 3.7 或更高版本
|
||
- pip（Python 包管理器）
|
||
- WorldQuant BRAIN 账户（用于 BRAIN 集成功能）
|
||
|
||
### 快速开始
|
||
|
||
1. **克隆或下载**此代码库到本地机器
|
||
|
||
2. **运行应用程序**（依赖项将自动安装！）:
|
||
|
||
**在 Windows 上：**
|
||
```bash
|
||
# 双击 run_app.bat 或在终端运行：
|
||
run_app.bat
|
||
```
|
||
|
||
**在 macOS/Linux 上：**
|
||
```bash
|
||
# 首次使脚本可执行：
|
||
chmod +x run_app.sh
|
||
|
||
# 运行应用程序：
|
||
./run_app.sh
|
||
```
|
||
|
||
**或直接用 Python 运行：**
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
3. **自动依赖安装**：
|
||
- 应用程序将自动检查缺失的依赖项
|
||
- 如果缺少任何软件包，将从 requirements.txt 安装
|
||
- **对于中国用户**：依赖项将从清华大学镜像自动下载，以加快安装速度
|
||
- 无需手动安装！
|
||
|
||
4. **打开应用程序**：
|
||
- Flask 服务器在 `http://localhost:5000` 启动
|
||
- 打开您的网络浏览器并导航到 `http://localhost:5000`
|
||
- 一切都已集成 - 无需单独的代理服务器！
|
||
|
||
### 对于中国用户
|
||
|
||
该应用程序自动使用清华大学的 PyPI 镜像进行更快的下载。如果您希望手动安装依赖项：
|
||
|
||
**Windows：**
|
||
```bash
|
||
# 使用清华镜像的安装脚本
|
||
setup_tsinghua.bat
|
||
```
|
||
|
||
**macOS/Linux：**
|
||
```bash
|
||
# 使可执行并运行
|
||
chmod +x setup_tsinghua.sh
|
||
./setup_tsinghua.sh
|
||
```
|
||
|
||
**使用清华镜像的手动安装：**
|
||
```bash
|
||
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
|
||
```
|
||
|
||
**配置其他镜像：**
|
||
您可以通过编辑 `mirror_config.txt` 更改镜像源。该文件包括几个流行的中国镜像：
|
||
- 清华大学 - 默认
|
||
- 阿里云
|
||
- 豆瓣
|
||
- 中国科学技术大学
|
||
|
||
### 手动安装
|
||
|
||
如果自动安装失败，您可以手动安装：
|
||
|
||
```bash
|
||
# 从 requirements.txt 安装依赖项
|
||
pip install -r requirements.txt
|
||
|
||
# 或单独安装软件包
|
||
pip install flask==2.3.3 flask-cors==4.0.0 requests==2.31.0 pandas==2.0.3
|
||
|
||
# 启动应用程序
|
||
python app.py
|
||
```
|
||
|
||
**注意**：该应用程序包括自动依赖检查，当您运行它时将尝试安装缺失的软件包。
|
||
|
||
## 🔗 BRAIN 集成
|
||
|
||
### 设置
|
||
1. **无需单独设置** - BRAIN API 集成已内置于 Flask 应用程序中
|
||
2. **连接到 BRAIN**：点击网页界面中的“连接到 BRAIN”按钮
|
||
3. **输入凭据**：使用您的 WorldQuant BRAIN 用户名和密码
|
||
4. **自动加载操作符**：系统会获取所有可用的操作符（186+）
|
||
|
||
### 使用 BRAIN 操作符
|
||
1. **配置模板**：将模板类型设置为 “Op”
|
||
2. **选择来自 BRAIN**：在模板配置中点击“从 BRAIN 中选择”按钮
|
||
3. **搜索和过滤**：使用搜索框和类别过滤器查找操作符
|
||
4. **多选**：选择多个操作符并将其应用于您的模板
|
||
5. **生成组合**：解码模板以获取所有可能的操作符组合
|
||
|
||
## 📝 使用指南
|
||
|
||
### 1. 表达式编辑器
|
||
- 在主编辑器中输入或粘贴您的表达式
|
||
- 语法将自动检查并提供视觉反馈
|
||
- 模板将实时检测并高亮显示
|
||
- 输入 `<` 以获取模板建议的自动完成
|
||
|
||
### 2. 模板管理
|
||
- 检测到的模板出现在右侧面板中
|
||
- 点击模板类型按钮（Op/Data/Normal）进行配置
|
||
- 视觉指示器显示已配置 (✓) 与未配置 (•) 的模板
|
||
- 点击模板名称查看当前配置
|
||
|
||
### 3. 模板配置
|
||
- **普通模板**：手动输入以逗号分隔的值
|
||
- **操作符模板**：从 BRAIN 操作符中选择或手动输入
|
||
- **数据模板**：输入数据字段规格
|
||
|
||
### 4. 模板解码
|
||
生成表达式的两个选项：
|
||
- **full_iteration**：生成所有可能的组合
|
||
- 使用笛卡尔积创建每一种可能的组合
|
||
- 显示前 999 个结果，并为大数据集提供搜索功能
|
||
- **random_iteration**：生成随机样本
|
||
- 指定随机表达式数量（默认为 10）
|
||
- 首先生成所有组合，然后随机选择指定数量
|
||
- 有助于测试或当您只需要部分可能性时
|
||
- 每个模板必须至少具有一个配置值
|
||
- 结果将显示，并提供复制和下载选项
|
||
|
||
## 💡 示例表达式
|
||
|
||
```
|
||
positive_sentiment = rank(<backfill_op/>(<positive_sentiment/>,<days/>));
|
||
negative_sentiment = rank(<backfill_op/>(<negative_sentiment/>, <days/>));
|
||
sentiment_difference = <compare_op/>(positive_sentiment, negative_sentiment);
|
||
<time_series_operator/>(sentiment_difference, <days/>)
|
||
```
|
||
|
||
### 示例配置
|
||
- `<days/>` → `7, 14, 30`
|
||
- `<compare_op/>` → `ts_max, ts_min`（从 BRAIN 中选择）
|
||
- `<time_series_operator/>` → `ts_delta, ts_mean`（从 BRAIN 中选择）
|
||
|
||
### 生成输出
|
||
解码器将生成所有组合：
|
||
```
|
||
ts_delta(ts_max(7), 7)
|
||
ts_delta(ts_max(14), 14)
|
||
ts_delta(ts_max(30), 30)
|
||
ts_delta(ts_min(7), 7)
|
||
ts_delta(ts_min(14), 14)
|
||
ts_delta(ts_min(30), 30)
|
||
ts_mean(ts_max(7), 7)
|
||
...等等
|
||
```
|
||
|
||
## 🎯 语法规则
|
||
|
||
- 使用 `/* */` 进行多行注释
|
||
- 语句以 `;` 结束（最后一行除外）
|
||
- 不允许使用类、对象、指针或函数
|
||
- 最后一行是 BRAIN 模拟器的 Alpha 表达式
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### Flask 应用程序结构
|
||
```
|
||
BRAINProject/
|
||
├── app.py # 拥有自动依赖安装的 Flask 应用程序
|
||
├── templates/
|
||
│ └── index.html # 主要网页界面模板
|
||
├── static/
|
||
│ ├── styles.css # 应用程序样式
|
||
│ ├── script.js # 核心应用程序逻辑
|
||
│ ├── decoder.js # 模板解码算法
|
||
│ └── brain.js # BRAIN API 集成模块
|
||
├── requirements.txt # Python 依赖项
|
||
├── mirror_config.txt # PyPI 镜像配置
|
||
├── run_app.bat # Windows 启动脚本
|
||
├── run_app.sh # Unix/macOS 启动脚本
|
||
├── setup_tsinghua.bat # 使用清华镜像的 Windows 设置（适用于中国）
|
||
├── setup_tsinghua.sh # 使用清华镜像的 Unix 设置（适用于中国）
|
||
├── brain_function_tester.ipynb # 用于测试的 Jupyter 笔记本
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
### 关键组件
|
||
- **Flask 后端**：处理 BRAIN API 身份验证和数据获取
|
||
- **模板引擎**：Jinja2 模板用于动态内容
|
||
- **静态资源**：高效提供 CSS 和 JavaScript
|
||
- **CORS 处理**：内置跨域请求支持
|
||
- **会话管理**：安全的会话处理以进行 BRAIN 身份验证
|
||
|
||
### API 端点
|
||
- `GET /` - 主要应用程序页面
|
||
- `POST /api/authenticate` - BRAIN 身份验证
|
||
- `GET /api/operators` - 获取 BRAIN 操作符，支持分页
|
||
- `GET /api/datafields` - 获取 BRAIN 数据字段
|
||
- `GET /api/status` - 检查身份验证状态
|
||
- `POST /api/logout` - 从 BRAIN 登出
|
||
|
||
## 🔧 高级特性
|
||
|
||
### 操作符获取
|
||
- **强大的分页**：自动处理 BRAIN API 分页
|
||
- **类别支持**：获取所有类别的操作符
|
||
- **错误处理**：多种应急策略以确保可靠的数据加载
|
||
- **调试**：内置端点用于 API 响应分析
|
||
|
||
### 模板处理
|
||
- **实时检测**：在输入时检测模板
|
||
- **视觉反馈**：颜色编码的语法高亮
|
||
- **状态指示器**：清晰的视觉提示模板配置状态
|
||
- **验证**：确保在解码前所有模板都已配置
|
||
|
||
### 用户体验
|
||
- **专业 UI**：干净、现代的界面设计
|
||
- **响应式设计**：适用于桌面和平板设备
|
||
- **键盘快捷键**：高效的模板自动完成
|
||
- **导出选项**：复制单个结果或下载所有结果
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **Flask 服务器无法启动**：
|
||
- 检查 Python 版本（需要 3.7+）
|
||
- 安装缺失的依赖项：`pip install -r requirements.txt`
|
||
|
||
2. **BRAIN 连接失败**：
|
||
- 验证您的 BRAIN 凭据
|
||
- 检查网络连接
|
||
- 确保没有防火墙阻止外发 HTTPS 请求
|
||
|
||
3. **模板未检测到**：
|
||
- 检查模板语法：`<template_name/>`
|
||
- 使用按钮手动刷新模板
|
||
|
||
4. **没有加载操作符**：
|
||
- 验证 BRAIN 身份验证是否成功
|
||
- 检查浏览器控制台是否有错误信息
|
||
- 尝试登出并重新认证
|
||
|
||
### 调试模式
|
||
在调试模式下运行应用程序以获取详细错误信息：
|
||
```bash
|
||
python app.py
|
||
# 应用程序默认启用调试模式
|
||
```
|
||
|
||
## 📈 性能
|
||
|
||
- **高效加载**：操作符在身份验证时加载一次
|
||
- **分页处理**：自动获取所有数据，无论 API 分页如何
|
||
- **会话管理**：持久会话提升用户体验
|
||
- **优化前端**：最小的 JavaScript 依赖加快加载速度
|
||
|
||
## 🔐 安全
|
||
|
||
- **会话安全**：Flask 安全会话，支持可配置的密钥
|
||
- **凭据处理**：凭据不被存储，仅用于 API 身份验证
|
||
- **CORS 保护**：正确配置的跨域请求处理
|
||
- **输入验证**：模板语法验证和语法检查
|
||
|
||
## 🚧 未来增强功能
|
||
|
||
- **模板库**：保存和共享模板配置
|
||
- **高级过滤**：更复杂的操作符和数据字段过滤
|
||
- **批量操作**：同时处理多个表达式
|
||
- **API 集成**：连接其他金融数据提供商
|
||
- **导出格式**：支持 JSON、CSV 和其他输出格式
|
||
|
||
---
|
||
|
||
**注意**：该 Flask 应用程序取代了之前的 HTML+代理架构，提供了更强大和集成的 BRAIN 模板解码解决方案。 |