Docs
文档目录

记忆配置中心与自定义 Pipeline

功能概述与核心场景

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

为此,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 对比与一键回滚。

例如,管理员可以为客服场景配置提取工单号和集群版本的流水线,并按实际业务要求设置记忆保留策略。下文中的项目名、模型与参数值均为示例。


核心概念与架构

配置中心将高频迭代的“业务流程节点参数(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;验证样例还需 memories.read
切换或恢复场景默认 Pipeline设为默认 / 恢复系统默认PUT /v1/memory/pipelines/defaultprojects.write
读写 5 大系统配置命名空间基础配置 子视图GET/PUT /v1/projects/{projectId}/memory/config/{namespace}projects.read / projects.write
查看配置历史、Diff 与回滚展开配置版本 区域GET /v1/projects/{projectId}/memory/config/{namespace}/history、GET /v1/projects/{projectId}/memory/config/{namespace}/history/{historyId}/diff?toHistoryId=...、POST .../rollbackprojects.read / projects.write

普通项目 API Key 不提供 projects.write;上述管理写入和样例验证请使用具备相应权限的 Console 会话。


功能详解与操作指南

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

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

记忆配置中心视图

图:2.12.0 测试项目中的页面状态;具体内容取决于项目配置。

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

  2. 在需要定制的流程节点(如 事实抽取 fact_extraction)中,按业务需要修改提示词、单次最大事实数(maxFacts)或节点使用的模型路由。

  3. 单击编辑器顶部的 保存,保存当前草稿。

测试项目的记忆流水线草稿

图:2.12.0 测试项目中新建的流水线草稿,尚未验证或发布。

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

    • 草稿保存后,在样例区输入测试消息和所需用户 ID,单击 验证(调用 POST /v1/memory/pipelines/{pipelineId}/validate);

    • 必须先让当前保存的草稿版本成功通过一次样例验证,系统才允许点击发布。

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

    • 核对样例输出符合预期后,单击 发布(POST /v1/memory/pipelines/{pipelineId}/publish),可同时勾选 设为该场景默认 Pipeline(makeDefault: true)。

    • 发布后,在 记忆、画像 或 经验与技能 页面即可显式选择该已发布 Pipeline,或直接继承更新后的场景默认 Pipeline。已受理的历史任务继续使用其入队时冻结的发布版本,不会因切换默认而重算历史数据。

试运行已保存的流水线版本

项目可以通过试运行接口比较同一场景下已保存的流水线版本。创建请求使用 POST /v1/memory/pipeline-runs,使用具备管理权限的 Console 会话;普通项目 API Key 无法提供此操作要求的 projects.write 权限;请求包含场景、1–8 个候选版本和 1–20 个样本。支持的场景为 add_memory、profile、distillation 和 forgetting。请求被接受时返回 HTTP 202,并不表示试运行已经完成。

使用 GET /v1/memory/pipeline-runs/{runId} 查看进度与逐样本结果,或通过 GET /v1/memory/pipeline-runs 按场景查询;项目 API Key 读取需要同时具备 projects.read 与 memories.read。控制台操作使用已获授权的会话。试运行使用受理时冻结的候选和样本,不进行业务记忆写入;模型调用是否产生费用取决于实际配置。具体可用性以部署环境为准。

创建并验证遗忘流水线示例:

将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),使用具备管理权限的 Console 会话,并设置 APPBASE_PROJECT_ID 与 APPBASE_CONSOLE_SESSION;普通项目 API Key 不适用于此示例。请按顺序单独执行各步骤,仅在上一步返回 HTTP 2xx 且结果符合预期后继续。 创建响应返回 pipelineId、draftVersionId 和 revision;将下方占位符替换为本次返回值。校验通过后,读取最新 revision 再发布;设为默认前使用发布后重新读取的 revision。示例数字仅作占位。

  1. 使用默认配置创建遗忘流水线(scenario=forgetting)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"scenario":"forgetting","fromDefaults":true}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. 执行单用户艾宾浩斯遗忘 Dry-run 校验预览(POST /v1/memory/pipelines/{id}/validate)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines/<PIPELINE_ID_FROM_RESPONSE>/validate" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"versionId":"<DRAFT_VERSION_ID_FROM_RESPONSE>","data":{"userId":"user_zhangwei_001"}}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. 校验成功后发布流水线(POST .../publish)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines/<PIPELINE_ID_FROM_RESPONSE>/publish" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"versionId":"<DRAFT_VERSION_ID_FROM_RESPONSE>","expectedRevision":1,"makeDefault":false}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. 确认发布成功后,将该流水线设为默认。

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X PUT "${APPBASE_ENDPOINT}/memory/pipelines/default" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"scenario":"forgetting","pipelineId":"<PIPELINE_ID_FROM_RESPONSE>","expectedRevision":2}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)

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)与配置回滚

