# quant-pyapp

**Repository Path**: yang-bo1118/quant-pyapp

## Basic Information

- **Project Name**: quant-pyapp
- **Description**: 参数寻优--------
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# parameter_optimization

参数调优系统中的 **Optimizer（寻优执行节点）** Python 实现：接收 Manager 下发的寻优任务，动态创建并管理算法实例（Optuna / pymoo），通过 ask/tell 与 Manager 交互，完成参数搜索。

```
Manager (Java)  ──Kafka COMMAND──▶  Optimizer (Python)  ──本地调用──▶  Optuna / pymoo
                ◀──Kafka RESULT──                          ◀─────────────
                     Redis（多节点 owner 协调）
```

## 功能概览

- **算法适配器**：统一 `BaseAlgorithm` 接口，屏蔽 Optuna / pymoo 差异
- **实例管理**：按 `(optimize_instance_id, batch_id)` 路由，支持并发多实例
- **消息传输**：Kafka COMMAND / RESULT（camelCase 线格式 ↔ 内部 snake_case JSON）
- **多节点协调**：Redis owner 租约 + commandId 幂等，仅 owner 节点处理同一业务键
- **生命周期维护**：实例 destroy 时释放 owner；后台 idle TTL 回收僵尸实例

### 已注册算法

| `algorithm_type` | 底层实现 |
|------------------|----------|
| `贝叶斯算法` | Optuna TPE |
| `遗传算法` | pymoo GA / NSGA-II |
| `网格搜索` | Optuna GridSampler |

新增算法：在 `algorithms/adapters/` 中用 `@register("名称")` 装饰 Adapter 类即可。

## 环境要求

- Python **3.10+**（勿用系统自带的 3.7）
- Redis Cluster（生产 / 多节点）
- Kafka（生产服务；本地测试可先起 mock 或本地 Kafka）

## 快速开始

```bash
cd parameter_optimization
python3.10 -m venv .venv
source .venv/bin/activate

# 推荐用国内镜像（项目根目录有 pip.conf）
PIP_CONFIG_FILE=pip.conf python -m pip install -r requirements.txt

# 或直接指定镜像
python -m pip install -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn
```

> 装包请用 `python -m pip`，避免 `.venv/bin/pip` shebang 指向错误环境。

运行时**只读** `config/config.yaml`。`config.dev.yaml` / `config.prod.yaml` 供对照，需手动合并进 `config.yaml` 后生效。

## 启动生产服务

1. 编辑 `config/config.yaml` 的 `optimizer` 段（Redis、Kafka topic、brokers 等）
2. 按需合并 `config.prod.yaml` 中的 logging / optimizer 配置
3. 启动：

```bash
# 本地开发（venv）
.venv/bin/python gate/run_optimizer.py

# 内网 / 生产：Miniforge 环境名默认 opt，或先 conda activate opt
./scripts/start_optimizer.sh
# 显式指定: OPTIMIZER_PYTHON=$HOME/miniforge3/envs/opt/bin/python ./scripts/start_optimizer.sh
```

多节点部署时，每个进程的 **node_id 默认取本机主机名**（`optimizer.runtime.app.service.default_node_id`），Kafka consumer group 与 Redis owner 均以此标识。

### 运行时组件

| 组件 | 配置键 | 作用 |
|------|--------|------|
| Kafka | `optimizer.messaging.*` | 订阅 COMMAND、发布 RESULT |
| Redis | `optimizer.redis.*` | owner 租约、commandId 去重、meta 观测 |
| 线程池 | `optimizer.service.pool_size` | Dispatcher 并发处理 |
| 空闲扫描 | `maintenance_interval_sec` / `idle_ttl_sec` | 后台 idle 实例回收 |

### 多节点协调（Redis）

| Key | 作用 |
|-----|------|
| `opt:owner:{opt}:{batch}` | 跨节点路由：谁拥有该业务键 |
| `opt:cmd:{commandId}` | owner 侧 Kafka 重投幂等（SET NX） |
| `opt:meta:{opt}:{batch}` | 运维观测（`alg_id`、`node_id`、`ts`） |

CONFIG 路由顺序：`has_capacity_for` → `acquire_owner` → `commit_slot` → `try_claim_command` → `submit`。实例正常结束 / 失败 / 取消 / shutdown 时 `destroy` 会释放 owner 与 meta。owner TTL 默认 86400s，不做续租；任务应在 TTL 内完成。

## 内网 / 离线部署（麒麟 v10 等）

**不能把开发机（macOS）的 `.venv` 直接拷到 Linux 生产环境。** `numpy`、`scipy`、`confluent-kafka` 等含平台相关二进制 wheel，必须在**与生产同架构的 Linux 构建机**上下载。

### 在有网构建机打包（推荐与生产同为麒麟 v10 + Python 3.10）

```bash
mkdir -p optimizer-offline/{wheels,src}
cp -r . src/parameter_optimization    # 勿包含 .venv、logs

python3.10 -m pip download \
  -r src/parameter_optimization/requirements.txt \
  -d wheels \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

tar czf optimizer-offline-$(uname -m).tar.gz wheels src
```

### 在内网生产机安装（Miniforge，无需 sudo）

