这次我们来看一个 LangChain 项目环境搭建的实战流程。这个流程的核心不是某个单一的模型而是一套完整的、可复现的本地开发环境构建方案。如果你正在学习 LangChain并希望在一个干净、隔离的虚拟机环境中从零开始部署 Docker、Docker Compose 以及向量数据库 Milvus那么这篇文章就是为你准备的。整个过程聚焦于实操我们会一步步完成虚拟机克隆、系统配置、软件安装和服务启动确保你最终能获得一个可用于 AI 应用开发的标准化环境。本文的重点是“可复现”和“可操作”。我们将从一台基础的 Linux 虚拟机例如 Ubuntu开始通过命令行完成所有必要组件的安装与配置。你会看到具体的命令、可能遇到的错误以及对应的解决方案。最终目标是成功启动一个 Milvus 单机版服务为后续集成 LangChain 进行向量检索、构建 RAG检索增强生成应用打下坚实基础。1. 核心能力速览能力项说明项目类型本地开发环境搭建与配置教程技术栈虚拟机 (VMware/VirtualBox) Ubuntu Docker Docker Compose Milvus核心目标构建一个干净、隔离的 LangChain 开发环境并启动向量数据库 Milvus硬件门槛对宿主机 CPU 和内存有基本要求需开启虚拟化支持。虚拟机本身资源建议 2核4G 以上。启动方式通过 Docker Compose 一键启动 Milvus 服务主要功能1. 虚拟机环境标准化配置2. Docker 及 Docker Compose 安装3. Milvus 单机版部署与启动4. 服务状态验证与基本使用适合场景LangChain/RAG 应用本地开发、测试、学习需要隔离的 AI 项目环境搭建2. 适用场景与使用边界这套环境搭建方案主要适合以下几类开发者LangChain 初学者希望在一个纯净、无干扰的环境中系统学习 LangChain 及其生态工具。AI 应用原型开发者需要快速搭建包含向量数据库的后端服务用于验证 RAG、智能体Agent等应用场景。团队协作与标准化通过共享虚拟机镜像或配置脚本确保团队所有成员拥有一致的开发环境避免“在我机器上是好的”这类问题。使用边界与注意事项性能限制在虚拟机中运行 Docker 和 Milvus性能会有一定损耗不适合生产环境高并发、大数据量场景。主要用于开发和测试。资源占用同时运行宿主机系统、虚拟机、Docker 容器对宿主机内存和 CPU 资源消耗较大。数据持久化需正确配置 Docker 卷Volume或绑定挂载确保虚拟机重启后 Milvus 数据不丢失。网络访问确保虚拟机网络配置正确如 NAT 或桥接以便宿主机能够访问虚拟机内启动的 Milvus 服务端口。3. 环境准备与前置条件在开始之前请确保你的宿主机满足以下条件宿主机操作系统Windows 10/11, macOS 或 Linux。本文以 Windows 宿主机 Ubuntu 虚拟机为例但原理通用。虚拟化支持已开启这是运行虚拟机的基石。需要在计算机 BIOS/UEFI 设置中开启 Intel VT-x 或 AMD-V 虚拟化技术。如何检查Windows打开任务管理器 - 性能 - CPU查看“虚拟化”是否显示“已启用”。虚拟机软件已安装 VMware Workstation、VMware Player 或 VirtualBox。本文示例使用 VMware。基础虚拟机镜像准备一个安装好的 Linux 虚拟机如 Ubuntu 20.04/22.04 LTS。建议使用 Minimal 或 Server 版本以减少资源占用。我们将以此为基础进行克隆和配置。网络连接虚拟机需要能访问互联网以下载 Docker 和 Milvus 的安装包及镜像。4. 克隆虚拟机与初始配置为了避免污染原始镜像我们首先克隆一份新的虚拟机用于本次环境搭建。操作步骤在你的虚拟机管理软件如 VMware中关闭原始 Ubuntu 虚拟机。找到克隆功能通常在虚拟机右键菜单或管理菜单中。选择“创建完整克隆”为新虚拟机命名例如ubuntu-langchain-dev。启动克隆好的新虚拟机并使用账号密码登录。初始系统配置在克隆的虚拟机内执行登录后首先更新系统包列表并升级现有软件这是一个好习惯。# 更新软件包列表 sudo apt update # 升级已安装的软件包 sudo apt upgrade -y # 可选安装一些常用工具如网络工具、编辑器等 sudo apt install -y net-tools curl wget vim5. 安装 Docker 引擎Docker 是容器化运行 Milvus 的基础。我们将使用 Docker 官方提供的便捷脚本进行安装。安装步骤下载并执行 Docker 安装脚本。将当前用户加入docker组以便无需sudo即可运行 Docker 命令。# 1. 下载 Docker 安装脚本 curl -fsSL https://get.docker.com -o get-docker.sh # 2. 执行安装脚本 sudo sh get-docker.sh # 3. 安装完成后将当前用户加入 docker 用户组 sudo usermod -aG docker $USER # 4. 提示为了使组更改生效你需要**注销并重新登录**或者重启虚拟机。 # 你可以先不重启继续安装 Docker Compose但后续运行 docker 命令可能仍需 sudo。 # 为了验证可以尝试运行如果提示权限错误请先使用 sudo sudo docker --version常见问题排查curl: command not found先执行sudo apt install -y curl安装 curl。脚本执行失败可能是网络问题。可以尝试使用国内镜像源或者查阅 Docker 官方文档使用其他安装方式。用户组更改未生效执行newgrp docker命令或重启虚拟机。6. 安装 Docker ComposeDocker Compose 用于定义和运行多容器应用。Milvus 单机版依赖多个容器如 etcd、MinIO使用 Compose 可以一键管理。安装步骤推荐从 Docker Compose 的 GitHub Release 页面直接下载二进制文件。# 1. 确定要下载的版本例如 v2.23.0。请查看 GitHub 最新版本。 COMPOSE_VERSIONv2.23.0 # 2. 下载 Docker Compose 二进制文件到 /usr/local/bin/docker-compose sudo curl -L https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 3. 赋予二进制文件可执行权限 sudo chmod x /usr/local/bin/docker-compose # 4. 创建软链接可选但可确保 docker compose 命令可用 sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose # 5. 验证安装 docker-compose --version # 或使用新的 docker compose 命令格式 docker compose version7. 安装与启动 Milvus 单机版Milvus 提供了官方的 Docker Compose 配置文件使得部署变得非常简单。操作步骤创建专用目录并下载配置文件。使用 Docker Compose 启动所有服务。验证服务是否正常运行。# 1. 创建一个工作目录并进入该目录 mkdir -p ~/milvus-standalone cd ~/milvus-standalone # 2. 下载 Milvus 单机版的 Docker Compose 配置文件 # 注意请从 Milvus 官方 GitHub 仓库获取最新版本的 compose 文件。 # 以下以较新的版本为例下载前请确认版本号。 wget https://github.com/milvus-io/milvus/releases/download/v2.3.3/milvus-standalone-docker-compose.yml -O docker-compose.yml # 3. 检查下载的 YAML 文件内容确保其正确性可选 cat docker-compose.yml | head -20 # 4. 在后台启动所有服务包括 Milvus, etcd, MinIO sudo docker compose up -d # 如果你安装的是独立的 docker-compose 命令也可以使用 # sudo docker-compose up -d # 5. 查看容器运行状态确认所有服务状态均为 running 或 healthy sudo docker compose ps # 或 sudo docker-compose ps命令输出解读执行docker compose ps后你应该看到类似下面的输出表明三个核心服务都已正常启动NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS milvus-standalone milvusdb/milvus:v2.3.3 /tini -- milvus run… milvus-standalone 10 seconds ago Up 9 seconds 0.0.0.0:19530-19530/tcp, 0.0.0.0:9091-9091/tcp milvus-etcd quay.io/coreos/etcd:v3.5.5 etcd -advertise-cli… etcd 10 seconds ago Up 9 seconds 2379-2380/tcp milvus-minio minio/minio:RELEASE.2023-03-20T20-16-18Z sh -c mkdir -p /da… minio 10 seconds ago Up 9 seconds 0.0.0.0:9000-9000/tcp, 0.0.0.0:9001-9001/tcp8. 功能测试与效果验证服务启动后我们需要验证 Milvus 是否真的可以访问并提供服务。8.1 验证服务健康状态Milvus 提供了一个健康检查接口。# 使用 curl 调用 Milvus 的健康检查 API curl http://localhost:9091/healthz如果返回{status:OK}则说明 Milvus 服务运行健康。8.2 使用 Python 客户端进行连接测试这是更贴近实际开发场景的验证方式。在虚拟机内安装 Milvus Python SDKpip install pymilvus如果未安装 pip请先执行sudo apt install -y python3-pip创建测试脚本test_connection.pyfrom pymilvus import connections, utility # 1. 连接到本地的 Milvus 服务 print(正在连接 Milvus...) connections.connect(host127.0.0.1, port19530) print(连接成功) # 2. 检查服务器状态可选需要相应权限 try: version utility.get_server_version() print(fMilvus 服务器版本: {version}) except Exception as e: print(f获取版本信息时出错可能权限不足: {e}) # 3. 列出所有集合数据库初始应为空 collections utility.list_collections() print(f当前集合列表: {collections}) # 4. 断开连接 connections.disconnect() print(测试完成连接已断开。)运行测试脚本python3 test_connection.py预期成功输出正在连接 Milvus... 连接成功 Milvus 服务器版本: 2.3.3 当前集合列表: [] 测试完成连接已断开。如果看到“连接成功”且没有报错则证明 Milvus 向量数据库服务已完全就绪可以接受客户端的操作指令。9. 接口 API 与基本操作Milvus 主要通过 gRPC 端口默认 19530和 HTTP 端口默认 9091提供服务。上一步的 Python SDK 是对这些接口的封装。对于更底层的测试或集成你也可以直接使用其 RESTful API部分管理功能或各种语言的 SDK。关键服务端口说明Milvus 服务:19530(gRPC),9091(HTTP 健康检查与管理)MinIO (对象存储):9000(API),9001(Console)etcd (元数据存储):2379(客户端通信)下一步可以尝试的 API 操作通过 Python SDK创建集合Collection相当于数据库的表。创建索引Index为向量字段创建索引以加速搜索。插入数据Insert向集合中插入向量数据和标量属性。向量搜索Search执行近似最近邻ANN搜索。这些操作是构建 RAG 应用的核心步骤将在你后续集成 LangChain 时用到。10. 资源占用与性能观察在虚拟机中运行这套服务了解其资源消耗很重要。观察资源占用命令# 查看所有运行中的容器资源占用情况 sudo docker stats # 查看特定容器的详细资源使用如 milvus-standalone sudo docker stats milvus-standalone # 在虚拟机内查看整体系统资源CPU、内存 htop # 如果未安装先运行 sudo apt install -y htop # 或使用 top典型资源占用仅供参考实际因数据和查询而异空闲状态启动后三个容器总内存占用约 1.5GB - 2.5GB。CPU 占用空闲时接近 0%执行插入或搜索任务时会显著升高。磁盘空间Docker 镜像和卷会占用数 GB 空间。使用docker system df查看。性能优化提示分配更多资源给虚拟机如果宿主机资源充足在虚拟机设置中增加 CPU 核心数和内存如 4核8G能明显提升 Milvus 处理速度。使用 SSD 硬盘将虚拟机磁盘文件放在宿主机 SSD 上能极大改善 etcd 和 MinIO 的 I/O 性能。调整 Milvus 配置对于高级用户可以修改docker-compose.yml中 Milvus 容器的启动参数或挂载自定义的server_config.yaml来调整缓存大小、线程数等。11. 常见问题与排查方法问题现象可能原因排查方式解决方案docker compose up -d失败提示Cannot connect to the Docker daemonDocker 服务未启动或当前用户无权限。运行sudo systemctl status docker查看服务状态。运行groups查看当前用户是否在docker组。启动服务sudo systemctl start docker。将用户加入 docker 组后务必注销重登或重启。临时使用sudo。Milvus 容器启动后很快退出Exited端口冲突、内存不足、配置文件错误。sudo docker compose logs milvus-standalone查看容器日志。sudo docker compose ps -a查看退出状态码。根据日志错误解决。常见于 19530 或 9091 端口被占用可修改docker-compose.yml中的端口映射。确保虚拟机内存足够2GB。健康检查curl http://localhost:9091/healthz失败Milvus 服务未完全启动或崩溃。sudo docker compose logs milvus-standalone查看详细启动日志。等待片刻再试。检查日志中是否有明显的错误信息如依赖的 etcd 连接失败。Python 客户端连接超时防火墙阻止、IP地址错误、服务未监听。在虚拟机内运行netstat -tlnp | grep 19530检查端口监听状态。确认连接 IP 是127.0.0.1。确保连接地址正确。如果是宿主机连接虚拟机需确认虚拟机网络模式如桥接并使用虚拟机 IP同时检查虚拟机防火墙sudo ufw status。执行docker compose命令提示command not foundDocker Compose 未安装或未在 PATH 中。检查/usr/local/bin/docker-compose是否存在且有执行权限。重新执行安装步骤或使用sudo /usr/local/bin/docker-compose指定全路径。也可安装docker-compose-plugin。虚拟机无法上网虚拟机网络配置问题。在虚拟机内ping 8.8.8.8。检查虚拟机软件的网络设置如 NAT 模式。确保虚拟机网络适配器已连接。在 VMware 中可尝试“恢复默认设置”。12. 最佳实践与使用建议环境快照在完成 Docker 和 Docker Compose 安装后为虚拟机创建一个“快照”Snapshot。这样如果后续 Milvus 配置出错可以快速回滚到这个干净的状态。数据持久化默认的docker-compose.yml通常已配置了匿名卷volume来持久化 etcd、MinIO 和 Milvus 的数据。你可以在宿主机上找到这些卷或修改配置将其映射到虚拟机内明确的目录便于备份。# 示例修改 docker-compose.yml 中的 volumes 部分将数据挂载到主机路径 services: milvus-standalone: # ... 其他配置 volumes: - ./volumes/milvus:/var/lib/milvus服务管理停止服务sudo docker compose down停止并删除数据卷sudo docker compose down -v(谨慎使用会清空所有数据)查看实时日志sudo docker compose logs -f milvus-standalone重启服务sudo docker compose restart为生产环境准备本文部署的是 Standalone 版适用于开发测试。生产环境应考虑使用 Cluster 集群版并配置独立的 MySQL/PGSQL 作为元数据存储以及更可靠的对象存储服务。与 LangChain 集成环境就绪后下一步就是在同一虚拟机或网络互通的其他机器上安装 LangChain 及其 Milvus 集成包langchain-milvus开始构建你的 RAG 应用。至此你已经成功在克隆的虚拟机中配置了一个包含 Docker、Docker Compose 和 Milvus 的标准化 LangChain 开发环境。这个环境隔离性好配置清晰非常适合进行各种 AI 应用的实验和开发。接下来你就可以专注于 LangChain 的代码编写和业务逻辑实现了。如果在后续集成中遇到连接问题首先回头检查本指南中的验证步骤确保 Milvus 这个基础服务是正常运行的。