查看: 411|回复: 3

PyCharm 创建 Conda 虚拟环境并完成依赖安装与报错排查

[复制链接]
发表于 5 小时前 | 显示全部楼层 |阅读模式
用 PyCharm 写 LangGraph 这类需要多套依赖的项目时,最容易出问题的不是代码本身,而是解释器、虚拟环境和依赖装错了位置。下面按“建环境 → 接 IDE → 装依赖 → 配密钥 → 验证 → 排错”的顺序,把一条能跑通的链路整理成可复用的操作步骤,命令和代码均来自实际配置过程。

一、先理清工具分工

Conda 同时承担包管理和环境管理两件事,Miniconda 是它的精简发行版,只带最基础组件,体积小、装得快,做项目隔离够用。PyCharm 选 Community 版即可,免费且功能完整。

本文示例以 Windows 为主,环境名统一为 langgraph,Python 版本定为 3.13,项目目录示例为 E:\code\langgraph。macOS 与 Linux 的差异主要在安装包格式(.dmg / .sh)和环境目录路径上,命令本身一致。

安装 Miniconda 时有两个选项会直接影响后续命令行能否使用,需要勾选:

- Add Miniconda3 to my PATH environment variable(把 conda 加入系统 PATH)
- Register Miniconda3 as my default Python 3.x(注册为默认 Python)

装完后从开始菜单打开 Anaconda Prompt (miniconda3),执行版本检查:
  1. conda --version
  2. # 输出类似:conda 26.x.x
复制代码

二、创建并激活独立环境

虚拟环境的本质是一个隔离的 Python 运行空间,不同环境互不影响。例如可以同时存在一个 Python 3.13 的 langgraph 环境和一个 Python 3.12 的 other_project 环境,各自的包不会互相污染。
  1. conda create -n langgraph python=3.13
  2. # 出现 Proceed ([y]/n)? 时输入 y 回车
  3. conda activate langgraph
  4. python --version
  5. # 输出:Python 3.13.x
复制代码

激活成功的标志是终端提示符前出现环境名:
  1. (langgraph) C:\Users\你的用户名>
复制代码

常用的环境管理命令整理如下:

- conda --version:查看 Conda 版本
- conda info --envs:列出全部虚拟环境,当前环境前带 * 号
- conda activate 环境名 / conda deactivate:进入、退出环境
- conda remove -n 环境名 --all:删除整个环境
- conda list:查看当前环境已安装的包

三、配置 pip 镜像源

依赖安装慢通常不是网络本身的问题,而是默认源距离远。在激活的環境中设置清华源:
  1. pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  2. pip config list
  3. # 应看到:global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
复制代码

如果后续镜像源不稳定,可以随时回退到默认源:
  1. pip config unset global.index-url
复制代码

四、在 PyCharm 中创建项目并接入 Conda 解释器

新建项目时,关键在于 Interpreter type 选择 Conda(或 Custom environment → Conda),Python 版本选 3.13,PyCharm 会调用 Conda 创建对应环境。Create Git repo 一项按需勾选,示例中不勾选。

项目初始化后结构如下:
  1. langgraph/        ← 项目根目录
  2. ├── .idea/       ← PyCharm 配置目录,无需手动修改
  3. └── main.py      ← 空入口文件,可删可留
复制代码

PyCharm 底部 Terminal 面板(Alt + F12)会自动激活项目绑定的 Conda 环境,提示符前同样带 (langgraph):
  1. (langgraph) PS E:\code\langgraph>
复制代码

因此 pip install、python、jupyter 这类命令建议统一在 PyCharm 的 Terminal 里执行,不必每次手动 conda activate。

若项目建好后发现解释器不对,或环境是外部创建的,按以下路径手动挂载:File → Settings → Project: langgraph → Python Interpreter → 齿轮图标 → Add Interpreter → Add Local Interpreter → 选择 Conda Environment → Use existing environment,然后浏览到环境目录下的解释器文件:

- Windows:C:\Users\你的用户名\miniconda3\envs\langgraph
- macOS / Linux:~/miniconda3/envs/langgraph

选中 python.exe(或 python)确认即可。这一步是“PyCharm 找不到 Conda 环境”和“终端进不了虚拟环境”两类问题的通用解法。

五、安装项目依赖并确认关键包
  1. conda activate langgraph
  2. cd 目录/langgraph
  3. pip install -r /requirements.txt
复制代码

注意依赖清单路径要按项目实际位置填写,示例中的 /requirements.txt 是原文写法,执行前先确认文件存在,否则会报找不到文件。

安装完成后环境里会包含几组关键依赖,可按用途理解:

- LangGraph 相关:langgraph(核心库,构建状态图)、langgraph-prebuilt(预置 Agent 组件)、langgraph-checkpoint(检查点机制)、langgraph-checkpoint-postgres(PostgreSQL 持久化检查点)、langgraph-sdk
- LangChain 相关:langchain、langchain-core(基础抽象)、langchain-community、langchain-openai、langchain-deepseek、langchain-anthropic
- 模型服务商 SDK:openai、anthropic、dashscope(阿里百炼 Qwen 等)、tencentcloud-sdk-python
- 其他支撑库:fastapi / uvicorn(服务部署)、pydantic(数据校验与状态定义)、httpx / httpx-sse(HTTP 与 SSE 流式)、loguru(日志)、python-dotenv(读取 .env)、tiktoken(token 计数)、SQLAlchemy / psycopg(数据库与持久化)、pymilvus(Milvus 向量库客户端)

六、用 .env 管理 API Key

默认走 DeepSeek 模型,至少需要配置 DEEPSEEK_API_KEY。在项目根目录 langgraph/ 下新建 .env 文件:
  1. # 必填:示例默认使用 DeepSeek 模型
  2. DEEPSEEK_API_KEY=sk-你的DeepSeek_API_Key
  3. # 可选:其他模型服务商
  4. # OPENAI_API_KEY=sk-你的OpenAI_API_Key
  5. # ANTHROPIC_API_KEY=sk-ant-你的Anthropic_API_Key
  6. # 部署时需要
  7. # LANGSMITH_API_KEY=lsv2-pt-你的LangSmith_API_Key
  8. # LANGSMITH_TRACING=true
  9. # LANGSMITH_ENDPOINT=https://api.smith.langchain.com
  10. # LANGSMITH_PROJECT="langgraph-tutorial"
复制代码

代码中通过 python-dotenv 加载,override=True 表示 .env 中的值优先于系统已有的同名环境变量:
  1. from dotenv import load_dotenv
  2. load_dotenv(override=True)
  3. from langchain_deepseek import ChatDeepSeek
  4. # API Key 自动从 DEEPSEEK_API_KEY 环境变量读取
  5. model = ChatDeepSeek(model="deepseek-v4-flash")
  6. response = model.invoke("回复'一切正常'四个字,不要其他内容")
  7. print(response.content)
复制代码

这种方式的好处是密钥不写进代码,SDK 自行从环境变量读取,切换模型服务商时只需改 .env 中的一行。

七、注册 Jupyter Kernel
  1. conda activate langgraph
  2. pip install ipykernel
  3. python -m ipykernel install --user --name langgraph --display-name "Python (langgraph)"
  4. jupyter notebook
复制代码

