什么是 Python 虚拟环境？
- 核心定义：虚拟环境 （Virtual Environment） 是 Python 提供的隔离式运行环境，它会在项目目录下创建一个独立的 Python 副本，包含专属的 python.exe、pip 工具和依赖包目录，与系统全局 Python 完全隔离；
- 为什么必须用虚拟环境？ （核心痛点解决）
问题场景 不用虚拟环境的后果 用虚拟环境的优势 多项目依赖冲突A 项目需要 Flask 2.0，B 项目需要 Flask 3.0，全局只能装一个版本，导致项目运行报错 每个项目独立环境，A 装 2.0、B 装 3.0，互不干扰 全局 Python 环境污染安装各种包导致全局 Python 混乱，甚至影响系统工具正常使用 依赖只在项目内部，删除项目即删除环境，不污染系统 权限问题频繁报错全局安装包经常需要管理员权限，容易出现权限不足、文件无法删除等错误 虚拟环境在项目目录下，普通权限即可安装，无权限问题 项目迁移部署困难不知道项目到底用了哪些包，换台电脑就跑不起来 一键导出依赖清单，新环境一键安装，移植零成本
汉化版 PyCharm 虚拟环境 全流程配置
场景 1：新建项目时，自动创建虚拟环境（最推荐，一步到位）
- 打开 PyCharm 点击 【新建项目】；
- 在 【新建项目】 窗口中，按以下配置：
- 位置：选择项目存放的文件夹 （如 D:\Projects\llmops-api）；
- Python 解释器：新环境使用：勾选 ✅；
- 环境类型：选择 【Virtualenv】 （默认，无需修改）；
- 位置：默认 项目目录 /.venv （强烈建议不修改，标准规范，Git 默认忽略）；
- 基础解释器：选择你系统安装的 Python （如 Python 3.9，路径一般为 C:\Python39\python.exe）；
- 继承全局站点包：取消勾选 ❌ （避免全局包污染项目环境）；
- 对所有项目可用：取消勾选 ❌ （保证环境仅属于当前项目）；
- 点击 【创建】，PyCharm 自动完成虚拟环境创建、解释器绑定，全程无需手动操作；
场景 2：已有项目，快速添加虚拟环境（20 秒搞定）
方法 A：右下角快捷入口 （最快）
- 看 PyCharm 右下角，点击当前显示的 【无解释器】/ Python 版本号；
- 在弹出菜单中，选择 【添加解释器…】；
- 左侧选择 【虚拟环境环境】，右侧选择 【新建】；
- 位置：填写 项目目录 /.venv；
- 基础解释器：选择系统 Python；
- 同样取消勾选 【继承全局站点包】 和 【对所有项目可用】；
- 点击 【确定】，等待 5-10 秒，虚拟环境创建完成，自动绑定到项目；
方法 B：设置菜单入口 （适合找不到右下角入口）
- 顶部菜单栏点击 【文件】 → 【设置】 （macOS 为【PyCharm】→【设置】）；
- 展开 【项目：你的项目名】 → 【Python 解释器】；
- 点击右上角 【齿轮】 图标 → 选择 【添加】；
- 后续步骤同方法 A，完成创建；
场景 3：虚拟环境激活、依赖安装（汉化终端操作）
- 激活虚拟环境 （解决 PowerShell 报错）
- 打开 PyCharm 底部 【终端】 （默认 PowerShell）
- 先执行临时解除策略 （仅当前终端生效，安全无风险）：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process - 再执行激活命令：
.venv\Scripts\activate
- 一键安装项目依赖 （对应你的 requirements.txt），在激活的虚拟环境中，执行：
pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple - 依赖导出 （给其他开发者 / 部署用）：
- 自动生成项目依赖清单，包含所有已安装包的精确版本；
- 新环境只需执行
pip install -r requirements.txt即可一键还原环境；
pip freeze > requirements.txt
虚拟环境 核心目录结构详解
- 创建完成后，项目根目录会生成 .venv 文件夹，结构如下 （以 Windows 为例）：
.venv/ ├── Scripts/ # 核心可执行文件目录 │ ├── python.exe # 虚拟环境专属 Python 解释器 │ ├── pip.exe # 虚拟环境专属 pip 工具 │ ├── activate.bat # cmd 环境激活脚本 │ └── activate.ps1 # PowerShell 环境激活脚本 ├── Lib/ # 依赖包安装目录 │ └── site-packages/ # 所有项目依赖包都在这里 └── pyvenv.cfg # 虚拟环境配置文件（记录基础解释器路径等） - 关键说明：
- 绝对不要手动修改 .venv 目录内的文件，否则会导致环境损坏；
- .venv 文件夹不要提交到 Git，PyCharm 会自动在 .gitignore 中添加该目录，避免上传；
- 删除项目时，直接删除 .venv 文件夹即可彻底删除虚拟环境，无残留；
虚拟环境最佳实践
- 每个项目一个独立虚拟环境：绝对不要多个项目共用一个虚拟环境，避免依赖冲突；
- 虚拟环境目录统一命名为 .venv：行业标准，IDE 自动识别，Git 默认忽略；
- 永远不要继承全局站点包：保持环境纯净，避免全局包污染；
- 提交代码时，仅上传 requirements.txt，不上传 .venv：减少仓库体积，保证环境一致性；
- 项目启动前，先激活虚拟环境：养成习惯，避免误操作全局环境；
- 定期清理无用虚拟环境：删除废弃项目时，同步删除对应的 .venv 文件夹，节省磁盘空间；
项目架构与基础框架选择
LLMOps 项目 7 层架构
语言与项目基础框架选择
- 使用 Python 作为后端编程语言虽然性能比不上 Java 等编译型等语言，但是 Python 丰富的生态系统，庞大的 AI 开源模型、机器学习基础库等，是其他语言无法媲美的；
- Flask 是一个轻量级的 web 框架，核心非常小，功能丰富但不臃肿，性能对比 Django 强了不少，零基础也可以快速入门，大大降低了学习难度；
- 对于 LLM 应用开发，可以使 langChain 极大简化开发流程，提升开发效率，其他语言需要自己封装轮子；
项目目录结构约定
- 项目结构：
├── app // 应用入口集合 │ ├── __init__.py │ └── http ├── config // 应用配置文件 │ ├── __init__.py │ ├── config.py │ └── default_config.py ├── internal // 应用所有内部文件夹 │ ├── core // LLM 核心文件，集成 LangChain、LLM、Embedding 等非逻辑代码 │ │ ├── __init__.py │ │ ├── agent │ │ ├── chain │ │ ├── prompt │ │ ├── model_runtime │ │ ├── moderation │ │ ├── tool │ │ └── vector_store │ ├── exception // 通用公共异常目录 │ │ ├── __init__.py │ │ └── exception.py │ ├── extension // Flask 扩展文件目录 │ │ ├── __init__.py │ │ └── database_extension.py │ ├── handler // 路由处理器、控制器目录 │ │ ├── __init__.py │ │ └── account_handler.py │ ├── middleware // 应用中间件目录，包含校验是否登录 │ │ ├── __init__.py │ │ └── middleware.py │ ├── migration // 数据库迁移文件目录，自动生成 │ │ ├── __init__.py │ │ └── versions │ ├── model // 数据库模型文件目录 │ │ ├── __init__.py │ │ └── account.py │ ├── router // 应用路由文件夹 │ │ ├── __init__.py │ │ └── router.py │ ├── schedule // 调度任务、定时任务文件夹 │ │ ├── __init__.py │ │ └── schedule.py │ ├── schema // 请求和响应的结构体 │ │ ├── __init__.py │ │ └── schema.py │ ├── server // 构建的应用，与 app 文件夹对应 │ │ ├── __init__.py │ │ └── server.py │ ├── service // 服务层文件夹 │ │ ├── __init__.py │ │ └── account_service.py │ └── task // 任务文件夹，支持即时任务 + 延迟任务 │ ├── __init__.py │ └── task.py ├── pkg // 扩展包文件夹 │ ├── __init__.py │ ├── oauth │ │ ├── __init__.py │ │ ├── github_oauth.py │ │ └── ... │ └── ... ├── storage // 本地存储文件夹 ├── test // 测试目录 ├── .venv // 虚拟环境 ├── .env // 应用配置文件 ├── .gitignore // 配置 git 忽略文件 ├── requirements.txt // 第三方包依赖管理 └── README.md // 项目说明文件 - 代码运行流程图：
- 项目通过路由接收用户的发起的请求，并调用控制器特定的方法来处理，控制器接收到数据后，对数据进行校验，校验未通过则抛出错误；
- 校验通过后将数据传递给 Service/Core 层进行相应的逻辑处理、数据存储和检索等操作，完成逻辑计算后得到响应数据，返回给控制器，控制器在将数据响应给用户，至此一个最简单的流程结束；
- 文件与 Python 类函数命名规范：
- 文件名：
- 使用全部小写字母；
- 使用下划线分隔单词，例如：app_service.py；
- 尽可能保证文件作用的单一，不要把所有代码一次性写在同一个文件中；
- 类名：
- 使用驼峰命名法，例如：class AppService；
- 类名应该以大写字母开头，每个单词的首字母都大写；
- 如果类名由多个单词组成，单词之间不使用下划线分割；
- 函数名和方法：
- 使用小写字母；
- 使用下划线分隔单词；
- 例如：get_account、generate_token 等；
- 变量名：
- 使用小写字母；
- 使用下划线分隔单词；
- 例如：my_variable、token_count；
- 常量：
- 使用全大写字母；
- 使用下划线分隔单词；
- 例如： MAX_SIZE、PI 等；
- 私有变量与方法：
- 以一个下划线开头表示私有，例如：_my_private_variable、_my_private_method() 等；
- 在 Python 中并没有严格的 私有变量/方法，这种命名约定只是一种约定，而不是强制规则，实际上这些 变量/方法 仍然可以被使用，但是作为一种约定，在外部调用时，不应该调用私有的变量与方法；
- 模块名：
- 与文件名类似，使用全部小写字母，使用下划线分隔单词；
- 例如：my_module.py 对应的模块名应该是 my_module；
- 模块下创建 __init__.py 文件代表当前目录为一个模块，并尽可能在 __init__.py 中使用 __all__ 简化导出；
from .app_handler import AppHandler __all__ = ["AppHandler"]
- 文件名：
Python 中的依赖注入框架 injector
- 依赖注入是软件工程中的一种设计模式，它允许在创建对象时由外部提供依赖关系，而不是自己创建这些依赖关系；
- 简单来说，即我需要什么，传递什么，而不是自己内部构建，Controller 需要使用 Service 的内容，将 Service 作为参数传递给 Controller 即可，在 Python 中可以使用 injector 包来快速实现依赖注入；
- 安装：
pip install injector - 使用示例：
- 其中 @inject 装饰器用于注入，使用 @inject 装饰的函数/类，不需要显式创建依赖对象就可以直接使用；
- 要获取被注入的对象，可以使用 Injector 实例的 get() 方法传入特定的类型，即可获取；
# 1. 导入依赖注入的核心类 from injector import Injector, inject # 2. 定义被依赖的类 A class A: pass # 3. 定义目标类 B，并标记需要注入依赖 # 使用 @inject 装饰器，表示该类的构造函数需要自动注入依赖 @inject class B: # __init__ 方法声明了参数 a: A # injector 会自动寻找 A 的实例并传递进来 def __init__(self, a: A): self.a = a # 4. 运行演示 if __name__ == '__main__': # 创建 Injector 容器 injector = Injector() # 从容器中获取 B 的实例 # injector 会自动发现 B 需要 A，并且 A 已经被正确绑定 b_instance = injector.get(B) # 验证：打印 B 实例中的属性 a，确认其确实是 A 的对象 print(type(b_instance.a)) # 输出: <class '__main__.A'> print("成功注入 A 到 B 中！")
Postgres 数据库
Postgres 是什么？
PostgreSQL = 开源、免费、功能最强、最接近商业级的关系型数据库；
- 开源免费 （无版权风险）；
- 功能比 MySQL 更强大；
- 支持复杂查询、JSON、数组、地理信息、向量搜索；
- 企业级稳定、可靠、可扩展；
- AI 项目常用 （因为支持 pgvector 向量存储）；
核心特点
- 完全开源免费：随便用、随便改、随便商用，无任何坑；
- 高度标准兼容 SQL：几乎支持完整 SQL 标准，写的 SQL 可迁移性强；
- 支持复杂数据类型：
- 数组 int[] text[]；
- JSON / JSONB；
- 日期、UUID、IP、几何、枚举；
- 向量类型 vector （AI 项目必备）；
- 强大的索引：B-tree、哈希、GIN、GiST、SP-GiST、BRINpgvector 向量索引 （做 RAG 知识库必用）；
- 事务、外键、约束、视图、存储过程、触发器全部支持，企业级功能齐全；
- 可扩展性极强，可以装插件：
- pgvector （向量）；
- postgis （地图）；
- pg_cron （定时任务）；
- pg_stat_statements （性能监控）；
- 比 MySQL 更适合：
- 复杂业务系统；
- 数据分析；
- AI 知识库 （向量数据库）；
- 高并发、高数据一致性要求的后台；
Postgres 适用场景
- 普通 Web 后台 （Flask/Django），完全替代 MySQL，更稳定、更强；
- AI 项目 + LangChain，
Postgres + pgvector = 最成熟的向量数据库方案可直接存：- 文档切片；
- 向量 embedding；
- 元数据；
- 用户对话记录；
- 企业管理系统：支持复杂事务、联表查询、权限、视图；
- 数据分析：支持开窗函数、CTE、复杂查询、JSON 处理；
基础 SQL 速查
- 创建数据库：
CREATE DATABASE mydb; - 创建表：
CREATE TABLE users ( id SERIAL PRIMARY KEY, name TEXT NOT NULL, age INT, create_time TIMESTAMP DEFAULT NOW() ); - 插入数据：
INSERT INTO users (name, age) VALUES ('张三', 20); - 查询数据：
SELECT * FROM users WHERE age > 18; - JSON 字段 （Postgres 超强）：
CREATE TABLE docs ( id SERIAL PRIMARY KEY, data JSONB ); INSERT INTO docs (data) VALUES ('{"name":"AI文档","vector":[1,2,3]}'); - 向量字段 （pgvector）：
CREATE TABLE embeddings ( id SERIAL PRIMARY KEY, embedding vector(1536) );
为什么 AI / RAG 项目都爱用 Postgres？
- 因为：
- 既能存业务数据；
- 又能存向量数据；
- 还能做向量相似度检索；
- 不用额外部署专门向量库 （如 Pinecone、Chroma）；
- LangChain 官方直接支持
Postgres + pgvector；
安装与使用
打赏作者
您的打赏是我前进的动力
微信
支付宝
ChatGPT 辅助学习与建议
上一篇
评论
