提炼存储检索记忆片段用户画像-长期记忆-大模型服务平台百炼-阿里云

AI 在长对话中会遗忘关键信息，且跨会话没有记忆，导致上下文丢失、体验不连贯。为解决此痛点，我们引入了长期记忆功能。该功能可自动从历史对话中提炼并结构化存储记忆片段与用户画像。在后续对话或新会话中，开发者可以检索这些记忆并将其注入 Prompt，赋能 AI 实现真正的持续性理解。

核心功能

说明

该功能与 API 调用限时免费。

记忆片段：从对话自动提取关键内容并结构化存储为记忆片段；也可以直接指定要存入的记忆内容；支持基于历史对话检索和动态更新。
用户画像：基于自定义画像模板，从对话中提取结构化用户属性（如年龄、职业、兴趣等）。

记忆片段适用于大多数长期记忆场景；当需要抽取固定属性时，建议搭配用户画像功能使用该功能。

生成的记忆片段与用户画像暂无失效日期。

适用范围

长期记忆功能通过开放的 API 接口，可接入任意应用，也支持多应用共享同一记忆库。

相比长期记忆（旧）的改进

速度与效率高：拥有更低的延迟，更高的记忆检索召回效果。
自动提取能力：支持从对话中自动提取关键信息，自动去重，无需手动输入。
检索算法优化：新增语义检索能力，检索准确性显著提升，响应速度更快。
用户画像能力：新增完整的用户画像提取和管理能力。

使用方法

使用前需要配置环境变量DASHSCOPE_API_KEY，获取与配置方式请参考获取 API Key。

添加与记忆片段

建立记忆：通过 AddMemory 保存上一轮对话内容，转换为记忆节点并构建语义索引。
检索记忆：通过 SearchMemory 基于语义检索相关历史记忆。

最佳实践：在每轮对话结束后及时调用 AddMemory 保存记忆，检索时建议将 top_k 设置在 3 到 10 之间，平衡性能和效果。

cURL

# 添加记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "每天上午9点提醒我喝水"},
      {"role": "assistant", "content": "好的，已记录"}
    ]
  }'

# 搜索记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "我需要做什么？"}
    ],
    "top_k": 5
  }'

Python

from agentscope_runtime.tools.modelstudio_memory import (
    AddMemory, SearchMemory, Message, AddMemoryInput, SearchMemoryInput,
)
import asyncio

async def basic_example():
    add_memory = AddMemory()
    search_memory = SearchMemory()

    try:
        # 添加记忆
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            messages=[
                Message(role="user", content="每天上午9点提醒我喝水"),
                Message(role="assistant", content="好的，已记录"),
            ]
        ))

        await asyncio.sleep(2)

        # 搜索记忆
        result = await search_memory.arun(SearchMemoryInput(
            user_id="user_001",
            messages=[Message(role="user", content="我需要做什么？")],
            top_k=5
        ))

        for node in result.memory_nodes:
            print(f"记忆: {node.content}")

    finally:
        await add_memory.close()
        await search_memory.close()

asyncio.run(basic_example())

更新记忆片段

管理记忆：通过 ListMemories、UpdateMemory、DeleteMemory 管理记忆节点，支持元数据分类和智能去重。

最佳实践：使用元数据对记忆进行分类管理（如按类别、优先级等），便于后续的精确检索和管理。

cURL

# 添加记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "每天上午9点提醒我喝水"},
      {"role": "assistant", "content": "好的，已记录"}
    ]
  }'

# 列出记忆
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
 
# 更新记忆
curl --location --request PATCH 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "custom_content": "还要提醒我上午10点吃药。"
  }'
  
# 查看更新的记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "我需要做什么？"}
    ],
    "top_k": 5
  }'

# 删除记忆
curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

提取用户画像

创建画像模板：通过 CreateProfileSchema 定义需要提取的用户属性。
提取画像：调用 AddMemory 时传入画像模板 ID，从对话中提取用户属性并更新画像。
获取画像：通过 GetUserProfile 获取完整的用户画像信息。

最佳实践：画像字段及描述应该清晰、具体，避免过于抽象。不应期望一次对话就能提取所有信息，应通过多轮对话收集。

cURL

# 创建画像 Schema
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "用户基础画像",
    "description": "包含年龄和兴趣的用户信息",
    "attributes": [
      {"name": "年龄", "description": "用户年龄"},
      {"name": "爱好", "description": "用户的兴趣爱好"},
      {"name": "职业", "description": "用户职业"}
    ]
  }'

