Back to Details

academic-jupyter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Academic Jupyter — Notebook Management

学术Jupyter——笔记本管理

Overview

概述

A headless Jupyter Server runs at 
http://localhost:8888
inside the container. Use its REST API and kernel WebSocket protocol to create notebooks, manage kernels, and execute code cells. The Jupyter token is in 
$JUPYTER_TOKEN
.
容器内的无头Jupyter Server运行在
http://localhost:8888
。使用其REST API和内核WebSocket协议来创建笔记本、管理内核并执行代码单元格。Jupyter令牌存储在
$JUPYTER_TOKEN
环境变量中。

When To Use

使用场景

  • User asks to create or run a Jupyter notebook
  • User wants an interactive computing session with persistent state
  • User needs to execute multi-step data analysis with shared variables
  • User asks for a notebook-style workflow (code → output → iterate)
  • 用户要求创建或运行Jupyter笔记本
  • 用户需要带有持久化状态的交互式计算会话
  • 用户需要执行多步骤数据分析并共享变量
  • 用户要求采用笔记本风格的工作流（代码→输出→迭代）

Authentication

身份验证

All requests require the token:
bash
undefined
所有请求都需要令牌：
bash
undefined

Token is available as environment variable

令牌可通过环境变量获取

echo $JUPYTER_TOKEN
echo $JUPYTER_TOKEN

Use in requests:

在请求中使用令牌：

curl -sf "http://localhost:8888/api/status?token=$JUPYTER_TOKEN" | jq .
undefined
curl -sf "http://localhost:8888/api/status?token=$JUPYTER_TOKEN" | jq .
undefined

Kernel Management

内核管理

List running kernels

列出运行中的内核

bash
curl -sf "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN" | jq .
bash
curl -sf "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN" | jq .

Start a new kernel

启动新内核

bash
curl -sf -X POST "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "python3"}' | jq .
bash
curl -sf -X POST "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "python3"}' | jq .

→ {"id": "<kernel-id>", "name": "python3", "state": "starting", ...}

→ {"id": "<kernel-id>", "name": "python3", "state": "starting", ...}

undefined
undefined

Restart a kernel (clears state)

重启内核（清除状态）

bash
curl -sf -X POST "http://localhost:8888/api/kernels/<kernel-id>/restart?token=$JUPYTER_TOKEN" | jq .
bash
curl -sf -X POST "http://localhost:8888/api/kernels/<kernel-id>/restart?token=$JUPYTER_TOKEN" | jq .

Shutdown a kernel

关闭内核

bash
curl -sf -X DELETE "http://localhost:8888/api/kernels/<kernel-id>?token=$JUPYTER_TOKEN"
bash
curl -sf -X DELETE "http://localhost:8888/api/kernels/<kernel-id>?token=$JUPYTER_TOKEN"

Notebook File Management (Contents API)

笔记本文件管理（Contents API）

List notebooks

列出笔记本

bash
curl -sf "http://localhost:8888/api/contents/notebooks?token=$JUPYTER_TOKEN" | jq '.content[] | {name, path, type}'
bash
curl -sf "http://localhost:8888/api/contents/notebooks?token=$JUPYTER_TOKEN" | jq '.content[] | {name, path, type}'

Create a new notebook

创建新笔记本

bash
curl -sf -X PUT "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "notebook",
    "content": {
      "cells": [
        {
          "cell_type": "markdown",
          "source": "# Analysis Notebook\nCreated by Prismer Academic Assistant.",
          "metadata": {}
        },
        {
          "cell_type": "code",
          "source": "import numpy as np\nimport matplotlib.pyplot as plt\nprint(\"Ready!\")",
          "metadata": {},
          "outputs": [],
          "execution_count": null
        }
      ],
      "metadata": {
        "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
        "language_info": {"name": "python", "version": "3.12.3"}
      },
      "nbformat": 4,
      "nbformat_minor": 5
    }
  }' | jq '{name, path, created}'
bash
curl -sf -X PUT "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "notebook",
    "content": {
      "cells": [
        {
          "cell_type": "markdown",
          "source": "# Analysis Notebook\nCreated by Prismer Academic Assistant.",
          "metadata": {}
        },
        {
          "cell_type": "code",
          "source": "import numpy as np\nimport matplotlib.pyplot as plt\nprint(\"Ready!\")",
          "metadata": {},
          "outputs": [],
          "execution_count": null
        }
      ],
      "metadata": {
        "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
        "language_info": {"name": "python", "version": "3.12.3"}
      },
      "nbformat": 4,
      "nbformat_minor": 5
    }
  }' | jq '{name, path, created}'

Read a notebook

读取笔记本

bash
curl -sf "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN" | jq .
bash
curl -sf "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN" | jq .

