Agent/examples/auto_put_ad_mini/PRODUCTION_AUTOMATION.md

auto_put_ad_mini 生产自动投放系统说明

目标

本系统用于服务端 Docker 环境每日自动扫描投放配置,完成腾讯广告自动搭建与创意补量。

人工只维护待投放配置,主流程自动完成:

• 从飞书配置表同步待投放账户
• 校验账户白名单
• 校验/授权腾讯人群包
• 创建缺口广告
• 给广告补足创意
• 视频风险审核
• 内容品类过滤
• 素材召回与质量过滤
• 飞书审批
• 审批通过后创建腾讯动态创意

人工配置入口

当前生产配置来自飞书表 自动化账户。

每个账户只需要配置:

• 账户 ID
• 人群包名称
• 初始出价
• 单广告预算
• 是否自动化执行

当 是否自动化执行=是 时,每日主流程会扫描并处理该账户。为否时,系统不再为该账户新建广告或补创意,但不会暂停或删除既有广告。

生产目标

当前单广告最终有效创意目标:

TARGET_CREATIVES_PER_AD = 4

含义:

• 每条广告最终有效创意数不少于 4 个
• 已有有效创意会计入目标
• DENIED 创意不计入有效创意
• 差几个补几个
• 补充创意会先进入飞书审批,审批通过后才调用腾讯创建接口

承接视频选择

每次为一条广告准备一条创意时,视频最多扫描:

primary source: 最多 100 条
hot source: 最多 100 条

执行顺序:

1. 先用账户配置的人群包拉主池视频
2. 主池 100 条经过过滤、风险审核、素材召回后仍无法产出可用创意时,再用同一个人群包拉 source=hot
3. hot 池同样最多 100 条
4. hot 池同样走风险审核、品类过滤、素材质量过滤

注意: source=hot 只改变内容服务的视频来源,crowdPackage 仍然传当前账户配置的人群包,不会固定成其他人群包。

视频过滤规则

内容服务 videoContentList 返回的 category 字段会用于内容品类过滤。

默认过滤:

LANDING_EXCLUDED_CATEGORIES=早中晚好,祝福音乐

命中后,该视频会在以下步骤前被跳过:

• 视频风险审核
• 素材召回
• xcx/save 落地计划创建

可通过 Docker/K8s 环境变量覆盖:

LANDING_EXCLUDED_CATEGORIES=早中晚好,祝福音乐

多个品类用英文逗号分隔。

视频风险审核

承接视频在创建落地计划前调用风险接口:

POST https://longvideoapi.piaoquantv.com/longvideoapi/openapi/video/getVideoTagIds

当前阈值:

VIDEO_RISK_MAX_ALLOWED_LEVEL=1

规则:

• 风险等级 0/1 通过
• 风险等级 2-10 拦截
• 风险接口异常时按不通过处理,避免风险未知的视频进入投放

素材召回质量门槛

素材召回仍使用现有质量阈值:

RECALL_MIN_IMPRESSIONS=2000
RECALL_MIN_CTR=0.10
RECALL_DAYS=180
RECALL_DISPLAY_K=30

素材必须同时满足:

• 曝光 impressions > 2000
• CTR >= 10%
• 封面 URL 不命中已知黑名单

热门兜底配置

热门兜底由以下环境变量控制:

PIAOQUANTV_HOT_FALLBACK_ENABLED=true
PIAOQUANTV_HOT_FALLBACK_SOURCE=hot

生产默认开启。

主池不足和主池无法产出可用创意是两个不同口径:

• 视频列表不足: 主池返回条数少于请求条数时,视频获取层可补 hot
• 创意产出不足: 主池 100 条无法产出 pending creative 时,创意准备层继续跑 hot 100 条

生产投放以“最终有效创意数达到目标”为准。

Docker/K8s 必配环境变量

除数据库、飞书、腾讯、ODPS 等基础密钥外,生产自动投放建议显式配置:

PIAOQUANTV_TOKEN=...
PIAOQUANTV_VIDEO_TYPE=5
PIAOQUANTV_VIDEO_SOURCE=prior
PIAOQUANTV_HOT_FALLBACK_ENABLED=true
PIAOQUANTV_HOT_FALLBACK_SOURCE=hot
LANDING_EXCLUDED_CATEGORIES=早中晚好,祝福音乐
VIDEO_RISK_MAX_ALLOWED_LEVEL=1
TENCENT_AUDIENCE_SOURCE_ACCOUNT_ID=55615440
TENCENT_AUDIENCE_GRANT_BUSINESS_ID=12312

当前已知限制

• R330 账户如果源账户无法解析到 ONLINE/SUCCESS 人群包,Phase 0 会跳过该账户。
• 泛人群 主池可能返回 0,需要依赖 source=hot 兜底。
• 当前素材质量门槛较高,部分安全视频会因素材曝光/CTR 不达标而无法产出创意。
• 每次 pending creative 准备会调用 xcx/save 生成落地计划;端到端测试中断不会自动清理已生成的落地计划。

上线检查

上线前至少确认:

• 飞书配置表可读
• 是否自动化执行 只对目标账户开启
• 目标账户在 account_whitelist 启用
• 人群包名称可在源账户解析并授权到目标广告账户
• 品牌图和监测链接模板可自动初始化
• Docker/K8s 环境变量与本文件一致
• 手动跑一次 execute_creation_once.py 能生成飞书审批表