从零开始一步一步完成本课程所需的所有环境配置。一、安装 MinicondaConda 是一个包管理和环境管理工具。Miniconda是 Conda 的精简版只包含最基本的组件体积小、安装快推荐使用。1.1 下载 Miniconda打开 Miniconda 官方下载页面https://docs.anaconda.com/miniconda/根据操作系统选择对应版本操作系统推荐安装包WindowsMiniconda3 Windows 64-bit.exe 安装包macOSMiniconda3 macOS Apple M1 64-bitApple 芯片或macOS Intel x86 64-bitIntel 芯片LinuxMiniconda3 Linux 64-bit.sh 脚本注意Miniconda 自带 Python 3.13本课程也使用 Python 3.13无需额外调整。1.2 Windows 安装步骤双击下载的Miniconda3-windows-*.exe启动安装向导点击Next→ 选择Just Me (recommended)→ Next安装路径建议保持默认如C:\Users\你的用户名\miniconda3点击 Next关键步骤勾选以下两项✅Add Miniconda3 to my PATH environment variable将 Conda 加入系统 PATH✅Register Miniconda3 as my default Python 3.x设为默认 Python点击 Install等待安装完成安装完成后打开Anaconda Prompt (miniconda3)从开始菜单搜索验证安装是否成功conda--version# 输出类似conda 26.x.x1.3 macOS 安装步骤# 在终端中执行以 Apple M1 芯片为例bash~/Downloads/Miniconda3-latest-MacOSX-arm64.sh# 按提示操作# - 按 Enter 阅读协议# - 输入 yes 接受协议# - 确认安装路径默认 ~/miniconda3 即可# - 输入 yes 执行 conda init安装完成后关闭并重新打开终端验证conda--version1.4 Linux 安装步骤# 在终端中执行bash~/Downloads/Miniconda3-latest-Linux-x86_64.sh# 按提示操作步骤同 macOS二、Conda 基础操作以下是本课程会用到的 Conda 命令有个印象即可命令作用conda --version查看 Conda 版本conda info --envs列出所有虚拟环境conda create -n 环境名 python3.10创建新环境conda activate 环境名激活进入某个环境conda deactivate退出当前环境conda remove -n 环境名 --all删除某个环境conda list列出当前环境已安装的包核心概念虚拟环境就是一个隔离的 Python 运行空间不同环境之间互不影响。比如你可以同时拥有一个用 Python 3.13 的langgraph环境和一个用 Python 3.12 的other_project环境。三、创建课程环境3.1 创建并激活环境# 创建名为 langgraph 的环境指定 Python 3.13conda create-nlanggraphpython3.13# 出现 Proceed ([y]/n)? 时输入 y 回车确认# 等待下载和安装完成约 1-2 分钟# 激活环境conda activate langgraph激活成功后终端提示符前面会出现(langgraph)表示当前已进入该环境(langgraph) C:\Users\你的用户名验证 Python 版本python--version# 输出Python 3.13.x3.2 配置 pip 镜像源中国大陆用户建议由于课程依赖包较多配置国内镜像可以大幅提升下载速度# 设置清华大学 pip 镜像源pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple验证配置pip config list# 应看到global.index-urlhttps://pypi.tuna.tsinghua.edu.cn/simple如果后续遇到镜像源不稳定可随时恢复默认pip configunsetglobal.index-url四、安装 PyCharm 并创建项目PyCharm 是 JetBrains 推出的 Python IDECommunity 版免费且功能齐全本课程全程使用 PyCharm 进行开发和调试。4.1 下载 PyCharm打开 PyCharm 官方下载页面https://www.jetbrains.com/pycharm/download/选择PyCharm Community Edition免费版根据操作系统下载对应安装包操作系统安装包格式Windows.exe安装包macOS.dmg磁盘映像Linux.tar.gz压缩包4.2 安装步骤Windows双击下载的.exe安装包启动安装向导安装路径建议保持默认如C:\Program Files\JetBrains\PyCharm Community Edition关键步骤在安装选项中勾选✅Add “Open Folder as Project”右键菜单快捷打开项目✅Add launchers dir to the PATH方便命令行启动其余选项默认即可点击 Install等待安装完成安装完成后勾选Run PyCharm→ Finish启动 PyCharmmacOS双击下载的.dmg文件将 PyCharm 图标拖入Applications文件夹从启动台打开 PyCharm4.3 创建课程项目PyCharm 启动后点击New Project新建项目在新建项目窗口中配置设置项值Location选择一个合适的路径末尾项目名填写langgraph如E:\code\langgraphCreate Git repo❌ 不勾选课程不涉及 GitInterpreter type选择Conda或Custom environment→CondaPython 版本选Python 3.13Conda 会自动创建对应环境点击Create等待 PyCharm 完成项目初始化创建完成后PyCharm 生成的空项目结构如下langgraph/ ← 项目根目录PyCharm 自动创建 ├── .idea/ ← PyCharm 配置文件无需手动修改 └── main.py ← 空入口文件可删除或保留练手这就是本课程的项目根目录。后续所有pip install、.env配置、代码文件都在这个目录下进行。.idea/是 PyCharm 自动生成的配置目录不要手动修改或提交到 Git。4.4 PyCharm 终端PyCharm 底部的Terminal面板快捷键Alt F12会自动激活当前项目配置的 Conda 环境终端的提示符前面会显示(langgraph)(langgraph) PS E:\code\langgraph后续所有命令pip install、python、jupyter等都建议在 PyCharm 的 Terminal 中执行无需手动conda activate。五、安装课程依赖课程提供了两个依赖文件均位于2.资料/目录下文件说明适用阶段requirements.txt核心依赖约 180 个包全部课程requirements_full.txt完整依赖额外包含 Jupyter Notebook 和langgraph-cli部署工具Ch 9 及之后5.1 安装核心依赖# 确保已激活 langgraph 环境conda activate langgraph# 进入项目根目录cd课程目录/langgraph# 安装核心依赖pipinstall-r2.资料/requirements.txt安装过程约 5-10 分钟会依次下载和安装约 180 个 Python 包。5.2 安装完整依赖推荐pipinstall-r2.资料/requirements_full.txt相比核心依赖额外安装额外包用途jupyter在浏览器中运行.ipynb笔记本langgraph-cli[inmem]LangGraph 本地开发服务器用于 Ch 9 项目部署5.3 核心包说明安装完成后环境中包含以下关键包无需手动逐个安装LangGraph 全家桶包名用途langgraphLangGraph 核心库构建状态图langgraph-prebuilt预置的 Agent 组件langgraph-checkpoint检查点Checkpoint机制langgraph-checkpoint-postgresPostgreSQL 持久化检查点langgraph-sdkLangGraph Python SDKLangChain 全家桶包名用途langchainLangChain 核心langchain-coreLangChain 基础抽象langchain-community社区集成langchain-openaiOpenAI 集成langchain-deepseekDeepSeek 集成langchain-anthropicAnthropic Claude 集成模型服务商 SDK包名用途openaiOpenAI 官方 SDKanthropicAnthropic 官方 SDKdashscope阿里百炼Qwen 等模型tencentcloud-sdk-python腾讯云 SDK其他重要依赖包名用途fastapi/uvicornWeb 服务框架部署时使用pydantic数据校验状态定义时大量使用httpx/httpx-sseHTTP 客户端 SSE 流式支持loguru日志库python-dotenv读取.env环境变量文件tiktokenOpenAI 的 token 计数工具SQLAlchemy/psycopg数据库操作持久化时使用pymilvusMilvus 向量数据库客户端六、配置 API Key课程示例默认使用DeepSeek大模型至少需要配置 DeepSeek 的 API Key。按实际需要也可以配置其他模型服务商。6.1 获取 DeepSeek API Key打开 DeepSeek 开放平台https://platform.deepseek.com/注册 / 登录账号进入API Keys页面点击创建 API Key复制生成的 key形如sk-xxxxxxxx注意 key只显示一次请立即保存DeepSeek 是新用户注册即送 500 万 tokens 额度足够学完整套课程。6.2 创建 .env 文件在项目根目录langgraph/下新建.env文件填入以下内容# # 必填课程示例默认使用 DeepSeek 模型 # DEEPSEEK_API_KEYsk-你的DeepSeek_API_Key # # 可选其他模型服务商如需切换模型时使用 # # OPENAI_API_KEYsk-你的OpenAI_API_Key # ANTHROPIC_API_KEYsk-ant-你的Anthropic_API_Key # # 部署时需要Ch 9 项目部署章节 # # LANGSMITH_API_KEYlsv2-pt-你的LangSmith_API_Key # LANGSMITH_TRACINGtrue # LANGSMITH_ENDPOINThttps://api.smith.langchain.com # LANGSMITH_PROJECTlanggraph-tutorial.env文件已在.gitignore中排除不会被提交到 Git可以放心保存密钥。6.3 代码中如何读取 .env课程每个 notebook 或示例代码开头都会包含以下两行自动加载.env中的密钥fromdotenvimportload_dotenv load_dotenv(overrideTrue)之后创建模型客户端时SDK 会自动从环境变量中读取对应的 API Key无需在代码中硬编码fromlangchain_deepseekimportChatDeepSeek# API Key 自动从 DEEPSEEK_API_KEY 环境变量读取modelChatDeepSeek(modeldeepseek-v4-flash)七、Jupyter Notebook 配置课程中的练习代码以.ipynbJupyter Notebook格式提供位于3.代码/目录下。7.1 启动 Jupyter# 确保已激活 langgraph 环境conda activate langgraph# 进入项目根目录cd课程目录/langgraph# 启动 Jupyterjupyter notebook执行后会终端显示一个带 token 的本地 URL如http://localhost:8888/?tokenxxx自动打开默认浏览器进入 Jupyter 文件管理界面7.2 验证 Kernel在 Jupyter 界面右上角或菜单栏中确认当前 Kernel 为Python (langgraph)。如果不是点击菜单Kernel→Change kernel→ 选择Python (langgraph)如果列表中没有Python (langgraph)说明没有创建对应的名称。在langgraph环境中重新执行conda activate langgraph pipinstallipykernel python-mipykernelinstall--user--namelanggraph --display-namePython (langgraph)八、环境验证全部配置完成后执行以下验证脚本确保一切就绪。8.1 基础验证在终端中# 1. 确认 Conda 版本conda--version# 2. 确认 Python 版本和当前环境python--version# 输出Python 3.13.x# 3. 确认当前环境conda info--envs# langgraph 前面应有 * 号表示当前激活# 4. 确认关键包已安装pip show langgraph pip show langchain-core pip show langchain-deepseek pip show jupyter8.2 代码验证在 Jupyter 中新建一个 Notebook或创建一个测试脚本test_env.py# test_env.pyprint(环境验证开始)print(*40)# 1. Python 版本importsysprint(fPython 版本:{sys.version})# 2. 关键包fromimportlib.metadataimportversionaspkg_versionprint(fLangGraph 版本:{pkg_version(langgraph)})importlangchain_coreprint(fLangChain Core 版本:{langchain_core.__version__})importpydanticprint(fPydantic 版本:{pydantic.__version__})# 3. .env 加载fromdotenvimportload_dotenvimportos load_dotenv(overrideTrue)deepseek_keyos.getenv(DEEPSEEK_API_KEY)ifdeepseek_key:print(fDeepSeek API Key 已配置:{deepseek_key[:8]}...{deepseek_key[-4:]})else:print(⚠️ 未检测到 DEEPSEEK_API_KEY请在 .env 文件中配置)# 4. 模型调用测试ifdeepseek_key:fromlangchain_deepseekimportChatDeepSeek modelChatDeepSeek(modeldeepseek-v4-flash)responsemodel.invoke(回复一切正常四个字不要其他内容)print(f模型调用测试:{response.content})else:print(⚠️ 跳过模型调用测试缺少 API Key)print(*40)print(环境验证完成)print(*40)运行脚本python test_env.py如果一切正常输出类似 环境验证开始 Python 版本: 3.13.14 LangGraph 版本: 1.1.2 LangChain Core 版本: 1.2.18 Pydantic 版本: 2.12.5 DeepSeek API Key 已配置: sk-xxxx...xxxx 模型调用测试: 一切正常 环境验证完成 九、常见问题9.1 Q1:conda命令找不到Windows确保安装时勾选了Add Miniconda3 to my PATH。如果还是找不到从开始菜单打开Anaconda Prompt (miniconda3)即可。macOS / Linux执行~/miniconda3/bin/conda init后重启终端。9.2 Q2: PyCharm 中找不到 Conda 环境打开File→Settings→Project: langgraph→Python Interpreter点击齿轮 →Add Interpreter→Add Local Interpreter选择Conda Environment→Use existing environment点击文件夹图标浏览到 Conda 环境目录Windows:C:\Users\你的用户名\miniconda3\envs\langgraphmacOS/Linux:~/miniconda3/envs/langgraph选择python.exe或python点击 OK如果列表中没有langgraph环境先在 Terminal 中手动创建conda create-nlanggraphpython3.13创建后再回到上述步骤手动添加。9.3 Q3:pip install速度很慢配置国内镜像源见 3.2 节pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple9.4 Q4: 安装依赖时报错Microsoft Visual C 14.0 is required部分包如unstructured需要 C 编译环境。解决方案下载 Visual Studio Build Toolshttps://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022安装时勾选“Desktop development with C”工作负载重新执行pip install如果不想装 C 工具链也可以跳过该包的学习章节不影响核心课程。9.5 Q5: Jupyter 中找不到Python (langgraph)Kernelconda activate langgraph pipinstallipykernel python-mipykernelinstall--user--namelanggraph --display-namePython (langgraph)重启 Jupyter 即可看到。9.6 Q6:import langgraph报ModuleNotFoundError说明包没有正确安装到当前环境# 确认当前在 langgraph 环境conda activate langgraph# 确认包已安装pip show langgraph# 如果未安装重新安装pipinstall-r2.资料/requirements.txt9.7 Q7: 模型调用时报AuthenticationError检查以下三点.env文件中是否配置了正确的 API Key.env文件是否在项目根目录langgraph/下代码开头是否执行了load_dotenv(overrideTrue)9.8 Q8: 想把环境恢复到初始状态# 退出当前环境conda deactivate# 删除并重建conda remove-nlanggraph--allconda create-nlanggraphpython3.13conda activate langgraph pipinstall-r2.资料/requirements_full.txt十、环境配置检查清单在开始第一章之前逐项确认Miniconda 已安装conda --version正常输出PyCharm Community Edition 已安装langgraph项目已通过 PyCharm 创建PyCharm 解释器已配置为 Condalanggraph环境Python 3.13核心依赖已安装requirements.txtJupyter 已安装并能正常启动.env文件已创建DEEPSEEK_API_KEY已填写DeepSeek API Key 有可用额度验证脚本全部通过