启动后终端会给出带 token 的本地地址(如 http://localhost:8888/?token=xxx),并自动打开浏览器。右上角 Kernel 若不是 Python (langgraph),通过菜单 Kernel → Change kernel 切换;列表里没有该名称,说明 kernel 未注册,回到上面的 ipykernel 命令重新执行并重启 Jupyter。

八、用脚本验证环境是否真的可用

先做命令行层验证:
  1. conda --version
  2. python --version
  3. conda info --envs
  4. pip show langgraph
  5. pip show langchain-core
  6. pip show langchain-deepseek
  7. pip show jupyter
复制代码

再写一个 test_env.py 做代码层验证,覆盖 Python 版本、关键包版本、.env 加载和模型调用四项:
  1. # test_env.py
  2. import sys
  3. import os
  4. from importlib.metadata import version as pkg_version
  5. from dotenv import load_dotenv
  6. print("=" * 40)
  7. print("环境验证开始")
  8. print("=" * 40)
  9. print(f"Python 版本: {sys.version}")
  10. print(f"LangGraph 版本: {pkg_version('langgraph')}")
  11. import langchain_core
  12. print(f"LangChain Core 版本: {langchain_core.__version__}")
  13. import pydantic
  14. print(f"Pydantic 版本: {pydantic.__version__}")
  15. load_dotenv(override=True)
  16. deepseek_key = os.getenv("DEEPSEEK_API_KEY")
  17. if deepseek_key:
  18.     print(f"DeepSeek API Key 已配置: {deepseek_key[:8]}...{deepseek_key[-4:]}")
  19. else:
  20.     print("未检测到 DEEPSEEK_API_KEY,请在 .env 文件中配置")
  21. if deepseek_key:
  22.     from langchain_deepseek import ChatDeepSeek
  23.     model = ChatDeepSeek(model="deepseek-v4-flash")
  24.     response = model.invoke("回复'一切正常'四个字,不要其他内容")
  25.     print(f"模型调用测试: {response.content}")
  26. else:
  27.     print("跳过模型调用测试(缺少 API Key)")
  28. print("=" * 40)
  29. print("环境验证完成")
复制代码
  1. python test_env.py
复制代码

正常情况会依次打印 Python 3.13.x、LangGraph 1.1.2、LangChain Core 1.2.18、Pydantic 2.12.5、掩码后的 Key,以及模型返回的“一切正常”。四项里任何一项缺失,都能直接定位到问题区间:包版本查不到是环境装错,Key 掩码没输出是 .env 没被读到,模型调用失败是密钥或网络问题。

九、常见报错与排查路径

conda 命令找不到:Windows 下先确认安装时勾选了加入 PATH;仍不行就直接用 Anaconda Prompt (miniconda3),它是自带环境变量的终端。

PyCharm 里没有 Conda 环境:按第四节的 Settings → Add Interpreter → Conda Environment → Use existing environment 手动指定 python.exe;若环境列表本身为空,先在终端执行 conda create -n langgraph python=3.13 再回来添加。

pip install 慢:执行第三节的清华源配置,必要时 unset 恢复默认源。

报错 Microsoft Visual C++ 14.0 is required:部分包(如 unstructured)需要 C++ 编译环境。安装 Visual Studio Build Tools,勾选 Desktop development with C++ 工作负载,然后重新执行 pip install。

Jupyter 里没有 Python (langgraph) Kernel:缺少 ipykernel 注册,执行 pip install ipykernel 和 python -m ipykernel install --user --name langgraph --display-name "Python (langgraph)",重启 Jupyter。

import langgraph 报 ModuleNotFoundError:几乎都是包装到了别的环境。用 conda activate langgraph 确认当前环境,再 pip show langgraph 看是否存在,缺失则重装依赖清单。

模型调用报 AuthenticationError:按顺序核对三点——.env 中 Key 是否正确;.env 是否放在项目根目录 langgraph/ 下;代码开头是否执行了 load_dotenv(override=True)。

环境想推倒重来:conda deactivate,然后 conda remove -n langgraph --all 删除,再重新 create、activate、安装依赖即可。相比逐个卸包,整环境重建更干净。

十、这套流程的价值

把环境创建、解释器绑定和依赖安装拆成三步并各自验证,好处是出错时责任边界清晰:conda 层面负责 Python 版本与环境隔离,PyCharm 负责解释器指向和终端自动激活,pip 负责包落地。三者任一环节错位,都会表现为同一个症状——导入失败或密钥读不到,但排查入口完全不同。配合 .env 集中管理和 test_env.py 这类自检脚本,新机器复现同一套开发环境的成本会明显降低。
回复

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: PyCharm 创建 Conda 虚拟环境并完成依赖安装与报错排查

这篇流程整理得很实用,尤其是先把 Conda 和 PyCharm 的分工讲清楚,再把解释器挂载单独拿出来说,能少踩很多坑。几个细节我很有同感:PyCharm 底部 Terminal 自动激活环境后,pip install 和 python 命令确实要固定在这里执行,不然很容易装到系统 Python 或别的环境里;requirements.txt 的路径也一定要先 cd 到项目目录再执行,示例里的 /requirements.txt 直接复制容易报找不到文件。镜像源那段设置和回退命令也很方便。看到最后“其他支撑库”似乎还没列完,后面的配密钥、验证和排错部分也没展开,如果方便的话期待继续补全,特别是怎么确认包到底装在 langgraph 环境里,以及解释器路径选错时该看哪里排查。
回复 支持 反对

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: PyCharm 创建 Conda 虚拟环境并完成依赖安装与报错排查

楼主这篇整理得挺实在的,尤其“装错位置”这个坑真是踩过才知道疼。顺着你的链路补几个自己常遇到的点,给后来人省点时间。 一是 Python 3.13 的问题。3.13 比较新,个别包还没出对应轮子,pip 装的时候会退回到源码编译,Windows 上大概率卡在缺 MSVC 或者某个 C 扩展上。真碰到这种报错,别死磕,先 conda create 一个 3.12 的环境整体挪过去,往往一把就过;确实是业务必须 3.13 再单独去查那个包的 issue。所以你说“版本定为 3.13”我建议后面加一句:装依赖报编译错优先考虑降小版本。 二是装完一定要确认包进了哪个环境。最省事的做法是 conda activate 之后跑 conda list | findstr langgraph(PowerShell 用 Select-String),或者 python -c “import langgraph; print(langgraph.__file__)”,看路径里有没有 envs\langgraph。之前我见过 pip 装到 base 里、项目却用 langgraph 解释器,报 ModuleNotFoundError 查了半天。 三是 PyCharm 的 Terminal 提示符。如果打开底部终端没有前面那个 (langgraph),说明解释器或者终端 shell 没绑对,这时候在里面
回复 支持 反对

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: PyCharm 创建 Conda 虚拟环境并完成依赖安装与报错排查

很实用的整理,链路完整。补几个自己踩过的点,供参考。 一是 Python 版本的选择。帖子里定的是 3.13,如果项目里的依赖比较新倒没问题,但 LangChain / LangGraph 生态里一些周边包(比如某些 checkpoint 后端、向量库客户端)对最新小版本的支持往往滞后一两个月,容易在 pip 解析依赖时卡住或者装上了运行时才报错。稳妥起见我会先用 3.12 跑通,确认没问题再考虑升。真遇到诡异的 ImportError,第一反应可以先怀疑版本兼容,而不是代码。 二是 PATH 那个勾选项。勾上确实方便,命令行随处能用 conda;但如果不勾,也不是不能用,全部操作走 Anaconda Prompt 或者 PyCharm 的 Terminal 就行,反而少一些“系统里有另一个 Python 抢了解释器”的麻烦。关键是别出现“装了包但 IDE 里 import 不到”的情况——这基本就是 pip 和 python 指向了不同环境。排查方法很简单,在报错的那个终端里分别执行 where python 和 where pip(macOS/Linux 用 which),看两个路径是不是同一个环境目录下的,不一致就说明装错地方了。 三是镜像源配置。pip config set 写的是用户级配置文件,对所有环境生效,不只是当前这个。如果公司内网或者后面要用私有源,记得 unse
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-16 07:51 , Processed in 0.022346 second(s), 17 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部