企业官网建设流程全解析

• CLI
• 开发工具
• 数据科学

本篇指南以 Kaggle 官方命令行工具（kaggle-api，即 Kaggle CLI）的 kernels_metadata 文档 为骨架，系统讲解kernel-metadata.json的全部字段语义、取值约束与默认行为，并结合仓库源码（kaggle_api_extended.py）与单元测试（test_kernels_push.py）剖析上传、校验、拉取的底层实现。读完本文，你将能够从零编写一份合法可用的 kernel 元数据文件，熟练使用kaggle kernels init、kaggle kernels push、kaggle kernels pull -m完成新建、更新、回拉内核的全流程，并理解 slug、id_no、machine_shape 等关键字段背后的工作机制。

什么是 kernel-metadata.json？

要在 Kaggle 上上传并运行一个内核（Kernel，即 notebook 或 script），必须为它指定一个特殊的kernel-metadata.json文件。该文件与内核源码（.ipynb、.py、.R、.Rmd等）一起放在同一个目录中，是kaggle kernels push命令读取的唯一配置入口——它声明了这个内核的身份（谁拥有、叫什么）、源码位置、语言与类型、可见性、运行环境（GPU/TPU/网络）以及它依赖的数据源。

在仓库源码中，该文件名被定义为常量KERNEL_METADATA_FILE = "kernel-metadata.json"（见 kaggle_api_extended.py），与dataset-metadata.json、model-metadata.json、competition-metadata.json等并列，是 Kaggle CLI 各资源类型上传时的统一约定。

一个最小可用的基础示例

以下是最基础、可复制使用的kernel-metadata.json示例（来自 kernels_metadata.md 原文）：

{ "id": "timoboz/my-awesome-kernel", "id_no": 12345, "title": "My Awesome Kernel", "code_file": "my-awesome-kernel.ipynb", "language": "python", "kernel_type": "notebook", "is_private": "false", "enable_gpu": "false", "enable_internet": "false", "machine_shape": "", "dataset_sources": ["timoboz/my-awesome-dataset"], "competition_sources": [], "kernel_sources": [], "model_sources": [] }

注意：上例中is_private、enable_gpu、enable_internet均以字符串"false"书写。实际解析时，CLI 通过get_bool兼容布尔值与字符串两种形式（见下文“字段详解”与“源码视角”章节），因此写成 JSON 布尔值false也完全合法。

两条捷径：init 生成模板与 pull 回拉元数据

手动编写容易遗漏字段，官方 CLI 提供了两条互补的途径：

1. 新建内核：使用kaggle kernels init -p /path/to/kernel，CLI 会在指定目录生成一份带占位符的kernel-metadata.json模板。源码中kernels_initialize生成的模板包含id（形如用户名/INSERT_KERNEL_SLUG_HERE）、title、code_file、language、kernel_type、is_private、enable_gpu、enable_tpu、enable_internet、machine_shape以及四类 sources 空数组（见 kaggle_api_extended.py）。命令结束后会打印Kernel metadata template written to: <路径>。

2. 已有内核：使用kaggle kernels pull -p /path/to/download -k username/kernel-slug -m，在下载源码的同时以-m/--metadata参数要求一并生成该内核当前的kernel-metadata.json。拉取时生成的元数据包含服务端返回的完整字段，如id、id_no、title、code_file、language、kernel_type、is_private、enable_gpu、enable_tpu、enable_internet、keywords、四类 sources、docker_image与machine_shape（见 kaggle_api_extended.py）。若当前目录已存在kernel-metadata.json，pull 会优先读取其中的id与code_file来复用命名，避免覆盖本地约定。

这两条命令分别解决了“从零开始”和“从已有内核复制配置”两个场景，是本文手写配置之外的推荐路径。

字段总览与完整语义

官方当前支持以下元数据字段（以下说明对应 kernels_metadata.md 原文的 Contents 章节，并补充了源码层面的默认值与校验行为）：

id与id_no：内核身份标识（二选一，id_no 优先）

• id：内核的 URL slug，格式为用户名slug/内核slug（例如timoboz/my-awesome-kernel）。其中：
  1. 第一段是你的用户名 slug；
  2. 第二段是该内核唯一的 slug。
• id_no：内核的数字 ID。id与id_no两者必须至少指定一个；如果同时指定，id_no会被优先采用（见 kaggle_api_extended.py 的校验逻辑：两者皆缺则报错ID or slug must be specified in the metadata）。
• 源码层面，id中的第三段被视为版本号：若id形如owner/kernel-slug/3，push 会直接报错Kernel metadata 'id' (slug) cannot contain a version（见 kaggle_api_extended.py），版本管理请交给 Kaggle 服务端，不要在元数据里写版本。

title：内核标题

