9.1.5.1 画像查询 API 接口

• 形式：通过 HTTP 接口提供单用户或批量用户的标签查询，支持 JSON/XML 格式返回。

• 核心接口说明

• 接口类型	接口路径	功能描述	请求方式	核心参数
  单用户标签查询	/api/v1/tags/user/{user_id}	获取单个用户的全量或指定分类标签	GET	user_id（用户唯一标识）、category（标签分类，如basic/behavior）
  批量用户标签查询	/api/v1/tags/users/batch	批量获取多个用户的标签（支持万级用户批量查询）	POST	user_ids（用户 ID 列表）、fields（指定返回字段，如age,gender）

点击图片可查看完整电子表格

• 技术实现：

• 后端：Spring Boot/Node.js + 缓存（Redis）+ 分布式查询（Elasticsearch）。

• 核心逻辑：根据用户 ID 从缓存或宽表中提取标签，支持条件过滤（如/api/user/{uid}/tags?category=消费）。

• 适用场景：

• 实时推荐系统（如电商商品详情页的用户标签匹配）。

• 营销触达系统（如短信 / APP 推送前校验用户标签）。

• 案例：某电商 APP 详情页调用/api/user/12345/tags接口，获取用户 “偏好品牌”“价格敏感度” 标签，动态展示推荐商品。

9.1.5.2 人群圈选 API

人群圈选业务流程（包括判存服务）

• 形式：支持通过标签组合条件（如 “年龄> 25 且近 30 天购买过数码产品”）直接返回用户集合（ID 列表或 Bitmap）。

• 核心接口说明

  接口类型	接口路径	功能描述	请求方式	典型参数
  创建人群	/api/v1/segments	基于标签条件创建人群（如 “年龄 25-35 岁且近 30 天购买过数码产品”）	POST	name（人群名称）、filters（标签筛选条件）、expire_time（有效期）
  查询人群列表	/api/v1/segments	获取已创建的人群列表（支持分页、过滤）	GET	page、page_size、status（如active/expired）
  获取人群详情	/api/v1/segments/{id}	获取指定人群的详细信息（如圈选规则、人群规模、创建时间）	GET	id（人群 ID）
  更新人群	/api/v1/segments/{id}	更新已有人群的圈选规则或基本信息	PUT	id（人群 ID）、filters（新筛选条件）
  删除人群	/api/v1/segments/{id}	删除指定人群（逻辑删除，保留历史记录）	DELETE	id（人群 ID）
  导出人群	/api/v1/segments/{id}/export	导出人群用户列表（支持多种格式，如 CSV、JSON）	POST	id（人群 ID）、format（导出格式）

点击图片可查看完整电子表格

• 技术实现：

人群圈选服务的技术实现需结合存储引擎、计算框架及性能优化，以满足高并发和大规模数据需求。

1. 核心技术选型

   组件	工具/框架	特点
   实时计算引擎	Flink	支持实时流式计算，用于动态更新标签和行为数据。
   离线计算引擎	Spark	用于批量处理历史数据，生成静态标签宽表。
   存储引擎	Apache Doris / ClickHouse	支持高效查询和BitMap交并差操作，适合人群圈选和画像统计。
   缓存层	Redis	缓存高频查询结果（如热门人群ID的用户列表）。

点击图片可查看完整电子表格

1. 表结构设计

（1） 标签宽表（Doris/ClickHouse）

Plain Text CREATE TABLE user_profile (   user_id STRING,   city STRING,   gender STRING,   age INT,   device_type STRING,   login_frequency INT,   avg_spending DECIMAL ) ENGINE=OLAP DUPLICATE KEY(user_id) COMMENT '用户画像宽表';

（2） BitMap 存储（Doris）

Plain Text CREATE TABLE user_tag_bitmap (   tag_name STRING,   tag_value STRING,   bitmap BITMAP ) ENGINE=OLAP DUPLICATE KEY(tag_name, tag_value) COMMENT 'BitMap人群存储表';

1. 核心流程

1. 规则解析：将用户定义的圈选条件（如性别=男 AND 城市=北京）转换为 SQL 或 DSL 表达式。

1. 数据计算：

• 实时圈选：通过 Flink 实时处理用户行为数据，更新 Doris/ClickHouse 中的 BitMap。

