1. 项目概述为什么环境搭建是LLM应用开发的第一步如果你刚接触LangChain或者任何大语言模型LLM应用开发可能会觉得直接写代码调用API才是正事环境配置无非是“安装Python、装几个包”的琐碎流程。我刚开始也是这么想的直到在一个关键项目交付前夜因为本地环境和服务器环境的细微差异导致整个RAG检索增强生成链条在服务器上跑不起来debug到凌晨三点。那次教训让我彻底明白一个稳定、可复现、团队统一的开发环境不是“准备工作”而是项目成功的基石。“第2章 开发环境搭建与基础配置”这个标题听起来像是技术手册里最枯燥的部分但它恰恰决定了你后续是顺畅地探索LLM的无限可能还是陷入“为什么我的代码跑不起来”的无尽泥潭。本章的核心就是帮你搭建一个专为LLM应用开发优化的“工作台”。我们将围绕LangChain这个当前最流行的LLM应用框架在Python环境下从零开始构建一个既能快速实验、又能平滑过渡到生产部署的健壮开发环境。这不仅仅是安装软件更是建立一套标准化的开发习惯和工具链涵盖从代码编辑、依赖管理、虚拟环境隔离到基础功能验证的完整闭环。无论你是想开发一个智能客服Agent、一个基于私有知识库的问答系统还是用LangGraph设计复杂的工作流一个配置得当的环境能让你专注于业务逻辑和创新而不是和版本冲突、路径错误作斗争。接下来我会带你一步步走通这个过程并分享那些官方文档里不会写的、我踩过坑后才总结出的实操细节。2. 环境整体设计与核心工具选型搭建开发环境首要原则是“隔离与可复现”。我们不能直接在系统全局Python环境里胡乱安装包那会给不同项目带来依赖地狱也让团队协作变得困难。因此我们的设计思路是以虚拟环境为核心配合现代高效的包管理工具和代码编辑器构建一个模块化、容器化友好的基础层。2.1 核心工具栈解析我们的工具选择基于当前2024年Python数据科学和AI开发社区的最佳实践Python 解释器这是基石。LangChain对Python版本有要求通常需要Python 3.8及以上。我强烈推荐使用Python 3.10或3.11它们在性能、语法支持和库的兼容性上达到了一个很好的平衡。避免使用最新的3.13等预览版某些科学计算库可能尚未适配。虚拟环境管理工具这是实现环境隔离的关键。我们有多个选择venv(内置)Python 3.3 自带轻量、无需额外安装是基础且可靠的选择。conda/mamba如果你需要管理非Python依赖如特定的CUDA版本、系统库或者身处数据科学领域Conda是王者。mamba是Conda的C重写版速度极快解决了Conda慢的痛点。pipenv/poetry这两者将依赖管理和虚拟环境绑定在一起能精确锁定依赖版本并生成Pipfile.lock或poetry.lock非常适合应用打包和部署。我的选择与理由对于纯Python的LLM应用开发我目前首选uv。它是一个用Rust编写的、极其快速的Python包安装器和解析器同时集成了虚拟环境管理功能。它的速度比传统pip快10-100倍并且能直接替代pip和venv的工作流。如果项目复杂或团队习惯统一poetry也是一个非常专业的选择。为了普适性本章会以venv为基础讲解但会穿插介绍uv等现代工具的高效用法。包管理工具就是pip。但pip本身也在进化。确保使用最新版的pippython -m pip install --upgrade pip。对于uv用户其内置的解析器已经替代了pip。代码编辑器/IDEVisual Studio Code (VS Code)是目前Python和AI开发领域的绝对主流。它轻量、插件生态丰富、对Jupyter Notebook支持好并且与Git集成无缝。我们将重点配置它。版本控制Git。毋庸置疑所有代码和关键配置文件如requirements.txt或pyproject.toml必须纳入版本控制。2.2 为什么需要这样的配置虚拟环境每个项目独立的环境避免包版本冲突。例如项目A需要langchain0.1.0项目B需要langchain0.2.0全局安装只能满足一个。虚拟环境让它们互不干扰。明确的依赖声明通过requirements.txt或pyproject.toml文件明确记录项目所有依赖及其版本。这确保了在任何机器上你的电脑、同事的电脑、云服务器都能一键复现完全相同的环境。VS Code的集成VS Code能自动识别并激活项目目录下的虚拟环境提供智能补全、代码导航、调试和Lint检查极大提升开发效率。为未来容器化铺路清晰的环境依赖文件是后续编写Dockerfile、将应用容器化的前提。Docker镜像构建过程本质上就是在一个纯净系统中复现你的开发环境。注意网络上很多教程会教你直接pip install langchain openai而不提虚拟环境。对于快速试一个小脚本或许可行但对于正经项目开发这绝对是坏习惯的开端。从一开始就规范起来能省去未来无数麻烦。3. 逐步搭建从Python安装到第一个LangChain程序让我们开始动手。我会以macOS/Linux和Windows系统下的通用操作为主并指出关键差异。3.1 安装与验证PythonmacOS/Linux用户 推荐使用Homebrew安装特定版本的Python。# 安装Homebrew如果尚未安装请访问 brew.sh /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) # 安装Python 3.11 brew install python3.11 # 验证安装 python3.11 --version # 应输出 Python 3.11.x pip3.11 --version # 应输出 pip 版本系统自带的Python通常版本较旧且与系统组件耦合不建议直接使用。Windows用户访问 python.org 。下载 Python 3.11 的 Windows 安装程序例如python-3.11.9-amd64.exe。运行安装程序。至关重要的一步务必勾选“Add python.exe to PATH”选项这样才可以在命令行中直接使用python命令。安装完成后打开命令提示符CMD或 PowerShell验证python --version pip --version验证与升级pip 无论哪种系统安装后都建议立即升级pip到最新版。python -m pip install --upgrade pip3.2 创建并激活虚拟环境我们将为项目创建一个独立的目录并在其中创建虚拟环境。创建项目目录并进入mkdir my-langchain-project cd my-langchain-project创建虚拟环境使用venv(传统方法)# macOS/Linux python3.11 -m venv venv # Windows python -m venv venv这会在当前目录下创建一个名为venv的文件夹里面包含独立的Python解释器和pip。使用uv(现代高效方法强烈推荐) 首先安装uv它是一个独立的二进制工具不依赖Python环境# 在终端中执行以下任一命令 # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -c irm https://astral.sh/uv/install.ps1 | iex安装后创建虚拟环境并安装Pythonuv venv # 这会在当前目录创建 .venv 虚拟环境 # 或者指定Python版本 uv venv --python 3.11激活虚拟环境 激活后你的终端提示符前通常会显示环境名如(venv)意味着后续所有pip install或python命令都只作用于这个隔离环境。macOS/Linux (bash/zsh)source venv/bin/activate # 如果是 uv 创建的 .venv则是 source .venv/bin/activateWindows (CMD)venv\Scripts\activate.batWindows (PowerShell)venv\Scripts\Activate.ps1如果PowerShell提示执行策略限制可以先以管理员身份运行Set-ExecutionPolicy RemoteSigned选择Y。激活后检查Python和pip的路径确认它们指向虚拟环境内部which python # macOS/Linux where python # Windows # 应输出类似 /path/to/my-langchain-project/venv/bin/python 的路径3.3 安装核心依赖LangChain与LLM提供商SDK现在我们在激活的虚拟环境中安装必要的包。LLM应用开发核心是LangChain框架和一个LLM提供商的接入能力例如OpenAI。安装LangChainpip install langchain这将安装LangChain的核心包。LangChain生态庞大还有许多可选的集成包如langchain-community,langchain-openai等。现在核心包已经包含了大部分常用功能。安装LLM提供商SDK 你需要一个LLM来驱动你的应用。这里以OpenAI的GPT模型为例你需要拥有OpenAI API Key。pip install openai如果你想使用开源模型比如通过Ollama在本地运行则可以安装pip install langchain-community # Ollama本身需要单独安装详见其官网安装环境变量管理工具可选但推荐 我们不应该将API Key等敏感信息硬编码在代码里。python-dotenv包可以方便地从.env文件加载环境变量。pip install python-dotenv生成依赖文件 安装完基础包后立即将当前环境的依赖固定下来这是“可复现”的关键。pip freeze requirements.txt查看requirements.txt你会看到类似这样的内容包含了所有包及其精确版本langchain0.1.xx openai1.12.xx python-dotenv1.0.xx ...使用uv的优化如果你用uv安装命令更高效且依赖解析更快。uv使用pyproject.toml但也可以兼容requirements.txt。uv pip install langchain openai python-dotenv uv pip freeze requirements.txt3.4 配置VS Code作为开发环境VS Code的强大在于其插件系统。我们需要配置它来完美支持我们的Python项目。打开项目文件夹 在VS Code中选择File-Open Folder...然后选择你刚才创建的my-langchain-project文件夹。安装核心插件Python (Microsoft)必装。提供Python语言支持、智能感知、调试、测试、Jupyter笔记本等所有核心功能。Pylance必装。它是Python的语言服务器提供超快的代码补全、类型检查、代码导航。安装Python扩展后Pylance通常会被推荐或内置启用。Jupyter如果你计划使用Jupyter Notebook进行快速原型实验这在LLM探索中很常见这个扩展是必须的。GitLens可选但强烈推荐。增强VS Code内置的Git功能让你能清晰看到代码的修改历史和作者。在VS Code的扩展市场CtrlShiftX中搜索并安装它们。选择Python解释器 这是让VS Code正确关联到你项目虚拟环境的关键一步。按F1或CtrlShiftP打开命令面板。输入并选择“Python: Select Interpreter”。在弹出的列表中你应该能看到一个指向./venv/bin/python或./.venv/bin/python的选项。选择它。选择后VS Code底部状态栏的左侧会显示当前选择的Python解释器路径。创建并配置.env文件 在项目根目录下创建一个名为.env的文件。这个文件用于存储敏感信息务必将其添加到.gitignore中不要提交到版本库。# .env OPENAI_API_KEYsk-your-actual-openai-api-key-here在VS Code中你可能需要安装“Env”插件来获得.env文件的语法高亮。创建第一个验证脚本 在项目根目录下创建一个test_env.py文件输入以下代码import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage # 1. 加载环境变量 load_dotenv() print(环境变量加载成功。) # 可以打印API Key的前几位验证生产环境不要打印 # print(fAPI Key 前缀: {os.getenv(OPENAI_API_KEY)[:10]}...) # 2. 初始化LLM # 使用较新的 langchain_openai 包它是 langchain 对 openai SDK v1 的封装 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 控制随机性0表示更确定性的输出 api_keyos.getenv(OPENAI_API_KEY) # 从环境变量读取 ) # 3. 发起一个简单的对话 print(正在调用LLM...) try: response llm.invoke([HumanMessage(content请用中文简单介绍一下你自己。)]) print(LLM 回复:) print(response.content) print(\n✅ 环境配置与基础连接测试成功) except Exception as e: print(f\n❌ 调用失败错误信息: {e}) print(请检查1. .env文件中的API KEY是否正确且有效2. 网络连接3. OpenAI账户余额。)这段代码做了三件事加载环境变量、初始化ChatOpenAI模型、发送一条测试消息。这是一个完整的、最小化的LangChain应用。运行测试 在VS Code中打开test_env.py文件点击右上角的运行按钮▶️或者右键在终端中运行。 如果一切配置正确你将在终端看到LLM的自我介绍并打印出成功信息。实操心得第一次运行常会遇到SSL证书错误特别是在某些网络环境下或超时。如果是SSL问题可以临时设置环境变量export REQUESTS_CA_BUNDLE不推荐长期使用或更新系统证书。超时问题可以尝试为ChatOpenAI初始化增加request_timeout参数例如request_timeout30。确保你的API Key有余额且未被禁用。4. 深入配置提升开发效率与项目健壮性基础环境跑通后我们需要一些进阶配置来让开发体验更丝滑项目结构更专业。4.1 项目结构标准化一个良好的项目结构有助于团队协作和长期维护。建议在项目根目录创建如下结构my-langchain-project/ ├── .env # 本地环境变量.gitignore ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖或 pyproject.toml ├── README.md # 项目说明 ├── src/ # 源代码目录 │ ├── __init__.py │ ├── agents/ # 代理模块 │ ├── chains/ # 链模块 │ ├── tools/ # 自定义工具模块 │ └── utils/ # 工具函数 ├── tests/ # 测试目录 │ └── __init__.py ├── notebooks/ # Jupyter实验笔记本 └── scripts/ # 部署或实用脚本你可以使用以下命令快速创建mkdir -p src/agents src/chains src/tools src/utils tests notebooks scripts touch src/__init__.py tests/__init__.py README.md .gitignore4.2 配置.gitignore文件一个针对Python和AI项目的.gitignore文件至关重要。你可以在项目根目录创建该文件并填入以下内容或从 github/gitignore 获取模板# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # Virtual environments venv/ .env/ .venv/ env/ # Environment variables .env .env.local .env.*.local # IDE .vscode/ .idea/ *.swp *.swo # Jupyter Notebook .ipynb_checkpoints # OS generated files .DS_Store Thumbs.db # My PyTest cache .pytest_cache/4.3 配置VS Code工作区设置在项目根目录创建.vscode文件夹并在其中创建settings.json文件。这个文件可以定义针对本项目的VS Code设置与全局设置隔离。{ python.defaultInterpreterPath: ${workspaceFolder}/venv/bin/python, python.terminal.activateEnvironment: true, python.terminal.executeInFileDir: true, python.linting.enabled: true, python.linting.pylintEnabled: false, // 个人偏好可以用flake8或ruff python.linting.flake8Enabled: true, python.formatting.provider: black, // 使用black自动格式化代码 python.testing.pytestEnabled: true, [python]: { editor.formatOnSave: true, // 保存时自动格式化 editor.codeActionsOnSave: { source.organizeImports: true // 保存时自动整理import语句 } }, files.exclude: { **/__pycache__: true, **/.pytest_cache: true, **/*.pyc: true }, jupyter.notebookFileRoot: ${workspaceFolder}/notebooks }这些设置实现了自动激活虚拟环境、保存时用black格式化代码并整理import、启用flake8代码检查、配置测试框架为pytest并优化了Jupyter笔记本的根目录。4.4 安装代码质量工具在虚拟环境中安装这些工具它们能强制保持代码风格一致提前发现潜在错误。pip install black flake8 isort pytestBlack一个“毫不妥协”的代码格式化工具。运行black .可以一键格式化整个项目。Flake8代码风格和错误检查工具。它会检查PEP8规范、代码复杂度等。isort自动对import语句进行排序和分组。pytest强大的测试框架。配置好后每次保存Python文件VS Code都会自动调用black和isort。你可以在终端运行flake8 src来检查代码问题。4.5 使用pyproject.toml进行现代项目管理替代 requirements.txt对于新项目特别是使用poetry或uv时推荐使用pyproject.toml作为项目配置和依赖管理的核心文件。它比requirements.txt更强大是Python官方推荐的配置格式。一个基本的pyproject.toml示例[project] name my-langchain-project version 0.1.0 description A LangChain-based LLM application. authors [{name Your Name, email youexample.com}] readme README.md requires-python 3.11 dependencies [ langchain0.1.0,0.2.0, openai1.0.0, python-dotenv1.0.0, ] [project.optional-dependencies] dev [ black24.0.0, flake87.0.0, isort5.13.0, pytest8.0.0, ] [build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta [tool.black] line-length 88 target-version [py311] [tool.isort] profile black使用uv安装依赖会非常方便# 安装主依赖 uv pip install -e . # -e 表示可编辑模式对本地包开发有用 # 安装开发依赖 uv pip install -e .[dev]pyproject.toml统一了依赖声明、构建配置和工具配置是更现代的选择。5. 常见问题与排查技巧实录即使按照步骤操作你也可能会遇到一些问题。这里记录了我自己和社区中常见的一些“坑”及其解决方案。5.1 虚拟环境相关问题1激活虚拟环境后命令提示符没有显示(venv)。排查执行which python(或where python)。如果路径指向的是/usr/bin/python或系统Python目录说明激活未成功。解决确保你在项目目录下。对于PowerShell执行策略可能阻止了脚本运行。以管理员身份运行Set-ExecutionPolicy RemoteSigned。尝试使用绝对路径激活.\venv\Scripts\activate(Windows) 或source /full/path/to/venv/bin/activate。有时候终端需要重启。问题2在VS Code中即使选择了正确的解释器运行脚本时仍提示“ModuleNotFoundError: No module named ‘langchain’”。排查VS Code底部状态栏显示的解释器路径是否正确在VS Code的集成终端里执行python --version和pip list看是否在虚拟环境中。解决关闭并重新打开VS Code然后再次选择解释器。在VS Code中按CtrlShiftP运行“Python: Clear Cache and Reload Window”。检查VS Code的集成终端是否自动激活了环境。在设置中确保python.terminal.activateEnvironment为true。5.2 包安装与依赖冲突问题3pip install速度极慢或超时。解决永久方案配置pip使用国内镜像源。创建或修改~/.pip/pip.conf(Linux/macOS) 或C:\Users\YourName\pip\pip.ini(Windows)[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn临时方案在安装命令后加-i参数pip install langchain -i https://pypi.tuna.tsinghua.edu.cn/simple。终极方案使用uv其下载和解析速度有数量级提升。问题4安装某个包时出现版本冲突错误例如 “Cannot install package-a 1.0.0 because it requires package-b 2.0.0, but you have package-b 2.1.0”。解决这是虚拟环境要解决的核心问题。优先尝试创建一个全新的虚拟环境然后按照requirements.txt或pyproject.toml一次性安装所有依赖。pip或uv的解析器会尝试找到一组兼容的版本。手动指定版本如果知道兼容版本可以手动安装pip install package-a1.0.0 package-b1.9.0。使用pip-tools对于复杂依赖可以使用pip-compile(来自pip-tools包) 来编译一个更精确、解决冲突后的requirements.txt。考虑升级有时冲突是因为你依赖的某个库版本太旧。查看是否有更新的版本可以解决冲突。5.3 LLM API连接问题问题5运行测试脚本时出现openai.AuthenticationError或API key not provided。排查检查.env文件是否在项目根目录且文件名正确前面有点。检查.env文件中的OPENAI_API_KEY变量名是否拼写正确值是否正确没有多余空格。在代码中print(os.getenv(‘OPENAI_API_KEY’))看看是否能打印出值调试后记得删除这行。确保load_dotenv()在访问环境变量之前被调用。解决修正.env文件或环境变量。也可以临时在代码中直接设置os.environ[‘OPENAI_API_KEY’] ‘sk-...’进行测试仅限测试切勿提交。问题6连接超时 (openai.APITimeoutError) 或网络错误。解决增加超时时间初始化ChatOpenAI时设置request_timeout30单位秒。检查代理如果你在公司网络或使用代理可能需要配置。OpenAI SDK v1 支持通过http_client参数传递自定义的httpx.Client来设置代理。import httpx from langchain_openai import ChatOpenAI proxy_client httpx.Client(proxieshttp://your-proxy:port) llm ChatOpenAI(http_clientproxy_client, ...)使用Azure OpenAI或其他区域端点如果你使用的是Azure服务或其他地区的代理需要配置base_url和api_key参数。5.4 代码编辑与运行问题问题7VS Code的Python扩展无法识别虚拟环境或者智能提示IntelliSense不工作。解决执行“Python: Select Interpreter”命令强制重新选择。重启VS Code的语言服务器按CtrlShiftP运行“Python: Restart Language Server”。检查Pylance是否已启用并设置为语言服务器。在VS Code设置中搜索python.languageServer确保其值为Pylance。有时需要为项目生成类型存根文件。在包含大量C扩展的包如numpy安装后可以运行python -m pip install --upgrade pip并重启编辑器。问题8想用Jupyter Notebook在VS Code里做实验但内核Kernel找不到虚拟环境中的包。解决在VS Code中打开一个.ipynb文件。点击Notebook右上角显示内核的地方通常显示“Python 3.x.x”或某个环境名。在弹出的选择器中选择“Select Another Kernel…”。然后选择“Python Environments…”并从列表中找到你的项目虚拟环境路径包含venv或.venv。选择后Notebook就会使用该环境的所有已安装包。环境搭建是LLM应用开发的起跑线一个稳固的起跑线能让你在后续的冲刺中毫无后顾之忧。我个人的习惯是每开始一个新项目都会严格走一遍这个流程创建目录、建立虚拟环境、安装核心依赖、配置VS Code、写一个最简单的连通性测试。这个习惯帮我规避了无数环境导致的诡异问题。当你熟悉之后整个过程可能只需要5-10分钟但它为你节省的调试时间可能是以小时甚至天计的。现在你的“工作台”已经就绪接下来就可以尽情地在LangChain的世界里构建属于你的智能体Agent、编排复杂的链Chain或是探索检索增强生成RAG的奥秘了。