AgentbaseDocs
文档目录

记忆配置中心与自定义 Pipeline

功能概述与核心场景

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

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

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


核心概念与架构

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

flowchart TB
    subgraph ConsoleConfig["Console 记忆 → 配置页签"]
        PipelinesUI["四类业务 Pipeline 编辑器\n1. 新增记忆 (add_memory)\n2. 画像 (profile)\n3. 经验与技能 (distillation)\n4. 遗忘 (forgetting)"]
        SystemConfigUI["基础配置 (Config Namespaces)\nprovider / policy / prompt / retention / evolution (+ runtime)"]
    end

    subgraph PipelineLifecycle["自定义 Pipeline 生命周期 (/v1/memory/pipelines)"]
        CreateDraft["从系统默认新建草稿\n(POST fromDefaults: true)"]
        EditDraft["编辑节点参数 / 查看内置默认提示词\n(PATCH expectedRevision)"]
        DryRun["运行样例验证 (Dry-run)\n(POST /validate 调用真实模型但零落库)"]
        Publish["发布不可变版本并可选设为场景默认\n(POST /publish makeDefault: true)"]
        CreateDraft --> EditDraft --> DryRun --> Publish
    end

    subgraph OptimisticConfig["版本化配置中心 (/v1/projects/{projectId}/memory/config)"]
        ReadVer["读取当前配置与版本\nGET /{namespace} -> version & ETag (If-None-Match)"]
        WriteVer["乐观并发更新\nPUT /{namespace} (expectedConfigVersion & If-Match)"]
        HistoryDiff["版本历史、Diff 与回滚\nGET /history & /diff | POST /rollback"]
        ReadVer --> WriteVer --> HistoryDiff
    end

    PipelinesUI --> CreateDraft
    SystemConfigUI --> ReadVer

四类业务 Pipeline 固定步骤与可调参数对照表

每条 Pipeline 的场景类型(scenario)在创建后固定不可修改,其内部节点按既定拓扑顺序执行(不可重排或删除节点,但支持按规则启停可选节点):

场景名称 (scenario)固定的节点执行拓扑顺序核心可调节点参数与模型路由覆盖样例验证(Dry-run)行为
**新增记忆 (add_memory)**receive(接收) → fact_extraction(事实抽取) → conflict_detection(冲突判断) → memory_operation(记忆操作)- fact_extraction:自定义抽取提示词、单次最大抽取事实数(maxFacts)、Chat 模型路由(可开关);<br>- conflict_detection:冲突判定提示词、每个事实召回候选数(candidatesPerFact)、最大总候选数(maxCandidates)、Chat 模型路由(可开关);<br>- 共享 models:可覆盖 embedding、rerank、vision 路由及冲突重排开关 rerankEnabled。调用真实模型执行抽取与冲突比对,直接展示计划执行的 ADD/UPDATE/DELETE/NONE 结果,不写入正式记忆表。
**画像 (profile)**receive(接收) → profile_generation(画像生成) → profile_operation(画像操作)- 三个步骤均必选;<br>- profile_generation:可分别定制增量生成提示词(prompt)与来源重建提示词(rebuildPrompt),并可独立指定生成节点的 Chat/VLM 模型路由。调用模型并返回生成的画像正文,不覆盖用户现有正式画像。
**经验与技能 (distillation)**receive → skill_extraction → skill_merge → experience_extraction → experience_merge → validation → knowledge_operation- skill_extraction 与 experience_extraction 至少开启一种(关闭某项时其对应的 merge 节点自动跳过,参数保留);<br>- 合并候选数 maxCandidates(1~20)、合并阈值 mergeThreshold((0, 1]);<br>- 各节点独立提示词与 Chat 模型,共享 models.embedding 路由覆盖。展示提取与合并后的技能/经验标题、摘要与节点技术详情,不落库正式知识或确认单。
**遗忘 (forgetting)**memory_scan(扫描记忆) → forgetting_decision(遗忘判断) → forgetting_operation(执行遗忘)- 使用确定性数学衰减规则(无 LLM 提示词参数);<br>- memory_scan:扫描批量 batchSize(1~1000);<br>- 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

截图未公开:原图可能包含账号或资源标识。

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

截图未公开:原图可能包含账号或资源标识。

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

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);<br>- observability:enabled、captureContent、successSampleRate、slowThresholdMs;<br>- 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 或系统提示词后,以前写入的旧记忆会自动重新抽取吗?


相关文档