audience-advisor

受众顾问

目的

帮助用户打造符合业务目标的合适受众，而不只是任意受众。使用 Lytics 分析 API ——ML 特征重要性、内容偏好、字段信息分布、细分受众摘要——提供基于证据的建议。如果未配置高级功能，则平稳降级。

支持两种模式：

• 根据目标创建：“帮我打造一个能促进更多购买的受众”
• 改进现有受众：“如何改进我的‘高价值客户’细分受众？”

环境

需要经过身份验证的 API 访问权限。凭据解析方式请参阅 ../references/auth.md。

流程

第 1 步：了解意图

确定用户需要哪种模式：

路径 A —— 根据业务目标创建新受众： 询问用户想要实现什么，而不是想要什么受众：

• “促进更多购买” -> 以转化为重点
• “重新吸引流失用户” -> 以留存为重点
• “增加电子邮件订阅者” -> 以获客为重点
• “推广新产品线” -> 以认知度为重点

对目标类型进行分类——这将决定之后优先考虑哪些字段和策略。

路径 B —— 改进现有细分受众： 接受细分受众名称或 ID。获取该细分受众及其当前 FilterQL：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

找到匹配的细分受众，记录其当前规模，并解析其 FilterQL 以了解现有筛选条件。

两条路径都在第 2 步汇合。

第 2 步：盘点现有细分受众

获取所有细分受众，以了解已构建的内容：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

• 根据名称、标签或类型识别与目标相关的细分受众
• 查找类型为“目标”或“转化”的细分受众——它们代表业务成果，是有价值的参考点
• 记录总体人群规模，以便之后计算百分比
• 标记任何已针对该目标的现有细分受众，以避免重复

步骤 3：收集分析信号

尝试每个数据源。跳过返回空结果或错误的数据源——根据可用数据继续操作。

3a. ML 特征重要性（最佳信号，可能不存在）：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

如果存在模型，请找出其目标细分群体与用户期望结果相匹配的模型。每个模型都会预测用户与其目标细分群体的相似度：

• 列出所有模型，并检查其目标细分群体的名称和描述

• 将目标细分群体与用户所述目标进行匹配（例如，目标 =“促成购买” -> 查找针对“购买者”或“转化用户”细分群体的模型）

• 如果找到相关模型，请获取其摘要：

  curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml/${MODEL_ID}/summary" \
    -H "Authorization: ${LYTICS_API_TOKEN}"
  

  响应中包含模型质量指标，以及一个 features 数组，用于按重要性排列最能区分目标受众的字段：

  {
    "data": {
      "id": "model_id",
      "name": "Model Name",
      "state": "completed",
      "summary": {
        "auc": 0.85,
        "accuracy": 0.82,
        "reach": 0.75,
        "model_health": "good",
        "mse": 0.12,
        "rsq": 0.71
      },
      "features": [
        {
          "kind": "score",
          "type": "numeric",
          "name": "visit_count",
          "importance": 1.79,
          "field_prevalence": {"source": 0.30, "target": 0.99},
          "correlation": 0.23,
          "impact": {"lift": 0.35, "threshold": 2}
        }
      ]
    }
  }
  

  推荐时的重要特征字段：

  • name -- 要筛选的架构字段名称
  • importance -- 值越高，对目标细分群体成员身份的预测能力越强
  • field_prevalence.source 与 .target -- 该字段在总体人群和目标人群中的普遍程度（差异越大 = 区分能力越强）
  • correlation -- 关系的方向和强度
  • impact.lift -- 该字段使用户属于目标人群的可能性提高了多少
  • impact.threshold -- 建议用于筛选的截断值

• 如果没有模型的目标细分群体与目标相关：跳过 ML。告知用户：“没有模型针对这一结果。你可以使用转化细分群体作为目标创建相似模型，以获取预测性特征排名。”

• 如果有多个模型可能适用：优先选择目标细分群体与目标最匹配的模型。

• 如果完全没有模型：静默跳过，继续下一个信号。

3b. 内容偏好（可能尚未配置）：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/affinity" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

如果存在偏好且有可用的参考细分群体：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/recommend/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

这会揭示受众中具有区分度的主题兴趣。如果未配置：静默跳过。

3c. Fieldinfo 分析（始终可用——基线）：

针对参考细分群体（目标／转化细分群体，或正在改进的细分群体）。 重要：使用细分群体的 id 哈希，而非 slug 名称——slug 会返回 HTTP 500。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=50" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

获取包含方面重叠信息的细分群体摘要：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/summary" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

如果没有参考细分群体，请使用架构级字段分布：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

此方法始终可用——字段覆盖率、值分布和基数始终可获取。

步骤 4：综合分析并提出建议

按信号强度整理并呈现发现：

有 ML 特征重要性时：