• 离线圈选：通过 Spark 批量计算标签宽表，结合调度系统，每天定时生成静态人群包。

1. 结果存储：将圈选结果（用户 ID 列表或 BitMap）持久化到 Doris/ClickHouse。

1. 查询优化：

• 使用 BitMap 交并差操作加速多人群运算（如bitmapAnd(bitmap1, bitmap2)）。

• 对高频查询字段（如城市、性别）建立索引。

1. 性能优化

• BitMap 压缩：使用 RoaringBitmap 减少存储空间（如 1 亿用户仅需 1MB）。

• 分页优化：对 Doris 的GET /crowd/{crowd_id}/users接口使用LIMIT+OFFSET分页，或Cursor分页。

• 缓存热点人群：Redis 缓存热门人群的用户 ID 列表，减少数据库查询压力。

• 适用场景：

• 广告投放平台（快速获取目标人群进行投放）。

• 营销活动系统（圈选用户后批量发送优惠券）。

• 案例：广告平台调用圈选 API 获取 “一线城市女性且关注美妆” 的用户 Bitmap，与媒体平台用户 Bitmap 取交集后进行广告投放。

9.1.5.3 人群判存 API

• 形式

人群判存服务的核心接口设计需支持单用户/批量用户判存、多人群判存，并兼容不同类型的用户 ID（如数字 ID、字符串 ID）。

1. 核心接口设计

2. HTTP方法	URI	操作	描述
   GET	/api/v1/crowd/{crowd_id}/contains/{user_id}	单用户判存	判断指定用户ID是否属于某个人群包（返回布尔值）。
   POST	/api/v1/crowd/match	批量用户判存	接收用户ID列表和人群ID列表，返回每个用户与人群的匹配结果（布尔数组）。
   GET	/api/v1/crowd/{crowd_id}/exists	人群存在性验证	判断指定人群ID是否已创建（用于前置校验）。

点击图片可查看完整电子表格

1. 请求与响应示例

（1） 单用户判存

Plain Text GET /api/v1/crowd/1001/contains/12345 Authorization: Bearer <token>

响应：

Plain Text {   "user_id": "12345",   "crowd_id": "1001",   "match": true }

（2） 批量用户判存

Plain Text POST /api/v1/crowd/match Authorization: Bearer <token> Content-Type: application/json {   "user_ids": ["12345", "67890"],   "crowd_ids": ["1001", "1002"] }

响应：

Plain Text {   "results": [     {       "user_id": "12345",       "matches": {         "1001": true,         "1002": false       }     },     {       "user_id": "67890",       "matches": {         "1001": false,         "1002": true       }     }   ] }

（3） 人群存在性验证

Plain Text GET /api/v1/crowd/1001/exists Authorization: Bearer <token>

响应：

Plain Text {   "crowd_id": "1001",   "exists": true }

二、技术实现

人群判存服务的核心技术围绕高效存储和快速查询展开，主要方案包括：

1. BitMap 方案

• 适用场景：支持数字类型 ID（如UserID、手机号），需高性能、低资源消耗。

• 实现逻辑：

1. 数据编码：将用户 ID 映射为连续整数（如UserID→Offset），压缩存储空间。

1. BitMap 存储：将人群 ID 与对应的 BitMap 关联，存储在内存或分布式存储中（如 OSS+大内存物理机）。

1. 判存过程：

• 将用户 ID 转换为Offset。

• 通过 BitMap 的contains函数判断是否存在。

1. 优势：

• 高性能：内存操作，无网络请求，响应时间<1ms。

• 资源消耗低：1 亿用户仅需 12MB 内存（1 个 BitMap）。

1. 局限性：

• ID 类型限制：仅支持数字 ID，非数字 ID 需额外编码（如DeviceId→Offset）。

• 维护成本高：进程重启需重新加载 BitMap，数据量大时加载时间较长。

1. Redis 方案

• 适用场景：支持任意类型 ID（如DeviceId、Email），需灵活扩展。

• 实现逻辑：

1. Key-Value 存储：将人群 ID 作为 Key，用户 ID 集合存储为 Value（如Set或Hash）。

1. 判存过程：通过SISMEMBER或HGET判断用户 ID 是否存在。

1. 优势：

• 通用性强：支持任意 ID 类型。

