快速入门：Windows系统本地部署Milvus Lite指南及踩坑实录

shot_gan

6750人浏览 · 2025-06-09 15:30:59

shot_gan · 2025-06-09 15:30:59 发布

快速入门：Windows系统本地部署Milvus Lite指南及踩坑实录

发布日期: 2025年6月9日

作者: shot_gan & AI开发伙伴Gemini

目标读者: 第一次接触Milvus、希望在Windows个人电脑上进行本地学习和实验的AI开发者、学生及爱好者。

核心目标: 搭建一个稳定、可靠、可复现的Milvus Lite本地开发环境，并成功运行一个完整的“增删查”代码示例。

前言：为什么需要这篇指南？

大家好！在我学习大模型开发，接触到“向量数据库”这个概念时，Milvus作为一款强大的开源工具，是必学的一站。然而，在官方文档大多推荐使用Docker或Linux环境的背景下，我作为一名Windows用户，在本地部署和学习的过程中，遇到了一系列“意料之外但情理之中”的坑。

这篇文档，就是我与我的AI伙伴共同走过的一段排错之旅的完整记录。它不仅会告诉你如何做（What），更会用通俗易懂的类比，让你明白为什么这么做（Why），真正做到“知其然，也知其所以然”。希望能帮助后来者节省时间，顺利迈出学习Milvus的第一步。

零、 Milvus vs. Milvus Lite，我们该如何选择？

在开始安装前，我们首先要理解，Milvus主要有两种存在形态，它们分别适用于不同的场景。

运维类比：
- Milvus (标准版)：就像一个部署在专业机房、由多台服务器组成的大型数据中心。它性能强大、稳定可靠、支持高并发，是生产环境的不二之选。部署它，通常需要使用Docker或在Linux服务器上进行。
- Milvus Lite (轻量版)：就像一台功能强大、开箱即用的个人开发笔记本。它把数据中心的核心功能都集成在了这台“笔记本”里，无需复杂的部署，非常适合学习、开发、原型验证和中小型项目。它可以在你的Windows或macOS上直接运行。

我们这篇指南，聚焦的就是Milvus Lite。它能让你在个人电脑上，以最快速度、最低成本体验到Milvus几乎所有的核心功能。当你完成了学习和开发，准备将应用部署到正式的生产环境时，再将代码无缝迁移到标准版的Milvus服务上即可。

一、最终目标：我们的“Hello Milvus”代码

在开始“施工”前，我们先明确一下最终要成功运行的代码是什么。这份代码实现了连接、创建集合、插入数据、查询数据、断开连接的完整流程。

# 导入所需要的库
from pymilvus import connections, utility, Collection, CollectionSchema, FieldSchema, DataType
from sentence_transformers import SentenceTransformer
import numpy as np

# --- 1. 连接 Milvus Lite ---
# 对于2.2.x版本的Milvus Lite，安装后即可直接连接，无需在代码中启动
print("开始连接 Milvus...")
connections.connect(alias="default") # 直接使用默认别名连接
print("Milvus 连接成功。")

# try...finally 结构能确保即使中间代码报错，最后也能优雅地断开连接
try:
    # --- 2. 定义集合的 Schema (像创建数据库表结构) ---
    collection_name = "my_milvus_collection_final" 
    if utility.has_collection(collection_name):
        utility.drop_collection(collection_name)

    field_id = FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=False)
    field_text = FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=512)
    # 注意：我们在这里需要知道“翻译官”产生的向量维度，all-MiniLM-L6-v2 是384维
    field_embedding = FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=384)
    schema = CollectionSchema(fields=[field_id, field_text, field_embedding])
    collection = Collection(name=collection_name, schema=schema)
    print(f"集合 '{collection_name}' 创建成功。")

    # --- 3. 准备数据和“翻译官”（嵌入模型） ---
    model = SentenceTransformer('all-MiniLM-L6-v2') 
    documents = [
        "RAG是一种检索增强生成技术", 
        "向量数据库存储文档的嵌入表示", 
        "在机器学习领域，智能体（Agent）通常指能够感知环境、做出决策并采取行动以实现特定目标的实体"
    ]
    embeddings = model.encode(documents)
    data_to_insert = [[1, 2, 3], documents, embeddings]

    # --- 4. 插入数据 ---
    collection.insert(data_to_insert)
    collection.flush()
    print("数据插入成功。")

    # --- 5. 创建索引并加载 ---
    index_params = {"metric_type": "L2", "index_type": "IVF_FLAT", "params": {"nlist": 128}}
    collection.create_index(field_name="embedding", index_params=index_params)
    collection.load()
    print("索引创建并加载成功。")

    # --- 6. 查询数据 ---
    query_text = ["RAG是什么？"]
    query_vectors = model.encode(query_text)
    search_params = {"metric_type": "L2", "params": {"nprobe": 10}}
    results = collection.search(data=query_vectors, anns_field="embedding", param=search_params, limit=2, output_fields=["text"])

    # --- 7. 打印和解析结果 ---
    print("\n查询结果: ")
    for hit in results[0]:
        print(f"ID: {hit.id}, 距离: {hit.distance:.4f}, 内容: {hit.entity.get('text')}")
    print("\n集合中的文档总数: ", collection.num_entities)

finally:
    # --- 8. 断开连接，释放资源 ---
    print("\n断开 Milvus 连接...")
    connections.disconnect("default")
    print("连接已断开。")

二、最佳实践：标准化的部署流程

为了避免“依赖地狱”，我们将采用最专业的“标准化部署”方式，通过requirements.txt文件来精确管理我们的开发环境。

