Metadata-Version: 2.4
Name: khy-quant
Version: 1.6.6.250505501
Summary: KHY-Quant quantitative trading system — graduation project edition with full documentation and comments
Author-email: khy-qqb <2578974124@qq.com>
License: MIT
Project-URL: Homepage, https://khyquant.top
Project-URL: Documentation, https://khyquant.top/docs
Project-URL: Repository, https://github.com/khyquant/khy-quant
Project-URL: Issues, https://github.com/khyquant/khy-quant/issues
Keywords: quant,trading,akshare,quantitative-finance,saas
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: JavaScript
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: cffi<3.0.0,>=1.15.0
Provides-Extra: data
Requires-Dist: akshare>=1.12.0; extra == "data"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "data"
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "data"
Provides-Extra: ml
Requires-Dist: khy-quant[data]; extra == "ml"
Requires-Dist: scikit-learn==1.8.0; extra == "ml"
Requires-Dist: xgboost==3.2.0; extra == "ml"
Requires-Dist: lightgbm==4.6.0; extra == "ml"
Requires-Dist: joblib==1.5.3; extra == "ml"
Requires-Dist: scipy>=1.10.0; extra == "ml"
Requires-Dist: ta>=0.11.0; extra == "ml"
Requires-Dist: tqdm>=4.65.0; extra == "ml"
Requires-Dist: pyyaml>=6.0; extra == "ml"
Requires-Dist: loguru>=0.7.0; extra == "ml"
Provides-Extra: frontend
Requires-Dist: khy-quant-frontend>=1.6.0; extra == "frontend"
Provides-Extra: backend
Requires-Dist: khy-quant-backend>=1.6.0; extra == "backend"
Provides-Extra: full
Requires-Dist: khy-quant[data]; extra == "full"
Requires-Dist: khy-quant[ml]; extra == "full"
Provides-Extra: all
Requires-Dist: khy-quant[full]; extra == "all"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://khyquant.top/logo.png" alt="KHY-Quant Logo" width="120">
</p>

<h1 align="center">KHY-Quant 量化交易系统</h1>

<p align="center">
  <strong>模块化 · 智能化 · 开箱即用的中文量化交易平台</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/khy-quant/"><img src="https://img.shields.io/pypi/v/khy-quant.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/khy-quant/"><img src="https://img.shields.io/pypi/pyversions/khy-quant.svg" alt="Python"></a>
  <a href="https://github.com/khyquant/khy-quant/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  <a href="https://khyquant.top"><img src="https://img.shields.io/badge/官网-khyquant.top-green.svg" alt="Website"></a>
</p>

<p align="center">
  <a href="#快速开始">快速开始</a> •
  <a href="#功能特性">功能特性</a> •
  <a href="#命令参考">命令参考</a> •
  <a href="#ai-能力">AI 能力</a> •
  <a href="#生态社区">生态社区</a>
</p>

---

## 概述

KHY-Quant 是一套面向中国 A 股市场的智能量化交易系统，集成了数据获取、策略回测、AI 分析、模型训练和实盘交易等完整链路。通过简洁的命令行界面（CLI），支持中文/拼音/英文多种输入方式，让量化交易触手可及。

**核心优势：**
- 🇨🇳 完整中文支持 — 命令、提示、文档全中文化
- 🤖 内置 AI 网关 — 支持 10+ 大模型提供商，一键切换
- 📊 专业回测引擎 — 支持多种策略的历史回测
- 🔧 开箱即用 — 一条命令安装，无需复杂配置
- 🌐 SaaS 就绪 — 支持云端部署和多用户管理

---

## 快速开始

### 环境要求

- Python >= 3.8
- Node.js >= 18（安装时自动检测）
- 操作系统: Linux / macOS / Windows

### 安装

```bash
# 基础安装（CLI + 回测 + 数据）
pip install khy-quant

# 包含机器学习策略
pip install khy-quant[ml]

# 完整安装（所有功能）
pip install khy-quant[full]
```

### 答辩友好打包说明（本版本固定）

本版本的 `pip` 打包**固定为不混淆**，始终保留源码注释与目录结构可读性，便于毕业答辩展示与代码讲解。

```bash
# 可读源码安装（推荐答辩）
pip install -e .[full]
```

### 首次启动

```bash
# 启动交互式 CLI
khy

# 或使用完整命令名
khy-quant
```

首次启动时系统会自动执行初始化：
1. 检测 Node.js 环境
2. 安装 npm 依赖
3. 初始化数据库
4. 配置 AI 网关

### 快速体验

```bash
# 查看股票行情
khy quote sh600519      # 或: hq 茅台

# 回测策略
khy backtest sh600519   # 或: bt sh600519

# AI 分析
khy analyze sh600519    # 或: fx sh600519

# 启动 Web 界面
khy server start        # 或: fw
```

---

## 功能特性

