bge-large-zh-v1.5实操手册：Prometheus+Grafana监控Embedding服务指标-平芜编程栈

bge-large-zh-v1.5实操手册：Prometheus+Grafana监控Embedding服务指标

1. bge-large-zh-v1.5模型基础认知

bge-large-zh-v1.5是一款专为中文语义理解优化的嵌入模型，它不是简单地把文字变成数字，而是把一句话、一段话甚至一篇短文，转化成一组能代表其真实含义的数字向量。你可以把它想象成给每段中文“打标签”的高手——不是用几个关键词，而是用一串几百维的数字，精准捕捉语气、逻辑关系、专业领域倾向等深层信息。

这个模型在实际使用中表现出几个特别实用的特点：

高区分度向量输出：生成的向量维度高达1024，这意味着它能更精细地区分“苹果手机”和“苹果水果”这类容易混淆的表达，对搜索、推荐、去重等任务帮助很大
支持合理长度输入：能稳定处理最长512个token的文本，覆盖绝大多数标题、摘要、商品描述、客服对话等常见场景，不用反复切分再拼接
通用+垂直兼顾：既能在新闻、百科等通用语料上表现稳健，也能在金融、法律、医疗等专业文档中保持不错的语义一致性，省去了频繁换模型的麻烦

但这些能力背后，是实实在在的资源消耗。模型加载需要显存，每次推理要占用GPU计算周期，高并发请求下还可能遇到响应延迟、OOM（内存溢出）或队列堆积。所以，光把模型跑起来远远不够——你得知道它“现在怎么样”，而这就离不开一套看得见、摸得着的监控体系。

2. 模型服务部署与基础验证

我们采用sglang框架部署bge-large-zh-v1.5，它提供了轻量、高效、兼容OpenAI API的推理服务接口。整个服务以HTTP方式暴露在本地30000端口，对外提供标准的/v1/embeddings路径，无需修改业务代码即可接入。

2.1 进入工作目录并确认环境状态

在服务器终端中执行以下命令，进入预设的工作空间：

cd /root/workspace

这一步看似简单，但很关键——所有日志、配置、临时文件都集中在此目录，统一管理能避免后续排查时“找不到文件”的尴尬。

2.2 查看启动日志确认服务就绪

运行以下命令查看sglang服务的启动日志：

cat sglang.log

如果看到类似这样的关键行，说明模型已成功加载并监听请求：

INFO: Uvicorn running on http://0.0.0.0:30000 (Press CTRL+C to quit) INFO: Loaded model 'bge-large-zh-v1.5' with 1024-dim embeddings INFO: Server started successfully. Ready to serve requests.

注意：仅靠“进程在运行”不能代表服务可用。必须看到明确的Loaded model和Ready to serve提示，才说明模型权重已加载进显存、tokenizer已初始化完成、HTTP服务已绑定端口。如果日志卡在Loading tokenizer...或报CUDA out of memory，则需检查GPU显存是否充足（建议≥24GB）或降低--tp张量并行数。

2.3 使用Jupyter快速调用验证

打开Jupyter Notebook（或直接在Python脚本中），运行以下代码片段，发起一次最简embedding请求：

import openai client = openai.Client( base_url="http://localhost:30000/v1", api_key="EMPTY" ) response = client.embeddings.create( model="bge-large-zh-v1.5", input="How are you today" ) print("Embedding维度:", len(response.data[0].embedding)) print("响应耗时（ms）:", response.usage.prompt_tokens)

正常返回结果中，len(response.data[0].embedding)应为1024，response.usage会显示token计数（此处为4）。这不仅验证了API通路，也确认了模型输出格式符合预期——后续所有监控指标，都要基于这种标准响应结构来提取。

3. Prometheus监控体系搭建

光有服务还不够，我们要让它的健康状态“自己说话”。Prometheus是目前最主流的时序数据库+监控抓取系统，它不依赖客户端上报，而是主动“拉取”（pull）目标服务暴露的指标数据。为了让sglang服务支持被Prometheus采集，我们需要两步：启用内置metrics端点 + 配置Prometheus抓取规则。

3.1 启用sglang的/metrics端点

sglang从v0.3.5起原生支持OpenMetrics格式的指标暴露。启动服务时，只需添加--enable-metrics参数：

sglang.launch_server \ --model-path /models/bge-large-zh-v1.5 \ --host 0.0.0.0 \ --port 30000 \ --enable-metrics \ --metrics-port 30001

该命令会在http://localhost:30001/metrics暴露一个纯文本格式的指标列表，例如：

# HELP sglang_request_count_total Total number of requests received # TYPE sglang_request_count_total counter sglang_request_count_total{model="bge-large-zh-v1.5",status="success"} 127 sglang_request_count_total{model="bge-large-zh-v1.5",status="error"} 3 # HELP sglang_request_latency_seconds Latency of requests in seconds # TYPE sglang_request_latency_seconds histogram sglang_request_latency_seconds_bucket{model="bge-large-zh-v1.5",le="0.1"} 89 sglang_request_latency_seconds_bucket{model="bge-large-zh-v1.5",le="0.2"} 112 ...

这些指标覆盖了请求总量、成功率、延迟分布、token吞吐量、GPU显存占用等核心维度，全部由sglang自动统计，无需额外埋点。

3.2 配置Prometheus抓取任务

