myTestFreqAI/doc/hyperopt.md

# Hyperopt 脚本使用指南

## 概述

本项目包含两个超参数优化脚本：`hyperopt.sh` 和 `hyperopt_org.sh`，用于自动化超参数优化，支持多种参数配置方式，能够自动匹配策略和配置文件。

## 脚本位置

```bash
/Users/zhangkun/myTestFreqAI/tools/hyperopt.sh
/Users/zhangkun/myTestFreqAI/tools/hyperopt_org.sh
```

## 脚本区别

| 脚本 | 功能特点 | 适用场景 |
|------|----------|----------|
| `hyperopt.sh` | 支持从远程API获取交易对，更智能的交易对处理 | 需要动态交易对优化的场景 |
| `hyperopt_org.sh` | 使用固定交易对列表，更稳定的优化过程 | 固定交易对组合的优化 |

## 环境配置

### .env 文件

脚本依赖 `.env` 文件设置默认参数，位于 `tools/.env`：

```bash
STRATEGY_NAME=TheForceV7
CONFIG_FILE=basic.json
TEST_BRANCH=theforce-noai-test
DRYRUN_BRANCH=theforce-noai-dryrun
```

### 可用策略和配置

#### 策略文件 (.py)
- 位置：`freqtrade/templates/`
- 当前可用：`freqaiprimer.py`, `TheForceV7.py`

#### 配置文件 (.json)
- 位置：`config_examples/`
- 可用配置：
  - `basic.json` - 基础配置
  - `config.json` - 标准配置
  - `freqaiprimer.json` - FreqAI策略配置
  - `live.json` - 实盘配置
  - `theforcev7.json` - TheForceV7策略配置

## 使用方法

### 1. 使用默认配置（最简单）

```bash
cd tools/
./hyperopt.sh
# 或
./hyperopt_org.sh
```

**默认行为：**
- 策略：`TheForceV7`
- 配置：`basic.json`
- 时间范围：最近2天到明天
- 交易对：默认USDT交易对列表

### 2. 省略 --config 参数（推荐）

```bash
./hyperopt.sh --strategy freqaiprimer
# 或
./hyperopt_org.sh --strategy freqaiprimer
```

脚本会自动匹配同名配置文件 `freqaiprimer.json`，如果不存在则使用 `basic.json`。

### 3. 完整参数配置

```bash
./hyperopt.sh --strategy freqaiprimer --config freqaiprimer.json --start-date "2024-01-01" --end-date "2024-12-31" --pairs "BTC/USDT ETH/USDT"
```

### 4. 位置参数方式

```bash
./hyperopt.sh "2024-01-01" "2024-12-31" freqaiprimer
# 或
./hyperopt_org.sh "2024-01-01" "2024-12-31" freqaiprimer
```

## 参数详解

### 命名参数

| 参数 | 简化参数 | 说明 | 示例 |
|------|----------|------|------|
| `--strategy` | `-t` | 策略名称（可省略.py后缀） | `--strategy freqaiprimer` 或 `-t freqaiprimer` |
| `--config` | - | 配置文件名称（可选） | `--config freqaiprimer.json` |
| `--start-date` | - | 开始时间 | `--start-date "2024-01-01"` |
| `--end-date` | - | 结束时间 | `--end-date "2024-12-31"` |
| `--pairs` | - | 交易对列表 | `--pairs "BTC/USDT ETH/USDT"` |
| `--pairRemoteList` | - | 远程交易对API | `--pairRemoteList http://api.example.com/pairs` |

### 时间格式支持

- **标准格式**：`"2024-01-01 00:00:00"`
- **简写格式**：`20240101`（自动转换为 `2024-01-01 00:00:00`）

### 交易对优先级

#### hyperopt.sh 的交易对获取优先级：
1. `--pairRemoteList` - 远程API获取交易对
2. `--pairs` - 手动指定交易对
3. 远程主API（带日期参数）
4. 默认交易对列表

#### hyperopt_org.sh 的交易对获取优先级：
1. `--pairRemoteList` - 远程API获取交易对
2. `--pairs` - 手动指定交易对
3. 默认交易对列表

## 配置文件自动匹配

脚本支持智能配置文件匹配：

```bash
# 自动匹配 freqaiprimer.json
./hyperopt.sh --strategy freqaiprimer

# 如果 freqaiprimer.json 不存在，自动回退到 basic.json
./hyperopt.sh --strategy nonexistent_strategy
```

## 超参数优化配置

### 优化参数

