notebook-lifecycle

Notebook 生命周期

概述

将此技能用于本地到 Kaggle Notebook 的管理：初始化、推送、拉取、运行、检查状态/日志/文件、下载输出，以及删除 kernel。对于 CLI/API，用途上将 Kaggle Notebooks 和 Kaggle kernels 视为同一操作界面。

快速参考

任务	Kaggle CLI
列出 kernels	kaggle kernels list
初始化文件夹	kaggle kernels init -p <folder>
推送/更新/运行	kaggle kernels push -p <folder> [-t <timeout>] [--accelerator <ID>]
拉取源码和元数据	kaggle kernels pull <owner/slug> -p <folder> -m
状态	kaggle kernels status <owner/slug>
文件	kaggle kernels files <owner/slug>
输出	kaggle kernels output <owner/slug> -p <folder> -o [--file-pattern <REGEX>]
日志	kaggle kernels logs <owner/slug>
删除	kaggle kernels delete <owner/slug> --yes

身份验证

执行生命周期命令前，请验证身份验证状态。支持的公开方式包括 kaggle auth login、KAGGLE_API_TOKEN、~/.kaggle/kaggle.json 和 ~/.kaggle/access_token。请勿在回复或日志中打印令牌内容。排查身份验证问题时，可检查文件是否存在及其权限，但不要泄露密钥。

标准工作流

1. 初始化或检查本地文件夹。
2. 推送前验证 kernel-metadata.json；如需修复架构，请加载 kernel-metadata。
3. 确认 code_file 引用的源文件存在，且与 kernel_type/language 相匹配。
4. 选择稳妥的超时时间和加速器。使用 GPU/TPU 运行会消耗配额时，请事先提醒。
5. 使用 kaggle kernels push -p <folder> 推送，可选添加 -t 或 --accelerator。
6. 轮询 kaggle kernels status <owner/slug>，直到运行完成或失败。
7. 使用 logs、files 和 output 诊断问题或获取构件。

拉取与同步

如果用户需要源码和元数据，请使用 kaggle kernels pull <owner/slug> -p <folder> -m。向非空文件夹拉取时要注意覆盖风险：替换本地工作前请先询问，或建议使用新文件夹。拉取后，在将更改推送回去之前，请比较元数据和代码。

获取输出

使用 kaggle kernels output <owner/slug> -p <folder> -o 下载所有输出。添加 --file-pattern <REGEX> 可筛选大量输出文件，例如提交文件或模型构件。提交竞赛前，请确认预期文件均已存在。

对于长时间运行的服务或隧道 Notebook，不要只依赖日志来获取外部所需的连接信息。keepalive 单元格运行期间，日志可能为空。请将发现的信息（例如公开隧道 URL）写入 /kaggle/working/ollama_base_url.txt，然后通过以下命令获取：

kaggle kernels output <owner>/<kernel-slug> -p ./outputs -o --file-pattern "ollama_base_url.txt"

推送后推导 Notebook 浏览器 URL

成功执行 kaggle kernels push 后，Kaggle CLI 并未提供有文档说明且稳定的约定，保证标准输出中包含 Notebook URL。对于端到端管理，如果 kernel-metadata.json 中的 id 字段采用文档说明的标识符格式 owner/kernel-slug，则可据此推导浏览器 URL：

https://www.kaggle.com/code/<owner>/<kernel-slug>

首次成功推送之前，请将其称为预期 URL。成功推送并检查状态后，再将其称为 Notebook URL：

kaggle kernels push -p <notebook-folder>
kaggle kernels status <owner/kernel-slug>

不要依赖解析 kaggle kernels push 的输出获取 URL；CLI 文本可能会变化。不要依赖列表命令中未记录的 CSV 列来构造 URL。私有 Notebook 可能需要登录或相应权限；重命名后 slug 的更改也可能导致之前推导的 URL 失效。

Python API 等效项

调用 API 前，请使用 KaggleApi().authenticate()。相关方法包括 kernels_push、kernels_status、kernels_pull、kernels_output、kernels_list、kernels_logs 和 kernels_delete。除非用户明确要求使用 Python 自动化，否则优先向用户提供 CLI 示例。

安全防护

执行 kaggle kernels delete <owner/slug> --yes 前，必须先征求明确确认；删除操作不可撤销。更改公开可见性、覆盖本地文件夹、推送可能包含机密的代码或运行耗时较长且使用加速器的任务前，也必须先征求确认。如果笔记本源代码或元数据中出现机密信息，请停止操作，并建议将其移至 Kaggle Secrets，而不是推送。

公共 API 的限制

不要声称公共 API 支持笔记本定时运行、机密信息管理、协作者管理、托管笔记本的单元格级编辑、Docker 镜像选择或配额管理。仅在适当时建议使用 Kaggle UI 工作流。

来源

• Kaggle kernels CLI：https://github.com/Kaggle/kaggle-api/blob/main/docs/kernels.md
• Kaggle 笔记本文档：https://www.kaggle.com/docs/notebooks
• Kaggle API 文档：https://www.kaggle.com/docs/api