第3课：开发环境全套搭建【Python环境、LangChain、LangSmith依赖安装与全局配置】

一、开篇导读

欢迎来到《LangSmith从入门到精通》专栏的第3节课。在前面两节课中，我们已经了解了LangSmith是什么，能做什么，以及如何注册账号、获取API Key、理解计费规则。现在，我们终于可以动手把这一切落实到键盘上了。

许多初学者在正式进入LangChain和LangSmith的学习时，往往在环境配置阶段就花费了大量时间——Python版本号不匹配导致依赖包安装失败、虚拟环境没有做好隔离导致包版本冲突、环境变量没有正确加载导致LangSmith追踪失效……这些问题虽然琐碎，却能耗费数小时甚至一整天。作为一名从2018年开始深耕LLMOps和LangChain生态的工程师，我已无数次在团队培训和项目实战中帮新人跨越这些门槛。

本节课，我将带你用最规范、最高效的方式，从零开始配置一套完整的Python开发环境。

二、知识前置铺垫

2.1 为什么要用虚拟环境

Python开发中有一种情况很常见：你的电脑上同时有项目A和项目B。项目A因为历史原因需要使用LangChain 0.2版本，项目B需要用最新的LangChain 0.3版本。如果没有虚拟环境，这两个项目会因为包版本冲突而无法共存。

虚拟环境本质上是一个独立的Python解释器副本及其关联的包文件夹。每个虚拟环境都有自己独立的site-packages目录，项目之间互不干扰。同时，在虚拟环境中安装和卸载包时，不会影响操作系统的全局Python环境，有效避免了潜在的“污染”风险。

目前主流的Python环境管理工具包括：

• venv：Python3内置，轻量无依赖，是初学者最合适的选择
• conda：适合需要管理非Python依赖的场景（如PyTorch、CUDA等），对环境配置不熟悉的用户有一定门槛
• uv：新一代Rust编写的包管理器，速度极快（比pip快10-100倍），是2026年社区的新趋势

2.2 LangChain与LangSmith的版本关系

LangSmith是LangChain官方的可观测性平台，两者在版本上有紧密的依赖关系。截至2026年初，稳定版本的推荐组合为：

LangSmith SDK要求最低Python版本为3.10，LangChain核心框架同样要求Python 3.10+。强烈建议使用Python 3.11或更高版本进行开发，以获得最佳兼容性和性能表现。

2.3 环境变量在配置中的核心作用

LangSmith的追踪功能主要通过环境变量来控制是否启用。你可以在不修改任何业务代码的前提下，通过环境变量决定是否将链路数据上传到LangSmith平台。这种方式将“代码逻辑”与“运行配置”完全解耦，是生产级LLM应用的标准实践。

关键的环境变量包括：

• LANGSMITH_TRACING或LANGCHAIN_TRACING_V2：追踪开关
• LANGSMITH_API_KEY或LANGCHAIN_API_KEY：API密钥
• LANGSMITH_PROJECT或LANGCHAIN_PROJECT：项目名称

三、核心概念精讲

3.1 什么是Python虚拟环境

Python虚拟环境是一个独立的Python运行环境，它包含特定版本的Python解释器、pip工具，以及一个独立的第三方包安装目录。当你激活虚拟环境后，python和pip命令会自动指向该环境内部的解释器和包管理工具。

3.2 为何推荐使用.env文件管理API密钥

直接在代码中写死API密钥，一旦将代码提交到Git仓库，即使随后删除了密钥，Git的提交历史中仍然会保留完整的密钥记录。更稳妥的做法是：在项目根目录创建.env文件，将LANGSMITH_API_KEY=your_key_here这样的内容写进去，并将.env加入.gitignore文件。在代码中使用python-dotenv库读取该文件即可，既保证了密钥安全，又方便在不同环境间快速切换配置。

3.3 国内用户安装依赖时的网络优化

由于PyPI官方源位于海外，国内用户通过pip install安装时可能遇到速度缓慢或连接超时的问题。此时可以临时使用国内镜像源加速下载。常用的国内镜像源包括清华大学源、阿里云源、豆瓣源等。

3.4 LangSmith SDK的两种工作模式

