Docs
文档目录

用户画像提取与管理

功能概述与核心场景

用户画像(User Memory Profiles)是 Agentbase Memory面向个性化智能体服务的核心聚合能力。在实际业务场景中,单个用户往往拥有数十甚至数百条碎片化的单条记忆(如技术栈偏好、负责的集群模块、过往工单背景、沟通风格偏好)。若每次对话仅检索零散的记忆条目,智能体难以迅速把握该用户的全局身份特征。用户画像功能通过大模型(如 dashscope-prod 下的 qwen-plus)与可配置的画像 Pipeline,将同一用户的有效来源与新对话归纳整理为高内聚的正文画像(content)与结构化主题画像(topics)。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的示例项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,系统为 VIP 架构师 user_zhangwei_001 与一线工程师 user_lina_002 维护动态演进的专属用户画像:


核心概念与架构

用户画像位于原始记忆/来源(L0/L1)之上,作为用户维度的全局语义视图,与记忆检索(Query Rewrite 画像改写)和智能体系统提示词注入紧密协同。

用户画像提取与管理:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念与模式对比

概念 / 操作模式参数标识适用场景与核心技术语义
正文画像(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}/profilememories.read画像缺失可能返回 404;错误类型以目标环境的实际响应为准
查询画像来源画像详情来源区域GET /v1/memory/memories/users/{userId}/profile/sourcesmemories.read展示支撑当前画像版本的有效来源与记忆关联
增量更新 / 重新生成增量更新 / 重新生成 操作区POST /v1/memory/memories/users/{userId}/profile/extractionsmemories.write可选传入已发布的画像 pipelineId 与 sessionId
按有效来源重建重建画像 按钮POST /v1/memory/memories/users/{userId}/profile/rebuildmemories.write仅在模型、提示词或底层来源发生变更后按需调用
删除指定类型画像删除画像 按钮DELETE /v1/memory/memories/users/{userId}/profilememories.delete仅清除该类型画像聚合,保留底层原始记忆

与其他模块的协同关系


功能详解与操作指南

1. 在控制台查询与管理用户画像

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),单击左侧 记忆(Memory) 并切换至 画像 页签。

  2. 在顶部查询栏输入目标用户 ID(例如 user_zhangwei_001 或 user_lina_002),在画像类型中选择 正文(content) 或 主题(topics),单击 查询。

  3. 页面展示当前生效的画像正文、画像版本号、最近更新时间以及后台画像提取任务的运行状态。

用户画像视图

图:2.12.0 测试项目中的合成画像示例。

2. 执行增量更新(incremental)与按证据重新生成(replace)

方式一:增量更新画像(吸收最新对话动态)

  1. 在 画像 页签操作区选择 增量更新。

  2. 输入目标用户 ID user_zhangwei_001,在 Pipeline 下拉框中选择 使用默认 Pipeline(或已发布的自定义画像 Pipeline)。

  3. 添加新消息及角色(如 role: "user",内容:近期我们核心账务集群正在将向量检索切换为 OceanBase 1024 维 HNSW 索引,并在 AI 网关配置了工具接入。)。

  4. 提交后查看实际处理结果,再次单击 查询 并核对画像及其来源。

方式二:根据新情况重新生成画像(replace 模式)

当用户的岗位职责或系统环境发生重大切换,需要彻底刷新画像时:

  1. 在操作区切换为 重新生成,输入用户 ID user_zhangwei_001 与新的背景说明文本。

  2. 选择证据来源范围:

    • 仅使用本次新输入(对应 API sourceMemoryIds: []);

    • 全部有效记忆(最多 100 条):控制台取列表加载的记录并排除画像来源记录;数量较多时不能视为该用户全部记忆;

    • 手工勾选特定记忆证据(从列表中勾选核心记忆 ID 作为补充证据)。

  3. 核对无误后提交。系统在同一数据库事务内替换画像内容与来源关联;若模型调用中途失败,事务自动回滚,绝不暴露半更新画像,且不会删除任何底层原始记忆。

