Jupyter Notebook集成生成式AI：从API调用到数据分析实战

你的日常工作里是不是也有这样的场景分析一个数据集时明明知道该用什么算法却要反复查文档确认参数写一段重复性代码时思路很清楚可就是不想手敲处理一个报错时搜索引擎翻了好几页答案还是对不上当前版本。如果给 Jupyter Notebook 配上生成式 AI这些场景会被彻底改变。Notebook 本身就是交互式编程的绝佳载体而生成式 AI 擅长代码生成、文本解释、问答和总结。把两者结合就等于在编辑器里塞进一个随时可用的编程助手。这篇文章不会只停留在概念层面。我会从环境配置开始带你一步步在你的 Jupyter Notebook 里集成生成式 AI同时给出一套完整可复制的实战代码覆盖文本生成、代码解释、数据分析辅助等高频场景。无论你是刚刚接触 Notebook 的新手还是想提升开发效率的进阶用户都可以在这篇文章里找到可以直接落地的方案。1. Jupyter Notebook 与生成式 AI 的核心概念1.1 Jupyter Notebook 到底是什么Jupyter Notebook 是一个基于 Web 的交互式开发环境核心单元是“单元格”。单元格可以单独执行 Python 代码、查看输出结果、甚至插入 Markdown 说明文档。这种“代码 文字 图形输出”混排的形式让它成为数据分析、机器学习、教学演示中最常用的工具之一。和传统 IDE 相比Notebook 最大的特点是“分块执行”。你可以只运行一个单元格观察结果再继续写下一块代码。这种模式非常适合探索性分析也因为“一次写一点、马上看结果”的即时反馈让它在编程入门场景中广受欢迎。不过我经常看到两个容易混淆的概念Jupyter Notebook 和 JupyterLab。简单来说Notebook 是经典界面结构简单JupyterLab 是后续推出的下一代界面支持多标签页、拖拽布局、终端集成更像一个“Web 版 IDE”。两者底层内核一致本文的代码在这两个环境中都可以运行。1.2 生成式 AI 如何融入 Notebook生成式 AI指的是能够根据输入文本自动生成新内容的人工智能模型。这里的“新内容”可以是文字、代码、摘要也可以是结构化数据。开发者日常接触最多的是大语言模型类的 AI 服务它们通过 API 对外提供能力。把生成式 AI 集成到 Jupyter Notebook 后典型的使用方式包括在单元格中直接调用 AI 的 API用 Python 代码把文本或代码片段发送给模型再把结果展示在 Notebook 中。用 AI 解释当前单元格的代码逻辑辅助阅读别人写的脚本。让 AI 对 DataFrame 的统计结果进行自然语言解读把“数字”变成“洞察”。编写小工具函数把重复性的提示词封装起来形成自己的“代码助手工具箱”。换句话说生成式 AI 并不会取代你写代码它更像是搭档你负责拆解问题、判断结果、设计结构AI 负责快速产出初稿、解释逻辑和提供备选方案。1.3 为什么程序员需要这套组合传统 IDE 中已经有不少 AI 编程插件但 Jupyter Notebook 的场景更偏数据分析、算法验证和教学。插件类工具在文本编辑器里很好用对于需要逐块执行的 Notebook 单元格往往支持不完整。一个很典型的例子你在 Notebook 中加载了一份销售数据通过 groupby 得到了各区域的汇总结果。这时候你想知道“这个结果说明了什么”传统流程是复制数字、打开聊天窗口、粘贴提问再把回答贴回来。集成生成式 AI 后只需要一个函数调用模型就会基于上下文直接给出解读。这种“分析闭环”才是 Notebook 集成 AI 的最大价值数据探索、结果解读、代码生成都发生在同一个环境里思维链路不会被频繁打断。2. 环境准备与版本说明2.1 确定你的基础环境在开始集成之前先确认本机的 Python 环境。本文示例使用 Python 3.9 及以上版本这是绝大多数生成式 AI SDK 的推荐配置。具体小版本可以根据你的项目实际情况调整教程的核心是配置思路。如果你还没有安装 Python建议直接安装 Anaconda。Anaconda 自带 Python、conda 包管理器和 Jupyter Notebook省去很多单独配置的麻烦。Windows、macOS、Linux 下安装步骤都比较简单这里不再展开。安装完成后打开终端或命令提示符输入以下命令确认版本python --version pip --version如果两条命令都能正常输出版本号说明 Python 环境已经就绪。2.2 安装 Jupyter Notebook如果你是通过 Anaconda 安装的 PythonJupyter Notebook 通常已经包含在内。可以用下面的命令验证jupyter --version如果提示找不到命令单独安装也很简单pip install jupyter安装完成后在终端启动jupyter notebook启动成功后终端会输出一段访问地址默认是http://localhost:8888浏览器会自动打开 Notebook 的首页。如果你在服务器或远程主机上运行则需要通过端口转发或配置远程访问的方式连接这不在本文范围内。如果启动后浏览器打开是空白页优先检查是否使用了代理类工具或者尝试更换默认浏览器。这是 Notebook 使用过程中非常常见的问题后面会在常见问题部分专门说明。2.3 安装生成式 AI 相关依赖接下来安装与生成式 AI 交互所需的 Python 包。最基础的是openai和requests。此外为了展示数据分析场景会用到pandas。一次性安装这三个包pip install openai pandas requests安装完成后可以先验证导入是否正常import openai import pandas as pd print(openai version:, openai.__version__) print(pandas version:, pd.__version__)如果你看到版本号正常输出说明依赖环境已经准备好。需要说明的是不同版本的 openai SDK 在调用方式上略有差异。下面代码示例基于 openai 1.x 版本如果你的版本是 0.xAPI 的调用写法会不一样建议先升级到 1.xpip install --upgrade openai2.4 工具选型Notebook 还是 JupyterLab在开始前想清楚用哪个界面。如果只是普通的数据分析和 AI 调用经典 Jupyter Notebook 完全够用如果你经常需要同时打开多个 Notebook、查看终端输出、对比文档JupyterLab 的体验会更好。两者共用同一套 Python 内核和已安装的包本文代码没有任何区别。选择你顺手的环境即可。在 JupyterLab 中新建 Notebook 的方法启动jupyter lab点击左侧文件栏的号选择 Python 3 内核即可。3. 核心思路Notebook 里的 AI 调用模型3.1 从一次最简单的 AI 调用开始在 Notebook 单元格里写 AI 调用代码和写普通 Python 没有本质区别。核心逻辑只有三步读取 API 密钥构造请求参数调用模型。先来看一个最小示例。# 文件路径notebooks/01-first-call.ipynb import os from openai import OpenAI # 从环境变量读取 API 密钥避免硬编码在代码中 client OpenAI( api_keyos.environ.get(OPENAI_API_KEY), ) response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个乐于助人的编程助手。}, {role: user, content: 请用一句话解释什么是 Python 装饰器。}, ], temperature0.7, ) print(response.choices[0].message.content)这段代码做了几件事通过os.environ.get读取环境变量避免把密钥直接写在代码里。创建 OpenAI 客户端对象。调用chat.completions.create发送对话请求。打印模型返回的文本内容。如果你没有 OpenAI 账号或无法直接访问官方 API不要着急。国内外有很多兼容 OpenAI 协议的服务商或者你可以使用本地部署的模型服务。这些服务的接口结构高度兼容只需要修改base_url和api_key两个参数即可示例代码如下client OpenAI( api_keyyour-service-key, base_urlhttps://your-api-endpoint/v1, )这里要特别说明不要编造或轻信未经验证的 API 地址。请根据你实际使用的服务提供方文档来填写base_url。3.2 理解 messages 和参数OpenAI 兼容接口的请求体内messages是最核心的部分。它是一个列表每一项包含role和content两个字段。system系统消息用来设定 AI 的角色和行为。user用户消息即你向 AI 提出的问题。assistant助手消息通常用于多轮对话中传递历史回复。temperature控制输出的随机性取值范围一般是 0 到 2。数值越低输出越确定数值越高越有创造性。在写代码场景中建议设置为 0.2 左右可以减少“自由发挥”带来的语法错误。在实际项目中不要每次都把密钥写在代码里。更推荐的做法是使用.env文件管理敏感信息配合python-dotenv加载环境变量。pip install python-dotenv然后在项目根目录创建.env文件OPENAI_API_KEY你的实际密钥在 Notebook 中加载环境变量from dotenv import load_dotenv import os # 加载项目根目录的 .env 文件 load_dotenv() api_key os.getenv(OPENAI_API_KEY) print(密钥已加载长度, len(api_key) if api_key else 0)这样做的优势是即使 Notebook 文件被分享出去也不会泄露密钥。.env文件应该加入.gitignore避免提交到代码仓库。3.3 构造自己的“AI 函数”直接调用 API 的代码可以跑通但不适合每天使用。更好的方式是把调用封装成通用函数然后在 Notebook 中反复调用。# 文件路径notebooks/02-ai-helper.ipynb from openai import OpenAI client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) def ask_ai(prompt: str, system: str 你是一个专业的编程助手。, temperature: float 0.3) - str: 向大模型发送一次简单请求返回文本结果。 :param prompt: 用户输入 :param system: 系统提示词 :param temperature: 随机性参数 :return: 模型回复文本 response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messages[ {role: system, content: system}, {role: user, content: prompt}, ], temperaturetemperature, ) return response.choices[0].message.content封装之后使用时会非常方便result ask_ai(用 Python 写一个快速排序并加上中文注释。) print(result)4. 完整实战构建一个数据分析 AI 助手上面已经掌握了 AI 调用的基础。这一节我们把它应用到真实场景用 Jupyter Notebook 读取一份销售数据做基础分析再让 AI 解读统计结果。完整流程分四步走。为了让示例可以一键复现我们先用代码生成一份模拟数据。4.1 准备示例数据# 文件路径notebooks/03-data-ai-assistant.ipynb import pandas as pd import numpy as np # 设置随机种子保证每次运行结果一致 np.random.seed(42) # 模拟 500 条订单记录 data { 订单编号: [fORD-{i:05d} for i in range(1, 501)], 地区: np.random.choice([华东, 华北, 华南, 西南], size500, p[0.35, 0.25, 0.25, 0.15]), 品类: np.random.choice([手机, 电脑, 家电, 服饰], size500, p[0.3, 0.3, 0.2, 0.2]), 销售额: np.random.uniform(50, 5000, size500).round(2), 订单日期: pd.date_range(start2024-01-01, periods500, freqD).strftime(%Y-%m-%d), } df pd.DataFrame(data) print(数据集大小, df.shape) df.head()这段代码生成一个包含 500 条模拟订单的 DataFrame包含订单编号、地区、品类、销售额和订单日期四个字段。接下来做一些基础聚合分析。4.2 数据聚合与统计我们关心两个问题不同地区的销售额表现如何不同品类的平均单价是多少。# 各地区销售额汇总 region_summary df.groupby(地区)[销售额].sum().reset_index() region_summary.columns [地区, 总销售额] region_summary[总销售额] region_summary[总销售额].round(2) print(各地区销售额汇总) region_summary# 各品类平均销售额 category_summary df.groupby(品类)[销售额].mean().reset_index() category_summary.columns [品类, 平均销售额] category_summary[平均销售额] category_summary[平均销售额].round(2) print(各品类平均销售额) category_summary运行之后你会得到两个统计表格。在传统流程中你需要自己“看”这些数字得出业务结论。现在让 AI 来做这件事。4.3 让 AI 解读统计结果把统计结果转成字符串拼进提示词调用前面封装的ask_ai函数。# 将统计结果格式化为文本 region_text region_summary.to_string(indexFalse) category_text category_summary.to_string(indexFalse) prompt f 我有一份电商销售数据请帮我分析以下统计结果。 各地区总销售额 {region_text} 各品类平均销售额 {category_text} 请从业务视角指出三个值得关注的发现并给出简单的建议。要求回答简洁每点不超过 50 字。 analysis_result ask_ai(prompt, system你是一名资深数据分析师。, temperature0.3) print(analysis_result)这里的关键点在于把 DataFrame 转成to_string()让模型能拿到可读的纯文本数据。不要把整个 DataFrame 直接塞进提示词那样不仅浪费 token还可能因为内容过长导致请求失败。运行后你会看到模型对数据的结构化解读。这是一个非常完整的“AI 分析助手”工作流。你可以把这段代码保存为一个函数以后只要传入 DataFrame 和统计口径就能自动生成分析摘要。4.4 生成图表并让 AI 解释数据分析场景中图表不可或缺。我们用 matplotlib 画一张各地区销售额柱状图然后让 AI 为图表生成一句“图表标题”或“图表解读”直接用在报告里。import matplotlib.pyplot as plt # 设置中文字体避免图表中文乱码具体字体名根据操作系统调整 plt.rcParams[font.sans-serif] [SimHei] plt.rcParams[axes.unicode_minus] False # 绘制柱状图 plt.figure(figsize(8, 5)) plt.bar(region_summary[地区], region_summary[总销售额], color#4C72B0) plt.title(各地区总销售额对比) plt.xlabel(地区) plt.ylabel(总销售额) plt.tight_layout() plt.show()图表生成后你还需要一段文字描述。让 AI 来完成chart_prompt f 这是一张地区销售额柱状图数据如下 {region_text} 请用 2-3 句话描述图表的核心信息适合直接放在数据分析报告中。 chart_description ask_ai(chart_prompt, system你是一名数据可视化专家。, temperature0.3) print(chart_description)到这里你已经拥有了一个“数据分析 自动解读”的完整 Notebook 工作流。生成式 AI 在这个流程中承担的是“解读员”和“总结者”的角色而 Notbook 则提供了数据操作与交互的载体。两者结合后分析报告的产出效率提升非常明显。5. 进阶玩法AI 代码解释器与魔术命令5.1 单元格代码解释器在 Jupyter Notebook 中你经常会打开别人写的 Notebook 或者官方文档的示例代码有些代码逻辑比较复杂逐行阅读很费时间。可以利用 Notebook 提供的%%capture魔术命令和 AI 结合做一个单元格级的“代码解释器”。思路是先获取当前单元格的源代码再让 AI 解释。不过更轻量的方式是直接选中代码粘贴给 AI一步到位。这里给出一个可以直接复用的函数# 文件路径notebooks/04-code-explainer.ipynb def explain_code(code_snippet: str) - str: prompt f 请解释下面的 Python 代码要求 1. 说明这段代码的用途。 2. 逐行解释关键逻辑。 3. 指出可能存在的坑。 代码 python {code_snippet} return ask_ai(prompt, system你是一名耐心的 Python 技术导师。, temperature0.2)在单元格中测试sample_code def calculate_ma(series, window5): return series.rolling(windowwindow).mean() print(explain_code(sample_code))如果经常需要解释单元格还可以借助 IPython 的get_ipython().history_manager获取最近执行过的代码但这不是必须的手动粘贴也完全够用。5.2 用 AI 生成 SQL 或正则表达式数据分析师经常会写 SQL 从数据库中取数。在 Notebook 中我们可以通过 AI 快速把自然语言转换成 SQL。def nl_to_sql(natural_language: str, table_name: str, fields: list) - str: prompt f 请把下面的自然语言需求转换成 SQL 查询语句。 表名{table_name} 字段{, .join(fields)} 需求 {natural_language} 只需要输出 SQL 语句不需要解释。 return ask_ai(prompt, system你是一名精通 SQL 的数据库工程师。, temperature0.1)调用示例sql nl_to_sql( 查询最近 7 天每天的总销售额按日期升序排列, table_nameorders, fields[order_date, sales_amount] ) print(sql)这种“自然语言转 SQL”的能力在生产中非常实用。不过要注意AI 生成的 SQL 必须经过人工确认和 explain 验证后再执行绝对不能无条件信任模型输出。5.3 多轮对话让 AI 记住上下文前面的示例都是单轮问答模型不记得之前聊过什么。如果要做稍微复杂的任务比如“先帮我写好代码再解释每一行”就需要多轮对话。# 多轮对话示例 messages [ {role: system, content: 你是一名 Python 开发专家。}, {role: user, content: 写一个函数输入是列表输出去重后的新列表。}, ] # 第一轮回复 response1 client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messagesmessages, temperature0.3, ) assistant_reply response1.choices[0].message.content print(第一轮回复\n, assistant_reply) # 把助手回复加入消息列表 messages.append({role: assistant, content: assistant_reply}) messages.append({role: user, content: 请给这个函数加上类型注解和文档字符串。}) # 第二轮回复 response2 client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messagesmessages, temperature0.3, ) print(第二轮回复\n, response2.choices[0].message.content)多轮对话的关键是维护messages列表每一轮回复后把 AI 的回答追加到列表中再追加用户的新问题。这样模型才能“记得”之前的对话内容。在长对话中消息列表会越来越长最终超过模型的 token 上限。实际使用时应该定期清理历史消息只保留最近几轮或者对历史消息做摘要压缩。6. 常见问题与排查思路6.1 认证错误或密钥无效提示信息AuthenticationError或Invalid API key provided。常见原因API 密钥填写错误、环境变量没有正确加载、密钥已经过期或额度耗尽。排查步骤检查.env文件中的密钥是否完整没有多余空格。确认已经执行了load_dotenv()。在单元格中打印os.getenv(OPENAI_API_KEY)的长度确认是否正常读取。检查服务商控制台确认密钥状态是否有效。6.2 网络连接超时或连接错误提示信息APIConnectionError或timed out。常见原因本机网络无法访问目标 API、使用了代理工具导致连接中断、防火墙拦截。排查步骤先用 curl 或浏览器访问 API 服务健康检查地址确认网络通不通。检查是否设置了HTTPS_PROXY或HTTP_PROXY环境变量如果不需要代理把它清空。在OpenAI客户端中配置更长的超时时间client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), timeout30.0, )6.3 Notebook 打开后空白页面提示信息浏览器访问http://localhost:8888时页面空白控制台可能有报错。常见原因浏览器插件冲突、使用了代理工具、Notebook 版本与浏览器兼容性问题。排查步骤换一个浏览器试试推荐 Chrome 或 Edge 的无痕模式。关闭代理类工具后刷新页面。在终端重启 Jupyter Notebook并加上--no-browser参数避免自动打开浏览器jupyter notebook --no-browser查看终端日志确认内核是否正常启动。6.4 返回值截断或不完整表现AI 回复的内容到一半突然结束。常见原因max_tokens设置过小、模型输出超过了限制。解决方式response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messagesmessages, max_tokens2000, # 根据实际需要调整 )如果输出仍然截断说明单次请求的 token 上限不够可以考虑让 AI 分段回答把长内容拆成多个部分分别生成。6.5 DataFrame 转换后中文乱码现象打印to_string()时中文正常但绘图时中文变成方框。原因matplotlib 默认字体不支持中文。解决方式import matplotlib.pyplot as plt plt.rcParams[font.sans-serif] [SimHei, Microsoft YaHei, Arial Unicode MS] plt.rcParams[axes.unicode_minus] False不同操作系统的中文字体名不同如果你用的是 macOS可以尝试Arial Unicode MS或PingFang SCLinux 服务器则要安装中文字体包。7. 最佳实践与工程建议7.1 密钥与安全边界在整个集成过程中API 密钥是最敏感的信息。务必做到以下几点密钥只存放在.env文件或环境变量中不要硬编码在 Notebook 中。.env文件加入.gitignore不要提交到 Git 仓库。分享 Notebook 前用jupyter nbconvert --clear-output清空输出缓存再次检查是否残留密钥。如果怀疑密钥泄露立即到服务商控制台重置。7.2 提示词设计规范同一个 AI 模型提示词写得好不好输出质量差别很大。以下几点我在实际项目中验证过效果明显给模型明确角色比如“你是一名资深数据分析师”。描述背景信息模型对业务场景理解越清楚输出越贴合需求。限定输出格式比如“用 3 点说明每点不超过 30 字”。重要输出要求“只需要输出 SQL 语句”或“不要解释”减少无效内容。7.3 成本控制与调用频率生成式 AI API 是按 token 计费的。在开发调试阶段建议使用价格较低的小模型在关键业务场景再使用更强的大模型。可以设置模型名称作为环境变量这样切换模型时不需要改代码OPENAI_MODELgpt-4o-mini在 Notebook 中读取import os MODEL_NAME os.getenv(OPENAI_MODEL, gpt-4o-mini)7.4 缓存 AI 结果数据分析中经常会对同一份数据反复提问。为了避免每次都调用 API可以在 Notebook 中加入简单的缓存逻辑把提示词哈希后作为 key把结果保存到本地 JSON 文件。import hashlib import json import os CACHE_FILE ai_cache.json def get_cache(prompt: str): key hashlib.md5(prompt.encode(utf-8)).hexdigest() if os.path.exists(CACHE_FILE): with open(CACHE_FILE, r, encodingutf-8) as f: cache json.load(f) if key in cache: return cache[key] return None def set_cache(prompt: str, result: str): key hashlib.md5(prompt.encode(utf-8)).hexdigest() cache {} if os.path.exists(CACHE_FILE): with open(CACHE_FILE, r, encodingutf-8) as f: cache json.load(f) cache[key] result with open(CACHE_FILE, w, encodingutf-8) as f: json.dump(cache, f, ensure_asciiFalse, indent2)在调用 AI 前先查缓存命中则直接返回未命中才调用 API。7.5 生产环境注意事项如果你打算把这个集成从本地 Notebook 迁移到生产环境有几个额外问题需要提前考虑服务地址生产环境的 API 地址和本地可能不同使用环境变量区分环境。错误重试生产环境需要增加重试机制捕捉网络抖动。内容安全AI 生成的 SQL、代码必须在沙箱或测试库中验证后才能执行。日志追踪记录每次请求的 prompt 摘要和返回状态方便排查问题。8. 总结与下一步到这里你已经完成了一条完整的“Jupyter Notebook 生成式 AI”学习路径从环境配置、基础 API 调用到数据分析实战、多轮对话和进阶玩法最后是排错思路和工程规范。这套流程不是一次性教程而是一个可以持续迭代的工作台。如果你能动手把第 4 节的销售数据分析案例完整跑通就已经掌握了 80% 的日常用法。剩下 20% 的价值来自持续积累自己的提示词模板和 AI 工具函数库下次遇到新任务时封装好的函数会大大缩短你的开发时间。接下来值得继续深入的方向有三个一是学习提示词工程的高级技巧比如少样本提示和思维链二是尝试把本地部署的开源模型接入 Notebook这样不依赖外部 API数据隐私更有保障三是 Jupyter Notebook 高级用法比如魔法命令、Widgets 交互组件和 nbconvert 自动化导出。技术工具的最终目的是让你更专注于“思考问题”而不是“打字”。希望这篇文章能成为你工作流升级的起点。如果过程中遇到任何配置问题欢迎对照第 6 节的排查清单一步步定位多数问题都能在几分钟内解决。