openvinotoolkit/openvino_notebooks · 上手攻略

  • 仓库：openvinotoolkit/openvino_notebooks
  • 链接：https://github.com/openvinotoolkit/openvino_notebooks
  • 分类：llm-infra / tutorial（OpenVINO 官方 Jupyter 教程集）
  • 作者：spark
  • 更新：2026-07-30

提示：上游仓库标识写作 openvinotoolkit/openvino_notebooks（带下划线），按本攻略规则计算的文件 slug 为 openvinotoolkit-openvino-notebooks.md。下文中如出现"OpenVINO 2026.2"等版本号，均来自仓库当前 README，未在外部二次确认。

1. 是什么

openvino_notebooks 是 Intel 维护的 OpenVINO™ 官方 Jupyter 教程集合，本身不是 SDK 也不是一个完整框架。它把 OpenVINO 在各种任务上的端到端用法拆成一个个独立的 notebook，覆盖传统 CV、Transformer、LLM 量化、检索增强生成、语音、生成式 AI、多模态等场景，几乎所有"你想用 OpenVINO 干 X，先看这个 notebook"的需求都能在这里找到参考实现。它与 OpenVINO 主仓库（openvinotoolkit/openvino）和 openvino.genai 仓库是配套关系：核心 C++/Python 引擎在主仓库，LLM/GenAI 高级 API 在 openvino.genai，这一仓库则是"用法教科书"。

2. 解决什么问题

直接读 OpenVINO C++/Python API 文档门槛偏高；用户希望快速看到完整可跑的端到端 demo：

  • 把一个 PyTorch / Transformers 模型（YOLO、CLIP、Segment Anything、LLM、Whisper、SD…）转成 OpenVINO IR（.xml + .bin）。
  • 在 CPU / iGPU / NPU / 独立 GPU 上做 INT8 / FP16 量化、剪枝、蒸馏。
  • 跑一次完整推理并可视化结果（检测框、分割 mask、生成文本等）。
  • 接入 OpenVINO Tokenizers、OpenVINO GenAI 等高层 API，做 RAG、聊天、图像生成视频。

如果只想要 IR 转换工具本身，请直接用 openvino Python 包；如果想用高层 chat completions API，请去 openvino.genai；想"边学边抄代码"，来这里。

3. 快速安装

依赖：Python 3.10–3.13（64-bit）、Git、操作系统为 Ubuntu 20.04+/22.04、RHEL 8、CentOS 7、macOS 10.15+、Windows 10 Pro/Enterprise 或 Windows Server 2016+。README 主分支已对齐 OpenVINO 2026.2（不另行核实具体小版本）。

# 克隆到本地
git clone https://github.com/openvinotoolkit/openvino_notebooks.git
cd openvino_notebooks

# 推荐建立虚拟环境（README 称之为 openvino_env）
python -m venv openvino_env
source openvino_env/bin/activate            # Linux/macOS
# openvino_env\Scripts\activate             # Windows cmd

# 升级依赖到 OpenVINO 2026.2
pip install --upgrade -r requirements.txt

如果第一次安装，按官方说法应阅读仓库的 Installation Guide 节；如需 LTS 老版本，请切到 2023.3 分支；要 2026.1 旧稳定版，切 2026.1 分支并保留老 requirements.txt。

不需要本地 GPU 也能跑绝大多数 notebook（OpenVINO CPU 后端足够），但有 iGPU/独立 GPU/NPU 时需要安装对应驱动和 openvino-dev 对应后端扩展。

校验：

python check_install.py     # 仓库自带工具，激活 openvino_env 后在仓库根目录执行

4. 核心用法

4.1 浏览所有 notebook 的官方目录页

https://openvinotoolkit.github.io/openvino_notebooks/

这是带筛选条件的 gallery 页，按任务分类（Vision / LLM / RAG / Multimodal / Audio / GenAI…）列出全部 notebook，可以挑感兴趣的点开仓库里对应子目录。

4.2 启动 Jupyter Lab / Notebook

# 启动后用左侧栏浏览 notebooks/ 目录，或打开 README 作为目录索引
jupyter lab notebooks/README.md

# 只想跑某一个 notebook（README 例子：Monodepth 深度估计）
jupyter lab notebooks/vision-monodepth/vision-monodepth.ipynb

支持 Windows / macOS / Linux / Docker，也可在 Binder、Google Colab 上免费跑（受限资源，性能有限）。每个 notebook 顶部通常需要 pip install 它额外声明的依赖，再"Restart Kernel + Run All"。

