Open Notebook：把数据、模型、集成三件事还给你的自托管 NotebookLM

NotebookLM 证明了一件事：把资料收进一个笔记本、让 AI 基于资料问答和生成播客，是真实需求。但它有三处硬约束——资料只能在 Google 云、模型只能用 Google 的、没有 API。Open Notebook（lfnovo/open-notebook）做的事就是把这三件事还给你：自托管所以数据在你机器上，接 18+ 家模型供应商所以可以随时换，REST API + MCP 所以能接进自己的工作流。代价是你自己管 Docker、数据库和备份。

边界同样清楚。官方 VISION.md 的 IS NOT 清单写明：它不是文档编辑器，不是文件存储系统，不是通用聊天机器人，今天也不是多用户产品——VISION 的当前姿态一节原话是 “Open Notebook is a single-user tool today”。想清楚你要的是"可控的研究底座"还是"开箱即用的协作产品"，再往下读。

项目坐标

数据来源：GitHub REST API（2026-09-30）、仓库 frontend/package.json、Releases。模型接入由作者开源的 esperanto 库统一封装，Open Notebook 自己只做调用层和上层工作流——这也是它敢承诺"换 Provider 不改上层"的原因。

原版文章基于 2026-06-12 的仓库状态写成；6 月到 9 月间项目连发 v1.9.0 到 v1.14.0 六个版本，其中 v1.13.0（Content Core 2.0）重构了整条素材处理链，本文按 2026-09-30 口径重写。

系统地图：一条内容链，四类出口

Open Notebook 的结构可以画成一条链：素材从入口进来，经内容处理引擎解析、分块、向量化，落进一份 SurrealDB 存储，再供四类功能消费。所有能力都同时暴露给 UI 和 REST API——这是官方写进设计原则的（ADR-003：“Every capability is accessible via the REST API — the UI is a client, never the only door”）。

先记住这个分工，后面每个部分都是在展开这条链上的一段。

快速开始

官方口径是 2 分钟三步：拿 docker-compose.yml、改一个加密密钥、docker compose up -d。前置条件只有 Docker Desktop——API Key 不用提前准备，启动后在 UI 里配。

curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml
# 编辑 docker-compose.yml，把 OPEN_NOTEBOOK_ENCRYPTION_KEY 改成自己的随机字符串
docker compose up -d

等 15-20 秒，两个地址：

• Web UI：http://localhost:8502（Next.js 前端）
• REST API 文档：http://localhost:5055/docs（FastAPI 自动生成的 OpenAPI 页面）

官方 compose 里有几处值得照抄的细节（2026-09-30 版）：

services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    command: ["start", "--log", "info", "--user", "${SURREAL_USER:-root}", "--pass", "${SURREAL_PASSWORD:-root}", "rocksdb:/mydata/mydatabase.db"]
    user: root
    ports:
      - "127.0.0.1:8000:8000"   # 只绑 localhost：SurrealDB 默认 root:root 凭证，绑 0.0.0.0 等于向局域网开门
    volumes:
      - ./surreal_data:/mydata
    environment:
      - SURREAL_EXPERIMENTAL_GRAPHQL=true
    restart: always

  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    ports:
      - "8502:8502"   # Web UI
      - "5055:5055"   # REST API
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string   # 必须改
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=${SURREAL_USER:-root}
      - SURREAL_PASSWORD=${SURREAL_PASSWORD:-root}
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
      # 可选：OPEN_NOTEBOOK_ENABLE_DOCLING=true 开启 OCR 文档引擎（首次启动拉取大型 ML 依赖）
      # 可选：OPEN_NOTEBOOK_ENABLE_CRAWL4AI=true 开启本地 JS 渲染引擎
      # 可选：OPEN_NOTEBOOK_WORKER_MAX_TASKS=1（默认 5）——单卡/本地模型建议串行
    volumes:
      - ./notebook_data:/app/data
    depends_on:
      - surrealdb
    restart: always

两个容易忽略的口令：

1. OPEN_NOTEBOOK_ENCRYPTION_KEY 必须改且必须记牢。 凭证系统没有默认密钥，不设置就无法保存任何 API Key；设置后用 Fernet（AES-128-CBC + HMAC-SHA256）加密入库。换了密钥或丢了密钥，库里所有凭证不可读——官方文档原话是 “all stored credentials become unreadable”。它支持 Docker secrets（_FILE 后缀），生产环境建议走这条道。
2. 端口口径：8502 是 Web UI，5055 是 REST API，8000 是 SurrealDB（只绑 127.0.0.1）。网上不少旧教程把 5055 当 UI 地址，照着打开会看到 JSON 而不是界面。

