jupyter-notebook-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Jupyter Notebook Writing

技能：Jupyter Notebook编写

Write Milvus application-level Jupyter notebook examples as a DevRel workflow. Uses a Markdown-first approach — AI edits

.md

files, then converts to

.ipynb

via

jupyter-switch

Prerequisites: Python >= 3.10, uv (
uvx
command available)

作为DevRel工作流，编写Milvus应用级别的Jupyter Notebook示例。采用Markdown优先的方法——AI编辑

.md

文件，然后通过

jupyter-switch

转换为

.ipynb

格式。

前置要求：Python >= 3.10，已安装uv（可使用
uvx
命令）

When to Use

适用场景

The user wants to create or edit a Jupyter notebook example, typically demonstrating Milvus usage in an application context (RAG, semantic search, hybrid search, etc.).

用户希望创建或编辑Jupyter Notebook示例，通常用于展示Milvus在应用场景中的用法（如RAG、语义搜索、混合搜索等）。

Core Workflow: Markdown-First Editing

核心工作流：Markdown优先编辑

Jupyter

.ipynb

files contain complex JSON with metadata, outputs, and execution counts — painful for AI to edit directly. Instead:

Write/Edit the
.md
file — AI works with clean Markdown
Convert to
.ipynb
— using
```
jupyter-switch
```
for runnable notebook
Keep both files in sync — the
```
.md
```
is the source of truth for editing

Jupyter的

.ipynb

文件包含复杂的JSON结构，包含元数据、输出结果和执行次数——AI直接编辑这类文件非常麻烦。因此我们采用以下方式：

编写/编辑
.md
文件 —— AI处理简洁的Markdown格式
转换为
.ipynb
—— 使用
```
jupyter-switch
```
生成可运行的Notebook
保持两个文件同步 ——
```
.md
```
文件是编辑的权威源

Format Convention

格式约定

In the

.md

file:

Python code blocks (
```
```python ... ```
```
) become code cells in the notebook
Everything else becomes markdown cells
Cell outputs are not preserved in
```
.md
```
(they get generated when running the notebook)

在

.md

文件中：

Python代码块（
```
```python ... ```
```
）会转换为Notebook中的代码单元格
其他所有内容会转换为Markdown单元格
单元格输出不会保留在
```
.md
```
文件中（运行Notebook时会自动生成）

Conversion Commands

转换命令

bash

undefined

bash

undefined

Markdown -> Jupyter Notebook

uvx jupyter-switch example.md

produces example.ipynb

生成 example.ipynb

Jupyter Notebook -> Markdown

uvx jupyter-switch example.ipynb

produces example.md

生成 example.md


- The original input file is never modified or deleted
- If the output file already exists, a `.bak` backup is created automatically

---


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

---

Step-by-Step

分步指南

Creating a New Notebook

创建新Notebook

Create
```
example.md
```
with the content (see structure below)
Convert:
```
uvx jupyter-switch example.md
```
Both
```
example.md
```
and
```
example.ipynb
```
now exist

创建包含内容的
```
example.md
```
文件（参考下方结构）
执行转换：
```
uvx jupyter-switch example.md
```
此时
```
example.md
```
和
```
example.ipynb
```
文件都会存在

Editing an Existing Notebook

编辑现有Notebook

If only
```
.ipynb
```
exists, convert first:
```
uvx jupyter-switch example.ipynb
```
Edit the
```
.md
```
file
Convert back:
```
uvx jupyter-switch example.md
```

如果只有

.ipynb

文件，先转换为

.md

：

uvx jupyter-switch example.ipynb

编辑
```
.md
```
文件
转换回
```
.ipynb
```
：
```
uvx jupyter-switch example.md
```

Testing / Running

测试/运行

1. Resolve the Jupyter execution environment

1. 确定Jupyter执行环境

Before running any notebook, you must determine which Python environment to use. The system default

jupyter execute

may not have the required packages installed.

Step A — Check for saved preference. Look in the current project's

CLAUDE.local.md

for a

## Jupyter Notebook Execution

section. If it contains a kernel name, use it directly and skip to Step 2.

Step B — If no saved preference, ask the user. Detect available environments first:

bash

undefined

在运行Notebook之前，必须确定要使用的Python环境。系统默认的

jupyter execute

可能没有安装所需的依赖包。

步骤A — 检查已保存的偏好设置：查看当前项目的

CLAUDE.local.md

文件中是否有

## Jupyter Notebook Execution

章节。如果包含内核名称，直接使用该内核，跳过步骤2。

步骤B — 如果没有保存的偏好设置，询问用户：先检测可用环境：

bash

undefined

Discover conda/mamba environments

发现conda/mamba环境

conda env list 2>/dev/null || mamba env list 2>/dev/null

Discover registered Jupyter kernels

发现已注册的Jupyter内核

jupyter kernelspec list 2>/dev/null

Check system default Python

检查系统默认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)

检查是否为uv管理的项目（pyproject.toml + .venv）

test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"


Then present a numbered list of choices. Include all detected environments:

1. **System default** — run `jupyter execute` as-is, no `--kernel_name`
2. **Each detected conda/mamba environment** — show name and path
3. **Each registered Jupyter kernel** — show kernel name
4. **Local venv** (if `.venv/` or `venv/` found in working directory) — the Python inside that venv
5. **Custom** — let the user type a Python path or environment name

> **Note on uv projects:** If the working directory has `pyproject.toml` + `.venv/` (a uv-managed project), the local venv option covers this case. The user can also run `uv run jupyter execute example.ipynb` directly if jupyter is a project dependency.

For every option, also offer a "remember" variant. Example prompt:

Which Python environment should I use to run this notebook?

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

Tip: add "remember" to save your choice (e.g. "2, remember"), so it gets written to CLAUDE.local.md and I won't ask next time.


**Step C — Apply the chosen environment:**

| Scenario | Action |
|----------|--------|
| Already a registered Jupyter kernel | Use `jupyter execute --kernel_name=<name>` |
| Conda env not yet registered as kernel | Register first: `<env-python> -m ipykernel install --user --name <name> --display-name "<label>"`, then use `--kernel_name=<name>` |
| Custom Python path | Same as above — register as kernel first, then use `--kernel_name` |

**Step D — If the user chose "remember":** append or update a `## Jupyter Notebook Execution` section in the current project's `CLAUDE.local.md`:

```markdown

test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"


然后列出所有检测到的环境选项：

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

> **关于uv项目的注意事项**：如果工作目录包含`pyproject.toml` + `.venv/`（uv管理的项目），本地虚拟环境选项已覆盖此场景。用户也可以直接运行`uv run jupyter execute example.ipynb`（如果jupyter是项目依赖）。

对于每个选项，还提供"记住"变体。示例提示：

我应该使用哪个Python环境来运行此Notebook？

系统默认（直接运行jupyter execute）
conda: myenv (/path/to/envs/myenv)
Jupyter内核: some-kernel
本地虚拟环境 (.venv/)
自定义 —— 输入路径或环境名称

提示：添加"remember"以保存您的选择（例如"2, remember"），这样会写入CLAUDE.local.md，下次我就不会再询问了。


**步骤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` |

**步骤D — 如果用户选择"记住"**：在当前项目的`CLAUDE.local.md`中追加或更新`## Jupyter Notebook Execution`章节：

