一、Python环境、Jupyter与Pycharm

安装Python

由于RAG项目中所需要的Python版本必须高于3.8，经过筛选，最终选择了3.10.11这个版本

bash 复制代码

py --version
Python 3.10.11

安装过程略过，但对于几个基础的命令作个笔记记录

where python

找到python启动器的位置

bash 复制代码

D:\>where python
C:\Users\xxxxx\AppData\Local\Programs\Python\Python310\python.exe

py -0

py -0 这个命令可以在有多个版本的Python的情况下，查看Python启动器默认执行的是哪个版本（带 * 标记的这个就是默认版本），多个版本的情况下，如果想改变Python启动器的默认版本，有两种方式：1、设置环境变量 PY_PYTHON=3.10 ；2、改配置置文件 %LOCALAPPDATA%\py.ini

bash 复制代码

D:\>py -0
Installed Pythons found by py Launcher for Windows
 -3.10-64 *

Python启动器的默认执行版本与环境变量PATH中的Phthon版本设定问题：

两者并不是同步的，因为Python启动器用的python版本并不依赖于PATH环境变量。

pip命令

pip命令最常见的用法就是安装依赖工具包

bash 复制代码

D:\PythonWorkspace\wow-rag\rag-venv>pip install fastapi

Looking in indexes: https://mirrors.aliyun.com/pypi/simple/
Requirement already satisfied: fastapi in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (0.116.1)
Requirement already satisfied: starlette<0.48.0,>=0.40.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (0.47.1)
Requirement already satisfied: typing-extensions>=4.8.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (4.14.1)
Requirement already satisfied: pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (2.11.7)
Requirement already satisfied: typing-inspection>=0.4.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (0.4.1)
Requirement already satisfied: annotated-types>=0.6.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (0.7.0)
Requirement already satisfied: pydantic-core==2.33.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (2.33.2)
Requirement already satisfied: anyio<5,>=3.6.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from starlette<0.48.0,>=0.40.0->fastapi) (4.9.0)
Requirement already satisfied: sniffio>=1.1 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (1.3.1)
Requirement already satisfied: idna>=2.8 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (3.10)
Requirement already satisfied: exceptiongroup>=1.0.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (1.3.0)
Note: you may need to restart the kernel to use updated packages.

有多个版本的Python时，可以用py命令带上版本号来对指定的版本安装依赖包，例：

bash 复制代码

py -3.10 -m pip install langchain

安装 langchain 包到 Python 3.10 的环境中

Python的虚拟环境

虚拟环境是一个 独立的 Python 环境目录 （包含解释器、pip、安装包等），本质是一个文件夹，在实际项目中，对每个项目单独创建一个虚拟环境是有重要意义的，这可以让每个项目所依赖的包与其他项目的依赖包进行隔离，避免工具包的版本冲突导致的各种问题。

虚拟环境通常在项目的根目录下创建，用命令行创建一个虚拟环境的示例（rag-env是虚拟环境的目录）：

bash 复制代码

py -3.10 -m venv rag-env

虚拟环境的激活：在 rag-env\Scripts 目录下执行active.bat （必须CMD窗口执行），关闭就是执行 deactive.bat

重要：安装项目依赖的工具包之前激活该项目的虚拟环境，避免工具包未正确安装导致运行代码的时候出现报错：

bash 复制代码

ModuleNotFoundError: No module named 'pandas'

一旦你激活了某个虚拟环境，后续在该命令行中执行的所有 Python 相关命令（如 python, pip, conda, pytest 等），都是作用在这个被激活的虚拟环境中的。

一个命令行窗口只能管理一个虚拟环境的状态（激活/关闭），命令行窗口关闭后，激活的虚拟环境会自动关闭。想要管理多个虚拟环境的状态，可以开多个命令行。

注：使用PyCharm创建一个项目可以指定的策略来为项目创建一个新的虚拟环境，且在PyCharm中运行Python程序的时候不需要手动激活虚拟环境，PyCharm会帮用户做这件事。

Jupyter与Jupyter Book

Jupyter适用于做Python的小实验，比用PyCharm更简洁方便。使用Jupyter需要的前提条件是：

1、安装Python