# 添加包含画像信息的对话（使用上面返回的 profile_schema_id）
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "我今年28岁，是一名软件工程师。周末喜欢踢足球。"},
      {"role": "assistant", "content": "很高兴认识你！"}
    ],
    "profile_schema": "YOUR_SCHEMA_ID"
  }'

# 获取用户画像（等待3秒后执行）
curl -X GET "https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{YOUR_SCHEMA_ID}/user_profile?user_id=user_001" \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json"

Python

from agentscope_runtime.tools.modelstudio_memory import (
    CreateProfileSchema, GetUserProfile, AddMemory,
    ProfileAttribute, CreateProfileSchemaInput,
    GetUserProfileInput, AddMemoryInput, Message,
)
import asyncio

async def profile_example():
    create_schema = CreateProfileSchema()
    get_profile = GetUserProfile()
    add_memory = AddMemory()

    try:
        # 创建画像 Schema
        schema_result = await create_schema.arun(CreateProfileSchemaInput(
            name="用户基础画像",
            description="包含年龄和兴趣的用户信息",
            attributes=[
                ProfileAttribute(name="年龄", description="用户年龄"),
                ProfileAttribute(name="爱好", description="用户的兴趣爱好"),
                ProfileAttribute(name="职业", description="用户职业"),
            ]
        ))
        schema_id = schema_result.profile_schema_id

        # 添加包含画像信息的对话
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            messages=[
                Message(role="user", content="我今年28岁，是一名软件工程师。周末喜欢踢足球。"),
                Message(role="assistant", content="很高兴认识你！"),
            ],
            profile_schema=schema_id
        ))

        await asyncio.sleep(3)  # 等待画像提取

        # 获取提取的画像
        profile = await get_profile.arun(GetUserProfileInput(
            schema_id=schema_id, user_id="user_001"
        ))
        for attr in profile.profile.attributes:
            print(f"{attr.name}: {attr.value or '未提取'}")

    finally:
        await create_schema.close()
        await get_profile.close()
        await add_memory.close()

asyncio.run(profile_example())

环境变量配置

环境变量	必需	默认值	说明
`DASHSCOPE_API_KEY`	是	-	百炼 API 密钥，获取方式请参见获取 API Key

依赖配置

Python SDK

# Python >= 3.10
# agentscope-runtime 版本要求：>= 1.0.5
pip install "agentscope-runtime>=1.0.5"

核心组件

1. AddMemory - 添加记忆

将用户对话存储为记忆，自动提取关键信息和用户画像。

请求体参数：

参数名	类型	必填	说明
user_id	string	是	用户自定义 ID
messages	array	是（与custom_content二选一）	对话消息列表，每个消息包含 `role`（user/assistant）和 `content`（文本或多模态内容）。支持多模态格式，参考全模态输入
messages[0].role	string	-	消息角色，可选值：`user`（用户消息）或 `assistant`（助手回复）
messages[0].content	string \| array	-	消息内容，支持多模态。可以是字符串（纯文本）或数组（多模态内容）。多模态格式参考全模态输入格式，支持文本、图片等多种内容类型。
custom_content	string	是（与messages二选一）	自定义内容（与messages二选一）
profile_schema	string	否	画像模板 ID
meta_data	object	否	用户自定义信息

返回结果：

返回字段包括：

request_id (string) - 请求ID
memory_nodes (array) - 变更的记忆列表，结构如下：

字段	类型	说明
memory_node_id	string	记忆节点 ID
content	string	记忆内容（从对话中提取）
event	string	操作事件类型：CREATE（创建）、UPDATE（更新）、DELETE（删除）
old_content	string	过去的内容，仅当event为"UPDATE"时有效

示例代码：

cURL

# 添加记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "messages": [{
      "role": "user",
      "content": "你好"
    }, {
      "role": "assistant",
      "content": "你好，有什么可以帮您"
    }, {
      "role": "user",
      "content": "每天上午11点提醒我点外卖。"
    }, {
      "role": "assistant",
      "content": "没问题"
    }, {
      "role": "user",
      "content": "明天10点提醒我整理会议纪要。"
     }
    ],
    "user_id": "user_001",
    "meta_data": {
      "location_name": "北京",
      "geo_coordinate": "116.481499,39.990475"
    }
  }'

