后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本篇技术指南聚焦 Semantic Routervllm-project/semantic-router的可观测性体系围绕其官方教程文档 website/versioned_docs/version-v0.1/tutorials/observability/metrics.md 展开。全文以 Router 原生 Prometheus 指标为核心覆盖本地宿主机模式、Docker Compose 模式、Kubernetes 模式三种部署形态的采集链路搭建并深入讲解窗口化模型指标Windowed Model Metrics的配置、指标语义与查询方法同时结合 src/semantic-router/pkg/observability/metrics/metrics.go 等源码级实现帮助读者掌握从「采集端点配置 → 指标查询 → 告警规则」的完整实战能力。1. 指标端点总览Router 可观测性的三个入口Semantic Router 在进程内原生暴露 Prometheus 格式指标同时提供 HTTP 健康检查端点若部署了 Envoy 还可采集其自身统计信息。三个端点的关系如下表组件端点说明Router metrics:9190/metricsPrometheus 文本格式端口由命令行 flag--metrics-port控制Router health:8080/healthHTTP readiness / liveness 探针Envoy metrics可选:19000/stats/prometheus仅在启用 Envoy 时存在其中 Router 的 metrics 端点并不依赖配置文件而是由运行时启动参数直接决定。源码层面runtime_bootstrap.go 中定义了--metrics-portflag默认值即为9190metricsServerEnabled()在cfg.Observability.Metrics.Enabled未显式设置时默认开启指标服务runtime_bootstrap.go。启动逻辑通过net.Listen(tcp, :port)绑定端口并以 metrics.NewServeMux() 作为 HTTP Handler因此只要 Router 进程存活curl localhost:9190/metrics即可直接拿到全部指标。文档约定观测相关配置统一放置在tools/observability/目录本地/Docker 模式Kubernetes 模式则对应deploy/kubernetes/observability/两者共享同一套 Grafana 面板定义llm-router-dashboard.json。在 v0.1 教程所处的仓库基线中完整目录包括prometheus.yaml—— Prometheus 采集配置grafana-datasource.yaml—— Grafana 数据源配置grafana-dashboard.yaml—— 面板 provision 配置llm-router-dashboard.json—— 面板定义JSON提示当前仓库版本已将 Kubernetes 观测栈独立成 Kustomize 包见第 4 节面板与告警规则也随版本演进有所扩充但端点与核心指标语义保持一致。2. 本地模式Router 运行在宿主机本地模式适合开发调试Router 以原生进程运行Prometheus 与 Grafana 以 Docker 容器提供观测能力。2.1 快速启动# 启动 Router宿主机进程 make run-router # 启动观测栈Prometheus Grafana 容器 make o11y-local启动后的访问入口Prometheushttp://localhost:9090Grafanahttp://localhost:3000默认账号admin/admin验证采集目标是否生效# 确认 Prometheus 正在抓取 localhost:9190 open http://localhost:9090/targets停止观测栈make stop-observability2.2 配置文件说明所有配置均位于tools/observability/prometheus.yaml—— 通过环境变量ROUTER_TARGET指定抓取目标默认值为localhost:9190grafana-datasource.yaml—— Grafana 数据源指向localhost:9090grafana-dashboard.yaml—— 面板自动 provisioning 配置llm-router-dashboard.json—— 面板定义本身2.3 常见故障排查问题解决方式Target 显示 DOWN先启动 Routermake run-router无指标数据主动产生流量通过 Router 发请求并检查:9190/metrics是否有输出端口冲突更换端口或停止占用端口的进程值得注意Router 的 health 端点与 metrics 端点相互独立。startMetricsServerIfEnabled()中如果端口已被占用指标服务会记录metrics_server_failed事件并跳过启动而不会中止 Router 主流程runtime_bootstrap.go因此「端口冲突」通常表现为 metrics 端点不可达而非进程崩溃。3. Docker Compose 模式全容器化观测栈当 Router 本身也容器化部署时观测组件与 Router 共享同一容器网络抓取目标从localhost变为服务名。3.1 快速启动# 启动完整栈包含观测组件 docker compose -f deploy/docker-compose/docker-compose.yml up --build # 或者启用 testing profile docker compose -f deploy/docker-compose/docker-compose.yml --profile testing up --build访问入口与本地模式一致Prometheushttp://localhost:9090Grafanahttp://localhost:3000默认账号admin/admin预期的采集目标semantic-router:9190—— Router 指标envoy-proxy:19000—— Envoy 统计信息可选3.2 与本地模式的差异配置仍复用tools/observability/下的文件但环境变量需要指向容器服务名ROUTER_TARGETsemantic-router:9190PROMETHEUS_URLprometheus:9090使用semantic-networkbridge 网络互通4. Kubernetes 模式生产级观测栈Kubernetes 模式提供面向生产环境的 Prometheus Grafana 部署运行在命名空间vllm-semantic-router-system中。仓库中的完整实现位于 deploy/kubernetes/observability/由 Kustomize 组织包含四类组件组件用途位置Prometheus抓取 Router 指标15 天保留期deploy/kubernetes/observability/prometheus/Grafana面板可视化deploy/kubernetes/observability/grafana/Ingress可选的外部访问入口deploy/kubernetes/observability/ingress.yamlDashboardRouter 配置与工具数据展示deploy/kubernetes/observability/dashboard/4.1 部署# 渲染并应用全部 manifest kubectl apply -k deploy/kubernetes/observability/ # 验证 Pod 状态 kubectl get pods -n vllm-semantic-router-system官方文档提醒仓库内自带的值是「便于检查」的开发示例而非安全默认值grafana/secret.yaml中写死admin/admin、ingress.yaml包含示例域名与 TLS Secret 名称。正式部署前应先执行kubectl kustomize deploy/kubernetes/observability/渲染检查再通过 overlay 替换凭据、存储类与资源配额。一个关键前提是Router 的 metrics Service 必须存在于同一命名空间且暴露名为metrics的端口kubectl get service semantic-router-metrics \ --namespace vllm-semantic-router-system4.2 访问方式端口转发无 Ingress 时kubectl port-forward svc/prometheus 9090:9090 -n vllm-semantic-router-system kubectl port-forward svc/grafana 3000:3000 -n vllm-semantic-router-systemIngress按需修改ingress.yaml中的域名与 TLS 配置。若通过外部代理转发内部 Host 访问 Grafana LiveWebSocket还需在 Grafana 容器上设置GF_LIVE_ALLOWED_ORIGINS为浏览器面向 Dashboard 的真实 Origin不要写成*详见 deploy/kubernetes/observability/README.md。4.3 关键配置Prometheus 使用 Kubernetes 服务发现Kubernetes SD仓库中 prometheus/configmap.yaml 的实际实现比文档示例更完整——通过relabel_configs只保留服务名为semantic-router-metrics、端口名为metrics的 endpointscrape_configs: - job_name: semantic-router kubernetes_sd_configs: - role: endpoints namespaces: names: [vllm-semantic-router-system] relabel_configs: - source_labels: [__meta_kubernetes_service_name] regex: semantic-router-metrics action: keep - source_labels: [__meta_kubernetes_endpoint_port_name] regex: metricsbegin▁of▁sentence r action: keep该 ConfigMap 同时设置了全局scrape_interval: 15s、evaluation_interval: 15s并加载rule_files中的告警规则。Grafana 数据源与面板 provisioninggrafana/configmap-provisioning.yaml 以datasources.yaml声明默认数据源http://prometheus:9090timeInterval: 15s以dashboards.yaml声明文件型 provider从/var/lib/grafana-dashboards自动加载面板面板文件由configmap-dashboard.yaml注入。Grafana 凭据生产环境务必替换kubectl create secret generic grafana-admin \ --namespace vllm-semantic-router-system \ --from-literaladmin-useradmin \ --from-literaladmin-passwordyour-password更推荐的做法是先用--dry-runclient -o yaml生成 Secret 再 apply避免把密码写进提交的 overlaykubectl create secret generic grafana-admin \ --namespace vllm-semantic-router-system \ --from-literaladmin-usermonitor \ --from-literaladmin-password$GRAFANA_ADMIN_PASSWORD \ --dry-runclient -o yaml | kubectl apply -f - kubectl rollout restart deployment/grafana \ --namespace vllm-semantic-router-system4.4 验证数据链路官方 K8s 部署文档deploy/kubernetes/observability/README.md给出了端到端验证顺序打开 PrometheusStatus Targets确认semantic-routerjob 为 UP通过 Envoy 发送推理流量查询 Router 实际输出的指标如llm_request_outcomes_total{traffic_kindinference}打开 Grafana 已 provisioning 的 Router 面板确认时间范围覆盖流量时段。若 target 缺失先检查服务发现而非面板kubectl get endpoints semantic-router-metrics \ --namespace vllm-semantic-router-system kubectl logs deployment/prometheus \ --namespace vllm-semantic-router-system5. 核心指标Router 原生导出的 Prometheus 指标Semantic Router 的核心指标全部在 src/semantic-router/pkg/observability/metrics/metrics.go 中通过promauto.NewCounterVec/NewHistogramVec注册。教程文档列出四个基础指标指标类型描述llm_category_classifications_countcounter分类category classification次数llm_model_completion_tokens_totalcounter各模型的输出 token 数llm_model_routing_modifications_totalcounter模型路由变更次数llm_model_completion_latency_secondshistogram模型完成响应耗时示例查询# 输出 token 速率每 5 分钟 rate(llm_model_completion_tokens_total[5m]) # 完成耗时的 P95 分位数 histogram_quantile(0.95, rate(llm_model_completion_latency_seconds_bucket[5m]))5.1 指标背后的源码实现这组指标在源码中均有对应注册与记录函数可作为排障时「指标为何缺失」的定位依据llm_model_completion_tokens_total注册于 metrics.go由RecordModelTokensDetailed(model, promptTokens, completionTokens)在累加llm_model_tokens_total与llm_model_prompt_tokens_total的同时记录metrics.gollm_model_routing_modifications_total注册于 metrics.go带source_model与target_model两个 label由RecordModelRouting(sourceModel, targetModel)在源模型与目标模型不同时才Inc()metrics.go因此它精确刻画了「路由决策真正改写目标模型」的次数llm_model_completion_latency_seconds注册于 metrics.gobucket 区间为0.005s ~ 1800s的有限序列。源码注释特别说明由于 completion 可能包含长流式 / reasoning 响应有限桶上界必须超出维护的 30 秒 P95 告警阈值llm_category_classifications_count对应分类管线的计数指标。同文件还注册了llm_classification_confidence分类置信度分布与llm_entropy_valuesShannon 熵分布等分类质量指标说明分类观测并不止于次数还包括置信度与不确定性维度metrics.go。5.2 值得关注的扩展指标除教程列出的四个基础指标外同文件还导出了模型成本、请求错误、会话级 token 等指标这些对生产运维同样关键指标类型说明llm_model_requests_totalcounter每个模型的请求总数label:modelllm_request_errors_totalcounter按model与reason分类的错误计数reason 会归一化为timeout、upstream_5xx、upstream_4xx等llm_model_cost_totalcounter按model与currency统计的成本llm_model_prompt_tokens_totalcounter各模型输入 token 数llm_prompt_tokens_per_request/llm_completion_tokens_per_requesthistogram单请求 token 数分布llm_session_turn_prompt_tokens/llm_session_turn_completion_tokenshistogram会话级每轮 token 数label:model、domainllm_model_first_response_observation_secondshistogram首个流式 chunk / 非流式响应头到达耗时llm_model_response_duration_per_output_token_secondshistogram完整响应耗时 ÷ 输出 token 数llm_model_routing_latency_secondshistogram路由决策本身耗时llm_unverified_factual_responses_totalcounter缺少工具上下文无法核验的事实性响应计数记录错误时RecordRequestError()还会把deadline_exceeded、upstream_500/502/503/504等原始值归一化为timeout、upstream_5xx便于告警规则聚合metrics.go。5.3 预置告警规则30 秒 P95 的真实出处教程中的histogram_quantile(0.95, ...)查询在 K8s 观测栈中被固化为告警规则。仓库 prometheus/rules.yaml 定义了HighCompletionLatencyP95等 7 条规则其中 completion 延迟告警正是histogram_quantile(0.95, sum(rate(llm_model_completion_latency_seconds_bucket[5m])) by (le)) 30 for: 10m其余规则覆盖请求错误率 5%HighRequestErrorRate、首响应 P95 5s、每输出 token 时长 P95 250ms、路由耗时 P95 100ms、单模型 in-flight 请求 50、缓存命中率 20%。这些规则均带for持续条件与dashboard_panel注解可直接作为生产基线并路由到 Alertmanager。与之对应的契约测试位于 completion_latency_contract_test.go用正则校验告警表达式形态防止查询被误改。6. 窗口化模型指标Windowed Model Metrics与负载均衡窗口化指标是面向模型性能追踪的增强能力尤其适合 Kubernetes 环境——该环境下「模型选择」与「下游 endpoint 负载均衡」是分离的职责Router 需要输出足够细粒度的窗口指标供下游决策使用。6.1 配置开启在config.yaml的observability.metrics.windowed_metrics节点开启observability: metrics: windowed_metrics: enabled: true time_windows: [1m, 5m, 15m, 1h, 24h] update_interval: 10s model_metrics: true queue_depth_estimation: true max_models: 100字段说明enabled总开关关闭时RecordRequest直接忽略windowed_metrics.gotime_windows时间窗口列表缺省使用DefaultTimeWindows [1m,5m,15m,1h,24h]每个窗口独立计算统计量update_interval后台计算周期默认10sWindowedMetricsManager.Start()以该间隔驱动 ticker 调用computeWindowedMetrics()windowed_metrics.gomax_models最多追踪的模型数默认100达到上限后新模型请求不再入缓冲区windowed_metrics.gomodel_metrics/queue_depth_estimation教程文档列出的配置开关。需要说明的是当前源码的指标导出以「已观测完成的响应」为统计对象——源码注释明确WindowedMetricsManager只汇总每个模型最多 10,000 条已完成的响应并非尝试次数、provider 失败、利用率或队列深度的完整普查windowed_metrics.go。启动时InitializeWindowedMetrics()会注册全部窗口化 Gauge 并创建后台管理 goroutine若初始化失败Router 仅记录windowed_metrics_init_failed警告而不崩溃runtime_bootstrap.go。6.2 模型级指标清单指标类型标签描述llm_model_latency_windowed_secondsgaugemodel, time_window窗口内平均延迟llm_model_requests_windowed_totalgaugemodel, time_window窗口内请求数实际为保留在窗口内的已完成响应数llm_model_tokens_windowed_totalgaugemodel, token_type, time_window窗口内 token 吞吐token_type 取值prompt/completionllm_model_utilization_percentagegaugemodel, time_window预估利用率百分比llm_model_queue_depth_estimatedgaugemodel当前预估队列深度llm_model_error_rate_windowedgaugemodel, time_window窗口内错误率llm_model_latency_p50_windowed_secondsgaugemodel, time_window窗口内 P50 延迟llm_model_latency_p95_windowed_secondsgaugemodel, time_window窗口内 P95 延迟llm_model_latency_p99_windowed_secondsgaugemodel, time_window窗口内 P99 延迟注意版本差异llm_model_utilization_percentage、llm_model_queue_depth_estimated、llm_model_error_rate_windowed三个指标出现在教程文档中但当前仓库源码对应的 windowed_metrics_test.go 已将其标记为「退役且不再导出的指标族」测试断言这些 family 不应存在。若你在较新版本中查询不到这三个指标请以llm_model_latency_*、llm_model_requests_windowed_total、llm_model_tokens_windowed_total作为负载均衡与容量规划的主要依据。6.3 示例查询# 某模型最近 5 分钟的平均延迟 llm_model_latency_windowed_seconds{modelgpt-4, time_window5m} # 跨模型对比 15 分钟窗口 P95 延迟 llm_model_latency_p95_windowed_seconds{time_window15m} # 各模型 1 小时窗口内的 completion token 吞吐 llm_model_tokens_windowed_total{token_typecompletion, time_window1h} # 负载均衡决策所需的当前队列深度 llm_model_queue_depth_estimated{modelgpt-4} # 错误率监控5 分钟窗口错误率超过 5% llm_model_error_rate_windowed{time_window5m} 0.056.4 实现原理时间窗口与百分位计算窗口化指标的核心数据结构是每个模型一个的时间型环形缓冲区RequestRingBufferNewRequestRingBuffer(capacity)创建容量固定的环形数组Add()在满时覆盖最旧数据windowed_metrics.go每个RequestData记录时间戳、模型、延迟、prompt/completion token 数windowed_metrics.go计算周期到达时computeWindowedMetrics()对每个模型 × 每个时间窗口调用GetDataSince(now-window)过滤出窗口内数据汇总平均延迟、token 总量并通过computePercentile()线性插值计算 P50/P95/P99windowed_metrics.go空窗口会把请求数置 0、删除延迟类指标避免把过期样本当作有效测量这一点在 TestWindowedCompletedSamplesExpireWithoutStaleLatency 中有专门测试验证。这一设计意味着窗口化指标以「gauge 前台后台周期计算」替代「counter/histogram Prometheus 端 rate 聚合」从而允许外部负载均衡器在不依赖 PromQL 时间范围参数的前提下直接读取 Router 已算好的窗口统计值。6.5 典型使用场景负载均衡结合队列深度与延迟指标把请求路由到负载较轻的模型性能监控跟踪各时间窗口下的 P95/P99 延迟趋势容量规划观察利用率百分比判断何时扩容模型告警针对窗口内错误率或延迟尖峰设置阈值告警。7. 汇总排查清单问题检查项修复方式Target DOWNPrometheus /targets 页面确认 Router 在运行且暴露:9190/metricsK8s 下另查semantic-router-metricsService 的 endpoints 与端口名metrics无指标流量是否经过 Router通过 Router 发送请求分类/推理流量后再查询面板为空Grafana 数据源配置检查 Prometheus URL 是否可达、指标名是否拼写正确、时间范围是否覆盖流量PVC PendingK8skubectl describe pvc检查存储类是否可用Ingress 404 / TLS 报错Ingress class、hostname、DNS按需 patch hostname 与 TLS SecretGrafana Live 面板加载失败GF_LIVE_ALLOWED_ORIGINS在 Grafana 容器环境变量中配置浏览器面向 Dashboard 的真实 Origin移除整个 K8s 观测示例kubectl delete -k deploy/kubernetes/observability/注意PVC 的删除与保留行为取决于集群与存储类移除前先确认是否需要保留数据。8. 小结Semantic Router 的观测体系是一套「Router 原生指标 三种部署形态 窗口化模型指标」的组合--metrics-port控制的:9190/metrics是数据源头本地与 Docker Compose 模式通过tools/observability/下的配置快速拉起 Prometheus/GrafanaKubernetes 模式以deploy/kubernetes/observability/Kustomize 包提供生产级服务发现、15 天保留期与 7 条预置告警规则窗口化指标则在 Router 进程内按时间窗口预先计算平均/分位延迟与 token 吞吐供外部负载均衡与容量规划直接消费。配合 metrics.go 与 windowed_metrics.go 的源码实现读者可以精确掌握每条指标的触发条件、标签语义与统计口径进而搭建出贴合自身业务的可观测与告警体系。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Ray 集群指标采集与监控基于 Prometheus 与 Grafana 的完整实践指南Ray 集群指标采集与监控基于 Prometheus 与 Grafana 的完整实践指南 导读 本文以 Ray 官方文档 doc/source/cluste人工智能分布式训练强化学习任务调度模型推理服务后端Semantic Router 指标与监控实战Prometheus Grafana 可观测性全指南Semantic Router 指标与监控实战Prometheus Grafana 可观测性全指南 Semantic RoutervLLM Projec后端API网关模型推理服务AI AgentCortex 集群监控指南基于 Prometheus 与 Grafana 的指标采集、可视化与导出实践Cortex 集群监控指南基于 Prometheus 与 Grafana 的指标采集、可视化与导出实践 Cortex 在生产集群内默认部署了 Promethe人工智能模型推理服务后端云原生MLOps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