- **迭代次数**：`-e 500`（默认500次迭代）
- **并行进程**：`-j 4`（默认4个进程）
- **优化空间**：`--spaces buy sell`（买卖参数优化）
- **损失函数**：`--hyperopt-loss SharpeHyperOptLossDaily`（夏普比率优化）

### 优化目标

脚本默认优化以下目标：
- 最大化夏普比率
- 优化买卖参数
- 考虑交易费用（0.0016）

## 运行示例

### 示例1：测试FreqAI策略优化（使用简化参数）

```bash
# 使用 -t 简化参数
./hyperopt.sh -t freqaiprimer

# 或者使用完整参数
./hyperopt.sh --strategy freqaiprimer
```

### 示例2：指定时间范围优化

```bash
# 使用 -t 简化参数
./hyperopt.sh -t freqaiprimer --start-date "2024-06-01" --end-date "2024-06-30"

# 或者使用完整参数
./hyperopt.sh --strategy freqaiprimer --start-date "2024-06-01" --end-date "2024-06-30"
```

### 示例3：指定交易对优化

```bash
# 使用 -t 简化参数
./hyperopt.sh -t freqaiprimer --pairs "BTC/USDT ETH/USDT SOL/USDT"

# 或者使用完整参数
./hyperopt.sh --strategy freqaiprimer --pairs "BTC/USDT ETH/USDT SOL/USDT"
```

### 示例4：从远程API获取交易对优化

```bash
# 使用 -t 简化参数
./hyperopt.sh -t freqaiprimer --pairRemoteList "http://api.example.com/pairlist"

# 或者使用完整参数
./hyperopt.sh --strategy freqaiprimer --pairRemoteList "http://api.example.com/pairlist"
```

## 运行步骤

1. **进入工具目录**
   ```bash
   cd /Users/zhangkun/myTestFreqAI/tools
   ```

2. **赋予执行权限**（首次使用）
   ```bash
   chmod +x hyperopt.sh hyperopt_org.sh
   ```

3. **运行脚本**
   ```bash
   ./hyperopt.sh [参数]
   # 或
   ./hyperopt_org.sh [参数]
   ```

4. **查看结果**
   - 实时日志：控制台输出
   - 优化结果：`user_data/hyperopt_results/` 目录
   - 模型文件：`user_data/models/` 目录

## 输出文件

- **优化结果**：`user_data/hyperopt_results/`
  - JSON格式的优化结果
  - 最佳参数组合
- **模型文件**：`user_data/models/`
  - 训练好的机器学习模型
- **日志文件**：`freqtrade/user_data/logs/freqtrade.log`

## 注意事项

1. **Docker环境**：脚本使用Docker运行超参数优化，确保Docker服务已启动
2. **配置文件加载**：脚本会自动加载 `config_examples/` 和 `freqtrade/templates/` 目录的配置文件
3. **时间格式**：支持多种时间格式，建议使用标准格式避免歧义
4. **交易对格式**：使用 `/` 分隔符，如 `BTC/USDT`
5. **错误处理**：如果配置文件不存在，脚本会自动回退到默认配置
6. **优化时间**：超参数优化可能需要较长时间，建议在服务器上运行

## 故障排除

### 常见问题

1. **策略文件不存在**
   ```bash
   # 检查可用策略
   ls ../freqtrade/templates/*.py
   ```

2. **配置文件不存在**
   ```bash
   # 检查可用配置
   ls ../config_examples/*.json
   ```

3. **Docker服务未启动**
   ```bash
   # 启动Docker服务
   sudo systemctl start docker
   # 或
   open -a Docker
   ```

4. **权限问题**
   ```bash
   # 赋予执行权限
   chmod +x hyperopt.sh hyperopt_org.sh
   ```

### 性能优化建议

1. **减少迭代次数**：对于快速测试，使用 `-e 100`
2. **减少并行进程**：对于资源受限环境，使用 `-j 2`
3. **缩小优化空间**：只优化关键参数，如 `--spaces sell`
4. **使用更小的数据集**：缩短时间范围

## 高级用法

### 自定义优化参数

```bash
# 自定义迭代次数和并行进程
./hyperopt.sh -t freqaiprimer -e 1000 -j 8

# 自定义优化空间
./hyperopt.sh -t freqaiprimer --spaces buy sell roi stoploss trailing

# 自定义损失函数
./hyperopt.sh -t freqaiprimer --hyperopt-loss OnlyProfitHyperOptLoss
```

### 批量优化

```bash
# 批量优化多个策略
for strategy in freqaiprimer TheForceV7; do
    ./hyperopt.sh -t $strategy
    echo "完成策略 $strategy 的优化"
done
```

通过本指南，您可以充分利用hyperopt脚本进行高效的超参数优化，提升交易策略的性能。