### 📈 数据服务
- A 股实时行情、历史 K 线、财务数据
- 基于 AkShare 的多源数据获取
- 本地缓存加速，支持增量更新

### 📊 策略回测
- 内置多种经典策略（均线、MACD、布林带等）
- 支持自定义策略编写
- 详细的回测报告与可视化

### 🤖 AI 智能分析
- 10+ 大模型提供商支持（OpenAI、Claude、Gemini、通义千问、DeepSeek 等）
- 自然语言交互，中文对话分析
- 智能策略推荐

### 🧠 模型训练
- 基于用户交互数据自动记录训练语料
- 支持 LoRA/QLoRA 微调
- 支持知识蒸馏（大模型 → 小模型）
- 模型导出为 GGUF（Ollama）/ safetensors（HuggingFace）格式
- 训练后模型命名: `khy-1.0`, `khy-2.0`, ... 自动递增

### 🔄 中转站兼容
- 支持 API 中转/代理配置
- Claude/OpenAI 等模型通过中转即可使用
- khy 训练模型同样支持中转部署

### 💰 用量统计
- 实时 token 消耗追踪
- 人民币计价（¥）的费用统计
- 按日/月/会话维度汇总

### 🖥️ Web 前端
- 专业交易看板
- K 线图表与指标叠加
- 策略可视化配置

---

## 命令参考

KHY-Quant 支持中文、拼音缩写和英文三种输入方式：

| 功能 | 中文 | 拼音 | 英文 |
|------|------|------|------|
| 行情查询 | `行情` | `hq` | `quote` |
| 策略回测 | `回测` | `bt` | `backtest` |
| 策略列表 | `策略` | `cl` | `strategy list` |
| 数据下载 | `下载` | `xz` | `data fetch` |
| AI 分析 | `分析` | `fx` | `analyze` |
| 持仓查看 | `持仓` | `cc` | `position` |
| 下单交易 | `买入/卖出` | `mai/maichu` | `buy/sell` |
| 费用统计 | `费用` | `feiyong` | `cost` |
| 模型训练 | `训练` | `xunlian` | `train` |
| 恢复上下文 | `恢复` | `huifu` | `history resume` |
| 系统更新 | `更新` | `gengxin` | `update` |
| 帮助 | `帮助` | `bz` | `help` |
| 退出 | `退出` | `q` | `exit` |

### 训练子命令

```bash
khy train start          # 开始本地训练
khy train cloud          # 提交云端训练
khy train distill        # 知识蒸馏
khy train status         # 查看训练状态
khy train list           # 列出已训练模型
khy train export gguf    # 导出 GGUF 格式（需密码）
khy train export safetensors  # 导出 safetensors（需密码）
khy train upload github  # 上传到 GitHub
khy train upload gitee   # 上传到 Gitee
khy train data           # 查看训练数据统计
```

### 用量查询

```bash
khy cost                 # 当前会话费用
khy usage                # 本月用量摘要
khy usage today          # 今日用量
khy usage history        # 30天历史
```

---

## AI 能力

### 支持的模型提供商

| 提供商 | 类型 | 配置方式 |
|--------|------|----------|
| OpenAI (GPT-4/3.5) | 云端 | API Key |
| Anthropic (Claude) | 云端 | API Key |
| Google (Gemini) | 云端 | API Key |
| DeepSeek | 云端 | API Key |
| 通义千问 (Qwen) | 云端 | API Key |
| Groq | 云端 | API Key |
| OpenRouter | 云端 | API Key |
| Ollama | 本地 | 自动检测 |
| LM Studio | 本地 | 自动检测 |
| Claude (中转) | 代理 | Relay URL |

### AI 网关配置

```bash
khy gateway status       # 查看网关状态
khy gateway config       # 配置 API Key
khy gateway model        # 选择模型
khy gateway relay        # 配置中转
```

---

## 系统更新

```bash
# 更新到最新版本
khy update
# 或
pip install --upgrade khy-quant
```

系统会自动检测新版本并提示更新。

---

## 项目结构

```
khy-quant/
├── khy_quant/          # Python 包入口
├── backend/            # Node.js 后端服务
│   ├── src/
│   │   ├── cli/        # 命令行交互
│   │   ├── services/   # 核心服务层
│   │   └── routes/     # Web API 路由
│   └── data/           # 策略与配置
├── frontend/           # Vue.js Web 前端
├── scripts/            # 工具脚本
└── docs/               # 文档
```

### 毕业答辩文档入口（新增）

- [论文结构映射](docs/guides/THESIS_ALIGNMENT_MAP.md)
- [答辩讲解稿](docs/guides/DEFENSE_SCRIPT.md)
- [答辩预设问题](docs/guides/DEFENSE_QA.md)
- [pip 打包说明（固定可读源码）](docs/guides/PIP_PACKAGING.md)

