2. 环境搭建：Python虚拟环境创建、依赖管理（pip/poetry）、项目目录结构设计、版本控制（Git）初始化

# 安装 Poetry（推荐使用官方安装脚本）
curl -sSL https://install.python-poetry.org | python3 -

# 验证安装
poetry --version

# 在项目目录初始化 Poetry
poetry init

# 添加依赖（自动更新 pyproject.toml 和 poetry.lock）
poetry add fastapi uvicorn pydantic scikit-learn shap pandas numpy

# 安装所有依赖
poetry install

# 激活 Poetry 虚拟环境
poetry shell

2.2.3 两种方案对比

本课程采用 Poetry 作为依赖管理工具，因其锁定机制能确保开发、测试、生产环境依赖完全一致。

2.3 项目目录结构设计

良好的目录结构提升代码可维护性和团队协作效率。以下是本课程推荐的结构：

explainable-ai-score-api/
├── .venv/                    # 虚拟环境（Git 忽略）
├── app/                      # 应用主代码
│   ├── __init__.py
│   ├── main.py               # FastAPI 应用入口
│   ├── api/                  # API 路由层
│   │   ├── __init__.py
│   │   └── v1/               # API 版本 v1
│   │       ├── __init__.py
│   │       └── endpoints.py  # 评分接口端点
│   ├── core/                 # 核心业务逻辑
│   │   ├── __init__.py
│   │   ├── model.py          # 模型加载与预测
│   │   └── explainer.py      # SHAP 解释器封装
│   ├── schemas/              # Pydantic 数据模型
│   │   ├── __init__.py
│   │   └── request_response.py
│   └── utils/                # 工具函数
│       ├── __init__.py
│       └── logger.py
├── tests/                    # 测试代码
│   ├── __init__.py
│   ├── test_api.py
│   └── test_model.py
├── models/                   # 训练好的模型文件
│   └── credit_model.pkl
├── notebooks/                # Jupyter 探索笔记
├── .gitignore                # Git 忽略规则
├── pyproject.toml            # Poetry 项目配置
├── poetry.lock               # 依赖锁定文件
├── README.md                 # 项目说明文档
└── Dockerfile                # 容器化部署配置

2.4 版本控制（Git）初始化

Git 是项目协作和版本回溯的基石。初始化步骤包括：创建仓库、配置忽略规则、首次提交。

2.4.1 初始化 Git 仓库

# 在项目根目录执行
git init

# 配置用户信息（首次使用 Git 时）
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 查看当前状态
git status

2.4.2 编写 .gitignore 文件

.gitignore 告诉 Git 哪些文件不需要纳入版本控制。以下是本项目的推荐配置：

# Python 虚拟环境
.venv/
venv/
env/

# Python 缓存
__pycache__/
*.py[cod]
*.so

# IDE 配置
.vscode/
.idea/
*.swp
*.swo

# 模型文件（体积大，不纳入版本控制）
models/*.pkl
models/*.h5

# 数据集
data/*.csv
data/*.xlsx

# Jupyter 检查点
.ipynb_checkpoints/

# 日志文件
*.log

# 操作系统文件
.DS_Store
Thumbs.db

# Poetry 虚拟环境目录（如果 Poetry 创建在项目内）
.poetry/

2.4.3 首次提交

# 添加所有文件到暂存区
git add .

# 查看即将提交的文件列表
git status

# 创建首次提交
git commit -m "chore: 初始化项目结构，配置 Poetry 和 Git"

# 关联远程仓库（以 GitHub 为例）
git remote add origin https://github.com/your-username/explainable-ai-score-api.git

# 推送到远程仓库
git push -u origin main

2.5 环境验证

完成上述步骤后，执行以下命令验证环境是否就绪：

# 1. 确认虚拟环境激活
which python
# 输出应包含 .venv

# 2. 确认 Poetry 安装
poetry --version
# 输出类似 Poetry (version 1.7.1)

# 3. 确认依赖安装
poetry show --tree
# 应列出所有已安装的依赖及其依赖树

# 4. 确认 Git 状态
git log --oneline
# 应显示首次提交记录

# 5. 确认项目结构
ls -la
# 应包含 app/ tests/ models/ pyproject.toml .gitignore 等