阶段 4: AI 增强版本
代码地址：prevailna/04-jupyterhub-ai-enhanced at prevailna · prevailna/project-1-jupyter
项目说明
基于 Docker 部署 JupyterHub，集成多种 AI 工具和模型，支持 AI 辅助编程和数据分析。本阶段构建了一个高级 JupyterHub 环境，通过多种 AI 模型（包括国际和国内）的接入，为用户提供 AI 辅助编程、数据分析、文档生成等功能。
- 多 AI 模型支持:
- 本地：Ollama 部署本地模型（DeepSeek-R1, Qwen 3, Llama 3.3, Qwen 2.5‑VL, Gemma 3 等）
- 云端：OpenAI、Anthropic、阿里云通义千问、DeepSeek
- PostgreSQL 数据存储: 高性能、可靠的用户数据和会话管理
- GitHub OAuth 认证: 安全的用户身份验证和权限管理
- 多种用户环境: Base、SciPy、DataScience 镜像选择
- 完整管理工具: 启动、停止、监控、备份、健康检查脚本
- 固定网络配置: 稳定的容器间通信 (172.18.0.0/16)
- 简化 AI 集成: 直接在 Notebook 中使用魔法命令
- 资源管理: 实现容器资源限制和管理，确保系统稳定运行
- 数据持久化: 用户数据和配置持久化存储，支持备份恢复
- 多阶段构建: 使用 Docker 多阶段构建优化镜像大小和构建速度
国内用户特别说明
为了解决国内用户可能面临的网络问题，本项目提供了以下替代方案：
- 使用国内 AI 模型（阿里云通义千问、DeepSeek）替代国际模型
- 使用 Ollama 部署本地模型，文档：Jupyterhub + Ollama
.env文件中使用代理配置：AI_PROXY_URL=http://your.proxy.url
目录结构
bash
./04-jupyterhub-ai-enhanced
├── config/
│ ├── jupyterhub_config.py # JupyterHub 主配置
│ └── postgres/ # PostgreSQL 配置
│ └── init.sql
├── jupyter/ # Docker 镜像构建文件
├── notebooks/ # AI 示例笔记本
├── scripts/
│ ├── start.sh
│ ├── stop.sh
│ ├── restart.sh
│ ├── health.sh
│ ├── logs.sh
│ ├── backup.sh
│ └── migrate-to-postgres.py
├── docker-compose.yml
├── Makefile
├── .env.example # 环境变量示例
├── .env
└── README.md快速开始
环境准备
bash
# 复制环境变量配置
cp .env.example .env配置环境变量
编辑 .env 文件，配置必要的参数：
bash
# GitHub OAuth 配置（必需）
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
OAUTH_CALLBACK_URL=http://localhost:8000/hub/oauth_callback
GITHUB_ADMIN_USERS=your_github_username
GITHUB_WHITELIST_USERS=
# PostgreSQL 数据库配置
POSTGRES_DB=jupyterhub
POSTGRES_USER=jupyterhub
POSTGRES_PASSWORD=your_secure_postgres_password
# Ollama 配置（本地 AI 模型）
OLLAMA_API_BASE=http://172.18.0.1:11434
OLLAMA_HOST=http://172.18.0.1:11434
# 云端 AI 模型配置
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
ALIYUN_API_KEY=your_aliyun_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key启动服务
方式一：使用脚本
bash
# 启动服务
./scripts/start.sh
# 查看状态
./scripts/health.sh
# 查看日志
./scripts/logs.sh --follow方式二：使用 Makefile
bash
# 一键启动
make all
# 或分步启动
make build # 构建镜像
make up # 启动服务访问服务
启动成功后，可以通过 http://localhost:8000 访问 JupyterHub。
使用 GitHub 账号登录 JupyterHub。
AI 功能使用
在 Notebook 中使用 AI
本项目采用了最新的 Jupyter AI 配置方式，无需复杂的全局配置文件。
加载 Jupyter AI 扩展
在 Notebook 中运行：
python
import os
%load_ext jupyter_ai_magics使用 AI 功能
在 Jupyter 笔记本中，可以通过以下方式使用 AI 功能：
使用
%%ai魔法命令与 AI 模型交互：python%%ai 请用 Python 编写一个函数，实现快速排序算法。指定特定的 AI 模型：
python%%ai gpt-4 请分析深度学习与传统机器学习的区别。python%%ai claude-3-opus-20240229 请解释量子计算的基本原理。python%%ai qwen-plus 请用中文介绍中国的人工智能发展现状。使用 Python API 调用 AI 模型：
pythonfrom jupyter_ai.chat import Chat # 创建聊天实例 chat = Chat() # 发送消息并获取回复 response = chat.send("请用 Python 代码实现一个简单的线性回归算法") print(response)
AI 示例笔记本
项目提供了丰富的示例笔记本，帮助用户快速上手：
- 00-Ollama 本地模型.ipynb: 演示如何使用 Ollama 本地模型
- 01-AI 助手入门.ipynb: 介绍如何使用 Jupyter AI 扩展与各种 AI 模型交互
- 02-AI 代码生成.ipynb: 演示如何使用 AI 生成各种编程语言的代码
- 03-AI 辅助数据分析.ipynb: 展示如何使用 AI 辅助数据分析的各个阶段
- 04-AI 代码助手.ipynb: 演示如何使用 AI 辅助编程，包括代码生成、解释、优化和调试
- 05-AI 辅助文档生成.ipynb: 展示如何使用 AI 生成各种类型的文档
故障排除
常见问题
GitHub 认证失败
bash# 检查配置 grep GITHUB .env # 验证回调 URL curl -I http://localhost:8000/hub/oauth_callbackPostgreSQL 连接失败
bash# 检查数据库状态 ./scripts/health.sh --postgres # 进入数据库终端 make postgres-shellOllama 连接异常
bash# 测试 Ollama 连接 curl http://172.18.0.1:11434/api/tags # 检查模型列表 ollama list用户容器启动失败
bash# 查看用户容器日志 ./scripts/logs.sh user # 检查资源使用 docker stats