```bash
tar xzf optimizer-offline-x86_64.tar.gz
cd optimizer-offline

# 一次性：Miniforge 装到用户目录
bash Miniforge3-Linux-x86_64.sh -b -p $HOME/miniforge3
$HOME/miniforge3/bin/conda create -n opt python=3.10 -y

$HOME/miniforge3/envs/opt/bin/pip install --no-index \
  --find-links=wheels \
  -r src/parameter_optimization/requirements.txt

cd src/parameter_optimization
# 合并 config.prod.yaml → config/config.yaml 后
./scripts/start_optimizer.sh
# 脚本会自动用 ~/miniforge3/envs/opt/bin/python（或通过 OPTIMIZER_PYTHON 指定）
```

有系统 Python 3.10 + sudo 时，也可用 `python3.10 -m venv .venv`；**勿把 macOS 的 `.venv` 拷到 Linux。**

打包前在构建机用 `python -c "import numpy, scipy, pymoo, confluent_kafka"` 验证；`uname -m`（x86_64 / aarch64）须与生产一致。

## 集成测试 / Debug

Mock 与集成测试读 **`tests/config/config.yaml`**（Redis 须为 **Cluster**）。本地可先起单节点 cluster：

```bash
./scripts/setup_local_redis_cluster.sh
./scripts/setup_local_kafka.sh          # 集成测试需要时
```

再运行 debug：

```bash
.venv/bin/python -m tests.integration.optimizer.runtime.app.debug_service_flow --preset grid_simple -v
.venv/bin/python -m tests.mock.optimizer.runtime.app.debug_service_flow --preset bayes_multi -v --step manual
```

## 项目结构

```
parameter_optimization/
├── gate/run_optimizer.py       # CLI 入口
├── config/
│   ├── config.yaml             # 运行时唯一配置入口
│   ├── config.dev.yaml         # 开发环境模板
│   ├── config.prod.yaml        # 生产环境模板
│   └── settings.py             # OptimizerSettings 解析
├── common/constants.py         # 配置键名、Redis key 前缀等
├── log/                        # 日志 bootstrap、trace、业务前缀
├── algorithms/
│   ├── base.py                 # 消息 dataclass、BaseAlgorithm
│   ├── registry.py             # @register 注册表
│   ├── adapters/               # 算法 Adapter
│   └── impl/                   # Optuna / pymoo 具体实现
├── optimizer/
│   ├── core/                   # Dispatcher、InstanceManager、内部 codec
│   └── runtime/                # 生产运行时
│       ├── app/service.py      # OptimizerService 装配
│       ├── bus/                # MessagingBus + Kafka 实现
│       ├── codec/              # Kafka camelCase 线格式适配
│       ├── coordination/       # Redis owner 协调
│       ├── routing/            # CommandRouter
│       └── publishing/         # ResultPublisher
├── scripts/                    # 启停、本地 Redis/Kafka 脚本
├── tests/                      # mock / integration 测试
├── requirements.txt            # 直接依赖（版本 pin）
└── pip.conf                    # pip 国内镜像（可选）
```

### 两层 codec 说明

| 模块 | 职责 |
|------|------|
| `optimizer/core/codec.py` | 内部 dataclass ↔ JSON（snake_case） |
| `optimizer/runtime/codec/` | Kafka 线格式 camelCase ↔ 内部 JSON |

## 配置参考

### logging

- `root.level: WARNING`：第三方库默认安静
- `loggers.optimizer` / `loggers.algorithms`：`INFO` 开启业务日志
- `console_logging.enabled`：dev 开控制台，prod 可关
- `file_logging.*`：异步落盘 `logs/optimizer.log`（RotatingFileHandler）

### optimizer（见 `config/settings.py` → `OptimizerSettings`）

```yaml
optimizer:
  redis:
    mode: cluster
    nodes:
      - host: redis1
        port: 6379
      - host: redis2
        port: 6379
    owner_ttl_sec: 86400
    command_ttl_sec: 86400
    meta_ttl_sec: 86400
  messaging:
    command_topic: OPTIMIZER_COMMAND
    result_topic: OPTIMIZER_RESULT
    brokers:
      - host: kafka1
        port: 9092
  service:
    pool_size: 8
    max_instances: 1024
    maintenance_interval_sec: 3600
    idle_ttl_sec: 3600
```

## 依赖

见 [requirements.txt](requirements.txt)：

| 包 | 版本 | 说明 |
|----|------|------|
| optuna | 4.9.0 | 贝叶斯 / 网格搜索 |
| pymoo | 0.6.1.6 | 遗传算法（会拉 scipy、matplotlib 等传递依赖） |
| numpy | 2.2.6 | 数值计算 |
| redis | 5.0.8 | Python 客户端（redis-py）；与 Redis 服务端版本号无关 |
| confluent-kafka | 2.13.0 | Kafka 客户端 |
| pydantic | 2.13.4 | 消息校验 |
| PyYAML | 6.0.3 | 配置解析 |

`pymoo` 安装时会自动拉取 `scipy`、`matplotlib` 等较大传递依赖；内网离线部署请用 `pip download` 一次性打全 wheel。