آموزش Jupyter Notebook و JupyterLab؛ از نصب تا پروژه هوش مصنوعی

Jupyter Notebook یکی از محبوب‌ترین محیط‌ها برای یادگیری پایتون، تحلیل داده، یادگیری ماشین و توسعه پروژه‌های هوش مصنوعی است. برخلاف یک فایل معمولی Python، در نوت‌بوک می‌توانید کد، توضیحات متنی، جدول، نمودار، فرمول و نتیجه اجرای برنامه را در یک سند واحد نگه دارید.

این ویژگی باعث شده است Jupyter به ابزار اصلی بسیاری از برنامه‌نویسان، تحلیلگران داده، پژوهشگران و مهندسان هوش مصنوعی تبدیل شود.

در این آموزش صرفاً چند دستور پراکنده را بررسی نمی‌کنیم. ابتدا Jupyter Notebook و JupyterLab را به‌درستی نصب می‌کنیم، سپس مفهوم Cell و Kernel، محیط مجازی، مدیریت پکیج‌ها، اجرای مرتب سلول‌ها و ساختار مناسب پروژه را یاد می‌گیریم. در پایان نیز یک پروژه عملی می‌سازیم که داده‌های فروش را تحلیل کرده و با استفاده از API هوش مصنوعی درواره، از نتایج عددی یک گزارش مدیریتی تولید می‌کند.

Jupyter Notebook چیست؟

Jupyter Notebook یک محیط تعاملی برای اجرای کد است. فایل‌های ساخته‌شده در این محیط معمولاً پسوند .ipynb دارند و می‌توانند بخش‌های زیر را در کنار یکدیگر نگه دارند:

• کد قابل اجرا
• متن Markdown
• جدول داده
• نمودار
• تصویر
• فرمول
• خروجی اجرای برنامه
• خطاها و پیام‌های تشخیصی

در یک فایل Python معمولی، معمولاً کل برنامه یا بخشی از آن را از طریق ترمینال اجرا می‌کنید. در Jupyter، برنامه به سلول‌های مستقل تقسیم می‌شود و می‌توانید هر سلول را جداگانه اجرا کنید.

این روش برای کارهای اکتشافی بسیار مناسب است؛ برای مثال:

• بررسی اولیه یک فایل CSV
• پاک‌سازی داده‌ها
• آزمایش یک الگوریتم یادگیری ماشین
• مقایسه چند مدل
• رسم نمودار
• آزمایش یک API
• تحلیل خروجی یک مدل زبانی
• نوشتن گزارش فنی همراه با کد

مطابق مستندات رسمی JupyterLab، نوت‌بوک‌ها می‌توانند کد اجرایی، Markdown، فرمول، تصویر، نمودار و خروجی‌های تعاملی را در یک سند ترکیب کنند.

تفاوت Jupyter Notebook و JupyterLab چیست؟

Jupyter Notebook نامی است که هم برای قالب فایل‌های .ipynb و هم برای رابط کلاسیک اجرای این فایل‌ها استفاده می‌شود.

JupyterLab محیط کامل‌تر و جدیدتری است که علاوه بر Notebook، امکانات دیگری نیز ارائه می‌دهد:

برای بیشتر کاربران، نصب JupyterLab انتخاب مناسب‌تری است؛ زیرا همچنان فایل‌های Notebook را اجرا می‌کند، اما محیط کاری کامل‌تری در اختیار شما قرار می‌دهد.

تفاوت Jupyter با Google Colab

هر دو ابزار از قالب Notebook استفاده می‌کنند، اما نحوه اجرا و مدیریت منابع آن‌ها متفاوت است.

اگر می‌خواهید سریع و بدون نصب آزمایش کنید، Google Colab مفید است. اگر کنترل بیشتری روی محیط، پکیج‌ها، فایل‌ها و ساختار پروژه می‌خواهید، JupyterLab محلی انتخاب بهتری است.

Jupyter چگونه کار می‌کند؟

برای درک درست Jupyter باید سه جزء اصلی آن را بشناسید.

رابط کاربری

همان صفحه‌ای است که در مرورگر مشاهده می‌کنید. این رابط می‌تواند Jupyter Notebook کلاسیک یا JupyterLab باشد.

سرور Jupyter

زمانی که دستور jupyter lab را اجرا می‌کنید، یک سرور محلی روی سیستم شما راه‌اندازی می‌شود. مرورگر به این سرور متصل می‌شود و فایل‌ها، سلول‌ها و خروجی‌ها را نمایش می‌دهد.

این سرور معمولاً فقط روی سیستم محلی و آدرسی شبیه آدرس زیر اجرا می‌شود:

http://localhost:8888/lab

Kernel

Kernel فرایندی است که کدهای داخل سلول‌ها را اجرا می‌کند. برای یک Notebook پایتون، معمولاً IPython Kernel مسئول اجرای کد است.

متغیرها، توابع، مدل‌ها و داده‌هایی که ایجاد می‌کنید در حافظه Kernel باقی می‌مانند. به همین دلیل ممکن است یک متغیر را در سلول اول تعریف کنید و در سلول پنجم از آن استفاده کنید.

اگر Kernel را Restart کنید، تمام متغیرهای موجود در حافظه حذف می‌شوند؛ اما کد نوشته‌شده داخل سلول‌ها باقی می‌ماند.

پیش‌نیازهای نصب JupyterLab

برای ادامه آموزش به موارد زیر نیاز دارید:

• Python 3
• دسترسی به Terminal، PowerShell یا Command Prompt
• pip
• یک مرورگر به‌روز
• آشنایی مقدماتی با پایتون

نسخه نصب‌شده پایتون را بررسی کنید:

python --version

در بعضی سیستم‌های لینوکس و macOS باید از دستور زیر استفاده کنید:

python3 --version

نسخه pip را نیز بررسی کنید:

python -m pip --version

استفاده از python -m pip کمک می‌کند پکیج‌ها برای همان نسخه پایتونی نصب شوند که قصد اجرای آن را دارید.

ساخت پوشه پروژه

