AI 生活应用 Python 环境：锁定依赖并一键自检-171主机测评

AI 生活应用 Python 环境：锁定依赖并一键自检

AI 生活应用的 Python 环境应锁定解释器和依赖，启动时自检模型文件与系统库。提供一份小样例输入，能比“在我机器上可用”更快发现差异。

Python 工具链与依赖隔离的三个检查点

Python 项目常见全局 site-packages 污染和间接依赖漂移。构建大模型应用时，可以先检查下面三点：

不要依赖隐式的全局环境。C 扩展、PyTorch 与 GPU 驱动的兼容关系应在初始化脚本中显式检查，失败时给出当前版本和期望范围。

现代化可复现实验构建拓扑

通过这一流程，环境配置不再依赖口耳相传的“文档经验”，而是靠自动化脚本进行硬性把关。

Shell / Python 可部署的环境一键复现与依赖隔离脚手架

以下是一套用于 AI 应用项目的一键环境初始化脚手架代码。包含了 Python 版本探测、Virtualenv 隔离创建、依赖锁强校验以及简单模型推导的冒烟测试。

#!/usr/bin/env python3
import sys
import os
import subprocess
import shutil
import logging
from pathlib import Path

logging.basicConfig(level=logging.INFO, format="[%(asctime)s][%(levelname)s] %(message)s")
logger = logging.getLogger("EnvBootstrap")

REQUIRED_PYTHON_MAJOR = 3
REQUIRED_PYTHON_MINOR = 10
VENV_DIR = Path(".venv")
LOCK_FILE = Path("poetry.lock")

class EnvironmentBootstrapper:
def __init__(self, root_dir: Path):
self.root_dir = root_dir

def check_python_version(self) -> None:
"""1. Python 运行环境版本探针"""
major, minor = sys.version_info.major, sys.version_info.minor
logger.info(f"检测到当前 Python 版本: {major}.{minor}.{sys.version_info.micro}")

if major < REQUIRED_PYTHON_MAJOR or (major == REQUIRED_PYTHON_MAJOR and minor < REQUIRED_PYTHON_MINOR):
logger.error(f"环境初始化阻断：本项目必须要求 Python >={REQUIRED_PYTHON_MAJOR}.{REQUIRED_PYTHON_MINOR}")
sys.exit(1)

def verify_gpu_acceleration(self) -> str:
"""2. 探测 CUDA / Apple Silicon MPS 加速设备"""
try:
import torch
if torch.cuda.is_available():
device = f"CUDA (GPU: {torch.cuda.get_device_name(0)})"
elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
device = "Apple Silicon MPS"
else:
device = "Pure CPU"
logger.info(f"硬件加速设备探针结果: {device}")
return device
except ImportError:
logger.warning("Torch 未安装，跳过 GPU 硬件探针")
return "UNKNOWN"

def create_virtual_environment(self) -> None:
"""3. 自动化独立虚拟环境构建"""
if VENV_DIR.exists():
logger.info(f"虚拟环境目录 {VENV_DIR} 已存在，跳过创建。")
return

logger.info(f"正在创建隔离虚拟环境: {VENV_DIR} …")
try:
subprocess.run([sys.executable, "-m", "venv", str(VENV_DIR)], check=True)
logger.info("虚拟环境创建成功。")
except subprocess.CalledProcessError as e:
logger.error(f"创建虚拟环境失败: {e}")
sys.exit(1)

def install_locked_dependencies(self) -> None:
"""4. 依赖锁定与校验安装"""
pip_path = VENV_DIR / ("Scripts" if os.name == "nt" else "bin") / "pip"

logger.info("正在升级基础构建工具 (pip, setuptools, wheel)…")
subprocess.run([str(pip_path), "install", "–upgrade", "pip", "setuptools", "wheel"], check=True)

# 检查是否存在锁文件
if LOCK_FILE.exists():
logger.info("检测到 poetry.lock 文件，使用 Lockfile 进行精准可复现构建…")
# 优先使用 poetry/uv 进行同步
if shutil.which("poetry"):
subprocess.run(["poetry", "install"], check=True)
return

# 兜底要求安装基本依赖
logger.info("安装核心 AI 依赖库 (requests, pydantic, dataclasses)…")
subprocess.run([str(pip_path), "install", "requests>=2.31.0", "pydantic>=2.0.0"], check=True)

def run_smoke_test(self) -> bool:
"""5. 运行本地冒烟测试并输出失败原因"""
logger.info("开始执行本地运行环境冒烟测试 (Smoke Test)…")
try:
# 简单验证基础包导入与数据模型渲染
from pydantic import BaseModel
class HeartbeatModel(BaseModel):
status: str
timestamp: float

hb = HeartbeatModel(status="OK", timestamp=1700000000.0)
logger.info(f"冒烟测试通过! 测试报文输出: {hb.model_dump_json()}")
return True
except Exception as err:
logger.error(f"冒烟测试失败! 隐患原因: {err}")
return False

def bootstrap(self) -> None:
print("=========================================")
print(" AI 生活化应用一键本地环境构建脚手架 ")
print("=========================================\\n")

self.check_python_version()
self.create_virtual_environment()
self.install_locked_dependencies()

device_info = self.verify_gpu_acceleration()

if self.run_smoke_test():
print("\\n🎉 恭喜！本地环境已成功一次跑通！")
print(f"📌 硬件加速: {device_info}")
print(f"📌 虚拟环境路径: {VENV_DIR.resolve()}")
print("👉 运行指令: source .venv/bin/activate && python main.py\\n")
else:
print("\\n❌ 环境跑通失败，请检查上方报错日志并清理 .venv 后重试。")

if __name__ == "__main__":
bootstrapper = EnvironmentBootstrapper(root_dir=Path("."))
bootstrapper.bootstrap()

把环境自检交给脚手架

脚手架应隐藏可自动处理的环境细节，同时把无法满足的版本与系统依赖明确报出。

在不同机器上运行同一自检命令，记录解释器、依赖和系统库差异。构建是否可复现，由相同输入的产物摘要与测试结果判断。

AI 生活应用 Python 环境：锁定依赖并一键自检