• 新内核必填，已有内核可选。
• 标题与 slug 相互绑定：内核 slug 永远是标题小写化、并用-替换空格后的结果。
• 若想重命名内核，可以直接修改元数据中的title，但必须在重命名完成后同步更新id。
• 源码约束：标题长度至少 5 个字符，否则报错Title must be at least five characters（见 kaggle_api_extended.py）。
• 源码还会将title做 slug 化处理后与id中的 slug 比对，若不匹配会打印警告，提示标题无法解析为指定的 id（见 kaggle_api_extended.py），避免因 slug 与标题脱节导致意外行为。

code_file：源码文件路径（必填）

• 内核源码文件的路径，必填。
• 若非绝对路径，则应相对于kernel-metadata.json所在目录。
• push 时会以os.path.join(folder, code_path)拼接出实际文件路径并检查文件存在，源码缺失报错Source file not found: <路径>；该字段为空则报错A source file must be specified in the metadata（见 kaggle_api_extended.py）。

language：内核语言（必填）

• 合法取值：python、r、rmarkdown。
• 源码常量valid_push_language_types = ["python", "r", "rmarkdown"]（见 kaggle_api_extended.py），非法值直接报错。
• 一个特殊处理：当kernel_type == "notebook"且language == "rmarkdown"时，提交语言会被自动归一化为r（见 kaggle_api_extended.py）。

kernel_type：内核类型（必填）

• 合法取值：script、notebook。
• 源码常量valid_push_kernel_types = ["script", "notebook"]（见 kaggle_api_extended.py）。
• 当类型为notebook时，push 会对.ipynb内容做预处理：清空代码单元格的outputs，并将source数组拼接为单个字符串，以满足服务端对 notebook 结构的预期（见 kaggle_api_extended.py）。

is_private：可见性

• 是否私有。未指定时默认true（即默认为私有内核）。
• 源码通过get_bool(meta_data, "is_private", True)读取，兼容布尔值与字符串（见 kaggle_api_extended.py）。

enable_gpu：GPU 加速

• 是否在 GPU 上运行。未指定时默认false。
• 通过get_bool(meta_data, "enable_gpu", False)读取（见 kaggle_api_extended.py）。

enable_internet：网络访问

• 内核能否访问互联网。未指定时默认false。
• 注意：与文档默认值不同，源码读取默认值为true（get_bool(meta_data, "enable_internet", True)，见 kaggle_api_extended.py），并在 init 模板中默认写入"enable_internet": "true"。实际以你使用的 CLI 版本为准：手写配置时显式给出该字段最为稳妥。

machine_shape：加速器/GPU 类型

• 指定使用的加速器类型，例如NvidiaTeslaT4（GPU T4 ×2）、NvidiaL4、TpuV5E8（TPU v5e-8）。留空""表示使用默认配置。
• push 时字段值会随请求提交，同时--accelerator命令行参数可覆盖元数据中的设置（request.machine_shape = acc if acc else ...，见 kaggle_api_extended.py）。
• 源码内置了“已退役加速器”警告表（见 kaggle_api_extended.py）：例如NvidiaTeslaP100会被提示“会话实际运行在默认 GPU（NvidiaTeslaT4）上”，TpuV38系列会被替换为TpuV5E8，TpuV232/TpuV2256则降级为纯 CPU。使用退役型号时 push 仍会成功，但会打印警告（_warn_if_retired_accelerator，见 kaggle_api_extended.py）。
• 当前可用的加速器清单可参考 kernels.md 中kaggle kernels push一节：NvidiaTeslaT4、NvidiaTeslaA100、NvidiaL4、TpuV5E8、NvidiaL4X1、TpuV6E8、NvidiaH100、NvidiaRtxPro6000；其中部分型号仅对特定竞赛参与者或 Kaggle 管理员开放。

四类 sources：内核依赖的数据源

• dataset_sources：数据集来源列表，格式"username/dataset-slug"（如"timoboz/my-awesome-dataset"）。push 时逐项调用validate_dataset_string校验（见 kaggle_api_extended.py）。
• competition_sources：竞赛来源列表，格式"competition-slug"（不含用户名段）。
• kernel_sources：内核来源列表，格式"username/kernel-slug"，逐项调用validate_kernel_string校验。
• model_sources：模型来源列表，格式"username/model-slug/framework/variation-slug/version-number"（共 5 段，含框架与版本号），逐项调用validate_model_instance_version_string校验（见 kaggle_api_extended.py）。

其他可选字段（源码支持、文档未展开）

• enable_tpu：TPU 加速开关，默认false，通过get_bool(..., False)读取（见 kaggle_api_extended.py），并随kernels pull -m一并回写。
• keywords：内核标签列表，对应服务端category_ids。
• docker_image与docker_image_pinning_type：指定运行镜像及镜像固定策略；docker_image_pinning_type的合法值为original、latest（常量valid_push_pinning_types，见 kaggle_api_extended.py），非法值报错（见 kaggle_api_extended.py）。

