大模型应用开发 / 系统课时
准备开发环境
准备开发环境
本课从零搭建一个可复用的 Python 大模型应用工程,完成运行时检查、虚拟环境、依赖管理、目录组织和环境变量配置,并通过一个最小程序验证环境是否可用。
学习目标
- 能检查 Python 与包管理工具是否满足项目要求
- 能创建隔离的虚拟环境并安装锁定范围内的依赖
- 能用环境变量保存配置并完成启动验证
前置检查
建议使用 Python 3.11 或更高版本,并通过 python -m pip 调用与当前解释器对应的 pip。不同系统中命令可能叫 python3 或 python,先确认两者实际指向的版本。
python3 --version
python3 -m pip --version预期输出:
Python <PYTHON_VERSION>
pip <PIP_VERSION> from <PATH> (python <PYTHON_MAJOR_MINOR>)实际版本号和安装路径会不同。若第一条命令不存在,应先安装 Python;若 pip 缺失,可尝试 python3 -m ensurepip --upgrade,再重新检查。
创建隔离项目
下面以 macOS 或 Linux 的 Bash 为例创建项目和虚拟环境。Windows PowerShell 的激活命令是 .venv\Scripts\Activate.ps1,其余 Python 命令保持一致。
mkdir -p llm-app/src
cd llm-app
python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix != sys.base_prefix)"预期输出:
TrueTrue 表示当前 Python 已进入虚拟环境。以后每次打开新终端,都需要先进入项目目录并重新激活 .venv,避免把依赖安装到系统 Python。
项目使用 requirements.txt 管理直接依赖。这里安装 python-dotenv,用于从本地 .env 文件读取环境变量。
printf 'python-dotenv>=1.0,<2.0\n' > requirements.txt
python -m pip install -r requirements.txt
python -c "import dotenv; print('dependency ready')"预期输出:
dependency ready安装过程中的下载地址、版本号和进度日志可能不同,最后一行出现 dependency ready 即表示依赖可导入。团队项目还应在验证通过后生成锁定文件或使用统一的依赖锁定工具,保证不同环境安装到一致版本。
配置目录与环境变量
在项目根目录创建 .env.example,只保存变量名和非敏感示例值。真实 .env 不提交到 Git,生产环境则应通过部署平台、密钥管理服务或容器注入变量。
LLM_API_KEY=local-development-placeholder
LLM_MODEL=demo-model将下面内容保存为 .gitignore:
.venv/
.env
__pycache__/
*.pyc复制示例文件作为本地配置:
cp .env.example .env预期结果:
项目根目录出现 .env 文件;该文件会被 .gitignore 忽略。将下面完整程序保存为 src/app.py。它只验证配置加载,不会向任何模型服务发送请求。
import os
from pathlib import Path
from dotenv import load_dotenv
def main() -> None:
project_root = Path(__file__).resolve().parent.parent
load_dotenv(project_root / ".env")
api_key = os.getenv("LLM_API_KEY")
model = os.getenv("LLM_MODEL", "demo-model")
# 启动时尽早校验必填配置,避免请求阶段才暴露问题。
if not api_key:
raise RuntimeError("LLM_API_KEY is missing")
print("environment ready")
print(f"model={model}")
if __name__ == "__main__":
main()运行与验收
在虚拟环境已激活、依赖已安装且 .env 存在的前提下运行程序:
python src/app.py预期输出:
environment ready
model=demo-model若出现 ModuleNotFoundError: No module named 'dotenv',通常是虚拟环境未激活或依赖装到了别的解释器;重新执行激活命令,并用 python -m pip install -r requirements.txt 安装。若提示 LLM_API_KEY is missing,检查 .env 是否位于项目根目录、变量名是否完全一致,以及文件是否保存成功。
实际接入模型服务前,应把占位密钥替换为真实密钥,但不要写入代码、提交记录、截图或日志。部署时也应先运行同样的配置校验,再启动正式 Web 服务或任务进程。
本课总结
- 虚拟环境可以隔离项目依赖,
python -m pip能避免解释器与 pip 不一致 .env.example用于声明配置,真实密钥应通过环境变量或密钥服务注入- 环境准备完成的标准是依赖可导入、配置可读取、最小程序可成功运行
下一课预告
下一课将基于这个工程接入模型调用接口,处理请求参数、响应内容、超时和错误返回。