麻瓜教程

Appearance

常见问题与故障排查 ​

连接问题 ​

无法连接到 Milvus 服务器 ​

症状:

MilvusException: (code=2, message=Fail connecting to server on localhost:19530)

排查步骤:

  1. 检查服务状态
bash
# 检查 Docker 容器
docker ps | grep milvus

# 查看容器日志
docker logs milvus-standalone
  1. 检查端口连通性
bash
# 测试端口
telnet localhost 19530

# 或使用 nc
nc -zv localhost 19530
  1. 检查防火墙设置
bash
# Linux
sudo iptables -L | grep 19530

# 或检查 firewalld
sudo firewall-cmd --list-ports

解决方案:

python
# 增加连接超时时间
from pymilvus import connections

connections.connect(
    alias="default",
    host="localhost",
    port="19530",
    timeout=30  # 增加超时时间
)

认证失败 ​

症状:

MilvusException: (code=5, message=authentication failed)

解决方案:

python
# 使用正确的用户名和密码
connections.connect(
    alias="default",
    host="localhost",
    port="19530",
    user="root",           # 默认用户名
    password="Milvus"      # 默认密码
)

数据操作问题 ​

插入数据失败 ​

症状:

MilvusException: (code=1, message=field ... type mismatch)

常见原因及解决方案:

  1. 数据类型不匹配
python
# 错误示例
wrong_data = {
    "id": "1",  # 错误：字符串而非整数
    "vector": [0.1, 0.2, ...]
}

# 正确示例
correct_data = {
    "id": 1,    # 正确：整数
    "vector": [0.1, 0.2, ...]
}
  1. 向量维度不匹配
python
# 检查向量维度
collection = Collection("my_collection")
schema = collection.schema

for field in schema.fields:
    if field.dtype == DataType.FLOAT_VECTOR:
        print(f"向量维度: {field.params['dim']}")

# 确保插入数据的维度一致
vector = [0.1] * 128  # 确保是 128 维
  1. 字符串长度超限
python
# 检查字段长度限制
# 如果 max_length=256，字符串长度不能超过 256
title = "短标题"  # 确保长度在限制内

查询无结果 ​

排查步骤:

python
from pymilvus import Collection

collection = Collection("my_collection")

# 1. 检查集合是否已加载
print(f"集合已加载: {collection.is_loaded}")

if not collection.is_loaded:
    collection.load()

# 2. 检查数据是否存在
print(f"实体数量: {collection.num_entities}")

# 3. 简单查询测试
results = collection.query(
    expr="",
    output_fields=["id"],
    limit=5
)
print(f"查询结果: {results}")

# 4. 检查表达式语法
try:
    results = collection.query(
        expr="id > 0",  # 测试简单表达式
        output_fields=["id"],
        limit=5
    )
except Exception as e:
    print(f"查询错误: {e}")

搜索问题 ​

搜索结果不准确 ​

可能原因:

  1. 索引参数不合适
python
# 检查当前索引
index = collection.index("vector_field")
print(f"当前索引: {index.params}")

# 优化搜索参数
search_params = {
    "metric_type": "L2",
    "params": {
        "nprobe": 128,    # 增加搜索范围
        "ef": 256         # HNSW 索引参数
    }
}
  1. 未创建索引
python
# 检查索引是否存在
indexes = collection.indexes
if not indexes:
    print("警告：集合没有创建索引")
    
    # 创建索引
    index_params = {
        "index_type": "IVF_FLAT",
        "metric_type": "L2",
        "params": {"nlist": 128}
    }
    collection.create_index("vector_field", index_params)
  1. 数据未归一化
python
import numpy as np

# 归一化向量
def normalize_vector(vector):
    norm = np.linalg.norm(vector)
    if norm > 0:
        return vector / norm
    return vector

# 插入前归一化
normalized_vector = normalize_vector(raw_vector)

搜索速度慢 ​

优化建议:

  1. 使用合适的索引类型
python
# 小规模数据（< 100万）
index_params = {
    "index_type": "IVF_FLAT",
    "metric_type": "L2",
    "params": {"nlist": 128}
}

# 大规模数据（> 1000万）
index_params = {
    "index_type": "HNSW",
    "metric_type": "L2",
    "params": {"M": 16, "efConstruction": 200}
}
  1. 批量搜索
