Jupyter AI 入门实战指南
# Jupyter AI 入门指南：实用教程
多年来我一直在使用 Jupyter notebook，但真正让我碰壁的是需要编写复杂的数据清洗脚本时——我意识到自己一周内重复写了五次相同的正则表达式模式。就在那时，我决定尝试 Jupyter AI，这个扩展能将代码生成和聊天功能直接集成到你的 notebook 环境中。以下是我经过一周密集测试后的心得，包括那些出问题的地方以及我是如何修复的。
## 环境搭建：你真正需要什么
首先，让我们把基础工作做好。你需要 JupyterLab 3.5+（我用的是 3.6.1）和 Python 3.8+。安装过程很简单，但有个关键点：你需要在开始前决定好 AI 提供商。
**第一步：安装 Jupyter AI**
```bash
pip install jupyter-ai
```
这会安装核心包。但你还需要一个模型提供商。我测试了两种：
- **OpenAI**（需要 API 密钥，支持 GPT-4 和 GPT-3.5）
- **Hugging Face**（免费，但速度较慢）
**第二步：配置提供商**
对于 OpenAI：
```bash
export OPENAI_API_KEY="你的密钥"
```
对于 Hugging Face（免费选项）：
```bash
pip install jupyter-ai-huggingface
export HUGGINGFACEHUB_API_TOKEN="你的令牌"
```
**警告：** 我花了 30 分钟调试 API 调用失败的问题——结果发现是环境变量名拼写错误。请仔细检查 `HUGGINGFACEHUB_API_TOKEN`（注意其中的 'HUB'）。
## 界面操作：在哪里找到魔法功能
重启 JupyterLab 后，你会看到左侧边栏新增了一个 AI 图标（看起来像闪光点）。点击它，就会弹出一个聊天面板。但首先让我困惑的是：**你不能直接开始聊天**。你需要先选择一个模型。
在聊天面板中：
1. 点击齿轮图标（设置）
2. 从下拉菜单中选择提供商（例如，GPT-4 选择 `openai-chat`）
3. 设置模型（复杂任务我用 `gpt-4`，快速任务用 `gpt-3.5-turbo`）
**专业提示：** 如果预算有限，可以使用 Hugging Face 的免费模型 `microsoft/DialoGPT-medium`，但响应时间预计在 5-10 秒。
## 我的第一个真实测试：自动化数据清洗脚本
我有一份包含 5 万行客户数据的混乱 CSV 文件。以下是我在聊天面板中输入的内容：
```
编写一个 Python 函数，用于清洗包含 'email'、'phone'、'age' 列的 DataFrame。
删除 email 缺失的行，将电话号码格式化为 (XXX) XXX-XXXX，
并将 age 转换为整数。
```
Jupyter AI 在大约 3 秒内生成了这段代码：
```python
def clean_customer_data(df):
# 删除 email 缺失的行
df = df.dropna(subset=['email'])
# 格式化电话号码
import re
def format_phone(phone):
digits = re.sub(r'\D', '', str(phone))
if len(digits) == 10:
return f"({digits[:3]}) {digits[3:6]}-{digits[6:]}"
return phone
df['phone'] = df['phone'].apply(format_phone)
# 将 age 转换为整数
df['age'] = pd.to_numeric(df['age'], errors='coerce').astype('Int64')
return df
```
**让我印象深刻的地方：** 它使用了带 `errors='coerce'` 参数的 `pd.to_numeric`——这正是我会写的写法。它还使用了 `Int64`（可空整数类型），能优雅地处理 NaN 值。
**出问题的地方：** 电话号码格式化没有处理国家代码（+1）。当我要求修复这个问题时，它生成了一个 20 行的正则表达式解决方案，过于复杂。最后我自己写了个更简单的版本。
## 真正的威力：%%ai 魔法命令
聊天功能不错，但 Jupyter AI 的真正亮点在于魔法命令。你可以在单元格中使用 `%%ai` 来内联生成代码。
**示例：生成可视化脚本**
在新单元格中，输入：
```python
%%ai openai-chat
编写 matplotlib 代码，创建名为 df 的 DataFrame 中 'sales' 对 'profit' 的散点图。
使用颜色表示 'region' 列。
```
AI 直接在单元格中生成代码：
```python
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
for region in df['region'].unique():
subset = df[df['region'] == region]
plt.scatter(subset['sales'], subset['profit'], label=region, alpha=0.6)
plt.xlabel('Sales')
plt.ylabel('Profit')
plt.title('Sales vs Profit by Region')
plt.legend()
plt.show()
```
**关键提示：** `%%ai` 命令会替换整个单元格内容。如果已有代码，它会被覆盖。我就这样丢失了一个 50 行的函数。**运行 %%ai 之前，务必先复制单元格内容。**
## 我发现的问题
经过一周的重度使用，以下是我遇到的困扰：
1. **上下文窗口太小** - AI 不会记住 5 分钟前讨论的内容。每次查询我都得重新解释 DataFrame 结构。
2. **没有代码执行反馈** - AI 不会运行你的代码来检查是否有效。有一次它生成的函数引用了我实际 DataFrame 中不存在的列。
3. **Hugging Face 模型速度慢** - 免费模型每次响应需要 10-15 秒。OpenAI 的 GPT-4 几乎是即时的。
4. **安全问题** - 使用 `%%ai` 时，整个单元格内容（包括任何敏感数据）都会被发送到 AI 提供商。我不小心把包含客户邮箱的 DataFrame 发送到了 OpenAI 的服务器。
## 实际可行的工作流程
经过反复试验，以下是我推荐的工作流程：
1. **使用 %%ai 进行代码生成，而非聊天** - 聊天面板还行，但魔法命令更快、更专注。
2. **始终指定模型** - 不要依赖默认设置。复杂任务使用 `%%ai openai-chat -m gpt-4`。
3. **在单独单元格中测试生成的代码** - 永远不要盲目信任 AI 输出。将生成的代码复制到新单元格，并用小样本数据测试。
4. **使用 `/fix` 命令** - 如果生成的代码有错误，输入 `/fix` 后跟错误信息。它在调试方面出奇地好用。
5. **将上下文限制在 2-3 条消息内** - 3 次交流后，AI 开始出现幻觉。我发现长时间对话后，它会建议不存在的 pandas 函数。
## 真实案例：构建 ETL 管道
让我为你演示一个完整示例。我需要为日志文件构建一个 ETL 管道。
**第一步：加载数据**
```python
%%ai openai-chat
编写 pandas 代码，读取名为 'logs/' 目录中的所有 CSV 文件，
将它们合并为一个 DataFrame，并添加包含文件名的 'source_file' 列。
```
**第二步：清洗数据**
```python
%%ai openai-chat
对于包含 'timestamp'、'level'、'message'、'user_id' 列的 DataFrame：
- 将 'timestamp' 解析为日期时间格式
- 过滤掉 'level' 为 'DEBUG' 的行
- 删除重复的 'message' 条目
```
**第三步：生成摘要**
```python
%%ai openai-chat
编写一个函数，接收包含 'level' 和 'message' 列的 DataFrame，
并返回一个字典，包含各日志级别的计数和最常见的 10 条消息。
```
每一步都生成了可用的代码，我随后手动进行了整合。AI 帮我节省了大约 2 小时编写样板代码的时间。
## 结论：你应该使用它吗？
Jupyter AI 非常适合：
- 生成样板代码（数据加载、基础清洗）
- 编写 matplotlib/seaborn 可视化
- 解释复杂的 pandas 操作
它在以下方面表现不佳：
- 领域特定逻辑（例如，金融计算）
- 需要记忆过去上下文的多步骤工作流
- 与数据库或 API 交互的代码
**我最大的建议：** 将其作为起点，而非最终方案。我现在把生成的代码当作初稿——它帮我省去了打字工作，但在生产数据上运行之前，我总会进行审查和测试。
## 你的下一步
不要只是阅读这篇文章——现在就试试。打开一个 Jupyter notebook，安装 `jupyter-ai`，然后运行这个确切的命令：
```python
%%ai openai-chat
生成 10 行模拟客户数据的随机行，包含以下列：
'customer_id'、'name'、'email'、'signup_date'、'plan_type'
```
然后运行生成的代码，看看是否有效。你会立刻理解它的强大之处和局限性。当它不可避免地产生错误时（一定会），使用 `/fix` 进行调试。这才是真正学习的开始。