AI Research Handbook

外观

Python 与数据处理环境 ​

可复现 Python 项目需要明确解释器版本、直接依赖、锁文件、入口命令和数据获取方式。不要用“在我的 base 环境里能跑”作为交付标准。

Python ​

项目代码放在包或 src/ 中，Notebook 负责探索，最终实验通过脚本或模块入口运行。用 python -m package.module 可减少当前目录和导入路径造成的差异。

text
project/
├── pyproject.toml
├── uv.lock
├── src/project/
├── tests/
├── notebooks/
└── README.md

随机种子、设备、数据划分和关键参数进入配置或命令行；不要把它们散落在 Notebook 单元格与全局变量中。

pip 与 venv ​

标准库 venv 加 pip 是轻量基线：

bash
python -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -r requirements.txt

始终用 python -m pip 确认 pip 属于当前解释器。pip freeze 会记录完整环境，但不区分直接和传递依赖；新项目更适合使用 pyproject.toml 与锁文件。

uv ​

uv 可管理 Python、环境、依赖、锁文件和命令执行：

bash
uv init
uv python pin 3.12
uv add torch pandas
uv add --dev pytest ruff
uv run pytest
uv sync --frozen

提交 pyproject.toml 和 uv.lock，忽略 .venv/。CI 和服务器使用 uv sync --frozen，让锁文件不一致直接失败。已有项目迁移时先在独立分支比较依赖解析与测试结果，不要同时更换 Python、CUDA 和训练代码。

Conda 与 Mamba ​

Conda 同时管理 Python 与系统级二进制包，适合 CUDA、地学或生物信息等复杂科学环境；Mamba 提供兼容但更快的解析体验。

bash
conda create -n research python=3.12
conda activate research
conda env export --from-history > environment.yml

尽量不要在同一环境中无规则混用 Conda 与 pip。确需混用时先装 Conda 包，再用当前环境的 Python 调用 pip，并记录原因。

JupyterLab ​

Notebook 适合探索和讲解，不适合隐藏生产管线。运行前重启 Kernel 并从上到下执行，确认没有依赖历史状态；把稳定函数移入 src/ 并测试，Notebook 只调用它们。

远程使用时让 Jupyter 监听 127.0.0.1，通过 SSH 隧道访问。输出中可能包含数据、Token 和绝对路径，提交前清理敏感内容和巨大单元格输出。

NumPy、pandas 与 scikit-learn ​

  • NumPy 提供定长同类型数组、广播和向量化计算。
  • pandas 处理带列名的表格、缺失值、连接和分组。
  • scikit-learn 提供预处理、传统模型、Pipeline、交叉验证和指标。
python
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression

model = make_pipeline(StandardScaler(), LogisticRegression())
model.fit(X_train, y_train)
score = model.score(X_test, y_test)

数据划分必须发生在学习预处理参数之前，避免泄漏。表格连接后检查行数和键唯一性，数组运算检查 shape、dtype、NaN 和单位。

参考：Python 文档、uv 文档、Conda 文档、Jupyter 文档、scikit-learn 用户指南。