用户画像提取与管理
功能概述与核心场景
用户画像(User Memory Profiles)是 Agentbase Memory(v2.10.0)面向个性化智能体服务的核心聚合能力。在实际业务场景中,单个用户往往拥有数十甚至数百条碎片化的单条记忆(如技术栈偏好、负责的集群模块、过往工单背景、沟通风格偏好)。若每次对话仅检索零散的记忆条目,智能体难以迅速把握该用户的全局身份特征。用户画像功能通过大模型(如 dashscope-prod 下的 qwen-plus)与可配置的画像 Pipeline,将同一用户的有效来源与新对话归纳整理为高内聚的**正文画像(content)与结构化主题画像(topics)**。
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,系统为 VIP 架构师 user_zhangwei_001 与一线工程师 user_lina_002 维护动态演进的专属用户画像:
- 当
user_zhangwei_001发起技术支持请求(如工单TK-20261022-001)时,智能体工作台(Agent Workbench)通过GET /v1/memory/memories/users/user_zhangwei_001/profile或统一召回(recall)快速获取其 VIP 架构师画像,自动跳过初级科普问答,直接提供生产级 OceanBase 分布式事务与向量索引排障指令; - 随着后续会话推进,系统支持通过**增量更新(
incremental)平滑吸收新动态,也支持通过按证据重新生成(replace)或来源重建(rebuild)**修正画像偏差,且删除画像不会误删底层原始记忆。
核心概念与架构
用户画像位于原始记忆/来源(L0/L1)之上,作为用户维度的全局语义视图,与记忆检索(Query Rewrite 画像改写)和智能体系统提示词注入紧密协同。
flowchart TB
subgraph TriggerLayer["画像触发与输入源"]
AutoTrigger["自动画像触发\n(policy.autoProfileExtractionEnabled)"]
IncrementalReq["增量提取 (mode=incremental)\n新对话 messages + 既有画像"]
ReplaceReq["替换生成 (mode=replace)\n新说明 messages + 显式选中记忆 (≤100条)"]
RebuildReq["按有效来源重建 (/profile/rebuild)\n无新输入,复用当前关联的有效来源"]
end
subgraph PipelineLayer["画像 Pipeline 处理引擎 (scenario=profile)"]
Receive["1. 接收与治理校验 (receive)\n校验 userId、有效记忆归属与策略未过期"]
Generate["2. 画像生成节点 (profile_generation)\n调用 dashscope-prod / qwen-plus\n执行 prompt 或 rebuildPrompt"]
Operate["3. 事务原子写入 (profile_operation)\n同事务更新画像正文/主题与来源关联表"]
end
subgraph StorageLayer["OceanBase Shared V2 画像持久化"]
ContentView[("正文画像视图\nprofileType = content")]
TopicsView[("主题画像视图\nprofileType = topics")]
SourceLinks[("画像来源关系表\nGET /profile/sources")]
end
subgraph ConsumerLayer["下游业务消费与注入"]
AgentPrompt["Agent Runtime 系统提示词注入\n(注入 user_zhangwei_001 VIP 架构师人设)"]
QueryRewrite["记忆搜索画像改写\n(policy.profileRewriteEnabled)"]
UnifiedRecall["统一召回接口\n(POST /v1/memory/memories/recall)"]
end
AutoTrigger --> Receive
IncrementalReq --> Receive
ReplaceReq --> Receive
RebuildReq --> Receive
Receive --> Generate
Generate --> Operate
Operate --> ContentView
Operate --> TopicsView
Operate --> SourceLinks
ContentView --> AgentPrompt
TopicsView --> AgentPrompt
ContentView --> QueryRewrite
ContentView --> UnifiedRecall核心概念与模式对比
| 概念 / 操作模式 | 参数标识 | 适用场景与核心技术语义 |
|---|---|---|
| 正文画像(Content Profile) | profileType: "content" | 连贯、凝练的自然语言段落描述,直接阐述用户的职责身份、技术栈背景、沟通偏好与近期关注焦点,最适合直接拼入 Agent System Prompt。 |
| 主题画像(Topics Profile) | profileType: "topics" | 按结构化维度(如角色职能、核心系统、偏好约束、近期痛点)分类组织的主题集合,遵循 runtime.profileSchemaVersion 定义的结构规范。 |
| 增量提取(Incremental Mode) | mode: "incremental"(默认) | 将本轮新传入的 messages 合并进用户当前已有画像中,无需事先删除旧画像,适合日常会话结束后的持续演进。 |
| 重新生成(Replace Mode) | mode: "replace" | 以本轮新传入的说明 messages 为核心,结合可选传入的 sourceMemoryIds(最多 100 条同项目、同用户的有效未过期记忆),在单事务内原子替换当前画像与来源关系。 |
| 按来源重建(Rebuild) | POST /profile/rebuild | 不接收新消息输入。当项目升级了画像模型(如从 qwen-turbo 升级至 qwen-plus)、调整了 profileRebuildPrompt 或部分底层来源被遗忘清理后,基于当前仍有效的关联来源重新计算画像。 |
功能入口与权限矩阵
控制台入口与 API 映射
控制台入口位于:**项目 enterprise-ai-hub-210 → 记忆(Memory) → 画像** 页签。
| 功能动作 | 控制台操作入口 | REST API 端点 | 所需 API Key Scope | 关联说明 |
|---|---|---|---|---|
| 查询用户画像 | 输入用户 ID + 选择 content / topics → 查询 | GET /v1/memory/memories/users/{userId}/profile | memories.read | 若用户尚无画像返回 404 profile_not_found |
| 查询画像来源 | 画像详情来源区域 | GET /v1/memory/memories/users/{userId}/profile/sources | memories.read | 展示支撑当前画像版本的有效来源与记忆关联 |
| 增量更新 / 重新生成 | 增量更新 / 重新生成 操作区 | POST /v1/memory/memories/users/{userId}/profile/extractions | memories.write | 可选传入已发布的画像 pipelineId 与 sessionId |
| 按有效来源重建 | 重建画像 按钮 | POST /v1/memory/memories/users/{userId}/profile/rebuild | memories.write | 仅在模型、提示词或底层来源发生变更后按需调用 |
| 删除指定类型画像 | 删除画像 按钮 | DELETE /v1/memory/memories/users/{userId}/profile | memories.delete | 仅清除该类型画像聚合,保留底层原始记忆 |
与其他模块的协同关系
- 与直接写入记忆的关系:调用
POST /v1/memory/memories且设置infer=false直接保存一条事实,不会自动保证用户画像已生成。在首次读取画像前,请确保自动画像任务已完成,或显式调用一次画像提取接口。 - 与配置中心(Pipeline)的关系:画像生成的提示词(
profileExtractionPrompt与profileRebuildPrompt)及生成节点模型路由可在 记忆 → 配置 → 画像 Pipeline 中定制发布,详见 记忆配置中心。 - 与记忆检索(Query Rewrite)的关系:当基础配置中开启
policy.profileRewriteEnabled: true时,POST /v1/memory/memories/search会利用目标用户的画像自动补全模糊查询词(例如将user_zhangwei_001的查询“索引报错怎么查”结合其画像改写为“OceanBase Shared V2 向量索引 HNSW 构建与查询报错排查”)。
功能详解与操作指南
1. 在控制台查询与管理用户画像
- 登录 Agentbase 控制台,进入项目
企业智能客服与知识中台(enterprise-ai-hub-210),单击左侧 记忆(Memory) 并切换至 画像 页签。 - 在顶部查询栏输入目标用户 ID(例如
user_zhangwei_001或user_lina_002),在画像类型中选择 **正文(content) 或 主题(topics),单击 查询**。 - 页面展示当前生效的画像正文、画像版本号、最近更新时间以及后台画像提取任务的运行状态。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
2. 执行增量更新(incremental)与按证据重新生成(replace)
方式一:增量更新画像(吸收最新对话动态)
- 在 画像 页签操作区选择 增量更新。
- 输入目标用户 ID
user_zhangwei_001,在 Pipeline 下拉框中选择 使用默认 Pipeline(或已发布的自定义画像 Pipeline)。 - 添加新消息及角色(如
role: "user",内容:近期我们核心账务集群正在将向量检索切换为 OceanBase 1024 维 HNSW 索引,并启用了 AI 网关语义缓存 cp-semantic-cache。)。 - 单击提交后等待任务完成,再次单击 查询,即可看到新架构动态已无缝融合进张伟的既有画像中。
方式二:根据新情况重新生成画像(replace 模式)
当用户的岗位职责或系统环境发生重大切换,需要彻底刷新画像时:
- 在操作区切换为 重新生成,输入用户 ID
user_zhangwei_001与新的背景说明文本。 - 选择证据来源范围:
- 仅使用本次新输入(对应 API
sourceMemoryIds: []); - 使用该用户全部有效记忆(最多自动选取 100 条未过期、未遗忘的记忆);
- 手工勾选特定记忆证据(从列表中勾选核心记忆 ID 作为补充证据)。
- 仅使用本次新输入(对应 API
- 核对无误后提交。系统在同一数据库事务内替换画像内容与来源关联;若模型调用中途失败,事务自动回滚,绝不暴露半更新画像,且不会删除任何底层原始记忆。
3. 画像提取、重建与删除的 REST API 参数规范
以下为 /v1/memory/memories/users/{userId}/profile/* 系列接口的完整参数对照表:
| 接口与方法 | 参数名 | 类型 | 必填 | 默认值 | 详细说明与取值约束 |
|---|---|---|---|---|---|
POST .../profile/extractions | mode | string | 否 | "incremental" | 取值 "incremental"(增量合并)或 "replace"(全量替换)。 |
POST .../profile/extractions | profileType | string | 否 | "content" | 取值 "content" 或 "topics"。 |
POST .../profile/extractions | messages | array | 是 | - | 本次提取的对话消息数组,每项包含 role(user/assistant/system)与非空 content。 |
POST .../profile/extractions | sourceMemoryIds | string[] | 否 | - | **仅在 mode="replace" 时可用**,最多 100 个属于同一项目、同一用户的有效记忆 ID。 |
POST .../profile/extractions | pipelineId | string | 否 | 场景默认 | 指定当前项目已发布的 profile 场景 Pipeline ID;草稿版本会被拒绝。 |
POST .../profile/extractions | sessionId | string | 否 | 空字符串 | 最长 128 字符,用于将本次提取任务及异步 Trace 关联到指定业务会话。 |
POST .../profile/rebuild | profileType | string | 否 | "content" | 基于既有有效来源重新计算指定类型画像,不接收 messages 新输入。 |
DELETE .../profile | profileType | string | 是 | - | 指定要删除的画像类型("content" 或 "topics"),支持附带 reason 与 source 供审计记录。 |
4. 实战示例:将 user_zhangwei_001 VIP 架构师画像注入 Agent Prompt
下面展示在企业智能客服后端中,如何通过 REST API 与 agentbase-node-sdk@2.10.0 提取 user_zhangwei_001 的画像,并将其动态注入到智能体工作台(Agent Runtime)或大模型调用的系统提示词中:
# 1. 使用 cURL 触发 user_zhangwei_001 的画像增量提取
curl -fsS -X POST "https://appbuild.oceanbase.com/v1/memory/memories/users/user_zhangwei_001/profile/extractions" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: profile-ext-zhangwei-20261022" \
-H "Content-Type: application/json" \
--data '{
"mode": "incremental",
"profileType": "content",
"sessionId": "sess_ticket_TK_20261022_001",
"messages": [
{
"role": "user",
"content": "我是核心账务系统架构师张伟,目前负责 enterprise-ai-hub-210 项目的 OceanBase Shared V2 向量库与 prod-enterprise-ai-gateway 网关高可用治理,排障时请直接给出 SQL 诊断语句和网关限流参数。"
}
]
}' | jq .在 Node.js 服务端(使用 agentbase-node-sdk@2.10.0)读取该画像并构造个性化 Agent Prompt:
// 使用官方服务端 SDK: agentbase-node-sdk@2.10.0
import { Client, Memory } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210')
.setKey(process.env.APPBASE_API_KEY);
const memory = new Memory(client);
async function buildPersonalizedSystemPrompt(userId) {
let personaBlock = '当前用户尚无历史画像,请按标准企业技术支持 SOP 礼貌解答。';
try {
const profileRes = await memory.getUserProfile({
userId,
profileType: 'content'
});
if (profileRes?.profile?.content) {
personaBlock = [
`【用户专属画像 (版本 v${profileRes.profile.version})】`,
profileRes.profile.content,
'请严格遵循上述画像中的技术深度与沟通偏好进行回复,避免冗余解释。'
].join('\n');
}
} catch (err) {
// 404 profile_not_found 表示首次访问用户,安全回退默认提示词
if (err.code !== 404) throw err;
}
return `你是 Agentbase 企业智能客服专家,绑定知识库 kb_enterprise_support。\n\n${personaBlock}`;
}
// 为 VIP 架构师 user_zhangwei_001 生成专属系统提示词
const systemPrompt = await buildPersonalizedSystemPrompt('user_zhangwei_001');常见问题与排障(FAQ)
1. 为什么我已经为用户写入了多条记忆,但查询画像时仍然返回 404 profile_not_found?
- 原因分析:通过
infer=false直接写入单条记忆不会自动触发画像生成;即便开启了自动画像(policy.autoProfileExtractionEnabled),后台画像任务也是异步执行的。如果尚未触发过画像提取或后台任务仍在queued/running阶段,查询接口会返回404 profile_not_found。 - 解决措施:在 记忆 → 画像 页签为该用户手动执行一次 增量更新 或 重新生成(或调用
POST /v1/memory/memories/users/{userId}/profile/extractions),待异步任务状态变为succeeded后即可正常读取。
2. 什么时候应该使用“重新生成(mode=replace)”,什么时候应该使用“重建画像(/profile/rebuild)”?
- 原因分析:两者都会刷新画像,但输入源不同。
- 解决措施:
- 当你有新的用户说明或对话输入,希望用这批新说明配合选定的记忆证据(
sourceMemoryIds)覆盖旧画像时,使用 **重新生成(mode=replace)**; - 当你没有新的业务对话输入,仅仅是因为修改了画像 Pipeline 的
rebuildPrompt、更换了qwen-plus模型,或者删除了若干条错误的历史记忆后希望按剩余有效来源重算画像时,使用 **重建画像(/profile/rebuild)**。切勿在每次普通检索前高频调用rebuild。
- 当你有新的用户说明或对话输入,希望用这批新说明配合选定的记忆证据(
3. 删除用户画像后,该用户名下的历史记忆和原始对话会被一并删除吗?
- 原因分析:部分开发者担心调用
DELETE /v1/memory/memories/users/{userId}/profile会清空用户的底层记忆表。 - 解决措施:不会。删除画像仅移除指定
profileType(content或topics)的聚合记录及画像与来源的映射关系,底层memories表和sources表中的数据完好无损。若需彻底清理用户记忆以履行隐私合规删除,请前往 记忆管理 执行单条或按用户批量删除(DELETE /v1/memory/memories)。