• 运维成熟：Redis 集群可横向扩展，维护成本较低。

1. 局限性：

• 性能瓶颈：高并发下 Redis 性能下降（如万级 QPS 时延迟显著增加）。

• 存储成本高：存储效率低于 BitMap（如Set结构存储 1 亿用户需约 1GB 内存）。

1. 基于规则的判存

• 适用场景：仅需判存规则人群（如“北京男性用户”），无需预先创建人群包。

• 实现逻辑：

1. 动态查询：通过标签查询服务实时计算用户是否符合规则（如查询用户省份=北京且性别=男）。

1. 优势：

• 无需预存人群：节省存储空间。

• 灵活性高：支持复杂规则组合。

1. 局限性：

• 依赖标签服务：仅适用于规则人群，无法支持静态人群包。

• 性能开销：需多次调用标签查询接口，响应时间较高。

1. 混合方案

• 适用场景：兼顾性能与灵活性，支持混合类型 ID（数字 ID+非数字 ID）。

• 实现逻辑：

1. ID 编码：非数字 ID（如DeviceId）通过编码转换为数字 ID（如Offset）。

1. BitMap+Redis:

• 数字 ID 直接使用 BitMap。

• 非数字 ID 通过 Redis 缓存ID→Offset映射表，再调用 BitMap 判存。

1. 优势：

• 兼容性强：支持数字 ID 与非数字 ID。

• 性能优化：通过缓存减少 ID 转换开销（如 Redis 缓存热点 ID）。

三、适用场景

人群判存服务广泛应用于以下业务场景：

1. 精准营销

• 场景描述：通过判存服务筛选符合特定规则的用户（如“高消费 VIP 用户”），进行定向营销。

• 案例：

• 某电商平台通过判存服务筛选“最近 7 天购买金额>1000 元”的用户，推送专属优惠券，转化率提升 25%。

1. 风控拦截

• 场景描述：实时判存用户是否属于风险人群（如“频繁登录失败用户”），触发拦截策略。

• 案例：

• 某银行通过判存服务判断用户是否属于“高风险 IP 登录用户”，拦截异常登录请求，降低欺诈率 18%。

1. 个性化推荐

• 场景描述：根据用户所属人群（如“母婴兴趣用户”）生成个性化推荐内容。

• 案例：

• 某短视频平台通过判存服务筛选“母婴兴趣用户”，推送育儿知识视频，点击率提升 30%。

1. A/B 测试

• 场景描述：将用户划分为不同测试组（如“新功能组”和“对照组”），通过判存服务验证效果。

• 案例：

• 某社交 App 通过判存服务分配用户到不同版本，发现新功能组用户留存率提升 12%。

四、典型案例

1. 案例一：BitMap 方案在营销活动中的应用

• 背景：某电商平台需在 618 大促期间，快速筛选“去年购买过同类商品”的用户，推送定向优惠。

• 实现：

1. 构建人群包：通过离线计算生成“去年购买过同类商品”的 BitMap。

1. 判存服务：实时判存用户是否属于该人群包。

1. 效果：推送效率提升 90%，优惠券领取率提高 40%。

1. 案例二：Redis 方案在风控中的应用

• 背景：某银行需实时拦截“高频登录失败用户”，防止账号盗用。

• 实现：

1. 构建人群包：通过 Flink 实时统计用户登录失败次数，更新 Redis 中的人群包。

1. 判存服务：登录时判存用户是否属于“高频登录失败用户”。

1. 效果：拦截异常登录请求 2000+次/日，误判率<1%。

1. 案例三：基于规则的判存在个性化推荐中的应用

• 背景：某视频平台需根据用户兴趣标签（如“电影”“音乐”）动态推荐内容。

• 实现：

1. 规则定义：定义人群规则（如“电影兴趣用户”）。

1. 判存服务：实时查询用户是否满足规则，生成推荐内容。

1. 效果：推荐点击率提升 22%，用户停留时长增加 15%。

五、总结

人群判存服务是用户画像平台的核心能力之一，其技术实现需根据业务需求选择合适方案：

• BitMap 方案：适合数字 ID 场景，性能最优。

• Redis 方案：适合非数字 ID 场景，灵活性强。

• 基于规则的判存：适合动态规则人群，无需预存人群包。

