AI智能体项目实战记录（02）：初始化 Python 项目

1. 前言

在上一篇《AI智能体项目实战记录（01）：开发环境搭建之conda的安装与配置》中，我们完成了本地环境的搭建。本篇将正式进入编码阶段，从零开始初始化 Python 项目，搭建基础工程骨架，为后续功能开发打好地基。

2. 环境准备

在开始初始化项目之前，需要确保本地开发环境满足以下要求：

• Python：3.10 及以上版本
• Conda：Anaconda 或 Miniconda（推荐使用 Miniconda，更轻量）
• IDE：IntelliJ IDEA 2023.1 及以上版本（社区版或旗舰版均可，需安装 Python 插件）

3. 创建虚拟环境

我们使用 Conda 来创建独立的 Python 虚拟环境，避免不同项目之间的依赖冲突。

3.1 以管理员权限打开 CMD

在 Windows 系统中，右键点击「开始」菜单，选择「Windows PowerShell（管理员）」或「命令提示符（管理员）」，确保拥有足够的系统权限。

3.2 创建并激活虚拟环境

在管理员 CMD 中依次执行以下命令：

conda create -n chat_py_server python=3.10
conda init    # 初始化，然后关闭 cmd 窗口

执行完 conda init 后，务必关闭当前 CMD 窗口，然后重新以管理员身份打开 CMD，再执行激活命令：

conda activate chat_py_server

激活成功后，命令行提示符前会出现 (chat_py_server) 前缀，效果如下：

(chat_py_server) C:\Users\yourname>

注意 ：conda init 会修改环境变量，必须重启 CMD 才能生效。如果激活失败，请检查是否已正确重启终端。

4. 安装依赖

如果你还没有创建项目，可以通过 IntelliJ IDEA 新建项目并创建文件：

1. 启动 IntelliJ IDEA，选择 New Project。
2. 选择 Python 项目类型，并指定解释器为 chat_py_server 环境对应的 Python 解释器路径。
3. 在项目根目录下右键点击，选择 New -> File，输入文件名为 requirements.txt。
4. 编辑该文件，添加所需依赖项。

在激活的 chat_py_server 环境中，创建 requirements.txt 文件，内容如下：

# ---- Web 框架 ----
fastapi==0.115.8
uvicorn==0.34.0
sse-starlette==2.2.1
python-multipart==0.0.20          # FastAPI 处理文件上传 UploadFile 必需

# ---- 日志 ----
loguru==0.7.3

# ---- 配置与数据模型 ----
python-dotenv==1.0.1
pydantic==2.7.4
pydantic-settings==2.8.0
pyyaml==6.0.2

# ---- HTTP 请求 ----
requests==2.32.3
httpx==0.28.1

# ---- OpenAI 客户端 ----
openai==1.64.0

# ---- LangChain / LangGraph 编排 ----
langchain==0.3.19
langchain-core>=0.3.81,<0.4       # 需 >=0.3.81 以支持 Reviver(allowed_objects=...)
langchain-text-splitters==0.3.6
langgraph>=0.3.0,<0.4
langgraph-checkpoint>=2.0,<3.0
langgraph-checkpoint-sqlite>=2.0,<3.0
aiosqlite>=0.19.0,<0.22.0            # AsyncSqliteSaver 异步持久化所需；0.22 起 Connection 不再继承 Thread，is_alive() 报错

# ---- 向量库 ----
pymilvus==2.5.4

# ---- Embedding ----
sentence-transformers==3.4.1
torch==2.6.0

# ---- 文档处理 ----
pymupdf>=1.24.0,<2.0.0
python-docx==1.1.2
openpyxl==3.1.5

# ---- 语音识别（SenseVoiceSmall via sherpa-onnx） ----
sherpa-onnx>=1.10.0
av>=12.0.0                       # 解码浏览器录音（webm/opus、m4a）为 PCM

# ---- 加密 ----
cryptography==42.0.8

# ---- 数据库与缓存（登录鉴权） ----
sqlalchemy>=2.0,<3.0
pymysql>=1.1,<2.0
redis>=5.0,<6.0

# ---- 密码与令牌 ----
bcrypt>=4.0,<5.0
pyjwt>=2.8,<3.0

# ---- 验证码图片 ----
pillow>=10.0,<12.0

然后在终端执行安装命令：

pip install -r requirements.txt

安装过程可能需要几分钟，请耐心等待。安装完成后，可以通过以下命令验证关键依赖是否安装成功：

pip list | findstr "fastapi langchain openai"

5. 如果是已有的项目使用 IDEA 打开项目并选择环境

5.1 打开项目

启动 IntelliJ IDEA，选择 File -> Open，定位到项目根目录并打开。

5.2 配置 Python 解释器

打开项目后，进入 File -> Project Structure -> Project，在 Python Interpreter 一栏点击齿轮图标，选择 Add Interpreter -> Conda Environment -> Existing environment，然后选择我们刚刚创建的 chat_py_server 环境。 也可以直接在 IDEA 右下角的状态栏点击 Python 解释器图标，快速切换解释器。 例如：

5.3 验证环境生效

在 IDEA 的终端（Terminal）中执行：

conda activate chat_py_server
python --version

如果输出 Python 3.10.x，说明环境配置成功。

6. 创建 Hello World 文件

在项目根目录下新建 main.py 文件，编写一个简单的 FastAPI 应用：

from fastapi import FastAPI

app = FastAPI(title="AI Agent Demo")


@app.get("/")
def read_root():
    return {"message": "Hello, AI Agent!"}


@app.get("/health")
def health_check():
    return {"status": "ok"}

在终端中启动服务：

uvicorn main:app --reload --port 8080

启动成功后，控制台输出类似以下日志：

INFO:     Uvicorn running on http://127.0.0.1:8080

此时访问 http://127.0.0.1:8080，浏览器会返回：

{"message": "Hello, AI Agent!"}

访问 http://127.0.0.1:8080/docs，可以看到 FastAPI 自动生成的 Swagger 接口文档，说明项目初始化成功。

7. 小结

本篇完成了 AI 智能体 Python 项目的初始化工作，包括 Conda 虚拟环境创建、依赖安装、IDEA 环境配置、Hello World 接口编写。至此，项目已经可以正常启动运行。

下一篇我们将开始实现核心功能------RAG知识库实战，敬请期待。