配 Provider 的路径也变了（旧版的 Settings → API Keys 已不存在）：UI 里进 Models 页面 → 选 Provider → + Add Configuration → 粘 Key → Test → Sync Models 勾选要用的模型 → 在 Default Model Assignments 里点 Auto-Assign Defaults 或手动指定各用途的默认模型。每个 Provider 可以存多份凭证，运行时轮换，不用重启。

想完全本地、零 API 费用，用 examples/docker-compose-full-local.yml：Ollama 跑 LLM 和 Embedding，Speaches 跑本地 TTS 和 STT——语音两端也都有本地选项了，数据可以完全不出机。另有 docker-compose-single.yml（SurrealDB 与应用同容器，试用省事、生产不推荐）等变体。

与 NotebookLM 差在哪

下表来自 README 的官方对照，“优势"列是仓库自宣，不是中立评测——读的时候把自宣词（“无上限"“极大”）当方向看，不要当数字看。

读法：前三行和 API 行是 Open Notebook 的结构性优势，来自架构选择，不会随版本波动；“引用质量"是 NotebookLM 的结构性优势——Open Notebook 的 Recently Completed 里虽有 Enhanced Citations（改进布局和引用粒度控制），README 至今仍把这一行标为 basic。如果你的工作靠引用逐条溯源，先小规模验证再迁移。

Provider 支持矩阵

这张矩阵是"多模型"主张的硬证据，同样来自 README（2026-09-30 口径）。同一 Provider 在不同能力上的支持差异很大，选型前先明确你要它干哪件事。

*含 LM Studio 及任意 OpenAI 兼容端点。官方口径是"18+ 提供商”，矩阵实列 22 行（含兜底行）。

v1.14.0（2026-07-21）一次加了四个入口：Cohere（走原生 v2 API）、PayPerQ（四项全 ✅ 的多模态网关）、Novita（OpenAI 兼容 LLM 网关）、Deepgram 补上 STT。OpenRouter 也补齐了 STT/TTS——注意它的 TTS 用微软神经语音名（如 en-US-AvaNeural），不是 OpenAI 的 alloy/nova 那套命名。还有两个不起眼但实用的：oMLX 面向 Apple Silicon 本地推理（默认 http://localhost:11435/v1）；anthropic_compatible 凭证类型专接只说 Anthropic Messages 协议的端点（比如 Kimi）。

选型时几条现成的路：

• 一套 Provider 包办四项：OpenAI、Google GenAI、Azure、Mistral、PayPerQ、OpenAI 兼容端点，共六个。
• 完全本地：Ollama（LLM + Embedding）或 oMLX，语音配 Speaches 或 ElevenLabs。
• 中文模型：DashScope（Qwen）、MiniMax、DeepSeek 都只覆盖 LLM；Embedding 仍需另配 OpenAI / Google / Ollama / Voyage 等。
• Anthropic 做 LLM：它没有 Embedding/STT/TTS，RAG 必须再配一个 Embedding Provider。

安全侧值得一提：v1.14.0 给所有出站 Provider 调用加了 DNS 重绑定防护（URL 校验后把请求钉在解析验证过的 IP 上），同时明确私有 IP、localhost、host.docker.internal、Tailscale 地址照常可用——自托管、本地模型是一等场景，不是被安全策略牺牲的对象。

素材处理链：Content Core 2.0

v1.13.0（2026-07-14）把素材解析整条链重写在 content-core 2.x 上，是 6 月以来对使用体验影响最大的变化：

• Docling 文档引擎（可选安装）：扫描版 PDF 和图片有了真 OCR 和版面感知解析。通过 OPEN_NOTEBOOK_ENABLE_DOCLING=true 开启，首次启动时自动安装重型 ML 依赖并缓存到数据卷；OCR 开关在 Settings → Content Processing，默认开——纯文本 PDF 可以关掉它提速。
• Crawl4AI URL 引擎（可选安装）：本地渲染 JavaScript 重的页面，不需要 API Key；也可以把 CRAWL4AI_API_URL 指向远程 Crawl4AI 服务免装本地运行时。URL 引擎现在与 Firecrawl、Jina、Simple 并列可选，而且你在设置里选的引擎这次真的会生效——release notes 自己承认之前"一直跑 auto、静默忽略选择”。
• 新格式：EPUB 电子书；Reddit 链接会连带抓取帖子和评论。
• PDF 提取换了 pdfplumber（MIT 协议，替换 AGPL 的 PyMuPDF）；音频提取改直调 ffmpeg，修复了带章节元数据的 MP3 解析失败。
• 失败更快更明白：不支持的格式在上传时立刻返回 415 并指明检测到的类型，不再让后台任务默默重试约一小时。
• 能力自省：GET /api/capabilities 报告当前容器实际装了哪些引擎；没装时 UI 会禁用对应选项，不给你点了个寂寞的开关。