# response
{
  "memory_nodes": [{
    "content": "用户要求每天上午11点提醒他点外卖",
    "event": "ADD",
    "memory_node_id": "50b46e9751504556a1a49a11b7639b3d"
  }, {
    "content": "用户要求明天10点提醒他整理会议纪要",
    "event": "ADD",
    "memory_node_id": "381cc694e4144dffbd546059189ce498"
  }],
  "request_id": "bec69131-627c-4636-a2ff-e71c0c8a5c53"
}

# 添加记忆（自定义内容）
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_content": "用户周末去上海参加WAIC",
    "user_id": "user_001",
    "meta_data": {
      "custom_key": "custom_value"
    }
  }'

Python

from agentscope_runtime.tools.modelstudio_memory import (
    AddMemory, Message, AddMemoryInput,
)
import asyncio

async def add_memory_example():
    add_memory = AddMemory()
    try:
        result = await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            messages=[
                Message(role="user", content="每天上午9点提醒我喝水"),
                Message(role="assistant", content="好的，已记录"),
            ],
            meta_data={"category": "提醒", "priority": "中"}
        ))
        print(f"创建了 {len(result.memory_nodes)} 个记忆节点")
    finally:
        await add_memory.close()

asyncio.run(add_memory_example())

2. SearchMemory - 搜索记忆

基于语义相似度搜索相关历史对话。

请求体参数：

参数名	类型	必填	说明
user_id	string	是	用户自定义 ID
messages	array	是	对话记录，支持多模态。多模态格式参考全模态输入格式。
messages[0].role	string	-	消息角色，可选值：`user`（用户消息）或 `assistant`（助手回复）
messages[0].content	string \| array	-	消息内容，支持多模态。多模态格式参考全模态输入格式。
top_k	integer	否	最大召回个数（默认 10）
min_score	double	否	最小相似度分数阈值，值域 [0,100]

返回结果：

返回字段包括：

request_id (string) - 请求 ID
memory_nodes (array) - 记忆节点列表，包含以下字段：

字段	类型	说明
memory_node_id	string	记忆节点 ID
content	string	记忆内容（从对话中提取）
created_at	long	创建时间
updated_at	long	更新时间

示例代码：

cURL

# 搜索记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [{
      "role": "user",
      "content": "你好"
    }, {
      "role": "assistant",
      "content": "你好"
    }, {
      "role": "user",
      "content": "明天上午十一点我有什么日程安排吗？"
    }],
    "top_k": 100,
    "min_score": 0
  }'

# response
{
  "memory_nodes": [{
    "updated_at": 1752941349,
    "created_at": 1752941349,
    "memory_node_id": "cce2393d894b477f8b207ba4d3aa70da",
    "content": "- 用户希望每天下午3点提醒他喝水\n- 用户最近在备考，且表示学习效率不高"
  }, {
    "updated_at": 1752941151,
    "created_at": 1752941151,
    "memory_node_id": "e9af5fbb696748d6b0133429e8c68b47",
    "content": "- 用户要求每天下午3点提醒他喝水\n- 用户最近在备考，学习效率不高，需要建议"
  }],
  "request_id": "cd6b32ef-a1ba-9ce1-af64-37f61e30e814"
}

Python

from agentscope_runtime.tools.modelstudio_memory import (
    SearchMemory, Message, SearchMemoryInput,
)
import asyncio

async def search_memory_example():
    search_memory = SearchMemory()
    try:
        result = await search_memory.arun(SearchMemoryInput(
            user_id="user_001",
            messages=[Message(role="user", content="我需要做什么？")],
            top_k=5,
            min_score=0.5
        ))
        for node in result.memory_nodes:
            print(f"记忆: {node.content}")
    finally:
        await search_memory.close()

asyncio.run(search_memory_example())

3. ListMemory - 列出记忆

分页查看用户的所有记忆。

查询参数：

参数名	类型	必填	说明
user_id	string	是	用户自定义 ID
page_num	integer	否	页码（从 1 开始，默认 1）
page_size	integer	否	每页条目数（默认 10）

返回结果：

返回字段包括：

request_id (string) - 请求 ID
memory_nodes (array) - 记忆节点列表，包含以下字段：