LangSmith SDK在实际工作中主要有两种模式：追踪模式和离线模式。追踪模式下，SDK会将链路数据通过HTTP请求上报到LangSmith云端；离线模式下，SDK只将数据写入本地文件而不进行上报，主要用于开发和调试环境。

3.5 环境配置的完整检查点

在正式开始编码之前，你需要依次完成以下检查：

• Python版本是否正确
• 虚拟环境是否已创建并激活
• 核心依赖包是否已安装到虚拟环境
• 环境变量是否已正确设置

四、原理底层剖析

4.1 pip install背后的工作流程

当你在终端中输入pip install langsmith时，后台发生了一系列精密的操作。pip工具首先解析用户输入的命令，确定要安装的包名；然后读取本地或远程的索引，找到该包的最新版本信息；接着检查当前环境中是否已安装该包。如果存在依赖冲突，pip会尝试计算解决方案，如果找不到兼容的版本，就会中止安装并报错。

4.2 load_dotenv的加载顺序

Python的os.environ是一个全局的键值对存储。当你在shell中设置export LANGSMITH_API_KEY=xxx时，这个变量就已经存在于os.environ中。而python-dotenv库的load_dotenv()函数的作用是从.env文件中读取键值对，并将其更新到os.environ中（默认不覆盖已存在的变量）。因此，加载顺序遵循“Shell环境变量 > .env文件 > 代码中的默认值”这一优先级规则。理解这一点，对后续排查LangSmith追踪不生效的问题至关重要。

五、环境配置手把手实战

5.1 安装Python（跨平台指南）

Windows系统：

1. 打开浏览器访问 https://www.python.org/downloads/
2. 下载最新版Python 3.11或3.12的Windows installer
3. 运行安装程序，务必勾选“Add Python to PATH”，建议选择“Customize installation”，确保pip工具也被勾选
4. 安装完成后，打开命令提示符，执行python --version确认版本正确，执行pip --version确认pip可用

macOS系统：
使用Homebrew安装是最便捷的方式：

brewinstallpython@3.11# 验证安装python3--versionpip3--version

Linux系统（Ubuntu/Debian）：

sudoaptupdatesudoaptinstallpython3.11 python3.11-venv python3-pip-y# 验证python3--version

5.2 创建项目与虚拟环境

# 创建项目目录mkdirlangsmith-tutorial&&cdlangsmith-tutorial# 使用venv创建虚拟环境python3-mvenv venv# 激活虚拟环境# Windows (cmd):venv\Scripts\activate.bat# Windows (PowerShell):venv\Scripts\Activate.ps1# macOS/Linux:sourcevenv/bin/activate

激活成功后，命令行前缀会显示(venv)，这表示所有后续的python和pip命令都将作用于当前独立的虚拟环境。

5.3 安装LangSmith与LangChain核心依赖

# 首先升级pip到最新版本pipinstall--upgradepip# 安装核心依赖包pipinstalllangchain langchain-openai langsmith python-dotenv# 可选：安装jupyter用于交互式探索pipinstalljupyter

这三个包的职责明确：

• langchain：LangChain核心框架，提供PromptTemplate、Chain等核心组件
• langchain-openai：OpenAI的LangChain集成，用于调用GPT系列模型
• langsmith：LangSmith的Python SDK，负责将追踪数据上报到LangSmith平台

5.4 获取LangSmith API Key

1. 访问 https://smith.langchain.com
2. 登录LangSmith控制台
3. 点击左下角的设置图标（齿轮状），进入Settings页面
4. 在左侧菜单中选择“API Keys”
5. 点击“Create API Key”按钮，填写一个有意义的名称（如dev-key）
6. 复制生成的API Key，格式通常为lsv2_pt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5.5 使用.env文件统一管理环境变量

创建.env文件：
在项目根目录下创建.env文件，内容如下：

# LangSmith配置LANGSMITH_TRACING=trueLANGSMITH_API_KEY=lsv2_pt_你刚刚复制的KeyLANGSMITH_PROJECT=my-first-project# OpenAI配置OPENAI_API_KEY=sk-你的OpenAI Key# 可选：端点配置（默认SaaS版本无需修改）LANGSMITH_ENDPOINT=https://api.smith.langchain.com

