AgentbaseDocs
文档目录

记忆模型路由配置

功能概述与核心场景

记忆模型路由(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) 实时解析凭据、执行协议转换与可观测计量。

flowchart LR
    subgraph MemoryConfig["Memory 模型路由层 (provider 命名空间 & Pipeline 覆盖)"]
        DefaultRoute["项目默认模型路由\n(/memory/config/provider)"]
        PipelineOverride["Pipeline 节点级模型覆盖\n(add_memory / profile / distillation)"]
        ImmGuard["向量空间不可变守卫\n(锁定 embeddingProviderRef / Model / Dims)"]
        DefaultRoute --> ImmGuard
        PipelineOverride --> ImmGuard
    end

    subgraph Capabilities["五类异构模型能力分工"]
        Dense["1. 稠密向量 (Dense Embedding)\ntext-embedding-v3 (1024维)\n记忆/知识向量化与 Vector 检索"]
        Sparse["2. 稀疏向量 (Sparse Embedding)\nDashScope Sparse 路由\n高维词项权重索引与 Sparse 召回"]
        Chat["3. 对话与推理 (Chat LLM)\nqwen-plus (structuredOutputMode=tool_call)\n事实提取 / 冲突判断 / 画像 / 蒸馏 / 图抽取"]
        Rerank["4. 语义重排 (Rerank)\nqwen3.7-text-rerank\n搜索结果重排 & 冲突候选重排"]
        Vision["5. 多模态视觉 (Vision LLM)\nqwen-vl-max\nStorage 图片/PDF 入库解析 & 图片查询转文本"]
    end

    subgraph GatewayLayer["Models / LLM Gateway (dashscope-prod)"]
        CredResolver["安全凭据解析与限流保护\nhttps://dashscope.aliyuncs.com/compatible-mode/v1"]
        Telemetry["模型调用遥测与错误分类\nmemory.model.call (LLM_RATE_LIMITED / LLM_TIMEOUT)"]
    end

    ImmGuard --> Dense
    ImmGuard --> Sparse
    ImmGuard --> Chat
    ImmGuard --> Rerank
    ImmGuard --> Vision
    Dense --> CredResolver
    Sparse --> CredResolver
    Chat --> CredResolver
    Rerank --> CredResolver
    Vision --> CredResolver
    CredResolver --> Telemetry

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

模型能力类别provider 配置字段标杆项目配置值 (dashscope-prod)作用的业务阶段与降级/失败行为
稠密向量(Dense Embedding)embeddingProviderRef<br>embeddingModel<br>embeddingDimsproject:dashscope-prod<br>text-embedding-v3<br>1024负责普通记忆、L2/L3 上下文、Experience 与 Skill 的向量化及 vector/hybrid 检索。项目初始化后这三个字段永久锁定。
稀疏向量(Sparse Embedding)sparseEmbeddingEnabled<br>sparseEmbeddingProviderRef<br>sparseEmbeddingModeltrue<br>project:dashscope-prod<br>text-embedding-v3(Sparse 路由)负责生成稀疏词项权重向量,支撑 sparse 与 hybrid 检索路线。新启用向导默认开启;若提供方不支持稀疏向量可显式关闭。
对话与推理(Chat LLM)llmProviderRef<br>chatModel<br>structuredOutputModeproject:dashscope-prod<br>qwen-plus<br>tool_call负责 infer=true 事实抽取、ADD/UPDATE/DELETE/NONE 冲突判断、Graph 实体边提取、查询改写、用户画像与经验蒸馏。支持 tool_call(推荐)与 legacy_json。
语义重排(Rerank)rerankProviderRef<br>rerankModelproject:dashscope-prod<br>qwen3.7-text-rerank负责在检索阶段对多路融合候选重排(需同时开启 policy.rerankEnabled),以及在新增记忆冲突检测时重排相似记忆候选。重排异常时在响应 degraded.rerank 中标记降级。
多模态视觉(Vision LLM)visionProviderRef<br>visionModelproject:dashscope-prod<br>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. 在控制台查看与调整 Memory 模型路由

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

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

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 时如何处理?


相关文档