你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
重要
在 Foundry 代理服务和内存存储 API（预览版）中，内存（预览版）作为您 Azure 订阅的一部分获得许可，并且受到 Microsoft 产品条款和 Microsoft 产品和服务数据保护附录中有关“预览版”的适用条款的约束，还需遵守 Microsoft Azure 预览版的补充使用条款中的 Microsoft 生成 AI 服务预览版条款。
Foundry 代理服务中的内存（预览版）是托管的长期内存解决方案。 它支持跨会话、设备和工作流的代理连续性。 通过创建和管理内存存储，可以生成代理来保留用户首选项、维护聊天历史记录并提供个性化体验。
本文介绍如何创建内存存储、添加和搜索记忆，并遵循安全和隐私的最佳做法。 内存存储充当持久性存储，定义与每个代理相关的信息类型。 使用 scope 参数控制访问，该参数将内存分段到各个用户，以确保安全且隔离的体验。
常见内存用例
以下示例说明了内存如何增强各种类型的代理。
对话代理
- 一个客户支持代理，用于记住你的姓名、以前的问题和解决方法、票证号码以及首选的联系人方法（聊天、电子邮件或回电）。 使用此内存可以避免重复信息，因此对话更高效且令人满意。
- 一个个人购物助手，能够记录你在特定品牌中的尺寸、首选颜色、过去的退货和最近的购买记录。 代理可以在启动会话后立即建议相关项目，并避免推荐已拥有的产品。
规划代理
- 一个出行代理，了解你的乘机偏好（例如窗口或过道）、座位和食品选择、直航与转机航班、会员计划以及过去旅行的反馈。 代理使用此信息快速构建优化的行程。
- 一个建筑设计代理，用于记住本地建筑代码、以前的投标材料成本以及初始客户端反馈。 代理以迭代方式优化设计，确保最终计划可行，并满足所有要求。
研究代理
- 一种医学研究代理，记得哪些化合物以前被测试和失败，来自不同实验室的关键发现，以及蛋白质之间的复杂关系。 该代理使用此知识来建议新的未经测试的研究假设。
了解内存类型
代理内存分为两类：
短期记忆 跟踪当前会话，并保持实时上下文以进行持续互动。 代理业务流程框架（如 Microsoft代理框架）通常将此内存作为会话上下文的一部分进行管理。
长期内存 会保留在不同会话中精炼的知识。 模型能够随着时间的推移，召回并基于先前的用户交互进行构建。 长期内存需要一个持久系统来提取、合并和管理知识。
Foundry 内存专为长期内存而设计。 它从对话中提取有意义的信息，将其合并到持久知识中，并使其在会话之间可用。
了解范围
参数 scope 控制内存的分区方式。 内存存储中的每个范围都保留一个独立内存项集合。 例如，如果创建具有内存的客户支持代理，则每个客户都应有自己的单个内存。
作为开发人员，可以选择用于存储和检索内存项的密钥，例如 UUID 或系统中的唯一用户 ID。
自定义内存
自定义智能体存储的信息，以保持内存高效、相关性强，并尊重隐私。 使用 user_profile_details 参数指定对代理函数至关重要的数据类型。
例如，设置 user_profile_details 以优先考虑旅行社的“航班承运人偏好和饮食限制”。 这种重点方法帮助记忆系统明确提取、总结以及存储到长期记忆中的详细信息。
还可以使用此参数排除某些类型的数据，使内存保持精简且符合隐私要求。 例如，设置为 user_profile_details “避免无关或敏感数据（年龄、财务、精确位置、凭据等）。
当前限制和配额
- 内存仅适用于 Azure OpenAI 模型。
- 必须显式设置该值
scope。 目前，该值无法通过请求标头中指定的用户标识进行填充，当前暂时不支持这项功能。 - 在此预览版中，适用以下限制：
- 每个内存存储的最大范围：100
- 每个作用域的最大内存数：10,000
- 搜索记忆：每分钟 1,000 个请求
- 更新内存：每分钟 1,000 个请求
先决条件
- 一份 Azure 订阅。 免费创建一个。
- 使用适当的权限访问 Microsoft Foundry，以创建和管理资源。
- Microsoft Foundry 项目。 确保项目的托管标识在其父资源上具有 Azure AI 用户 角色，该角色允许内存运行时环境调用您的模型部署以进行与内存相关的操作。
- 项目中的聊天模型部署（例如
gpt-4.1）。 -
在项目中嵌入模型部署 （例如
text-embedding-3-small）。 - 具有 配置环境的 Python 3.8 或更高版本，或对 REST API 的访问权限。
创建内存存储
为每个代理创建专用内存存储，为内存访问和优化建立明确的边界。 创建内存存储时，请指定处理内存内容的聊天模型和嵌入模型的部署。
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential
# Initialize the client
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
# Create memory store
definition = MemoryStoreDefaultDefinition(
chat_model="gpt-4.1", # Your chat model deployment name
embedding_model="text-embedding-3-small", # Your embedding model deployment name
options=MemoryStoreDefaultOptions(user_profile_enabled=True, chat_summary_enabled=True)
)
memory_store = client.memory_stores.create(
name="my_memory_store",
definition=definition,
description="Memory store for customer support agent",
)
print(f"Created memory store: {memory_store.name}")
将信息添加到记忆存储库
通过向内存存储提供对话内容来添加记忆。 系统预处理和后处理数据（包括内存提取和合并）以优化代理的内存。 此长时间运行的操作可能需要大约一分钟。
通过指定 scope 参数来确定如何跨用户分段内存。 可以将内存范围限定为特定的最终用户、团队或其他标识符。
可以使用多个会话轮次的内容更新内存存储，或者使用以前的更新操作 ID 在每个轮次和链更新后更新。
from azure.ai.projects.models import ResponsesUserMessageItemParam
# Set scope to associate the memories with
scope = "user_123"
user_message = ResponsesUserMessageItemParam(
content="I prefer dark roast coffee and usually drink it in the morning"
)
update_poller = client.memory_stores.begin_update_memories(
name="my_memory_store",
scope=scope,
items=[user_message], # Pass conversation items that you want to add to memory
update_delay=0, # Trigger update immediately without waiting for inactivity
)
# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
print(
f" - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
)
# Extend the previous update with another update and more messages
new_message = ResponsesUserMessageItemParam(content="I also like cappuccinos in the afternoon")
new_update_poller = client.memory_stores.begin_update_memories(
name="my_memory_store",
scope=scope,
items=[new_message],
previous_update_id=update_poller.update_id, # Extend from previous update ID
update_delay=0, # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
print(
f" - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
)
在记忆库中搜索记忆
搜索记忆以检索代理交互的相关上下文。 指定内存存储名称和范围以缩小搜索范围。
from azure.ai.projects.models import MemorySearchOptions
# Search memories by a query
query_message = ResponsesUserMessageItemParam(content="What are my coffee preferences?")
search_response = client.memory_stores.search_memories(
name="my_memory_store",
scope=scope,
items=[query_message],
options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
print(f" - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")
更新内存存储
更新内存存储属性（例如 description 或 metadata）以更好地管理内存存储。
# Update memory store properties
updated_store = client.memory_stores.update(
name="my_memory_store",
description="Updated description"
)
print(f"Updated: {updated_store.description}")
列出内存空间
检索项目中内存存储的列表，以管理和监视内存基础结构。
# List all memory stores
stores_list = client.memory_stores.list()
print(f"Found {len(stores_list.data)} memory stores")
for store in stores_list.data:
print(f"- {store.name} ({store.description})")
删除内存
警告
在删除内存存储之前，请考虑对依赖代理的影响。 具有附加内存存储的代理可能会失去对历史上下文的访问权限。
内存根据内存库中的范围进行组织。 可以删除特定范围的内存以删除用户特定的数据，或删除整个内存存储，以删除所有范围内的所有内存。
按范围删除内存
在保留内存存储结构的同时，删除与特定用户或组范围关联的所有内存。 使用此作可处理特定用户的用户数据删除请求或重置内存。
# Delete memories for a specific scope
delete_scope_response = client.memory_stores.delete_scope(
name="my_memory_store",
scope="user_123"
)
print(f"Deleted memories for scope: user_123")
删除内存存储
删除所有范围内的整个内存仓库及所有关联的内存。 此操作不可逆。
# Delete the entire memory store
delete_response = client.memory_stores.delete("my_memory_store")
print(f"Deleted memory store: {delete_response.deleted}")
Pricing
在此公共预览版中，内存功能是免费的。 你只需为使用聊天完成模型和嵌入模型付费。
最佳做法
在代理中实现内存时，请遵循以下做法：
-
实现每用户访问控制。 避免向代理授予对所有用户共享的内存的访问权限。
scope使用属性按用户对内存存储进行分区。 在用户之间共享scope时，用于user_profile_details指示内存系统不存储个人信息。 - 最小化和保护敏感数据。 仅存储用例所需的内容。 如果必须存储敏感数据（如个人数据、运行状况数据或机密业务输入），请编辑或删除可用于追溯到个人的其他内容。
- 支持隐私和合规性。 为用户提供透明度，包括访问和删除其数据的选项。 在防篡改审核日志中记录所有删除。 确保系统遵守本地合规性要求和法规标准。
- 分段数据并隔离内存。 在多代理系统中，内存要在逻辑上和操作上进行分段。 允许客户定义、隔离、检查和删除其自己的内存占用情况。
- 监视内存使用情况。 跟踪令牌使用情况和内存作，以了解成本和优化性能。
提示注入的安全风险
在 Foundry 代理服务中使用内存时，LLM 会根据对话提取和合并内存。 防止内存受到提示注入和内存损坏等威胁。 当错误或有害的数据存储在代理的内存中时，这些风险可能会影响代理响应和作。
执行输入验证以防止提示注入。 请考虑以下事项:
- 使用 Azure AI 内容安全 及其 指令注入检测。 验证输入或离开内存系统的所有提示，以防止恶意内容。
- 执行攻击和对抗测试。 定期通过在受控环境下的对抗性演练对代理进行注入漏洞的压力测试。