AI Skills
jupyter-notebook-writing

jupyter-notebook-writing

使用 Markdown 優先的工作流程搭配 jupyter-switch 進行格式轉換，撰寫 Milvus 應用層級的 Jupyter notebook 範例。

0星標
0分支
更新於 2026/7/22
獲取技能源代碼

相關技能

dogfood22萬frontend-testing15萬next-cache-components-optimizer14萬
SKILL.md
唯讀
名稱
jupyter-notebook-writing
描述

使用 Markdown 優先的工作流程搭配 jupyter-switch 進行格式轉換，撰寫 Milvus 應用層級的 Jupyter notebook 範例。

技能：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
# 產生 example.ipynb

# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# 產生 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. 轉換回來：uvx jupyter-switch example.md

測試/執行

1. 解析 Jupyter 執行環境

在執行任何 notebook 之前，必須先決定要使用哪個 Python 環境。系統預設的 jupyter execute 可能沒有安裝所需的套件。

步驟 A — 偵測可用的環境。

# 發現 conda/mamba 環境
conda env list 2>/dev/null || mamba env list 2>/dev/null

# 發現已註冊的 Jupyter kernel
jupyter kernelspec list 2>/dev/null

# 檢查系統預設 Python
which python3 2>/dev/null && python3 --version 2>/dev/null

# 檢查工作目錄中的本機虛擬環境
ls -d .venv/ venv/ 2>/dev/null

# 檢查是否為 uv 管理的專案（pyproject.toml + .venv）
test -f pyproject.toml && test -d .venv && echo "偵測到 uv/pip 專案虛擬環境"

步驟 B — 詢問使用者要使用哪個環境。 提供編號清單供選擇。包含所有偵測到的環境：

  1. 系統預設 — 直接執行 jupyter execute，不加 --kernel_name
  2. 每個偵測到的 conda/mamba 環境 — 顯示名稱和路徑
  3. 每個已註冊的 Jupyter kernel — 顯示 kernel 名稱
  4. 本機虛擬環境（如果在工作目錄中找到 .venv/ 或 venv/）— 該虛擬環境中的 Python
  5. 自訂 — 讓使用者輸入 Python 路徑或環境名稱

關於 uv 專案的注意事項： 如果工作目錄有 pyproject.toml + .venv/（uv 管理的專案），本機虛擬環境選項涵蓋此情況。如果 jupyter 是專案相依套件，使用者也可以直接執行 uv run jupyter execute example.ipynb。

範例提示：

請問您要使用哪個 Python 環境來執行這個 notebook？

1. 系統預設（直接執行 jupyter execute）
2. conda: myenv (/path/to/envs/myenv)
3. Jupyter kernel: some-kernel
4. 本機虛擬環境 (.venv/)
5. 自訂 — 輸入路徑或環境名稱

步驟 C — 套用所選的環境：

情境 動作
已是已註冊的 Jupyter kernel 使用 jupyter execute --kernel_name=<name>
Conda 環境尚未註冊為 kernel 先註冊：<env-python> -m ipykernel install --user --name <name> --display-name "<label>"，然後使用 --kernel_name=<name>
自訂 Python 路徑 同上 — 先註冊為 kernel，然後使用 --kernel_name
2. 準備 notebook 以供執行

在執行之前，將 .md 檔案中的「僅設定用」儲存格註解掉 — 這些儲存格是給初次使用者看的，但不應在自動化測試環境中執行。具體來說：

  • pip install 儲存格 — 相依套件應已安裝在所選的 Jupyter 環境中。如果缺少任何套件或需要升級，請在目標環境外部安裝（加上 --upgrade），而不是在 notebook 內部。
  • API 金鑰/憑證佔位符儲存格 — 例如 os.environ["OPENAI_API_KEY"] = "sk-***********"。改為在執行前於外部設定環境變數（在 shell 中 export，或在 jupyter execute 之前透過程式碼注入）。
  • 模擬/僅示範用儲存格 — 任何純粹為了說明而存在、在實際執行時會失敗或干擾的儲存格。

若要註解掉一個儲存格，將其內容包在區塊註解中，這樣儲存格仍會執行（產生空輸出）但不會做任何事：

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

這樣可以保持 notebook 結構完整（儲存格數量、順序），同時避免與外部 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 檔案中修正，如有需要可取消註解設定儲存格以進行除錯，然後重新轉換

Notebook 結構範本

典型的 Milvus 範例 notebook 遵循以下結構：

# 標題

簡短說明此 notebook 展示的內容。

## 先決條件

安裝相依套件：

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

## 設定

匯入與設定：

` ``python
from pymilvus import MilvusClient

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

## 準備資料

載入或產生範例資料：

` ``python
# 資料準備程式碼
` ``

## 建立集合並插入資料

` ``python
# 建立集合與插入資料
` ``

## 查詢/搜尋

` ``python
# 搜尋或查詢範例
` ``

## 清理

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

參考文件

此技能包含 references/ 下的兩份參考文件。當任務涉及相關主題時，請閱讀它們。

參考文件 何時閱讀 檔案
Bootcamp 格式 撰寫 Milvus 整合教學（徽章、文件結構、章節格式、範例佈局） references/bootcamp-format.md
Milvus 程式碼風格 撰寫 pymilvus 程式碼（集合建立、MilvusClient 連線參數、schema 模式、最佳實踐） references/milvus-code-style.md

Bootcamp 格式（references/bootcamp-format.md）

當使用者正在為 bootcamp 儲存庫撰寫 Milvus 整合教學時，請閱讀此文件。內容涵蓋：

  • 徽章格式（頂端的 Colab + GitHub 徽章）
  • 文件結構：標題 -> 先決條件 -> 主要內容 -> 結論
  • 相依套件安裝格式，附帶 Google Colab 重新啟動注意事項
  • API 金鑰佔位符慣例（"sk-***********"）
  • 每個程式碼區塊前應有一段簡短的文字介紹

Milvus 程式碼風格（references/milvus-code-style.md）

當 notebook 涉及 pymilvus 程式碼時，請閱讀此文件。主要規則：

  • 一律使用 MilvusClient API — 絕不使用舊版的 ORM 層（connections.connect()、Collection()、FieldSchema() 等）
  • 一律明確定義 schema（create_schema + add_field）— 不要使用不帶 schema 的捷徑 create_collection(dimension=...)
  • 在建立集合前加入 has_collection 檢查
  • 在 create_collection() 中加入註解掉的 consistency_level="Strong" 行
  • 不需要呼叫 load_collection() — 集合在建立時會自動載入
  • 首次 MilvusClient 連線必須包含說明 uri 選項（Milvus Lite / Docker / Zilliz Cloud）的引用區塊

重要注意事項

  • 一律編輯 .md 檔案，而不是直接編輯 .ipynb。AI 更容易讀寫 .md。
  • 保留兩個檔案 — .md 用於編輯，.ipynb 用於執行/分享。
  • 編輯 .md 後，務必重新執行 uvx jupyter-switch example.md 以同步 .ipynb。