ابتدا یک پوشه برای پروژه بسازید:

mkdir jupyter-ai-project
cd jupyter-ai-project

ساختار نهایی پروژه ما به شکل زیر خواهد بود:

jupyter-ai-project/
├── .env
├── .gitignore
├── requirements.txt
├── data/
├── notebooks/
│   └── sales_analysis.ipynb
└── src/

پوشه notebooks محل نگهداری نوت‌بوک‌ها است. کدهای قابل استفاده مجدد را بعداً می‌توانیم به پوشه src منتقل کنیم.

ساخت محیط مجازی پایتون

بهتر است Jupyter و کتابخانه‌های هر پروژه را داخل یک Virtual Environment جداگانه نصب کنید. این کار از تداخل نسخه پکیج‌های پروژه‌های مختلف جلوگیری می‌کند.

ساخت محیط مجازی:

python -m venv .venv

فعال‌سازی در Windows PowerShell:

.venv\Scripts\Activate.ps1

فعال‌سازی در Command Prompt ویندوز:

.venv\Scripts\activate.bat

فعال‌سازی در Linux و macOS:

source .venv/bin/activate

پس از فعال‌سازی، معمولاً نام .venv در ابتدای خط ترمینال نمایش داده می‌شود.

نصب JupyterLab

ابتدا pip را به‌روزرسانی کنید:

python -m pip install --upgrade pip

سپس JupyterLab و کتابخانه‌های موردنیاز پروژه را نصب کنید:

python -m pip install jupyterlab ipykernel pandas numpy plotly requests python-dotenv

طبق راهنمای رسمی نصب Jupyter، JupyterLab از طریق pip نصب و با دستور jupyter lab اجرا می‌شود.

برای مشاهده نسخه نصب‌شده:

jupyter lab --version

اجرای JupyterLab

در ریشه پروژه دستور زیر را اجرا کنید:

jupyter lab

پس از چند لحظه، محیط JupyterLab در مرورگر باز می‌شود. اگر مرورگر خودکار باز نشد، آدرس نشان‌داده‌شده در ترمینال را باز کنید.

برای متوقف‌کردن سرور، به ترمینال برگردید و کلیدهای زیر را فشار دهید:

Ctrl + C

ساخت اولین Notebook

در JupyterLab وارد پوشه notebooks شوید. سپس از Launcher گزینه Python را در بخش Notebook انتخاب کنید.

یک فایل جدید ایجاد می‌شود. نام آن را از Untitled.ipynb به نام زیر تغییر دهید:

sales_analysis.ipynb

برای اطمینان از عملکرد صحیح محیط، کد زیر را در اولین سلول بنویسید:

message = "JupyterLab با موفقیت اجرا شد."
print(message)

سلول را با Shift + Enter اجرا کنید.

انواع Cell در Jupyter

سه نوع اصلی سلول در Jupyter وجود دارد.

Code Cell

برای نوشتن و اجرای کد استفاده می‌شود:

numbers = [10, 20, 30, 40]
sum(numbers)

Markdown Cell

برای عنوان، توضیح، فهرست، لینک و مستندسازی استفاده می‌شود:

# گزارش تحلیل فروش

در این نوت‌بوک، عملکرد کانال‌های فروش بررسی می‌شود.

## اهداف

- محاسبه درآمد
- مقایسه کانال‌ها
- تولید گزارش مدیریتی

Raw Cell

متن داخل Raw Cell اجرا یا پردازش نمی‌شود. این نوع سلول در بعضی فرایندهای تبدیل و انتشار کاربرد دارد، اما در استفاده روزمره کمتر به آن نیاز خواهید داشت.

میان‌برهای کاربردی JupyterLab

Jupyter دو حالت اصلی دارد:

• Edit Mode برای ویرایش محتوای سلول
• Command Mode برای مدیریت سلول‌ها

با Enter وارد Edit Mode و با Esc وارد Command Mode می‌شوید.

میان‌برهای مهم:

ممکن است بعضی میان‌برها با توجه به نسخه، سیستم‌عامل یا Keymap انتخاب‌شده کمی متفاوت باشند.

مدیریت Kernel و ترتیب اجرای سلول‌ها

یکی از رایج‌ترین خطاهای کاربران Jupyter، اجرای سلول‌ها با ترتیب نامنظم است.

برای مثال، اگر ابتدا این سلول را اجرا کنید:

discounted_price = price * 0.9

اما سلول تعریف price را اجرا نکرده باشید، خطای زیر رخ می‌دهد:

NameError: name 'price' is not defined

مشکل جدی‌تر زمانی ایجاد می‌شود که مقدار متغیری را تغییر داده باشید، اما ترتیب نمایش سلول‌ها با ترتیب واقعی اجرا متفاوت باشد. در این وضعیت، Notebook روی سیستم شما کار می‌کند، ولی پس از Restart شدن Kernel دیگر از ابتدا اجرا نمی‌شود.

قبل از تحویل یا انتشار Notebook:

1. Kernel را Restart کنید.
2. همه سلول‌ها را از بالا به پایین اجرا کنید.
3. بررسی کنید هیچ سلولی به وضعیت مخفی قبلی وابسته نباشد.
4. مطمئن شوید خروجی نهایی قابل بازتولید است.

در JupyterLab می‌توانید از گزینه زیر استفاده کنید:

Kernel → Restart Kernel and Run All Cells

اگر Notebook بعد از Restart و اجرای کامل بدون خطا کار کند، احتمال وابستگی آن به وضعیت مخفی Kernel بسیار کمتر است.

ثبت محیط مجازی به‌عنوان Kernel

ممکن است JupyterLab اجرا شود، اما Notebook از Python یا محیط مجازی اشتباهی استفاده کند. برای جلوگیری از این مشکل، محیط فعلی را به‌عنوان یک Kernel ثبت کنید:

python -m ipykernel install --user --name darvareh-jupyter --display-name "Python (Darvareh Project)"

اکنون در منوی انتخاب Kernel باید گزینه زیر را ببینید:

Python (Darvareh Project)

فهرست Kernelهای نصب‌شده را می‌توانید با این دستور مشاهده کنید:

