服务器部署与数据存放

\[ \begin{align}\begin{aligned}\newcommand{\ba}{\boldsymbol{a}} \newcommand{\bb}{\boldsymbol{b}} \newcommand{\be}{\boldsymbol{e}} \newcommand{\bq}{\boldsymbol{q}} \newcommand{\bk}{\boldsymbol{k}} \newcommand{\bw}{\boldsymbol{w}} \newcommand{\bx}{\boldsymbol{x}} \newcommand{\by}{\boldsymbol{y}} \newcommand{\bz}{\boldsymbol{z}} \newcommand{\bd}{\boldsymbol{d}} \newcommand{\bv}{\boldsymbol{v}} \newcommand{\bs}{\boldsymbol{s}}\\\newcommand{\btheta}{\boldsymbol{\theta}} \newcommand{\bbeta}{\boldsymbol{\beta}} \newcommand{\bgamma}{\boldsymbol{\gamma}} \newcommand{\bsigma}{\boldsymbol{\sigma}} \newcommand{\md}{\mbox{d}} \newcommand{\bmu}{\boldsymbol{\mu}} \newcommand{\bone}{\boldsymbol{1}} \newcommand{\bzero}{\boldsymbol{0}} \newcommand{\bepsilon}{\boldsymbol{\epsilon}} \newcommand{\bphi}{\boldsymbol{\phi}} \newcommand{\bh}{\boldsymbol{h}} \newcommand{\bc}{\boldsymbol{c}} \newcommand{\br}{\boldsymbol{r}} \newcommand{\bQ}{\boldsymbol{Q}} \newcommand{\bK}{\boldsymbol{K}} \newcommand{\bV}{\boldsymbol{V}} \newcommand{\bSigma}{\boldsymbol{\Sigma}} \newcommand{\bg}{\boldsymbol{g}} \newcommand{\bxi}{\boldsymbol{\xi}} \newcommand{\bvarepsilon}{\boldsymbol{\varepsilon}} \newcommand{\bdelta}{\boldsymbol{\delta}} \newcommand{\bq}{\boldsymbol{q}} \newcommand{\bk}{\boldsymbol{k}} \newcommand{\bJ}{\boldsymbol{J}} \newcommand{\bp}{\boldsymbol{p}} \newcommand{\bi}{\boldsymbol{i}} \newcommand{\bo}{\boldsymbol{o}} \newcommand{\bE}{\boldsymbol{E}} \newcommand{\bH}{\boldsymbol{H}} \newcommand{\bL}{\boldsymbol{L}} \newcommand{\bu}{\boldsymbol{u}} \newcommand{\bLambda}{\boldsymbol{\Lambda}} \newcommand{\trans}{^{\rm\scriptsize T}} \newcommand{\var}{\mathrm{var}}\\\newcommand{\bA}{\boldsymbol{A}} \newcommand{\bB}{\boldsymbol{B}} \newcommand{\bC}{\boldsymbol{C}} \newcommand{\bD}{\boldsymbol{D}} \newcommand{\bG}{\boldsymbol{G}} \newcommand{\bI}{\boldsymbol{I}} \newcommand{\bM}{\boldsymbol{M}} \newcommand{\bP}{\boldsymbol{P}} \newcommand{\bS}{\boldsymbol{S}} \newcommand{\bU}{\boldsymbol{U}} \newcommand{\bW}{\boldsymbol{W}} \newcommand{\bX}{\boldsymbol{X}} \newcommand{\bY}{\boldsymbol{Y}} \newcommand{\bZ}{\boldsymbol{Z}} \newcommand{\cotp}{\textcolor[RGB]{48,209,88}{TP}} \newcommand{\cotn}{\textcolor[RGB]{100,210,255}{TN}} \newcommand{\cofp}{\textcolor[RGB]{94,92,230}{FP}} \newcommand{\cofn}{\textcolor[RGB]{191,90,242}{FN}}\\\newcommand{\numcotp}{\textcolor[RGB]{48,209,88}{50}} \newcommand{\numcotn}{\textcolor[RGB]{100,210,255}{30}} \newcommand{\numcofp}{\textcolor[RGB]{94,92,230}{10}} \newcommand{\numcofn}{\textcolor[RGB]{191,90,242}{10}} \DeclareMathOperator*{\argmin}{arg\,min}\end{aligned}\end{align} \]

服务器部署与数据存放#

　　推荐把“课程源码”“数据缓存”“执行产物”和“公开站点”分成四个位置。最重要的原则是：服务器只公开静态 HTML，不公开原始数据、训练日志、Notebook 临时文件或模型权重。

建议目录#

　　以下只是 Linux 服务器的示例，路径可按权限体系调整：

/srv/ai-course/source/          # 课程源码，只读部署副本
/srv/ai-course/data/            # 数据缓存，可持久化，不对 Web 公开
/srv/ai-course/work/            # Notebook 隔离执行的临时工作区
/srv/ai-course/site/            # Sphinx 生成的静态 HTML，唯一 Web 根目录

　　运行账户应只获得完成任务所需的权限。把环境变量 AI_COURSE_DATA_DIR 指向 /srv/ai-course/data；多个发布任务可共享下载缓存，但不要让 Web 服务器进程直接列目录。

依赖分层#

　　文档构建、传统机器学习和深度学习依赖分开安装，避免仅更新网页时也安装整套 GPU 软件：

python -m venv .venv
.venv/bin/python -m pip install -r requirements/docs.txt
.venv/bin/python -m pip install -r requirements/cases-core.txt
# 需要执行 CNN、RNN、GNN 或扩散案例时再安装：
.venv/bin/python -m pip install -r requirements/cases-torch.txt

　　生产环境还应把解析成功的版本冻结为 constraints 或锁文件，并记录 Python、CUDA 与驱动版本。

发布顺序#

  1. 用 python scripts/validate_cases.py 检查知识点覆盖、Notebook 结构、代码语法、输出清理和本机绝对路径。

  2. 在允许联网的发布任务中增加 --check-urls，确认数据直链仍可匿名访问。

  3. 若只需要正文和代码，使用普通的 make html；此时配置中的 nb_execution_mode='off' 会防止构建阶段意外训练模型。

  4. 若需要发布全部案例的运行结果，在项目根目录运行 python source/scripts/build_case_results.py --include-slow。该命令显式启用 myst-nb 缓存执行，并把表格、数值和图片嵌入 HTML；源码 Notebook 始终保留为空输出。

  5. 结果站点默认生成在 build/html-case-results，不会被之后的普通 make html 覆盖。用 python source/scripts/check_case_site.py build/html-case-results 拒绝混入 CSV、Excel、ZIP、检查点或序列化模型。

  6. 只把通过检查的 build/html-case-results 部署到 Nginx、Caddy 或对象存储的公开根目录。

快速模式与完整实验#

　　计算量较大的案例包含快速模式或抽样路径，适合在自动构建时检查程序能否完整运行。完整训练应由单独的 GPU 作业执行，并记录随机种子、数据摘要、依赖版本、训练预算和检查点来源。不要让访问网页触发 Notebook 执行或下载。

许可与归因#

　　站点应保留 数据来源、直链与许可 页面。UCI 的 CC BY、OGB 的 ODC-BY、MIT 数据以及 EuroSAT 的 Copernicus 条款并不相同；再分发前逐项核对。Project Gutenberg 的公版声明与司法辖区有关，也不应概括成全球无条件公版。