★ FEATURED ARTICLE 后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读router_replay是 semantic-router 提供的路由局部route-local插件用于为指定路由捕获请求—响应重放/调试产物。它把重放捕获的粒度从全局收敛到单条路由只有处于调试、审计或受控重放分析中的路由才产生存储开销其余路由完全不受影响。读完本文你将掌握router_replay的完整配置参数含全局global.services.router_replay与插件级覆盖、存储后端选型memory/redis/postgres/milvus/qdrant、内置的请求/响应体截断与工具轨迹限流机制以及通过 ext-proc 只读 API 查询重放记录与聚合统计的方法。一、什么是 Router Replayrouter_replay是路由局部插件对应配置文件 config/fragments/plugin/router-replay/debug.yaml。它解决的问题非常直接重放replay有用但并非每条路由都应该记录同样多的数据。如果重放存储是全局开关那么所有流量都会背上写入与存储成本而router_replay允许单条路由自行选用重放行为把存储成本局部化从而避免全局化存储成本。主要优势重放捕获局部在活跃调试或审计的路由上只有挂载了该插件的 decision路由决策才会捕获其他路由零开销支持请求与响应体控制capture_request_body/capture_response_body可分别决定是否落盘请求体与响应体规避敏感内容与存储膨胀存储限制显式而非隐式max_records、max_body_bytes等上限全部显式可配让每条路由的存储行为可预期、可审计。何时使用适合在以下场景启用一条路由正处于调试、审计或受控重放分析阶段捕获限制需要对每条路由显式声明不同路由允许不同配额仅希望对选中流量启用重放避免全局开启带来的写放大。二、插件级配置挂载到 routing.decisions[].plugins在routing.decisions[].plugins下使用plugin: type: router_replay configuration: enabled: true max_records: 5000 capture_request_body: true capture_response_body: false max_body_bytes: 65536各字段含义如下插件级配置结构定义见 plugin_config.go参数类型默认值说明enabledbooltrue插件声明后是否启用该 decision 的重放捕获max_recordsint10000config 层默认该路由最多保留的重放记录条数memory 后端生效capture_request_bodybooltrue是否捕获请求体capture_response_bodybooltrue是否捕获响应体max_body_bytesint4096单个请求/响应体最大捕获字节数超过部分截断capture_personal_databooltruenil 视为 true是否允许捕获个人数据false时触发 PII 证据依赖max_tool_trace_bytesint0无限制结构化工具轨迹字段Prompt、ToolDefinitions、ToolTraceStep.Arguments、ToolTraceStep.Output的字节上限max_tool_trace_stepsint100config 层默认每条记录保留的 ToolTraceStep 条数上限超出后丢弃最旧步骤0 表示不限制注意max_records与max_tool_trace_steps的插件级默认值由 config 包提供DefaultRouterReplayPluginConfig见 plugin_router_replay_support.goMaxRecords10000、MaxBodyBytes4096、MaxToolTraceSteps100。而routerreplay包自身的底层默认值不同DefaultMaxRecords200、DefaultMaxBodyBytes4096、DefaultMaxToolTraceSteps0见 recorder.go插件路径下由 config 层统一覆盖保证路由开箱即安全。片段配置示例官方提供的插件片段 config/fragments/plugin/router-replay/debug.yaml 给出了更完整的调试型配置plugin: type: router_replay configuration: enabled: true max_records: 10000 capture_request_body: true capture_response_body: true max_body_bytes: 4096 # 限制每条记录保留的 tool-trace 步数。长 Agent 会话可能使 trace 无界增长并拖垮路由器进程 (#1835)。0 不限制。 max_tool_trace_steps: 100三、全局配置存储后端与全局捕获默认值除插件级配置外重放还有全局配置global.services.router_replay结构定义见 runtime_config.goJSON Schema 见 router-config-v0.3.schema.jsonglobal: services: router_replay: enabled: true store_backend: postgres ttl_seconds: 2592000 async_writes: false postgres: host: postgres port: 5432 database: vsr user: router password: ${POSTGRES_PASSWORD} ssl_mode: disable table_name: router_replay_records全局配置字段参数类型说明enabledbool全局是否启用重放默认关闭store_backendstring存储后端memory/redis/postgres/milvus/qdrant不设置时按已配置的 postgres/redis/milvus/qdrant 推断否则为memoryttl_secondsint记录过期时间redis/postgres 等后端生效0 表示不过期async_writesbool是否异步写存储降低对请求路径的阻塞capture_request_body/capture_response_body/capture_personal_data/max_records/max_body_bytes/max_tool_trace_bytes/max_tool_trace_steps*bool / *int全局捕获默认值会被 decision 插件级显式字段覆盖captureDefaults逻辑见 plugin_router_replay_support.goredis/postgres/milvus/qdrantobject各后端连接配置各后端连接参数均在 runtime_config.go 定义redisaddress、db、password、use_tls、tls_skip_verify、max_retries、pool_size、key_prefixpostgreshost、port、database、user、password、ssl_mode、max_open_conns、max_idle_conns、conn_max_lifetime、table_namemilvusaddress、username、password、collection_name、consistency_level、shard_numqdranthost、port、api_key、use_tls、collection_name。全局默认值与 plugin 覆盖的解析顺序EffectiveRouterReplayConfigplugin_router_replay_support.go展示了实际的生效逻辑先取DefaultRouterReplayPluginConfig()作为基底用全局RouterReplay.captureDefaults()覆盖基底Enabled来自全局开关其余仅覆盖显式设置的字段若 decision 上存在router_replay插件则把插件configuration反序列化到底层配置上插件级字段优先最终Enabled false时返回nil即该 decision 不捕获。仓库中的完整 recipe 示例 config/recipes/agent/config.yaml 展示了全局启用 postgres 持久化 插件级捕获策略的组合用法全局层配置enabled: true、store_backend: postgres、ttl_seconds: 2592000与连接信息而具体 decision如第 1059–1066 行再以插件形式声明capture_request_body: true、capture_response_body: true、max_body_bytes: 2048、max_records: 10000、max_tool_trace_steps: 100。四、存储后端与 Recorder 生命周期router_replay的运行时核心是Recorderrecorder.go其初始化与后端解析逻辑集中在 router_replay_setup.go后端解析resolveReplayStoreBackend第 180–197 行优先读store_backend字段否则按 postgres → redis → milvus → qdrant 顺序推断兜底memory共享存储判定usesSharedReplayStorage第 171–178 行postgres、redis、milvus、qdrant视为共享后端多个 decision 可共用一个共享存储实例memory为隔离后端每个 decision 独立创建内存存储memory 后端的显式警告createReplayStore第 206–232 行源码会记录Warnf日志提示memory后端在配置重载或路由重启后全部记录丢失生产环境应改用postgres或redis等持久化后端每个 decision 一个 RecorderinitializeIsolatedReplayRecorders第 65–88 行以RoutingDecisionKey(recipe, decision)为键创建独立 recorder并应用该 decision 解析出的捕获策略SetCapturePolicy、SetMaxToolTraceBytes、SetMaxToolTraceSteps。捕获策略的执行Recorder.AttachRequest/AttachResponserecorder.go严格遵循捕获策略若captureRequestBody falseAttachRequest直接返回nil不产生任何存储 I/O捕获时先经truncateBody(body, maxBodyBytes)截断再落盘并标记truncated操作有独立超时DefaultOperationTimeout 5s存储 I/O 不拖累客户端请求。五、工具轨迹ToolTrace保护与防 OOM 限流针对 Agent 场景router_replay提供了两层工具轨迹防护max_tool_trace_bytes限制每条结构化轨迹字段Prompt、ToolDefinitions、ToolTraceStep.Arguments、ToolTraceStep.Output的字节数独立于原始 body 的max_body_bytes保证结构化字段在原始体被截断时仍保持完整max_tool_trace_steps限制每条记录保留的 ToolTraceStep 条数。长 Agent 会话每轮工具调用产生一个 step若不加限制失控的循环如 hermes 式死循环会让 trace 无界增长最终 OOM 路由器进程——这正是 issue #1835 的动机见 plugin_config.go 与 recorder.go。超限时的处理策略是丢弃最旧drop oldest保留最近时间线的步骤并在ToolTrace.StepsTruncated上置位调用方可见限流发生。该策略在UpdateToolTrace路径上同样生效recorder.go因为响应侧轨迹正是通过该更新路径写入若不在此处再次截断即便AddRecord截断正确#1835 的 OOM 场景依然可能发生。六、通过 ext-proc API 查询重放数据启用router_replay后可在 ext-proc 处理链上通过只读 HTTP API查询重放记录。API 基路径为/api/v1/observability/replays见 router.go路由分发逻辑见 router_replay_api.go路径说明GET /api/v1/observability/replays重放记录列表支持分页与过滤GET /api/v1/observability/replays/{replay_id}单条记录详情GET /api/v1/observability/replays/aggregate聚合统计生命周期、成本、模型选择、决策/信号分布、Token 用量GET /api/v1/observability/replays/trajectory?session_id{id}将存储的 ToolTrace 步骤转换为扁平 OpenAI Chat Completions 消息列表GET /api/v1/observability/replays/dataset数据集导出接口列表查询参数列表接口parseRouterReplayListQueryrouter_replay_api.go支持limit每页条数默认 20最大 100offset分页偏移默认 0showDetails是否返回完整详情false时返回摘要记录ListSummaryRecord减小响应体积search按 request_id / recipe 模糊搜索recipe/decision按路由决策精确过滤model按所选模型或原始模型过滤SelectedModel/OriginalModelsession_id按会话过滤cache_statusall/cached/streamed。响应采用分页结构routerReplayListResponserouter_replay_api.go包含count、total、limit、offset、has_more、next_offset与data。聚合统计GET /api/v1/observability/replays/aggregate返回router_replay_aggregate.gorecord_count过滤后的记录数lifecycle按 completed / failed / aborted / in_progress / unknown 统计生命周期分布summary按币种聚合的基线成本、实际成本与节省额仅统计生命周期 completed 且成本为有限值的记录model_selectionTop-10 模型选择分布decision_distribution决策分布recipe:decision键signal_distribution信号类型分布keyword、embedding、domain、fact_check、user_feedback、reask、preference、language、context、complexitytoken_volume输入/输出/总 token 量token_breakdown按决策与所选模型拆分的 token 用量 Top-8。响应体大小保护所有重放 JSON 响应经createRouterReplayJSONResponse检查router_replay_api.go若 proto 编码后超过routerReplayMaxImmediateResponseMB 4MB返回 HTTP 413并提示减小分页或降低捕获的 body 字节数防止 ext-proc 消息超限。七、管理与权限重放查询接口同样受管理 API 鉴权保护。测试 route_router_replay_test.go 验证了viewer / operator / admin 三类角色令牌下重放管理路由要求鉴权且对 viewer 角色会脱敏响应负载request_body、response_body等字段被清洗避免只读查看者接触敏感捕获内容。此外router_replay与 PII 证据机制联动ReplayNeedsPIIEvidenceplugin_router_replay_support.go当全局默认或任一 decision 关闭capture_personal_data时现有的 PII 规则被标记为消费者运行时对未经验证的内容做保守省略。八、测试验证与最佳实践小结仓库为router_replay提供了成体系的测试覆盖可作为行为契约参考插件配置解析与默认值canonical_router_replay_test.go、router_replay_policy_test.gopkg/config启停与捕获策略router_replay_enablement_test.gopkg/extproc轨迹聚合与截断router_replay_trajectory_test.go、router_replay_aggregate_test.gopkg/extproc记录器与存储recorder_test.go、store/lifecycle_read_test.go、store/postgres_safety_evidence_test.gopkg/routerreplay脱敏行为redaction_test.gopkg/routerreplay/redaction。落地建议生产环境务必选择持久化后端memory后端在配置重载或重启后会丢数据仅适合本地调试生产请配置postgres或redis并设置ttl_seconds控制留存周期先全局收口再路由放行保持global.services.router_replay.enabled关闭或使用保守默认值仅在需要调试/审计的路由上以插件方式显式开启并把max_records、max_body_bytes、max_tool_trace_steps设置为符合该路由业务量的值敏感流量关闭响应体捕获对隐私敏感路由将capture_response_body置为false必要时用capture_personal_data: false触发 PII 保守省略Agent 路由务必设置轨迹上限长会话场景下设置max_tool_trace_steps建议沿用官方默认 100防止工具轨迹无界增长导致 OOM查询时善用过滤与摘要列表接口默认返回摘要记录配合recipe、decision、session_id、cache_status过滤可显著降低 ext-proc 响应体积避免触发 4MB 上限。关联文档与配置插件片段config/fragments/plugin/router-replay/debug.yaml完整 recipe 示例config/recipes/agent/config.yaml配置 Schemarouter-config-v0.3.schema.json插件配置结构plugin_config.go全局配置结构runtime_config.go默认值与生效逻辑plugin_router_replay_support.go运行时初始化与后端解析router_replay_setup.goRecorder 实现recorder.go查询 API 实现router_replay_api.go、router_replay_query.go聚合统计实现router_replay_aggregate.go赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 关键词路由Keyword Routing实战指南用显式规则实现可解释、可审计、亚毫秒级的智能路由semantic router 关键词路由Keyword Routing实战指南用显式规则实现可解释、可审计、亚毫秒级的智能路由 本指南基于 semant后端API网关模型推理服务AI Agentsemantic-router RAG 插件深度指南路由级检索注入与 Vela 神经重排实战semantic router RAG 插件深度指南路由级检索注入与 Vela 神经重排实战 导读 本指南以 semantic router 开源仓库中的 R后端API网关模型推理服务AI Agentsemantic-router Keyword Routing 实战指南用显式关键词与正则规则构建可审计的确定性路由semantic router Keyword Routing 实战指南用显式关键词与正则规则构建可审计的确定性路由 本指南围绕 semantic route后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
