后端Python环境搭建与项目配置

章节介绍

本章主要讲解Python后端开发的基础准备工作，涵盖虚拟环境与编辑器配置、项目架构与框架依赖选择、Postgres数据库与Postman接口调试工具配置三大核心模块，同时详细说明Python环境搭建、镜像加速、项目规范、依赖注入等实操内容，为LLMOps项目开发奠定基础。

一、虚拟环境与编辑器配置

1.1 Python稳定版与发行版差异

不同Python版本的维护状态、发布及终止支持时间对比：

Python版本	维护状态	首次发布	终止支持
3.13	prerelease	2024-10-01	2029-10
3.12	bugfix	2023-10-02	2028-10
3.11	bugfix	2022-10-04	2027-10
3.10	security	2021-10-04	2026-10
3.9	security	2020-10-05	2025-10
3.8	security	2019-10-14	2024-10

1.2 Python虚拟环境的创建与优缺点

1. 创建命令：python -m venv 环境名 Python 2.7+或Python 3.3+以上版本可直接使用内置命令创建，实现一个项目一个虚拟环境。
2. 核心优点：不同虚拟环境相互独立，最大程度避免包版本冲突。
3. 主要缺点：占用更多磁盘空间；使用前需通过activate命令激活，使用后需通过deactivate命令退出。

1.3 腾讯云pip镜像加速配置

1. 加速原理：国内镜像站拷贝了pip官方所有包，本地pip直接连接国内镜像下载，提升安装速度。
2. 使用方式
   • 临时使用：pip install <some-package> -i 镜像地址
   • 全局使用：配置腾讯云镜像源pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple 查看镜像源 pip config list

1.4 PyCharm编辑器配置

涵盖代码格式化与导入优化、常用快捷键使用、插件配置安装，核心目标是提升开发效率（文档未展开具体操作，为后续实操内容）。

二、项目架构与框架依赖选择

2.1 LLMOps项目7层架构

分层架构的核心原则：每一层仅与直接上层/下层交互，不跨层调用，自上而下分为7层：

1. 表示层：PC网站、API开放、APP，搭配Nginx
2. 接入层：Nginx、负载均衡
3. 控制层：AI应用模块、用户模块、授权模块、插件模块
4. 服务层 LLM应用服务、上传服务、授权服务、文本嵌入服务
5. 核心层：多LLM集成、Agent集成；LangChain封装
6. 存储层：Postgres、Redis、向量数据库、对象存储
7. 资源层：Linux服务器、Docker虚拟机、K8s

2.2 语言与项目基础框架选择

1. 后端语言：Python
   • 缺点：性能不如Java等编译型语言
   • 核心优势：拥有庞大的AI开源模型、机器学习基础库生态，是其他语言无法比拟的。
2. Web框架：Flask
   • 特性：轻量级微框架，核心小巧、功能丰富不臃肿，性能优于Django，零基础易入门，降低学习难度。
3. LLM开发：LangChain
   • 作用：极大简化LLM应用开发流程，提升开发效率，避免开发者重复封装基础功能。

2.3 项目目录结构约定、规范与依赖注入

2.3.1 LLMOps项目标准目录结构

├── app/          # 应用入口集合
│   ├── __init__.py
│   └── http/
├── config/       # 应用配置文件
│   ├── __init__.py
│   ├── config.py
│   └── default_config.py
├── internal/     # 应用所有内部文件夹
│   ├── core/     # 核心文件，集成LLM、LangChain、Embedding等非业务逻辑代码
│   │   ├── agent/、chain/、prompt/、model_runtime/等
│   ├── exception/ # 通用公共异常目录
│   ├── extension/ # Flask扩展文件目录
│   ├── handler/   # 路由处理器、控制器目录
│   ├── middleware/ # 应用中间件（如登录校验）
│   ├── migration/ # 数据库迁移文件（自动生成）
│   ├── model/     # 数据库模型文件
│   ├── router/    # 应用路由文件夹
│   ├── schedule/  # 调度/定时任务文件夹
│   ├── schema/    # 请求和响应的结构体
│   ├── server/    # app构建的应用，与app文件夹对应
│   ├── service/   # 服务层文件夹
│   └── task/      # 即时/延迟任务文件夹
├── pkg/          # 扩展包文件夹
│   ├── oauth/、storage/等
├── test/         # 测试目录
├── venv/         # 虚拟环境
├── .env          # 应用配置文件
├── .gitignore    # git忽略文件配置
├── requirements.txt # 第三方包依赖管理
└── README.md     # 项目说明文件

设计原因：Flask灵活性高但团队开发易导致结构混乱，统一目录规范是企业团队开发的必要要求，遵循越规矩，越自由原则。

2.3.2 代码运行流程图

核心流程：请求→控制器→服务/核心层→数据存储层→响应

1. 用户通过浏览器/API/Form以Get/Post等方式发起请求，传递至Controller控制器；
2. 控制器对请求数据进行校验并提取；
3. 校验未通过：直接抛出错误并响应给用户；
4. 校验通过：将数据传递给Service/Core层，进行逻辑处理、数据存储/检索；
5. Service/Core层完成处理后，将响应数据返回给控制器；
6. 控制器将最终数据响应给用户，流程结束。

2.3.3 Python文件与类/函数命名规范