Delete a notebook

删除笔记本

bash
curl -sf -X DELETE "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN"
bash
curl -sf -X DELETE "http://localhost:8888/api/contents/notebooks/analysis.ipynb?token=$JUPYTER_TOKEN"

Execute Code in a Kernel

在内核中执行代码

For executing code, use the Jupyter kernel's execute endpoint. The simplest approach: write code to a 
.py
file and run it, or use the REST API to execute within a kernel session.
要执行代码，请使用Jupyter内核的执行端点。最简单的方法是将代码写入
.py
文件并运行，或者使用REST API在内核会话中执行代码。

Quick execution via file

通过文件快速执行

bash
undefined
bash
undefined

Write a cell's code to temp file and execute

将单元格代码写入临时文件并执行

cat > /tmp/cell.py << 'PYTHON' import numpy as np x = np.random.randn(1000) print(f"Mean: {x.mean():.4f}, Std: {x.std():.4f}") PYTHON
python3 /tmp/cell.py
undefined
cat > /tmp/cell.py << 'PYTHON' import numpy as np x = np.random.randn(1000) print(f"Mean: {x.mean():.4f}, Std: {x.std():.4f}") PYTHON
python3 /tmp/cell.py
undefined

For persistent state across cells

用于跨单元格的持久化状态

When the user needs variables to persist between executions (true notebook experience), start a kernel and use the Jupyter execute API:
bash
undefined
当用户需要变量在多次执行之间保持持久（真正的笔记本体验）时，请启动一个内核并使用Jupyter执行API：
bash
undefined

1. Start kernel

1. 启动内核

KERNEL_ID=$(curl -sf -X POST "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN"
-H "Content-Type: application/json" -d '{"name":"python3"}' | jq -r '.id')
KERNEL_ID=$(curl -sf -X POST "http://localhost:8888/api/kernels?token=$JUPYTER_TOKEN"
-H "Content-Type: application/json" -d '{"name":"python3"}' | jq -r '.id')

2. Execute code via the kernel (uses WebSocket internally)

2. 通过内核执行代码（内部使用WebSocket）

For simple cases, write the notebook with cells and outputs.

对于简单场景，编写包含单元格和输出的笔记本。

For complex interactive sessions, guide the user to open Jupyter in browser.

对于复杂的交互式会话，引导用户在浏览器中打开Jupyter。

undefined
undefined

API Reference

API参考

EndpointMethodPurpose
/api/status
GETServer status
/api/kernels
GETList kernels
/api/kernels
POSTStart kernel (
{"name":"python3"}
)
/api/kernels/<id>
DELETEShutdown kernel
/api/kernels/<id>/restart
POSTRestart kernel
/api/contents/<path>
GETRead file/notebook
/api/contents/<path>
PUTCreate/update file/notebook
/api/contents/<path>
DELETEDelete file/notebook
All endpoints require 
?token=$JUPYTER_TOKEN
query parameter.
端点方法用途
/api/status
GET服务器状态
/api/kernels
GET列出内核
/api/kernels
POST启动内核（
{"name":"python3"}
）
/api/kernels/<id>
DELETE关闭内核
/api/kernels/<id>/restart
POST重启内核
/api/contents/<path>
GET读取文件/笔记本
/api/contents/<path>
PUT创建/更新文件/笔记本
/api/contents/<path>
DELETE删除文件/笔记本
所有端点都需要
?token=$JUPYTER_TOKEN
查询参数。

Notebook Storage

笔记本存储

  • Default notebook directory: 
    /workspace/notebooks/
  • The Jupyter server serves files from 
    /workspace/
  • Save notebooks to 
    /workspace/notebooks/<name>.ipynb
  • 默认笔记本目录：
    /workspace/notebooks/
  • Jupyter服务器从
    /workspace/
    提供文件服务
  • 将笔记本保存到
    /workspace/notebooks/<name>.ipynb

Tips

提示

  • For simple one-off computations, use 
    python3
    directly (academic-python skill).
  • Use Jupyter when the user needs persistent state across multiple code executions.
  • Always include 
    matplotlib.use('Agg')
    in visualization cells.
  • Kernel state is lost on restart — save important results to files.
  • The web frontend may have a Notebook Viewer for rendering 
    .ipynb
    files.
  • 对于简单的一次性计算，直接使用
    python3
    （academic-python技能）。
  • 当用户需要跨多次代码执行的持久化状态时，使用Jupyter。
  • 在可视化单元格中始终包含
    matplotlib.use('Agg')
    。
  • 重启内核会丢失状态——将重要结果保存到文件中。
  • Web前端可能有用于渲染
    .ipynb
    文件的笔记本查看器。