# 出价调整系统实际执行指南

## 演示执行结果 ✓

刚才的演示成功展示了完整的出价调整流程：

### 执行场景
- **昨日消耗**: 522,685 元（模拟数据）
- **今日预算**: 100,000 元
- **缩量幅度**: 81%
- **策略**: aggressive_scale_down（大幅缩量）

### 执行结果
- ✅ **Tier 1（30个）**: 出价 -5%~0%，保护高效广告
- ✅ **Tier 2（70个）**: 出价 -15%，适度缩量
- ✅ **Tier 3（116个）**: 出价 -30%，大幅削减
- ✅ **暂停（79个）**: 样本不足广告全部暂停
- ✅ **总计**: 调整 216 个，暂停 79 个

---

## 实际生产环境部署

### 前置条件

#### 1. 环境变量配置

```bash
# 腾讯广告 API
export TENCENT_AD_ACCESS_TOKEN="your_access_token_here"
export TENCENT_AD_ACCOUNT_ID="123456"
export TENCENT_AD_BASE_URL="https://api.e.qq.com/v3.0"

# ODPS（MaxCompute）数据仓库
export ODPS_ACCESS_ID="your_aliyun_access_key_id"
export ODPS_ACCESS_SECRET="your_aliyun_access_key_secret"
export ODPS_PROJECT="loghubods"
export ODPS_ENDPOINT="http://service.cn-shanghai.maxcompute.aliyun.com/api"
```

#### 2. 依赖安装

```bash
# 进入项目目录
cd /Users/liulidong/project/agent/Agent

# 安装 Python 依赖
pip install -r requirements.txt

# 确保安装了 ODPS 客户端
pip install pyodps

# 确保安装了 HTTP 客户端
pip install httpx
```

#### 3. 数据表准备

确保 ODPS 中存在以下表：

**表 1: `loghubods.creative_detail`**
- 字段：ad_id, ad_name, 首层小程序打开数, 裂变0层回流数, cost 等
- 分区：bizdate（格式：YYYYMMDD）

**表 2: `loghubods.ad_put_tencent_ad`**
- 字段：ad_id, ad_name, account_id, bid_amount, day_amount, ad_status, optimization_goal, targeting, create_time
- 说明：存储广告当前状态

---

## 执行方式

### 方式 1: 交互式执行（推荐）

```bash
# 启动 Agent 系统
python examples/auto_put_ad/run.py

# 在交互界面输入
> 账户 123456 今日预算 10 万，帮我调整出价
```

**系统流程：**
1. Budget Agent 自动调用 `budget_calculate_from_data`
2. 从 ODPS 拉取昨日效率数据和当前广告状态
3. 计算出价调整方案并展示
4. 等待用户确认
5. 用户输入"确认"后，调用 `bid_adjustment_execute` 执行
6. 报告执行结果

### 方式 2: 程序化调用

```python
import asyncio
from examples.auto_put_ad.tools.budget_calc import (
    budget_calculate_from_data,
    bid_adjustment_execute
)

async def main():
    # 步骤 1: 计算方案
    result = await budget_calculate_from_data(
        account_id=123456,
        total_budget_yuan=100000,
        bizdate="20260406"  # 或 "yesterday"
    )

    # 步骤 2: 展示方案
    print(result.output)

    # 步骤 3: 等待确认
    confirm = input("\n是否执行？(y/n): ")

    if confirm.lower() == 'y':
        # 步骤 4: 执行调整
        exec_result = await bid_adjustment_execute(
            adjustment_plan=result.data["adjustment_plan"],
            account_id=123456
        )
        print(exec_result.output)

if __name__ == "__main__":
    asyncio.run(main())
```

### 方式 3: 定时任务（自动化）

```bash
# 创建定时脚本
cat > /path/to/daily_bid_adjustment.sh << 'EOF'
#!/bin/bash
cd /Users/liulidong/project/agent/Agent
source venv/bin/activate

# 设置环境变量
export TENCENT_AD_ACCESS_TOKEN="..."
export ODPS_ACCESS_ID="..."
export ODPS_ACCESS_SECRET="..."

# 执行调整（需要实现自动确认逻辑）
python examples/auto_put_ad/auto_bid_adjustment.py \
    --account-id 123456 \
    --budget 100000 \
    --auto-confirm
EOF

chmod +x /path/to/daily_bid_adjustment.sh

# 添加到 crontab（每天早上 9:00 执行）
crontab -e
# 添加：0 9 * * * /path/to/daily_bid_adjustment.sh >> /var/log/bid_adjustment.log 2>&1
```

---

## 执行检查清单

### 执行前检查

- [ ] 环境变量已配置（TENCENT_AD_ACCESS_TOKEN, ODPS_ACCESS_ID 等）
- [ ] ODPS 数据表存在且有最新数据
- [ ] 腾讯广告 API 凭证有效（未过期）
- [ ] 账户余额充足（>= 今日预算 × 1.2）
- [ ] 网络连接正常（可访问腾讯广告 API 和 ODPS）

### 执行中监控

