Workshop Labs Setup Guide
本指南帮助您在开始实验前设置开发环境。
前置要求
-
macOS, Linux, 或 Windows with WSL
-
Git
-
终端/命令行
-
Python 版本：3.10～3.12
-
百炼 API Key
1. 安装 UV (Python 包管理器)
UV 是一个快速的 Python 包管理器，同时处理 Python 安装和依赖管理。
安装 UV
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后，重启终端或运行：
source $HOME/.local/bin/env # macOS/Linux
验证安装：
uv --version
2. 设置 Python 环境
进入 workshop 目录并同步依赖：
cd workshop
# 这将安装 Python（如需要）和所有依赖
uv sync
UV 将自动：
-
安装正确的 Python 版本
-
创建虚拟环境
-
安装所有必需的包
3. LazyLLM 安装与配置
环境需求
-
Python 版本：3.10～3.12
-
Jupyter Notebook / Jupyter Lab
-
百炼 API Key
主要依赖：
lazyllm >= 0.7.5
pandas
seekmem
jupyterlab
安装 LazyLLM
一键安装（推荐使用清华镜像）：
pip3 install lazyllm==0.7.5 -i https://pypi.tuna.tsinghua.edu.cn/simple
验证百炼 API Key
在 Python 或 Jupyter 中运行，将 sk-xxx 替换为您的百炼 API Key：
from lazyllm import OnlineModule
api_key = 'sk-xxx'
m = OnlineModule(source='qwen', type='llm', api_key=api_key)
print(m('Hello'))
若正常返回模型回复，说明 API Key 可用。
4. OceanBase/seekdb 的安装部署
桌面版
软件包下载：https://www.oceanbase.com/softwarecenter （选择OceanBase桌面版一键部署安装包）
linux 版本
安装参考文档：OceanBase 社区
5. 启动 Jupyter Lab 
Jupyter Lab 是本工作坊的主要演示和实验环境。
启动方式
cd workshop
uv run jupyter lab
启动后
-
浏览器将自动打开 Jupyter Lab 界面
-
如果没有自动打开，复制终端中显示的 URL（类似
http://localhost:8888/lab?token=xxx） -
在左侧文件浏览器中，导航到
labs/文件夹 -
双击打开实验 notebook（
.ipynb文件）
Jupyter Lab 界面说明
常用快捷键
| 快捷键 | 功能描述 | 使用场景 |
|---|---|---|
| Shift + Enter | 运行当前 Cell，并选中/跳到下一个 Cell | 最常用的组合，用于顺序执行代码。 |
| Ctrl + Enter | 运行当前 Cell，光标停留在当前 Cell | 用于反复调试某一段代码，无需跳转。 |
| Esc + A | 在上方插入新 Cell (Above) | 需要在当前代码前补充定义或注释时。 |
| Esc + B | 在下方插入新 Cell (Below) | 需要在当前代码后继续编写逻辑时。 |
| Esc + D, D | 删除当前 Cell (需连续按两次 D) | 快速清理无用代码块（防止误删设计）。 |
验证清单 
开始实验前，请验证：
-
[ ]
uv --version显示版本号 -
[ ]
uv sync无错误完成 -
[ ]
.env文件包含您的 LangSmith API Key -
[ ] LazyLLM 已安装且百炼 API Key 测试通过（如使用 LazyLLM Workshop）
-
[ ] Jupyter Lab 正常启动并在浏览器中打开
常见问题
UV 安装后找不到命令
source $HOME/.local/bin/env
# 或添加到 shell 配置文件 (.bashrc, .zshrc)
macOS 权限错误
xattr -d com.apple.quarantine $(which uv)
Jupyter Lab 无法启动
-
确保在
workshop/目录下运行 -
尝试指定端口：
uv run jupyter lab --port=8889 -
检查是否有其他 Jupyter 实例占用端口
快速参考
| 命令 | 详细说明 | 等价的传统操作 (参考) |
|---|---|---|
uv sync |
同步环境。 1. 读取 pyproject.toml 和 uv.lock 文件。2. 自动创建虚拟环境（如果不存在）。 3. 安装/更新所有依赖项到精确锁定的版本。 特点：无需手动激活环境 ( source .venv/bin/activate)，它确保你的环境与锁定文件完全一致。 |
python -m venv .venv pip install -r requirements.txt
|
uv run jupyter lab |
在隔离环境中运行命令。 自动识别当前项目的虚拟环境，并在该环境中启动 Jupyter Lab。即使你没有手动激活虚拟环境，它也能确保 Jupyter 使用的是项目指定的 Python 版本和依赖包。 |
source .venv/bin/activate jupyter lab
|
uv run python <script> |
运行脚本。 同上，它会在项目的虚拟环境中执行 Python 脚本。这对于确保脚本使用的库版本与开发环境一致至关重要。 |
source .venv/bin/activate python script.py
|