Open Notebook 文档全景指南从安装部署到开发维护的分层学习路线图【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook本文是 open-notebook 项目官方文档入口 docs/index.md 的深度导读。open-notebook 是一套以隐私优先、可完全本地化运行的开源 AI 研究助手提供 Notebooks / Sources / Notes 三级研究管理、RAG 问答、多模态内容处理、多说话人播客生成与全量 REST API。docs 目录下的 8 大分区以渐进式披露Progressive Disclosure组织本文替你梳理每个分区的定位、适用人群与核心内容并对照仓库源码补充可验证的依据帮助你在 15 分钟到数小时内按需完成理解 → 安装 → 上手 → 配置 → 排障 → 二次开发的完整学习闭环。一、docs/index.md 是什么一扇通向全部知识的导航门户docs/index.md本身并不是某单一功能的教程而是整个文档体系的总索引按不同的用户画像组织出多种进入路径。它明确声明了文档组织遵循的六条设计原则渐进式披露先讲简单的需要时再深入多种入口路径不同用户从不同入口进入高信噪比内容聚焦、无废话逐步指导每一步都可照做决策树帮助你在分叉点选对路径按症状组织排障根据哪里坏了而非根因是什么来排查。docs 目录整体划分为 8 个分区对应你当前所处的阶段分区目录适合谁回答什么问题0-START-HEREdocs/0-START-HERE/index.md所有人起点Open Notebook 是什么、5 分钟跑起来1-INSTALLATIONdocs/1-INSTALLATION/index.md部署者用哪种方式安装2-CORE-CONCEPTSdocs/2-CORE-CONCEPTS/index.md想理解原理的人系统的心智模型与架构3-USER-GUIDEdocs/3-USER-GUIDE/index.md使用者各功能如何一步步操作4-AI-PROVIDERSdocs/4-AI-PROVIDERS/index.md需要 AI 能力的人用哪家 Provider、怎么选5-CONFIGURATIONdocs/5-CONFIGURATION/index.md配置者环境变量与各项参考6-TROUBLESHOOTINGdocs/6-TROUBLESHOOTING/index.md遇到问题的人报错了怎么办7-DEVELOPMENTdocs/7-DEVELOPMENT/index.md贡献者/二次开发者架构、API、测试、提交规范文档在 2026 年 1 月更新正文标注适配Open Notebook v1.2.4并宣称体系内含 8 大分区、35 篇聚焦指南覆盖全部功能模块。二、先回答三个问题Choose Your Path 决策树docs/index.md用 Choose Your Path帮你在第一时间收敛方向只需对照你自己的身份回答三个问题我是纯新手→ 进入 0-START-HERE先搞清Open Notebook 是什么再选一条 5 分钟安装路径我要安装/部署→ 进入 1-INSTALLATION在 Docker Compose / 源码 / Windows 原生等多条路线中做选择我要搞懂原理→ 阅读 2-CORE-CONCEPTS 建立心智模型随后按需查阅使用教程、配置参考、Provider 专项文档、故障排查或开发文档。这套按角色分叉的设计贯穿全文同一个知识被拆进 0→7 七个递增深度的章节前端使用者在第 3 层即止步而开发者可以一路走到第 7 层。docs/index.md 还专门用一张By Section / By Problem Type的双重视图组织导航——既可按文档结构找也可按我遇到什么问题找后者正是按症状组织原则的落地。三、5 分钟上手路线0-START-HERE 的三条快速路径0-START-HERE 首页把用户分成三条快速路径每条都宣称约 5 分钟可运行路径目标用户文档OpenAI最快有 OpenAI Key想最快跑起来docs/0-START-HERE/quick-start-openai.md其他云端 AIAnthropic、Google、OpenRouter 等想在 17 Provider 中自由选择docs/0-START-HERE/quick-start-cloud.md本地全离线Ollama / LM Studio完全隐私、零 API 成本docs/0-START-HERE/quick-start-local.md已有外部 Ollama 实例复用现成 Ollama 服务docs/0-START-HERE/quick-start-external-ollama.md三条路径的共同前置条件只有两个Docker所有路径都基于容器与一种 AI 能力来源云端 API Key或用 Ollama 的免费本地模型。这与仓库根目录 README.md 的 2 分钟快速开始一致docker compose up -d启动后打开http://localhost:8502在 UI 的Models / Settings → API Keys中完成 Provider 凭据配置。从5 分钟能做什么看这一分区同时预告了产品的能力边界是 docs/index.md按 Section 概览中对 0-START-HERE 的官方描述 上传内容PDF、网页链接、音视频、纯文本 与 AI 对话基于文档问答并给出引用citations 生成笔记AI 摘要与洞察️ 生成播客把研究材料转成专业音频 搜索全文检索与语义向量检索⚙️ 变换Transformations抽取洞察、分析主题、生成摘要。关键版本提示0-START-HERE 首页的对比表中Podcast 说话人为1–4 个可定制对比 Google Notebook LM 仅 2 个AI 提供商数量标注为 17支持完全离线运行——这些是 docs 自身陈述的能力边界可作为选用时的判断依据。四、安装与部署1-INSTALLATION 的多路线矩阵进入 docs/1-INSTALLATION/index.md 后首先是一张Quick Decision路线决策表路线适用人群状态说明Docker Compose绝大多数用户推荐✅ 当前推荐多容器、生产就绪、服务隔离清晰、易于扩展Mac/Windows/Linux 通用约 5 分钟单容器 Single Container曾用旧版单容器部署的用户⚠️ 已弃用文档明确标注 Deprecated将在 v2 移除从源码安装 From Source开发者/贡献者✅需 Python 3.11 与 Node.js约 10 分钟Windows 原生无法使用 Docker/WSL 的 Windows 用户✅面向 Windows ARM64需 Python 3.12、Node.js、SurrealDB、uv约 15 分钟4.1 系统要求文档给出的基线最低4GB 内存2GB 存储另需文档存放空间任意现代 CPU网络离线部署场景可选。推荐8GB 内存10GB 存储含本地模型多核 CPU可选 GPU加速本地 AI 推理。4.2 AI Provider 的双阵营权衡docs/1-INSTALLATION 同时给出选型框架云端按量付费OpenAI、Anthropic Claude、Google Gemini、Groq、Mistral、DeepSeek、xAI、OpenRouter 等。优点是延迟低亚秒级、免运维代价是数据上云、按 Token 计费。本地免费、私密Ollama、LM Studio、Hugging Face 模型。零使用成本仅电费100% 离线但推理速度取决于硬件。隐私敏感用户文档强调任意安装方式 Ollama 即可实现 100% 本地 AI详见 docs/0-START-HERE/quick-start-local.md。4.3 安装后与生产化衔接安装完成后的标准动作链配置模型Settings 选择 Provider→ 创建第一个 Notebook → 添加 Sources → 探索 Chat/Search/Transformations → 阅读完整用户指南。若为生产部署文档把话题继续下放到 docs/5-CONFIGURATION/security.md安全加固、docs/5-CONFIGURATION/reverse-proxy.md反向代理与 docs/5-CONFIGURATION/advanced.md性能调优。这一分区在仓库中的权威佐证是根目录 docker-compose.yml它定义了surrealdb默认root:root仅绑定127.0.0.1:8000与open_notebook暴露 8502 Web UI 与 5055 REST API两个服务并要求设置OPEN_NOTEBOOK_ENCRYPTION_KEY用于加密数据库中的 API Key体现了文档数据库默认预配置、重点配置 Provider的总体叙述。五、理解系统的心智模型2-CORE-CONCEPTS 的五大概念2-CORE-CONCEPTS 首页 是全文档的为什么层主张先建立 5 个心智模型再动手Notebooks, Sources, Notes 三级结构notebooks-sources-notes.md Notebook 是有边界的研究容器Sources 是输入PDF、URL…Notes 是输出人工洞察、AI 摘要、被捕获的回答。这是理解信息如何从原材料流向成品洞察的根基前端 frontend/src/app/(dashboard)/notebooks/page.tsx/notebooks/page.tsx) 的三栏布局SourcesColumn / ChatColumn / NotesColumn正是这一层级的直接呈现。AI Context 与 RAGChat 与 Ask 的两种路径ai-context-rag.mdChat把选中的完整 Source 交给 LLM全量上下文、对话式Ask走 RAG——先检索再只取相关片段。对应后端实现分别位于 api/routers/chat.py、api/routers/source_chat.py 与 api/routers/search.py以及 open_notebook/graphs/ 下的 chat.py / source_chat.py / ask.py 图谱。不同工具有不同用途是全文反复强调的核心理念。Chat vs Transformationschat-vs-transformations.md Chat 是对话式探索你控制上下文Transformations 是洞察抽取把庞杂内容压缩为浓缩高密度信息——这对 AI 使用更友好。该心智模型在测试集如 tests/test_transformations_api.py 中有端到端验证。Context Management你的隐私与成本控制面板chat-vs-transformations.md 每个上下文有三个级别可选不在上下文中私密/ 仅摘要压缩/ 完整内容全量访问。前端 frontend/src/components/common/ContextToggle.tsx 与 ContextIndicator 组件承担了这个粒度控制。Podcasts把研究转成可听的格式podcasts-explained.md 播客把阅读消费变为听觉消费。支持多说话人Episode Profiles 与 Speaker Profiles后端由 api/podcast_service.py 与 open_notebook/podcasts/models / audio_paths支撑前端有 frontend/src/components/podcasts/GeneratePodcastDialog.tsx 等完整流程 UI。2-CORE-CONCEPTS 首页的Big Picture一句话点题你的研究理应属于你自己——默认隐私、AI 是工具而非守门人、消费方式灵活读/听/搜/聊/变换。六、八大功能实操3-USER-GUIDE 的使用层docs/3-USER-GUIDE/index.md 的前置条件是先读完 2-CORE-CONCEPTS随后按顺序覆盖八大功能的逐步教程添加 Sourcesadding-sources.md— PDF、网页链接、音视频转写、直接粘贴文本常见错误与修复。content-processing-engines.md 补充了 Docling、Firecrawl、Jina、Crawl4AI 等抽取引擎与 OCR 控制对应 api/routers/sources.py 的 POST 上传与处理端点使用 Notesworking-with-notes.md— 手动笔记、把 AI 回答存为笔记、用变换生成洞察、标签与命名组织后端 api/routers/notes.py前端编辑器 frontend/src/components/ui/markdown-editor.tsx有效聊天chat-effectively.md— 首次对话、选择进入上下文的 Sources、提好问题、跟进追问、读懂引用验证声明创建播客creating-podcasts.md— 选择/定制说话人、选择 TTS Provider、生成与下载、音频质量修复有效搜索search.md— 关键词全文检索 vs 语义向量检索的适用场景以及用 Ask 获取综合答案、把结果存为笔记Transformationstransformations.md— 内置模板、自建变换、单/多 Source 批量应用后端 api/routers/transformations.py引用 Citationscitations.md— 读/点引用、对照源文验证、请求更好引用、把引用内容存为笔记API 配置api-configuration.md— 直接在 Settings UI 添加 API Key、测试连接、从环境变量迁移、管理 Azure 与 OpenAI 兼容 Provider、理解加密存储。文档还给出了一张很有实战价值的哪个功能干哪个活决策表节选想带追问地探索话题 → Chat加源、选上下文、对话 想要一份综合大答案 → Search / Ask系统自动检索 想从多个源抽同样信息 → Transformations定义模板批量应用 想要所有源的摘要 → Transformations内置摘要模板 想把研究变成音频分享 → Podcasts建说话人、生成剧集 想找回某句记得的引用 → Search / Text Search关键词 概念模糊、说不出准确词 → Search / Vector Search语义相似 要增改 Provider API Key → Settings / API Keys不碰文件以及首 15 分钟清单建 Notebook1 分钟给个描述性名字→ 添加第一个 Source3 分钟等待处理 30–60 秒→ 围绕它聊天3 分钟Context 设为 Full Content→ 把好回答存为 Note2 分钟→ 再添源做对比式提问6 分钟。完整跑通notebook → sources → chat → notes即视为掌握核心工作流。同时该页用常见错误表提前预警六个高频坑单 Notebook 塞进所有项目、指望 AI 自带上下文、从不点引用、一次性问题滥用 Chat、超大 PDF 不分块、所有会话共用同一上下文又贵又发散。七、Provider 怎么选、系统怎么配4-AI-PROVIDERS 与 5-CONFIGURATION7.1 提供商选型4-AI-PROVIDERSdocs/4-AI-PROVIDERS/index.md 帮助你在 17 提供商中做选择核心结论可浓缩为一张决策表需求推荐最容易上手 / 质量优先OpenAI省钱Groq约 $0.05/1M tokens 档位隐私 / 离线Ollama免费、纯本地Apple Silicon MacoMLXMLX 原生推理偏好 GUI 而非 CLILM Studio企业合规HIPAA/SOC2/VPCAzure OpenAI200K 长上下文Anthropic Claude多模态图/音/视频、超长上下文Google Gemini一把 Key 用 100 模型OpenRouter长上下文 204K 档MiniMax仓库侧证据是根目录 README.md 的Provider Support Matrix它把各厂商按 LLM / Embedding / Speech-to-Text / Text-to-Speech 四个能力维度打钩涵盖 OpenAI、Anthropic、Groq、Google GenAI、Vertex AI、Ollama、oMLX、Azure OpenAI、Mistral、DeepSeek、Cohere、OpenRouter、DashScope、PayPerQ 与 OpenAI Compatible含 LM Studio等。该矩阵同时提醒Embedding 与语音能力并非每家都有例如 Anthropic 仅有 LLM而*OpenAI Compatible一类覆盖任何兼容端点——这一点在 docs/5-CONFIGURATION/openai-compatible.md 有专项配置说明。7.2 配置参考5-CONFIGURATIONdocs/5-CONFIGURATION/index.md 明确指出真正需要手工配置的只有三件事AI Provider、数据库通常预配置、服务器参数通常自动探测。配置文件按场景分为两类.env本地开发使用位于项目根目录KEYvalue每行一条docker.envDocker Compose 部署时存放环境变量也支持直接写进 compose 文件加载方为 docker-compose.yml。数据库连接SurrealDBSURREAL_URLws://surrealdb:8000/rpc SURREAL_USERroot SURREAL_PASSWORDroot # 生产环境务必修改 SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook文档特别提醒唯一不能错的是SURREAL_URL中的hostname不同部署方式容器网络 / 本机 / 外部实例的 URL 写法见 docs/5-CONFIGURATION/database.md。AI Provider 凭据走 Settings UI文档规定必须先在环境里设置加密密钥否则无法保存凭据# 必需.env 或 docker-compose.yml 中都要有 OPEN_NOTEBOOK_ENCRYPTION_KEYmy-secret-key随后按Settings → API Keys → Add Credential → 选择 Provider 粘贴 Key → Test Connection → Discover Models → Register Models完成注册凭据以加密形式存入数据库无需重启服务。真正的密钥存储与加密逻辑可在 open_notebook/utils/encryption.py 与 api/credentials_service.py 中核对Ollama / OpenAI 兼容端点则分别参照 ollama.md 与 openai-compatible.md。API URL仅反向代理场景需要API_URLhttps://your-domain.com # 大多数情况下自动探测仅在代理或改端口时设置5-CONFIGURATION 还把配置按 5 种场景给出即贴即用的最小样例Docker 本机 / Docker 远程服务器 / Nginx-Cloudflare 反向代理 / 本地 Ollama / Azure OpenAI并汇总常见错误未配置凭据模型不可用、缺加密密钥无法保存凭据、数据库 URL 写错API 起不来、未暴露 5055 端口前端提示 Cant connect to server、环境变量拼写错误大小写敏感与改完不重启。该分区其余章节构成完整的参考体系ai-providers.md各厂商分步配置、environment-reference.md全量环境变量、默认值、advanced.md端口、超时、并发、SSL、重试、Worker 并发、STT/TTS、日志、reverse-proxy.mdNginx/Caddy/Traefik/Coolify、security.md密码保护与生产加固、local-tts.md/local-stt.mdSpeaches 本地语音。最小运行配置按文档总结只需 4 步设置OPEN_NOTEBOOK_ENCRYPTION_KEY→ 启动服务 → 在 Settings 中添加 Provider 凭据 → 完成。其余都是可选优化。八、出问题先看这6-TROUBLESHOOTING 的按症状排障docs/6-TROUBLESHOOTING/index.md 采用识别症状 → 找到对应指南 → 按步骤修复三段式并提供了两条查表按阶段安装期/启动期/配置期/使用期与按错误信息原文。例如症状去向容器起不来 / Docker 报错 / 权限拒绝quick-fixes.md#9-services-wont-start-or-docker-error端口被占用quick-fixes.md#3-port-x-already-in-useCannot connect to serverconnection-issues.mdInvalid API key / 模型不出现 / 回答差ai-chat-issues.md文件无法上传/处理、网页抽不出来quick-fixes.md#4-cannot-process-file-or-unsupported-format搜索无结果 / 结果不对quick-fixes.md#7-search-returns-nothing播客生成失败显示 FAILED 徽标查看剧集错误信息后用Retry按钮见 quick-fixes.md#8-podcast-generation-failed其中多数高频问题的通用诊断清单文档原样给出值得沉淀成肌肉记忆docker ps # 服务是否在跑 docker compose logs api # 看后端日志frontend / surrealdb 同理 netstat -tlnp | grep 5055 # 端口是否被监听或 lsof -i :5055 curl http://localhost:5055/health # 期望返回 {status:ok} docker inspect container # 核对环境变量 docker compose restart # 兜底重启慢性能时可在环境文件中调低SURREAL_COMMANDS_MAX_TASKS2以降低并发高成本问题则建议换用更便宜的模型或在 Settings 中切到 Ollama。若确实需要上报文档要求附带精确错误信息、复现步骤、docker compose logs输出、部署方式/Provider/操作系统与你已尝试过的办法。仓库里还准备了 docs/6-TROUBLESHOOTING/faq.md费用、备份、最佳实践与 docs/6-TROUBLESHOOTING/quick-fixes.mdTop 10 一分钟解决方案。九、贡献与二次开发7-DEVELOPMENT面向开发者的 7-DEVELOPMENT 是一套完整的工程文档工作流入口contributing.mdDiscussion → Issue → PR以及 5 分钟环境验证的 quick-start.md、完整环境的 development-setup.md、code-standards.md 与 testing.md架构层architecture.md 描述三层系统设计技术栈Python / FastAPI 后端、Next.js / React 前端、SurrealDB 存储并可下钻到 credentials.md凭据加密与 provisioning、content-processing.md切块、embedding、上下文构建、podcasts.mdProfile 体系与任务生命周期、prompts.md 与 frontend.md设计决策根目录 VISION.md产品定位与 docs/7-DEVELOPMENT/decisions/ 下的 ADR/PDR 决策记录含 SurrealDB 选型、从 Streamlit 迁移到 Next.js、后台 Worker、迁移粒度等Python 与前端各自根目录的AGENTS.md是给编码 Agent以及赶时间的人的规范速查约束与安全docs/7-DEVELOPMENT/security.md 覆盖 SurrealQL 注入、SSTI、路径穿越、CORS 与密钥管理等清单docs/7-DEVELOPMENT/api-reference.md 是全量 REST API 参考运行时可访问http://localhost:5055/docs。仓库实际规模也与此呼应后端代码集中在 open_notebook/ai / domain / database/migrations / graphs / podcasts / utilsAPI 层在 api/前端在 frontend/src/测试在 tests/ 与 frontend/src/app/(dashboard)/notebooks/components//notebooks/components/) 等处可作为阅读架构文档时的对照源码。十、按问题定位与四套推荐阅读路径docs/index.md在末尾提供了两组高价值导航工具恰恰是全文档被搜索引擎与 AI 最常命中的路标按问题快速定位节选全新安装看 0-START-HERE配置参考看 5-CONFIGURATIONProvider 配置看 4-AI-PROVIDERS功能不会用看 3-USER-GUIDEChat 不工作看 docs/6-TROUBLESHOOTING/ai-chat-issues.md文件传不上看 docs/6-TROUBLESHOOTING/quick-fixes.md架构原理看 docs/7-DEVELOPMENT/architecture.md。四条官方推荐的阅读路径完整新手路径约 1–2 小时0-START-HERE是什么 跑起来→ 2-CORE-CONCEPTS心智模型→ 3-USER-GUIDE学会各功能→ 达成完全会用 Open Notebook最快运行路径约 15 分钟0-START-HERE 选路径 → 照 quick-start 执行 → 先跑起来、细节后补DevOps/生产部署路径约 1–2 小时1-INSTALLATION选安装路线→ 5-CONFIGURATION参考配置→ 7-DEVELOPMENT 架构理解系统→ 具备生产部署能力排障路径约 5–30 分钟6-TROUBLESHOOTING 首页定位问题 → 打开对应专项指南 → 按步骤解决。常见问答速览文档原意从哪开始→0-START-HERE怎么装→1-INSTALLATION某功能怎么用→3-USER-GUIDE某功能为何这样设计→2-CORE-CONCEPTS某 Provider 怎么配→4-AI-PROVIDERS 或 5-CONFIGURATION坏了怎么办→6-TROUBLESHOOTING系统内部怎么运作→2-CORE-CONCEPTS 7-DEVELOPMENT能否参与贡献→7-DEVELOPMENT。十一、读完本文之后的建议动作docs/index.md是 docs 体系的交通枢纽它本身不含太多代码却决定了你检索所有细节知识的路径。建议按以下顺序行动按上文四套阅读路径中与你身份最匹配的一条从 docs/0-START-HERE/index.md 或 docs/1-INSTALLATION/index.md 落点先用根目录 docker-compose.yml 把服务跑起来用 docs/5-CONFIGURATION/index.md 的最小配置清单加密密钥 Settings UI 添加 Provider打通第一个可用环境遇到具体报错时始终先回到 docs/6-TROUBLESHOOTING/index.md 按症状定位再结合docker compose logs与curl http://localhost:5055/health收敛问题需要二次开发时从 docs/7-DEVELOPMENT/architecture.md 与 docs/7-DEVELOPMENT/api-reference.md 起步对照 open_notebook/、api/、frontend/src/ 的真实实现阅读。记住文档组织的一句话原则面向不同需求提供多条入口、按症状而非根因组织排障、由浅入深渐进披露——把 docs/index.md 当作这份分级手册的总目录而非终点任何功能细节都能沿其链接追踪到可操作的教程。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Open Notebook 文档全景指南：从安装部署到开发维护的分层学习路线图
Open Notebook 文档全景指南从安装部署到开发维护的分层学习路线图【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook本文是 open-notebook 项目官方文档入口 docs/index.md 的深度导读。open-notebook 是一套以隐私优先、可完全本地化运行的开源 AI 研究助手提供 Notebooks / Sources / Notes 三级研究管理、RAG 问答、多模态内容处理、多说话人播客生成与全量 REST API。docs 目录下的 8 大分区以渐进式披露Progressive Disclosure组织本文替你梳理每个分区的定位、适用人群与核心内容并对照仓库源码补充可验证的依据帮助你在 15 分钟到数小时内按需完成理解 → 安装 → 上手 → 配置 → 排障 → 二次开发的完整学习闭环。一、docs/index.md 是什么一扇通向全部知识的导航门户docs/index.md本身并不是某单一功能的教程而是整个文档体系的总索引按不同的用户画像组织出多种进入路径。它明确声明了文档组织遵循的六条设计原则渐进式披露先讲简单的需要时再深入多种入口路径不同用户从不同入口进入高信噪比内容聚焦、无废话逐步指导每一步都可照做决策树帮助你在分叉点选对路径按症状组织排障根据哪里坏了而非根因是什么来排查。docs 目录整体划分为 8 个分区对应你当前所处的阶段分区目录适合谁回答什么问题0-START-HEREdocs/0-START-HERE/index.md所有人起点Open Notebook 是什么、5 分钟跑起来1-INSTALLATIONdocs/1-INSTALLATION/index.md部署者用哪种方式安装2-CORE-CONCEPTSdocs/2-CORE-CONCEPTS/index.md想理解原理的人系统的心智模型与架构3-USER-GUIDEdocs/3-USER-GUIDE/index.md使用者各功能如何一步步操作4-AI-PROVIDERSdocs/4-AI-PROVIDERS/index.md需要 AI 能力的人用哪家 Provider、怎么选5-CONFIGURATIONdocs/5-CONFIGURATION/index.md配置者环境变量与各项参考6-TROUBLESHOOTINGdocs/6-TROUBLESHOOTING/index.md遇到问题的人报错了怎么办7-DEVELOPMENTdocs/7-DEVELOPMENT/index.md贡献者/二次开发者架构、API、测试、提交规范文档在 2026 年 1 月更新正文标注适配Open Notebook v1.2.4并宣称体系内含 8 大分区、35 篇聚焦指南覆盖全部功能模块。二、先回答三个问题Choose Your Path 决策树docs/index.md用 Choose Your Path帮你在第一时间收敛方向只需对照你自己的身份回答三个问题我是纯新手→ 进入 0-START-HERE先搞清Open Notebook 是什么再选一条 5 分钟安装路径我要安装/部署→ 进入 1-INSTALLATION在 Docker Compose / 源码 / Windows 原生等多条路线中做选择我要搞懂原理→ 阅读 2-CORE-CONCEPTS 建立心智模型随后按需查阅使用教程、配置参考、Provider 专项文档、故障排查或开发文档。这套按角色分叉的设计贯穿全文同一个知识被拆进 0→7 七个递增深度的章节前端使用者在第 3 层即止步而开发者可以一路走到第 7 层。docs/index.md 还专门用一张By Section / By Problem Type的双重视图组织导航——既可按文档结构找也可按我遇到什么问题找后者正是按症状组织原则的落地。三、5 分钟上手路线0-START-HERE 的三条快速路径0-START-HERE 首页把用户分成三条快速路径每条都宣称约 5 分钟可运行路径目标用户文档OpenAI最快有 OpenAI Key想最快跑起来docs/0-START-HERE/quick-start-openai.md其他云端 AIAnthropic、Google、OpenRouter 等想在 17 Provider 中自由选择docs/0-START-HERE/quick-start-cloud.md本地全离线Ollama / LM Studio完全隐私、零 API 成本docs/0-START-HERE/quick-start-local.md已有外部 Ollama 实例复用现成 Ollama 服务docs/0-START-HERE/quick-start-external-ollama.md三条路径的共同前置条件只有两个Docker所有路径都基于容器与一种 AI 能力来源云端 API Key或用 Ollama 的免费本地模型。这与仓库根目录 README.md 的 2 分钟快速开始一致docker compose up -d启动后打开http://localhost:8502在 UI 的Models / Settings → API Keys中完成 Provider 凭据配置。从5 分钟能做什么看这一分区同时预告了产品的能力边界是 docs/index.md按 Section 概览中对 0-START-HERE 的官方描述 上传内容PDF、网页链接、音视频、纯文本 与 AI 对话基于文档问答并给出引用citations 生成笔记AI 摘要与洞察️ 生成播客把研究材料转成专业音频 搜索全文检索与语义向量检索⚙️ 变换Transformations抽取洞察、分析主题、生成摘要。关键版本提示0-START-HERE 首页的对比表中Podcast 说话人为1–4 个可定制对比 Google Notebook LM 仅 2 个AI 提供商数量标注为 17支持完全离线运行——这些是 docs 自身陈述的能力边界可作为选用时的判断依据。四、安装与部署1-INSTALLATION 的多路线矩阵进入 docs/1-INSTALLATION/index.md 后首先是一张Quick Decision路线决策表路线适用人群状态说明Docker Compose绝大多数用户推荐✅ 当前推荐多容器、生产就绪、服务隔离清晰、易于扩展Mac/Windows/Linux 通用约 5 分钟单容器 Single Container曾用旧版单容器部署的用户⚠️ 已弃用文档明确标注 Deprecated将在 v2 移除从源码安装 From Source开发者/贡献者✅需 Python 3.11 与 Node.js约 10 分钟Windows 原生无法使用 Docker/WSL 的 Windows 用户✅面向 Windows ARM64需 Python 3.12、Node.js、SurrealDB、uv约 15 分钟4.1 系统要求文档给出的基线最低4GB 内存2GB 存储另需文档存放空间任意现代 CPU网络离线部署场景可选。推荐8GB 内存10GB 存储含本地模型多核 CPU可选 GPU加速本地 AI 推理。4.2 AI Provider 的双阵营权衡docs/1-INSTALLATION 同时给出选型框架云端按量付费OpenAI、Anthropic Claude、Google Gemini、Groq、Mistral、DeepSeek、xAI、OpenRouter 等。优点是延迟低亚秒级、免运维代价是数据上云、按 Token 计费。本地免费、私密Ollama、LM Studio、Hugging Face 模型。零使用成本仅电费100% 离线但推理速度取决于硬件。隐私敏感用户文档强调任意安装方式 Ollama 即可实现 100% 本地 AI详见 docs/0-START-HERE/quick-start-local.md。4.3 安装后与生产化衔接安装完成后的标准动作链配置模型Settings 选择 Provider→ 创建第一个 Notebook → 添加 Sources → 探索 Chat/Search/Transformations → 阅读完整用户指南。若为生产部署文档把话题继续下放到 docs/5-CONFIGURATION/security.md安全加固、docs/5-CONFIGURATION/reverse-proxy.md反向代理与 docs/5-CONFIGURATION/advanced.md性能调优。这一分区在仓库中的权威佐证是根目录 docker-compose.yml它定义了surrealdb默认root:root仅绑定127.0.0.1:8000与open_notebook暴露 8502 Web UI 与 5055 REST API两个服务并要求设置OPEN_NOTEBOOK_ENCRYPTION_KEY用于加密数据库中的 API Key体现了文档数据库默认预配置、重点配置 Provider的总体叙述。五、理解系统的心智模型2-CORE-CONCEPTS 的五大概念2-CORE-CONCEPTS 首页 是全文档的为什么层主张先建立 5 个心智模型再动手Notebooks, Sources, Notes 三级结构notebooks-sources-notes.md Notebook 是有边界的研究容器Sources 是输入PDF、URL…Notes 是输出人工洞察、AI 摘要、被捕获的回答。这是理解信息如何从原材料流向成品洞察的根基前端 frontend/src/app/(dashboard)/notebooks/page.tsx/notebooks/page.tsx) 的三栏布局SourcesColumn / ChatColumn / NotesColumn正是这一层级的直接呈现。AI Context 与 RAGChat 与 Ask 的两种路径ai-context-rag.mdChat把选中的完整 Source 交给 LLM全量上下文、对话式Ask走 RAG——先检索再只取相关片段。对应后端实现分别位于 api/routers/chat.py、api/routers/source_chat.py 与 api/routers/search.py以及 open_notebook/graphs/ 下的 chat.py / source_chat.py / ask.py 图谱。不同工具有不同用途是全文反复强调的核心理念。Chat vs Transformationschat-vs-transformations.md Chat 是对话式探索你控制上下文Transformations 是洞察抽取把庞杂内容压缩为浓缩高密度信息——这对 AI 使用更友好。该心智模型在测试集如 tests/test_transformations_api.py 中有端到端验证。Context Management你的隐私与成本控制面板chat-vs-transformations.md 每个上下文有三个级别可选不在上下文中私密/ 仅摘要压缩/ 完整内容全量访问。前端 frontend/src/components/common/ContextToggle.tsx 与 ContextIndicator 组件承担了这个粒度控制。Podcasts把研究转成可听的格式podcasts-explained.md 播客把阅读消费变为听觉消费。支持多说话人Episode Profiles 与 Speaker Profiles后端由 api/podcast_service.py 与 open_notebook/podcasts/models / audio_paths支撑前端有 frontend/src/components/podcasts/GeneratePodcastDialog.tsx 等完整流程 UI。2-CORE-CONCEPTS 首页的Big Picture一句话点题你的研究理应属于你自己——默认隐私、AI 是工具而非守门人、消费方式灵活读/听/搜/聊/变换。六、八大功能实操3-USER-GUIDE 的使用层docs/3-USER-GUIDE/index.md 的前置条件是先读完 2-CORE-CONCEPTS随后按顺序覆盖八大功能的逐步教程添加 Sourcesadding-sources.md— PDF、网页链接、音视频转写、直接粘贴文本常见错误与修复。content-processing-engines.md 补充了 Docling、Firecrawl、Jina、Crawl4AI 等抽取引擎与 OCR 控制对应 api/routers/sources.py 的 POST 上传与处理端点使用 Notesworking-with-notes.md— 手动笔记、把 AI 回答存为笔记、用变换生成洞察、标签与命名组织后端 api/routers/notes.py前端编辑器 frontend/src/components/ui/markdown-editor.tsx有效聊天chat-effectively.md— 首次对话、选择进入上下文的 Sources、提好问题、跟进追问、读懂引用验证声明创建播客creating-podcasts.md— 选择/定制说话人、选择 TTS Provider、生成与下载、音频质量修复有效搜索search.md— 关键词全文检索 vs 语义向量检索的适用场景以及用 Ask 获取综合答案、把结果存为笔记Transformationstransformations.md— 内置模板、自建变换、单/多 Source 批量应用后端 api/routers/transformations.py引用 Citationscitations.md— 读/点引用、对照源文验证、请求更好引用、把引用内容存为笔记API 配置api-configuration.md— 直接在 Settings UI 添加 API Key、测试连接、从环境变量迁移、管理 Azure 与 OpenAI 兼容 Provider、理解加密存储。文档还给出了一张很有实战价值的哪个功能干哪个活决策表节选想带追问地探索话题 → Chat加源、选上下文、对话 想要一份综合大答案 → Search / Ask系统自动检索 想从多个源抽同样信息 → Transformations定义模板批量应用 想要所有源的摘要 → Transformations内置摘要模板 想把研究变成音频分享 → Podcasts建说话人、生成剧集 想找回某句记得的引用 → Search / Text Search关键词 概念模糊、说不出准确词 → Search / Vector Search语义相似 要增改 Provider API Key → Settings / API Keys不碰文件以及首 15 分钟清单建 Notebook1 分钟给个描述性名字→ 添加第一个 Source3 分钟等待处理 30–60 秒→ 围绕它聊天3 分钟Context 设为 Full Content→ 把好回答存为 Note2 分钟→ 再添源做对比式提问6 分钟。完整跑通notebook → sources → chat → notes即视为掌握核心工作流。同时该页用常见错误表提前预警六个高频坑单 Notebook 塞进所有项目、指望 AI 自带上下文、从不点引用、一次性问题滥用 Chat、超大 PDF 不分块、所有会话共用同一上下文又贵又发散。七、Provider 怎么选、系统怎么配4-AI-PROVIDERS 与 5-CONFIGURATION7.1 提供商选型4-AI-PROVIDERSdocs/4-AI-PROVIDERS/index.md 帮助你在 17 提供商中做选择核心结论可浓缩为一张决策表需求推荐最容易上手 / 质量优先OpenAI省钱Groq约 $0.05/1M tokens 档位隐私 / 离线Ollama免费、纯本地Apple Silicon MacoMLXMLX 原生推理偏好 GUI 而非 CLILM Studio企业合规HIPAA/SOC2/VPCAzure OpenAI200K 长上下文Anthropic Claude多模态图/音/视频、超长上下文Google Gemini一把 Key 用 100 模型OpenRouter长上下文 204K 档MiniMax仓库侧证据是根目录 README.md 的Provider Support Matrix它把各厂商按 LLM / Embedding / Speech-to-Text / Text-to-Speech 四个能力维度打钩涵盖 OpenAI、Anthropic、Groq、Google GenAI、Vertex AI、Ollama、oMLX、Azure OpenAI、Mistral、DeepSeek、Cohere、OpenRouter、DashScope、PayPerQ 与 OpenAI Compatible含 LM Studio等。该矩阵同时提醒Embedding 与语音能力并非每家都有例如 Anthropic 仅有 LLM而*OpenAI Compatible一类覆盖任何兼容端点——这一点在 docs/5-CONFIGURATION/openai-compatible.md 有专项配置说明。7.2 配置参考5-CONFIGURATIONdocs/5-CONFIGURATION/index.md 明确指出真正需要手工配置的只有三件事AI Provider、数据库通常预配置、服务器参数通常自动探测。配置文件按场景分为两类.env本地开发使用位于项目根目录KEYvalue每行一条docker.envDocker Compose 部署时存放环境变量也支持直接写进 compose 文件加载方为 docker-compose.yml。数据库连接SurrealDBSURREAL_URLws://surrealdb:8000/rpc SURREAL_USERroot SURREAL_PASSWORDroot # 生产环境务必修改 SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook文档特别提醒唯一不能错的是SURREAL_URL中的hostname不同部署方式容器网络 / 本机 / 外部实例的 URL 写法见 docs/5-CONFIGURATION/database.md。AI Provider 凭据走 Settings UI文档规定必须先在环境里设置加密密钥否则无法保存凭据# 必需.env 或 docker-compose.yml 中都要有 OPEN_NOTEBOOK_ENCRYPTION_KEYmy-secret-key随后按Settings → API Keys → Add Credential → 选择 Provider 粘贴 Key → Test Connection → Discover Models → Register Models完成注册凭据以加密形式存入数据库无需重启服务。真正的密钥存储与加密逻辑可在 open_notebook/utils/encryption.py 与 api/credentials_service.py 中核对Ollama / OpenAI 兼容端点则分别参照 ollama.md 与 openai-compatible.md。API URL仅反向代理场景需要API_URLhttps://your-domain.com # 大多数情况下自动探测仅在代理或改端口时设置5-CONFIGURATION 还把配置按 5 种场景给出即贴即用的最小样例Docker 本机 / Docker 远程服务器 / Nginx-Cloudflare 反向代理 / 本地 Ollama / Azure OpenAI并汇总常见错误未配置凭据模型不可用、缺加密密钥无法保存凭据、数据库 URL 写错API 起不来、未暴露 5055 端口前端提示 Cant connect to server、环境变量拼写错误大小写敏感与改完不重启。该分区其余章节构成完整的参考体系ai-providers.md各厂商分步配置、environment-reference.md全量环境变量、默认值、advanced.md端口、超时、并发、SSL、重试、Worker 并发、STT/TTS、日志、reverse-proxy.mdNginx/Caddy/Traefik/Coolify、security.md密码保护与生产加固、local-tts.md/local-stt.mdSpeaches 本地语音。最小运行配置按文档总结只需 4 步设置OPEN_NOTEBOOK_ENCRYPTION_KEY→ 启动服务 → 在 Settings 中添加 Provider 凭据 → 完成。其余都是可选优化。八、出问题先看这6-TROUBLESHOOTING 的按症状排障docs/6-TROUBLESHOOTING/index.md 采用识别症状 → 找到对应指南 → 按步骤修复三段式并提供了两条查表按阶段安装期/启动期/配置期/使用期与按错误信息原文。例如症状去向容器起不来 / Docker 报错 / 权限拒绝quick-fixes.md#9-services-wont-start-or-docker-error端口被占用quick-fixes.md#3-port-x-already-in-useCannot connect to serverconnection-issues.mdInvalid API key / 模型不出现 / 回答差ai-chat-issues.md文件无法上传/处理、网页抽不出来quick-fixes.md#4-cannot-process-file-or-unsupported-format搜索无结果 / 结果不对quick-fixes.md#7-search-returns-nothing播客生成失败显示 FAILED 徽标查看剧集错误信息后用Retry按钮见 quick-fixes.md#8-podcast-generation-failed其中多数高频问题的通用诊断清单文档原样给出值得沉淀成肌肉记忆docker ps # 服务是否在跑 docker compose logs api # 看后端日志frontend / surrealdb 同理 netstat -tlnp | grep 5055 # 端口是否被监听或 lsof -i :5055 curl http://localhost:5055/health # 期望返回 {status:ok} docker inspect container # 核对环境变量 docker compose restart # 兜底重启慢性能时可在环境文件中调低SURREAL_COMMANDS_MAX_TASKS2以降低并发高成本问题则建议换用更便宜的模型或在 Settings 中切到 Ollama。若确实需要上报文档要求附带精确错误信息、复现步骤、docker compose logs输出、部署方式/Provider/操作系统与你已尝试过的办法。仓库里还准备了 docs/6-TROUBLESHOOTING/faq.md费用、备份、最佳实践与 docs/6-TROUBLESHOOTING/quick-fixes.mdTop 10 一分钟解决方案。九、贡献与二次开发7-DEVELOPMENT面向开发者的 7-DEVELOPMENT 是一套完整的工程文档工作流入口contributing.mdDiscussion → Issue → PR以及 5 分钟环境验证的 quick-start.md、完整环境的 development-setup.md、code-standards.md 与 testing.md架构层architecture.md 描述三层系统设计技术栈Python / FastAPI 后端、Next.js / React 前端、SurrealDB 存储并可下钻到 credentials.md凭据加密与 provisioning、content-processing.md切块、embedding、上下文构建、podcasts.mdProfile 体系与任务生命周期、prompts.md 与 frontend.md设计决策根目录 VISION.md产品定位与 docs/7-DEVELOPMENT/decisions/ 下的 ADR/PDR 决策记录含 SurrealDB 选型、从 Streamlit 迁移到 Next.js、后台 Worker、迁移粒度等Python 与前端各自根目录的AGENTS.md是给编码 Agent以及赶时间的人的规范速查约束与安全docs/7-DEVELOPMENT/security.md 覆盖 SurrealQL 注入、SSTI、路径穿越、CORS 与密钥管理等清单docs/7-DEVELOPMENT/api-reference.md 是全量 REST API 参考运行时可访问http://localhost:5055/docs。仓库实际规模也与此呼应后端代码集中在 open_notebook/ai / domain / database/migrations / graphs / podcasts / utilsAPI 层在 api/前端在 frontend/src/测试在 tests/ 与 frontend/src/app/(dashboard)/notebooks/components//notebooks/components/) 等处可作为阅读架构文档时的对照源码。十、按问题定位与四套推荐阅读路径docs/index.md在末尾提供了两组高价值导航工具恰恰是全文档被搜索引擎与 AI 最常命中的路标按问题快速定位节选全新安装看 0-START-HERE配置参考看 5-CONFIGURATIONProvider 配置看 4-AI-PROVIDERS功能不会用看 3-USER-GUIDEChat 不工作看 docs/6-TROUBLESHOOTING/ai-chat-issues.md文件传不上看 docs/6-TROUBLESHOOTING/quick-fixes.md架构原理看 docs/7-DEVELOPMENT/architecture.md。四条官方推荐的阅读路径完整新手路径约 1–2 小时0-START-HERE是什么 跑起来→ 2-CORE-CONCEPTS心智模型→ 3-USER-GUIDE学会各功能→ 达成完全会用 Open Notebook最快运行路径约 15 分钟0-START-HERE 选路径 → 照 quick-start 执行 → 先跑起来、细节后补DevOps/生产部署路径约 1–2 小时1-INSTALLATION选安装路线→ 5-CONFIGURATION参考配置→ 7-DEVELOPMENT 架构理解系统→ 具备生产部署能力排障路径约 5–30 分钟6-TROUBLESHOOTING 首页定位问题 → 打开对应专项指南 → 按步骤解决。常见问答速览文档原意从哪开始→0-START-HERE怎么装→1-INSTALLATION某功能怎么用→3-USER-GUIDE某功能为何这样设计→2-CORE-CONCEPTS某 Provider 怎么配→4-AI-PROVIDERS 或 5-CONFIGURATION坏了怎么办→6-TROUBLESHOOTING系统内部怎么运作→2-CORE-CONCEPTS 7-DEVELOPMENT能否参与贡献→7-DEVELOPMENT。十一、读完本文之后的建议动作docs/index.md是 docs 体系的交通枢纽它本身不含太多代码却决定了你检索所有细节知识的路径。建议按以下顺序行动按上文四套阅读路径中与你身份最匹配的一条从 docs/0-START-HERE/index.md 或 docs/1-INSTALLATION/index.md 落点先用根目录 docker-compose.yml 把服务跑起来用 docs/5-CONFIGURATION/index.md 的最小配置清单加密密钥 Settings UI 添加 Provider打通第一个可用环境遇到具体报错时始终先回到 docs/6-TROUBLESHOOTING/index.md 按症状定位再结合docker compose logs与curl http://localhost:5055/health收敛问题需要二次开发时从 docs/7-DEVELOPMENT/architecture.md 与 docs/7-DEVELOPMENT/api-reference.md 起步对照 open_notebook/、api/、frontend/src/ 的真实实现阅读。记住文档组织的一句话原则面向不同需求提供多条入口、按症状而非根因组织排障、由浅入深渐进披露——把 docs/index.md 当作这份分级手册的总目录而非终点任何功能细节都能沿其链接追踪到可操作的教程。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考