Docs
文档目录

记忆模型路由配置

功能概述与核心场景

记忆模型路由(Memory Model Routing,控制台页签为 模型)是 Agentbase Memory(v2.10.0)连接底层大模型与向量计算能力的枢纽,对应项目 Memory 配置中心的 provider 命名空间(/v1/projects/{projectId}/memory/config/provider)。Memory 并非单一模型调用,而是由稠密向量(Dense Embedding)、稀疏向量(Sparse Embedding)、对话生成(Chat LLM)、语义重排(Rerank)与多模态视觉(Vision LLM)五类异构模型协同驱动的复合智能引擎。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,Memory 模型路由统一挂载至项目的 DashScope 生产提供方 dashscope-prod(兼容端点 https://dashscope.aliyuncs.com/compatible-mode/v1):


核心概念与架构

Memory 服务本身不在业务表或异步 Job 快照中明文存储任何上游模型的 API Key。所有模型请求均以逻辑引用(providerRef: "project:dashscope-prod" + model)的形式发起,由 Agentbase 内部的 Models(LLM Gateway) 实时解析凭据、执行协议转换与可观测计量。

记忆模型路由配置:流程示意,不是运行截图

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

查看流程图大图

五类模型能力与职责对照表

模型能力类别provider 配置字段标杆项目配置值 (dashscope-prod)作用的业务阶段与降级/失败行为
稠密向量(Dense Embedding)embeddingProviderRef
embeddingModel
embeddingDims
project:dashscope-prod
text-embedding-v3
1024
负责普通记忆、L2/L3 上下文、Experience 与 Skill 的向量化及 vector/hybrid 检索。项目初始化后这三个字段永久锁定。
稀疏向量(Sparse Embedding)sparseEmbeddingEnabled
sparseEmbeddingProviderRef
sparseEmbeddingModel
true
project:dashscope-prod
text-embedding-v3(Sparse 路由)
负责生成稀疏词项权重向量,支撑 sparse 与 hybrid 检索路线。新启用向导默认开启;若提供方不支持稀疏向量可显式关闭。
对话与推理(Chat LLM)llmProviderRef
chatModel
structuredOutputMode
project:dashscope-prod
qwen-plus
tool_call
负责 infer=true 事实抽取、ADD/UPDATE/DELETE/NONE 冲突判断、Graph 实体边提取、查询改写、用户画像与经验蒸馏。支持 tool_call(推荐)与 legacy_json。
语义重排(Rerank)rerankProviderRef
rerankModel
project:dashscope-prod
qwen3.7-text-rerank
负责在检索阶段对多路融合候选重排(需同时开启 policy.rerankEnabled),以及在新增记忆冲突检测时重排相似记忆候选。重排异常时在响应 degraded.rerank 中标记降级。
多模态视觉(Vision LLM)visionProviderRef
visionModel
project:dashscope-prod
qwen-vl-max
独立于文本 Chat 模型,专门用于解析 Storage 图片(PNG/JPEG/WebP)与 PDF 文档,或在图片搜索时将图片转为文本描述。必须成对配置,未配置时拒绝媒体输入。

功能入口与权限矩阵

控制台入口与管理权限

控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 模型 页签(内部复用配置中心的 provider 命名空间视图)。

操作动作入口位置底层 REST API所需权限关联关系
登记上游模型 Provider左侧导航栏 Models(模型网关)/v1/llm-gateway/providersprojects.write为 Memory 提供可选的 project:<providerId> 目录
查看当前 Memory 模型路由记忆 → 模型 页签GET /v1/projects/{projectId}/memory/config/providerprojects.read返回当前 version、etag 与完整 provider 路由配置
更新默认模型路由记忆 → 模型 → 保存配置PUT /v1/projects/{projectId}/memory/config/providerprojects.write须携带 expectedConfigVersion 乐观锁版本号
覆盖单条 Pipeline 模型路由记忆 → 配置 → 各场景 PipelinePATCH /v1/memory/pipelines/{pipelineId}projects.write未勾选覆盖时自动继承本页的 provider 默认路由

默认路由与自定义 Pipeline 路由的继承关系

  1. 继承与覆盖规则: 在 记忆 → 配置 的四类 Pipeline(新增记忆、画像、经验与技能、遗忘)中,各节点(如事实抽取、冲突判断、画像生成)可单独指定模型路由;若取消勾选节点级路由覆盖,则自动继承本页(provider 命名空间)配置的默认路由(取消勾选代表“继承默认”,而非“禁用该能力”)。

  2. 共享模型路由快照: 当前项目的默认新增记忆 Pipeline 中配置的共享 embedding、rerank 与 vision 路由,还会同时作用于在线记忆检索(search)、统一召回(recall)、图片查询解析以及后台补索引任务。异步任务在受理入队瞬间会冻结当时的模型路由快照(但不含明文密钥),确保重试期间行为一致。


功能详解与操作指南

1. 在控制台查看与调整 Memory 模型路由

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210)。

  2. 先确认在左侧 Models(模型网关) 中已添加提供方 dashscope-prod,且模型目录中包含 text-embedding-v3、qwen-plus、qwen3.7-text-rerank 和 qwen-vl-max(视觉模型优先展示登记了 vlm 分类的模型,也兼容 chat 分类下的多模态模型)。

  3. 打开左侧 记忆(Memory) 并切换到 模型 页签。