“针对‘购买者’的 ML 模型将以下特征列为最重要的预测因素：

1. visit_count -- 访问 5 次以上的用户转化可能性是其他用户的 3.2 倍
2. email_engagement -- 积极阅读邮件的用户转化率是基线的 2.8 倍
3. products_viewed -- 浏览 3 个以上产品类别表明购买意愿较高

我建议围绕这些字段构建筛选条件。”

有内容偏好时：

“你的转化用户对‘Technology’内容的关注度高于基线（3.2 倍），对‘Product Reviews’的关注度也更高（2.5 倍）。可以考虑将内容偏好作为定向信号。”

只有 fieldinfo 时（始终可用）：

“查看你的‘近期购买者’细分群体：

• 78% 的用户 visit_count >= 5（所有用户中为 30%）
• 92% 的用户填写了 email（适合用于邮件营销）
• country：65% 来自 US，15% 来自 CA，10% 来自 UK

筛选 visit_count >= 5 可以覆盖大多数转化用户，同时排除购买意愿较低的用户。”

改进现有细分群体时：

“你的‘高价值’细分群体目前有 50,000 名用户（总数的 35%）——对于定向营销而言范围相当宽泛。以下是我的发现：

• 筛选条件 EXISTS email 匹配了 92% 的所有用户——它几乎没有提高筛选精度
• 该细分群体中只有 20% 填写了 purchase_history——这个字段在此处可能没有用
• 添加 visit_count >= 5 会将范围缩小到 15,000 名用户（10%），同时保留 78% 的实际转化用户

建议更新后的 FilterQL： FILTER AND (visit_count >= 5, email_engagement > 0.3) FROM user ALIAS high_value_v2”

第 5 步：迭代调整规模

测试不同的筛选条件，不创建细分。向用户展示每次更改如何影响受众规模：

# Get total population size for percentage context
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER * FROM user'

# Test each filter variation
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5) FROM user'

按逐步细化的方式呈现：

Starting point: 145,000 total users (100%)

1. visit_count >= 5          -> 43,500 (30%)
2. + email_engagement > 0.3  -> 18,200 (13%)
3. + last_visit > "now-30d"  -> 12,400 (9%)   <-- recommended

This 9% audience captures your highest-intent users with recent activity.

在计算规模前验证每个 FilterQL：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5, email_engagement > 0.3, last_visit > "now-30d") FROM user'

第 6 步：确认并创建

用户对拟定的受众满意后，交由 audience-builder skill 创建细分，并采用完整的确认门控模式。

要改进现有细分，请改用 PUT /v2/segment/:id。

第 7 步：创建后的快照

创建后，可提议运行 audience-snapshot skill，展示最终受众构成并确认结果看起来合理。

受众规模指南

占总人数的比例	评估	最适用场景
< 1%	范围很窄——可能限制触达范围和统计显著性	高度个性化、VIP 计划
1-10%	定向精准	转化活动、再营销
10-30%	定向范围广	品牌认知活动、电子邮件群发
> 30%	范围很广——考虑收紧定向是否能提高投资回报率	仅适用于广泛公告

按目标类型选择字段指南

目标	首选字段类型	原因
转化/购买	行为：visit_count、pages_viewed、购物车活动	行为比人口统计信息更能预测意向
重新互动/留存	时间：last_visit、last_purchase、近期度评分	近期度可识别已流失用户
品牌认知/触达	人口统计：国家、行业、兴趣类别	广泛属性有助于触达合适人群
电子邮件/渠道增长	渠道：email_opt_in、channel_preferences、互动评分	渠道特定信号最为重要

细化模式

• 从宽泛开始，逐步收窄 —— 每一步都展示规模变化，让用户了解取舍
• 用 AND 缩小范围，用 OR 扩大范围 —— 指导用户组合条件
• 推荐前检查字段覆盖率 —— 覆盖率为 20% 的字段会将受众规模限制在最多 20%
• 集合字段优先使用 INTERSECTS（例如 products_purchased），数值字段使用比较运算符
• 使用日期运算进行时间定向 —— "now-30d" 表示近期，"now-90d" 表示中期，"now-1y" 表示长期

错误处理

• 没有 ML 模型：优雅跳过，依靠字段信息分析。建议创建相似模型。
• 没有亲和度数据：静默跳过，继续使用字段信息。
• 没有转化/目标细分：请用户手动描述理想客户的特征。使用架构发现来查找匹配字段。
• 筛选后细分为空：建议放宽条件——移除限制最严格的筛选条件或调整阈值。
• 用户不确定目标：提供常见目标类别供其选择。

依赖项

• 组合使用：audience-builder skill、audience-snapshot skill、segment-manager skill、schema-discovery skill
• 参考：../references/auth.md、../references/api-client.md、../references/field-types.md、../references/filterql-grammar.md