Página Principal Explorar Ajuda
Iniciar Sessão
howard
/
Agent
2
0
Fork 0
Ficheiros Problemas 0 Pull Requests 0 Wiki
Árvore: 18791fea41
Ramos Etiquetas
Agent
/
examples
/
auto_put_ad_mini
/
PRODUCTION_AUTOMATION.md

PRODUCTION_AUTOMATION.md 9.3 KB
Histórico Em bruto

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 使用当前账户配置的人群包;如果配置了视频召回映射,则 primary/hot 都使用映射后的召回人群包。

当前默认视频召回映射:

cell*year*商业 -> wx*商业

该映射只影响 videoContentList 获取视频,不影响腾讯投放定向、人群包授权和 xcx/save 落地计划。

视频过滤规则

内容服务 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=5

规则:

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

素材召回筛选与排序

videoContentList 只负责提供承接视频候选。素材召回特征统一通过 video_id 查询 ODPS 表:

loghubods.dwd_video_element_contribution_analysis

当前使用的召回特征:

  • 解构选题 列 -> VIDEO_TOPIC
  • 元素维度=实质, 点类型=灵感点 -> INSPIRATION_SUBSTANCE
  • 元素维度=实质, 点类型=关键点 -> KEYPOINT_SUBSTANCE
  • 元素维度=实质, 点类型=目的点 -> PURPOSE_SUBSTANCE

形式 和 意图 不参与素材召回。primary 和 hot 视频都走同一套 ODPS 查询、风险审核、素材召回和审批流程。

素材召回只使用相似度做硬筛:

RECALL_SIM_THRESHOLD=0.8
RECALL_DAYS=180
RECALL_DISPLAY_K=30

素材必须满足:

  • 相似度 score >= 0.8
  • 封面 URL 不命中已知黑名单

通过筛选后按历史消耗 cost 倒序选择。ROI、CTR、曝光数和相似度会进入创意审批报表,但不再作为硬筛。

AI 生成图片素材

账户可通过飞书/DB 指定素材来源:

  • 空值或 历史素材:继续使用历史已投素材召回。
  • AI生成素材:按承接视频的 ODPS 特征生成新图片素材。

AI 生成素材链路只改变“素材来源”,不改变视频筛选、人群包、出价、预算、落地计划、审批和腾讯创意创建主流程。 当前每个视频通过 landing_video_id 读取本地库 video_element_feature_cache 中该视频最新分区的 解构选题, 并使用贡献分最高的 standard_element 生成 1 张 topic 图片。 生成图片前会先用 OpenRouter 文本模型清洗原始 解构选题, 去掉转发、关注、公众号回复、加群、领取、底部提示、推广话术等互动/营销引导,同时保留核心事实、对象、数字和主题。 清洗失败或清洗后仍包含互动/营销词时,本轮跳过该视频,不使用原始 topic 兜底。 最终图片 prompt 由工程内模板和清洗后的动态承接视频描述拼接:

  • 清洗模板文件:examples/auto_put_ad_mini/prompts/ai_sanitize_video_description.md
  • 模板文件:examples/auto_put_ad_mini/prompts/ai_generated_material.md
  • 动态描述:解构选题.standard_element 经文本模型清洗后的主题描述
  • 图片比例:AI_IMAGE_ASPECT_RATIO,默认 16:9
  • 最终输出尺寸:AI_IMAGE_TARGET_WIDTH x AI_IMAGE_TARGET_HEIGHT,默认 1280x720

AI 图先上传到 OSS 并进入飞书人工审批。只有人工 approve 后,Phase 3 才会把图片上传到腾讯 images/add 并创建创意。 如果账户配置 生成失败是否回退历史素材=是,AI 生成失败或无候选时才回退历史素材;否则本轮跳过。

AI 图默认上传到:

  • OSS bucket:art-pubbucket
  • OSS 目录:auto_put_tencent/image
  • 对外 URL 域名:https://rescdn.yishihui.com/

手动调试生成效果可运行:

.venv/bin/python examples/auto_put_ad_mini/debug_generate_ai_material.py --video-id 71187017 --title "视频标题"

调试脚本按 video_id 读取本地特征缓存表,只生成并上传 OSS,打印图片 URL,不会创建腾讯广告或创意。

素材排重分两层:

  • 历史排重只读取已有明确结果的素材使用记录,按同人群包下的 material_id 排除。
  • 本轮审批候选做内存展示去重,同一 crowd_package + material_id 只进入当前审批表一次。该规则不写入历史排重库,进程结束即失效。

落地页视频排重分两层:

  • 当前运行内同一 crowd_package + landing_video_id 只允许进入 pending creative 一次。
  • 跨轮近期排重默认读取 creative_material_usage 和 creative_creation_task,排除同人群包最近 7 天进入 pending 或已提交腾讯的 landing_video_id。
  • 同一广告内同一 landing_video_id 仍保留限频保护,默认最多 1 次。

可通过环境变量调整同广告落地页视频本轮限频:

MAX_SAME_LANDING_PER_AD_IN_RUN=1
CREATIVE_LANDING_DEDUPE_LOOKBACK_DAYS=7

热门兜底配置

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

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=5
VIDEO_RECALL_CROWD_PACKAGE_MAP={"cell*year*商业":"wx*商业"}
MAX_SAME_LANDING_PER_AD_IN_RUN=1
CREATIVE_LANDING_DEDUPE_LOOKBACK_DAYS=7
TENCENT_AUDIENCE_SOURCE_ACCOUNT_ID=55615440
TENCENT_AUDIENCE_GRANT_BUSINESS_ID=12312
OPENROUTER_API_KEY=...
OPENROUTER_TEXT_MODEL=google/gemini-2.5-flash
OPENROUTER_IMAGE_MODEL=google/gemini-3-pro-image
ALIYUN_OSS_ENDPOINT=oss-xxx.aliyuncs.com
ALIYUN_OSS_BUCKET=art-pubbucket
ALIYUN_OSS_ACCESS_KEY_ID=...
ALIYUN_OSS_ACCESS_KEY_SECRET=...
AI_IMAGE_OSS_PREFIX=auto_put_tencent/image
AI_IMAGE_PUBLIC_BASE_URL=https://rescdn.yishihui.com
AI_IMAGE_TARGET_WIDTH=1280
AI_IMAGE_TARGET_HEIGHT=720

OSS key 已迁移到本工程环境变量。生产 Docker 也应显式注入这些变量,不依赖外层参考工程。

当前已知限制

  • R330 账户如果源账户无法解析到 ONLINE/SUCCESS 人群包,Phase 0 会跳过该账户。
  • 泛人群 主池可能返回 0,需要依赖 source=hot 兜底。
  • 当前素材只按相似度准入并按消耗排序;低曝光/低 CTR 素材可能进入审批表,需要运营结合报表判断。
  • AI 生成素材 v1 不做机器预审,质量和合规依赖飞书人工审批 + 腾讯审核。
  • 每次 pending creative 准备会调用 xcx/save 生成落地计划;端到端测试中断不会自动清理已生成的落地计划。

上线检查

上线前至少确认:

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