镜像因此保持精简：重型运行时全部 opt-in，默认镜像不带 Docling 和本地 Crawl4AI。

核心能力拆解

Sources：多模态素材库

PDF、EPUB、视频、音频、网页、Office 文档、纯文本都进同一个入口。添加后系统解析内容、Embedding 分块入库、生成摘要和关键洞察，然后进入 Search 和 Chat 的可引用范围。它是其余所有功能的内容池。

Notes：两类笔记

手动写的 Markdown 笔记，和对素材跑 Transformation 生成的 AI 笔记，同库存放。笔记在 Chat 和 Podcast 里与 Source 平权，相当于"你整理过的上下文”。

Chat：一个 Notebook 开多个会话

会话是独立对象：各自绑定上下文范围（哪些 Source、哪些 Note）、引用粒度、模型。推理模型（DeepSeek-R1、Qwen3 这类 thinking model）官方明确支持。把 Notebook 当"主题包"、Chat 当"包内的多次独立研究"，这个模型比单一对话流更接近真实的研究节奏。

Search：全文 + 向量双路

跨所有 Notebook 检索，关键词命中和语义命中都走，最后仍由 LLM 基于命中段落生成回答——“只基于来源"的原则与 NotebookLM 一致。

Transformations：把素材变成产物

内置模板（摘要、提纲、要点、问答对）加自定义 Prompt。典型用法：五份 PDF 一次转结构化笔记、按固定模板出客户提案草稿、英文素材改写成中文播客脚本。

Podcast：1-4 个说话人

对比 NotebookLM 锁死的 2 说话人，这里每个说话人有独立 Episode Profile（角色、性格、语速、风格），语音由矩阵里支持 TTS 的 Provider 合成。v1.13.0 修掉了两个烦人的正确性问题：重命名说话人档案不再弄坏引用它的节目（改按记录 ID 引用），音频路径改为相对存储，挪动数据目录不会让旧节目失联。官方有段 4 说话人的 Podcast Demo，可以先听再决定。

一份扫描版 PDF 的完整旅程

把机制串起来：假设你拖进一份 200 页的扫描版合同 PDF，想让它变成可问答、可引用、最后生成一段三人讨论音频的笔记本。

1. 上传      拖入 UI（或 POST /api/sources）。格式校验在入口完成，
             不支持的类型当场 415，不会进后台队列空转。
2. 解析      扫描件没有文本层 → Docling 引擎接手：OCR 逐页识别 + 版面
             解析（表格、标题层级）。首次启用时容器先自动安装 Docling，
             日志会打出实际生效的 document_engine / docling_ocr。
3. 入库      文本分块、逐块 Embedding（比如 mxbai-embed-large），向量与
             原文、页码引用一起写进 SurrealDB；同时生成摘要和关键洞察。
4. 问答      开一个 Chat 会话，上下文限定这份合同，开 citations。提问
             "违约金条款在哪几页"，回答带块级引用，可跳回原文核对。
5. 加工      对这份 Source 跑 Transformation："提取全部期限与金额条款，
             输出表格"，产出一页 Notes。
6. 出声      建三个 Episode Profile（主持人 + 两位分析师人设），选支持
             TTS 的 Provider 合成，生成音频存进 notebook_data，可下载。

这条链上任何一环都可以换成别的：PDF 换 Reddit 链接（解析改 Crawl4AI）、问答模型换本地 Ollama、TTS 换 ElevenLabs——上层流程不变，这正是 esperanto 抽象层的意义。整条链同样可以用 REST API 驱动，第 1 步和第 6 步都有对应端点。

常见坑

密钥与迁移：OPEN_NOTEBOOK_ENCRYPTION_KEY 换机器、重装、换值，三者的后果一样——库里的 Provider 凭证全部读不出来。把密钥进密码管理器，和数据库备份分开存放。