- [ ] 数据拉取成功（昨日效率数据 + 当前广告状态）
- [ ] 策略判断合理（缩量/扩量幅度符合预期）
- [ ] 分层结果正确（Tier 1/2/3 数量合理）
- [ ] 出价调整幅度在预期范围内
- [ ] 暂停广告数量可接受

### 执行后验证

- [ ] 检查执行结果（成功/失败数量）
- [ ] 抽查几个广告的出价是否已更新
- [ ] 监控实时消耗速度（是否符合预期）
- [ ] 记录调整历史（用于后续分析）

---

## 常见问题处理

### 1. ODPS 连接失败

**错误信息：**
```
ODPS 客户端初始化失败: Invalid access key
```

**解决方案：**
```bash
# 检查环境变量
echo $ODPS_ACCESS_ID
echo $ODPS_ACCESS_SECRET

# 重新设置
export ODPS_ACCESS_ID="your_correct_access_key_id"
export ODPS_ACCESS_SECRET="your_correct_access_key_secret"
```

### 2. 腾讯广告 API 调用失败

**错误信息：**
```
ad_update 失败: Invalid access token
```

**解决方案：**
```bash
# 检查 token 是否过期
# 重新获取 access_token（通过 OAuth2 流程）
export TENCENT_AD_ACCESS_TOKEN="new_access_token"
```

### 3. 数据查询为空

**错误信息：**
```
查询到 0 个广告的昨日效率数据
```

**解决方案：**
```python
# 检查 bizdate 是否正确
# 检查 account_id 是否正确
# 检查数据表分区是否存在

# 手动查询验证
from examples.auto_put_ad.tools.data_query import data_query

result = await data_query(
    table_name="creative_detail",
    bizdate="20260406",
    account_id=123456
)
print(result.output)
```

### 4. 批量执行超时

**错误信息：**
```
bid_adjustment_execute 超时
```

**解决方案：**
```python
# 分批执行（每批 50 个广告）
adjustment_plan = result.data["adjustment_plan"]

for i in range(0, len(adjustment_plan), 50):
    batch = adjustment_plan[i:i+50]
    await bid_adjustment_execute(
        adjustment_plan=batch,
        account_id=123456
    )
    await asyncio.sleep(6)  # QPS 限制：10/秒，休息 6 秒
```

---

## 监控与优化

### 1. 实时监控指标

```python
# 监控脚本示例
import asyncio
from examples.auto_put_ad.tools.ad_api import ad_get_report

async def monitor_realtime():
    """监控实时消耗"""
    while True:
        result = await ad_get_report(
            account_id=123456,
            date_range="today",
            level="ad"
        )

        # 解析消耗数据
        total_cost = sum(ad["cost"] for ad in result.data)
        print(f"当前消耗: {total_cost/100:.2f} 元")

        await asyncio.sleep(300)  # 每 5 分钟检查一次

asyncio.run(monitor_realtime())
```

### 2. 效果评估

**关键指标：**
- 实际消耗 vs 预算目标（偏差 <5%）
- 各层级广告表现（Tier 1 ROI 是否保持）
- 整体 ROI 变化（是否提升）
- 暂停广告数量（是否合理）

**评估周期：**
- 短期（2-4 小时）：消耗速度是否符合预期
- 中期（1 天）：整体 ROI 是否达标
- 长期（7 天）：策略效果是否稳定

### 3. 策略优化

**根据效果调整参数：**

```python
# 如果消耗过快，增加缩量幅度
result = await budget_calculate_from_data(
    account_id=123456,
    total_budget_yuan=80000,  # 降低预算
    tier1_ratio=0.10,  # 减少 Tier 1 占比
)

# 如果消耗过慢，减少缩量幅度
result = await budget_calculate_from_data(
    account_id=123456,
    total_budget_yuan=120000,  # 提高预算
    tier1_ratio=0.20,  # 增加 Tier 1 占比
)
```

---

## 安全建议

### 1. 权限控制
- 限制 API 凭证访问权限
- 使用只读账号查询数据
- 执行操作需要二次确认

### 2. 数据备份
- 执行前备份当前广告状态
- 记录每次调整的详细日志
- 保留历史调整方案（用于回滚）

### 3. 异常处理
- 设置消耗上限告警
- 监控异常广告（消耗突增）
- 准备紧急暂停脚本

```python
# 紧急暂停所有广告
from examples.auto_put_ad.tools.ad_api import ad_batch_update_status

await ad_batch_update_status(
    account_id=123456,
    adgroup_ids=[...],  # 所有广告 ID
    configured_status="AD_STATUS_SUSPEND"
)
```

---

## 总结

✅ **系统已就绪**：核心功能已实现并测试通过

✅ **演示成功**：模拟数据执行流程完整

✅ **文档完善**：提供详细的部署和执行指南

**下一步行动：**
1. 配置生产环境变量
2. 验证数据表连接
3. 小规模测试（10-20 个广告）
4. 全量执行并监控效果
5. 根据效果优化策略参数

---

**文档版本**: v1.0
**更新日期**: 2026-04-07
**联系人**: liulidong