AgentStorage 为 AI 应用提供知识检索和记忆能力。控制台无需编写代码即可创建 AgentStorage 实例、管理知识库与记忆库、调试检索效果，并结合模型完成 Agent 对话验证。
适用范围
支持地域：华北2（北京）、华东1（杭州）
账号需具备 AgentStorage 的查看和管理权限，详情请参见配置访问权限。
AgentStorage 实例管理
AgentStorage 实例是知识库和记忆库的载体，使用前需先在目标地域创建实例。
创建 AgentStorage 实例
选择目标地域，点击创建 AgentStorage
填写名称（3～16 个字符，以英文字母开头，只能包含英文字母、数字和短划线，末尾不能是短划线，且同一地域内不能重复），按需填写描述并选择资源组，点击确定
创建成功后，实例需要短暂初始化。控制台会自动检测可用状态；如果暂时无法进入功能页面，请刷新页面或重新选择该实例。
查看和维护 AgentStorage
在左上角AgentStorage 选择框中点击AgentStorage管理，可以搜索当前地域下的实例，并进行以下操作：
点击详情，获取 Agent Storage SDK 所需的实例名称和访问地址，并查看地域、存储规格、资源组和创建时间
点击修改描述，更新实例描述。实例名称和地域在创建后不可更改
点击删除，释放不再使用的实例
删除操作不可恢复。删除 AgentStorage 前，请确认相关业务已停止使用。
知识库操作
创建知识库并导入文档
知识库用于保存文档内容，并通过向量检索、全文检索和重排序为问答应用提供上下文。
创建知识库
进入知识库管理，点击新建知识库，按页面填写以下参数：
参数 | 说明 |
名称 | 以字母开头，只能包含字母、数字和下划线，最多 64 个字符 |
描述、标签 | 说明知识库用途，便于后续管理 |
元数据模式 | 定义文档的附加属性（如来源、分类、版本号等自定义字段）。导入文档时可为每篇文档填写这些字段的值，检索时可按字段过滤结果。建议在创建知识库时提前规划所需字段 |
启用子空间 | 适合在同一知识库内按业务线、项目或租户隔离文档 |
多模态 | 用于图片文档入库、图片检索及多模态 Embedding/Rerank |
表格公式 Caption | 开启后，系统会为文档中的表格和公式生成自然语言描述，提升这类内容的检索命中率。 |
高级设置 | 可设置 Embedding模型、召回数量、检索类型和重排序策略；没有明确调优需求时，建议先使用默认配置 |
多模态设置在知识库创建后不能修改，请在创建前确认是否需要该能力。
如需从本地或 OSS 导入知识文档，账号下应已有可用的 OSS Bucket，须与 AgentStorage 实例同地域。如果创建知识库时出现 OSS 授权提示，请先完成授权再继续创建。
创建成功后，知识库会出现在列表中。如需修改知识库的检索、 Embedding 配置或调整重排序策略，可点击目标卡片右上角 的进行调整。
导入文档
打开知识库卡片，进入文档管理，点击上传入口。控制台支持以下三种导入方式：
多模态设置创建后不可修改，请在创建前确认是否需要。导入知识文档需要与实例同地域的 OSS Bucket；若出现 OSS 授权提示，请先完成授权。
上传文件：选择本地文件，并指定 OSS Bucket 和保存目录
上传文件夹：按目录批量上传，可设置是否递归以及包含、排除的文件扩展名
从 OSS 导入：直接选择 OSS 中已有的文件或目录
文件类型、单文件大小和批量数量限制以控制台 的上传面板为准。文档上传后需要经过解析和切片，状态变为已完成 后才能进行检索测试。文档详情中可以查看元数据和切片内容，并对支持编辑的切片进行调整。
执行检索测试
点击目标知识库，选择左侧的检索测试，按以下步骤验证检索效果：
输入需要检索的问题或关键词，如果启用了子空间，还需填写要检索的子空间名称
搜索类型：同时勾选向量检索（基于语义相似度匹配）和全文检索（基于关键词匹配）
各检索方式的 TopK（返回的最大结果数量）和最终重排序数量：保持默认值
模型重排、权重融合或 RRF 等重排序（对初步结果按相关度重新排列）策略：保持默认值
如知识库定义了元数据字段，可增加元数据过滤条件
点击 执行检索，即可查看召回内容、相似度和耗时
首次调试建议先使用默认参数，确认可以召回目标文档后，再根据召回准确率和结果数量逐步调整 TopK 与重排序配置。如果结果中没有目标内容，建议按以下顺序排查：
确认文档状态为已完成
确认子空间和元数据过滤条件是否符合预期
临时移除过滤条件，验证基础召回是否正常
增大 TopK
调整重排序策略
使用知识库实验室验证问答效果
知识库实验室用于验证完整的 RAG 问答效果，不会修改知识库中的文档：
进入知识库实验室，在左侧配置模型的温度系数和系统提示词
选择一个或多个知识库；如果知识库启用了子空间时，还需要填写对应子空间名称
设置全局检索参数，并按需打开引用面板
在中间对话区输入问题，在右侧查看实际检索到的文档、切片、相似度及提供给模型的引用数量
如果回答不符合预期，先检查引用面板中是否召回了正确内容。未召回目标内容时优先调整文档、子空间和检索参数；已召回但回答不理想时，再调整系统提示词或模型参数。
记忆库操作
创建和管理记忆库
记忆库用于保存应用、用户、智能体和会话范围内的上下文。进入记忆库管理 后，点击新建记忆库，按页面填写以下参数：
名称：只能包含字母、数字和下划线，最多 32 个字符
描述：说明记忆库的业务用途
存储模式：创建后不可修改，请在创建前根据使用方式选择
存储模式
适用场景
主要能力
结构化记忆
用户偏好、事实、任务等长期记忆
长期记忆、短期记忆、检索、任务、Dream
结构化记忆 + 文件投影
同时需要结构化查询和文件视图
保留结构化能力，并提供只读文件浏览
文件记忆
以文件组织记忆内容
可写文件、目录管理和版本历史；不生成结构化记忆
提取指令：用于指导系统从文本或对话中提取结构化记忆，最多 4096 个字符；仅支持结构化记忆 和 结构化记忆 + 文件投影 两种模式。
创建完成后，记忆库卡片会显示名称、存储模式和创建时间。如需删除记忆库，返回记忆库管理 列表页，点击目标记忆库卡片右上角的 ···，选择删除；此操作不可恢复，需要输入记忆库名称二次确认。
使用记忆库
记忆库详情页显示的菜单会随存储模式变化。以下以结构化记忆模式为例，说明主要功能的使用方法。
写入记忆
点击写入记忆，填写符合预期的Scope 多租户（用于表示记忆数据的归属和隔离边界），选择输入方式后填写记忆内容：
文本输入：直接输入需要记录的文本，可按需附加元数据
消息 JSON：适合调试对话消息场景，格式如：
[{"role":"user","content":"你好"},{"role":"assistant","content":"你好！有什么可以帮你的吗？"}]
填写完成后点击写入记忆
appId为必填项，其余字段留空时由系统自动填充为默认值，且写入操作不能使用通配符。写入接口成功只表示内容已接收。长期记忆提取属于异步处理，请刷新长期记忆页面查看提取结果。
查看短期记忆
进入短期记忆，选择相同 Scope 和合适的时间范围，页面会保留原始写入的消息，便于还原用户当时输入的上下文。如果这里没有数据，应先检查 Scope、时间范围和写入结果。
查看长期记忆
进入长期记忆 并刷新，查看系统从写入内容中提取出的长期记忆，列表中可以查看记忆类型、版本和创建时间，也可以进入详情、修改或删除单条记忆。
长期记忆是经过模型整理后的信息，不等同于原始消息。生产使用时建议抽查提取结果，并在提取指令中明确需要保留和忽略的信息。
记忆检索
进入记忆检索，输入查询语句，设置 Top K，按需开启重排序，然后点击 搜索。检索结果会显示相似度、相关度、记忆类型、Scope、版本和创建时间；若业务写入时附加了元数据，还可以通过元数据过滤缩小范围。
相关度：检索结果的最终排序依据。开启重排序时为重排模型给出的相关度分数，关闭重排序时为归一化后的向量相似度。通过 SDK 设置相似度阈值（
minSimilarity）时，过滤的也是该值。相似度：查询与记忆内容的原始向量余弦相似度，仅供参考，不参与排序和过滤；未计算向量相似度时不返回该值。
查看提取任务
进入任务页面，可以查看异步记忆提取任务的状态、输入 Scope、记忆数量和处理时间。点击任务详情可以进一步确认输入内容、处理状态、耗时及生成结果。当写入成功但长期记忆未出现时，应优先在这里检查任务是否仍在运行或是否失败。
使用 Dream 整理记忆
Dream 用于对一组已有记忆生成整理建议。进入 Dream，点击创建任务，输入 Scope 并填写整理指令，例如：
合并重复偏好，保留最新的用户画像和明确待办事项。提交后任务会进入运行中状态；Dream 需要读取并分析已有记忆，处理时间通常比普通查询更长。任务完成后会生成待审核的整理建议，页面显示建议类型、目标 Scope、置信度和原因。
Dream 建议不会自动应用。请逐条查看详情，确认不会丢失有效信息后，再选择应用或跳过。
使用 Agent 对话联合验证
Agent 对话用于把模型、知识库和记忆库组合起来进行验证。
进入 Agent 对话，展开右侧 Agent 配置
按需调整模型的温度和系统提示词
选择知识库，设置每个知识库的 TopK、检索类型、重排序方式及全局聚合 TopK
如需使用记忆，选择记忆库，填写
appId、tenantId、agentId，并按需开启记忆检索和设置记忆 TopK。runId可由控制台自动生成，也可以自行填写返回对话区输入问题，查看回答、知识库引用和命中的记忆
未启用记忆库时，对话历史保存在当前页面中，刷新后会丢失。启用记忆库后，对话内容会写入记忆库；刷新页面后可到记忆库中查看对应 Scope 下的历史消息。
模型生成内容可能不准确。涉及生产操作、权限、安全和业务决策时，应结合引用内容进行人工核对。
验收联合问答时，至少检查以下三点：回答是否覆盖问题；知识库引用是否来自预期文档；记忆引用是否属于当前 Scope。任一项不符合预期，都应回到对应知识库或记忆库单独排查。
使用建议
测试和生产业务使用不同的 AgentStorage，避免调试数据与生产数据混用
创建知识库前先规划子空间和元数据字段；创建记忆库前先确定存储模式和 Scope 规则
先使用默认检索配置完成基础验证，再根据真实问题集调整参数
文档更新后重新执行检索测试，确认新内容已经生效
删除 AgentStorage、知识库、记忆库或记忆单元前，先确认业务不再使用并保留必要备份