文章目录一、开篇导读二、知识前置铺垫2.1 为什么要用虚拟环境2.2 LangChain与LangSmith的版本关系2.3 环境变量在配置中的核心作用三、核心概念精讲3.1 什么是Python虚拟环境3.2 为何推荐使用.env文件管理API密钥3.3 国内用户安装依赖时的网络优化3.4 LangSmith SDK的两种工作模式3.5 环境配置的完整检查点四、原理底层剖析4.1 pip install背后的工作流程4.2 load_dotenv的加载顺序五、环境配置手把手实战5.1 安装Python跨平台指南5.2 创建项目与虚拟环境5.3 安装LangSmith与LangChain核心依赖5.4 获取LangSmith API Key5.5 使用.env文件统一管理环境变量5.6 验证环境配置六、完整可运行代码案例6.1 第一个带有完整环境配置的LangSmith追踪项目6.2 使用uv进行更高效的依赖管理进阶6.3 Docker化开发环境配置七、代码逐行详解7.1 环境变量加载的时机7.2 prompt与llm的管道连接八、常见坑点与避坑指南8.1 环境变量加载时机错误8.2 虚拟环境未正确激活8.3 国内用户网络问题导致的安装失败8.4 环境变量在Jupyter Notebook中读取失败8.5 多个LangSmith项目混淆九、企业级落地最佳实践9.1 使用dotenvx管理多环境配置9.2 标准化项目目录结构9.3 CI/CD流水线中的环境配置9.4 离线环境部署方案十、本节知识点总结十一、课后思考练习题练习题1理论理解练习题2动手实践练习题3场景设计练习题4源码分析选做《20节课 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环境管理工具包括venvPython3内置轻量无依赖是初学者最合适的选择conda适合需要管理非Python依赖的场景如PyTorch、CUDA等对环境配置不熟悉的用户有一定门槛uv新一代Rust编写的包管理器速度极快比pip快10-100倍是2026年社区的新趋势2.2 LangChain与LangSmith的版本关系LangSmith是LangChain官方的可观测性平台两者在版本上有紧密的依赖关系。截至2026年初稳定版本的推荐组合为包名推荐版本Python要求备注langchain0.3.0Python 3.10核心框架langchain-core0.3.0Python 3.10核心抽象层langchain-openai0.2.0Python 3.10OpenAI集成langsmith0.1.99Python 3.10追踪SDK需要0.1.99以上以获得最佳兼容性LangSmith SDK要求最低Python版本为3.10LangChain核心框架同样要求Python 3.10。强烈建议使用Python 3.11或更高版本进行开发以获得最佳兼容性和性能表现。2.3 环境变量在配置中的核心作用LangSmith的追踪功能主要通过环境变量来控制是否启用。你可以在不修改任何业务代码的前提下通过环境变量决定是否将链路数据上传到LangSmith平台。这种方式将“代码逻辑”与“运行配置”完全解耦是生产级LLM应用的标准实践。关键的环境变量包括LANGSMITH_TRACING或LANGCHAIN_TRACING_V2追踪开关LANGSMITH_API_KEY或LANGCHAIN_API_KEYAPI密钥LANGSMITH_PROJECT或LANGCHAIN_PROJECT项目名称三、核心概念精讲3.1 什么是Python虚拟环境Python虚拟环境是一个独立的Python运行环境它包含特定版本的Python解释器、pip工具以及一个独立的第三方包安装目录。当你激活虚拟环境后python和pip命令会自动指向该环境内部的解释器和包管理工具。3.2 为何推荐使用.env文件管理API密钥直接在代码中写死API密钥一旦将代码提交到Git仓库即使随后删除了密钥Git的提交历史中仍然会保留完整的密钥记录。更稳妥的做法是在项目根目录创建.env文件将LANGSMITH_API_KEYyour_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_KEYxxx时这个变量就已经存在于os.environ中。而python-dotenv库的load_dotenv()函数的作用是从.env文件中读取键值对并将其更新到os.environ中默认不覆盖已存在的变量。因此加载顺序遵循“Shell环境变量 .env文件 代码中的默认值”这一优先级规则。理解这一点对后续排查LangSmith追踪不生效的问题至关重要。五、环境配置手把手实战5.1 安装Python跨平台指南Windows系统打开浏览器访问 https://www.python.org/downloads/下载最新版Python 3.11或3.12的Windows installer运行安装程序务必勾选“Add Python to PATH”建议选择“Customize installation”确保pip工具也被勾选安装完成后打开命令提示符执行python --version确认版本正确执行pip --version确认pip可用macOS系统使用Homebrew安装是最便捷的方式brewinstallpython3.11# 验证安装python3--versionpip3--versionLinux系统Ubuntu/Debiansudoaptupdatesudoaptinstallpython3.11 python3.11-venv python3-pip-y# 验证python3--version5.2 创建项目与虚拟环境# 创建项目目录mkdirlangsmith-tutorialcdlangsmith-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这三个包的职责明确langchainLangChain核心框架提供PromptTemplate、Chain等核心组件langchain-openaiOpenAI的LangChain集成用于调用GPT系列模型langsmithLangSmith的Python SDK负责将追踪数据上报到LangSmith平台5.4 获取LangSmith API Key访问 https://smith.langchain.com登录LangSmith控制台点击左下角的设置图标齿轮状进入Settings页面在左侧菜单中选择“API Keys”点击“Create API Key”按钮填写一个有意义的名称如dev-key复制生成的API Key格式通常为lsv2_pt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5.5 使用.env文件统一管理环境变量创建.env文件在项目根目录下创建.env文件内容如下# LangSmith配置LANGSMITH_TRACINGtrueLANGSMITH_API_KEYlsv2_pt_你刚刚复制的KeyLANGSMITH_PROJECTmy-first-project# OpenAI配置OPENAI_API_KEYsk-你的OpenAI Key# 可选端点配置默认SaaS版本无需修改LANGSMITH_ENDPOINThttps://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:valueos.getenv(var)ifnotvalue:missing.append(var)else:# 部分显示避免泄露完整密钥maskedvalue[:10]...iflen(value)10else***print(f{var}:{masked})ifmissing:print(f\n缺失关键环境变量:{, .join(missing)})returnFalse# 检查追踪开关tracingos.getenv(LANGSMITH_TRACING,false).lower()iftracingtrue:print(追踪开关已启用)else:print(追踪开关未启用请检查 LANGSMITH_TRACINGtrue)projectos.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(fLangSmith项目:{os.getenv(LANGSMITH_PROJECT,default)})# 2. 构建LangChain链路llmChatOpenAI(modelgpt-3.5-turbo,temperature0.7)promptChatPromptTemplate.from_messages([(system,你是一个热情友好的AI助手。),(human,{input})])parserStrOutputParser()chainprompt|llm|parser# 3. 执行调用print(\n正在调用AI助手...)resultchain.invoke({input:什么是LangSmith请用一句话介绍})print(f\nAI回答:\n{result})print(\n调用完成)print(请登录LangSmith控制台在 my-first-project 项目中查看本次调用)if__name____main__:main()6.2 使用uv进行更高效的依赖管理进阶如果你是追求极致开发体验的开发者可以尝试使用uv这一新一代包管理器。相较于pipuv在解析依赖时的速度可以快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-dotenv6.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_TRACINGtrue ENV LANGSMITH_ENDPOINThttps://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的管道连接chainprompt|llm|parser管道符|是LangChain Expression Language的核心语法。prompt首先接收一个参数字典如{input: ...}将其渲染成完整的消息列表后传给llmllm模型根据消息列表返回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.exe8.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-gdotenvx/dotenvx# 创建多环境配置文件cp.env .env.developmentcp.env .env.production9.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离线镜像导出导入的方式传递完整环境。十、本节知识点总结知识点类别核心内容实践要点Python环境Python 3.10推荐3.11三个操作系统的安装方式、版本验证虚拟环境venv、conda、uv项目隔离、避免全局污染依赖管理langchain、langchain-openai、langsmith版本兼容性、网络加速技巧环境变量.env文件、python-dotenvAPI Key安全管理、加载时机追踪配置LANGSMITH_TRACING、LANGSMITH_API_KEY等开关控制、项目划分验证机制环境验证脚本主动检查缺失变量企业实践dotenvx多环境、标准目录结构、CI/CD注入团队协作、自动流水线十一、课后思考练习题练习题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文件中某一行出现KEYvalue # comment with sign时库是如何正确解析变量名和变量值的如果一行中引用了另一个环境变量如API_KEY${APP_ID}_secret代码是如何实现变量嵌套展开的下节课预告第4节课我们将系统拆解LangSmith的五大核心概念——Trace、Run、Project、Session、Tag。从官方定义出发结合原理剖析和大量实战代码透彻厘清这些概念之间的关系以及如何在实际项目中高效运用它们。请确保你的开发环境已配置完成下节课将基于本课的环境运行大量实践代码。《20节课 LangSmith 从入门到精通》系列课程导航去订阅 感谢您耐心阅读到这里 如果本文对您有所启发欢迎 点赞 收藏 分享给更多需要的伙伴。️ 期待在评论区看到您的想法, 共同进步。 关注我持续获取更多干货内容 我们下篇文章见
第3课：开发环境全套搭建【Python环境、LangChain、LangSmith依赖安装与全局配置】
发布时间：2026/6/7 23:49:17
文章目录一、开篇导读二、知识前置铺垫2.1 为什么要用虚拟环境2.2 LangChain与LangSmith的版本关系2.3 环境变量在配置中的核心作用三、核心概念精讲3.1 什么是Python虚拟环境3.2 为何推荐使用.env文件管理API密钥3.3 国内用户安装依赖时的网络优化3.4 LangSmith SDK的两种工作模式3.5 环境配置的完整检查点四、原理底层剖析4.1 pip install背后的工作流程4.2 load_dotenv的加载顺序五、环境配置手把手实战5.1 安装Python跨平台指南5.2 创建项目与虚拟环境5.3 安装LangSmith与LangChain核心依赖5.4 获取LangSmith API Key5.5 使用.env文件统一管理环境变量5.6 验证环境配置六、完整可运行代码案例6.1 第一个带有完整环境配置的LangSmith追踪项目6.2 使用uv进行更高效的依赖管理进阶6.3 Docker化开发环境配置七、代码逐行详解7.1 环境变量加载的时机7.2 prompt与llm的管道连接八、常见坑点与避坑指南8.1 环境变量加载时机错误8.2 虚拟环境未正确激活8.3 国内用户网络问题导致的安装失败8.4 环境变量在Jupyter Notebook中读取失败8.5 多个LangSmith项目混淆九、企业级落地最佳实践9.1 使用dotenvx管理多环境配置9.2 标准化项目目录结构9.3 CI/CD流水线中的环境配置9.4 离线环境部署方案十、本节知识点总结十一、课后思考练习题练习题1理论理解练习题2动手实践练习题3场景设计练习题4源码分析选做《20节课 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环境管理工具包括venvPython3内置轻量无依赖是初学者最合适的选择conda适合需要管理非Python依赖的场景如PyTorch、CUDA等对环境配置不熟悉的用户有一定门槛uv新一代Rust编写的包管理器速度极快比pip快10-100倍是2026年社区的新趋势2.2 LangChain与LangSmith的版本关系LangSmith是LangChain官方的可观测性平台两者在版本上有紧密的依赖关系。截至2026年初稳定版本的推荐组合为包名推荐版本Python要求备注langchain0.3.0Python 3.10核心框架langchain-core0.3.0Python 3.10核心抽象层langchain-openai0.2.0Python 3.10OpenAI集成langsmith0.1.99Python 3.10追踪SDK需要0.1.99以上以获得最佳兼容性LangSmith SDK要求最低Python版本为3.10LangChain核心框架同样要求Python 3.10。强烈建议使用Python 3.11或更高版本进行开发以获得最佳兼容性和性能表现。2.3 环境变量在配置中的核心作用LangSmith的追踪功能主要通过环境变量来控制是否启用。你可以在不修改任何业务代码的前提下通过环境变量决定是否将链路数据上传到LangSmith平台。这种方式将“代码逻辑”与“运行配置”完全解耦是生产级LLM应用的标准实践。关键的环境变量包括LANGSMITH_TRACING或LANGCHAIN_TRACING_V2追踪开关LANGSMITH_API_KEY或LANGCHAIN_API_KEYAPI密钥LANGSMITH_PROJECT或LANGCHAIN_PROJECT项目名称三、核心概念精讲3.1 什么是Python虚拟环境Python虚拟环境是一个独立的Python运行环境它包含特定版本的Python解释器、pip工具以及一个独立的第三方包安装目录。当你激活虚拟环境后python和pip命令会自动指向该环境内部的解释器和包管理工具。3.2 为何推荐使用.env文件管理API密钥直接在代码中写死API密钥一旦将代码提交到Git仓库即使随后删除了密钥Git的提交历史中仍然会保留完整的密钥记录。更稳妥的做法是在项目根目录创建.env文件将LANGSMITH_API_KEYyour_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_KEYxxx时这个变量就已经存在于os.environ中。而python-dotenv库的load_dotenv()函数的作用是从.env文件中读取键值对并将其更新到os.environ中默认不覆盖已存在的变量。因此加载顺序遵循“Shell环境变量 .env文件 代码中的默认值”这一优先级规则。理解这一点对后续排查LangSmith追踪不生效的问题至关重要。五、环境配置手把手实战5.1 安装Python跨平台指南Windows系统打开浏览器访问 https://www.python.org/downloads/下载最新版Python 3.11或3.12的Windows installer运行安装程序务必勾选“Add Python to PATH”建议选择“Customize installation”确保pip工具也被勾选安装完成后打开命令提示符执行python --version确认版本正确执行pip --version确认pip可用macOS系统使用Homebrew安装是最便捷的方式brewinstallpython3.11# 验证安装python3--versionpip3--versionLinux系统Ubuntu/Debiansudoaptupdatesudoaptinstallpython3.11 python3.11-venv python3-pip-y# 验证python3--version5.2 创建项目与虚拟环境# 创建项目目录mkdirlangsmith-tutorialcdlangsmith-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这三个包的职责明确langchainLangChain核心框架提供PromptTemplate、Chain等核心组件langchain-openaiOpenAI的LangChain集成用于调用GPT系列模型langsmithLangSmith的Python SDK负责将追踪数据上报到LangSmith平台5.4 获取LangSmith API Key访问 https://smith.langchain.com登录LangSmith控制台点击左下角的设置图标齿轮状进入Settings页面在左侧菜单中选择“API Keys”点击“Create API Key”按钮填写一个有意义的名称如dev-key复制生成的API Key格式通常为lsv2_pt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5.5 使用.env文件统一管理环境变量创建.env文件在项目根目录下创建.env文件内容如下# LangSmith配置LANGSMITH_TRACINGtrueLANGSMITH_API_KEYlsv2_pt_你刚刚复制的KeyLANGSMITH_PROJECTmy-first-project# OpenAI配置OPENAI_API_KEYsk-你的OpenAI Key# 可选端点配置默认SaaS版本无需修改LANGSMITH_ENDPOINThttps://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:valueos.getenv(var)ifnotvalue:missing.append(var)else:# 部分显示避免泄露完整密钥maskedvalue[:10]...iflen(value)10else***print(f{var}:{masked})ifmissing:print(f\n缺失关键环境变量:{, .join(missing)})returnFalse# 检查追踪开关tracingos.getenv(LANGSMITH_TRACING,false).lower()iftracingtrue:print(追踪开关已启用)else:print(追踪开关未启用请检查 LANGSMITH_TRACINGtrue)projectos.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(fLangSmith项目:{os.getenv(LANGSMITH_PROJECT,default)})# 2. 构建LangChain链路llmChatOpenAI(modelgpt-3.5-turbo,temperature0.7)promptChatPromptTemplate.from_messages([(system,你是一个热情友好的AI助手。),(human,{input})])parserStrOutputParser()chainprompt|llm|parser# 3. 执行调用print(\n正在调用AI助手...)resultchain.invoke({input:什么是LangSmith请用一句话介绍})print(f\nAI回答:\n{result})print(\n调用完成)print(请登录LangSmith控制台在 my-first-project 项目中查看本次调用)if__name____main__:main()6.2 使用uv进行更高效的依赖管理进阶如果你是追求极致开发体验的开发者可以尝试使用uv这一新一代包管理器。相较于pipuv在解析依赖时的速度可以快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-dotenv6.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_TRACINGtrue ENV LANGSMITH_ENDPOINThttps://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的管道连接chainprompt|llm|parser管道符|是LangChain Expression Language的核心语法。prompt首先接收一个参数字典如{input: ...}将其渲染成完整的消息列表后传给llmllm模型根据消息列表返回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.exe8.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-gdotenvx/dotenvx# 创建多环境配置文件cp.env .env.developmentcp.env .env.production9.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离线镜像导出导入的方式传递完整环境。十、本节知识点总结知识点类别核心内容实践要点Python环境Python 3.10推荐3.11三个操作系统的安装方式、版本验证虚拟环境venv、conda、uv项目隔离、避免全局污染依赖管理langchain、langchain-openai、langsmith版本兼容性、网络加速技巧环境变量.env文件、python-dotenvAPI Key安全管理、加载时机追踪配置LANGSMITH_TRACING、LANGSMITH_API_KEY等开关控制、项目划分验证机制环境验证脚本主动检查缺失变量企业实践dotenvx多环境、标准目录结构、CI/CD注入团队协作、自动流水线十一、课后思考练习题练习题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文件中某一行出现KEYvalue # comment with sign时库是如何正确解析变量名和变量值的如果一行中引用了另一个环境变量如API_KEY${APP_ID}_secret代码是如何实现变量嵌套展开的下节课预告第4节课我们将系统拆解LangSmith的五大核心概念——Trace、Run、Project、Session、Tag。从官方定义出发结合原理剖析和大量实战代码透彻厘清这些概念之间的关系以及如何在实际项目中高效运用它们。请确保你的开发环境已配置完成下节课将基于本课的环境运行大量实践代码。《20节课 LangSmith 从入门到精通》系列课程导航去订阅 感谢您耐心阅读到这里 如果本文对您有所启发欢迎 点赞 收藏 分享给更多需要的伙伴。️ 期待在评论区看到您的想法, 共同进步。 关注我持续获取更多干货内容 我们下篇文章见
)