第1步：创建全新的、干净的Conda环境

为Milvus项目创建一个完全隔离的“工作室”。

conda create -n milvus-final python=3.10 -y
conda activate milvus-final

第2步：创建`requirements.txt`部署蓝图

在你的项目文件夹下，新建一个名为requirements.txt的文本文件，将以下内容复制进去。这份文件就是我们环境的“配置清单”，精确定义了每个工具的版本。

# --- Milvus 核心组件 ---
# 在windows上，这是能稳定运行Milvus Lite的最新版本。另外，使用pip安装milvus只能安装lite版本（因为Milvus的开发者在打包时决定，提供给Windows用户的`milvus`包，就是方便好用的`Milvus Lite`版）。
milvus==2.2.16

# --- Milvus 客户端 (与核心版本匹配) ---
pymilvus==2.2.13

# --- 关键依赖版本锁定 ---
# 解决 "AttributeError: __version_info__" 的问题
# 强制 marshmallow 版本低于 4.0
marshmallow<4.0

# --- 嵌入模型库 ---
sentence-transformers

# --- Jupyter 开发环境 ---
jupyterlab
ipykernel

第3步：一键自动化安装

在终端中，确保你处于项目文件夹路径下，然后执行“魔法命令”：

pip install -r requirements.txt

pip会自动读取清单，为你安装所有指定版本的依赖。

第4步：手动启动Milvus Lite服务

打开一个新的终端窗口，激活milvus-final环境，然后启动服务。这个窗口需要保持运行。

conda activate milvus-final
milvus-server

第5步：在Jupyter中运行代码

回到你原来的终端，从项目目录启动Jupyter Lab。

# 确保在项目目录下
jupyter lab

在Jupyter Lab中，新建一个Notebook，确保其内核（右上角）是我们新建的milvus-final环境，然后将第一部分的目标代码粘贴进去并运行。

如果使用VS Code，也需要在右上角选择对应的conda环境，确保右上角的内核（Kernel）选择的是我们刚刚创建的milvus-final环境。成功运行的效果如下图：

运行结果-success

三、避坑指南：我们是如何走出“依赖地狱 (Dependency Hell)”的

如果你严格按照第二部分的流程操作，应该会一帆风顺。但我在第一次“过河”的时候，却多次“踩坑”。经过反复和Gemini对话，才得到这份“最佳实践”的，下面是我们“踩坑”和“排错”的全过程复盘。

坑点1：`SyntaxError: invalid syntax`

现象：在Jupyter lab的代码块中运行milvus-server命令，就出现上面的报错信息。
原因：混淆了命令行语言和Python语言。milvus-server是给终端（Shell）听的命令，而Jupyter lab的代码块只认识Python代码。
类比：我们不能在“Python编程台”上，说“终端操作台”的方言。
解决方案：必须在独立的终端窗口（如Anaconda Powershell Prompt）里执行这类服务启动命令。

（启动milvus-server时的终端输出效果如下图，它在经典的Logo旁边，明确地打上了{Lite}的标签，并且在版本号里也写着v2.2.16-lite。“确认过眼神，这是对的人”）

坑点2：`MilvusException: Fail connecting to server on localhost:19530`

现象：运行connections.connect(...)时连接超时。
原因：客户端（Python代码）在拨打服务器的“电话”，但服务器进程（milvus-server.exe）根本没有启动，导致无人接听。
类比：用SSH客户端去连接一台没开机的服务器。
解决方案：采用“手动模式”，先在独立的终端里确认milvus-server已成功启动并正在运行，再在Jupyter里执行连接代码。

坑点3：`ImportError: cannot import name 'default_server'`

现象：代码from pymilvus import default_server报错。
原因：版本不匹配。较新版的pymilvus客户端才有default_server这个便捷工具，但我们Windows环境能装上的milvus核心服务是较旧的2.2.16版。
类比：代工车厂不按原厂说明组装零件，“2025款”的新方向盘，想去控制“2023款”的旧引擎，发现很多新功能按钮（如default_server）在旧引擎上没有对应的接口。
解决方案：放弃使用最新版客户端，先通过pip uninstall pymilvus命令删除2.5.10新版本的pymilvus，再通过pip install pymilvus==2.2.13，手动安装与核心服务版本相匹配的旧版客户端，实现“版本对齐”。

坑点4：`pip install` 总是安装旧版本

现象：即使卸载后重装，pip也总是安装milvus==2.2.16。
原因：pip的缓存机制或平台兼容性。pip会优先使用本地缓存的旧版安装包，或者发现最新版的软件包没有提供Windows的“型号”。
类比：“节俭的管家”优先从“本地仓库”拿货，而不是去“网上总店”；或者“网上总店”告知“Windows牌”汽车只能使用这款旧型号。
解决方案：使用--no-cache-dir参数强制pip忽略缓存，并认识到平台兼容性是软件选型的重要限制。

坑点5：`AttributeError: 'marshmallow' has no attribute '__version_info__'`

现象：即使装了pymilvus==2.2.13，导入时依然报错。
原因：“依赖的依赖”不兼容。pymilvus依赖environs，environs又依赖marshmallow。pip在安装时，为environs自动匹配了一个太新的marshmallow 4.0版，而旧的environs不认识新版marshmallow的格式。由于三方的依赖包之前的版本兼容性问题，导致pymilvus无法正常运行。
类比：“二级分包商”不认识“三级分包商”提供的新版资质文件。
解决方案：作为“总包商”，我们必须手动干预，强制pip install marshmallow==3.21.3，降级这个底层的依赖包，确保整个“供应链”上的版本都能互相兼容。