Embedding 决定搜索质量：全文搜索不依赖它，但语义搜索和 Chat 的召回全靠 Embedding 模型。官方 Ollama 文档的排序是 mxbai-embed-large（Excellent，首选）、nomic-embed-text（Good）、all-minilm（Fair，只图省资源时用）。换了 Embedding 模型，旧向量要重建。

端口冲突：8000 / 8502 / 5055 三个都要空。SurrealDB 那个端口默认绑 127.0.0.1 是刻意设计——数据库凭证默认 root:root，绑到 0.0.0.0 等于把数据库暴露给整个局域网。要远程访问应用，走反向代理（docs/5-CONFIGURATION/reverse-proxy.md），不要直接改数据库端口绑定。

并发与本地模型：后台 Worker 默认并发 5 个任务（解析、Embedding、播客都在里面）。单 GPU 或本地小模型扛不住并行请求，OPEN_NOTEBOOK_WORKER_MAX_TASKS=1 改串行。

公网部署：密码保护默认关闭，设 OPEN_NOTEBOOK_PASSWORD 启用（单密码，不是账号体系）；两个敏感环境变量都支持 _FILE 后缀接 Docker secrets。

自动化出口：REST API 与 MCP

API-first 是写进设计原则的承诺：UI 能做的，REST API 都能做，:5055/docs 是完整参照。这意味着"丢资料、跑 Transformation、出播客"可以整个挂在自动化流水线上。

MCP 接入走第三方维护的 open-notebook-mcp（PyPI 包，Claude Desktop / VS Code 里 uvx open-notebook-mcp 直接跑），能力覆盖 Notebooks / Sources / Notes 的完整增删改查、Chat 会话管理、双路搜索、模型配置和设置读写——已经不止"查查笔记”，足以当 Agent 的记忆外挂用。连接受 OPEN_NOTEBOOK_PASSWORD 保护，远程实例把 OPEN_NOTEBOOK_URL 指过去即可。

一条务实建议：自动化先从 REST API 起步（OpenAPI 文档即契约），MCP 适合"在对话里顺手查一下笔记本"的轻场景。

谁该用，谁该等

现在就值得上：资料不能出本机的团队（合规、客户合同、内部研究）；要在多家模型间按成本和质量随时切换的人；需要把 Notebook 接进自己 Agent 或内容流水线的开发者；想要 3-4 人播客的内容团队。

先等等：指望它替代 NotebookLM 的协作体验——它是单用户工具，多用户还在 Horizon 议程（issue #712），目前只有单密码保护；对引用溯源有硬要求的研究——官方自己标注 citations 仍是 basic；完全不想碰 Docker 和备份的人——NotebookLM 更省心。

另外留意版本节奏：6 月到 9 月发了 6 个 minor 版本，且 Horizon 上挂着 SurrealDB v3 迁移和前后端镜像拆分（issues #372/#378/#381），官方明确说这是一次协同的 breaking change。生产化之前，把升级成本算进去。

稳妥的采用顺序：

1. 单机 docker compose up 跑通：UI 能开、Provider Test 通过、建第一个 Notebook 传一份真实资料。
2. 用真实工作素材走完"上传 → Chat 引用问答 → Transformation → 播客"闭环，验证它真能接替你现在的流程，再谈迁移。
3. 把 Embedding 模型选对（别用默认的轻量款凑合），确认语义搜索质量达标。
4. 需要"零 API 费 + 数据不出机"时，切到 full-local compose 变体验证一遍。
5. 最后接入自动化（REST API 或 MCP），并把 ./notebook_data、./surreal_data 和加密密钥纳入常规备份。

数据口径与参考

• Stars、Forks、Commits、语言构成、License：GitHub REST API，2026-09-30 抓取。
• Provider 矩阵、对照表、Quick Start、Roadmap：main 分支 README，2026-09-30 抓取；安装命令与 UI 路径以最新文档为准。
• Content Core 2.0、DNS 加固、新 Provider：v1.13.0 / v1.14.0 release notes；单用户定位：VISION.md Current Posture（PDR-001）；API-first：ADR-003。
• 环境变量语义（加密、_FILE、Worker 并发）：docs/5-CONFIGURATION/environment-reference.md 与 security.md；Ollama Embedding 选型：docs/5-CONFIGURATION/ollama.md。

本文不覆盖从源码构建（docs/1-INSTALLATION/from-source.md）、反向代理细节与 Easypanel 一键部署；播客音质、OCR 准确率这类依赖模型与素材的主观指标，仓库未提供可引用的基准数据，建议用自己的一份素材实测。