294 lines
8.7 KiB
Plaintext
294 lines
8.7 KiB
Plaintext
{
|
||
"cells": [
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"# 02 Python 环境配置\n",
|
||
"\n",
|
||
"## 学习目标\n",
|
||
"1. 理解 Python 虚拟环境的作用，掌握 venv 的进阶用法\n",
|
||
"2. 学会使用 `requirements.txt` 管理项目依赖\n",
|
||
"3. 掌握 Jupyter Notebook / JupyterLab 在 VS Code 中的配置\n",
|
||
"4. 学会为 Jupyter 注册虚拟环境内核并排查常见环境问题"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 1. 为什么需要虚拟环境\n",
|
||
"\n",
|
||
"在 Python 开发中，不同项目可能依赖不同版本的库。如果不加隔离，全局安装的库会相互冲突。\n",
|
||
"\n",
|
||
"### 虚拟环境的好处\n",
|
||
"- **依赖隔离**：每个项目有独立的包集合\n",
|
||
"- **版本可控**：避免全局包版本混乱\n",
|
||
"- **便于迁移**：通过 `requirements.txt` 快速复现环境\n",
|
||
"- **与生产一致**：开发、测试、生产环境使用相同依赖"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 2. venv 进阶用法\n",
|
||
"\n",
|
||
"Python 3.12 内置 `venv` 模块，无需额外安装。除了创建环境，你还可以指定 Python 解释器、选择是否包含系统站点包等。\n",
|
||
"\n",
|
||
"### 常用命令\n",
|
||
"\n",
|
||
"```powershell\n",
|
||
"# 创建虚拟环境（默认当前目录下 .venv 文件夹）\n",
|
||
"python -m venv .venv\n",
|
||
"\n",
|
||
"# 指定 Python 版本创建环境（需该版本在 PATH 中）\n",
|
||
"python3.12 -m venv .venv\n",
|
||
"\n",
|
||
"# 创建时继承系统已安装的包（谨慎使用）\n",
|
||
"python -m venv .venv --system-site-packages\n",
|
||
"\n",
|
||
"# 删除虚拟环境（直接删除文件夹即可）\n",
|
||
"Remove-Item -Recurse -Force .venv\n",
|
||
"```"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 虚拟环境目录结构\n",
|
||
"\n",
|
||
"```text\n",
|
||
".venv/\n",
|
||
"├── Scripts/ # Windows 可执行文件（python.exe、pip.exe、activate）\n",
|
||
"├── Lib/ # 安装的第三方库\n",
|
||
"├── include/ # C 扩展头文件\n",
|
||
"└── pyvenv.cfg # 环境配置信息\n",
|
||
"```"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# 查看当前解释器所在环境信息\n",
|
||
"import sys\n",
|
||
"import os\n",
|
||
"\n",
|
||
"print(f\"当前 Python：{sys.executable}\")\n",
|
||
"print(f\"是否处于虚拟环境：{hasattr(sys, 'real_prefix') or sys.base_prefix != sys.prefix}\")\n",
|
||
"print(f\"虚拟环境路径：{sys.prefix}\")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 3. 使用 requirements.txt 管理依赖\n",
|
||
"\n",
|
||
"`requirements.txt` 是 Python 项目的依赖清单，便于团队共享和部署复现。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 导出当前环境依赖\n",
|
||
"\n",
|
||
"在已激活的虚拟环境中执行：\n",
|
||
"\n",
|
||
"```powershell\n",
|
||
"pip freeze > requirements.txt\n",
|
||
"```\n",
|
||
"\n",
|
||
"### 从 requirements.txt 安装依赖\n",
|
||
"\n",
|
||
"```powershell\n",
|
||
"pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple\n",
|
||
"```"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 一份适合本课程的 requirements.txt 示例\n",
|
||
"\n",
|
||
"你可以将以下内容保存为项目根目录下的 `requirements.txt`：\n",
|
||
"\n",
|
||
"```text\n",
|
||
"# 核心框架\n",
|
||
"langchain>=0.3.0\n",
|
||
"langgraph>=0.2.0\n",
|
||
"langchain-openai>=0.2.0\n",
|
||
"\n",
|
||
"# 向量数据库与 Embedding\n",
|
||
"langchain-chroma>=0.1.0\n",
|
||
"sentence-transformers>=3.0.0\n",
|
||
"\n",
|
||
"# Jupyter 与工具\n",
|
||
"jupyter>=1.0.0\n",
|
||
"ipykernel>=6.29.0\n",
|
||
"python-dotenv>=1.0.0\n",
|
||
"\n",
|
||
"# 可选：搜索/网络请求工具\n",
|
||
"requests>=2.32.0\n",
|
||
"```"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# 示例：查看当前环境已安装的核心包\n",
|
||
"import subprocess\n",
|
||
"result = subprocess.run(['pip', 'list'], capture_output=True, text=True)\n",
|
||
"print(result.stdout[:2000]) # 只打印前 2000 字符"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 4. Jupyter Notebook 配置\n",
|
||
"\n",
|
||
"Jupyter Notebook 是交互式运行 Python 代码的理想工具，本课程所有课件都以 `.ipynb` 格式提供。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 安装 Jupyter\n",
|
||
"\n",
|
||
"在虚拟环境中执行：\n",
|
||
"\n",
|
||
"```powershell\n",
|
||
"pip install jupyter ipykernel -i https://pypi.tuna.tsinghua.edu.cn/simple\n",
|
||
"```"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 为 Jupyter 注册当前虚拟环境内核\n",
|
||
"\n",
|
||
"这样 VS Code 的 Jupyter 面板就能识别并使用 `.venv` 中的解释器：\n",
|
||
"\n",
|
||
"```powershell\n",
|
||
"python -m ipykernel install --user --name=langchain-env --display-name=\"LangChain课程环境\"\n",
|
||
"```\n",
|
||
"\n",
|
||
"参数说明：\n",
|
||
"- `--user`：安装到用户目录，无需管理员权限\n",
|
||
"- `--name`：内核内部名称\n",
|
||
"- `--display-name`：在 VS Code 中显示的名称"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 在 VS Code 中切换 Jupyter 内核\n",
|
||
"\n",
|
||
"1. 打开任意 `.ipynb` 文件\n",
|
||
"2. 点击右上角内核选择器（默认显示为 Python 版本号）\n",
|
||
"3. 选择 `LangChain课程环境` 或 `.venv` 对应的解释器\n",
|
||
"4. 重新运行单元格即可"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# 测试 Jupyter 运行是否正常\n",
|
||
"print(\"Hello, LangChain + LangGraph!\")"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 5. pip 常用命令速查\n",
|
||
"\n",
|
||
"| 命令 | 作用 |\n",
|
||
"| --- | --- |\n",
|
||
"| `pip install 包名` | 安装指定包 |\n",
|
||
"| `pip install 包名==1.0.0` | 安装指定版本 |\n",
|
||
"| `pip install -U 包名` | 升级指定包 |\n",
|
||
"| `pip uninstall 包名` | 卸载指定包 |\n",
|
||
"| `pip list` | 列出已安装包 |\n",
|
||
"| `pip show 包名` | 查看包详细信息 |\n",
|
||
"| `pip freeze > requirements.txt` | 导出依赖清单 |\n",
|
||
"| `pip install -r requirements.txt` | 按清单安装依赖 |"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 6. 常见环境问题排查\n",
|
||
"\n",
|
||
"### 问题 1：终端显示未激活虚拟环境\n",
|
||
"- 检查终端是否从 VS Code 正确启动\n",
|
||
"- 手动执行 `.venv\\Scripts\\Activate.ps1`\n",
|
||
"\n",
|
||
"### 问题 2：pip 安装速度慢或超时\n",
|
||
"- 使用清华镜像源：`-i https://pypi.tuna.tsinghua.edu.cn/simple`\n",
|
||
"- 升级 pip：`python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple`\n",
|
||
"\n",
|
||
"### 问题 3：Jupyter 内核无法导入虚拟环境中的包\n",
|
||
"- 确认内核选择的是 `.venv` 对应的解释器\n",
|
||
"- 重新注册内核：`python -m ipykernel install --user --name=langchain-env --force`\n",
|
||
"\n",
|
||
"### 问题 4：安装包时报依赖冲突\n",
|
||
"- 优先在干净虚拟环境中安装\n",
|
||
"- 使用 `pip install 包名 --no-deps` 跳过依赖检查（谨慎）\n",
|
||
"- 使用 `pip install -r requirements.txt` 统一安装"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 7. 本节课练习\n",
|
||
"\n",
|
||
"1. 在当前项目目录下创建一个名为 `.venv` 的虚拟环境（如果尚未创建）\n",
|
||
"2. 激活虚拟环境后，使用清华镜像源安装 `jupyter`、`ipykernel`、`langchain`、`langgraph`\n",
|
||
"3. 注册当前环境为 Jupyter 内核，名称为 `langchain-env`\n",
|
||
"4. 在 VS Code 中切换到这个内核，并成功运行本 notebook 中的所有代码单元格\n",
|
||
"5. 使用 `pip freeze > requirements.txt` 导出依赖清单，查看文件内容"
|
||
]
|
||
}
|
||
],
|
||
"metadata": {
|
||
"kernelspec": {
|
||
"display_name": ".venv",
|
||
"language": "python",
|
||
"name": "python3"
|
||
},
|
||
"language_info": {
|
||
"codemirror_mode": {
|
||
"name": "ipython",
|
||
"version": 3
|
||
},
|
||
"file_extension": ".py",
|
||
"mimetype": "text/x-python",
|
||
"name": "python",
|
||
"nbconvert_exporter": "python",
|
||
"pygments_lexer": "ipython3",
|
||
"version": "3.14.4"
|
||
}
|
||
},
|
||
"nbformat": 4,
|
||
"nbformat_minor": 4
|
||
}
|