2、在项目的根目录下创建该项目的虚拟环境，例：py -3.10 -m venv rag-venv

3、已激活虚拟环境（命令行前缀显示虚拟环境的目录名，如： rag-env）

bash 复制代码

(rag-venv) C:\Users\YourName\YourProject>

安装Jupyter的步骤

1、（建议）使用阿里的镜像源，提高下载速度

bash 复制代码

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

2、安装Jupyter

bash 复制代码

pip install notebook

3、确认已装好

bash 复制代码

jupyter --version

4、启动Jupyter（在虚拟环境中执行）

bash 复制代码

jupyter notebook

浏览器中打开 http://localhost:8888，这是 Jupyter 的控制面板，你可以：

新建一个 Notebook（点击右上角 New → 选择 Python 3.10 环境）
编写代码，运行、保存等

5、退出 Jupyter 后，如果不再工作，可关闭虚拟环境（执行 \Scripts目录下的 deactive.bat）

在 Jupyter Notebook 中，界面是由一个个可以运行代码或写文字的"格子"（单元格，ode cell）组成的。每个格子可以：

输入一段 Python 代码
按下 Shift + Enter 运行这段代码
结果会显示在格子下方
你可以随时插入新格子、删除、复制、重新运行等

你可以在Jupyter Notebook中写python 代码、调试、展示结果等操作。比命令行好用，比PyCharm方便。

每个代码格子都要单独运行 ，才能执行其中的代码，除非你选择了批量执行（比如，菜单栏中执行 Restart & Run All，这会重骑Python的环境并按顺序运行所有的代码格子）。

Pycharm

与IDEA同为JetBrains下的产品，因此，很多设计特点可以参照IDEA来对标。

与IDEA一样，免费使用的版本为社区版（Community），本次安装的版本为 PyCharm Community 2023.3.5，安装过程略。

首次启动时的几个设置：

Import Settings：
- 选择 Do not import settings（针对首次使用者）。
UI 界面主题选择：
- 推荐选择 Darcula（深色） 或 Light（浅色），可随时更改。
插件推荐（可跳过）

项目与虚拟环境

与IDEA中对Java的版本设置相似，PyCharm中也可以设置全局Python的版本，但是不建议设置全局共享的Python解释器，因为这样很容易造成依赖冲突。

因此，对每个项目构建一个该项目的虚拟环境是实际项目中规范的做法。

新建项目的示例：

File→New Project：Interpreter Type 选 Custom enviroment

这样就可以在创建项目目录的同时，在项目的目录下构建该项目的虚拟环境。

在虚拟环境的目录里，可以看到有一个python.exe，在 项目文件夹\虚拟环境文件夹\Scripts\ 这个目录下，这是系统安装的Python(多版本的话指向的是默认版本 )的一个副本，副本的意思是基于系统安装的Python复制必要的解释器文件，并创建一个独立的依赖空间 （包的安装路径、sys.path 等都被重定向到了虚拟环境下的 Lib/ 和 Scripts/ 目录）。这样的话，在这个虚拟环境中装包、运行脚本，不会影响或依赖全局安装。

这里可以类比 Docker来理解：

虚拟环境机制	Docker 概念类比
`python.exe` + Lib	镜像的运行时
虚拟环境目录结构	容器文件系统
`Scripts/activate`	启动入口（类似 entrypoint）
pip install 的包	容器内的依赖

用Conda构建虚拟环境

Conda 是一个跨平台的包管理 + 环境管理工具，类似于 pip + virtualenv 的合体，而且不限于 Python 包。

Conda的能力	作用
📦 包管理	安装、卸载、更新第三方库（不只是 Python 库）
🌍 环境管理	创建、切换、隔离多个 Python 环境（或其他语言环境）
🏗️ Python 版本管理	每个环境可以使用不同版本的 Python
💼 支持非 Python 包	可安装 C/C++ 编译的科学计算包（如 numpy、pandas、opencv 等）而不需你配置编译器

与前面的创建虚拟环境的方式相比，使用Conda最大的优势是支持非Python包的安装与管理

Conda有两个版本，Anaconda和Miniconda，以下是这两个版本的对比