jupyter kernelspec list

برای بررسی مفسر فعال داخل Notebook نیز این کد را اجرا کنید:

import sys

print(sys.executable)
print(sys.version)

مسیر نمایش‌داده‌شده باید به محیط .venv پروژه مربوط باشد.

نصب پکیج از داخل Notebook

اگر لازم است کتابخانه‌ای را داخل Notebook نصب کنید، بهتر است از Magic Command زیر استفاده کنید:

%pip install package-name

برای مثال:

%pip install plotly

استفاده از %pip معمولاً بهتر از دستور زیر است:

!pip install plotly

زیرا %pip با محیط Kernel هماهنگی بیشتری دارد. بااین‌حال، برای پروژه‌های جدی بهتر است نصب پکیج‌ها را در ترمینال و داخل محیط مجازی انجام دهید.

بعد از نصب یا ارتقای بعضی پکیج‌ها ممکن است لازم باشد Kernel را Restart کنید.

Magic Commandهای مهم

Jupyter و IPython چند دستور ویژه ارائه می‌دهند که با % یا %% شروع می‌شوند.

نمایش پوشه کاری فعلی:

%pwd

نمایش متغیرهای تعریف‌شده:

%who

اندازه‌گیری زمان اجرای یک دستور:

%time sum(range(1_000_000))

اندازه‌گیری چندباره برای مقایسه عملکرد:

%timeit sum(range(10_000))

اندازه‌گیری زمان اجرای کل سلول:

%%time

result = 0
for number in range(1_000_000):
    result += number

بارگذاری خودکار تغییرات ماژول‌های محلی:

%load_ext autoreload
%autoreload 2

این قابلیت زمانی مفید است که توابع پروژه را داخل فایل‌های پوشه src نوشته باشید و بخواهید تغییرات آن‌ها بدون Restart کامل Kernel بارگذاری شوند.

مدیریت مسیر فایل‌ها در Notebook

یکی از خطاهای رایج، استفاده از مسیرهای مطلق مانند نمونه زیر است:

data = pd.read_csv("C:/Users/example/Desktop/sales.csv")

این مسیر فقط روی کامپیوتر همان کاربر کار می‌کند.

بهتر است از مسیرهای نسبی و کتابخانه pathlib استفاده کنید:

from pathlib import Path

current_directory = Path.cwd()

if current_directory.name == "notebooks":
    project_root = current_directory.parent
else:
    project_root = current_directory

data_directory = project_root / "data"
data_directory.mkdir(exist_ok=True)

print(project_root)
print(data_directory)

این روش اجرای پروژه روی سیستم‌های مختلف را ساده‌تر می‌کند.

پروژه عملی: تحلیل فروش و تولید گزارش با هوش مصنوعی

در این پروژه یک مجموعه داده نمونه می‌سازیم، عملکرد کانال‌های فروش را تحلیل می‌کنیم، نمودار تعاملی رسم می‌کنیم و سپس خلاصه داده را برای تولید گزارش به API هوش مصنوعی درواره می‌فرستیم.

مرحله اول: واردکردن کتابخانه‌ها

در یک Code Cell بنویسید:

from pathlib import Path
import json
import os

import numpy as np
import pandas as pd
import plotly.express as px
import requests
from dotenv import load_dotenv

pd.set_option("display.max_columns", 20)
pd.set_option("display.float_format", lambda value: f"{value:,.2f}")

مرحله دوم: تعیین مسیر پروژه

current_directory = Path.cwd()

if current_directory.name == "notebooks":
    project_root = current_directory.parent
else:
    project_root = current_directory

data_directory = project_root / "data"
data_directory.mkdir(exist_ok=True)

print(f"Project root: {project_root}")

مرحله سوم: ساخت داده نمونه

برای اینکه پروژه بدون نیاز به دانلود فایل خارجی اجرا شود، یک مجموعه داده قابل بازتولید می‌سازیم:

rng = np.random.default_rng(seed=42)

row_count = 1_500
available_dates = pd.date_range(
    start="2026-01-01",
    end="2026-06-30",
    freq="D",
)

channels = np.array([
    "Organic Search",
    "Direct",
    "Social",
    "Email",
    "Referral",
])

categories = np.array([
    "Software",
    "Education",
    "Electronics",
    "Office",
])

sales = pd.DataFrame({
    "date": rng.choice(available_dates, size=row_count),
    "channel": rng.choice(
        channels,
        size=row_count,
        p=[0.34, 0.22, 0.18, 0.16, 0.10],
    ),
    "category": rng.choice(categories, size=row_count),
    "sessions": rng.integers(100, 2_500, size=row_count),
    "conversion_rate": rng.uniform(0.01, 0.09, size=row_count),
    "average_order_value": rng.uniform(500_000, 8_000_000, size=row_count),
})

sales["orders"] = (
    sales["sessions"] * sales["conversion_rate"]
).round().astype(int)

sales["revenue"] = (
    sales["orders"] * sales["average_order_value"]
).round()

sales = sales.sort_values("date").reset_index(drop=True)

sales.head()

چون Seed ثابت است، اجرای مجدد این سلول همان توالی تصادفی را تولید می‌کند. این ویژگی برای بازتولیدپذیری آزمایش مهم است.

مرحله چهارم: ذخیره داده نمونه

csv_path = data_directory / "sales.csv"

sales.to_csv(csv_path, index=False)

print(f"Saved to: {csv_path}")

در یک پروژه واقعی، می‌توانید این مرحله را حذف و فایل اصلی خود را از پوشه data بخوانید.

مرحله پنجم: خواندن و اعتبارسنجی داده

df = pd.read_csv(
    csv_path,
    parse_dates=["date"],
)

required_columns = {
    "date",
    "channel",
    "category",
    "sessions",
    "orders",
    "revenue",
}

missing_columns = required_columns.difference(df.columns)

if missing_columns:
    raise ValueError(
        f"Missing required columns: {sorted(missing_columns)}"
    )

if df.empty:
    raise ValueError("The dataset is empty.")