务必确保.env文件被加入.gitignore，避免密钥泄露。

5.6 验证环境配置

# 文件名: verify_env.pyimportosfromdotenvimportload_dotenv load_dotenv()defverify_environment():required_vars=["LANGSMITH_API_KEY","OPENAI_API_KEY"]missing=[]forvarinrequired_vars:value=os.getenv(var)ifnotvalue:missing.append(var)else:# 部分显示，避免泄露完整密钥masked=value[:10]+"..."iflen(value)>10else"***"print(f"{var}:{masked}")ifmissing:print(f"\n缺失关键环境变量:{', '.join(missing)}")returnFalse# 检查追踪开关tracing=os.getenv("LANGSMITH_TRACING","false").lower()iftracing=="true":print("追踪开关已启用")else:print("追踪开关未启用，请检查 LANGSMITH_TRACING=true")project=os.getenv("LANGSMITH_PROJECT","default")print(f"当前LangSmith项目:{project}")returnTrueif__name__=="__main__":verify_environment()

执行命令python verify_env.py，如果所有环境变量都已正确配置，你将看到类似“ LANGSMITH_API_KEY: lsv2_pt_xxx… OPENAI_API_KEY: sk-xxx…”的输出。

六、完整可运行代码案例

6.1 第一个带有完整环境配置的LangSmith追踪项目

在完成上述所有配置步骤后，就可以编写第一个带LangSmith追踪的LangChain项目了。

# 文件名: first_trace.py# 说明: 验证LangSmith追踪功能是否正常工作importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_core.output_parsersimportStrOutputParser# 必须在导入LangChain组件之前加载环境变量load_dotenv()defmain():print("="*50)print("第一个LangSmith追踪项目")print("="*50)# 1. 检查环境变量required_vars=["LANGSMITH_API_KEY","OPENAI_API_KEY"]forvarinrequired_vars:ifnotos.getenv(var):print(f"环境变量{var}未设置")returnprint("环境变量检查通过")print(f"LangSmith项目:{os.getenv('LANGSMITH_PROJECT','default')}")# 2. 构建LangChain链路llm=ChatOpenAI(model="gpt-3.5-turbo",temperature=0.7)prompt=ChatPromptTemplate.from_messages([("system","你是一个热情友好的AI助手。"),("human","{input}")])parser=StrOutputParser()chain=prompt|llm|parser# 3. 执行调用print("\n正在调用AI助手...")result=chain.invoke({"input":"什么是LangSmith？请用一句话介绍"})print(f"\nAI回答:\n{result}")print("\n调用完成！")print("请登录LangSmith控制台，在 'my-first-project' 项目中查看本次调用")if__name__=="__main__":main()

6.2 使用uv进行更高效的依赖管理（进阶）

如果你是追求极致开发体验的开发者，可以尝试使用uv这一新一代包管理器。相较于pip，uv在解析依赖时的速度可以快10到100倍。

# 安装uvcurl-LsSfhttps://astral.sh/uv/install.sh|sh# 使用uv创建虚拟环境uv venv--python3.11source.venv/bin/activate# 使用uv安装依赖uv pipinstalllangchain langchain-openai langsmith python-dotenv

6.3 Docker化开发环境配置

对于需要进行私有化部署或希望团队成员拥有完全一致开发环境的企业，可以使用Docker容器化技术快速拉起LangSmith所需的完整依赖。

# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . ENV LANGSMITH_TRACING=true ENV LANGSMITH_ENDPOINT=https://api.smith.langchain.com CMD ["python", "main.py"]

七、代码逐行详解

7.1 环境变量加载的时机

fromdotenvimportload_dotenv load_dotenv()fromlangchain_openaiimportChatOpenAI

在LangChain组件导入之前调用load_dotenv()，确保了LangSmith回调系统在初始化时就能读取到完整的环境变量配置。这是LangSmith追踪能正常工作的关键步骤。如果将load_dotenv()放在导入LangChain之后，LangSmith的回调处理器会在环境变量未加载的情况下就完成了初始化，导致后续一切追踪都无法生效。

7.2 prompt与llm的管道连接

chain=prompt|llm|parser

