Docs
文档目录

记忆配置中心与自定义 Pipeline

功能概述与核心场景

记忆配置中心与自定义流水线(Memory Configuration & Pipelines,控制台页签为 配置)是 Agentbase Memory(v2.10.0)的策略与流程控制中枢。在实际企业生产环境中,不同业务场景对事实抽取的粒度、用户画像的结构、知识蒸馏的阈值以及历史记忆的衰减遗忘周期有着截然不同的要求。如果把所有提示词和模型参数耦合在单一全局大对象中,不仅容易在并发修改时相互覆盖,也无法在上线前安全验证新提示词的效果。

为此,Agentbase Memory 提供了双层配置治理体系:

  1. 四类场景化业务 Pipeline(add_memory、profile、distillation、forgetting):支持从系统默认参数一键创建草稿、按节点定制提示词与模型路由、通过 Dry-run 样例在线试跑验证、发布不可变版本并切换场景默认流水线(单个项目四类合计最多支持 32 条自定义 Pipeline);

  2. 版本化配置中心(Config Center):按职责划分为 provider、policy、prompt、retention、evolution(以及底层运行时 runtime)命名空间,全面采用基于 expectedConfigVersion 与 HTTP If-Match / If-None-Match(ETag)的乐观并发控制,支持版本历史查看、Diff 对比与一键回滚。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,管理员通过自定义 Pipeline 为智能客服定制了专门提取工单号、OceanBase 集群版本与 SLA 等级的事实抽取流程,并通过 policy 与 retention 命名空间精细管控 168 小时新记忆保护期与合规保留周期。


核心概念与架构

配置中心将高频迭代的“业务流程节点参数(Pipelines)”与全局生效的“系统级治理策略(Config Namespaces)”解耦,并通过任务受理时的版本快照冻结机制,保证线上在途任务不受配置变更干扰。

记忆配置中心与自定义 Pipeline:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

四类业务 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 列表 → 新建 PipelineGET /v1/memory/pipelines?scenario=...、POST /v1/memory/pipelinesprojects.read / projects.write
保存草稿、运行样例与发布编辑器顶部 保存草稿 / 运行样例 / 发布PATCH /v1/memory/pipelines/{pipelineId}、POST .../validate、POST .../publishprojects.write
切换或恢复场景默认 Pipeline设为默认 / 恢复系统默认PUT /v1/memory/pipelines/defaultprojects.write
读写 5 大系统配置命名空间基础配置 子视图GET/PUT /v1/projects/{projectId}/memory/config/{namespace}projects.read / projects.write
查看配置历史、Diff 与回滚展开配置版本 区域GET .../config/{namespace}/history、/diff、POST .../rollbackprojects.read / projects.write

功能详解与操作指南

1. 创建、验证并发布自定义记忆 Pipeline

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 配置 页签。

记忆配置中心视图(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

  1. 选择要调整的业务场景(例如 新增记忆 Pipeline),单击 从默认新建 Pipeline(对应 POST /v1/memory/pipelines 传入 {"scenario": "add_memory", "fromDefaults": true})。

  2. 展开需要定制的流程节点(如 事实抽取 fact_extraction):

    • 单击提示词输入框下方的 查看内置默认提示词,可查阅并一键复制平台内置的基础提示词模板(查看或复制不会自动改动当前草稿,系统在运行时还会自动附加不可覆盖的安全协议规则);

    • 根据企业客服场景修改抽取指令、单次最大事实数(maxFacts)或节点使用的模型路由。

  3. 单击编辑器顶部的 保存草稿(编辑器顶部同时提供 复制已保存草稿 与 删除 Pipeline 按钮)。

记忆流水线草稿视图(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

  1. 运行样例验证(Dry-run):

    • 草稿保存后,在右侧或下方样例区输入测试消息或目标用户 ID,单击 运行样例(调用 POST /v1/memory/pipelines/{pipelineId}/validate);

    • 必须先让当前保存的草稿版本成功通过一次样例验证,系统才允许点击发布。样例请求的审计仅记录 Pipeline ID、版本与结果状态,不会保存样例输入原文。

  2. 发布版本并设为默认:

    • 核对样例输出符合预期后,单击 发布(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 条件请求头支持:

# 示例:使用 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 中点击“发布”按钮时提示无法发布?

2. 开启或关闭“永久遗忘(permanent_forgetting_enabled)”开关有什么影响?会影响用户主动删除(DELETE)吗?

3. 修改了默认新增记忆 Pipeline 或系统提示词后,以前写入的旧记忆会自动重新抽取吗?


相关文档