if (df["sessions"] < 0).any():
    raise ValueError("Sessions cannot be negative.")

if (df["orders"] < 0).any():
    raise ValueError("Orders cannot be negative.")

print(f"Rows: {len(df):,}")
print(f"Duplicate rows: {df.duplicated().sum():,}")
print(f"Date range: {df['date'].min()} to {df['date'].max()}")

df.info()

اعتبارسنجی داده پیش از تحلیل، جلوی بسیاری از نتایج اشتباه را می‌گیرد. فقط اینکه کد بدون خطا اجرا شود به معنی صحیح‌بودن داده نیست.

مرحله ششم: بررسی مقادیر خالی

missing_report = (
    df.isna()
    .sum()
    .sort_values(ascending=False)
    .rename("missing_count")
    .to_frame()
)

missing_report["missing_percent"] = (
    missing_report["missing_count"] / len(df) * 100
)

missing_report

در این داده نمونه نباید مقدار خالی وجود داشته باشد. در داده واقعی باید برای هر ستون تصمیم بگیرید مقدار خالی حذف، جایگزین یا نگه‌داری شود.

مرحله هفتم: خلاصه آماری

df[
    [
        "sessions",
        "orders",
        "conversion_rate",
        "average_order_value",
        "revenue",
    ]
].describe()

برای جلوگیری از نمایش خروجی بسیار بزرگ، به‌جای چاپ کل DataFrame از head()، sample()، describe() و گزارش‌های تجمیعی استفاده کنید.

مرحله هشتم: محاسبه عملکرد کانال‌ها

میانگین ساده نرخ تبدیل می‌تواند گمراه‌کننده باشد، زیرا تعداد Session در ردیف‌ها یکسان نیست. بنابراین نرخ تبدیل تجمیعی را از تقسیم مجموع سفارش‌ها بر مجموع Sessionها محاسبه می‌کنیم:

channel_summary = (
    df.groupby("channel", as_index=False)
    .agg(
        sessions=("sessions", "sum"),
        orders=("orders", "sum"),
        revenue=("revenue", "sum"),
    )
)

channel_summary["conversion_rate"] = (
    channel_summary["orders"]
    / channel_summary["sessions"]
)

channel_summary["revenue_per_session"] = (
    channel_summary["revenue"]
    / channel_summary["sessions"]
)

channel_summary = channel_summary.sort_values(
    "revenue",
    ascending=False,
).reset_index(drop=True)

channel_summary

مرحله نهم: محاسبه روند ماهانه

monthly = (
    df.assign(
        month=df["date"].dt.to_period("M").dt.to_timestamp()
    )
    .groupby(["month", "channel"], as_index=False)
    .agg(
        sessions=("sessions", "sum"),
        orders=("orders", "sum"),
        revenue=("revenue", "sum"),
    )
)

monthly["conversion_rate"] = (
    monthly["orders"]
    / monthly["sessions"]
)

monthly.head()

مرحله دهم: رسم نمودار تعاملی

revenue_chart = px.line(
    monthly,
    x="month",
    y="revenue",
    color="channel",
    markers=True,
    title="Monthly Revenue by Acquisition Channel",
    labels={
        "month": "Month",
        "revenue": "Revenue",
        "channel": "Channel",
    },
)

revenue_chart.update_layout(
    hovermode="x unified",
    legend_title_text="Channel",
)

revenue_chart.show()

JupyterLab از کتابخانه‌هایی مانند Matplotlib و Plotly برای نمایش نمودار پشتیبانی می‌کند. برخی خروجی‌های تعاملی ممکن است به پکیج‌های تکمیلی نیاز داشته باشند.

مرحله یازدهم: نمودار نرخ تبدیل

conversion_chart = px.bar(
    channel_summary,
    x="channel",
    y="conversion_rate",
    color="channel",
    title="Conversion Rate by Channel",
    labels={
        "channel": "Channel",
        "conversion_rate": "Conversion Rate",
    },
)

conversion_chart.update_yaxes(tickformat=".1%")
conversion_chart.update_layout(showlegend=False)

conversion_chart.show()

مرحله دوازدهم: آماده‌سازی خلاصه برای مدل هوش مصنوعی

نباید هزاران ردیف خام را بدون نیاز برای مدل ارسال کنیم. ابتدا داده را با پایتون محاسبه و خلاصه می‌کنیم؛ سپس خلاصه ساختاریافته را در اختیار مدل قرار می‌دهیم.

report_data = channel_summary.copy()

report_data["conversion_rate_percent"] = (
    report_data["conversion_rate"] * 100
).round(2)

report_data["revenue_per_session"] = (
    report_data["revenue_per_session"]
).round(2)

report_records = report_data[
    [
        "channel",
        "sessions",
        "orders",
        "revenue",
        "conversion_rate_percent",
        "revenue_per_session",
    ]
].to_dict(orient="records")

print(
    json.dumps(
        report_records,
        ensure_ascii=False,
        indent=2,
    )
)

این الگو چند مزیت دارد:

• حجم ورودی مدل کمتر می‌شود.
• محاسبات عددی به پایتون سپرده می‌شود.
• احتمال برداشت اشتباه از داده خام کاهش می‌یابد.
• هزینه مصرف توکن بهتر کنترل می‌شود.
• بررسی گزارش آسان‌تر خواهد بود.

اتصال Jupyter Notebook به API هوش مصنوعی درواره

برای استفاده از مدل‌های هوش مصنوعی در پروژه‌های پایتون می‌توانید از API درواره استفاده کنید.

درواره یک رابط سازگار با الگوی رایج OpenAI-compatible ارائه می‌دهد؛ بنابراین اتصال آن به بسیاری از کتابخانه‌ها و برنامه‌های موجود ساده است.

ابتدا در درواره ثبت‌نام و API Key خود را دریافت کنید. برای مشاهده مدل‌های قابل استفاده و قیمت به‌روز آن‌ها نیز صفحه مدل‌های درواره را ببینید.

نگهداری API Key در فایل .env

در ریشه پروژه یک فایل با نام .env بسازید:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID

کلید واقعی را مستقیماً داخل سلول Notebook قرار ندهید؛ زیرا فایل .ipynb علاوه بر کد، خروجی سلول‌ها را نیز ذخیره می‌کند و ممکن است بعداً منتشر یا برای دیگران ارسال شود.

فایل .gitignore را نیز ایجاد کنید:

.env
.venv/
.ipynb_checkpoints/
__pycache__/

بارگذاری تنظیمات

load_dotenv(project_root / ".env")

api_key = os.getenv("DARVAREH_API_KEY")
model_id = os.getenv("DARVAREH_MODEL_ID")

if not api_key:
    raise RuntimeError(
        "DARVAREH_API_KEY is not set in the .env file."
    )

if not model_id:
    raise RuntimeError(
        "DARVAREH_MODEL_ID is not set in the .env file."
    )

دقت کنید هیچ‌گاه مقدار api_key را با print() نمایش ندهید.

ساخت تابع ارسال درخواست

DARVAREH_CHAT_URL = (
    "https://api.darvareh.ir/v1/chat/completions"
)


def generate_management_report(
    records: list[dict],
) -> str:
    prompt = f"""
داده زیر خلاصه قطعی عملکرد کانال‌های فروش است:

{json.dumps(records, ensure_ascii=False, indent=2)}

یک گزارش مدیریتی فارسی تهیه کن که شامل موارد زیر باشد:
1. خلاصه وضعیت کل
2. بهترین کانال از نظر درآمد
3. بهترین کانال از نظر نرخ تبدیل
4. کانال دارای فرصت بهبود
5. سه پیشنهاد اجرایی و قابل‌اندازه‌گیری

فقط بر اساس داده ارائه‌شده نتیجه‌گیری کن.
هیچ عددی را تغییر نده و عدد جدیدی نساز.
اگر برای یک نتیجه داده کافی نیست، صریح اعلام کن.
"""

    response = requests.post(
        DARVAREH_CHAT_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "model": model_id,
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "تو یک تحلیلگر داده دقیق هستی. "
                        "بین محاسبه قطعی و تفسیر مدیریتی "
                        "تفاوت قائل شو."
                    ),
                },
                {
                    "role": "user",
                    "content": prompt,
                },
            ],
            "temperature": 0.2,
        },
        timeout=60,
    )

    try:
        response.raise_for_status()
    except requests.HTTPError as error:
        error_preview = response.text[:500]
        raise RuntimeError(
            f"Darvareh API request failed: "
            f"{response.status_code} - {error_preview}"
        ) from error

    result = response.json()

    try:
        return result["choices"][0]["message"]["content"]
    except (KeyError, IndexError, TypeError) as error:
        raise RuntimeError(
            "Unexpected response structure from the API."
        ) from error

تولید گزارش نهایی

management_report = generate_management_report(
    report_records
)

print(management_report)

در این معماری، مسئولیت‌ها از یکدیگر جدا هستند:

• Pandas محاسبات و تجمیع عددی را انجام می‌دهد.
• Plotly داده را به‌صورت بصری نمایش می‌دهد.
• مدل هوش مصنوعی نتایج محاسبه‌شده را تفسیر می‌کند.
• API درواره دسترسی برنامه‌نویسی به مدل انتخابی را فراهم می‌کند.

مدل زبانی نباید جایگزین محاسبات قابل انجام با کد شود. بهتر است عددها ابتدا به‌صورت قطعی محاسبه و فقط برای تفسیر، خلاصه‌سازی یا تولید گزارش به مدل ارسال شوند.

تبدیل کدهای تکراری به ماژول Python

Notebook برای آزمایش و تحلیل مناسب است؛ اما نباید همه منطق پروژه برای همیشه داخل سلول‌ها باقی بماند.

اگر یک تابع در چند Notebook استفاده می‌شود، آن را به فایل مستقل منتقل کنید. برای مثال، فایل زیر را بسازید:

src/reporting.py

محتوای نمونه:

import pandas as pd


def summarize_channels(
    data: pd.DataFrame,
) -> pd.DataFrame:
    required_columns = {
        "channel",
        "sessions",
        "orders",
        "revenue",
    }

    missing_columns = required_columns.difference(
        data.columns
    )

    if missing_columns:
        raise ValueError(
            f"Missing columns: {sorted(missing_columns)}"
        )

    summary = (
        data.groupby("channel", as_index=False)
        .agg(
            sessions=("sessions", "sum"),
            orders=("orders", "sum"),
            revenue=("revenue", "sum"),
        )
    )

    summary["conversion_rate"] = (
        summary["orders"] / summary["sessions"]
    )

    return summary.sort_values(
        "revenue",
        ascending=False,
    )

سپس در Notebook آن را وارد کنید:

import sys

source_directory = project_root / "src"

if str(source_directory) not in sys.path:
    sys.path.insert(0, str(source_directory))

from reporting import summarize_channels

summary = summarize_channels(df)
summary

این ساختار چند مزیت دارد:

• Notebook کوتاه‌تر و خواناتر می‌شود.
• توابع قابلیت تست پیدا می‌کنند.
• استفاده مجدد از کد آسان‌تر می‌شود.
• انتقال پروژه به API یا اپلیکیشن ساده‌تر خواهد بود.
• تغییر منطق اصلی در یک محل انجام می‌شود.

ذخیره وابستگی‌های پروژه

بعد از آزمایش نسخه پکیج‌ها می‌توانید وابستگی‌های محیط را ذخیره کنید:

python -m pip freeze > requirements.txt

برای نصب همان وابستگی‌ها در محیط جدید:

python -m pip install -r requirements.txt

فایل تولیدشده توسط pip freeze همه پکیج‌های محیط را ثبت می‌کند. برای پروژه‌های قابل نگهداری، بهتر است این فهرست را بازبینی کنید و فقط وابستگی‌های ضروری پروژه را نگه دارید.

تبدیل Notebook به HTML

برای ارسال گزارش به فردی که Jupyter نصب ندارد، می‌توانید Notebook را به HTML تبدیل کنید.