官方文档末尾注明：“我们将在后续版本的 API 中增加更多元数据处理。”因此字段集合会持续演进，以所使用 CLI 版本的实际行为为准。

字段速查表

端到端实战：从模板到上线

第一步：初始化模板并编辑

kaggle kernels init -p my-kernel/

将生成的my-kernel/kernel-metadata.json按需修改，例如：

{ "id": "your-username/my-first-cli-kernel", "title": "My First CLI Kernel", "code_file": "my-first-cli-kernel.ipynb", "language": "python", "kernel_type": "notebook", "is_private": false, "enable_gpu": false, "enable_internet": true, "machine_shape": "", "dataset_sources": ["timoboz/my-awesome-dataset"], "competition_sources": [], "kernel_sources": [], "model_sources": [] }

第二步：推送并运行

kaggle kernels push -p my-kernel/

CLI 会依次完成：读取并校验元数据 → 校验 title 长度、language/kernel_type 合法性、id 与 id_no 存在性、源码文件存在性、sources 格式 → 预处理 notebook → 组装ApiSaveKernelRequest提交 → 打印结果 URL。若元数据中的内核已存在于你的账户下则执行更新，否则创建新内核。

常用变体：

# 指定加速器（覆盖元数据中的 machine_shape） kaggle kernels push -p my-kernel/ --accelerator NvidiaTeslaT4 # 限制最大运行时长（秒） kaggle kernels push -p my-kernel/ -t 3600 # 仅保存新版本、不运行（等价于网页端 Quick Save） kaggle kernels push -p my-kernel/ --no-run

push命令同时提供别名update，pull提供别名get（见 cli.py）。

第三步：拉回源码与元数据

kaggle kernels pull -p ./downloaded your-username/my-first-cli-kernel -m

-m/--metadata会同时生成该内核当前的kernel-metadata.json（包含id_no、keywords、docker_image等本地模板中没有的服务端字段），便于你在其他机器上复刻或继续迭代。

源码视角：push 的完整调用链

一次kaggle kernels push的实际执行路径为：

1. CLI 入口parser_kernels_push（cli.py）解析-p/--path、-t/--timeout、--accelerator、--no-run，调用api.kernels_push_cli；
2. kernels_push_cli（kaggle_api_extended.py）调用kernels_push；
3. kernels_push（kaggle_api_extended.py）执行全部校验、notebook 预处理与请求组装，最终调用kaggle.kernels.kernels_api_client.save_kernel(request)；
4. 返回结果后，kernels_push_cli打印版本号、结果状态与内核 URL；若--no-run，则提示“saved without running”。

kaggle kernels pull -m的对应链路则为：kernels_pull_cli→kernels_pull（kaggle_api_extended.py）→kernels_api_client.get_kernel(request)→ 依据服务端返回的 language/kernel_type 推断扩展名（.py/.R/.Rmd/.ipynb/.irnb/.ijlnb等）→ 写源码 → 写元数据。

单元测试（test_kernels_push.py）覆盖了缺失元数据文件、title 过短、code_file 缺失、id 与 id_no 同时缺失、id 含版本号、非法 language/kernel_type、非法docker_image_pinning_type等异常路径，与上述源码校验一一对应，可作为你排查本地元数据问题的参考。

常见错误与排查要点

• ID or slug must be specified in the metadata：id与id_no均缺失，补其一即可。
• Kernel metadata 'id' (slug) cannot contain a version：id写成了owner/kernel-slug/3形式，去掉版本段。
• Title must be at least five characters：title 少于 5 个字符。
• A source file must be specified in the metadata/Source file not found：code_file缺失或相对于元数据目录的路径不正确。
• A valid language must be specified.../A valid kernel type must be specified...：language 或 kernel_type 不在合法取值集合内。
• slug 与 title 不一致警告：title slug 化后与id中的 slug 不符，修改 title 或 id 使之一致。
• 退役加速器警告：machine_shape使用了退役型号（如NvidiaTeslaP100、TpuV38），服务端会自动替换运行环境，建议改用当前可用型号。

总结

kernel-metadata.json是 Kaggle CLI 上传内核的核心契约文件：id/id_no决定内核身份，title与 slug 强绑定，code_file/language/kernel_type决定源码形态，is_private/enable_gpu/enable_internet/machine_shape决定运行环境，四类 sources 决定依赖数据。配合kaggle kernels init生成模板、kaggle kernels pull -m回拉现有配置，你可以完全用命令行完成内核的创建、更新、复制与迭代；遇到异常时，依据 kernels_push 校验源码 与 单元测试 即可快速定位。后续版本的 API 还会继续扩展元数据字段，建议始终以你所安装 CLI 版本的实际行为为准。

• CLI
• 开发工具
• 数据科学