Milvus怎么做常见问题排查手册

Milvus 怎么做常见问题排查手册

一 排查前置准备

先收集基础信息再定位问题避免盲目操作确认 Milvus 部署模式单机 docker k8s 或物理机记录 Milvus 版本客户端 sdk 版本操作系统信息获取基础运行状态包含服务进程日志资源指标整理业务相关信息查询语句写入参数集合 schema 数据量索引类型

常用工具 milvus-cli 命令行客户端做连接和基础测试 prometheus 加 grafana 查看监控指标 docker logs 或者 kubectl logs 查看容器日志 top iostat netstat 查看服务器 cpu 内存磁盘网络状态

二 服务无法启动类问题

服务进程启动失败查看 milvus 日志重点关注 etcd 连接端口占用文件权限磁盘空间不足 etcd 依赖异常检查 etcd 服务状态网络连通性 etcd 存储目录读写权限端口冲突确认 milvus 使用端口没有被其他程序占用修改配置更换端口磁盘空间不足清理磁盘预留足够空间数据目录需要预留额外余量配置文件错误核对 yaml 配置语法参数填写错误会直接启动失败

服务启动后自动退出内存不足系统 oom 杀死 milvus 进程查看系统 oom 日志调整内存分配依赖组件故障 etcd minio 不可用 milvus 依赖对象存储保存数据 minio 连接失败会反复重启数据目录损坏非正常关机导致元数据文件损坏必要时从备份恢复

三 连接访问失败

客户端连不上 Milvus 检查网络防火墙安全组开放 milvus 服务端口确认服务监听地址配置如果绑定 127.0.0.1 外部机器无法访问核对用户名密码 token 集群模式确认 proxy 节点正常运行 sdk 版本和服务版本不匹配大版本差异容易出现连接协议报错测试方式使用 milvus-cli 在客户端机器尝试连接判断是网络问题还是认证问题

连接成功但是超时网络延迟过高跨机房跨云场景检查带宽丢包服务负载过高 cpu 内存打满请求排队查询写入并发超过系统上限触发限流

四 写入插入数据异常

插入返回报错主键重复主键设置唯一时重复插入相同主键直接报错字段类型不匹配向量维度和集合定义维度不一致向量数值非法出现 nan 无穷大数值分区不存在检查分区名称拼写

插入速度慢批量插入单批次大小不合适过小会频繁提交开销大单批过大占用内存索引未构建不影响插入但是大量写入时资源抢占磁盘 io 压力高 minio 对象存储读写慢本地磁盘写入瓶颈并发写入线程太多触发内部限流

插入成功但是查询找不到数据数据写入后未刷新向量数据默认异步落盘需要执行 flush 设置了自动刷新等待自动刷新周期查询使用的分区和写入分区不一致时间分区场景查询时间范围设置错误

五 查询检索异常

检索返回结果为空向量维度不匹配查询向量维度和集合定义不一致数据没有 flush 数据还停留在内存没有加载到检索引擎索引未构建未建索引只能全量扫描检索参数设置错误过滤条件不合理 where 条件过滤掉全部数据

检索结果不准召回率低索引参数不合适 ivf 类索引聚类数量不匹配数据量查询 topk 设置过大超过索引支持上限向量归一化问题使用余弦相似度向量没有归一化数据分布变化新增大量数据没有重新构建索引检索参数 ef 过小 hnsw 索引 ef 值太低召回下降

查询耗时很长没有建立索引向量检索触发全量扫描 topk 数值过大需要扫描更多向量过滤条件复杂带大量计算或者非索引字段过滤并发查询请求多系统资源耗尽

查询报错内存超限单次查询 topk 过大加载过多向量数据并发查询数量太多内存占用叠加集合数据量大内存资源不足需要开启磁盘索引或者扩容内存

六 索引相关问题

创建索引失败向量字段类型错误维度填写错误数据量太少 ivf 索引需要足够样本聚类数据量不足无法建索引磁盘空间不足建索引会生成临时文件占用存储空间资源不足建索引消耗大量 cpu 内存资源高负载下创建失败

索引丢失集合被删除或者分区删除异常重启索引文件损坏需要重新构建索引 minio 对象存储权限问题索引文件无法读取

七 资源与性能问题

cpu 持续高占用大量并发查询或者频繁构建索引频繁 flush 操作小批量持续写入触发多次落盘查询没有走索引全表向量扫描后台 compaction 合并任务持续运行

内存占用持续上涨大量集合或者分区加载到内存批量写入缓存数据未 flush compaction 任务占用内存大客户端连接过多会话缓存堆积

磁盘占用快速增长原始向量数据加上索引文件双重占用 compaction 产生大量临时文件合并完成后才清理日志级别过高日志文件持续膨胀

网络带宽打满大批量导入数据上传 minio 大规模向量查询结果传输返回海量数据

八 日志查看关键关键字

搜索日志关键词快速定位 error 错误信息 warn 警告信息 timeout 请求超时 oom 内存溢出 connection refused 连接拒绝 invalid dimension 向量维度非法 duplicate primary key 主键重复

九 通用排查步骤标准化流程

第一步确认业务现象记录报错信息复现步骤第二步检查 milvus 服务状态确认所有节点 proxy querynode datanode etcd minio 正常运行第三步查看监控 cpu 内存磁盘 io 网络队列第四步查看 milvus 服务日志定位报错关键词第五步简化测试用例使用小数据简单 sql 复现问题排除业务代码干扰第六步隔离测试单独测试写入单独测试查询定位模块第七步查阅 milvus 官方文档版本适配说明第八步无法解决收集日志指标版本信息提交 issue

十 常见误区

直接重启服务当做万能方案重启可以临时解决部分内存问题但是掩盖根因日志丢失不利于排查忽略版本差异不同版本参数行为不一样不要跨版本套用方案只看业务报错不看 milvus 底层日志业务 sdk 报错信息有限核心原因在服务端日志不做 flush 直接查询新写入数据误以为数据丢失索引建好之后不维护新增大量数据不重建索引导致召回持续下降

十一 应急处理清单

服务响应缓慢降低业务并发暂停非核心任务内存过高减少同时加载的集合分区缩小并发查询磁盘满停止写入清理过期日志无用备份连接数爆满限制客户端连接数量索引异常删除损坏索引重新构建索引