### 论文章节 → 代码直达链接

| 论文章节 | 代码入口 |
|------|------|
| 4.1 五层架构与路由设计 | [backend/server.js](backend/server.js) |
| 4.2 接入层与中间件设计 | [backend/server.js](backend/server.js), [backend/src/middleware](backend/src/middleware) |
| 4.3 策略适配层设计 | [backend/src/routes/strategy.js](backend/src/routes/strategy.js), [backend/src/services/strategyEngine.js](backend/src/services/strategyEngine.js) |
| 4.4 多智能体协同层设计 | [backend/src/routes/tradingAgents.js](backend/src/routes/tradingAgents.js), [backend/src/services/tradingAgentsService.js](backend/src/services/tradingAgentsService.js), [backend/src/services/gateway/aiGateway.js](backend/src/services/gateway/aiGateway.js) |
| 4.5 数据治理层设计 | [backend/src/services/akshareDataService.js](backend/src/services/akshareDataService.js), [backend/src/services/marketDataService.js](backend/src/services/marketDataService.js), [backend/src/services/klineDataService.js](backend/src/services/klineDataService.js) |
| 5.5 前端实现与部署 | [frontend/src/router/index.js](frontend/src/router/index.js), [frontend/src/views/Trading.vue](frontend/src/views/Trading.vue), [frontend/src/views/admin/Dashboard.vue](frontend/src/views/admin/Dashboard.vue) |
| Python 启动与 pip 分发 | [khy_quant/cli.py](khy_quant/cli.py), [khy_quant/_bootstrap.py](khy_quant/_bootstrap.py), [setup.py](setup.py) |

---

## 部署方式

### 方式一：pip 安装（推荐）

```bash
pip install khy-quant[full]
khy
```

### 方式二：Docker 部署

```bash
docker compose up --build
```

- 前端: http://localhost:18080
- 后端 API: http://localhost:3000
- 默认账号: admin / admin123

### 方式三：源码部署

```bash
git clone https://github.com/khyquant/khy-quant.git
cd khy-quant
pip install -e .[full]
khy init
khy
```

---

## 生态社区

### 官方资源

| 资源 | 地址 |
|------|------|
| 🌐 官方网站 | [https://khyquant.top](https://khyquant.top) |
| 📖 在线文档 | [https://khyquant.top/docs](https://khyquant.top/docs) |
| 💻 GitHub | [https://github.com/khyquant/khy-quant](https://github.com/khyquant/khy-quant) |
| 📦 PyPI | [https://pypi.org/project/khy-quant/](https://pypi.org/project/khy-quant/) |

### 社区交流

| 渠道 | 信息 |
|------|------|
| 📱 QQ 群 | **1083973296**（量化交流群，入群暗号: khy） |
| 📧 邮箱 | [2578974124@qq.com](mailto:2578974124@qq.com) |
| 🐛 Bug 反馈 | [GitHub Issues](https://github.com/khyquant/khy-quant/issues) |

### 加入我们

我们欢迎所有对量化交易感兴趣的开发者参与贡献：
- 提交 Issue 报告问题或建议新功能
- 提交 Pull Request 贡献代码
- 在 QQ 群内交流策略和使用心得
- 分享你训练的 khy 模型

---

## 常见问题

<details>
<summary><b>安装后提示找不到 Node.js？</b></summary>

KHY-Quant 后端基于 Node.js 运行。请先安装 Node.js >= 18：
```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# macOS
brew install node

# Windows
# 从 https://nodejs.org 下载安装包
```
然后重新运行 `khy`，系统会自动完成初始化。
</details>

<details>
<summary><b>如何配置 AI 模型？</b></summary>

```bash
khy gateway config
```
按照提示输入 API Key 即可。支持 OpenAI、Claude、DeepSeek 等多种提供商。本地模型（Ollama）无需 API Key，安装后自动检测。
</details>

<details>
<summary><b>训练模型需要什么硬件？</b></summary>

- **本地训练**: 建议 NVIDIA GPU (≥ 8GB VRAM) 配合 QLoRA
- **云端训练**: 无硬件要求，使用 KHY 云服务
- **CPU 训练**: 可行但速度较慢，建议小模型 (1.5B-3B)
</details>

<details>
<summary><b>如何恢复之前的对话上下文？</b></summary>

```bash
khy history resume    # 或输入: /huifu
```
系统会自动保存每次对话，支持随时恢复。
</details>

<details>
<summary><b>模型导出需要密码？</b></summary>

是的，为保护训练成果，导出模型（GGUF/safetensors）需要输入导出密码。请在 QQ 群或官方文档中获取。
</details>

---

## 许可证

本项目基于 [MIT License](LICENSE) 开源。

---

<p align="center">
  <sub>Made with ❤️ by KHY-Quant Team | <a href="https://khyquant.top">khyquant.top</a></sub>
</p>