ابتدا nbconvert را نصب کنید:

python -m pip install nbconvert

سپس دستور زیر را از ریشه پروژه اجرا کنید:

jupyter nbconvert \
  --to html \
  notebooks/sales_analysis.ipynb

در Windows PowerShell می‌توانید دستور را در یک خط بنویسید:

jupyter nbconvert --to html notebooks/sales_analysis.ipynb

فایل HTML شامل متن، کد و خروجی‌های ذخیره‌شده Notebook خواهد بود. گزینه‌ها و فرمت‌های قابل تبدیل در مستندات رسمی nbconvert توضیح داده شده‌اند.

تبدیل Notebook به فایل Python

برای استخراج سلول‌های کد به یک اسکریپت Python:

jupyter nbconvert \
  --to script \
  notebooks/sales_analysis.ipynb

خروجی اولیه احتمالاً هنوز به پاک‌سازی نیاز دارد. Magic Commandها، ترتیب سلول‌ها و وابستگی به خروجی‌های تعاملی را بررسی کنید.

اجرای کامل Notebook از خط فرمان

برای بررسی اینکه Notebook از ابتدا قابل اجرا است:

jupyter nbconvert \
  --to notebook \
  --execute \
  --output sales_analysis_executed.ipynb \
  notebooks/sales_analysis.ipynb

این دستور تمام سلول‌های کد را اجرا می‌کند. آن را فقط برای Notebookهایی اجرا کنید که منبع و محتوای آن‌ها را بررسی کرده‌اید.

پاک‌کردن خروجی‌ها پیش از انتشار

فایل Notebook ممکن است شامل موارد زیر باشد:

• داده‌های شخصی یا سازمانی
• مسیر فایل‌های محلی
• متن پاسخ API
• پیام‌های خطا
• آدرس‌های داخلی
• خروجی‌های حجیم
• اطلاعاتی که به‌اشتباه چاپ شده‌اند

پیش از انتشار، خروجی‌ها را از رابط JupyterLab پاک کنید یا از دستور زیر استفاده کنید:

jupyter nbconvert \
  --clear-output \
  --inplace \
  notebooks/sales_analysis.ipynb

پس از پاک‌سازی، فایل را دوباره بازبینی کنید. حذف خروجی به‌تنهایی تضمین نمی‌کند که هیچ اطلاعات حساسی داخل کد یا Markdown باقی نمانده باشد.

استفاده مسئولانه از Notebookهای دیگران

فایل .ipynb فقط یک متن ساده آموزشی نیست؛ سلول‌های آن می‌توانند کد دلخواه اجرا کنند.

بنابراین:

• Notebook ناشناس را بلافاصله Run All نکنید.
• ابتدا تمام سلول‌های کد را بررسی کنید.
• دستورهای Shell را با دقت بخوانید.
• به عملیات فایل، شبکه و نصب پکیج توجه کنید.
• از اجرای Notebook غیرقابل اعتماد با دسترسی‌های گسترده خودداری کنید.
• خروجی‌های تعاملی فایل‌های ناشناس را بدون بررسی Trust نکنید.

JupyterLab برای خروجی‌های HTML و JavaScript نوت‌بوک‌های ساخته‌شده روی سیستم‌های دیگر سازوکار Trust دارد. بااین‌حال، Trust کردن خروجی با ایمن‌بودن کد همه سلول‌ها یکسان نیست.

آیا می‌توان Jupyter را روی اینترنت منتشر کرد؟

Jupyter Server امکان اجرای کد روی سیستم میزبان را فراهم می‌کند. بنابراین نباید یک نمونه محلی را بدون احراز هویت و پیکربندی مناسب مستقیماً در اینترنت قرار دهید.

در استفاده معمولی، JupyterLab را روی localhost نگه دارید. اگر به محیط چندکاربره یا دسترسی از راه دور نیاز دارید، از راهکارهای مدیریت‌شده و پیکربندی‌شده مانند JupyterHub یا زیرساخت دارای احراز هویت، HTTPS و کنترل دسترسی استفاده کنید.

طبق مستندات امنیت Jupyter Server، دسترسی به سرور Jupyter به معنی امکان اجرای کد است و به همین دلیل احراز هویت توکنی به‌صورت پیش‌فرض فعال می‌شود. غیرفعال‌کردن احراز هویت برای یک سرور در دسترس شبکه توصیه نمی‌شود.

بهترین روش‌های ساخت Notebook حرفه‌ای

هر Notebook یک هدف مشخص داشته باشد

نام‌هایی مانند Untitled1.ipynb یا test-final-v3.ipynb نگهداری پروژه را دشوار می‌کنند.

از نام‌های روشن استفاده کنید:

01_data_validation.ipynb
02_exploratory_analysis.ipynb
03_model_training.ipynb
04_management_report.ipynb

ورودی‌ها را در ابتدای Notebook تعریف کنید

مسیر فایل، تاریخ گزارش، تنظیمات نمودار و پارامترها را در چند سلول نخست قرار دهید.

REPORT_START_DATE = "2026-01-01"
REPORT_END_DATE = "2026-06-30"
TOP_CHANNEL_COUNT = 5

سلول‌های بسیار طولانی نسازید

هر سلول بهتر است یک وظیفه مشخص داشته باشد؛ مانند بارگذاری داده، اعتبارسنجی، تجمیع یا رسم نمودار.

محاسبه و توضیح را از هم جدا کنید

در Code Cell محاسبه را انجام دهید و در Markdown Cell هدف، فرض‌ها و نتیجه را توضیح دهید.

خروجی کامل DataFrame را نمایش ندهید

به‌جای نمایش هزاران ردیف:

df

از گزینه‌های زیر استفاده کنید:

df.head()
df.sample(5, random_state=42)
df.shape
df.describe()

هشدارها را بدون بررسی مخفی نکنید

خاموش‌کردن همه Warningها ممکن است مشکلات مهم مربوط به نوع داده، نسخه کتابخانه یا رفتار آینده را پنهان کند. ابتدا علت هشدار را بررسی کنید.