为防止多名管理员同时修改配置产生静默覆盖,所有配置命名空间均实施严格的乐观并发锁与 HTTP 条件请求头支持:

使用具备管理权限的 Console 会话。先显式设置目标环境的 APPBASE_ENDPOINT(包含 /v1)、APPBASE_PROJECT_ID 和 APPBASE_CONSOLE_SESSION;以下步骤在同一会话中单独执行。读取成功并核对返回的配置后,才按需执行更新。

读取当前配置。

: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
# 1. 读取当前 retention 可编辑配置与版本
unset RETENTION_RESP RET_VER RET_SCHEMA RET_ETAG RET_VALUE
if RETENTION_RESP="$(
  set +x
  set -e -o pipefail
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin")"; then
RET_VER="$(printf '%s' "${RETENTION_RESP}" | jq -er '.configVersion')" &&
RET_SCHEMA="$(printf '%s' "${RETENTION_RESP}" | jq -er '.schemaVersion')" &&
RET_ETAG="$(printf '%s' "${RETENTION_RESP}" | jq -er '.etag')" &&
RET_VALUE="$(printf '%s' "${RETENTION_RESP}" | jq -ec '.editableValue | objects')"
else
  builtin printf 'Failed to read retention configuration\n' >&2
  false
fi

确认目标后更新配置。

(
  set +x
  set -e -o pipefail
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${RET_VER:?Read the current retention configuration first}"
: "${RET_SCHEMA:?Read the current retention configuration first}"
: "${RET_ETAG:?Read the current retention configuration first}"
: "${RET_VALUE:?Read the current retention configuration first}"
# 2. 保留现有字段,仅更新需要修改的保留天数
UPDATE_BODY="$(jq -n --argjson version "${RET_VER}" --argjson schema "${RET_SCHEMA}" \
  --argjson value "${RET_VALUE}" \
  '{expectedConfigVersion: $version, schemaVersion: $schema,
    reason: "Update retention periods", value: ($value | .factDays = 365 | .auditEventDays = 90)}')"
: "${UPDATE_BODY:?Failed to construct the request}"
builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "If-Match: ${RET_ETAG}" \
  -H "Content-Type: application/json" --data "${UPDATE_BODY}" | jq .
)

按需查看历史差异。

(
  set +x
  set -e -o pipefail
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
# 3. 从历史列表选择两个记录 ID 后查看差异
: "${FROM_HISTORY_ID:?Set the source history ID}"
: "${TO_HISTORY_ID:?Set the target history ID}"
builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -G "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention/history/${FROM_HISTORY_ID}/diff" \
  --data-urlencode "toHistoryId=${TO_HISTORY_ID}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" | jq .
)

常见问题与排障(FAQ)

1. 为什么在自定义 Pipeline 中点击“发布”按钮时提示无法发布?

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

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


相关文档

Pipeline 对比试运行

选择同一场景下已经保存的 Pipeline 版本,对固定样本发起对比试运行。四类场景为 add_memory、profile、distillation、forgetting,每次 1–8 个候选、1–20 个有唯一 ID 的样本。提交时冻结候选配置与输入,后续修改草稿不会改变已有运行。

试运行不写入业务记忆,仍可能调用模型;检查各候选的执行结果、失败信息和费用,再选择需要发布的配置。HTTP 接受只表示已入队,等待运行终态再比较;读取或执行权限不足时分别核对 projects.read/projects.write,而不是只补 memories.read。