字段	类型	说明
memory_node_id	string	记忆节点 ID
content	string	记忆内容（从对话中提取）
created_at	long	创建时间
updated_at	long	更新时间
meta_data	object	用户自定义信息

分页字段：

total (string) - 总数
page_size (integer) - 每页大小
page_num (integer) - 页号

示例代码：

cURL

# 列出记忆
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "memory_nodes": [{
    "updated_at": 1752941349,
    "created_at": 1752941349,
    "memory_node_id": "cce2393d894b477f8b207ba4d3aa70da",
    "content": "- 用户希望每天下午3点提醒他喝水\n- 用户最近在备考，且表示学习效率不高"
  }, {
    "updated_at": 1752941151,
    "created_at": 1752941151,
    "memory_node_id": "e9af5fbb696748d6b0133429e8c68b47",
    "content": "- 用户要求每天下午3点提醒他喝水\n- 用户最近在备考，学习效率不高，需要建议"
  }],
  "page_size": 10,
  "page_num": 1,
  "total": 100,
  "request_id": "cc2690f9f2b3485a93013e5705c91241"
}

Python

from agentscope_runtime.tools.modelstudio_memory import (
    ListMemory, ListMemoryInput,
)
import asyncio

async def list_memory_example():
    list_memory = ListMemory()
    try:
        result = await list_memory.arun(ListMemoryInput(
            user_id="user_001",
            page_num=1,
            page_size=10
        ))
        for node in result.memory_nodes:
            print(f"记忆ID: {node.memory_node_id}, 内容: {node.content}")
    finally:
        await list_memory.close()

asyncio.run(list_memory_example())

4. DeleteMemory - 删除记忆

删除指定的记忆节点。

路径参数：memory_node_id - 记忆节点 ID

查询参数：

参数名	类型	必填	说明
user_id	string	是	用户自定义 ID (仅 Python SDK 需要填写)
memory_node_id	String	是	记忆片段Id

示例代码：

cURL

# 删除记忆
curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "request_id": "cc2690f9f2b3485a93013e5705c91241"
}

Python

from agentscope_runtime.tools.modelstudio_memory import (
    DeleteMemory, DeleteMemoryInput,
)
import asyncio

async def delete_memory_example():
    delete_memory = DeleteMemory()
    try:
        result = await delete_memory.arun(DeleteMemoryInput(
            user_id="user_001",
            memory_node_id="node_abc123"
        ))
        print(f"删除成功: {result.success}")
    finally:
        await delete_memory.close()

asyncio.run(delete_memory_example())

5. UpdateMemory - 更新记忆

更新记忆内容。

路径参数：memory_node_id - 记忆节点 ID

请求体参数：

参数名	类型	必填	说明
custom_content	string	是	要更新的记忆内容
user_id	string	是	用户自定义 ID
timestamp	long	否	记忆发生时的时间戳（秒级Unix时间戳，默认现在）
meta_data	object	否	用户自定义信息（增量更新）

返回结果：request_id (string) - 请求 ID

示例代码：

cURL

# 更新记忆
curl --location --request PATCH 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "custom_content": "{new_memory_custom_content}",
    "timestamp": 1747278460,
    "meta_data": {
      "custom_key": "custom_value"
    }
  }'

# response
{
  "request_id": "23d4f8bf-5e39-43ef-925a-82cf7757ec70"
}

6. CreateProfileSchema - 创建画像模板

请求体参数：

参数名	类型	必填	说明
name	string	是	模板名称
description	string	否	模板描述
attributes	array	是	模板的属性维度数组
attributes[0].name	string	是	属性名称，应该尽可能保证在语义中唯一，不然会对抽取效果有一定影响，如["姓名"、"名称"、"名字"]，["年龄"，"年纪"，"岁数"]不应该同时出现
attributes[0].description	string	否	描述
attributes[0].default_value	string	否	初始值，选填

返回结果：

request_id (string) - 请求 ID
profile_schema_id (string) - 画像 ID

示例代码：

cURL

