后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本指南围绕 semantic-router 的memory路由本地插件展开讲解如何让某一条或某一族路由独立启用会话记忆的检索与自动存储同时把共享后端统一收敛到global.stores.memory。读完本文你将掌握 memory 插件的 YAML 配置方式、三种后端Milvus / Valkey / Qdrant的选型与参数、反射Reflection门控对注入 token 预算的影响、Prometheus 可观测指标以及更换 embedding 模型时物理集合隔离的迁移注意事项。为什么需要 memory 插件将记忆行为锁定在路由本地memory是 semantic-router 提供的 route-local 插件在源码中注册为DecisionPluginMemory见 plugin_registry.go负责「检索历史会话记忆」和「自动存储有用的新对话轮次」两件事。它解决的核心问题是并非每一条路由都应该承担检索记忆带来的复杂度与隐私成本。如果所有路由都无差别地读写共享记忆系统的隐私边界、数据保留策略和性能开销都会失控。memory 插件的设计将记忆行为限定在真正受益的路由上记忆行为只对命中该决策decision的路由生效不扩散到其他路由检索与自动存储在同一个插件内完成不需要分别接入两条链路路由本地只声明「要不要用记忆、取多少条」而共享存储的连接、鉴权、维度等基础设施配置统一放在global.stores.memory实现策略与后端解耦。值得注意的边界会话级模型稳定性session-aware model stability属于另一套 Router Learning 适配配置在global.router.learning下与 memory 插件互不混淆。何时应该启用 memory 插件满足以下任一场景就可以为对应决策挂载 memory 插件该路由需要检索用户此前的会话上下文如多轮客服、Agent 对话该路由需要自动把有价值的新对话轮次写回记忆库auto_store记忆的开关、检索条数等设置希望保持在该路由族route family本地不全局扩散。若路由既不需要检索也不需要存储保持enabled: false或干脆不挂载该插件即可——这正是「按需付费复杂度」的体现。全局后端global.stores.memory与三种存储后端memory 插件本身不携带存储连接信息它依赖global.stores.memory提供的后端。仓库默认的全局内存配置见 canonical_defaults.go为enabled: false、auto_store: false、Milvus 默认 collection 为agentic_memory、default_retrieval_limit: 5。路由器支持三种后端后端定位适用场景Milvus默认分布式向量数据库大规模生产环境Valkey基于 Search 模块的单二进制轻量方案开发/测试或已有 Valkey 基础设施Qdrant支持 gRPC 的单二进制方案运维比 Milvus 简单覆盖中小到较大规模负载三种后端的完整配置参考见 stores-and-tools 教程、Valkey Memory 部署指南 与 Qdrant 部署指南后端专属配置片段位于 config/runtime/memory/。Milvus默认后端global: stores: memory: enabled: true milvus: address: milvus:19530 collection: agentic_memory dimension: 256Valkey需要带 Search 模块的 Valkey 服务Valkey 后端使用 HASH 结构存储、FT.SEARCH 做向量相似度检索对应实现见 valkey_store.go需要--enable-search编译或使用 valkey-bundle 镜像。完整参考配置见 config/runtime/memory/valkey.yamlglobal: stores: memory: enabled: true backend: valkey valkey: host: valkey port: 6379 database: 0 password: timeout: 10 collection_prefix: mem: index_name: mem_idx dimension: 256 # mmbert 支持 64/128/256/512/768 metric_type: COSINE # COSINE、L2 或 IP index_m: 16 # HNSW 每节点双向链接数越高越准、越耗内存 index_ef_construction: 256 # 建索引搜索宽度越高召回越好、构建越慢 tls_enabled: false tls_ca_path: tls_insecure_skip_verify: false embedding_model: mmbert default_retrieval_limit: 5 default_similarity_threshold: 0.40 hybrid_search: true hybrid_mode: weighted adaptive_threshold: true reflection: enabled: true algorithm: heuristic max_inject_tokens: 512 recency_decay_days: 14 dedup_threshold: 0.9Qdrantglobal: stores: memory: enabled: true backend: qdrant qdrant: host: qdrant port: 6334 collection: agentic_memory dimension: 256 embedding_model: mmbert default_retrieval_limit: 5 default_similarity_threshold: 0.30嵌入维度与阈值的关键约束三个示例均使用默认嵌入模型mmbertVela Embedding因此dimension只能取 64、128、256、512、768 之一。若配置其他维度路由器会记录Failed to create memory store: … Memory will be disabled并以无记忆状态运行见 stores-and-tools 教程。另外注意Qdrant 示例中的0.30相似度阈值只是基于普通余弦分数的起点并非校准值用于生产前应先结合自己的数据检查无关查询与已修正事实。hybrid_mode只接受weighted、rrf小写精确reflection.algorithm只接受heuristic、noop其他值如旧的rerank、recency_semantic会在启动时被拒绝。在决策下挂载 memory 插件在routing.decisions[].plugins中加入type: memory即可。仓库提供的官方片段 config/fragments/plugin/memory/session-memory.yaml 内容如下plugin: type: memory configuration: enabled: true retrieval_limit: 5 # Inherit the embedding-model-calibrated global threshold. auto_store: true在完整决策中的写法即routing: decisions: - name: session_agent_route ... plugins: - type: memory configuration: enabled: true retrieval_limit: 5 auto_store: true插件配置字段说明从源码看plugin_config.gomemory 插件的完整配置面包括字段类型含义enabledbool是否启用该决策的 memoryretrieval_limit*int单次检索返回的最大记忆条数缺省继承全局default_retrieval_limit默认 5similarity_threshold*float32检索相似度阈值缺省继承全局校准值auto_store*bool是否自动存储本轮对话hybrid_searchbool是否启用混合检索hybrid_modestringweighted或rrfreflectionMemoryReflectionConfig反射过滤的覆盖配置关键点省略的 per-decision 阈值threshold会继承全局设置resolveReflectionConfig会把 per-decision 覆盖合并进全局配置见 reflection.go。因此在为某个决策添加similarity_threshold覆盖之前应先基于所选 embedding 模型与检索模式校准该全局值再决定是否覆盖。校验逻辑见 validator_memory.go。写入路径的优先级与异步落盘自动存储遵循这样的优先级链详见 stores-and-tools 教程首先尊重全局 memory 开关、保留策略retention以及该决策插件上显式的auto_store: false当策略允许持久化时Responses 请求自带的auto_store优先于决策值其次才是global.stores.memory——只有被省略的值才逐级回退。响应处理不会等待 Memory 持久化完成身份检查与容量预留先行历史快照在响应路径仍持有会话状态时截取协议编码与写入在后台执行。global.stores.memory.persistence提供有界化的异步写入约束字段含义默认timeout_seconds从预留到超时的秒数30concurrency工作槽数量8queue等待工作槽的预留尝试数64shutdown_grace_seconds重载/停机时排空写操作秒数5这些值在配置校验阶段就会拒收负数与超限值。持久化负载超限历史过大时会以skipped/history_too_large且fail_opentrue跳过写入绝不截断模型响应被 jailbreak 或 hallucination 策略拦截的响应以policy_blocked记录不会落盘。存储层的实现从「原始对话轮次」到向量记忆memory 插件的后端存储采用「直接存储对话轮次」的实现MemoryExtractor不调用 LLM 抽取事实而是把原始用户问题与助手回答去除 think 标签后直接 embedding 并按滑动窗口写入向量库见 extractor.go默认每 5 轮存储一个会话块以改善多跳检索。这意味着记忆检索与存储都只依赖 embedding 模型与向量库不需要额外的抽取模型端点。检索侧还支持可选的 Redis 热缓存前置层global.stores.memory.redis_cache见 runtime_config.go热点查询可命中缓存而免于打到 Milvus缓存命中/未命中分别由llm_memory_cache_hits_total与llm_memory_cache_misses_total计量。反射Reflection与max_inject_tokens注入前的智能裁剪当global.stores.memory.reflection开启默认启用见 runtime_config.goReflectionEnabled()在未显式配置时返回true检索到的记忆在注入模型前会被裁剪到max_inject_tokens预算以内。这是一个无 LLM 调用的启发式门控sub-millisecond 开销实现位于 reflection.go其Filter流程包含五步阻断按block_patterns正则过滤对抗性内容时效衰减按exp(-0.693 × age_days / halfLife)对得分做指数衰减半衰期recency_decay_days默认 30 天重排按调整后得分降序去重基于文本单元 Jaccard 相似度dedup_threshold默认 0.90并保留数字绑定如「一万美元/两万美元」不会被误判为重复预算裁剪按累计估算 token 数截断到max_inject_tokens默认 2048。脚本感知的多语言 token 估算token 预算采用脚本感知启发式而非上游模型 tokenizer对应实现见 reflection.go每个拉丁词单元约计1.3 tokens每个 Han汉字、Hiragana、Katakana 或 Hangul 字符约计1.5 tokens合计估算结果向上取整ceil。因此无空格 CJK 文本会把大量字符计入预算而不是像英文那样塌缩成单个空格词。面向中文、日文、韩文流量调整max_inject_tokens的运维者应当预期裁剪会比旧的纯英文估算更紧。泰语等其他无空格书写系统暂未在此完整分词精确的 tokenizer 记账由路由预算另行跟踪。默认recency_decay_days与dedup_threshold的取值逻辑可见 reflection.go。可观测性Router Memory 的 Prometheus 指标Router Memory 在 Router 抓取端点scrape endpoint暴露有界的 Prometheus 指标定义见 metrics.go指标类型标签llm_memory_retrieval_totalCounterbackend、statushit/miss/errorllm_memory_retrieval_latency_secondsHistogrambackend、operationllm_memory_retrieval_resultsHistogrambackend每次查询返回的记忆条数llm_memory_extraction_totalCounterstatusllm_memory_store_operations_totalCounterbackend、operation、statusllm_memory_store_sizeGaugebackendllm_memory_cache_hits_total/llm_memory_cache_misses_totalCounterbackend延迟与结果计数使用独立直方图不带 per-user 标签——这是有意为之的有界基数设计。如果你的监控面板从带user_id标签的旧版本升级而来请阅读 Router Memory Prometheus label release note旧版本llm_memory_retrieval_total的标签为backend、status、user_id新版本移除user_id聚合查询需相应改写例如sum by (backend, status) (llm_memory_retrieval_total)。status在 Milvus、Valkey、Qdrant 后端上继续区分hit、miss、error。更换 embedding 模型自动身份绑定与集合隔离Memory 的 embedding 权重变更后需要重启 model runtime。关键机制是身份绑定identity binding实现相关代码见 embedding.go对于来自 model runtime 的嵌入包括 Vela Embedding路由器会把 memory 绑定到已加载的模型、tokenizer、推理设置与向量维度以上任一发生变化就会创建独立的物理 collection/index 与独立的 Redis 热缓存——即使逻辑名称不变用相同表示representation重启则复用已有存储你配置的逻辑名logical names保持不变。几点重要的迁移事实早期未打标签untagged的 collection 会被保留但不会被自动采纳向量维度相同并不能证明两个模型产出的 embedding 兼容管理 API 目前没有记忆的导入或批量导出端点因此新模型的 collection 从空开始、由新流量重新填充启动或模型迁移期间不会删除任何旧 collection这种自动身份绑定覆盖 model runtime 提供的每一种 embedding。对于远程 embedding 端点远程端点无法证明其向量由哪个模型产生因此 memory 会保留已配置的 collection/index并在启动时记录一条警告。当你修改了endpoint.model或 provider 在端点背后更换了模型需要把 memory 指向一个新的 collection/index——新 collection 从空开始旧 collection 原样保留。数据与安全提示记忆库中可能包含提示词、响应、向量与抽取出的记忆内容。请为所选后端配置与之相称的用户/租户隔离、保留策略、认证与传输安全TLS。例如 Valkey 后端可通过tls_enabled、tls_ca_path启用 TLS密码建议从环境变量注入。在嵌入模型或向量维度变更后需要重建或迁移索引以匹配既有 collection 的维度。小结semantic-router 的 memory 插件把「检索 自动存储」打包为路由本地的轻量策略点决策处只声明retrieval_limit与auto_store共享存储统一收敛在global.stores.memory后端可选 Milvus / Valkey / Qdrant。注入前由脚本感知的 ReflectionGate 做去重、时效衰减与 token 预算裁剪多语言文本的估算规则决定了 CJK 流量需要更紧的预算设置Prometheus 指标与身份绑定的集合隔离机制则为监控与模型升级提供了可操作的基础设施。结合 session-memory.yaml 片段与 stores-and-tools、valkey-memory、qdrant 部署指南即可在生产中落地一套路由局部、后端共享的会话记忆方案。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Semantic Router Agentic Memory 提案解读检索→注入→提取→存储的持久记忆闭环设计与落地对照Semantic Router Agentic Memory 提案解读检索→注入→提取→存储的持久记忆闭环设计与落地对照 本篇技术指南围绕 semantic后端API网关模型推理服务AI Agentgrok-build 跨会话记忆Cross-Session Memory完全指南存储架构、搜索评分与配置实战grok build 跨会话记忆Cross Session Memory完全指南存储架构、搜索评分与配置实战 记忆Memory是 grok build人工智能大模型AI Agent代码智能体CLI工具调用MCP ClientsVoltAgent Agent Memory 完全指南会话存储、语义检索与工作记忆的工程化实践VoltAgent Agent Memory 完全指南会话存储、语义检索与工作记忆的工程化实践 VoltAgent 的 Memory 类是构建有状态 AI A人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇突破生成瓶颈DiT模型分布式推理实战指南下一篇告别教材预览难题kkFileView全格式文件在线预览终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考