LangChain 学习记录 02环境准备与第一个 LangChain 程序本文适合准备正式动手写 LangChain 代码的同学。关键词LangChain、Python、uv、虚拟环境、pyproject.toml、uv.lock、API Key、ChatOpenAI摘要学习 LangChain 的第一道坎往往不是模型调用而是环境配置。很多初学者会在这里被几个词绕晕conda、venv、pip、uv、pyproject.toml、uv.lock、.env它们到底是什么关系为什么课程里推荐用uvAPI Key 应该放在哪里第一个 LangChain 程序怎么跑本文会按“能真正跑起来”的顺序讲清楚Python 项目为什么需要虚拟环境conda、venv、pip、uv的区别如何用uv创建 LangChain 项目LangChain 常见包结构怎么理解.env如何安全管理 API Key如何写第一个 LangChain 模型调用程序一句话概括环境准备的目标是让项目依赖可隔离、可复现、密钥不泄露、代码能稳定运行。文章目录LangChain 学习记录 02环境准备与第一个 LangChain 程序摘要一、环境准备到底在准备什么1. Python 版本2. 项目依赖3. API Key二、环境搭建流程图三、conda、venv、pip、uv 是什么关系1. venv2. pip3. conda4. uv对比表四、为什么推荐用 uv1. 安装依赖快2. 自动维护 pyproject.toml3. 自动生成 uv.lock4. 项目管理更清晰五、LangChain 包结构怎么理解六、安装 uvWindows PowerShellmacOS / Linux七、创建项目并安装 LangChain1. 创建项目2. 指定 Python 版本3. 安装 LangChain 核心包4. 安装 OpenAI 集成5. 安装 dotenv 支持八、理解 pyproject.toml、uv.lock 和 .venv1. pyproject.toml购物清单2. uv.lock收银小票3. .venv项目冰箱九、配置 API Key 和环境变量1. 创建 .env2. 把 .env 加进 .gitignore3. 在代码中读取 .env十、第一个 LangChain 程序用 init_chat_model 的写法十一、常见坑1. Python 版本太低2. 装错 dotenv 包3. 忘记加载 .env4. base_url 写错5. API Key 写进代码6. 终端位置不对十二、小结参考资料一、环境准备到底在准备什么正式写代码前我们至少要解决三个问题。1. Python 版本LangChain 当前 Python 文档要求Python 3.10课程里推荐使用 Python 3.12是一个比较舒服的选择。2. 项目依赖LangChain 不是一个单独的大包打天下而是按功能拆分成多个包。例如langchain langchain-core langchain-openai langchain-anthropic langchain-community langchain-chroma你用到哪个模型或能力就安装对应包。3. API Key调用大模型通常需要密钥。API Key 不能直接写死在代码里否则容易泄露。更推荐写进 .env 文件 代码通过环境变量读取 .env 加入 .gitignore这三个问题解决好项目才算有一个比较稳的起点。二、环境搭建流程图先看一张图。完整流程可以理解成确认 Python 版本 ↓ 安装 uv ↓ 创建项目和虚拟环境 ↓ 安装 LangChain 相关包 ↓ 配置 .env ↓ 运行第一个程序如果这个流程顺了后面学习 Prompt、Parser、Chain 就不会被环境问题反复打断。三、conda、venv、pip、uv 是什么关系很多同学第一次看到这些词会感觉像进了 Python 工具动物园。其实它们主要解决两个问题1. 环境隔离 2. 包安装与依赖管理1. venvvenv是 Python 自带的虚拟环境工具。作用给每个项目创建一个独立环境避免依赖互相污染。比如项目 A 需要langchain0.x项目 B 需要langchain1.x如果没有虚拟环境两个项目可能互相影响。2. pippip是 Python 的包安装工具。作用从 PyPI 安装第三方库。例如pipinstalllangchainvenv pip是 Python 传统组合。能用但依赖锁定、速度和项目管理体验一般。3. condaconda是更大的环境管理工具。它不仅能管理 Python 包还能管理一些非 Python 依赖比如 CUDA、C/C 库等。适合深度学习、科学计算、需要复杂底层依赖的项目。但它也有缺点体积较大依赖解析较慢对纯 Python 项目来说有时显得重4. uvuv是新一代 Python 包和项目管理工具速度非常快。它可以做很多事创建项目创建虚拟环境安装依赖锁定依赖版本管理 Python 版本运行项目命令课程里推荐uv因为 LangChain 的依赖主要来自 PyPI用uv会很顺。对比表工具主要作用优点适合场景venv创建虚拟环境Python 内置简单项目pip安装包最基础、最通用小脚本、传统项目conda环境和非 Python 依赖管理能管理 CUDA 等复杂依赖深度学习、科学计算uv项目、环境、依赖、锁文件管理快、现代、可复现LangChain 课程项目一句话记忆venv 管环境pip 装包conda 什么都管但比较重uv 又快又适合现代 Python 项目。四、为什么推荐用 uv课程推荐用uv主要有几个原因。1. 安装依赖快uv使用 Rust 编写依赖解析和安装速度很快。对 LangChain 这种依赖较多的项目体验会明显好一些。2. 自动维护 pyproject.toml使用uvaddlangchain它会自动把依赖写入pyproject.toml不用你手动维护依赖列表。3. 自动生成 uv.lockuv.lock会记录所有包的精确版本包括间接依赖。这样别人拿到你的项目后可以复现同样的环境。4. 项目管理更清晰一个标准项目大概是langchain-demo/ ├── .venv/ ├── pyproject.toml ├── uv.lock ├── .env ├── .gitignore └── main.py比起到处手动pip install这更像一个正式项目。五、LangChain 包结构怎么理解LangChain 的包不是一个“全家桶必须全装”。它更像按功能拆开的积木。分类包名说明核心包langchain主包安装常用能力核心抽象langchain-coreRunnable、Prompt、Parser 等基础抽象OpenAI 集成langchain-openai调用 OpenAI 兼容模型Anthropic 集成langchain-anthropic调用 Claude 系列Google 集成langchain-google-genai调用 GeminiOllama 集成langchain-ollama调用本地 Ollama 模型DeepSeek 集成langchain-deepseek调用 DeepSeek社区集成langchain-community社区维护的加载器、工具等向量库集成langchain-chromaChroma 向量数据库支持安装原则只安装你用到的包。比如你只用 OpenAI 兼容接口uvaddlangchain langchain-openai如果后面要用 Chromauvaddlangchain-chroma不用一开始把所有包都装上。六、安装 uvWindows PowerShellpowershell-ExecutionPolicy ByPass-cirm https://astral.sh/uv/install.ps1 | iex安装完成后验证uv--versionmacOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh验证uv--version如果能看到版本号就说明安装成功。七、创建项目并安装 LangChain下面是一套推荐流程。1. 创建项目uv init langchain-democdlangchain-demo如果你已经在项目目录里也可以直接uv init2. 指定 Python 版本推荐uv python pin3.12说明LangChain 要求 Python 3.10课程中推荐 3.12。3. 安装 LangChain 核心包uvaddlangchain4. 安装 OpenAI 集成uvaddlangchain-openai5. 安装 dotenv 支持uvaddpython-dotenv注意包名是python-dotenv代码里导入时才是fromdotenvimportload_dotenv这是很多新手会踩的坑。八、理解 pyproject.toml、uv.lock 和 .venv执行uv add后项目里会出现几个重要文件。1. pyproject.toml购物清单pyproject.toml记录项目基本信息和直接依赖。比如[project] name langchain-demo version 0.1.0 requires-python 3.12 dependencies [ langchain, langchain-openai, python-dotenv, ]你可以把它理解成我这个项目需要哪些东西。一般不需要手动改依赖使用uvadd包名 uv remove 包名让 uv 自动维护。2. uv.lock收银小票uv.lock记录所有实际安装包的精确版本。包括你直接安装的包也包括它们依赖的包。它解决的是环境可复现。你把pyproject.toml和uv.lock给同学同学执行同步命令就能得到接近一致的环境。3. .venv项目冰箱.venv是虚拟环境目录。里面装的是当前项目实际使用的 Python 包。它不应该提交到 Git。.gitignore里通常要有.venv/ .env简单比喻文件类比是否提交 Gitpyproject.toml购物清单提交uv.lock收银小票提交.venv/冰箱里的实物不提交.env密码本不提交这个比喻非常实用。毕竟谁也不会把自家密码本贴到公告栏上除非今天特别想给自己找点刺激。九、配置 API Key 和环境变量调用模型需要 API Key。推荐使用.env文件。1. 创建 .env在项目根目录创建.env写入OPENAI_API_KEYsk-your-api-key OPENAI_BASE_URLhttps://api.openai.com/v1如果你使用 OpenAI 兼容平台也通常是改OPENAI_BASE_URL你的平台 base_url OPENAI_API_KEY你的平台 api_key注意不同平台的 API Key、模型名、base_url 可能不同要以对应平台文档为准。2. 把 .env 加进 .gitignore.env这一点非常重要。不要把密钥提交到 GitHub、Gitee 或 CSDN 示例仓库里。API Key 泄露之后轻则额度被刷重则账号风险。这不是危言耸听是很多人用真金白银交过的学费。3. 在代码中读取 .envfromdotenvimportload_dotenvimportos load_dotenv()api_keyos.getenv(OPENAI_API_KEY)base_urlos.getenv(OPENAI_BASE_URL)print(api_key)print(base_url)正式项目里不要打印完整 API Key。调试时最多打印前后几位确认读取到了即可。十、第一个 LangChain 程序创建main.pyimportosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAI load_dotenv()llmChatOpenAI(modelgpt-4o-mini,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL,https://api.openai.com/v1),)responsellm.invoke(你好请用一句话介绍 Python。)print(response.content)运行uv run python main.py如果配置正确你会看到模型返回类似Python 是一种语法简洁、应用广泛的高级编程语言。用 init_chat_model 的写法LangChain 也提供了统一初始化模型的方式fromdotenvimportload_dotenvfromlangchain.chat_modelsimportinit_chat_model load_dotenv()modelinit_chat_model(openai:gpt-4o-mini)responsemodel.invoke(你好请用一句话介绍 LangChain。)print(response.content)这种写法适合统一初始化不同模型。不过学习阶段用ChatOpenAI更直观因为你能清楚看到模型名、api_key、base_url这些配置是怎么传进去的。十一、常见坑1. Python 版本太低如果 Python 版本低于 3.10可能会遇到安装或运行问题。检查python--version或者uv run python--version2. 装错 dotenv 包正确安装uvaddpython-dotenv代码导入fromdotenvimportload_dotenv不要装成uvadddotenv3. 忘记加载 .env如果你写了.env但代码里没写load_dotenv()那么os.getenv(OPENAI_API_KEY)可能读不到。4. base_url 写错如果你使用非官方或 OpenAI 兼容平台base_url必须按平台要求填写。常见错误少了 /v1 多了空格 协议 http/https 写错 平台不兼容当前模型名5. API Key 写进代码不要这样llmChatOpenAI(api_keysk-xxxx)更推荐api_keyos.getenv(OPENAI_API_KEY)代码可以分享密钥不能分享。6. 终端位置不对运行命令时要在项目根目录。也就是包含这些文件的目录pyproject.toml uv.lock .env main.py否则.env可能加载不到依赖也可能找不到。十二、小结这一篇主要完成了 LangChain 的环境准备。你需要记住Python 版本推荐 3.10课程用 3.12。 uv负责项目、虚拟环境、依赖和锁文件。 pyproject.toml记录项目需要什么。 uv.lock记录实际安装了什么。 .venv当前项目的虚拟环境。 .env保存 API Key不提交 Git。第一段 LangChain 程序的核心是llmChatOpenAI(modelgpt-4o-mini)responsellm.invoke(你好)print(response.content)从这一刻开始你已经不只是“配置环境”而是真的把 LangChain 跑起来了。下一篇继续学习Model I/O 模型调用。也就是更系统地理解模型、消息、参数、流式输出和多模型切换。参考资料LangChain 安装文档https://docs.langchain.com/oss/python/langchain/installLangChain Python 官方文档https://docs.langchain.com/oss/python/langchainuv 官方文档https://docs.astral.sh/uv/python-dotenv 文档https://saurabh-kumar.com/python-dotenv/