# 创建画像模板
curl --location "https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas" \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "{your_profile_schema_name}",
    "description": "{schema_description}",
    "attributes": [
      {"name": "年龄", "description": "用户的年龄", "default_value": "18"},
      {"name": "年龄段", "description": "用户当前所处的年龄阶段（如小学生、初中生、高中生、大学生、青年、中年、老年等）。"},
      {"name": "民族", "description": "用户的民族或种族背景。"},
      {"name": "性别", "description": "用户的性别认同或自我表达。"},
      {"name": "家庭成员", "description": "提及的家庭成员及其关系（如父母、兄弟姐妹、子女等）。"},
      {"name": "居住地", "description": "用户目前居住的城市、地区或国家。"},
      {"name": "饮食习惯", "description": "用户是否有特定饮食偏好或限制（如素食、忌口、节食、酸甜苦辣咸等）。"},
      {"name": "爱好", "description": "用户提到的兴趣爱好、休闲活动等。"},
      {"name": "使用平台", "description": "用户常使用的社交平台、内容平台或设备系统。"},
      {"name": "内容偏好", "description": "用户喜欢阅读或观看的内容类型（如新闻、娱乐、科技、动漫等）。"},
      {"name": "宠物", "description": "用户是否养宠物及其种类、数量。"},
      {"name": "宗教限制", "description": "用户的宗教信仰及相关的禁忌或行为规范。"},
      {"name": "童年经历", "description": "用户提及的童年记忆、成长环境等。"},
      {"name": "人生事件", "description": "用户经历的重要人生节点（如升学、毕业、就业、搬家等）。"},
      {"name": "收藏品/所有物", "description": "用户拥有的贵重物品、收藏品或特别提及的物品。"},
      {"name": "游戏", "description": "用户玩的游戏类型、偏好或成就。"},
      {"name": "负面情绪", "description": "用户表达的焦虑、压力、不满或困扰。"},
      {"name": "幸福来源", "description": "用户提到的让自己感到幸福、满足的事物或经历。"},
      {"name": "家庭关系", "description": "用户与家人之间的关系质量（如亲密、疏远、冲突等）。"},
      {"name": "人生理想/目标", "description": "用户的长远目标、梦想或人生规划。"},
      {"name": "社会关系（朋友圈）", "description": "用户的朋友圈构成、社交习惯或重要社交关系。"},
      {"name": "近期活动", "description": "用户近期所进行的活动或行为。"}
    ]
  }'

# response
{
  "profile_schema_id": "d148aac7f4ff42f598e3fcbc6eae4de3",
  "request_id": "23d4f8bf-5e39-43ef-925a-82cf7757ec70"
}

Python

from agentscope_runtime.tools.modelstudio_memory import (
    CreateProfileSchema, ProfileAttribute, CreateProfileSchemaInput,
)
import asyncio

async def create_schema_example():
    create_schema = CreateProfileSchema()
    try:
        result = await create_schema.arun(CreateProfileSchemaInput(
            name="用户基础画像",
            description="包含年龄、兴趣和职业的用户信息",
            attributes=[
                ProfileAttribute(name="年龄", description="用户年龄"),
                ProfileAttribute(name="爱好", description="用户的兴趣爱好"),
                ProfileAttribute(name="职业", description="用户职业"),
            ]
        ))
        print(f"创建的画像模板 ID: {result.profile_schema_id}")
    finally:
        await create_schema.close()

asyncio.run(create_schema_example())

7. ListProfileSchemas - 获取画像模板列表

分页获取所有画像模板列表。

查询参数：

参数名	类型	必填	说明
page_size	integer	否	每页条目数（默认 10）
page_num	integer	否	页码（从 1 开始，默认 1）

返回结果：

request_id (string) - 请求 ID
profile_schemas (array) - 画像模板列表，每个模板包含：
name (string) - profile名称
description (string) - profile描述
profile_schema_id (string) - 画像 ID
total (integer) - 总数

示例代码：

cURL

# 获取画像模板列表
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas?page_size=10&page_num=1' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "profile_schemas": [
    {
      "name": "{your_profile_schema_name}",
      "description": "{schema_description}",
      "profile_schema_id": "2dd5b7961ac44630949db7533f796b18"
    },
    {
      "description": "测试description",
      "name": "测试profile_schema",
      "profile_schema_id": "fa06b80b08e1445bb128d2ea8373aef3"
    }
  ],
  "request_id": "25b10053-194d-48e2-9189-3e3d868afcf2",
  "total": 2
}

8. DeleteProfileSchema - 删除画像模板

删除指定的画像模板。

路径参数：profile_schema_id - 画像模板 ID

返回结果：request_id (string) - 请求ID

示例代码：

cURL

# 删除画像模板
curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{profile_schema_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "request_id": "23d4f8bf-5e39-43ef-925a-82cf7757ec70"
}