نتیجه محاسبات را به مدل زبانی نسپارید

مجموع، میانگین، نرخ تبدیل و شاخص‌های دقیق را با پایتون محاسبه کنید. از مدل هوش مصنوعی برای کارهایی مانند این موارد کمک بگیرید:

• توضیح نتیجه
• خلاصه مدیریتی
• دسته‌بندی متن
• استخراج نکات
• پیشنهاد فرضیه
• تولید روایت قابل فهم از داده

داده خام را بدون ضرورت ارسال نکنید

پیش از ارسال داده به API:

• داده را تجمیع کنید.
• ستون‌های غیرضروری را حذف کنید.
• اطلاعات حساس را حذف یا ناشناس‌سازی کنید.
• فقط داده موردنیاز برای همان درخواست را ارسال کنید.
• خروجی مدل را پیش از استفاده بررسی کنید.

Notebook را از بالا تا پایین قابل اجرا نگه دارید

یک همکار باید بتواند Kernel را Restart کرده و تمام سلول‌ها را بدون حدس‌زدن ترتیب اجرا کند.

خطاهای رایج Jupyter و راه‌حل آن‌ها

دستور jupyter شناخته نمی‌شود

خطای احتمالی:

jupyter: command not found

ابتدا مطمئن شوید محیط مجازی فعال است:

python -m pip show jupyterlab

سپس JupyterLab را نصب یا دوباره نصب کنید:

python -m pip install jupyterlab

می‌توانید اجرای مستقیم ماژول را نیز امتحان کنید:

python -m jupyterlab

پکیج نصب شده اما Import نمی‌شود

احتمالاً پکیج و Kernel به دو محیط متفاوت مربوط هستند.

داخل Notebook اجرا کنید:

import sys
print(sys.executable)

سپس در ترمینال:

python -c "import sys; print(sys.executable)"

اگر مسیرها متفاوت‌اند، Kernel صحیح را انتخاب یا محیط فعلی را با ipykernel ثبت کنید.

خطای ModuleNotFoundError

برای مثال:

ModuleNotFoundError: No module named 'plotly'

داخل Kernel فعال اجرا کنید:

%pip install plotly

بعد از نصب، در صورت نیاز Kernel را Restart کنید.

Kernel متوقف شده است

اگر یک سلول وارد حلقه طولانی شده، ابتدا از گزینه Interrupt Kernel استفاده کنید.

اگر پاسخ نداد:

Kernel → Restart Kernel

با Restart شدن Kernel، تمام متغیرهای حافظه پاک می‌شوند.

فایل CSV پیدا نمی‌شود

پوشه کاری را بررسی کنید:

from pathlib import Path

print(Path.cwd())
print(list(Path.cwd().iterdir()))

سپس مسیر را با pathlib و بر اساس ریشه پروژه بسازید.

نتیجه بعد از اجرای مجدد تغییر می‌کند

برای عملیات تصادفی Seed تعیین کنید:

rng = np.random.default_rng(42)

همچنین ورودی داده، نسخه پکیج‌ها و ترتیب سلول‌ها را ثابت نگه دارید.

Notebook بسیار کند شده است

موارد زیر را بررسی کنید:

• DataFrameهای بزرگ بدون استفاده در حافظه باقی نمانده باشند.
• خروجی‌های بسیار بزرگ نمایش داده نشده باشند.
• حلقه پایتونی غیرضروری وجود نداشته باشد.
• عملیات قابل برداری با NumPy یا Pandas جایگزین حلقه شود.
• فقط ستون‌های موردنیاز خوانده شوند.
• برای فایل‌های بزرگ از پردازش Chunk استفاده شود.
• در صورت انباشته‌شدن حافظه، Kernel Restart شود.

درخواست API با Timeout مواجه می‌شود

برای درخواست شبکه همیشه Timeout تعیین کنید:

response = requests.post(
    DARVAREH_CHAT_URL,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": model_id,
        "messages": [
            {
                "role": "user",
                "content": "سلام",
            }
        ],
    },
    timeout=60,
)

در برنامه واقعی بهتر است خطاهای موقت شبکه با Retry محدود و فاصله افزایشی مدیریت شوند. Retry بی‌نهایت می‌تواند مصرف منابع و هزینه را افزایش دهد.

چه زمانی Jupyter انتخاب مناسبی نیست؟

Jupyter برای تحلیل، یادگیری و نمونه‌سازی عالی است، اما جایگزین همه ابزارهای توسعه نرم‌افزار نیست.

برای موارد زیر بهتر است کد اصلی به فایل‌ها و ماژول‌های Python منتقل شود:

• APIهای Production
• سرویس‌های پس‌زمینه
• Workerها
• برنامه‌های زمان‌بندی‌شده
• کتابخانه‌های قابل انتشار
• پروژه‌های دارای تست گسترده
• برنامه‌های چندماژولی
• سیستم‌های نیازمند استقرار خودکار

یک الگوی مناسب این است:

1. ایده را در Notebook آزمایش کنید.
2. بخش‌های تکرارشونده را به تابع تبدیل کنید.
3. توابع را به پوشه src منتقل کنید.
4. برای منطق اصلی تست بنویسید.
5. Notebook را به لایه تحلیل و ارائه نتیجه محدود کنید.
6. سرویس نهایی را با ابزار مناسب مانند FastAPI یا Streamlit بسازید.

استفاده از Jupyter برای پروژه‌های هوش مصنوعی

Jupyter در مراحل مختلف توسعه هوش مصنوعی کاربرد دارد:

• بررسی و پاک‌سازی داده
• ساخت ویژگی‌ها
• آموزش مدل
• مقایسه معیارها
• رسم نمودارهای آموزشی
• تحلیل خطای مدل
• آزمایش پرامپت
• بررسی پاسخ API
• ارزیابی چند مدل
• آماده‌سازی مجموعه داده Evals
• ساخت نمونه اولیه RAG
• تولید گزارش از خروجی ساختاریافته