特性	Anaconda	Miniconda
📦 包含内容	Python + Conda + 300+ 常用数据科学包 + Navigator GUI	仅 Python + Conda + 少量基础依赖（轻量命令行版）
🛠 安装体积	≈ 4 GB，安装后环境庞大	约 480 MB，下载快，安装轻便
🧰 适用人群	希望开箱即用，零配置即可使用数据科学工具	想控制包安装，节省空间，只安装所需包
🛠 包管理方式	GUI + CLI（conda install）	纯命令行（conda install）
📡 非 Python 包支持	支持 C/C++ 库、R 等	同 Anaconda（都使用 Conda 包管理）
⚙️ 包更新频率	默认 conda 通道中包更新较慢	轻量，建议通过 conda-forge 或 mamba 加速

这里选用Anaconda，因为这对初学者更友好一点。

Anaconda的对虚拟环境的创建有两种方式：

方式	命令	环境位置	适用场景
方式 A：命名环境法（命名环境拨法）	`conda create -n myenv python=3.10`	➤ 一个统一的目录，如：Anaconda 的目录：`.../anaconda3/envs/myenv/`	✅ 推荐用于多个项目共享某个环境，统一管理
方式 B：路径方式（项目内环境）	`conda create -p ./venv python=3.10`	➤ 在项目的目录下创建，如 `./venv/`	✅ 推荐用于项目内绑定，方便迁移、开源

两种方式的区别可简单理解为：虚拟环境的安装位置一个在统一的目录里（比如Anaconda下的目录），另一个在项目的目录里，使用PyCharm新建项目的时候分别在不同的虚拟环境目录下选择python解释器（后面的详细步骤也会提到），核心区别的详细对比如下：

特性	命名环境（-n myenv）	路径环境（-p ./venv）
📁 环境放在哪里	系统集中目录（如 `anaconda3/envs/`）	项目目录下（如 `./venv/`）
🔄 是否推荐复用	✅ 支持复用（多个项目可用）	❌ 项目独占，不复用
🧳 可迁移性	❌ 环境与项目分离（不便迁移）	✅ 项目打包带走环境更方便
🛠 开发效率	快速使用已有环境，无需重复安装	需要每次创建、安装依赖
🤝 团队协作	不易同步环境，需导出 `.yml`	配合环境文件更清晰可控
📦 PyCharm 支持	自动识别，配置简单	需手动指向解释器路径

使用Anaconda创建项目的步骤描述

1、创建项目目录

bash 复制代码

# 创建项目目录
mkdir MyProject && cd MyProject

# 创建目录结构
mkdir app tests
echo > README.md
echo > app/main.py
echo > app/__init__.py
echo > tests/test_main.py

2、创建Conda虚拟环境（这里用"命名环境法"）

bash 复制代码

# 创建环境（可自定义名称和版本）
conda create -n myproject_env python=3.10

# 激活环境
conda activate myproject_env

# 安装开发常用包
conda install pytest

# 如果用 pip 也可以混合使用
pip install requests

3、在 PyCharm 中打开项目并配置解释器

打开 PyCharm → Open → 选择你的项目目录（如 D:\Projects\MyProject）
菜单栏：File → Settings → Project → Python Interpreter
添加解释器：选择
- Conda Environment → Existing Environment
- 指向：
  bash 复制代码
```
...\anaconda3\envs\myproject_env\python.exe
```

4、设置项目入口

右键 main.py → Mark as Entry Point（或者设置运行配置）
或在顶部菜单选择：
- Run → Edit Configurations → + → Python
- Script path 选 app/main.py
- Name 起个名字 Run App
- Interpreter 选你刚配置的 Conda 解释器
- Apply → OK

5、设置 app/ 为源码目录（非常重要）

右键 app/ → Mark Directory as → Sources Root

这样导入 from utils import xxx 就不会报错。

6.、导出 environment.yml（可选，但推荐）

将当前环境依赖导出成配置文件：

bash 复制代码

conda env export --from-history > environment.yml

这样你可以：

保留环境快照
迁移到新机器时 conda env create -f environment.yml 即可重建

最终实现的项目目录结构如下：

bash 复制代码

MyProject/
├── .idea/              ← PyCharm 配置（自动生成）
├── app/                ← 源代码
├── tests/              ← 测试
├── README.md
├── environment.yml