```markdown

Jupyter Notebook Execution

Jupyter kernel:
```
<kernel-name>
```


This ensures future runs skip the prompt and use the saved kernel directly.

Jupyter内核:
```
<kernel-name>
```


这样后续运行时会跳过提示，直接使用保存的内核。

2. Prepare the notebook for execution

2. 准备Notebook以执行

Before running, comment out "setup-only" cells in the

.md

file — cells that are meant for first-time users but should not run in an automated test environment. Specifically:

pip install
cells — dependencies should already be installed in the chosen Jupyter environment. If any packages are missing or need upgrading, install them externally in the target environment (with
```
--upgrade
```
), not inside the notebook.
API key / credential placeholder cells — e.g.
```
os.environ["OPENAI_API_KEY"] = "sk-***********"
```
. Instead, set environment variables externally before running (export in shell, or inject via code before
```
jupyter execute
```
).
Mock / demo-only cells — any cells that exist purely for illustration and would fail or interfere in a real run.

To comment out a cell, wrap its content in a block comment so the cell still executes (producing empty output) but does nothing:

python

undefined

运行前，在

.md

文件中注释掉"仅用于设置"的单元格——这些单元格是为首次使用的用户准备的，但在自动化测试环境中不应运行。具体包括：

pip install
单元格 —— 依赖包应已安装在所选的Jupyter环境中。如果缺少或需要升级依赖包，在目标环境外部安装（使用
```
--upgrade
```
参数），不要在Notebook内部安装。
API密钥/凭证占位符单元格 —— 例如
```
os.environ["OPENAI_API_KEY"] = "sk-***********"
```
。应在运行前通过外部设置环境变量（在shell中export，或在
```
jupyter execute
```
前通过代码注入）。
模拟/仅演示用单元格 —— 任何仅用于演示、在实际运行中会失败或干扰的单元格。

要注释单元格，将其内容包裹在块注释中，这样单元格仍会执行（产生空输出）但不会执行实际操作：

python

undefined

# pip install --upgrade langchain pymilvus

import os

os.environ["OPENAI_API_KEY"] = "sk-***********"


This keeps the notebook structure intact (cell count, ordering) while preventing conflicts with the external Jupyter environment.

**For environment variables:** either `export` them in the shell before running `jupyter execute`, or prepend them to the command:

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


这样可以保持Notebook的结构完整（单元格数量、顺序不变），同时避免与外部Jupyter环境冲突。

**关于环境变量**：可以在shell中export，或者在`jupyter execute`命令前添加：

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

3. Convert and run

3. 转换并运行

Convert
```
.md
```
to
```
.ipynb
```
if needed
Install any missing dependencies in the target environment externally:
```
<env-python> -m pip install --upgrade <packages>
```

Run:

jupyter execute --kernel_name=<name> example.ipynb

(omit

--kernel_name

if using system default)

If errors found, fix in the
```
.md
```
file, uncomment setup cells if needed for debugging, and re-convert

如有需要，将
```
.md
```
转换为
```
.ipynb
```
在目标环境外部安装任何缺失的依赖：
```
<env-python> -m pip install --upgrade <packages>
```

运行：

jupyter execute --kernel_name=<name> example.ipynb

（如果使用系统默认，省略

--kernel_name

）

如果发现错误，在
```
.md
```
文件中修复，调试时可取消设置单元格的注释，然后重新转换

Notebook Structure Template

Notebook结构模板

A typical Milvus example notebook follows this structure:

markdown

undefined

典型的Milvus示例Notebook遵循以下结构：

markdown

undefined

Title

标题

Brief description of what this notebook demonstrates.

简要描述此Notebook演示的内容。

Prerequisites

前置要求

Install dependencies:

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

安装依赖：

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

Setup

设置

Import and configuration:

` ``python from pymilvus import MilvusClient

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

导入和配置：

` ``python from pymilvus import MilvusClient

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

Prepare Data

准备数据

Load or generate example data:

` ``python

加载或生成示例数据：