编辑Prometheus配置文件prometheus.yml，在scrape_configs下新增一项：

- job_name: 'sglang-embedding' static_configs: - targets: ['localhost:30001'] metrics_path: '/metrics' scheme: 'http' scrape_interval: 15s scrape_timeout: 10s

保存后重启Prometheus：

sudo systemctl restart prometheus

稍等15秒，访问http://localhost:9090/targets，确认sglang-embedding状态为UP，表示抓取链路已打通。

3.3 关键指标解读与验证查询

在Prometheus Web界面（http://localhost:9090/graph）中，可直接输入以下查询语句验证数据是否正常：

实时请求速率（过去1分钟平均每秒请求数）：

rate(sglang_request_count_total{model="bge-large-zh-v1.5",status="success"}[1m])

P95请求延迟（95%的请求耗时不超过多少秒）：

histogram_quantile(0.95, rate(sglang_request_latency_seconds_bucket{model="bge-large-zh-v1.5"}[5m]))

GPU显存使用率（需nvidia-smi exporter配合，此处为补充说明）：

100 * (nvidia_smi_memory_total_bytes{gpu="0"} - nvidia_smi_memory_free_bytes{gpu="0"}) / nvidia_smi_memory_total_bytes{gpu="0"}

首次看到图表曲线跳动，意味着监控数据流已建立——这是构建可视化看板的第一块基石。

4. Grafana看板定制与实战告警

Prometheus负责“收集数据”，Grafana负责“讲好故事”。我们将围绕Embedding服务的核心诉求，构建一个聚焦性能、稳定性与资源的实战看板。

4.1 创建Embedding服务专属看板

登录Grafana（默认http://localhost:3000），点击左侧+→Dashboard→Add new panel。为每个关键维度添加独立面板：

顶部总览区：放置3个大数字卡片（Big Number）
- 当前QPS（每秒请求数）：rate(sglang_request_count_total{model="bge-large-zh-v1.5",status="success"}[1m])
- 错误率（%）：100 * rate(sglang_request_count_total{model="bge-large-zh-v1.5",status="error"}[5m]) / rate(sglang_request_count_total{model="bge-large-zh-v1.5"}[5m])
- 平均延迟（ms）：1000 * avg(rate(sglang_request_latency_seconds_sum{model="bge-large-zh-v1.5"}[5m])) by (model) / avg(rate(sglang_request_latency_seconds_count{model="bge-large-zh-v1.5"}[5m])) by (model)
中间趋势图区：2×2网格布局
- 左上：请求量热力图（按小时/天维度，观察业务波峰）
- 右上：延迟分布直方图（对比P50/P90/P99，识别长尾问题）
- 左下：GPU显存使用率折线图（关联请求量，判断是否需扩容）
- 右下：错误类型堆叠图（区分context_length_exceeded、cuda_oom、timeout等）

所有面板设置Refresh every 15s，确保数据实时刷新。

4.2 设置实用告警规则

在Grafana中创建Alerting规则，避免“等出事才看见”。以下是3条高价值告警：

高延迟告警（影响用户体验）
当P95延迟 > 1.2秒且持续2分钟→ 触发通知，排查GPU负载或模型batch size是否过大
高错误率告警（预示服务异常）
当错误率 > 5%且持续1分钟→ 触发通知，检查日志中是否有CUDA out of memory或token limit exceeded
零请求告警（服务可能宕机）
当QPS = 0且持续5分钟→ 触发通知，立即检查sglang进程与端口监听状态

告警渠道可配置邮件、企业微信或钉钉机器人，确保第一时间响应。

4.3 看板使用技巧：从“看数据”到“做决策”

一个优秀的监控看板，不只是仪表盘，更是运维决策的依据：

定位慢请求：当延迟突增时，下钻查看sglang_request_latency_seconds_bucket各分位数值变化，若le="0.5"桶增长而le="1.0"不变，说明大部分请求仍在1秒内，少数超长请求拖累P95，应检查输入文本长度分布
评估扩容时机：观察GPU显存使用率与QPS曲线的相关性。若显存长期>90%且QPS上升，说明已逼近瓶颈；若显存<70%但延迟升高，则可能是CPU解码或网络IO成为新瓶颈
验证优化效果：调整sglang启动参数（如--max-num-seqs 256）后，对比优化前后P95延迟与错误率，用数据证明改动价值，而非凭感觉

5. 监控之外：让Embedding服务真正“稳得住、扛得久”

监控是眼睛，但让服务长久健康，还需要几项关键实践：

输入预处理标准化：在调用前截断超长文本（>512 token）、过滤控制字符、统一编码。避免因脏数据触发模型内部异常，这类错误不会体现在status="error"中，却会显著拉低成功率
客户端重试与降级：在业务代码中实现指数退避重试（最多2次），对非核心场景（如搜索联想）可配置fallback到更轻量的bge-small-zh模型，保障主流程可用性
定期模型健康检查：每周用固定测试集（含100条典型query）批量调用，计算平均cosine相似度波动。若下降>3%，需重新校验模型文件完整性或检查CUDA版本兼容性
日志结构化归档：将sglang.log通过filebeat推送到ELK，设置level: ERROR告警，捕获那些未被metrics覆盖的底层异常（如CUDA驱动崩溃、磁盘满）

这些动作不产生监控图表，却是服务可靠性的真正护城河。