记忆模型路由视图(沿用已登记截图)

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

  1. 按业务需求配置或调整可编辑的模型路由字段:

    • Embedding 路由(只读锁定):页面显示 embeddingProviderRef(project:dashscope-prod)、embeddingModel(text-embedding-v3)与 embeddingDims(1024)处于锁定状态,防止破坏 OceanBase 既有向量表空间。

    • 稀疏向量(Sparse Embedding):勾选开启并绑定 project:dashscope-prod 的稀疏向量模型。

    • Chat 模型路由:选择提供方 project:dashscope-prod 与模型 qwen-plus,并将 结构化输出模式(structuredOutputMode) 设为 tool_call(由 LLM Gateway 强制校验工具名与 JSON Schema,显著降低 LLM_INVALID_JSON 发生率)。

    • Rerank 模型路由:选择提供方 project:dashscope-prod 与模型 qwen3.7-text-rerank。

    • 视觉模型路由(Vision LLM):成对选择 visionProviderRef(project:dashscope-prod)与 visionModel(qwen-vl-max)。注意:只填其中一项无效,必须成对配置并保存后,项目才接受 Storage 图片/PDF 记忆写入。

  2. 填写变更原因(reason)并单击 保存。

2. provider 配置命名空间完整参数规范

通过控制面 API 读写 /v1/projects/{projectId}/memory/config/provider 时,完整字段定义如下:

字段名类型初始化后可否修改标杆配置示例校验规则与详细说明
allowedProvidersstring[]可修改["openai", "dashscope", "anthropic", "theta"]允许项目 Memory 使用的上游提供方类型白名单。
credentialModestring可修改"project_gateway"固定通过项目 LLM Gateway 解析凭据,禁止在请求中内联明文密钥。
embeddingProviderRefstring不可变(Immutable)"project:dashscope-prod"稠密向量提供方引用。Memory 初始化后修改会触发 400/409 不可变守卫拦截。
embeddingModelstring不可变(Immutable)"text-embedding-v3"稠密向量模型标识,初始化后永久锁定。
embeddingDimsinteger不可变(Immutable)1024向量物理列维度,必须与模型实际输出维度一致,初始化后永久锁定。
sparseEmbeddingEnabledboolean可修改true是否开启稀疏向量索引与稀疏检索分支。
sparseEmbeddingProviderRefstring可修改"project:dashscope-prod"稀疏向量提供方引用(开启稀疏向量时必填)。
sparseEmbeddingModelstring可修改"text-embedding-v3"稀疏向量模型标识。
llmProviderRefstring可修改"project:dashscope-prod"默认对话与推理模型提供方引用。
chatModelstring可修改"qwen-plus"默认对话与推理模型名称。
structuredOutputModestring可修改"tool_call"结构化输出协议,支持 "tool_call"(推荐,强制 Schema)与 "legacy_json"。
rerankProviderRefstring可修改"project:dashscope-prod"默认重排模型提供方引用。
rerankModelstring可修改"qwen3.7-text-rerank"默认重排模型名称。
visionProviderRefstring可修改"project:dashscope-prod"多模态视觉模型提供方引用,须与 visionModel 成对设置。
visionModelstring可修改"qwen-vl-max"多模态视觉模型名称,用于解析 Storage 图片与 PDF。

3. 通过控制面 API 查询与更新模型路由示例

更新项目配置属于控制面操作,需要使用 Console 管理员会话(或管理员 JWT + X-Appwrite-Mode: admin),并传入最近一次 GET 返回的 expectedConfigVersion:

export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"

# 1. 读取当前 provider 命名空间配置与版本号 (version)
PROVIDER_RESP="$(curl -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin")"

echo "${PROVIDER_RESP}" | jq .
CURRENT_VERSION="$(echo "${PROVIDER_RESP}" | jq -er '.version')"

# 2. 更新 provider 配置(保持锁定的 embedding 三元组不变,启用 qwen-vl-max 视觉路由与 tool_call 模式)
curl -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "Content-Type: application/json" \
  --data "{
    \"expectedConfigVersion\": ${CURRENT_VERSION},
    \"reason\": \"开启 qwen-vl-max 多模态视觉路由并切换 tool_call 结构化输出模式\",
    \"value\": {
      \"allowedProviders\": [\"openai\", \"dashscope\", \"anthropic\", \"theta\"],
      \"credentialMode\": \"project_gateway\",
      \"embeddingProviderRef\": \"project:dashscope-prod\",
      \"embeddingModel\": \"text-embedding-v3\",
      \"embeddingDims\": 1024,
      \"sparseEmbeddingEnabled\": true,
      \"sparseEmbeddingProviderRef\": \"project:dashscope-prod\",
      \"sparseEmbeddingModel\": \"text-embedding-v3\",
      \"llmProviderRef\": \"project:dashscope-prod\",
      \"chatModel\": \"qwen-plus\",
      \"structuredOutputMode\": \"tool_call\",
      \"rerankProviderRef\": \"project:dashscope-prod\",
      \"rerankModel\": \"qwen3.7-text-rerank\",
      \"visionProviderRef\": \"project:dashscope-prod\",
      \"visionModel\": \"qwen-vl-max\"
    }
  }" | jq .

常见问题与排障(FAQ)

1. 为什么项目启用 Memory 后,不能在“模型”页签中直接修改 Embedding 模型或向量维度?

2. 在模型页签配置了 qwen3.7-text-rerank 重排模型,为什么搜索结果响应中仍没有触发 Rerank?

3. 异步写入或蒸馏任务报错 LLM_RATE_LIMITED、LLM_INVALID_JSON 或 LLM_REQUEST_REJECTED 时如何处理?


相关文档