بااین‌حال، اگر پروژه از مرحله آزمایش عبور کرده است، منطق اصلی را داخل Notebook حبس نکنید. Notebook باید امکان مشاهده و توضیح فرایند را فراهم کند، نه اینکه تنها محل نگهداری کل سیستم باشد.

چک‌لیست نهایی Notebook قابل انتشار

پیش از ارسال یا انتشار یک Notebook این موارد را بررسی کنید:

• نام فایل معنی‌دار است.
• هدف Notebook در ابتدای آن توضیح داده شده است.
• وابستگی‌ها مشخص هستند.
• مسیرهای مطلق حذف شده‌اند.
• API Key داخل کد یا خروجی وجود ندارد.
• داده حساس حذف شده است.
• Kernel از ابتدا Restart شده است.
• همه سلول‌ها به ترتیب اجرا شده‌اند.
• خروجی نهایی با اجرای کامل بازتولید می‌شود.
• محاسبات عددی با کد انجام شده‌اند.
• فرض‌ها و محدودیت‌ها توضیح داده شده‌اند.
• خروجی‌های بسیار بزرگ حذف شده‌اند.
• کدهای تکراری به تابع یا ماژول منتقل شده‌اند.
• فایل .env در .gitignore قرار دارد.
• Notebook ناشناس بدون بررسی اجرا نشده است.

پرسش‌های متداول

آیا Jupyter Notebook رایگان است؟

بله. پروژه Jupyter متن‌باز است و می‌توانید Jupyter Notebook یا JupyterLab را روی سیستم خود نصب کنید. هزینه احتمالی به زیرساخت، سرور، پکیج‌های تجاری یا APIهایی مربوط می‌شود که در پروژه استفاده می‌کنید.

JupyterLab بهتر است یا Jupyter Notebook؟

برای بیشتر پروژه‌های جدید، JupyterLab محیط کامل‌تری است. این ابزار علاوه بر اجرای Notebook، فایل‌منیجر، Terminal، ویرایشگر متن و امکان مدیریت چند سند را ارائه می‌دهد.

آیا Jupyter بدون اینترنت کار می‌کند؟

بله. پس از نصب پکیج‌های موردنیاز، اجرای محلی Jupyter به اینترنت وابسته نیست. درخواست به API، نصب پکیج یا دریافت داده آنلاین همچنان به اتصال شبکه نیاز دارد.

آیا می‌توان Jupyter را داخل VS Code اجرا کرد؟

بله. VS Code با افزونه‌های Python و Jupyter می‌تواند فایل‌های .ipynb را باز و اجرا کند. همچنان باید Kernel و محیط پایتون صحیح را انتخاب کنید.

چرا کد در ترمینال کار می‌کند ولی در Jupyter خطا می‌دهد؟

رایج‌ترین علت، متفاوت‌بودن Python Interpreter ترمینال و Kernel نوت‌بوک است. مسیر sys.executable را در هر دو محیط مقایسه کنید.

آیا می‌توان از Jupyter برای یادگیری ماشین استفاده کرد؟

بله. کتابخانه‌هایی مانند Scikit-learn، TensorFlow و PyTorch در Jupyter قابل استفاده هستند. بهتر است آموزش‌های سنگین، مدیریت داده و ذخیره مدل را به‌صورت ساختاریافته انجام دهید و فقط به وضعیت حافظه Notebook وابسته نباشید.

آیا می‌توان Jupyter را به API هوش مصنوعی متصل کرد؟

بله. با کتابخانه‌هایی مانند requests یا SDK سازگار می‌توانید از داخل Notebook درخواست API ارسال کنید. در این آموزش اتصال به endpoint زیر انجام شد:

https://api.darvareh.ir/v1/chat/completions

چگونه مدل مناسب درواره را انتخاب کنیم؟

Model ID و قیمت مدل‌ها ممکن است تغییر کند. برای مشاهده گزینه‌های موجود و انتخاب مدل متناسب با بودجه، سرعت و کیفیت موردنیاز، صفحه مدل‌های درواره را بررسی کنید.

جمع‌بندی

Jupyter Notebook فقط یک محیط ساده برای اجرای چند خط کد نیست. اگر اصولی استفاده شود، می‌تواند یک محیط قدرتمند برای تحلیل داده، مستندسازی آزمایش، آموزش پایتون و ساخت نمونه اولیه پروژه‌های هوش مصنوعی باشد.

مهم‌ترین نکات این آموزش عبارت‌اند از:

• JupyterLab را داخل محیط مجازی نصب کنید.
• Kernel صحیح پروژه را انتخاب کنید.
• سلول‌ها را از بالا به پایین قابل اجرا نگه دارید.
• مسیر فایل‌ها را به‌صورت نسبی مدیریت کنید.
• محاسبات عددی را با پایتون انجام دهید.
• فقط خلاصه ضروری داده را برای مدل ارسال کنید.
• API Key را در .env نگه دارید.
• پیش از انتشار، کد و خروجی Notebook را بازبینی کنید.
• منطق قابل استفاده مجدد را به ماژول‌های Python منتقل کنید.
• Notebook را ابزار تحلیل و مستندسازی بدانید، نه جایگزین کامل معماری نرم‌افزار.

برای اجرای پروژه‌های هوش مصنوعی از داخل Jupyter، می‌توانید در درواره حساب بسازید، API Key دریافت کنید و مدل مناسب پروژه خود را از صفحه مدل‌ها و قیمت‌ها انتخاب کنید.

منابع رسمی

• راهنمای نصب Jupyter
• مستندات نصب JupyterLab
• راهنمای Notebook در JupyterLab
• مستندات امنیت Jupyter Server
• مستندات nbconvert

مقالات مرتبط

• آموزش Google Colab برای هوش مصنوعی و API درواره
• آموزش هوش مصنوعی با پایتون؛ ساخت پروژه واقعی با API
• آموزش Pandas با پایتون؛ تحلیل و پاک‌سازی داده از صفر
• Scikit-learn چیست؟ آموزش کامل Machine Learning با پایتون
• آموزش Streamlit؛ ساخت اپلیکیشن هوش مصنوعی با پایتون
• تحلیل فایل CSV با هوش مصنوعی

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.