{
 "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",
    "```\n",
    "\n",
    "在Docker中安装\n",
    "\n",
    "```bash\n",
    "cd /opt\n",
    "mkdir jupyter\n",
    "cd jupyter\n",
    "docker run -p 8888:8888 \\\n",
    "    -v \"$PWD\":/home/jovyan/work \\\n",
    "    --name my-jupyter \\\n",
    "    jupyter/scipy-notebook:latest\n",
    "```\n",
    "\n",
    "在Docker中为jupyter安装汉化包\n",
    "\n",
    "```bash\n",
    "docker exec -it my-jupyter pip install jupyterlab-language-pack-zh-CN -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
}