3. 画像提取、重建与删除的 REST API 参数规范

以下为 /v1/memory/memories/users/{userId}/profile/* 系列接口的完整参数对照表:

接口与方法参数名类型必填默认值详细说明与取值约束
POST .../profile/extractionsmodestring否"incremental"取值 "incremental"(增量合并)或 "replace"(全量替换)。
POST .../profile/extractionsprofileTypestring否"content"取值 "content" 或 "topics"。
POST .../profile/extractionsmessagesarray是-本次提取的对话消息数组,每项包含 role(user/assistant/system)与非空 content。
POST .../profile/extractionssourceMemoryIdsstring[]否-仅在 mode="replace" 时可用,最多 100 个属于同一项目、同一用户的有效记忆 ID。
POST .../profile/extractionspipelineIdstring否场景默认指定当前项目已发布的 profile 场景 Pipeline ID;草稿版本会被拒绝。
POST .../profile/extractionssessionIdstring否空字符串最长 128 字符,用于将本次提取任务及异步 Trace 关联到指定业务会话。
POST .../profile/rebuildprofileTypestring否"content"基于既有有效来源重新计算指定类型画像,不接收 messages 新输入。
DELETE .../profileprofileTypestring是-指定要删除的画像类型("content" 或 "topics"),支持附带 reason 与 source 供审计记录。

4. 实战示例:将 user_zhangwei_001 VIP 架构师画像注入 Agent Prompt

下面展示在企业智能客服后端中,如何通过 REST API 与 agentbase-node-sdk@2.12.0 提取 user_zhangwei_001 的画像,并将其动态注入到智能体工作台(Agent Runtime)或大模型调用的系统提示词中:

为每次新的画像提取设置独立的 PROFILE_IDEMPOTENCY_KEY;仅在重试同一次提交时沿用原键和相同请求内容。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
  : "${PROFILE_IDEMPOTENCY_KEY:?Set a unique key for this new extraction}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
# 1. 使用 cURL 触发 user_zhangwei_001 的画像增量提取
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/users/user_zhangwei_001/profile/extractions" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "Idempotency-Key: ${PROFILE_IDEMPOTENCY_KEY}" \
  -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.12.0)读取该画像并构造个性化 Agent Prompt:

运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。

// 使用官方服务端 SDK: agentbase-node-sdk@2.12.0
import { Client, Memory } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY);

const memory = new Memory(client);

async function buildPersonalizedSystemPrompt(userId) {
    let personaBlock = '当前用户尚无历史画像,请按标准企业技术支持 SOP 礼貌解答。';

    try {
        const profileRes = await memory.getProfile({
            userId,
            profileType: 'content'
        });
        if (profileRes?.profile?.profileContent) {
            personaBlock = [
                `【用户专属画像 (版本 v${profileRes.profile.version})】`,
                profileRes.profile.profileContent,
                '请严格遵循上述画像中的技术深度与沟通偏好进行回复,避免冗余解释。'
            ].join('\n');
        }
    } catch (err) {
        // 仅明确的 profile_not_found 才回退;其他错误由调用方处理
        if (err.code !== 404 || err.type !== 'profile_not_found') throw err;
    }

    return `你是 Agentbase 企业智能客服专家,绑定知识库 kb_enterprise_support。\n\n${personaBlock}`;
}

// 为 VIP 架构师 user_zhangwei_001 生成专属系统提示词
const systemPrompt = await buildPersonalizedSystemPrompt('user_zhangwei_001');

部分部署把缺少画像映射为 memory_not_found,该类型也可能表示其他资源不存在;上例会继续抛出,调用方应先核实原因再决定是否使用默认提示词。


常见问题与排障(FAQ)

1. 为什么写入记忆后查询画像仍返回 404?

2. 什么时候应该使用“重新生成(mode=replace)”,什么时候应该使用“重建画像(/profile/rebuild)”?

3. 删除用户画像后,该用户名下的历史记忆和原始对话会被一并删除吗?


相关文档