jupyter-notebook-writing

技能：编写 Jupyter Notebook

以 DevRel 工作流编写面向应用的 Milvus Jupyter Notebook 示例。采用 Markdown 优先的方法——AI 编辑 .md 文件，然后通过 jupyter-switch 转换为 .ipynb。

前置条件：Python >= 3.10，uv（可使用 uvx 命令）

---

适用场景

用户想要创建或编辑 Jupyter Notebook 示例，通常用于演示如何在应用场景中使用 Milvus（RAG、语义搜索、混合搜索等）。

---

核心工作流：优先编辑 Markdown

Jupyter .ipynb 文件包含复杂的 JSON，其中有元数据、输出和执行计数——直接让 AI 编辑十分麻烦。可改用以下方式：

1. 编写/编辑 .md 文件——AI 使用简洁的 Markdown
2. 转换为 .ipynb——使用 jupyter-switch 生成可运行的 Notebook
3. 保持两个文件同步——编辑时以 .md 作为事实来源

格式约定

在 .md 文件中：

• Python 代码块（```python ... ```）会成为 Notebook 中的代码单元格
• 其他所有内容都会成为Markdown 单元格
• .md 中不会保留单元格输出（运行 Notebook 时会生成输出）

转换命令

# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# produces example.ipynb

# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# produces example.md

• 原始输入文件不会被修改或删除
• 如果输出文件已存在，会自动创建 .bak 备份

---

分步说明

创建新的 Notebook

1. 使用相应内容创建 example.md（参见下方结构）
2. 转换：uvx jupyter-switch example.md
3. 此时 example.md 和 example.ipynb 均已存在

编辑现有 Notebook

1. 如果只有 .ipynb，先进行转换：uvx jupyter-switch example.ipynb
2. 编辑 .md 文件
3. 转换回 .ipynb：uvx jupyter-switch example.md

测试/运行

1. 确定 Jupyter 执行环境

运行任何 Notebook 之前，必须先确定要使用哪个 Python 环境。系统默认的 jupyter execute 可能没有安装所需的软件包。

步骤 A — 检测可用环境。

# Discover conda/mamba environments
conda env list 2>/dev/null || mamba env list 2>/dev/null

# Discover registered Jupyter kernels
jupyter kernelspec list 2>/dev/null

# Check system default Python
which python3 2>/dev/null && python3 --version 2>/dev/null

# Check for local virtual environment in the working directory
ls -d .venv/ venv/ 2>/dev/null

# Check if a uv-managed project (pyproject.toml + .venv)
test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"

步骤 B — 询问用户要使用哪个环境。 提供带编号的选项列表，并包含所有检测到的环境：

1. 系统默认环境——直接运行 jupyter execute，不使用 --kernel_name
2. 检测到的每个 conda/mamba 环境——显示名称和路径
3. 已注册的每个 Jupyter 内核——显示内核名称
4. 本地 venv（如果在工作目录中找到 .venv/ 或 venv/）——使用该 venv 中的 Python
5. 自定义——让用户输入 Python 路径或环境名称

**关于 uv 项目的说明：**如果工作目录中有 pyproject.toml 和 .venv/（即由 uv 管理的项目），本地 venv 选项已涵盖这种情况。如果项目依赖中包含 jupyter，用户也可以直接运行 uv run jupyter execute example.ipynb。

提示示例：

Which Python environment should I use to run this notebook?

1. System default (jupyter execute as-is)
2. conda: myenv (/path/to/envs/myenv)
3. Jupyter kernel: some-kernel
4. Local venv (.venv/)
5. Custom — enter a path or environment name

步骤 C — 使用所选环境：

场景	操作
已注册的 Jupyter 内核	使用 jupyter execute --kernel_name=<name>
尚未注册为内核的 Conda 环境	先注册：<env-python> -m ipykernel install --user --name <name> --display-name "<label>"，然后使用 --kernel_name=<name>
自定义 Python 路径	同上——先注册为内核，然后使用 --kernel_name

2. 准备笔记本以供执行

运行前，请将 .md 文件中仅用于设置的单元格注释掉——这些单元格面向首次使用者，但不应在自动化测试环境中运行。具体包括：

