dorian68/quant-guardrails

# Quant Guardrails 用于系统化交易系统的生产级 Guardrails。本项目专注于位于信号与执行之间的安全层：数据完整性检查、市场状态检测、异常评分，以及决定是否允许交易和承担多少风险的策略规则。 ## 业务背景 在实盘交易中，业绩表现往往因非模型原因而失败：糟糕的市场数据、无声的市场状态转变、执行压力或逐渐衰退。在成为模型问题之前，这些首先是运维和风险问题。Quant Guardrails 提供了一个可审计的决策层，可以根据证据停止或调整风险规模，从而保护资金和声誉。 ## 业务成果 - 减少因错误数据和断连 Feed 造成的损失。 - 尽早检测市场状态转变和压力期。 - 执行交易门控，并提供透明、可解释的原因。 - 跨策略提供一致的风险控制层。 - 通过 Walk-Forward 诊断揭示性能衰退。 ## 核心能力 - 针对 OHLCV 的数据清洗，包括时间戳强制执行、缺口检测、重复检查、OHLC 完整性、负成交量以及稳健的离群值标记。 - 针对收益率、波动率、价格区间和 Z-Score 的特征工程，支持可配置窗口。 - 市场状态检测，包含可解释的基于规则的逻辑和概率性 HMM。 - 多层异常评分：数据质量、市场行为和性能衰退。 - 策略引擎，将证据转化为交易许可和风险乘数。 - Walk-Forward 评估，以量化随时间推移的性能退化。 - 带有异步任务的 FastAPI 服务和 Streamlit 仪表板。 - AWS Serverless 部署模板（API Gateway, Lambda, S3, DynamoDB）。 ## 展示的量化 / ML 技能 - 时间序列标准化和时间戳规范。 - 稳健统计：中位数 /MAD Z-Score 和滚动 Z-Score。 - 用于市场状态和风险信号的波动率和价格区间估算。 - 使用滚动统计和自相关检测趋势和均值回归。 - 基于 CUSUM 的变化检测，用于市场和表现异常。 - 用于状态发现和概率分类的隐马尔可夫模型 (HMM)。 - 风险诊断：Sharpe、回撤、性能衰退追踪。 - 生产化：配置驱动的流水线、后台任务、API 设计、基础设施即代码。 ## Guardrail 逻辑（业务视角） 输入数据：带有时间戳列或 DatetimeIndex 的 OHLCV。默认强制使用 UTC。 市场状态标签： - `LOW_VOL`：波动率低于第 25 百分位数。 - `HIGH_VOL`：波动率高于第 75 百分位数或默认状态。 - `TRENDING`：持续的方向性漂移超过阈值。 - `MEAN_REVERT`：在趋势窗口上呈负自相关。 - `STRESS`：极端收益 Z-Score（压力事件）。 异常评分： - 数据：完整性违规、缺口、重复、负成交量、可疑数据错误。 - 市场：收益/区间峰值和 CUSUM 变化点。 - 表现：滚动 Sharpe 退化和下跌的 CUSUM。 策略决策： - 针对完整性/缺口或严重数据异常的硬性阻断。 - 在压力/高波动状态以及市场/表现异常时降低风险。 - 输出 `trade_allowed`、`risk_multiplier` 和 `reasons` 以供审计。 如果 HMM 训练失败或 `hmmlearn` 不可用，系统将回退到基于规则的市场状态检测器。 ## 配置（示例） ``` { "feature": { "return_windows": [1, 5, 20], "vol_windows": [10, 20], "shift": 1 }, "rule_regime": { "vol_window": 20, "trend_window": 50, "stress_z": 3.5 }, "hmm_regime": { "n_states": 5, "n_iter": 200 }, "policy": { "data_anomaly_block": 0.8, "stress_regime_prob": 0.5 }, "walk_forward": { "train_window": 200, "test_window": 50, "step": 50 }, "isolate_outliers": false } ``` ## 端到端流程 1. 接入 OHLCV 数据并强制执行时间戳。 2. 运行数据清洗检查并标记问题。 3. 构建收益、波动率和 Z-Score 的特征。 4. 使用基于规则的逻辑和可选 HMM 检测市场状态。 5. 对数据、市场和表现进行异常评分。 6. 应用策略引擎决定交易门控和风险缩放。 7. 评估 Walk-Forward 性能衰退以进行诊断。 8. 返回结构化的 JSON 结果用于审计或监控。 ## 仓库布局 ``` quant-guardrails/ ??? apps/ ? ??? api/ # FastAPI service (jobs + results) ? ??? dashboard/ # Streamlit demo UI ??? packages/ ? ??? core/ # Reusable analytics package ? ??? core/ # Core logic (hygiene, regimes, anomalies, policy) ??? data/ ? ??? sample/ # Sample OHLCV data ??? infra/ ? ??? aws/ # Terraform + deploy script ??? tests/ # pytest unit tests ??? .github/workflows/ci.yml # CI pipeline ``` ## 架构图 ``` graph TD A[Data Sources
OHLCV CSV] --> B[Ingestion
API / Dashboard] B --> C[Data Hygiene] C --> D[Feature Engineering] D --> E[Regime Detection
Rule-based + HMM] D --> F[Anomaly Scoring
Data / Market / Performance] E --> G[Policy Engine] F --> G G --> H[Decision Output
trade_allowed / risk_multiplier] G --> I[Walk-Forward Diagnostics] H --> J[Results Store
Local JSON or S3] I --> J ``` ## 快速开始（本地） 1. 安装依赖 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt 2. 运行测试 make test 3. 运行 API uvicorn apps.api.main:app --reload 4. 运行仪表板 streamlit run apps/dashboard/app.py ## API 使用 - POST `/jobs` - GET `/jobs/{job_id}` - GET `/jobs/{job_id}/result` 本地执行在进程内运行作业，并将结果存储在 `data/results/` 下。AWS 堆栈配置 S3 和 DynamoDB 用于生产存储，代码结构设计为在不更改 API 的情况下交换后端。 示例 (JSON)： ``` curl -X POST http://localhost:8000/jobs \ -H "Content-Type: application/json" \ -d '{"path": "data/sample/sample_ohlcv.csv", "config": {"feature": {"shift": 1}}}' ``` ## 仪表板 Streamlit 演示在样本数据集或用户上传的数据上运行完整流水线，并显示： - 最新策略决策 - 市场状态快照（基于规则 + HMM） - 异常评分 - Walk-Forward 退化指标 ## AWS 部署（Serverless） 在 `infra/aws` 下提供了一个最小化的 Terraform 堆栈： - API Gateway + Lambda（通过 Mangum 运行 FastAPI） - S3 用于存储结果 - DynamoDB 用于作业元数据 部署： ``` cd infra/aws/scripts ./deploy.sh ``` 环境变量（不存储密钥）： - `AWS_REGION` - `QG_S3_BUCKET` - `QG_DDB_TABLE` - `QG_LAMBDA_NAME` - `QG_API_NAME` ## 项目亮点 - 业务优先的 Guardrails，降低运维和市场状态风险。 - 整洁的架构，具有可复用的核心分析和清晰的 API。 - 面向生产交付：异步任务、CI 和基础设施即代码。 - 透明、可审计的决策，带有明确的原因和阈值。 ## 不在范围内（但可作为自然扩展） - 期权估值和希腊字母（例如 Black-Scholes，局部或随机波动率）。 - 跨多资产组合的 VaR 或 CVaR。 - 执行成本和滑点模型。 - 订单簿或基于微观结构的风险信号。 ## 截图（占位符） - `docs/screenshots/dashboard.png` - `docs/screenshots/api-response.png` 如果您需要扩展支持（功能添加、监控、云加固），请开启 Upwork 合同并分享您的需求。

标签：Apex, API服务, AWS无服务器, HMM模型, Kubernetes, OHLCV数据, Python, Streamlit, Zenmap, 云部署, 交易护栏, 回撤控制, 安全规则引擎, 市场机制识别, 异常检测, 数据完整性, 数据清洗, 无后门, 时序分析, 机器学习, 波动率估计, 漏洞探索, 特征工程, 稳健统计, 策略开关, 策略衰减, 系统化交易, 访问控制, 逆向工具, 量化交易, 金融科技, 风控引擎