python
# 批量搜索比单条搜索更高效
batch_results = collection.search(
    data=[vector1, vector2, vector3, ...],  # 批量查询向量
    anns_field="vector",
    param=search_params,
    limit=10
)
  1. 使用分区
python
# 只在相关分区中搜索
results = collection.search(
    data=[query_vector],
    anns_field="vector",
    param=search_params,
    partition_names=["recent_data"],  # 限定分区
    limit=10
)

内存问题 ​

内存不足 (OOM) ​

症状:

MilvusException: (code=1, message=Out of memory)

解决方案:

  1. 减少加载的数据量
python
# 只加载需要的分区
collection.load(partition_names=["partition_2024"])

# 而不是加载整个集合
# collection.load()  # 避免这样做
  1. 使用量化索引
python
# 使用 IVF_SQ8 替代 IVF_FLAT，节省 75% 内存
index_params = {
    "index_type": "IVF_SQ8",
    "metric_type": "L2",
    "params": {"nlist": 128}
}
  1. 增加系统内存
bash
# Docker 配置中增加内存限制
docker run -m 16g --memory-swap 16g milvusdb/milvus:latest

集合加载失败 ​

排查步骤:

python
from pymilvus import utility

# 检查集合是否存在
if not utility.has_collection("my_collection"):
    print("集合不存在")

# 检查索引状态
index_progress = utility.index_building_progress("my_collection")
print(f"索引进度: {index_progress}")

# 等待索引构建完成
utility.wait_for_index_building_complete("my_collection")

# 然后加载集合
collection = Collection("my_collection")
collection.load()

性能问题 ​

查询延迟高 ​

诊断工具:

python
import time

# 测量查询时间
start = time.time()
results = collection.search(
    data=[query_vector],
    anns_field="vector",
    param=search_params,
    limit=10
)
latency = (time.time() - start) * 1000
print(f"查询延迟: {latency:.2f}ms")

# 如果延迟 > 100ms，考虑优化
if latency > 100:
    print("建议优化：")
    print("1. 检查索引类型是否合适")
    print("2. 调整搜索参数（减小 nprobe/ef）")
    print("3. 使用更快的索引（如 HNSW）")

吞吐量低 ​

优化方案:

python
from concurrent.futures import ThreadPoolExecutor

# 并行查询
def parallel_search(collection, query_vectors, max_workers=4):
    def search_single(vector):
        return collection.search(
            data=[vector],
            anns_field="vector",
            param=search_params,
            limit=10
        )
    
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        results = list(executor.map(search_single, query_vectors))
    
    return results

数据一致性问题 ​

插入后查询不到数据 ​

原因: 数据可能还在缓冲区，未刷新到存储

解决方案:

python
# 手动刷新
collection.flush()

# 或者等待一段时间
import time
time.sleep(1)

# 然后再查询
results = collection.query(expr="", limit=10)

数据删除后空间未释放 ​

解决方案:

python
# 手动压缩
collection.compact()

# 等待压缩完成
utility.wait_for_compaction_complete("my_collection")

日志与调试 ​

启用调试日志 ​

python
from pymilvus import Config

# 设置日志级别
Config.set_log_level("DEBUG")

# 现在可以看到详细的日志输出

查看 Milvus 日志 ​

bash
# Docker 安装
docker logs milvus-standalone

# 或进入容器查看
docker exec -it milvus-standalone bash
cat /var/lib/milvus/logs/milvus.log

常见错误代码 ​

错误代码含义解决方案
1通用错误检查参数和配置
2连接错误检查服务状态和端口
3权限错误检查认证信息
4集合不存在创建集合或检查名称
5参数错误检查参数类型和范围
6索引错误检查索引配置
7搜索错误检查搜索参数

获取帮助 ​

官方资源 ​

提交 Issue ​

提交 Issue 时请提供：

  1. Milvus 版本
  2. 部署方式（Docker/K8s/源码）
  3. 完整的错误信息
  4. 复现步骤
  5. 相关配置
python
# 获取版本信息
import pymilvus
print(f"PyMilvus 版本: {pymilvus.__version__}")

from pymilvus import utility
print(f"Milvus 服务器版本: {utility.get_server_version()}")

Copyright © 2025-2026 京公网安备 11010102000001号 京ICP备2024078128号-1