Jupyter AI 入门指南：实用教程

多年来我一直在使用 Jupyter notebook，但真正让我碰壁的是需要编写复杂的数据清洗脚本时——我意识到自己一周内重复写了五次相同的正则表达式模式。就在那时，我决定尝试 Jupyter AI，这个扩展能将代码生成和聊天功能直接集成到你的 notebook 环境中。以下是我经过一周密集测试后的心得，包括那些出问题的地方以及我是如何修复的。

环境搭建：你真正需要什么

首先，让我们把基础工作做好。你需要 JupyterLab 3.5+（我用的是 3.6.1）和 Python 3.8+。安装过程很简单，但有个关键点：你需要在开始前决定好 AI 提供商。

第一步：安装 Jupyter AI

pip install jupyter-ai

这会安装核心包。但你还需要一个模型提供商。我测试了两种：

OpenAI（需要 API 密钥，支持 GPT-4 和 GPT-3.5）
Hugging Face（免费，但速度较慢）

第二步：配置提供商

对于 OpenAI：

export OPENAI_API_KEY="你的密钥"

对于 Hugging Face（免费选项）：

pip install jupyter-ai-huggingface
export HUGGINGFACEHUB_API_TOKEN="你的令牌"

警告： 我花了 30 分钟调试 API 调用失败的问题——结果发现是环境变量名拼写错误。请仔细检查 HUGGINGFACEHUB_API_TOKEN（注意其中的 'HUB'）。

界面操作：在哪里找到魔法功能

重启 JupyterLab 后，你会看到左侧边栏新增了一个 AI 图标（看起来像闪光点）。点击它，就会弹出一个聊天面板。但首先让我困惑的是：你不能直接开始聊天。你需要先选择一个模型。

在聊天面板中：

点击齿轮图标（设置）
从下拉菜单中选择提供商（例如，GPT-4 选择 openai-chat）
设置模型（复杂任务我用 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 秒内生成了这段代码：

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 来内联生成代码。

示例：生成可视化脚本

在新单元格中，输入：

%%ai openai-chat
编写 matplotlib 代码，创建名为 df 的 DataFrame 中 'sales' 对 'profit' 的散点图。
使用颜色表示 'region' 列。

AI 直接在单元格中生成代码：

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 之前，务必先复制单元格内容。

我发现的问题

经过一周的重度使用，以下是我遇到的困扰：

上下文窗口太小 - AI 不会记住 5 分钟前讨论的内容。每次查询我都得重新解释 DataFrame 结构。
没有代码执行反馈 - AI 不会运行你的代码来检查是否有效。有一次它生成的函数引用了我实际 DataFrame 中不存在的列。
Hugging Face 模型速度慢 - 免费模型每次响应需要 10-15 秒。OpenAI 的 GPT-4 几乎是即时的。
安全问题 - 使用 %%ai 时，整个单元格内容（包括任何敏感数据）都会被发送到 AI 提供商。我不小心把包含客户邮箱的 DataFrame 发送到了 OpenAI 的服务器。

实际可行的工作流程

经过反复试验，以下是我推荐的工作流程：

使用 %%ai 进行代码生成，而非聊天 - 聊天面板还行，但魔法命令更快、更专注。
始终指定模型 - 不要依赖默认设置。复杂任务使用 %%ai openai-chat -m gpt-4。
在单独单元格中测试生成的代码 - 永远不要盲目信任 AI 输出。将生成的代码复制到新单元格，并用小样本数据测试。
使用 /fix 命令 - 如果生成的代码有错误，输入 /fix 后跟错误信息。它在调试方面出奇地好用。
将上下文限制在 2-3 条消息内 - 3 次交流后，AI 开始出现幻觉。我发现长时间对话后，它会建议不存在的 pandas 函数。

真实案例：构建 ETL 管道

让我为你演示一个完整示例。我需要为日志文件构建一个 ETL 管道。

第一步：加载数据

%%ai openai-chat
编写 pandas 代码，读取名为 'logs/' 目录中的所有 CSV 文件，
将它们合并为一个 DataFrame，并添加包含文件名的 'source_file' 列。

第二步：清洗数据

%%ai openai-chat
对于包含 'timestamp'、'level'、'message'、'user_id' 列的 DataFrame：
- 将 'timestamp' 解析为日期时间格式
- 过滤掉 'level' 为 'DEBUG' 的行
- 删除重复的 'message' 条目

第三步：生成摘要

%%ai openai-chat
编写一个函数，接收包含 'level' 和 'message' 列的 DataFrame，
并返回一个字典，包含各日志级别的计数和最常见的 10 条消息。

每一步都生成了可用的代码，我随后手动进行了整合。AI 帮我节省了大约 2 小时编写样板代码的时间。

结论：你应该使用它吗？

Jupyter AI 非常适合：

生成样板代码（数据加载、基础清洗）
编写 matplotlib/seaborn 可视化
解释复杂的 pandas 操作

它在以下方面表现不佳：

领域特定逻辑（例如，金融计算）
需要记忆过去上下文的多步骤工作流
与数据库或 API 交互的代码

我最大的建议： 将其作为起点，而非最终方案。我现在把生成的代码当作初稿——它帮我省去了打字工作，但在生产数据上运行之前，我总会进行审查和测试。

你的下一步

不要只是阅读这篇文章——现在就试试。打开一个 Jupyter notebook，安装 jupyter-ai，然后运行这个确切的命令：

%%ai openai-chat
生成 10 行模拟客户数据的随机行，包含以下列：
'customer_id'、'name'、'email'、'signup_date'、'plan_type'

然后运行生成的代码，看看是否有效。你会立刻理解它的强大之处和局限性。当它不可避免地产生错误时（一定会），使用 /fix 进行调试。这才是真正学习的开始。

Jupyter AI 入门实战指南