1. 這篇文章真正要解決的問(wèn)題先說(shuō)結(jié)論Jupyter Notebook 不只是寫 Python 的筆記本工具它是目前最適合把生成式 AI 落地到日常開發(fā)工作中的“交互式實(shí)驗(yàn)臺(tái)”。很多程序員對(duì) Jupyter Notebook 的態(tài)度分兩種要么覺得它只是數(shù)據(jù)分析師和數(shù)據(jù)科學(xué)家的玩具寫工程代碼根本用不上要么覺得 AI 時(shí)代該用各種新出現(xiàn)的 AI 編程工具Jupyter 這種老牌交互式環(huán)境已經(jīng)過(guò)時(shí)。這兩種判斷在生成式 AI 爆發(fā)之后都被推翻了。為什么這樣說(shuō)回想一下你平時(shí)寫 AI 相關(guān)代碼會(huì)遇到什么情況調(diào)用大模型 API 時(shí)明明在終端里能跑通一旦放到腳本里就各種報(bào)錯(cuò)。想快速驗(yàn)證一個(gè)提示詞Prompt在不同參數(shù)下的效果卻要反復(fù)修改代碼、重新執(zhí)行整個(gè)腳本。處理一份數(shù)據(jù)想把 AI 生成的 JSON 結(jié)果可視化看看得先把結(jié)果保存成文件再用另一個(gè)腳本讀取。想調(diào)試一段內(nèi)嵌了 AI 調(diào)用的業(yè)務(wù)代碼卻看不清每一步的中間輸出。這些痛點(diǎn)本質(zhì)上不是代碼能力問(wèn)題而是工具形態(tài)問(wèn)題。終端腳本是線性執(zhí)行的你無(wú)法輕易地停在某個(gè)變量上觀察、修改、再繼續(xù)而 Jupyter Notebook 把代碼拆成一個(gè)個(gè)單元格可以獨(dú)立運(yùn)行、重復(fù)執(zhí)行、即時(shí)看到輸出這種交互方式恰好和生成式 AI 的“實(shí)驗(yàn)-觀察-調(diào)整”節(jié)奏完全匹配。另外一個(gè)更關(guān)鍵的變化是OpenAI、Anthropic、Hugging Face 等主流 AI 生態(tài)的官方示例代碼大量以 Jupyter Notebook 的形式發(fā)布。模型評(píng)測(cè)、RAG 問(wèn)答、Agent 工具調(diào)用、微調(diào)數(shù)據(jù)準(zhǔn)備隨便打開一個(gè)開源項(xiàng)目十有八九能在examples目錄里看到.ipynb文件。換句話說(shuō)Jupyter Notebook 已經(jīng)成了生成式 AI 領(lǐng)域的“事實(shí)標(biāo)準(zhǔn)演示格式”。不會(huì)用它你連很多官方示例都跑不起來(lái)。這篇文章要解決的就是如何把 Jupyter Notebook 配置成一個(gè)能用于生成式 AI 開發(fā)調(diào)試的完整環(huán)境從安裝、創(chuàng)建內(nèi)核、安裝依賴到調(diào)用大模型 API、處理流式輸出、集成工具調(diào)用再到多環(huán)境隔離和常見問(wèn)題排查。讀完你可以直接照著一套流程在手邊搭起一個(gè)屬于自己的 AI 實(shí)驗(yàn)環(huán)境。文章不會(huì)只講怎么打開 Notebook 寫兩行print(hello)而是從實(shí)際需求出發(fā)一步步走完環(huán)境配置、代碼實(shí)現(xiàn)、運(yùn)行驗(yàn)證和排錯(cuò)的全過(guò)程。2. 環(huán)境準(zhǔn)備與前置條件在動(dòng)手配置之前先明確我們要搭什么。很多人在“環(huán)境配置”這一步就放棄了不是因?yàn)殡y而是因?yàn)榫W(wǎng)上的教程版本混亂、工具選擇太多不知道聽誰(shuí)的。這里直接給出一份保守、穩(wěn)定、適合生成式 AI 開發(fā)的環(huán)境清單組件推薦方案說(shuō)明操作系統(tǒng)Windows 10/11 / Ubuntu 20.04 / macOS本文以 Windows 為主演示Linux/macOS 命令基本通用Python 版本Python 3.9 - 3.12太老版本不支持最新依賴太新版本部分庫(kù)可能不兼容包管理工具pip venv 或 conda二選一新手推薦 Anaconda工程化推薦 venvJupyter 環(huán)境Jupyter Notebook / JupyterLab兩者可以共存建議直接使用 JupyterLabAI 相關(guān)依賴openai、langchain 等按實(shí)際項(xiàng)目安裝不要一次裝太多瀏覽器Chrome / Edge不要用太老的瀏覽器Jupyter 前端依賴現(xiàn)代瀏覽器特性關(guān)于 Python 版本這里先給一個(gè)明確建議如果你的電腦上已經(jīng)有 Anaconda直接用它創(chuàng)建新的虛擬環(huán)境如果不想裝 Anaconda就用系統(tǒng) Python 加 venv。不要在系統(tǒng) Python 里直接pip install jupyter然后把所有包都裝到全局環(huán)境這在后續(xù)管理項(xiàng)目依賴時(shí)會(huì)出現(xiàn)嚴(yán)重問(wèn)題。Jupyter Notebook 和 JupyterLab 的區(qū)別很多新手會(huì)混淆。簡(jiǎn)單對(duì)比一下Jupyter Notebook經(jīng)典的單文檔交互界面一個(gè)瀏覽器標(biāo)簽頁(yè)對(duì)應(yīng)一個(gè).ipynb文件操作簡(jiǎn)單適合輕量使用。JupyterLabJupyter 官方打造的下一代集成開發(fā)環(huán)境支持多標(biāo)簽頁(yè)、文件資源管理器、終端、代碼高亮、插件系統(tǒng)更適合做完整項(xiàng)目開發(fā)。從生成式 AI 的開發(fā)需求來(lái)看推薦直接選擇 JupyterLab。它能在同一個(gè)界面里同時(shí)打開 Notebook、終端、文本編輯器一邊調(diào)試 AI 代碼一邊看日志體驗(yàn)接近一個(gè)輕量級(jí) IDE。Jupyter Notebook 稍后也可以繼續(xù)使用兩者共享相同的內(nèi)核機(jī)制并不沖突。還有一點(diǎn)需要提前確認(rèn)你的網(wǎng)絡(luò)環(huán)境能否訪問(wèn)大模型的 API 服務(wù)。生成式 AI 開發(fā)免不了調(diào)用云端大模型接口不同服務(wù)商的訪問(wèn)要求不同。在使用任何 API 之前請(qǐng)先確認(rèn)你使用的服務(wù)商提供的接入說(shuō)明以及你的網(wǎng)絡(luò)環(huán)境是否滿足訪問(wèn)條件。這個(gè)前置條件如果沒(méi)確認(rèn)好后面的示例代碼即使完全正確也可能出現(xiàn)連接超時(shí)。3. Jupyter 環(huán)境搭建與基礎(chǔ)配置3.1 方案一使用 Anaconda 安裝推薦新手Anaconda 自帶 Python、conda 包管理器、Jupyter Notebook、JupyterLab 和大量科學(xué)計(jì)算庫(kù)是最省事的方案。下載 Anaconda 安裝包后一路按默認(rèn)選項(xiàng)安裝。安裝完成后在命令行執(zhí)行conda --version如果能輸出版本號(hào)說(shuō)明 conda 安裝成功。接下來(lái)創(chuàng)建一個(gè)專門用于 AI 開發(fā)的虛擬環(huán)境conda create -n ai-dev python3.10 -y conda activate ai-dev簡(jiǎn)要解釋一下這兩條命令conda create -n ai-dev python3.10 -y創(chuàng)建名為ai-dev的虛擬環(huán)境并指定 Python 3.10。conda activate ai-dev激活這個(gè)環(huán)境。注意Windows 命令行和 PowerShell 環(huán)境下可能需要先執(zhí)行conda init初始化 shell。創(chuàng)建完虛擬環(huán)境后安裝 Jupyter 相關(guān)組件conda install jupyter jupyterlab -y安裝完成后在終端啟動(dòng)jupyter lab正常情況下瀏覽器會(huì)自動(dòng)打開http://localhost:8888/lab進(jìn)入 JupyterLab 界面。3.2 方案二使用 venv 安裝推薦工程化如果你不喜歡 Anaconda 的“大而全”更希望保持項(xiàng)目依賴干凈可以使用 Python 自帶的venv。首先確認(rèn)系統(tǒng) Python 版本python --version然后創(chuàng)建虛擬環(huán)境python -m venv ai-envWindows 下激活ai-env\Scripts\activateLinux/macOS 下激活source ai-env/bin/activate激活后命令行提示符前面會(huì)出現(xiàn)(ai-env)表示當(dāng)前在虛擬環(huán)境中。然后安裝 Jupyter 和 JupyterLabpip install --upgrade pip pip install jupyter jupyterlab同樣啟動(dòng)時(shí)執(zhí)行jupyter lab3.3 配置遠(yuǎn)程訪問(wèn)與固定密碼實(shí)際開發(fā)中你可能需要在另一臺(tái)機(jī)器或服務(wù)器上訪問(wèn) Jupyter。默認(rèn)啟動(dòng)方式只監(jiān)聽本機(jī)不方便遠(yuǎn)程使用。生成密碼配置文件jupyter server password按提示輸入兩次密碼后會(huì)生成一個(gè)帶哈希值的配置文件。然后執(zhí)行jupyter server --generate-config在生成的配置文件中修改以下幾項(xiàng)# 文件路徑~/.jupyter/jupyter_server_config.py c.ServerApp.ip 0.0.0.0 c.ServerApp.port 8888 c.ServerApp.open_browser False c.ServerApp.allow_remote_access True需要說(shuō)明的是遠(yuǎn)程訪問(wèn) Jupyter 必須考慮安全邊界特別是當(dāng) Jupyter 運(yùn)行在有公網(wǎng) IP 的云服務(wù)器上時(shí)一定要設(shè)置強(qiáng)密碼、禁用 root 用戶直接運(yùn)行 Notebook并建議通過(guò) SSH 隧道或內(nèi)網(wǎng)環(huán)境訪問(wèn)不要直接把 Jupyter 暴露到公網(wǎng)。更穩(wěn)妥的方式是使用--no-browser參數(shù)僅將 Jupyter 作為本機(jī)或內(nèi)網(wǎng)的開發(fā)調(diào)試工具使用。3.4 為虛擬環(huán)境創(chuàng)建 Jupyter 內(nèi)核這一步是新手最容易忽略的坑。我們創(chuàng)建了ai-dev或ai-env虛擬環(huán)境但在 JupyterLab 的新建 Notebook 中通常只看到默認(rèn)的Python 3內(nèi)核。如果直接在默認(rèn)內(nèi)核里安裝 AI 依賴會(huì)裝到 base 環(huán)境或系統(tǒng)環(huán)境導(dǎo)致虛擬環(huán)境里安裝的包加載不到。解決辦法是在激活的虛擬環(huán)境中把當(dāng)前環(huán)境注冊(cè)為 Jupyter 的內(nèi)核pip install ipykernel python -m ipykernel install --user --name ai-dev --display-name Python (ai-dev)參數(shù)解釋--name ai-dev內(nèi)核的唯一名稱。--display-name Python (ai-dev)顯示在 Jupyter 界面中的名稱。創(chuàng)建完成后在 JupyterLab 中新建 Notebook 時(shí)就能看到名為Python (ai-dev)的內(nèi)核選項(xiàng)。以后每個(gè)項(xiàng)目都可以通過(guò)這種方式創(chuàng)建獨(dú)立內(nèi)核避免依賴沖突。3.5 環(huán)境配置的最終檢查完成以上步驟后建議在 Notebook 中執(zhí)行以下代碼確認(rèn)環(huán)境正確import sys import jupyter print(Python 解釋器路徑:, sys.executable) print(Python 版本:, sys.version) print(Jupyter 版本:, jupyter.__version__)預(yù)期輸出中解釋器路徑應(yīng)該指向你的虛擬環(huán)境目錄而不是系統(tǒng) Python 目錄。這一步能幫你確認(rèn)“當(dāng)前 Notebook 用的到底是哪個(gè)環(huán)境”也是排查各種“我怎么裝了包但導(dǎo)入失敗”問(wèn)題的入口。同時(shí)要注意項(xiàng)目的需求依賴建議寫進(jìn)requirements.txt或environment.yml方便以后重建環(huán)境。不要憑記憶手動(dòng)安裝依賴。4. 生成式 AI 開發(fā)的核心概念配置好 Jupyter 之后先別急著寫代碼。要把生成式 AI 開發(fā)跑通需要先理解幾個(gè)核心概念。這些概念看起來(lái)簡(jiǎn)單但在實(shí)際調(diào)試時(shí)如果理解不透很容易被各種報(bào)錯(cuò)折磨。4.1 大模型 API 與提示詞生成式 AI 應(yīng)用的最基本形式就是調(diào)用大模型 API。你把一段輸入文本Prompt提示詞發(fā)給模型模型返回一段生成結(jié)果。在 Jupyter 單元格中調(diào)用過(guò)程通常是這樣from openai import OpenAI client OpenAI(api_keyyour-api-key) response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一個(gè)擅長(zhǎng)代碼審查的助手。}, {role: user, content: 請(qǐng)幫我解釋下面的代碼是做什么的...} ] ) print(response.choices[0].message.content)這里的messages列表是 Chat Completion API 的核心結(jié)構(gòu)包含三類角色system系統(tǒng)指令用來(lái)設(shè)定模型的行為和身份。user用戶輸入也就是你希望模型回答的問(wèn)題。assistant模型的回復(fù)在多輪對(duì)話中帶上歷史回復(fù)讓模型記住上下文。在這個(gè)示例中需要注意 API Key 千萬(wàn)不要直接寫在 Notebook 中并提交到代碼倉(cāng)庫(kù)。更安全的做法是使用環(huán)境變量import os from openai import OpenAI client OpenAI(api_keyos.getenv(OPENAI_API_KEY))在終端設(shè)置環(huán)境變量export OPENAI_API_KEYyour-api-keyWindows PowerShell 下$env:OPENAI_API_KEYyour-api-key4.2 流式輸出與實(shí)時(shí)交互調(diào)用大模型時(shí)如果模型生成內(nèi)容較長(zhǎng)等待完整結(jié)果返回會(huì)讓人感覺“卡住了”。實(shí)際上大模型本身是逐 token 生成內(nèi)容的API 也支持流式輸出Stream像 ChatGPT 那樣一個(gè)字一個(gè)字地出現(xiàn)在屏幕上。在 Jupyter 中實(shí)現(xiàn)流式輸出尤其有價(jià)值因?yàn)?Notbook 可以逐行顯示輸出效果非常直觀from openai import OpenAI import os client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) stream client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 寫一段 Python 代碼實(shí)現(xiàn)斐波那契數(shù)列。}], streamTrue, ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end, flushTrue)這段代碼的核心區(qū)別在于streamTrue后API 返回的是一個(gè)生成器對(duì)象可以逐個(gè)區(qū)塊讀取內(nèi)容。flushTrue確保內(nèi)容能實(shí)時(shí)打印而不是攢到緩沖區(qū)才顯示。這里真正容易踩坑的地方是部分模型服務(wù)商的兼容接口對(duì)stream參數(shù)的處理方式不完全一致有的返回delta.content有的返回choices[0].delta但content為None。如果輸出為空可以先打印一個(gè)chunk看完整結(jié)構(gòu)再?zèng)Q定取值字段。4.3 上下文管理與多輪對(duì)話很多人把多輪對(duì)話理解成“把用戶每句話拼接起來(lái)發(fā)給模型”這其實(shí)不對(duì)。正確的做法是把整個(gè)對(duì)話歷史作為messages列表傳給模型讓模型自己理解上下文messages [ {role: system, content: 你是一個(gè) Python 導(dǎo)師回答要簡(jiǎn)潔。}, ] messages.append({role: user, content: 什么是生成式 AI}) response client.chat.completions.create(modelgpt-4o-mini, messagesmessages) assistant_reply response.choices[0].message.content messages.append({role: assistant, content: assistant_reply}) messages.append({role: user, content: 那它和普通 AI 有什么區(qū)別}) response client.chat.completions.create(modelgpt-4o-mini, messagesmessages) print(response.choices[0].message.content)隨著對(duì)話輪次增加messages會(huì)越來(lái)越長(zhǎng)最終超過(guò)模型的最大上下文長(zhǎng)度。這時(shí)要考慮上下文壓縮、摘要或滑動(dòng)窗口策略。在生成式 AI 應(yīng)用里這部分通常需要專門的框架或向量數(shù)據(jù)庫(kù)支持不是簡(jiǎn)單拼接就能解決的。4.4 工具調(diào)用與 Agent 雛形生成式 AI 不只是“問(wèn)答機(jī)器”。通過(guò)工具調(diào)用Function Calling / Tool Use模型能夠決定在某些時(shí)候調(diào)用外部函數(shù)比如查詢數(shù)據(jù)庫(kù)、搜索網(wǎng)頁(yè)、執(zhí)行代碼從而完成更復(fù)雜的任務(wù)。用通俗的方式理解模型就像一個(gè)聰明的實(shí)習(xí)生它能聽懂你的需求但很多具體操作需要調(diào)用你提供的工具完成。工具調(diào)用就是給這個(gè)實(shí)習(xí)生一套“工具箱”并告訴他每個(gè)工具怎么用。在 Jupyter 中你可以非常方便地驗(yàn)證工具調(diào)用流程模型返回一個(gè)“意圖”你根據(jù)意圖執(zhí)行本地代碼然后把結(jié)果返回給模型讓模型根據(jù)結(jié)果生成最終回復(fù)。這種“模型-工具-模型”的循環(huán)就是 Agent 應(yīng)用的核心機(jī)制。5. Jupyter Notebook 集成生成式 AI 完整示例理清基礎(chǔ)概念后我們用一個(gè)完整示例把整個(gè)流程串起來(lái)。這個(gè)示例雖然不大但覆蓋了生成式 AI 開發(fā)的典型套路環(huán)境變量管理、模型調(diào)用、流式輸出、結(jié)構(gòu)化輸出以及將復(fù)雜邏輯封裝成類以便在 Jupyter 中反復(fù)調(diào)試。5.1 安裝依賴在虛擬環(huán)境激活狀態(tài)下執(zhí)行pip install openai python-dotenvopenaiOpenAI 官方 Python SDK目前大多數(shù)兼容接口也通過(guò)該 SDK 調(diào)用。python-dotenv用于加載.env文件中的環(huán)境變量。然后創(chuàng)建.env文件放在項(xiàng)目根目錄# 文件路徑.env OPENAI_API_KEYyour-api-key-here5.2 加載環(huán)境變量在 Jupyter 第一個(gè)單元格中from dotenv import load_dotenv import os load_dotenv() api_key os.getenv(OPENAI_API_KEY) print(API Key 是否已加載:, bool(api_key))如果輸出True說(shuō)明環(huán)境變量加載成功。如果輸出False請(qǐng)檢查.env文件路徑是否與 Notebook 所在目錄一致。Jupyter 的工作目錄默認(rèn)是啟動(dòng)時(shí)所在的目錄不是 Notebook 文件所在目錄這一點(diǎn)很容易搞混。5.3 封裝一個(gè)通用的大模型調(diào)用類為了后續(xù)在多個(gè) Notebook 中復(fù)用建議把大模型調(diào)用封裝成一個(gè)簡(jiǎn)單的類# 文件ai_client.py from openai import OpenAI from dotenv import load_dotenv import os load_dotenv() class AIClient: def __init__(self, modelgpt-4o-mini): self.client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) self.model model def chat(self, messages, streamFalse): response self.client.chat.completions.create( modelself.model, messagesmessages, streamstream, ) return response def stream_chat(self, messages): stream self.chat(messages, streamTrue) collected [] for chunk in stream: if chunk.choices[0].delta.content is not None: content chunk.choices[0].delta.content print(content, end, flushTrue) collected.append(content) print() return .join(collected)在 Jupyter 中導(dǎo)入并使用from ai_client import AIClient ai AIClient(modelgpt-4o-mini) messages [ {role: system, content: 你是一個(gè)代碼審查助手回答使用中文。}, {role: user, content: 請(qǐng)審查以下 Python 代碼指出潛在問(wèn)題\n\ndef calculate_average(nums):\n return sum(nums) / len(nums)}, ] ai.stream_chat(messages)這個(gè)類的好處是模型名稱、API 密鑰、調(diào)用方式都集中管理在 Notebook 中調(diào)試時(shí)只需要修改一個(gè)地方。實(shí)際項(xiàng)目中你還可以增加日志、重試、超時(shí)控制等功能。5.4 使用生成式 AI 分析代碼文件現(xiàn)在模擬一個(gè)更貼近開發(fā)者的場(chǎng)景我們有一段程序員的代碼希望 AI 幫忙分析復(fù)雜度、指出問(wèn)題并給出優(yōu)化建議。先把代碼定義為字符串避免在 Notebook 中創(chuàng)建臨時(shí)文件target_code def fetch_user_data(user_id): conn create_connection() cursor conn.cursor() cursor.execute(SELECT * FROM users WHERE id ?, (user_id,)) rows cursor.fetchall() result [] for row in rows: result.append({id: row[0], name: row[1], email: row[2]}) return result analysis_prompt f 請(qǐng)對(duì)以下代碼進(jìn)行審查輸出 JSON 格式的結(jié)果包含三個(gè)字段 - summary: 代碼功能概述 - issues: 潛在問(wèn)題列表 - suggestion: 改進(jìn)建議 代碼 {target_code} messages [ {role: system, content: 你是資深后端工程師擅長(zhǎng)代碼審查。}, {role: user, content: analysis_prompt}, ] response ai.chat(messages) content response.choices[0].message.content print(content)這里用了提示詞強(qiáng)制要求模型輸出 JSON 結(jié)構(gòu)。在實(shí)際項(xiàng)目中更推薦使用 API 的響應(yīng)格式參數(shù)或工具調(diào)用來(lái)獲得穩(wěn)定的結(jié)構(gòu)化輸出而不是僅靠提示詞約束。5.5 在 Notebook 中繪制結(jié)果生成式 AI 的響應(yīng)經(jīng)常包含文本和結(jié)構(gòu)化數(shù)據(jù)。在 Notebook 中你可以直接用 Pandas 和 Matplotlib 把 AI 生成的結(jié)果可視化這是終端腳本很難做到的體驗(yàn)。例如讓 AI 生成一份包含“代碼問(wèn)題嚴(yán)重程度”的 JSON 數(shù)據(jù)然后讀取并繪圖import json import pandas as pd import matplotlib.pyplot as plt data json.loads(content) issues data.get(issues, []) # 簡(jiǎn)單統(tǒng)計(jì)每個(gè)問(wèn)題的關(guān)鍵詞 issue_keywords [issue[:4] for issue in issues] # 取前4個(gè)字作為簡(jiǎn)易類別 df pd.DataFrame({問(wèn)題: issue_keywords}) df[數(shù)量] 1 summary_df df.groupby(問(wèn)題).count().reset_index() plt.figure(figsize(8, 4)) plt.bar(summary_df[問(wèn)題], summary_df[數(shù)量]) plt.title(代碼審查問(wèn)題統(tǒng)計(jì)) plt.xlabel(問(wèn)題類別) plt.ylabel(數(shù)量) plt.xticks(rotation45) plt.show()這個(gè)例子不算復(fù)雜但它展示了 Jupyter 集成生成式 AI 的核心優(yōu)勢(shì)在同一個(gè)文檔里完成“生成數(shù)據(jù)-處理數(shù)據(jù)-可視化數(shù)據(jù)”的完整閉環(huán)。6. 運(yùn)行結(jié)果與效果驗(yàn)證以上代碼運(yùn)行后我們需要驗(yàn)證是否真的成功了。生成式 AI 開發(fā)與普通 Web 開發(fā)不同判斷“成功”不只是看有沒(méi)有報(bào)錯(cuò)還要看輸出質(zhì)量是否符合預(yù)期。6.1 驗(yàn)證模型連接是否成功最簡(jiǎn)單的驗(yàn)證方式是調(diào)用一次短文本生成觀察輸出test_messages [ {role: user, content: 請(qǐng)回答11等于幾只輸出數(shù)字。}, ] response ai.chat(test_messages) print(response.choices[0].message.content)預(yù)期輸出2如果這一步能輸出內(nèi)容說(shuō)明 API 密鑰、網(wǎng)絡(luò)連接、SDK 版本都正常。這是整個(gè) AI 開發(fā)流程的“最小可行驗(yàn)證”。6.2 驗(yàn)證流式輸出是否正常執(zhí)行 5.3 中的stream_chat方法如果終端或 Notebook 單元格逐字打印出內(nèi)容說(shuō)明流式輸出生效。如果內(nèi)容一次性打印說(shuō)明flushTrue未生效或輸出緩沖機(jī)制不同。如果完全沒(méi)有輸出需要檢查chunk結(jié)構(gòu)stream ai.chat(test_messages, streamTrue) for chunk in stream: print(chunk)觀察打印出來(lái)的對(duì)象結(jié)構(gòu)確認(rèn)字段名。不同版本 SDK 的字段結(jié)構(gòu)可能略有不同。6.3 驗(yàn)證結(jié)構(gòu)化輸出是否可解析在 5.4 節(jié)模型返回的內(nèi)容是 JSON 字符串。需要驗(yàn)證能否被json.loads解析try: parsed json.loads(content) print(JSON 解析成功) print(字段列表:, list(parsed.keys())) except json.JSONDecodeError as e: print(JSON 解析失敗:, e)如果失敗常見原因是模型在 JSON 前后添加了 Markdown 代碼塊標(biāo)記比如json {...}解決辦法是清洗內(nèi)容 python def extract_json(text): # 去掉可能的 markdown 標(biāo)記 if text.startswith(): text text.strip() if text.startswith(json): text text[4:] return json.loads(text)6.4 驗(yàn)證環(huán)境隔離是否生效在 Jupyter 單元格中執(zhí)行import sys print(sys.executable)如果輸出路徑指向虛擬環(huán)境如/path/to/ai-env/bin/python或C:\...\ai-env\Scripts\python.exe說(shuō)明當(dāng)前 Notebook 使用的確實(shí)是虛擬環(huán)境的內(nèi)核。如果輸出指向系統(tǒng) Python 或 Anaconda base 環(huán)境說(shuō)明內(nèi)核選擇錯(cuò)誤需要重新執(zhí)行第 3.4 節(jié)的內(nèi)核創(chuàng)建步驟。7. 環(huán)境配置與 AI 開發(fā)常見問(wèn)題排查在實(shí)際操作中環(huán)境配置和 AI 調(diào)用是兩大問(wèn)題高發(fā)區(qū)。這里整理一份排查清單按出現(xiàn)頻率排序。問(wèn)題現(xiàn)象可能原因排查方式解決方案Jupyter 啟動(dòng)后瀏覽器空白瀏覽器版本過(guò)舊、內(nèi)核崩潰、端口被占用檢查瀏覽器控制臺(tái)報(bào)錯(cuò)更換瀏覽器訪問(wèn)更新瀏覽器重啟 Jupyter換端口啟動(dòng)jupyter lab --port 8890Notebook 導(dǎo)入了虛擬環(huán)境之外的包當(dāng)前內(nèi)核不是目標(biāo)虛擬環(huán)境print(sys.executable)查看解釋器路徑激活虛擬環(huán)境后重新執(zhí)行python -m ipykernel install --user --name my-env并在 Notebook 中切換內(nèi)核ModuleNotFoundError: No module named openai依賴裝錯(cuò)環(huán)境查看 pip 安裝時(shí)的提示路徑確認(rèn)虛擬環(huán)境已激活后重新pip install openaiAPI 調(diào)用超時(shí)網(wǎng)絡(luò)不通、代理干擾、模型服務(wù)端異常先測(cè)試網(wǎng)絡(luò)連通性查看錯(cuò)誤碼檢查網(wǎng)絡(luò)環(huán)境重試使用支持超時(shí)參數(shù)的 SDK 配置API 返回401 UnauthorizedAPI Key 錯(cuò)誤或未設(shè)置打印api_key前綴確認(rèn)來(lái)源檢查.env文件、環(huán)境變量是否正確加載API 返回RateLimitError觸發(fā)調(diào)用頻率限制查看錯(cuò)誤響應(yīng)中的 Retry-After 時(shí)間降低調(diào)用頻率升級(jí)套餐增加退避重試邏輯流式輸出沒(méi)有逐字顯示緩沖機(jī)制、SDK 版本差異檢查flushTrue打印 chunk 結(jié)構(gòu)改用display()方法或在循環(huán)中收集后統(tǒng)一顯示json.loads解析失敗模型輸出中包含 Markdown 標(biāo)記或多余文本打印原始content查看頭尾字符編寫清洗函數(shù)去除 Markdown 標(biāo)記后解析7.1 關(guān)于ModuleNotFoundError的深層排查很多人在 Jupyter 中import包失敗但在終端中import成功這是因?yàn)?Jupyter 的內(nèi)核環(huán)境與終端環(huán)境不一致。排查步驟在 Notebook 中執(zhí)行python -c import sys; print(sys.executable)。在終端中執(zhí)行pip show package-name查看包安裝路徑。對(duì)比兩者路徑是否一致。如果不一致執(zhí)行# 激活目標(biāo)環(huán)境 conda activate ai-dev # 重新安裝 ipykernel 并注冊(cè) python -m ipykernel install --user --name ai-dev --display-name Python (ai-dev)然后在 JupyterLab 中選擇內(nèi)核Kernel - Change Kernel - Python (ai-dev)。7.2 關(guān)于 Jupyter 啟動(dòng)后空白頁(yè)Windows 上經(jīng)常出現(xiàn) Jupyter 啟動(dòng)后瀏覽器打開但頁(yè)面空白的問(wèn)題。原因可能是筆記本默認(rèn)瀏覽器不支持 WebSocket或者瀏覽器插件攔截。建議按以下順序排查手動(dòng)復(fù)制終端輸出的http://localhost:8888/lab地址在 Chrome 或 Edge 中打開。清除瀏覽器緩存。查看終端日志是否出現(xiàn)KernelRestarter或WebSocket相關(guān)錯(cuò)誤。如果仍空白嘗試在啟動(dòng)命令中加入--no-browser后手動(dòng)打開地址。7.3 關(guān)于 API Key 管理這里要特別強(qiáng)調(diào)任何形式的 API Key 泄露都可能造成資金損失和安全問(wèn)題。不要把 Key 寫到代碼里更不要直接把.env文件提交到 Git 倉(cāng)庫(kù)。建議在.gitignore中添加.env *.env同時(shí)在云服務(wù)器上運(yùn)行 Jupyter 時(shí)不要直接用 root 賬號(hào)啟動(dòng)建議創(chuàng)建普通用戶并限制目錄訪問(wèn)權(quán)限。8. 生產(chǎn)環(huán)境與工程化最佳實(shí)踐如果只是個(gè)人學(xué)習(xí)把 Jupyter 和生成式 AI 跑通就足夠了。但如果你想把這個(gè)流程用到團(tuán)隊(duì)項(xiàng)目或生產(chǎn)環(huán)境中下面這些實(shí)踐值得提前了解。8.1 環(huán)境隔離與依賴管理在生成式 AI 項(xiàng)目中依賴版本變化非常快。今天能用openaiSDK 的 1.x 版本明天模型服務(wù)商可能就更新接口。所以環(huán)境隔離不是可選項(xiàng)而是必須項(xiàng)。推薦做法每個(gè)項(xiàng)目單獨(dú)創(chuàng)建虛擬環(huán)境單獨(dú)注冊(cè) Jupyter 內(nèi)核。使用requirements.txt或pyproject.toml鎖定依賴版本。定期更新依賴但更新前先在虛擬環(huán)境測(cè)試。不要直接在 base 環(huán)境安裝包。生成依賴鎖定文件的方式pip freeze requirements-lock.txt8.2 提示詞版本管理與測(cè)試生成式 AI 應(yīng)用與傳統(tǒng)軟件最大的不同提示詞就是代碼的一部分但它很難做單元測(cè)試。同一個(gè)提示詞換一個(gè)模型版本輸出可能完全不一樣。因此工程化項(xiàng)目中通常會(huì)把提示詞抽取到單獨(dú)的模塊并用測(cè)試用例維護(hù)# 文件prompts.py CODE_REVIEW_SYSTEM_PROMPT 你是一個(gè)資深后端工程師擅長(zhǎng)代碼審查。 CODE_REVIEW_USER_PROMPT_TEMPLATE 請(qǐng)對(duì)以下代碼進(jìn)行審查輸出 JSON 格式的結(jié)果包含三個(gè)字段 - summary: 代碼功能概述 - issues: 潛在問(wèn)題列表 - suggestion: 改進(jìn)建議 代碼 {code} 這樣做的價(jià)值是可以在 Notebook 或測(cè)試腳本中引用同一個(gè)提示詞模板保證線上和實(shí)驗(yàn)環(huán)境一致。避免在 Notebook 里寫死提示詞部署到生產(chǎn)時(shí)又復(fù)制一份到代碼里最后兩邊不一致。8.3 模型調(diào)用的可觀測(cè)性調(diào)用大模型 API 時(shí)一定要記錄日志。原因是大模型接口是黑盒出錯(cuò)時(shí)需要知道請(qǐng)求參數(shù)、響應(yīng)內(nèi)容、耗時(shí)和錯(cuò)誤碼。在AIClient中增加簡(jiǎn)單日志import logging import time logger logging.getLogger(__name__) class AIClient: def __init__(self, modelgpt-4o-mini): self.client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) self.model model def chat(self, messages, streamFalse): start_time time.time() logger.info(開始調(diào)用模型 %s消息數(shù)量 %d, self.model, len(messages)) response self.client.chat.completions.create( modelself.model, messagesmessages, streamstream, ) elapsed time.time() - start_time logger.info(模型調(diào)用完成耗時(shí) %.2f 秒, elapsed) return response在生產(chǎn)環(huán)境中應(yīng)把日志輸出到收集系統(tǒng)而不是全部打到控制臺(tái)。這部分根據(jù)團(tuán)隊(duì)實(shí)際技術(shù)棧選擇。8.4 安全與合規(guī)提醒涉及生成式 AI 開發(fā)有幾個(gè)安全邊界必須注意不要將敏感數(shù)據(jù)直接發(fā)送給大模型 API。在發(fā)送前盡量做脫敏處理。不要自動(dòng)執(zhí)行模型生成的代碼。模型輸出可能包含惡意內(nèi)容如果需要執(zhí)行必須在沙箱環(huán)境中。對(duì)模型輸出做校驗(yàn)特別是涉及 SQL、文件路徑、命令執(zhí)行時(shí)禁止直接拼接執(zhí)行。遵守模型服務(wù)商的使用條款不要批量抓取或?yàn)E用接口。這些提醒看起來(lái)很基礎(chǔ)但在實(shí)際生產(chǎn)中正是這些細(xì)節(jié)決定了系統(tǒng)能否穩(wěn)定運(yùn)行。8.5 Notebook 與生產(chǎn)代碼的邊界最后給一個(gè)明確的工程建議Jupyter Notebook 適合做實(shí)驗(yàn)和調(diào)試但不適合直接作為生產(chǎn)代碼運(yùn)行。如果你已經(jīng)在 Notebook 中驗(yàn)證了一個(gè) AI 功能把它遷移到生產(chǎn)時(shí)應(yīng)該將核心邏輯抽到 Python 模塊或服務(wù)中。去掉 Notebook 特有的狀態(tài)依賴。使用配置管理工具管理環(huán)境和密鑰。編寫自動(dòng)化測(cè)試至少覆蓋“調(diào)用成功”“調(diào)用失敗”“輸入為空”三類場(chǎng)景。部署前在實(shí)際環(huán)境跑一次冒煙測(cè)試。Notebook 的最大價(jià)值是讓你更快地探索和驗(yàn)證想法生產(chǎn)系統(tǒng)的穩(wěn)定性還是要靠規(guī)范的代碼和流程來(lái)保障。9. Jupyter Notebook 與 JupyterLab 的選型參考回到很多新手糾結(jié)的問(wèn)題Jupyter Notebook 和 JupyterLab 到底選哪個(gè)給出直接的結(jié)論新項(xiàng)目直接用 JupyterLab老教程里涉及.ipynb文件的用 JupyterLab 打開也一樣可以運(yùn)行。兩者能處理的文件格式相同JupyterLab 是 Jupyter Notebook 的超集界面。不過(guò)如果只是臨時(shí)打開別人分享的.ipynb文件看一下運(yùn)行結(jié)果那么 Jupyter Notebook 更輕量啟動(dòng)速度更快。另一種情況是你的項(xiàng)目代碼主要是純 Python 腳本只有少數(shù)幾個(gè) Notebook 用來(lái)做試驗(yàn)也可以混合使用。兩者對(duì)比對(duì)比項(xiàng)Jupyter NotebookJupyterLab界面形態(tài)單文檔界面多標(biāo)簽頁(yè)集成界面文件瀏覽器無(wú)有終端支持弱內(nèi)置終端插件生態(tài)較少豐富適用場(chǎng)景輕量查看、簡(jiǎn)單實(shí)驗(yàn)完整開發(fā)、調(diào)試、AI 項(xiàng)目未來(lái)趨勢(shì)維護(hù)模式官方主推方向從生成式 AI 開發(fā)的實(shí)際體驗(yàn)來(lái)看JupyterLab 的多標(biāo)簽頁(yè)支持非常實(shí)用一個(gè)標(biāo)簽頁(yè)寫 Notebook一個(gè)標(biāo)簽頁(yè)打開終端一個(gè)標(biāo)簽頁(yè)看文檔效率比來(lái)回切換窗口高很多。10. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇內(nèi)容差不多把“Jupyter Notebook 生成式 AI 環(huán)境配置”這條線完整走了一遍理解了 Jupyter 系列工具在 AI 開發(fā)中的定位它本質(zhì)上是交互式實(shí)驗(yàn)臺(tái)和 AI 的探索式工作流非常匹配。完成了從 Anaconda/venv 到 Jupyter 內(nèi)核注冊(cè)的環(huán)境搭建解決了“包裝錯(cuò)環(huán)境”“內(nèi)核選錯(cuò)”等經(jīng)典問(wèn)題。通過(guò)完整示例實(shí)現(xiàn)了大模型 API 調(diào)用、流式輸出、結(jié)構(gòu)化輸出、代碼審查與結(jié)果可視化。整理了常見問(wèn)題排查表覆蓋環(huán)境配置和 API 調(diào)用兩大高頻故障區(qū)。探討了生產(chǎn)環(huán)境中的依賴管理、提示詞版本管理、日志可觀測(cè)性、安全邊界等工程化問(wèn)題。下一步的學(xué)習(xí)方向可以根據(jù)自己的目標(biāo)選想深入理解生成式 AI 的原理學(xué)習(xí) Transformer 的核心架構(gòu)理解 Token、注意力機(jī)制、上下文窗口等基礎(chǔ)概念這對(duì)調(diào)優(yōu)提示詞和選擇模型有很大幫助。想做 RAG 應(yīng)用把 LLM 和向量數(shù)據(jù)庫(kù)結(jié)合起來(lái)在 Jupyter 中試驗(yàn)文檔切分、嵌入、檢索的完整流程。想做 Agent 應(yīng)用研究工具調(diào)用機(jī)制在 Notebook 中搭建一個(gè)能自動(dòng)調(diào)用外部函數(shù)的 Agent 原型。想進(jìn)入生產(chǎn)部署學(xué)習(xí)如何把 Notebook 中驗(yàn)證過(guò)的代碼打包成服務(wù)配置 CI/CD處理模型 API 的并發(fā)和降級(jí)策略。一個(gè)比較實(shí)用的建議是把你日常開發(fā)中的一個(gè)低頻重復(fù)任務(wù)比如代碼審查、日志分析、測(cè)試用例生成用 Jupyter 生成式 AI 做一個(gè)原型?；▋蓚€(gè)小時(shí)跑通感受一下交互式調(diào)試帶來(lái)的效率變化比看再多教程都有用。環(huán)境配置是第一步也是最容易勸退的一步現(xiàn)在照著上面的步驟跑通一次后面就順暢了。建議收藏備用遇到環(huán)境問(wèn)題的時(shí)候回來(lái)對(duì)照排查清單能省下不少搜索時(shí)間。