记忆配置中心与自定义 Pipeline
功能概述与核心场景
记忆配置中心与自定义流水线(Memory Configuration & Pipelines,控制台页签为 配置)是 Agentbase Memory(v2.10.0)的策略与流程控制中枢。在实际企业生产环境中,不同业务场景对事实抽取的粒度、用户画像的结构、知识蒸馏的阈值以及历史记忆的衰减遗忘周期有着截然不同的要求。如果把所有提示词和模型参数耦合在单一全局大对象中,不仅容易在并发修改时相互覆盖,也无法在上线前安全验证新提示词的效果。
为此,Agentbase Memory 提供了双层配置治理体系:
四类场景化业务 Pipeline(
add_memory、profile、distillation、forgetting):支持从系统默认参数一键创建草稿、按节点定制提示词与模型路由、通过 Dry-run 样例在线试跑验证、发布不可变版本并切换场景默认流水线(单个项目四类合计最多支持 32 条自定义 Pipeline);版本化配置中心(Config Center):按职责划分为
provider、policy、prompt、retention、evolution(以及底层运行时runtime)命名空间,全面采用基于expectedConfigVersion与 HTTPIf-Match/If-None-Match(ETag)的乐观并发控制,支持版本历史查看、Diff 对比与一键回滚。
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,管理员通过自定义 Pipeline 为智能客服定制了专门提取工单号、OceanBase 集群版本与 SLA 等级的事实抽取流程,并通过 policy 与 retention 命名空间精细管控 168 小时新记忆保护期与合规保留周期。
核心概念与架构
配置中心将高频迭代的“业务流程节点参数(Pipelines)”与全局生效的“系统级治理策略(Config Namespaces)”解耦,并通过任务受理时的版本快照冻结机制,保证线上在途任务不受配置变更干扰。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
四类业务 Pipeline 固定步骤与可调参数对照表
每条 Pipeline 的场景类型(scenario)在创建后固定不可修改,其内部节点按既定拓扑顺序执行(不可重排或删除节点,但支持按规则启停可选节点):
场景名称 (scenario) | 固定的节点执行拓扑顺序 | 核心可调节点参数与模型路由覆盖 | 样例验证(Dry-run)行为 |
|---|---|---|---|
新增记忆 (add_memory) | receive(接收) → fact_extraction(事实抽取) → conflict_detection(冲突判断) → memory_operation(记忆操作) | - fact_extraction:自定义抽取提示词、单次最大抽取事实数(maxFacts)、Chat 模型路由(可开关);- conflict_detection:冲突判定提示词、每个事实召回候选数(candidatesPerFact)、最大总候选数(maxCandidates)、Chat 模型路由(可开关);- 共享 models:可覆盖 embedding、rerank、vision 路由及冲突重排开关 rerankEnabled。 | 调用真实模型执行抽取与冲突比对,直接展示计划执行的 ADD/UPDATE/DELETE/NONE 结果,不写入正式记忆表。 |
画像 (profile) | receive(接收) → profile_generation(画像生成) → profile_operation(画像操作) | - 三个步骤均必选; - profile_generation:可分别定制增量生成提示词(prompt)与来源重建提示词(rebuildPrompt),并可独立指定生成节点的 Chat/VLM 模型路由。 | 调用模型并返回生成的画像正文,不覆盖用户现有正式画像。 |
经验与技能 (distillation) | receive → skill_extraction → skill_merge → experience_extraction → experience_merge → validation → knowledge_operation | - skill_extraction 与 experience_extraction 至少开启一种(关闭某项时其对应的 merge 节点自动跳过,参数保留);- 合并候选数 maxCandidates(1~20)、合并阈值 mergeThreshold((0, 1]);- 各节点独立提示词与 Chat 模型,共享 models.embedding 路由覆盖。 | 展示提取与合并后的技能/经验标题、摘要与节点技术详情,不落库正式知识或确认单。 |
遗忘 (forgetting) | memory_scan(扫描记忆) → forgetting_decision(遗忘判断) → forgetting_operation(执行遗忘) | - 使用确定性数学衰减规则(无 LLM 提示词参数); - memory_scan:扫描批量 batchSize(1~1000);- forgetting_decision(可关闭):初始保留率、衰减率、层级阈值、最短保护期(minimum_protection_hours)、复习间隔与永久遗忘开关。 | 仅只读扫描指定样例用户的可见记忆,返回 scanned 及计划动作(archive、expire、review、promote)与 dryRun: true,绝不执行任何删除或归档写入。 |
功能入口与权限矩阵
控制台入口与权限要求
控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 配置 页签。该页签包含 5 个二级子视图:新增记忆 Pipeline、画像 Pipeline、经验与技能 Pipeline、遗忘 Pipeline 以及 基础配置。
| 操作类别 | 控制台入口 | REST API 端点 | 所需权限 |
|---|---|---|---|
| 查询与创建 Pipeline | 各场景 Pipeline 列表 → 新建 Pipeline | GET /v1/memory/pipelines?scenario=...、POST /v1/memory/pipelines | projects.read / projects.write |
| 保存草稿、运行样例与发布 | 编辑器顶部 保存草稿 / 运行样例 / 发布 | PATCH /v1/memory/pipelines/{pipelineId}、POST .../validate、POST .../publish | projects.write |
| 切换或恢复场景默认 Pipeline | 设为默认 / 恢复系统默认 | PUT /v1/memory/pipelines/default | projects.write |
| 读写 5 大系统配置命名空间 | 基础配置 子视图 | GET/PUT /v1/projects/{projectId}/memory/config/{namespace} | projects.read / projects.write |
| 查看配置历史、Diff 与回滚 | 展开配置版本 区域 | GET .../config/{namespace}/history、/diff、POST .../rollback | projects.read / projects.write |
功能详解与操作指南
1. 创建、验证并发布自定义记忆 Pipeline
登录 Agentbase 控制台,进入项目
企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 配置 页签。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
选择要调整的业务场景(例如 新增记忆 Pipeline),单击 从默认新建 Pipeline(对应
POST /v1/memory/pipelines传入{"scenario": "add_memory", "fromDefaults": true})。展开需要定制的流程节点(如 事实抽取
fact_extraction):单击提示词输入框下方的 查看内置默认提示词,可查阅并一键复制平台内置的基础提示词模板(查看或复制不会自动改动当前草稿,系统在运行时还会自动附加不可覆盖的安全协议规则);
根据企业客服场景修改抽取指令、单次最大事实数(
maxFacts)或节点使用的模型路由。
单击编辑器顶部的 保存草稿(编辑器顶部同时提供 复制已保存草稿 与 删除 Pipeline 按钮)。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
运行样例验证(Dry-run):
草稿保存后,在右侧或下方样例区输入测试消息或目标用户 ID,单击 运行样例(调用
POST /v1/memory/pipelines/{pipelineId}/validate);必须先让当前保存的草稿版本成功通过一次样例验证,系统才允许点击发布。样例请求的审计仅记录 Pipeline ID、版本与结果状态,不会保存样例输入原文。
发布版本并设为默认:
核对样例输出符合预期后,单击 发布(
POST /v1/memory/pipelines/{pipelineId}/publish),可同时勾选 设为该场景默认 Pipeline(makeDefault: true)。发布后,在 记忆、画像 或 经验与技能 页面即可显式选择该已发布 Pipeline,或直接继承更新后的场景默认 Pipeline。已受理的历史任务继续使用其入队时冻结的发布版本,不会因切换默认而重算历史数据。
2. 五大核心配置命名空间详解与乐观并发控制
在 记忆 → 配置 → 基础配置 中,项目配置按 5 个主要业务命名空间(以及底层 runtime 检索融合命名空间)组织:
命名空间 (namespace) | 核心职责 | 关键配置字段与生产推荐值 | 失败策略 |
|---|---|---|---|
provider | 模型提供方与五类模型默认路由 | embeddingProviderRef / embeddingModel (text-embedding-v3) / embeddingDims (1024,锁定不可变);sparseEmbeddingEnabled (true);llmProviderRef / chatModel (qwen-plus);structuredOutputMode ("tool_call");rerankModel (qwen3.7-text-rerank);visionModel (qwen-vl-max)。 | Fail-closed(路由无效时拒绝调用) |
policy | 捕获策略、搜索增强、可观测采样与自适应遗忘 | - rerankEnabled(搜索重排开关,默认 false)、profileRewriteEnabled(画像改写开关,默认 false)、autoProfileExtractionEnabled(自动画像)、requestAuditEnabled(请求审计,默认 true);- observability:enabled、captureContent、successSampleRate、slowThresholdMs;- forgetting:enabled (true)、permanent_forgetting_enabled (false)、minimum_protection_hours (168)、working_threshold (0.3)、short_term_threshold、long_term_threshold。 | 核心访问策略 Fail-closed |
prompt | 各阶段项目级提示词覆盖 | factExtractionPrompt、memoryUpdatePrompt、profileExtractionPrompt、profileRebuildPrompt、queryRewritePrompt、skillDistillationPrompt、skillMergePrompt、experienceDistillationPrompt、experienceMergePrompt、evolutionValidationPrompt、contextAggregationPrompt、promptVersion。 | 已迁入自定义 Pipeline 的节点以其发布版本为准 |
retention | 各类数据与任务回执的物理保留天数 | defaultDays(默认保留天数)、factDays(事实记忆保留天数)、conversationDays(对话记忆保留天数)、auditEventDays(审计事件保留天数)、terminalJobDays(已结束异步任务保留天数)、idempotencyReceiptDays(幂等回执保留天数)。 | 到期数据在线立即不可见,后台异步清理 |
evolution | 经验/技能激活门槛与 Dreaming 上下文调度 | enabled、autoDistillEnabled、requireConfirmation(自进化二次确认,默认 false)、allowSingleVerifiedUserActivation、crossUserPromotionEnabled;activation(minConfidence、minIndependentSessionsForAgent、requireVerifiedSuccess);retrieval(experienceTopK、skillTopK、maxTokens);dreaming(enabled、mode、batchSize、minimumChanged)。 | Fail-closed(未达门槛保持 shadow) |
补充说明(
runtime命名空间):系统还支持通过/v1/projects/{projectId}/memory/config/runtime调整底层检索融合参数,如recallFusion.method、rrfK、weights(dense/sparse/keyword/graph四路权重)、candidateThresholds与queryEmbeddingCache.maxEntries。
3. 乐观并发控制(expectedConfigVersion + If-Match / If-None-Match)与配置回滚
为防止多名管理员同时修改配置产生静默覆盖,所有配置命名空间均实施严格的乐观并发锁与 HTTP 条件请求头支持:
条件读取(
If-None-Match):GET /v1/projects/{projectId}/memory/config/{namespace}在响应中返回当前整数version、最后事件 IDlastEventId以及ETag响应头。客户端轮询时可携带If-None-Match: "<etag>",若配置未发生变化将高效返回304 Not Modified。条件更新(
expectedConfigVersion与If-Match):PUT /v1/projects/{projectId}/memory/config/{namespace}请求体必须携带最新读取到的expectedConfigVersion(整数),也可同时在 HTTP 请求头中携带If-Match: "<etag>"。若服务端检测到当前版本已前进,立即返回409 Conflict,客户端必须重新读取最新配置与版本后再提交。历史对比与回滚(
history/diff/rollback): 在控制台展开 配置版本 可按需加载历史版本列表与只读 YAML Diff(查看历史不会覆盖当前未保存草稿)。调用POST /v1/projects/{projectId}/memory/config/{namespace}/rollback传入targetVersion与expectedConfigVersion,即可将配置参数安全回退至指定历史版本(回滚配置仅恢复参数本身,不会恢复已被物理删除的记忆数据)。
# 示例:使用 expectedConfigVersion 与 If-Match 更新 retention 保留策略,并查询版本 Diff
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
# 1. 读取当前 retention 配置与版本号
RETENTION_RESP="$(curl -fsS -D /tmp/retention_headers.txt \
"${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
-H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Mode: admin")"
RET_VER="$(echo "${RETENTION_RESP}" | jq -er '.version')"
RET_ETAG="$(grep -i '^etag:' /tmp/retention_headers.txt | awk '{print $2}' | tr -d '\r')"
# 2. 携带 expectedConfigVersion 与 If-Match 乐观锁更新保留天数
curl -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
-H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Mode: admin" \
-H "If-Match: ${RET_ETAG}" \
-H "Content-Type: application/json" \
--data "{
\"expectedConfigVersion\": ${RET_VER},
\"reason\": \"按企业合规要求将事实记忆保留期设为 365 天,审计保留期设为 90 天\",
\"value\": {
\"defaultDays\": 180,
\"factDays\": 365,
\"conversationDays\": 90,
\"auditEventDays\": 90,
\"terminalJobDays\": 14,
\"idempotencyReceiptDays\": 7
}
}" | jq .
# 3. 对比版本差异 (Diff)
curl -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention/diff?fromVersion=${RET_VER}&toVersion=$((RET_VER + 1))" \
-H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Mode: admin" | jq .常见问题与排障(FAQ)
1. 为什么在自定义 Pipeline 中点击“发布”按钮时提示无法发布?
原因分析:Agentbase Memory 强制要求每一个 Pipeline 草稿版本在发布上线前,必须基于当前已保存的最新草稿版本(
versionId)成功通过一次 运行样例(POST /validate) 校验。如果在运行样例后又修改了任意节点参数但未重新保存并重跑样例,或者样例执行因模型路由错误失败,系统都会拦截发布。解决措施:先单击 保存草稿,再单击 运行样例 并确认返回成功结果,此时 发布 按钮即可正常点击。
2. 开启或关闭“永久遗忘(permanent_forgetting_enabled)”开关有什么影响?会影响用户主动删除(DELETE)吗?
原因分析:容易混淆“后台自适应衰减归档”与“显式隐私删除”两个概念。
解决措施:
forgetting.permanent_forgetting_enabled(默认false)仅控制后台遗忘 Pipeline 因记忆保留率衰减低于阈值而自动归档(Archive)的记忆是否进入物理压缩清理;关闭时,自适应衰减的记忆仅标记归档不可见,不立即物理擦除。而用户或应用通过
DELETE /v1/memory/memories发起的主动删除、达到明确到期时间(硬过期)的记忆,以及项目生命周期销毁,始终执行不可逆的永久清理,不受permanent_forgetting_enabled开关关闭的保护。
3. 修改了默认新增记忆 Pipeline 或系统提示词后,以前写入的旧记忆会自动重新抽取吗?
原因分析:不会。异步写入、画像提取与知识蒸馏任务在受理入队时会将当时选中的已发布 Pipeline 版本固化到任务快照中;新发布的 Pipeline 或配置仅对后续新受理的请求生效,不会自动重算存量历史记忆。
解决措施:对于用户画像或分层上下文,若希望应用新发布的提示词重算,可显式调用画像的 重建(
/profile/rebuild) 或上下文的 重建(/contexts/{contextId}/rebuild) 接口。


