AI 应用 Python 项目的最小工程基线

AI 应用的原型很容易从一个脚本开始，但一旦加入接口、模型调用、文件处理和部署，最先失控的往往是依赖、配置和运行入口。一个足够小的工程基线，能让项目保持可运行、可测试、可交接。

推荐目录

project/
├── app/            # 业务模块与 API
├── tests/          # 自动化测试
├── scripts/        # 维护或开发脚本
├── pyproject.toml  # 依赖与工具配置
├── .env.example    # 仅保留变量名，不放真实值
└── README.md       # 启动方式与边界说明

四个基本约束

1. 使用项目级虚拟环境，避免系统 Python 与项目依赖混用。
2. 用 pyproject.toml 或同等依赖清单固定运行所需的软件包。
3. 配置从环境变量或受控配置文件读取；真实密钥不提交，也不写进日志。
4. 为核心逻辑建立最小测试，至少覆盖正常输入、非法输入和下游失败。

启动前先做三件事

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

这不是所有项目唯一的安装方式，但它明确了三个事实：当前解释器来自项目虚拟环境、依赖安装到该环境、项目本身以可编辑方式运行。出现“本机能跑、换台机器就报错”时，先检查这三个前提。

AI 应用额外要注意的边界

• 模型调用、文件写入和外部工具调用都可能失败；接口应返回可区分的失败状态。
• 长耗时任务不应让 HTTP 请求无限等待，应有任务状态或可查询结果。
• 模型输出不是可信数据，进入数据库、命令或业务流程前需要校验。
• 调试日志只记录必要上下文，避免写入原始对话、上传文件或凭据。

工程化不是提前把项目做复杂，而是给后续变化留出清晰边界。