# Mizarα
_____ .__
/ \ |__|____________ _______
/ \ / \| \___ /\__ \\_ __ \
/ Y \ |/ / / __ \| | \/
\____|__ /__/_____ \(____ /__|
\/ \/ \/
开阳 · 向量策略 · ·· ··· ✦ ✧
观往知来 · Mizarα · * ★ * ✧ ✦
> **观往知来 · 相似性量化**
> 基于向量相似性检索的市场状态预测与量化策略实验框架
---
## 📖 简介
**Mizarα (mizar-alpha)** 是一个实验性的量化策略研究平台。它不依赖传统参数化模型，而是将市场技术指标编码为高维向量，通过向量数据库检索历史上最相似的“市场状态”，并根据这些相似状态的未来走势生成预测信号。
与黑盒模型不同，Mizarα 的每一次预测都**完全可追溯、可解释**——你会看到与当前 K 线最相似的历史片段，以及它们之后发生了什么。
**当前状态**：MVP（最小可行产品）已开源，欢迎社区参与测试、反馈与共建。
---
## ✨ 核心特性
- **端到端流程**：数据加载 → 52 个技术指标计算 → PCA 降维 → ChromaDB 向量存储 → 相似检索 → 预测统计
- **交互式 CLI**：`mizar scan` 命令实时查询个股预测，直观展示相似历史状态及其后续收益
- **回测引擎**：基于 `backtesting.py` 封装，支持单标的、可配置手续费/滑点、自定义信号生成器，输出交互式 HTML 报告
- **RESTful API**：FastAPI 提供查询、健康检查等接口，便于集成到其他系统
- **模块化设计**：特征工程、向量库、回测、服务层解耦，预留 FAISS / Milvus 适配器接口，易于扩展
---
### 核心理念与比较优势
Mizarα 的内核哲学是：**“若当前市场状态与历史上某一状态高度相似，则未来走势具有统计上的可复用性。”** 相较于传统策略，其根本差异体现在：
| 维度 | Mizarα（相似性检索） | 传统多因子模型 | 监督学习（LGB/LSTM） | 规则式策略 |
| :--- | :--- | :--- | :--- | :--- |
| **可解释性** | ⭐⭐⭐⭐⭐ 直接展示相似K线 | ⭐⭐⭐ 需归因分析 | ⭐ 黑箱 | ⭐⭐⭐⭐ 逻辑简单 |
| **非线性捕捉** | ⭐⭐⭐⭐ 天然支持 | ⭐⭐ 依赖因子工程 | ⭐⭐⭐⭐ 可学习复杂边界 | ⭐ 仅线性逻辑 |
| **过拟合风险** | ⭐⭐⭐ 中等（依赖K/Decay调参） | ⭐⭐ 低（因子半衰期长） | ⭐ 高（需大量正则化） | ⭐⭐⭐ 低（参数少） |
| **市场适应性** | ⭐⭐⭐ 依赖向量库覆盖度 | ⭐⭐⭐⭐ 风格中性好 | ⭐⭐⭐ 需定期重训 | ⭐⭐ 易失效 |
| **跨标的泛化** | ⭐⭐⭐⭐ 可借用全市场记忆 | ⭐⭐⭐ 因子普适 | ⭐⭐ 单标的样本稀疏 | ⭐ 仅针对单一标的 |
| **极端行情表现** | ⭐⭐ 预测易跳跃（样本稀疏） | ⭐⭐⭐ 较稳健 | ⭐⭐ 易误判 | ⭐ 常失效 |
---
## 🚀 快速开始
### 环境要求
- Python 3.11+
- TA-Lib（请参考 [TA-Lib 安装指南](https://github.com/TA-Lib/ta-lib-python)）
### 安装
```bash
git clone https://github.com/jiangtaovan/mizar-alpha.git
cd mizar-alpha
pip install -r requirements.txt
pip install -e . # 使 mizar 命令全局可用
准备日线行情数据（CSV 格式，需包含 date,open,high,low,close,volume 列，且已前复权），放入 storage/quotes/ 目录。
mizar build --market A_sharemizar scan输入股票代码（如 000001.SZ）即可查看预测结果及最相似历史状态。
执行 mizar scan 并输入股票代码 688256 后，系统输出示例如下：
- 查询代码：688256
- 查询时间：2026-04-09
- 检索参数：top_k=10，加权方式=distance
- 样本标签分布：小跌 2 个、小涨 5 个、震荡 3 个
核心信号
- 上涨概率：55.36%
- 次日预期收益：+0.16%
- 波动率：0.68%
- 置信度：0.558
5日预期统计
- 收益均值：-1.55%
- 收益中位数：-1.77%
- 下行风险（VaR 90%）：-3.35%
- 上行潜力（90%分位）：-0.33%
Top 5 相似历史状态
| 日期 | 标的 | 标签 | 次日收益 | 5日收益 | 距离 |
|---|---|---|---|---|---|
| 2025-08-25 | 600519 | 小跌 | -0.59% | -0.95% | 0.0030 |
| 2025-07-22 | 600519 | 小涨 | +0.72% | -1.77% | 0.0035 |
| 2025-03-14 | 600519 | 小涨 | +0.61% | -3.33% | 0.0050 |
| 2025-03-17 | 600519 | 小跌 | -0.85% | -3.35% | 0.0082 |
| 2025-09-09 | 600519 | 小涨 | +1.13% | -0.33% | 0.0084 |
# 编辑 config/backtest_config.yaml 配置策略参数后执行
mizar backtest --symbol 000001回测结果（指标、交易记录、权益曲线、HTML 报告）将保存在 storage/backtest_results/。
python main.py访问 http://localhost:8000/docs 查看 Swagger 交互文档。
mizar-alpha/
├── mizar/ # 核心源码
│ ├── cli/ # 命令行入口（mizar 命令）
│ ├── core/ # 特征工程、向量检索核心逻辑
│ ├── back/ # 回测引擎封装（基于 backtesting.py）
│ ├── api/ # FastAPI 服务
│ ├── data/ # 行情获取与处理
│ └── services/ # 预测服务层
├── config/ # 配置文件（YAML）
├── storage/ # 本地数据存储（行情、向量库、回测输出）
├── models/ # 训练好的 scaler / pca 模型
├── scripts/ # 辅助脚本（构建、更新、预处理）
├── tests/ # 单元测试
├── requirements.txt
├── LICENSE
├── CHANGELOG.md
└── README.md
以下为基于 Mizarα 相似性策略在中国中车（601766）上的回测表现：
| 指标 | 数值 |
|---|---|
| 标的 | 601766（中国中车） |
| 回测区间 | 2023-05-24 至 2026-03-25 |
| 累计收益率 | 43.28% |
| 年化收益率 | 13.5% |
| 夏普比率 | 0.92 |
| 最大回撤 | -12.3% |
| 胜率 | 49.12% |
| 盈亏比 | 1.38 |
| 交易次数 | 114 |
注1：结果已扣除双边 0.3% 交易成本，采用全仓逐笔复利模拟。
注2：上述结果为未调优的基准策略，仅供展示。实际表现依赖参数与数据质量。
我们欢迎任何形式的贡献！请阅读 CONTRIBUTING.md 了解行为准则与提交流程。
以下方向尤其需要社区帮助：
- 回测统计逻辑增强与单元测试
- 风险控制模块（止损、仓位管理）
- 参数优化工具（网格搜索、贝叶斯优化）
- 向量库维护策略（滑动窗口淘汰、增量更新）
- 更多向量数据库适配器（FAISS、Milvus）
Mizarα 是实验性研究项目，不构成任何投资建议。历史回测结果不代表未来收益。直接用于实盘交易可能导致重大损失。项目作者及贡献者不对任何投资损失承担责任。
使用本项目即表示您已理解并接受上述风险。
本项目采用 Apache License 2.0。
Mizarα 在启动时会显示 ASCII 艺术 Logo 及版权信息。根据 Apache 2.0 许可证，您可以在修改代码后自由分发，但必须保留原始版权声明和许可证副本。为此，Mizarα 内置了一个轻量级完整性校验：
- 如果您使用官方发布版，将显示完整的艺术 Logo。
- 如果您修改了与品牌标识相关的部分，程序仍会正常运行，但会显示一个简化的文本标识，以履行许可证的声明义务。
这并非限制您的自由，而是帮助您合规地使用本项目。
Mizarα 的诞生离不开以下优秀开源项目：
- ChromaDB - 向量数据库
- TA-Lib - 技术指标库
- backtesting.py - 回测框架
- FastAPI - Web 框架
- mootdx - A股行情数据接口
观往知来，格物致知。
愿 Mizarα 成为你探索量化世界的一盏微光。