Agent/examples/tencent_realtime_control

腾讯广告实时调控

独立管理实时投放指标采集、状态判断和腾讯广告调控，不依赖广告创建或历史调价分析流程。

数据和范围

• 从 loghubods.advertiser_data_da_hour 读取当天整体小时数据。
• CPM 直接使用 真实cpm_总。
• 固定过滤名称、广告主、公司、行业、客户和落地页类型均为 SUM。
• 账户只取 ad_creation_account_config.enabled=1 与 account_whitelist.enabled=1 的交集。
• 普通出价使用 bid_amount，最大转化量使用 custom_cost_cap。
• 每条广告首次纳管时将腾讯当前实际出价持久化为基础出价。

调控规则

北京时间每天 07:00-21:00 每 10 分钟检查一次：

• CPM > 250：基础出价上调 25%。
• 190 <= CPM <= 250：恢复基础出价并恢复策略暂停的广告。
• CPM < 190：先恢复基础出价，再暂停广告。
• 同一广告每天最多上调一次；恢复基础价后，当天也不会再次上调。
• 21:00：先恢复基础出价，再暂停广告。
• 次日 07:00：只恢复由本策略暂停的广告，不打开人工暂停广告。

每个真实发生调价或关停动作的窗口会生成一张飞书在线表格并发送到调控群。 群消息包含触发时间、数据分区、当前 CPM、决策、影响账户/广告数、动作分布和 受影响广告当日累计消耗。表格包含日期、数据分区、当前 CPM、账户、广告 ID、 广告名称、人群包、广告当日累计消耗/曝光/点击、基础出价、调整前出价、执行后 当前出价和动作。 同一窗口的所有成功动作合并在一张表中；无动作、dry-run 和已达到当日上调 上限的广告不发送通知。飞书发送失败不会回滚已经成功的腾讯操作，本地 xlsx 仍保存在 outputs/，错误会写入本轮 JSON 报告和进程日志。

腾讯写接口返回 code=0 后不会立即判定成功。流程会按广告 ID 重新读取腾讯 广告并核对本次修改的出价和状态字段，默认最多校验 3 次、间隔 1 秒。只有读回 值与目标一致才更新成功状态并进入成功通知；持续不一致按失败写入动作审计， 飞书卡片标红并在表格中展示错误。

ODPS 小时分区可能延迟。当天尚未出现 06 点及之后的分区时只等待，不使用 夜间低流量分区做关停判断。最新分区相对当前时间最多允许延迟 2 小时，超过后 本轮不执行基于 CPM 的调价、恢复或关停；每天 07:00 的定时恢复不依赖 CPM。

状态保存在 MySQL，使用数据库锁避免多 Pod 同时执行。相同分区和相同决策默认 不重复扫描腾讯；每 60 分钟至少刷新一次广告清单以纳管新广告。

初始化

.venv/bin/python examples/tencent_realtime_control/init_db.py

数据检查

读取上海时区当天分时 CPM：

.venv/bin/python examples/tencent_realtime_control/fetch_daily_hourly_cpm.py

指定日期：

.venv/bin/python examples/tencent_realtime_control/fetch_daily_hourly_cpm.py \
  --date 20260724

单次执行

默认 dry-run，不修改腾讯：

.venv/bin/python examples/tencent_realtime_control/run_once.py

验证 CPM 分支：

.venv/bin/python examples/tencent_realtime_control/run_once.py \
  --at 2026-07-24T15:00:00 \
  --cpm-override 260

使用真实账户、广告、出价和当日指标模拟完整通知链路，不修改腾讯广告：

.venv/bin/python examples/tencent_realtime_control/run_once.py \
  --at 2026-07-24T15:00:00 \
  --cpm-override 260 \
  --test-notification

模拟卡片、动作列和表格标题都会标记“模拟”。--test-notification 不能与 --apply 同时使用。

真实执行：

.venv/bin/python examples/tencent_realtime_control/run_once.py --apply

Docker 调度

长驻进程会在投放时段按 10 分钟边界执行，21 点收尾后休眠到次日 7 点：

.venv/bin/python examples/tencent_realtime_control/run_scheduler.py --apply

默认所有执行入口均为 dry-run，必须显式传 --apply 才会调用腾讯写接口。 --at 和 --cpm-override 只允许 dry-run。

构建独立生产镜像：

docker build \
  -f Dockerfile.tencent_realtime_control \
  -t tencent-realtime-control:local .

镜像默认命令是 python run_scheduler.py --apply。首次上线应先覆盖默认命令执行 python run_once.py 完成 dry-run，确认无误后再启动默认调度命令。

环境变量

参考 .env.example。部署必须提供 ODPS、MySQL、腾讯 token 服务和飞书应用 配置，不能在代码中写入凭证。通知群优先读取 RTC_FEISHU_CHAT_ID，为空时 复用广告调控流程的 FEISHU_AD_PROJECT_CHAT_ID；不会回退发送到个人或运营 审批群。RTC_FEISHU_NOTIFY_ENABLED=0 可临时关闭 通知。