Skip to main content

记忆库用于阿里云百炼应用

介绍如何在阿里云百炼平台的工作流应用和高代码应用中集成记忆库，通过 API 调用赋予应用跨会话的长期记忆能力。

概述

记忆库提供独立的 API 接口，可集成到阿里云百炼平台的应用中。集成后，应用能够跨会话积累和引用用户的历史信息，提供个性化的对话体验。 阿里云百炼平台提供三种应用类型，其中工作流应用和高代码应用支持集成记忆库：
应用类型是否支持记忆库集成方式
智能体应用不支持智能体应用暂不支持集成记忆库
工作流应用支持在工作流编辑器中使用 API 组件调用记忆库 API
高代码应用支持在上传的代码包中直接编写 API 调用代码

前提条件

在开始集成前，请确保满足以下条件：
  • 已创建记忆库：在阿里云百炼控制台创建一个记忆库。详细步骤请参见创建记忆库。
  • 已获取 API Key：在阿里云百炼控制台获取 DashScope API Key，用于调用记忆库 API 时进行身份验证。
  • 已获取业务空间 ID：在业务空间管理页面查看，详见获取 Workspace ID。API Key 须属于同一业务空间。
记忆库 API 的 Base URL 为： 
https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/
调用时请将 {workspaceId} 替换为真实的业务空间 ID。完整的 API 接口说明请参见长期记忆 API 参考。

在工作流应用中使用记忆库

工作流应用通过可视化编辑器构建流程。您可以使用编辑器中的 API 组件调用记忆库 API，无需编写代码即可为工作流添加长期记忆能力。 典型的带记忆工作流结构为：
  1. 开始节点接收用户输入
  2. API 组件（SearchMemory）：检索该用户的相关历史记忆
  3. 大模型节点：将记忆注入 System Prompt，结合用户提问生成回复
  4. API 组件（AddMemory）：将本轮对话写入记忆库
  5. 结束节点输出回复

步骤一：配置开始节点并添加 API 组件

首先，在开始节点中确认输入变量。默认的 user_input 变量用于接收用户的对话消息。此外，您需要添加一个 user_id 变量（类型为 String），用于标识不同用户的记忆。如果您通过 API 方式调用该工作流，user_id 可以在调用时作为输入参数传入。 然后，在工作流编辑器左侧的节点库中，找到工具分类下的 API，将其拖拽到画布中。API 组件支持通过 POST 或 GET 方式调用自定义 API 服务。 您需要添加两个 API 组件：一个用于检索记忆（SearchMemory），一个用于写入记忆（AddMemory）。

步骤二：配置 SearchMemory 节点

点击画布中的第一个 API 组件，在右侧配置面板中填写以下信息：
配置项值
API 地址选择 POST
URL 地址https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/search
Header 设置Authorization：值为 Bearer YOUR_API_KEY（替换为您的 API Key）
Body 设置选择 JSON 格式，填写 JSON 请求体（见下方示例）
{
"user_id": "{{user_id}}",
"query": "{{user_input}}"
}
其中 {{user_id}} 和 {{user_input}} 为工作流变量，引用开始节点中的用户标识和用户输入。您可以在输入框中输入 / 来插入变量。 在 API 组件底部的输出区域，配置一个输出变量（如 result，类型选择 Object），用于接收 SearchMemory 的返回结果。后续大模型节点将引用该变量中的记忆内容。

步骤三：配置大模型节点

在画布中添加一个大模型节点，连接在 SearchMemory API 组件之后。在大模型节点的 System Prompt 中，引用 SearchMemory 的输出变量来注入记忆内容。 System Prompt 示例： 
你是一个贴心的智能助手。以下是关于该用户的历史记忆：
{{search_memory_node.result}}
请基于这些记忆信息回答用户的问题。如果记忆中没有相关信息，正常回答即可。
其中 search_memory_node 为 SearchMemory API 组件的节点名称，result 为其输出变量名。请根据实际配置修改。 SearchMemory API 返回的数据为 JSON 格式，包含 memory_nodes 数组。如果需要更精细地控制注入格式，可以在 SearchMemory 和大模型节点之间插入一个脚本节点，提取并格式化记忆内容。

步骤四：配置 AddMemory 节点

在大模型节点之后再添加一个 API 组件，用于将本轮对话写入记忆库。配置方式与 SearchMemory 类似：
配置项值
API 地址选择 POST
URL 地址https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add
Header 设置与 SearchMemory 节点相同
Body 设置选择 JSON 格式
{
"user_id": "{{user_id}}",
"messages": [
{"role": "user", "content": "{{user_input}}"},
{"role": "assistant", "content": "{{llm_node.output}}"}
]
}
其中 llm_node.output 为大模型节点的输出变量，引用模型生成的回复内容。

步骤五：连接节点并测试

将各节点按以下顺序连接： 开始 → SearchMemory（API） → 大模型 → AddMemory（API） → 结束 连接完成后，点击右上角的测试按钮。在测试面板中填写 user_id（如 test_user_001）和 user_input（如"你好"），点击运行验证工作流是否正常。首次对话时 SearchMemory 返回结果为空属于正常情况，多轮对话后即可检索到之前存储的记忆。

在高代码应用中使用记忆库

