Почетна Преглед Помоћ
Пријавите се
howard
/
Agent
1
0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Дрво: dde291f941
Гране Ознаке
Agent
/
examples
/
auto_put_ad_mini
/
API_TEST_GUIDE.md

API_TEST_GUIDE.md 5.1 KB
Историја Датотека

腾讯广告平台 API 测试指南

项目分析总结

系统架构

auto_put_ad_mini 是一个智能广告投放系统,主要功能包括:

数据拉取 → ROI 计算 → 广告分类(A/B/C) → AI 推理决策 → 保存决策 → 护栏验证 → 生成报告 → 执行

核心组件

  1. API 封装 (tools/ad_api.py)

    • 腾讯广告 Marketing API v3.0 封装
    • 支持广告创建、更新、查询
    • 支持创意管理
    • 支持数据报表查询
    • 支持账户信息查询

  2. 数据查询 (tools/data_query.py)

    • 拉取创意数据
    • 合并数据

  3. ROI 计算 (tools/roi_calculator.py)

    • 计算 f_7日动态ROI
    • 多维度 ROI 分析

  4. 决策引擎 (tools/ad_decision.py)

    • 广告分类 (A/B/C)
    • AI 推理决策
    • 应用决策

  5. 安全护栏 (tools/guardrails.py)

    • 验证决策安全性
    • 防止过度调整

  6. 执行引擎 (tools/execution_engine.py)

    • 分级执行决策
    • 效果检查

  7. 报告生成 (tools/report_generator.py)

    • 生成决策报告
    • 对比分析

关键特性

  • API 版本: 腾讯广告 Marketing API v3.0
  • 层级结构: 广告(Ad) → 创意(Dynamic Creative)
  • 决策依据: f_7日动态ROI + 消耗双维度
  • 决策范围: 调整出价、暂停广告
  • 安全模式: DRY_RUN_MODE 默认开启,不实际执行

API 测试配置指南

1. 获取腾讯广告 API 凭证

1.1 获取 Access Token

  1. 登录腾讯广告平台: https://e.qq.com
  2. 进入"开发者中心" → "API 管理"
  3. 创建应用并获取 App ID 和 App Secret
  4. 使用 OAuth2.0 授权流程获取 access_token

详细文档: https://developers.e.qq.com/docs/guide/auth

1.2 获取账户 ID

  1. 登录腾讯广告平台
  2. 在账户管理页面查看账户 ID (数字格式)
  3. 或通过 API 调用 /accounts/get 获取

2. 配置环境变量

编辑项目根目录的 .env 文件,添加以下配置:

# 腾讯广告 API 配置
TENCENT_AD_ACCESS_TOKEN=your_access_token_here
TENCENT_AD_ACCOUNT_ID=your_account_id_here

# 可选: 自定义 API Base URL (默认为 v3.0)
TENCENT_AD_BASE_URL=https://api.e.qq.com/v3.0

示例:

TENCENT_AD_ACCESS_TOKEN=abcdefghijklmnopqrstuvwxyz123456
TENCENT_AD_ACCOUNT_ID=1234567890

3. 安装依赖

# 安装 httpx (用于 API 请求)
pip3 install httpx

# 或安装完整依赖
pip3 install -r requirements.txt

4. 运行测试

cd /Users/liulidong/project/agent/Agent

# 运行简化版测试 (推荐)
python3 examples/auto_put_ad_mini/test_api_simple.py

5. 预期结果

如果配置正确,测试脚本会依次测试:

✅ 环境变量检查
✅ 账户信息查询
✅ 广告列表查询
✅ 数据报表查询

🎉 所有测试通过! 腾讯广告平台接口可用

测试失败排查

错误 1: 环境变量未设置

现象:

❌ TENCENT_AD_ACCESS_TOKEN: 未设置

解决方法:

  • 确认 .env 文件存在于项目根目录
  • 确认 .env 文件中已添加 TENCENT_AD_ACCESS_TOKEN 和 TENCENT_AD_ACCOUNT_ID
  • 确认没有多余的空格或引号

错误 2: API 错误 code != 0

现象:

❌ API 错误 (code=4001): access_token invalid

可能原因:

  1. Access Token 已过期
  2. Access Token 格式错误
  3. Access Token 权限不足

解决方法:

  • 重新获取 Access Token
  • 检查 Token 是否有账户访问权限
  • 确认使用的是 v3.0 API

错误 3: HTTP 错误 403/401

现象:

❌ HTTP 错误: 403

可能原因:

  1. 账户权限不足
  2. IP 白名单未配置
  3. 账户状态异常

解决方法:

  • 检查账户状态是否正常
  • 配置 API 调用 IP 白名单
  • 确认账户有 API 调用权限

错误 4: 网络连接错误

现象:

❌ 网络请求错误: Connection timeout

可能原因:

  1. 网络不通
  2. 防火墙拦截
  3. 需要代理

解决方法:

  • 检查网络连接

  • 配置代理 (如果需要):

    export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

    API 限制说明

    根据腾讯广告 API 文档:

    • QPS 限制: 单账户 10 QPS
    • 批量操作: 单次最多 50 条
    • 金额单位: 分 (1元 = 100分)
    • 审核时间: 2-4 小时 (普通素材)
    • 数据延迟: 实时数据 15-30 分钟,转化数据 1-2 小时

    下一步操作

    配置成功后,可以:

    1. 运行完整系统: bash python3 examples/auto_put_ad_mini/run.py

输入指令: 分析广告

  1. 查看系统配置:

    • 配置文件: examples/auto_put_ad_mini/config.py
    • 决策策略: examples/auto_put_ad_mini/skills/roi_strategy.md
    • 安全护栏: examples/auto_put_ad_mini/skills/guardrail_rules.md

  2. 启用执行模式 (谨慎):

    • 编辑 config.py
    • 设置 DRY_RUN_MODE = False
    • 设置 EXECUTION_ENABLED = True

技术支持

最后更新: 2026-04-15