AI 生成回测因子 API 文档

把一段自然语言的策略/想法，通过大模型生成本站可回测的因子表达式。共两步：生成（即保存）→ 预览回测。 本文档为面向使用者的说明；完整接口定义见 Swagger /docs。

1. 生成候选（即保存）

curl -X POST http://localhost:8000/api/ai/factor \
  -H "Content-Type: application/json" \
  -d '{"description": "低波动稳健，偏好波动率低的股票"}'

# Python
import requests
r = requests.post("http://localhost:8000/api/ai/factor",
                  json={"description": "低波动稳健，偏好波动率低的股票"})
print(r.json())

响应包含 factor_id、raw（expression/name/category/description）与 validation（ok、fields、lookback、canonical）。若 validation.ok 为 false， 表达式不可回测（被白名单拦截）。因子已自动保存为私有因子，可在「我的因子」查看。

2. 预览回测（登录用户）

curl -X POST http://localhost:8000/api/ai/factor/preview \
  -H "Content-Type: application/json" \
  -d '{"factor_id": "ai_xxxx"}'

返回近一年回测的 metrics（年化收益/夏普/最大回撤/胜率/换手等）与近 6 年 yearly 年度明细。此操作不落库，绑定本人因子，可安全反复试跑（不计额度）。

错误码

接入真实模型

通过环境变量切换（任选一个 OpenAI 兼容服务，如 OpenAI / DeepSeek / 通义等）：

# openai 兼容
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# 示例：DeepSeek
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat

配置后重启服务即走真实模型；未配置时生成接口返回 503（不再伪造数据）。内部测试环境可设 GPZS_AI_DEMO=1 启用演示模式。

管理端：AI 自动因子工厂

管理员可在「管理后台 → AI 因子工厂」（/admin/ai-factory）一键运行 生成 → 发布入库 → 邮件通知 完整轮次：AI 按本站操作符与数据字段自动组合具有经济学意义的因子， 先生成候选存入数据库（同表达式去重、打标记避免重复生成），计算绩效后加入公共因子库（source='ai_auto'）， 并向所有绑定邮箱用户发送「网站更新了 N 个因子」通知邮件（按轮次去重）。每天默认 18:00 自动跑一轮 （GPZS_AI_FACTORY_TIME 可调，未配置有效 OPENAI_API_KEY 时自动跳过）。 以下接口均仅管理员可调用（生成/发布为后台异步执行，前端轮询 stats / candidates 查看结果）：