高代码应用支持上传自定义代码包来实现业务逻辑。您可以在代码中直接通过 HTTP 请求调用记忆库 API，实现记忆的检索和写入。 核心流程与工作流应用相同：检索记忆 → 注入 Prompt → 生成回复 → 写入记忆。区别在于所有步骤都通过代码实现。 代码示例：带记忆的完整对话流程

cURL

# 步骤 1：检索与当前提问相关的历史记忆
curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/search \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"user_id": "user_001",
"query": "今天下午有什么安排？"
}'

# 步骤 2：将记忆注入 System Prompt，调用大模型
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-plus",
"messages": [
{
"role": "system",
"content": "你是一个贴心的智能助手。以下是关于该用户的记忆：\n- 用户要求每天下午3点提醒他喝水\n- 用户明天10点需要整理会议纪要\n请基于这些记忆回答用户问题。"
},
{"role": "user", "content": "今天下午有什么安排？"}
]
}'

# 步骤 3：对话结束后，将本轮对话写入记忆库
curl -X POST https://{workspaceId}.cn-beijing.maas.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": "今天下午有什么安排？"},
{"role": "assistant", "content": "根据记录，您每天下午3点需要喝水。另外明天上午10点您需要整理会议纪要，建议提前准备。"}
]
}'

Python

import os
import requests

DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")
BASE_URL = "https://{workspaceId}.cn-beijing.maas.aliyuncs.com"
HEADERS = {
"Authorization": f"Bearer {DASHSCOPE_API_KEY}",
"Content-Type": "application/json",
}

def chat_with_memory(user_id: str, user_input: str) -> str:
"""带长期记忆的单轮对话"""

# 步骤 1：检索相关记忆
search_resp = requests.post(
f"{BASE_URL}/api/v2/apps/memory/search",
headers=HEADERS,
json={"user_id": user_id, "query": user_input},
)
memories = search_resp.json().get("output", {}).get("memory_nodes", [])

# 步骤 2：将记忆注入 System Prompt
if memories:
memory_text = "\n".join(f"- {m['content']}" for m in memories)
else:
memory_text = "暂无相关记忆"

system_prompt = (
"你是一个贴心的智能助手。"
"以下是关于该用户的记忆：\n"
f"{memory_text}\n"
"请基于这些记忆回答用户问题。"
)

# 步骤 3：调用大模型生成回复
chat_resp = requests.post(
f"{BASE_URL}/compatible-mode/v1/chat/completions",
headers=HEADERS,
json={
"model": "qwen-plus",
"messages": [
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_input},
],
},
)
assistant_reply = chat_resp.json()["choices"][0]["message"]["content"]

# 步骤 4：将本轮对话写入记忆库
requests.post(
f"{BASE_URL}/api/v2/apps/memory/add",
headers=HEADERS,
json={
"user_id": user_id,
"messages": [
{"role": "user", "content": user_input},
{"role": "assistant", "content": assistant_reply},
],
},
)

return assistant_reply

# 运行示例
reply = chat_with_memory("user_001", "今天下午有什么安排？")
print(f"助手: {reply}")
以上示例展示了记忆库集成的核心逻辑。在实际高代码应用中，您需要将此逻辑嵌入应用的入口函数中，通过应用框架接收用户输入和 user_id。将代码打包后上传至阿里云百炼控制台的高代码应用中即可运行。关于高代码应用的创建和代码包上传方式，请参见高代码应用。

进阶优化

完成基础集成后，您可以通过以下方式进一步提升记忆效果。以下优化方法同时适用于工作流应用和高代码应用。

优化检索效果

SearchMemory 支持以下参数来提升检索质量：
参数说明适用场景
rewrite对用户提问进行改写优化，提升检索召回率用户表述模糊或口语化时
rerank对检索结果重新排序，将最相关的记忆排在前面记忆量大、需要精准匹配时
similarity_threshold设置相似度阈值，过滤低相关性的结果需要减少不相关记忆干扰时
max_results限制返回的记忆条数需要控制注入 Prompt 长度时
{
"user_id": "{{user_id}}",
"query": "{{user_input}}",
"max_results": 5,
"rewrite": true,
"rerank": true,
"similarity_threshold": 0.5
}

结合用户画像

用户画像记录用户的稳定属性（如偏好、角色、习惯），与记忆片段互补。将两者分层注入 Prompt，可以同时提供"全局背景"和"当前相关细节"。 实现方式：在检索记忆前，额外调用 GetUserProfile API 获取用户画像，然后在 System Prompt 中分层注入。
  • 工作流应用：添加一个额外的 API 组件调用 GET https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/profile_schemas/{schema_id}/user_profile?user_id={user_id}，将画像输出与记忆输出一起注入大模型节点。
  • 高代码应用：在代码中增加 GetUserProfile 的 HTTP 请求，组装分层 System Prompt。

写入策略

AddMemory 支持两种写入方式：
参数说明适用场景
messages传入完整的对话消息数组，系统自动提取关键信息并存储标准对话场景，推荐优先使用
custom_content直接传入已整理好的文本内容，系统原样存储需要存储结构化摘要、外部数据或自定义格式
写入建议：推荐写入用户的偏好表达、关键决策、待办事项、重要事实等有长期价值的内容。避免写入一次性查询（如"今天天气"）、敏感信息（如密码、密钥）、系统内部指令。