• 混合方案：兼顾性能与灵活性，支持复杂业务需求。

9.1.5.4 流式 API

• 形式：实时画像推送服务通过标准化 API 提供用户画像变更的实时通知能力，核心接口包括订阅管理、推送配置与状态查询：

• 核心接口说明

• 接口类型	接口路径	功能描述	请求方式	典型参数
  创建订阅	/api/v1/subscriptions	订阅指定类型的画像变更事件（如 “年龄更新”“消费等级变化”）	POST	user_ids（用户 ID 列表）、tag_types（标签类型）、callback_url（回调地址）
  查询订阅列表	/api/v1/subscriptions	获取已创建的订阅列表（支持分页、过滤）	GET	page、page_size、status（如active/paused）
  更新订阅	/api/v1/subscriptions/{id}	更新订阅配置（如修改回调地址、调整推送频率）	PUT	id（订阅 ID）、callback_url（新回调地址）
  删除订阅	/api/v1/subscriptions/{id}	删除指定订阅	DELETE	id（订阅 ID）
  查询推送状态	/api/v1/push/status/{id}	查询特定推送任务的状态（如成功 / 失败 / 重试中）	GET	id（推送任务 ID）
  批量推送测试	/api/v1/push/test	向指定地址批量推送模拟画像数据（用于回调接口测试）	POST	callback_url、mock_data（模拟画像数据）

点击图片可查看完整电子表格

• 技术实现：

1. 表结构设计

（1） 实时用户标签表（Redis）

Plain Text Hash Key: user:12345 Fields:   - tags: ["电子产品爱好者", "高活跃用户"]   - last_active_time: "2025-06-22T16:45:00Z"

（2） 用户行为日志表（ClickHouse）

Plain Text CREATE TABLE user_actions (   user_id String,   action_type String,   item_id String,   timestamp DateTime ) ENGINE = MergeTree() ORDER BY (user_id, timestamp);

1. 核心流程

1. 数据采集：通过埋点 SDK 或 API 实时采集用户行为（如浏览、点击、购买）。

1. 实时计算：

• Flink 流处理：解析用户行为事件，更新 Redis 中的标签。

• 规则引擎：根据预设规则（如“连续 3 天浏览未购买”）生成实时人群 ID。

1. 动态推送：

• 消息队列触发：将人群 ID 和推送内容发送至消息队列（如 Kafka）。

• 多渠道推送：通过阿里云 MNS 或 AWS SNS 将消息推送到目标用户。

1. 效果监控：

• 实时统计：通过 ClickHouse 记录点击、转化等数据。

• 反馈优化：基于 A/B 测试结果调整推送策略。

1. 性能优化

• 标签缓存：Redis 缓存高频访问的用户标签，减少数据库查询。

• 流批一体：Flink 与 Spark 协同处理实时与离线数据。

• 异步推送：通过消息队列解耦计算与推送环节，提升系统吞吐量。

适用场景

1. 精准营销

• 场景描述：实时捕捉用户行为（如浏览商品），触发定向优惠推送。

• 案例：

• 某电商平台通过实时推送“浏览后未购买商品的用户”，转化率提升 25%。

1. 风控拦截

• 场景描述：实时识别异常行为（如频繁登录失败），触发风险拦截。

• 案例：

• 某银行通过实时分析登录行为，拦截欺诈账户，降低损失率 30%。

1. 个性化推荐

• 场景描述：根据用户实时兴趣（如搜索关键词）动态调整推荐内容。

• 案例：

• 某视频平台实时推送“用户当前观看视频的相关内容”，点击率提升 40%。

1. A/B 测试

• 场景描述：实时分配测试组与对照组，验证推送策略效果。

• 案例：

• 某社交 App 通过实时 A/B 测试优化推送文案，最终选择点击率最高的版本。

典型案例

1. 中原银行智能厅堂人脸识别推送

• 背景：银行需实时识别到店客户并推送个性化产品。

• 实现：

1. 客户进入网点，动态人脸识别获取年龄、性别、职业等标签。

1. 通过 Flink 实时分析客户业务轨迹（如查询理财产品），推算潜在需求。

1. 将产品信息通过手机银行 APP 或短信推送至客户手机。