命名对象	命名规则	示例
文件名	全小写+下划线分隔，单一作用	app_service.py
类名	大驼峰命名法，首字母大写，无下划线	class AppService
函数/方法名	全小写+下划线分隔	get_account()、generate_token()
变量名	全小写+下划线分隔	my_variable、token_count
常量	全大写+下划线分隔	MAX_SIZE、PI
私有变量/方法	单下划线开头（约定性，非强制）	_my_private_variable、_my_private_method()
模块名	全小写+下划线分隔，与文件名一致；目录需建init.py，推荐用all简化导出	my_module.py → 模块名my_module

2.3.4 Python中的依赖注入

1. 核心定义：软件工程设计模式，创建对象时由外部提供依赖关系，而非对象内部自行创建，即需要什么，传递什么。
2. 简单示例：Controller需要使用Service的功能时，将Service作为参数传递给Controller，而非Controller内部实例化Service。
3. 推荐框架：Injector（Python轻量级依赖注入框架）

   • 优势：通过装饰器轻松实现依赖注入，无需显式创建依赖对象。

   • 安装命令：pip install injector

   • 使用示例：

     from injector import Injector, inject
     
     class A:
         pass
     
     @inject
     class B:
         def __init__(self, a: A):
             self.a = a
     
     injector = Injector()
     b_instance = injector.get(B)

   • 关键用法：@inject装饰器标记需要注入的类/函数；通过Injector()实例的get()方法获取被注入的对象。

2.4 项目依赖管理

1. 一般方式: pip freeze 查看项目的依赖清单 pip freeze > requirements.txt 但是这样会将所有安装的包都写入文件
2. 工具选择： pipreqs . --encoding=utf8 --force，用于生成项目依赖清单，确保依赖版本稳定，避免随意升级导致项目无法运行。
3. 依赖文件：pip install -r requirements.txt，统一管理第三方包依赖，便于项目部署和团队协作。

三、数据库与接口调试工具

3.1 Postgres数据库安装与配置

3.1.1 Postgres数据库介绍

PostgreSQL（简称Postgres）是开源关系型数据库管理系统（RDBMS），核心特点：

1. 开源免费，支持修改/分发；
2. 完善的SQL支持，强大的数据处理能力；
3. 高可扩展性，支持多种插件；
4. 支持数组、JSON、XML等复杂数据类型；
5. 完整的ACID事务支持，保证数据一致性；
6. 支持触发器、存储过程，可在数据库层实现业务逻辑；
7. 强大的并发控制和用户认证/权限管理能力；
8. 支持全文搜索、地理信息系统等扩展功能。 官网：https://www.postgresql.org/

3.1.2 不同环境下的Postgres安装

（1）Windows环境

1. 下载方式：通过可执行文件安装，下载地址https://www.enterprisedb.com/downloads/postgres-postgresql-downloads；
2. 管理工具：安装后自带pgAdmin可视化工具，用于连接数据库；
3. 服务管理
   • 关闭开机自启：运行services.msc → 找到postgres-x64-16 → 属性修改为手动启动；
   • 启动/停止命令：

     pg_ctl start -D "D:\Software\PostgreSQL\16\data"
     pg_ctl stop -D "D:\Software\PostgreSQL\16\data"

   • 快捷方式：编写bat批处理文件，快速执行启动/停止命令。

（2）Ubuntu/Debian环境

1. 安装命令：

   sudo apt update
   sudo apt install postgresql postgresql-contrib

2. 服务管理：

   sudo systemctl status postgresql # 检测状态
   sudo systemctl start postgresql  # 启动
   sudo systemctl stop postgresql   # 停止

3. 连接数据库
   • 命令行连接：psql -U postgres -h localhost -W
   • 切换postgres用户连接：sudo -u postgres -i → psql
   • 修改postgres密码：\password postgres（psql命令行内执行）
4. 远程登录配置：编辑pg_hba.conf文件，将身份验证方式改为md5：

   local   all             all                                     md5
   host    all             all             127.0.0.1/32            md5
   host    all             all             ::1/128                 md5

5. Postgres常见身份验证方法
   • peer：仅本地连接，客户端需与数据库操作用户同名；
   • md5：密码MD5哈希加密验证（推荐）；
   • password：明文密码验证（不推荐）；
   • trust：免密连接（生产环境禁用）。

（3）Docker环境（快捷安装）

1. 拉取官方镜像：docker pull postgres
2. 运行容器：

   docker run --name postgres-dev -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

3. 容器管理：

   docker start postgres-dev # 启动
   docker stop postgres-dev  # 停止

4. 镜像/容器删除：

   docker rmi <镜像ID/名称> # 删除镜像
   docker rm <容器ID/名称>  # 删除容器

3.2 Postman接口调试工具

涵盖安装配置、环境变量设置、基础URL/路径参数配置、授权认证等内容，为LLMOps项目API接口调试提供支持（文档未展开具体操作，为后续实操内容）。

本章核心总结

1. 环境搭建：掌握Python版本选择、虚拟环境创建、腾讯云pip镜像加速，解决开发环境基础问题；
2. 项目设计：明确LLMOps项目7层架构、Python+Flask+LangChain技术选型，遵循统一的目录/命名规范；
3. 开发技巧：学会使用Injector实现依赖注入，通过pipreqs管理项目依赖，保证开发效率和项目稳定性；
4. 基础配置：掌握Postgres数据库在Windows/Ubuntu/Docker环境的安装与配置，了解Postman接口调试工具的基础使用；
5. 核心原则：团队开发中规范先行，遵循“越规矩，越自由”，为后续LLMOps项目开发做好全方面准备。