9. UpdateProfileSchema - 更新画像模板

更新画像模板的名称、描述和属性。

路径参数：profile_schema_id - 画像模板 ID

请求体参数：

参数名	类型	必填	说明
name	string	否	模板名称
description	string	否	模板描述
attributes_operations	array	否	属性操作列表
attributes_operations[0].op	string	是	操作类型：`add`（新增属性）、`update`（更新属性）、`delete`（删除属性）
attributes_operations[0].attribute_id	string	否	要操作的属性标识（操作类型为更新或删除时必填）
attributes_operations[0].name	string	否	属性名称（操作类型为新增时必填）
attributes_operations[0].description	string	否	描述
attributes_operations[0].default_value	string	否	默认值

返回结果：request_id (string) - 请求ID

示例代码：

cURL

# 更新画像模板
curl --location --request PATCH 'https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{profile_schema_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New Schema Name",
    "description": "New schema description",
    "attributes_operations": [
      {
        "op": "add",
        "name": "plan",
        "description": "User subscription plan",
        "default_value": "free"
      },
      {
        "op": "update",
        "attribute_id": "attr_1",
        "name": "plan_v2",
        "description": "Updated description",
        "default_value": null
      },
      {
        "op": "delete",
        "attribute_id": "attr_2"
      }
    ]
  }'

# response
{
  "request_id": "733715b5-23b1-4bf5-87b7-076f72e7181f"
}

10. GetProfileSchema - 获取画像模板详情

获取指定画像模板的详细信息。

路径参数：profile_schema_id - 画像模板 ID

返回结果：

request_id (string) - 请求ID
name (string) - profile名称
description (string) - profile描述
attributes (array) - 属性列表，每个属性包含：
attribute_id (string) - 属性ID
name (string) - 名称
description (string) - 描述
default_value (string) - 实体初始值

示例代码：

cURL

# 获取画像模板详情
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{profile_schema_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "attributes": [
    {
      "attribute_id": "0050023926374ef397b9cf06542a287c",
      "default_value": "更新default_value",
      "description": "更新attribute",
      "name": "更新attribute"
    },
    {
      "attribute_id": "0270aff7e631425c91595455ff8a65cf",
      "description": "用户的长远目标、梦想或人生规划。",
      "name": "人生理想/目标"
    },
    {
      "attribute_id": "092fc04dd42241f5842dedb1ec6d9575",
      "description": "提及的家庭成员及其关系（如父母、兄弟姐妹、子女等）。",
      "name": "家庭成员"
    }
  ],
  "name": "{your_profile_schema_name}",
  "description": "{schema_description}",
  "request_id": "22e73019-c24d-4885-9cbd-89e6cb7ca801"
}

11. GetUserProfile - 获取用户画像

获取系统自动提取的用户画像信息。

路径参数：profile_schema_id - 画像模板 ID

查询参数：user_id - 用户自定义 ID

返回结果：

返回字段包括：

request_id (string) - 请求ID
profile (object) - 用户画像对象，包含以下字段：

字段	类型	说明
schema_name	string	profile名称
schema_description	string	profile描述
attributes	array	属性列表，每个属性包含以下字段：

attributes 字段：

字段	类型	说明
attribute_id (id)	string	attribute_id
name	string	名称
value	string	value（提取的属性值，未提取时不存在此字段）

示例代码：

cURL