管道符|是LangChain Expression Language的核心语法。prompt首先接收一个参数字典（如{"input": "..."}），将其渲染成完整的消息列表后传给llm；llm模型根据消息列表返回AIMessage对象；最后parser将其转换为纯字符串。LangSmith会自动捕获这个过程中的每一个组件的输入输出，形成完整的Run追踪树。

八、常见坑点与避坑指南

8.1 环境变量加载时机错误

典型症状：代码运行成功，但LangSmith控制台没有任何新数据出现。

根本原因：LangSmith SDK在导入langchain包时就会初始化回调系统，并读取当时的LANGSMITH_API_KEY等环境变量。

解决方案：务必在Python脚本的最顶部使用load_dotenv()加载环境变量，然后再进行其他模块的导入。如果你使用Jupyter Notebook，建议重启内核后重新顺序执行所有单元格。

8.2 虚拟环境未正确激活

典型症状：执行pip install后，在代码中import langsmith时仍然报错“No module named ‘langsmith’”。

解决方案：

• 检查终端提示符是否显示(venv)。如果未显示，需要先执行激活命令
• 执行which python命令查看当前的Python解释器路径，确认是否指向虚拟环境内部的python
• 如果在PyCharm等IDE中运行，需要先在项目设置中配置正确的Python解释器路径，指向虚拟环境中的python或python.exe

8.3 国内用户网络问题导致的安装失败

典型症状：pip install命令长时间卡住不动，或报错“Read timed out”等网络超时错误。

解决方案：使用国内镜像源加速下载。建议永久配置清华镜像源，避免每次都要手动添加镜像参数：

pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple

也可以临时使用阿里云镜像源安装指定包：

pipinstalllangsmith-ihttps://mirrors.aliyun.com/pypi/simple/

8.4 环境变量在Jupyter Notebook中读取失败

当你使用.env文件在Jupyter Notebook中配置环境变量时，可能会遇到变量读取失败的问题。这是因为Jupyter内核启动时就已经缓存了当时的环境变量，后续修改.env文件不会影响已运行的内核。请务必在修改.env文件后重启Jupyter内核，或使用%load_ext dotenv魔术命令动态加载。

8.5 多个LangSmith项目混淆

如果你设置了LANGSMITH_PROJECT环境变量，所有未显式指定项目名称的追踪数据都会上报到该项目。如果不小心将生产环境的API Key和开发环境的项目名混用，可能导致生产数据意外覆盖开发项目。

在生产级落地中，建议在代码层面通过RunnableConfig的metadata字段显式指定项目名称，彻底规避对全局环境变量的误依赖。

九、企业级落地最佳实践

9.1 使用dotenvx管理多环境配置

在拥有开发、测试、生产等多套配置的团队中，python-dotenv原生的.env文件管理显得不够用。此时可以使用dotenvx这一增强工具管理多套环境配置，实现加密存储和团队共享：

npminstall-g@dotenvx/dotenvx# 创建多环境配置文件cp.env .env.developmentcp.env .env.production

9.2 标准化项目目录结构

可以参考以下标准目录结构：

langsmith-project/ ├── .env # 本地开发配置（不提交） ├── .env.example # 配置模板（提交） ├── .gitignore # 忽略.venv和.env等 ├── requirements.txt # 核心依赖 ├── requirements-dev.txt # 开发依赖 ├── verify_env.py # 环境验证脚本 ├── src/ # 源代码 │ └── __init__.py └── tests/ # 单元测试

9.3 CI/CD流水线中的环境配置

在GitHub Actions中运行时，应将LANGSMITH_API_KEY等敏感信息存放在GitHub Secrets中，并在Workflow中通过环境变量注入：

-name:Run tests with LangSmith tracingenv:LANGSMITH_API_KEY:${{secrets.LANGSMITH_API_KEY}}LANGSMITH_PROJECT:ci-${{github.run_id}}run:|pip install -r requirements.txt pytest tests/

9.4 离线环境部署方案

在内网开发环境中，无法直接访问PyPI仓库。可以通过以下两种方式解决：一是搭建公司内部私有PyPI镜像仓库，提前同步所有依赖包；二是使用Docker离线镜像导出导入的方式传递完整环境。

十、本节知识点总结

