官方平台用户指南¶

本文根据官方企业微信文档 Tencent Angel Machine Learning Platform User Guide 于 2026-04-25 的只读页面整理，重点保留训练、模型发布、评测、平台规格与环境变量约束，方便在本仓库文档站内查阅。

文档元信息¶

同步方法¶

这份页面的同步分成正文和图片两部分，目标是把内容固化到仓库内，而不是依赖外部登录态或截图留档。

正文同步¶

1. 在已登录的企业微信文档只读页中，优先从编辑器状态直接读取正文，而不是抓取可见 DOM 文本。
2. 这一步使用的页面内对象是 window.pad.editor.state，正文提取调用如下：

window.pad.editor.state.getTextStream().readText(0)

1. 提取结果里会带有少量编辑器残留格式，需要人工整理成当前这份 Markdown，重点保留训练流程、模型发布、评测约束、环境变量和平台规格。

图片同步¶

1. 不使用截图。
2. 先从页面中枚举真实内嵌图片资源，优先读取 img.melo-inline-image 的 src，必要时再从资源加载记录里补全：

Array.from(document.querySelectorAll('img.melo-inline-image')).map((img) => img.src)

Array.from(
    new Set(
        performance
            .getEntriesByType('resource')
            .map((entry) => entry.name)
            .filter((name) => /picgzc\.qpic\.cn\//i.test(name))
    )
)

1. 确认这些 URL 指向真实图片字节后，直接下载到本仓库静态资源目录 docs/assets/figures/guide/official-platform-guide/。
2. 当前页面使用相对路径引用这些本地图片，因此文档站构建后不会依赖腾讯文档登录态。

本地落库与验证¶

1. 将正文整理进当前页面，并把图片以 official-guide-01.png 到 official-guide-10.png 的固定命名落库。
2. 在页面中使用相对路径引用本地图片资源。
3. 完成后运行下面的命令重建文档站：

uv run --no-project --isolated --with zensical zensical build --clean

1. 构建完成后，确认 site/assets/figures/guide/official-platform-guide/ 下已经生成对应图片文件。

官方界面图集¶

下列图片来自官方文档页面中的原始内嵌图片资源，已经同步为本仓库本地静态资产，避免后续查阅依赖外部登录态。

赛事首页与时间线¶

训练流程总览¶

创建训练任务表单¶

创建任务关键区域高亮¶

运行入口 Run¶

运行状态示例¶

Instances 入口¶

实例页操作入口¶

More 菜单常见操作¶

在线脚本编辑器¶

训练任务流程¶

创建与提交¶

1. 填写 Job Name。
2. 填写 Job Description。
3. 通过 Local Upload 上传本地脚本，或通过 New Script 在线新建脚本。
4. 确认无误后点击 Submit 保存训练任务。

启动与查看运行状态¶

1. 点击 Run 启动任务。
2. 启动后，Instance Status 会自动切换到 Training Job Running。
3. 进入 Instances 页面后，可以查看 Output 和 Logs。
4. 如果需要提前终止任务，可以点击 Stop。

常见任务操作¶

• More 菜单支持复制、删除、编辑当前训练任务。
• 模型发布入口在训练任务的实例产物页面，不在训练表单里直接出现。

模型发布与管理¶

发布步骤¶

1. 在训练任务中点击 Instances。
2. 打开 Output。
3. 选中要发布的 checkpoint，点击 Publish。
4. 填写 Model Name 和 Model Description。
5. 提交成功后，Publish Status 会切换为 Released。

发布后管理¶

• 左侧栏的 Model Management 可以查看和管理已发布模型。
• 官方文档提到可以继续做模型编辑或删除，但正文没有给出更细的字段级说明。

评测任务流程¶

入口¶

有两种进入方式：

1. 在 Model Management 页面找到目标模型，点击卡片底部的 Model Evaluation。
2. 直接进入 Model Evaluation 页面，点击 Create Evaluation。

提交要求¶

状态流转¶

依赖安装钩子¶

官方文档说明，评测任务可以额外上传一个严格命名为 prepare.sh 的脚本。它会在推理开始前自动执行，并且执行时所在环境已经是平台预激活的 Conda 环境。

#!/bin/bash

# 1. 该脚本会在推理逻辑开始前自动执行
# 2. 运行位置是平台预激活环境
# 3. 在这里加入你自己的准备步骤

官方原文明确允许在这里执行平台侧环境准备命令；本仓库本地开发和复现实验仍建议按仓库规范使用显式 profile 的 uv 工作流。

平台规格¶

硬件环境¶

官方文档给出的单个 GPU 切片规格如下：

软件环境¶

预装 Python 栈摘要¶

官方文档列出了完整的预装包清单。对本仓库最相关的条目包括：

原文还说明，如果平台默认环境没有你需要的依赖，可以在平台提供的环境里追加安装。

训练阶段环境变量¶

官方变量表¶

读取示例¶

Shell：

${TRAIN_DATA_PATH}

Python：

import os

os.environ.get("TRAIN_DATA_PATH")

输出约束¶

1. 模型权重必须写入 TRAIN_CKPT_PATH。
2. 迭代 checkpoint 必须放在目录名前缀为 global_step 的目录下，否则平台不会识别。
3. checkpoint 目录名长度不能超过 300 个字符。
4. 目录名只允许字母、数字、下划线、连字符、等号和点号。

官方示例里给出的合法命名方式类似：

global_step20.lr=0.001.layer=2.head=1.hidden=50.maxlen=200

TensorBoard 指标¶

• 平台只支持 scalar 指标。
• 官方示例使用 TRAIN_TF_EVENTS_PATH 初始化 SummaryWriter。

from torch.utils.tensorboard import SummaryWriter
import os

writer = SummaryWriter(os.environ.get("TRAIN_TF_EVENTS_PATH"))

评测阶段环境变量¶

官方变量表¶

读取示例¶

Shell：

${EVAL_DATA_PATH}

Python：

import os

os.environ.get("EVAL_DATA_PATH")

predictions.json 规范¶

强制要求¶

1. 主脚本必须严格命名为 infer.py。
2. infer.py 必须包含无参数 main()。
3. main() 必须在 EVAL_RESULT_PATH 下生成 predictions.json。

数据格式¶

示例：

{
    "predictions": {
        "user_001": 0.8732,
        "user_002": 0.1245,
        "user_003": 0.5621
    }
}

额外注意事项¶

• predictions 里的每个 key 都必须是测试集里的有效 user_id。
• 少传、漏传或出现额外 user_id 都可能影响最终得分。
• 每个团队每天最多可提交 3 个评测任务，按 AOE 时区计算；失败和主动停止的任务不计入该限制。

平台强制入口提醒¶

官方文档最后特别强调：训练模板里必须包含 run.sh，平台会在任务启动时自动执行它。

这与本仓库当前的统一入口设计是一致的：无论本地还是线上 bundle，入口都应该围绕 run.sh 展开，而不是依赖手工点击后的隐式启动逻辑。

与本仓库文档的对应关系¶

• 如果你关心平台实测容器资源和我们在线上日志中观察到的差异，见 比赛线上服务器设备信息。
• 如果你要把本仓库实验包上传到线上平台，见 线上训练打包。

与当前仓库观察到的差异¶

这份官方指南与我们仓库内的线上日志观察有一处值得特别注意的差异：

• 官方指南列出的基础软件环境是 Python 3.10.20。
• 我们在 比赛线上服务器设备信息 中记录到的某次任务启动参数里，平台曾显式传入 requested_python=3.13。

更稳妥的理解是：官方指南描述的是平台默认基础镜像，而实际任务仍可能叠加比赛模板、运行脚本或平台侧参数覆盖，因此线上排障时应同时参考官方指南和真实任务日志。

评论