# 获取用户画像
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{profile_schema_id}/user_profile?user_id={user_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# response
{
  "profile": {
    "attributes": [
      {
        "id": "00484806d4a343198d61abe8a0d8ae84",
        "name": "家庭关系"
      },
      {
        "id": "05fa398b8386454999a685d246bb2f91",
        "name": "使用平台"
      },
      {
        "id": "09100265f3d341a79e2916fa623b9ffc",
        "name": "宗教限制"
      },
      {
        "id": "14bb432a07c64dad82033e2613db7a9c",
        "name": "人生事件",
        "value": "27岁生日"
      },
      {
        "id": "15c3d7da69584e7c8b9b51c62afc121b",
        "name": "游戏"
      },
      {
        "id": "2f4d4a48125a45beb22f45f7578b167e",
        "name": "内容偏好"
      },
      {
        "id": "4d4a765760c749d082d82eb81029bd44",
        "name": "爱好"
      },
      {
        "id": "614991ce106b4e27a369c04204cd4412",
        "name": "民族"
      },
      {
        "id": "6cc071fb3e764128a2313443bff7eb70",
        "name": "负面情绪"
      },
      {
        "id": "8afa889cbe504ff69551d729a1a0df53",
        "name": "收藏品/所有物"
      },
      {
        "id": "8f73380e494b4b0fab6da1ed64b27eee",
        "name": "性别",
        "value": "男"
      },
      {
        "id": "8fb150e4acf8421cb2825c382e695ea2",
        "name": "家庭成员"
      },
      {
        "id": "93d5d2cb8b8b4b3bbfdea44a69b63642",
        "name": "近期活动",
        "value": "整理会议纪要"
      },
      {
        "id": "a118ec78a5874251b1892e148eef76d7",
        "name": "宠物",
        "value": "一只叫伊恩的小狗"
      },
      {
        "id": "a7a1023d69b74e23852165ffe1a7d249",
        "name": "年龄段",
        "value": "青年"
      },
      {
        "id": "aeb1c823222f4cdd849859403b2a9ff5",
        "name": "年龄",
        "value": "27岁"
      },
      {
        "id": "dca26843674945c59d7b822ae51c8f33",
        "name": "幸福来源"
      },
      {
        "id": "e11e8a29dd3b4c71b26bbd9b4283f65e",
        "name": "饮食习惯"
      },
      {
        "id": "f040cf561d8d461693d9d768ddcaa86c",
        "name": "人生理想/目标"
      },
      {
        "id": "f0c6744a65e44c2991e6b04864f05d6c",
        "name": "居住地"
      },
      {
        "id": "fe1be71415c6436f849064aeb781d7c3",
        "name": "社会关系（朋友圈）"
      },
      {
        "id": "ff87d78ca1e24018985d80157d1dc266",
        "name": "童年经历"
      }
    ],
    "schemaDescription": "用户画像001的描述",
    "schemaName": "用户画像001"
  },
  "requestId": "e5986fe3-6f2b-4381-892b-01528443790e"
}

Python

from agentscope_runtime.tools.modelstudio_memory import (
    GetUserProfile, GetUserProfileInput,
)
import asyncio

async def get_profile_example():
    get_profile = GetUserProfile()
    try:
        result = await get_profile.arun(GetUserProfileInput(
            schema_id="schema_abc123",
            user_id="user_001"
        ))
        for attr in result.profile.attributes:
            print(f"{attr.name}: {attr.value or '未提取'}")
    finally:
        await get_profile.close()

asyncio.run(get_profile_example())

错误处理

调用记忆服务时可能遇到以下常见错误：

错误码	HTTP 状态码	说明	处理建议
InvalidApiKey	401	API Key 无效或未配置	检查环境变量 DASHSCOPE_API_KEY 是否正确配置
UserNotFound	404	指定的 user_id 不存在	确认 user_id 正确，或先调用 AddMemory 创建用户记忆
TooManyRequests	429	请求频率超过限制	降低请求频率，建议两次请求间隔至少 1 秒
InternalError	500	服务内部错误	稍后重试，如持续出现请联系技术支持

更多错误码信息，请参考错误信息。

常见问题

API 是否存在限流？

API 接口	限流（阿里云账号级别）
全部接口	总计不超过 3000 QPM
记忆片段 add 接口	120 QPM
记忆片段 search 接口	300 QPM

核心功能

适用范围

相比长期记忆（旧）的改进

使用方法

添加与记忆片段

cURL

Python

更新记忆片段

cURL

提取用户画像

cURL

Python

环境变量配置

依赖配置

Python SDK

核心组件

1. AddMemory - 添加记忆

cURL

Python

2. SearchMemory - 搜索记忆

cURL

Python

3. ListMemory - 列出记忆

cURL

Python

4. DeleteMemory - 删除记忆

cURL

Python

5. UpdateMemory - 更新记忆

cURL

6. CreateProfileSchema - 创建画像模板

cURL

Python

7. ListProfileSchemas - 获取画像模板列表

cURL

8. DeleteProfileSchema - 删除画像模板

cURL

9. UpdateProfileSchema - 更新画像模板

cURL

10. GetProfileSchema - 获取画像模板详情

cURL

11. GetUserProfile - 获取用户画像

cURL

Python

错误处理

相关文档

常见问题

API 是否存在限流？