• pip install 单元格——所选 Jupyter 环境中应已安装依赖项。如果缺少任何软件包或需要升级，请在目标环境中于笔记本外安装（使用 --upgrade），不要在笔记本内安装。
• API 密钥／凭据占位符单元格——例如 os.environ["OPENAI_API_KEY"] = "sk-***********"。请改为在运行前于外部设置环境变量（在 shell 中导出，或在 jupyter execute 之前通过代码注入）。
• 模拟／仅用于演示的单元格——任何纯粹用于演示、在实际运行中会报错或造成干扰的单元格。

要注释掉某个单元格，请将其内容包在块注释中，这样该单元格仍会执行（并产生空输出），但不执行任何操作：

# # pip install --upgrade langchain pymilvus
# import os
# os.environ["OPENAI_API_KEY"] = "sk-***********"

这样既能保持笔记本结构不变（单元格数量和顺序不变），又能避免与外部 Jupyter 环境发生冲突。

**对于环境变量：**可以在运行 jupyter execute 前于 shell 中使用 export 设置，也可以将它们添加到命令前面：

OPENAI_API_KEY="sk-real-key" jupyter execute --kernel_name=<name> example.ipynb

3. 转换并运行

1. 如有需要，将 .md 转换为 .ipynb
2. 在目标环境中于外部安装任何缺失的依赖项：<env-python> -m pip install --upgrade <packages>
3. 运行：jupyter execute --kernel_name=<name> example.ipynb（如果使用系统默认内核，则省略 --kernel_name）
4. 如果发现错误，请在 .md 文件中修复；如需调试，可取消设置单元格的注释，然后重新转换

---

笔记本结构模板

典型的 Milvus 示例笔记本遵循以下结构：

# Title

Brief description of what this notebook demonstrates.

## Prerequisites

Install dependencies:

` ``python
!pip install pymilvus some-other-package
` ``

## Setup

Import and configuration:

` ``python
from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")
` ``

## Prepare Data

Load or generate example data:

` ``python
# data preparation code
` ``

## Create Collection & Insert Data

` ``python
# collection creation and data insertion
` ``

## Query / Search

` ``python
# search or query examples
` ``

## Cleanup

` ``python
client.drop_collection("example_collection")
` ``

---

参考文档

此技能在 references/ 下包含两份参考文档。当任务涉及其中的主题时，请阅读相应文档。

参考文档	阅读时机	文件
Bootcamp Format	编写 Milvus 集成教程时（徽章、文档结构、章节格式、示例布局）	references/bootcamp-format.md
Milvus Code Style	编写 pymilvus 代码时（集合创建、MilvusClient 连接参数、架构模式、最佳实践）	references/milvus-code-style.md

Bootcamp Format (references/bootcamp-format.md)

如果用户正在为 bootcamp 仓库编写 Milvus 集成教程，请阅读本文档。内容包括：

• 徽章格式（顶部的 Colab + GitHub 徽章）
• 文档结构：标题 -> 先决条件 -> 主要内容 -> 结论
• 依赖项安装格式，以及 Google Colab 重启提示
• API 密钥占位符约定（"sk-***********"）
• 每个代码块前都应有简短的文字介绍

Milvus Code Style (references/milvus-code-style.md)

如果笔记本涉及 pymilvus 代码，请阅读本文档。主要规则：

• 始终使用 MilvusClient API——切勿使用旧版 ORM 层（connections.connect()、Collection()、FieldSchema() 等）
• 始终显式定义架构（create_schema + add_field）——不要使用不带架构的快捷方式 create_collection(dimension=...)
• 创建集合前，先检查 has_collection
• 在 create_collection() 中添加注释掉的 consistency_level="Strong" 行
• 无需调用 load_collection()——集合在创建时会自动加载
• 首次连接 MilvusClient 时，必须包含说明 uri 选项的引用块（Milvus Lite / Docker / Zilliz Cloud）

---

重要说明

• 始终编辑 .md 文件，不要直接编辑 .ipynb。.md 更便于 AI 阅读和编写。
• 保留两个文件——.md 用于编辑，.ipynb 用于运行和分享。
• 编辑 .md 后，务必重新运行 uvx jupyter-switch example.md，以同步 .ipynb。