• 效果：试点期间精准信息推送 3 万条，营销成功 1700 余笔，销售 2 亿余元。

1. 某电商平台实时优惠券推送

• 背景：用户浏览商品后未购买，需及时触发优惠券提醒。

• 实现：

1. 用户浏览商品后，Flink 检测到未购买行为，更新标签“高意向用户”。

1. 通过 Kafka 触发推送任务，向用户发送“限时优惠券”。

• 效果：转化率提升 15%，用户满意度提高 20%。

1. 社交平台实时消息推送

• 背景：优化用户活跃度，需在最佳时间推送内容。

• 实现：

1. 通过 Flink 分析用户活跃时段（如晚上 8-10 点）。

1. 在用户活跃时段自动推送热门话题或好友动态。

• 效果：用户日均使用时长增加 20%，点击率提升 30%。

9.1.5.5 人群包文件导出

• 形式：将圈选的用户集合导出为文件（如 CSV、Parquet、JSONL），包含用户 ID 及标签信息。

• 技术实现：

• 离线任务从宽表或 Bitmap 中提取数据，通过 Hadoop/Spark 批量处理生成文件，存储至对象存储（如 S3/HDFS）。

• 支持压缩（GZIP）和分块（按用户 ID 哈希分文件），便于大数据分析。

• 适用场景：

• 离线数据分析（如用 Python/Spark 分析人群特征）。

• 第三方合作（向外部机构提供脱敏后的人群数据）。

• 案例：市场部门导出 “近半年高价值用户” CSV 文件，用 Excel 分析其地域分布和消费习惯。

9.1.5.6 标签宽表同步

• 形式：定期将全量或增量画像宽表同步至下游数据仓库（如 Redshift/BigQuery）。

• 技术实现：

• 基于 CDC（变更数据捕获）技术，通过 Airflow/DolphinScheduler 调度任务，将 Hive 宽表同步至目标仓库。

• 字段映射：保留用户 ID 及所有标签字段，支持增量更新（仅同步变化数据）。

• 适用场景：

• BI 报表系统（基于宽表生成用户分群报表）。

• 数据挖掘（机器学习模型从宽表中提取特征）。

• 案例：数据分析团队从同步至 BigQuery 的宽表中，用 SQL 查询 “各年龄段用户的复购率”，生成月度运营报表。

9.1.5.7 标签字典文件

• 形式：输出标签体系的元数据（如标签名称、定义、取值范围、更新频率），通常为 JSON/Excel 格式。

• 技术实现：

• 从标签管理系统中提取元数据，人工审核后生成文件，供接入方查阅。

• 示例结构：{"tags":[{"name":"age","description":"用户年龄","values":["18-25","26-35",...],"update_freq":"daily"}]}。

• 适用场景：

• 新业务接入时的标签理解（如前端开发人员根据字典对接 API）。

• 合规审计（提供标签定义供监管机构审查）。

9.1.5.8 用户画像看板

• 形式：Web 端可视化界面，展示单用户详情或人群统计数据（如标签分布、行为趋势）。

• 技术实现：

• 前端：React/Vue + ECharts/Highcharts，后端通过 API 获取数据。

• 单用户视图：展示基础属性、核心标签、行为时间线；人群视图：展示标签分布饼图、漏斗分析。

• 适用场景：

• 运营人员查看用户详情（如高价值用户的标签构成）。

• 管理层监控核心人群变化（如会员群体的规模趋势）。

• 案例：运营人员在看板中输入用户 ID，查看该用户的 “最近购买品类”“活跃时间段” 等标签，并生成用户画像报告。

9.1.5.9 人群分析仪表盘

• 形式：多维度数据可视化面板，支持自定义圈选人群并实时展示统计指标。

• 技术实现：

• 基于 OLAP 引擎（如 ClickHouse/Starrocks）构建指标聚合层，前端通过拖拽标签条件生成可视化图表。

• 支持实时计算：如圈选 “25-30 岁女性” 后，立即展示该人群的平均消费金额、地域分布。

• 适用场景：

• 市场调研（快速分析不同人群的特征差异）。

• 活动效果评估（对比活动前后目标人群的标签变化）。

案例：某品牌通过仪表盘分析 “参与 618 活动的用户” 与 “未参与用户” 的标签差异，优化下一次营销方案