` ``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")

---

``python client.drop_collection("example_collection")

---

Reference Documents

参考文档

This skill includes two reference documents under

references/

. Read them when the task involves their topics.

Reference	When to Read	File
Bootcamp Format	Writing a Milvus integration tutorial (badges, document structure, section format, example layout)	`references/bootcamp-format.md`
Milvus Code Style	Writing pymilvus code (collection creation, MilvusClient connection args, schema patterns, best practices)	`references/milvus-code-style.md`

本技能在

references/

目录下包含两份参考文档。当任务涉及相关主题时，请阅读这些文档。

参考文档	适用场景	文件
Bootcamp格式	编写Milvus集成教程（徽章、文档结构、章节格式、示例布局）	`references/bootcamp-format.md`
Milvus代码风格	编写pymilvus代码（集合创建、MilvusClient连接参数、模式、最佳实践）	`references/milvus-code-style.md`

Bootcamp Format (

references/bootcamp-format.md

)

Bootcamp格式 (

references/bootcamp-format.md

)

Read this when the user is writing a Milvus integration tutorial for the bootcamp repository. It covers:

Badge format (Colab + GitHub badges at the top)
Document structure: Header -> Prerequisites -> Main Content -> Conclusion
Dependency install format with Google Colab restart note
API key placeholder conventions (
```
"sk-***********"
```
)
Each code block should have a short text introduction before it

当用户为bootcamp仓库编写Milvus集成教程时，请阅读此文档。内容包括：

徽章格式（顶部的Colab + GitHub徽章）
文档结构：标题 -> 前置要求 -> 主要内容 -> 结论
依赖安装格式（包含Google Colab重启提示）
API密钥占位符约定（
```
"sk-***********"
```
）
每个代码块前应有简短的文字介绍

Milvus Code Style (

references/milvus-code-style.md

)

Milvus代码风格 (

references/milvus-code-style.md

)

Read this when the notebook involves pymilvus code. Key rules:

Always use
MilvusClient
API — never use the legacy ORM layer (

connections.connect()

Collection()

FieldSchema()

, etc.)

Always define schema explicitly (
```
create_schema
```
+
```
add_field
```
) — do not use the shortcut
```
create_collection(dimension=...)
```
without schema
Include
```
has_collection
```
check before creating collections

Add commented

consistency_level="Strong"

line in

create_collection()

No need to call
```
load_collection()
```
— collections auto-load on creation
First MilvusClient connection must include the blockquote explaining
```
uri
```
options (Milvus Lite / Docker / Zilliz Cloud)

当Notebook涉及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）

Important Notes

重要注意事项

Always edit the
.md
file, not the
```
.ipynb
```
directly. The
```
.md
```
is easier for AI to read and write.
Keep both files —
```
.md
```
for editing,
```
.ipynb
```
for running/sharing.
After editing
```
.md
```
, always re-run
```
uvx jupyter-switch example.md
```
to sync the
```
.ipynb
```
.

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

jupyter-notebook-writing

Original

Translation

Skill: Jupyter Notebook Writing

技能：Jupyter Notebook编写

When to Use

适用场景

Core Workflow: Markdown-First Editing

核心工作流：Markdown优先编辑

Format Convention

格式约定

Conversion Commands

转换命令

Markdown -> Jupyter Notebook

Markdown -> Jupyter Notebook

produces example.ipynb

生成 example.ipynb

Jupyter Notebook -> Markdown

Jupyter Notebook -> Markdown

produces example.md

生成 example.md

Step-by-Step

分步指南

Creating a New Notebook

创建新Notebook

Editing an Existing Notebook

编辑现有Notebook

Testing / Running

测试/运行

1. Resolve the Jupyter execution environment

1. 确定Jupyter执行环境

Discover conda/mamba environments

发现conda/mamba环境

Discover registered Jupyter kernels

发现已注册的Jupyter内核

Check system default Python

检查系统默认Python

Check for local virtual environment in the working directory

检查工作目录中的本地虚拟环境

Check if a uv-managed project (pyproject.toml + .venv)

检查是否为uv管理的项目（pyproject.toml + .venv）

Jupyter Notebook Execution

Jupyter Notebook Execution

2. Prepare the notebook for execution

2. 准备Notebook以执行

# pip install --upgrade langchain pymilvus

# pip install --upgrade langchain pymilvus

import os

import os

os.environ["OPENAI_API_KEY"] = "sk-***********"

os.environ["OPENAI_API_KEY"] = "sk-***********"

3. Convert and run

3. 转换并运行

Notebook Structure Template

Notebook结构模板

Title

标题

Prerequisites

前置要求

Setup

设置

Prepare Data

准备数据

data preparation code

数据准备代码

Create Collection & Insert Data

创建集合并插入数据

collection creation and data insertion

集合创建和数据插入代码

Query / Search

查询/搜索

search or query examples

查询或搜索示例代码

Cleanup

清理

Reference Documents

参考文档

Bootcamp Format (references/bootcamp-format.md)

Bootcamp格式 (references/bootcamp-format.md)

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

Bootcamp Format (
`references/bootcamp-format.md`
)

Bootcamp格式 (
`references/bootcamp-format.md`
)

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

Milvus代码风格 (
`references/milvus-code-style.md`
)