4.3 一个典型 notebook（以图像分类 + OpenVINO IR 转换为例）

仓库里的 LLM / RAG / YOLO / SAM / Stable Diffusion 等 notebook 都遵循同一个最小模式：

# ① 加载原始 PyTorch / HF 模型
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("some-org/some-model")

# ② 转成 OpenVINO IR（FP16）
from openvino import convert_model, compile_model
ov_model = convert_model(model, example_input=...)
# 保存为 .xml / .bin（也可直接用 compile_model 跑在内存里）
compiled = compile_model(ov_model, device_name="CPU")   # 也可 "GPU" / "NPU"

# ③ 推理
outputs = compiled({"input_ids": input_ids})["logits"]

不同 notebook 在量化阶段会用 nncf.quantize（NNCF）做 INT8 权重量化或训练感知量化（PTQ/QAT），跑过量化后会再次 compile_model 并对比延迟与精度。LLM 教程通常还会接入 openvino_genai 的 LLMPipeline 给 chat completions 用。

4.4 遥测

notebook 中有 collect_telemetry() 调用会经 Scarf 上报匿名使用数据（仅"这个 cell 被执行"），介意可以：

export SCARF_NO_ANALYTICS=1    # 或 DO_NOT_TRACK=1

或注释掉对应 cell。

5. 典型适用场景

  • 模型迁移评估：手上有 PyTorch/ONNX/TF 模型，想知道 OpenVINO 在自家 CPU/NPU 上的延迟/精度收益 → 找对应任务（检测/分割/语音/LLM）的"convert + benchmark" notebook 改改路径即可。
  • 入门 OpenVINO GenAI：本仓库多个 RAG / 文生图 / 多模态 notebook 直接调用 openvino_genai 的 LLMPipeline / Text2ImagePipeline，比读 GenAI 仓库的 API 友好得多。
  • 学习 NNCF 量化：notebooks/quantization-* 一系列覆盖 PTQ、权重压缩、混合精度、数据集无关量化。
  • 教学/分享：可以裁剪某个 notebook 当作内部分享模板（Markdown 解释 + 可跑代码 + 实时图）。

不太适合：纯服务端高吞吐生产部署——这种应该直接拉 openvino.genai 或自建服务；也不适合需要"非 Python 栈"的人（C++ 用例请看 openvino 主仓库 samples）。

6. 坑与注意

  • kernel 选错会 ImportError：装好后一定要在 Jupyter 里选 openvino_env 这个 kernel，否则 import openvino 会失败；可执行 jupyter kernelspec remove openvino_env 清掉旧 kernel 后再装一次。
  • Windows 安装建议用 cmd.exe，PowerShell 里某些激活脚本行为差异会导致报错。
  • 不要在已经 source setupvars.sh/.bat 的终端里再 pip install——OpenVINO 全局安装和虚拟环境会冲突。
  • notebook_utils 旧版本会出现 ImportError: cannot import name 'collect_telemetry'：删除子目录里残留的旧 notebook_utils.py 再重跑即可。
  • Colab/Binder 资源有限：大模型（≥7B）会 OOM，建议本地或带 GPU 的 VM。
  • 版本切换时记得 pip install --upgrade -r requirements.txt，否则不同分支的 notebook 互相混用极易报 API/属性错误。

7. 与同类对比

  • vs ultralytics/ultralytics：Ultralytics 只覆盖 YOLO 系，目标单一但一站式（训练+导出+推理），本仓库更"百科全书"，覆盖 YOLO/CLIP/SAM/SD/LLM/ASR 多家模型。
  • vs open-mmlab/mmagic 或 HuggingFace transformers 的示例：那些示例通常以 PyTorch 原生推理为主；本仓库价值在于"走通 OpenVINO 整条转换-量化-推理链路"。
  • vs openvino.genai 的 samples：openvino.genai 仓库聚焦高层 API（LLMPipeline、Text2ImagePipeline、EmbeddingsPipeline），教程更简短；本仓库 notebook 会先讲底层 IR 转换和量化，再展示高层 API，适合"想理解清楚发生了什么"的读者。
  • vs 上层 RAG 框架（如 HKUDS/LightRAG、infiniflow/ragflow）：那些是"开箱即用的产品"，本仓库更偏"用 OpenVINO 自定义一条 RAG 流水线"的参考实现。

8. 一句话结论

如果你打算用 OpenVINO，先 clone 这个仓库跑一两个 notebook 验证环境，比直接读主仓库 API 文档效率高 10 倍；如果你只想用高层 chat/vision API、不想关心 IR，绕道 openvino.genai 或托管服务更省心。