十一、课后思考练习题

练习题1：理论理解

1.1你正在参与一个LangChain项目的开发，同事小王无意中将包含真实API Key的.env文件提交到了公司内部的Git仓库。虽然仓库是私有的，但公司安全规定要求所有API Key必须定期轮换。请分析这种行为可能带来的风险，并设计一套后续处理的行动方案，包括但不限于：如何撤销已泄露的Key、如何从Git历史中清理该文件、如何建立后续防范机制。

1.2LangSmith的追踪功能通过环境变量控制开启和关闭，而非直接在代码中调用langsmith.enable_tracing()。请从“关注点分离”的角度，分析这种设计对LLM应用开发和运维带来的实际好处。

1.3在国内网络环境下直接使用pip install langsmith可能因下载速度慢而超时。请列举至少三种加速安装的可行方案，并分析每种方案的优缺点。

1.4假设你在同一台开发机上需要同时维护多个LangChain项目，项目A依赖langchain 0.2版本，项目B依赖langchain 0.3版本。请设计一套完整的环境管理方案，确保两个项目的开发互不干扰。

练习题2：动手实践

2.1在你的本地机器上完成以下操作：

• 创建一个全新的虚拟环境，命名为langsmith_homework
• 在虚拟环境中安装langchain、langsmith、langchain-openai三个包
• 将当前虚拟环境中所有已安装的包导出到requirements_hw.txt文件中
• 验证使用requirements_hw.txt文件能否在全新的虚拟环境中完整重建依赖

2.2编写一个环境配置诊断脚本env_checker.py，要求能够主动检查以下项目：

• 当前Python版本是否符合要求
• 当前是否在虚拟环境中运行
• 必选依赖包langchain、langsmith、langchain-openai是否已正确安装及其版本号
• LANGSMITH_API_KEY和OPENAI_API_KEY是否已正确设置
• LANGSMITH_TRACING开关是否已启用
• 能否向LangSmith服务端发送一个简单的测试追踪请求（可以是一个最简单的chain.invoke()调用）

练习题3：场景设计

3.1你的团队新加入了一位实习生，你需要为他搭建一套标准化的LangSmith开发环境。请撰写一份不超过一页A4纸的操作手册，内容应涵盖：Python与虚拟环境的创建、依赖包的安装、LangSmith API Key的获取与配置、环境验证，以及常见问题的排查步骤。

3.2公司网络策略要求所有外部HTTP/HTTPS请求都必须通过一个认证代理服务器（proxy.company.com:8080，需要用户名和密码）。请给出在pip安装依赖时、以及在LangSmith SDK上报追踪数据时，完成代理配置的完整技术方案（包括命令行配置和Python代码级配置）。

练习题4：源码分析（选做）

4.1阅读LangSmith Python SDK的源码（位于GitHub仓库langchain-ai/langsmith-sdk），重点分析Client类在初始化时如何读取环境变量。尝试回答：代码中是优先读取LANGSMITH_API_KEY还是LANGCHAIN_API_KEY？两者同时存在时谁优先生效？LANGSMITH_ENDPOINT默认值是在代码中硬编码的还是通过其他方式定义的？

4.2分析python-dotenv库的源码，回答以下问题：当.env文件中某一行出现KEY=value # comment with = sign时，库是如何正确解析变量名和变量值的？如果一行中引用了另一个环境变量（如API_KEY=${APP_ID}_secret），代码是如何实现变量嵌套展开的？

下节课预告：

第4节课我们将系统拆解LangSmith的五大核心概念——Trace、Run、Project、Session、Tag。从官方定义出发，结合原理剖析和大量实战代码，透彻厘清这些概念之间的关系，以及如何在实际项目中高效运用它们。请确保你的开发环境已配置完成，下节课将基于本课的环境运行大量实践代码。

🔗《20节课 LangSmith 从入门到精通》系列课程导航

去订阅

🌟 感谢您耐心阅读到这里！
💡 如果本文对您有所启发欢迎：
👍 点赞📌 收藏 📤 分享给更多需要的伙伴。
🗣️ 期待在评论区看到您的想法, 共同进步。
🔔 关注我，持续获取更多干货内容～
🤗 我们下篇文章见～