Open Notebook REST API 完整参考掌握认证、核心资源与异步流式开发【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook本文是 Open NotebookNotebook LM 的开源实现REST API 的开发实战指南。它基于仓库内官方文档 api-reference.md并结合 api/main.py 及 api/routers 下的真实实现与测试交叉验证帮助你快速理解该项目的接口契约、认证模型、通用调用模式分页、异步任务、SSE 流式、文件上传以及错误处理与生产部署要点。读完本文你将能够直接调用 curl / 编写客户端独立完成「创建笔记本 → 导入资料 → 提问对话 → 提取洞察」的完整自动化工作流。1. API 基础Base URL 与交互式文档Open Notebook 的全部 HTTP 端点由 FastAPI 后端统一提供。按照文档约定开发环境默认 Base URL 为http://localhost:5055一个容易被忽略但极其重要的实现细节是所有业务路由统一挂载在/api前缀之下。参见 api/main.py 中数十次app.include_router(..., prefix/api, ...)的注册方式因此 notebooks、sources、search、chat、models、credentials、commands 等端点的完整路径实际是/api/notebooks、/api/sources、/api/search/ask…… 下面小节中的 curl 示例已按此真实前缀给出。FastAPI 会自动生成三套交互式文档是排查请求/响应结构与调试的首选工具Swagger UIhttp://localhost:5055/docsReDochttp://localhost:5055/redocOpenAPI Schemahttp://localhost:5055/openapi.json这三个路径连同/、/health、/api/auth/status、/api/config一起被认证中间件排除在鉴权之外见 api/auth.py 与 api/main.py因此可以直接在浏览器中打开。此外有两个用于健康检查与状态探测的根级端点无需认证端点说明GET /返回{message: Open Notebook API is running}GET /health返回{status: healthy}两者定义于 api/main.py。其中/health被 docker 编排脚本如 scripts/wait-for-api.sh用作就绪探针。2. 认证机制从开发密码到生产加固2.1 开发模式Bearer 密码认证当前版本的 API 采用单密码 Bearer 认证密码通过环境变量OPEN_NOTEBOOK_PASSWORD配置curl http://localhost:5055/api/notebooks \ -H Authorization: Bearer your_password认证逻辑在中间件 api/auth.py 中实现几点值得开发者注意的边界行为未设置密码 鉴权完全关闭PasswordAuthMiddleware的注释明确写道「Auth is fully disabled (no hardcoded default password) if OPEN_NOTEBOOK_PASSWORD is not set」即仓库没有任何硬编码默认口令支持 Docker Secrets除环境变量外还可通过OPEN_NOTEBOOK_PASSWORD_FILE从挂载的 secret 文件读取密码支持 CORS 预检OPTIONS请求跳过认证防时序侧信道密码比对使用secrets.compare_digest常量时间比较统一 401 语义缺失头、格式错误、口令不符分别返回不同的detail但都会附带WWW-Authenticate: Bearer响应头。⚠️ 文档明确警告该密码方案仅限开发环境生产环境必须替换为 OAuth 2.0推荐、JWT 或 API Key。完整的生产加固说明、Docker Secrets 配置示例与openssl rand -base64 24生成强密码的方法见 安全配置。2.2 路由装配与鉴权白名单后端进程启动时还会执行两件与安全相关的事读取并解析 CORS 白名单默认CORS_ORIGINS未设置时允许任意来源*并自动关闭allow_credentials避免通配符来源 凭据的反射风险显式设置具体的来源后才会开启凭据支持见 api/main.py 与 L225-L277在认证外层叠加请求体大小限制OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB控制单次请求体上限默认值由 api/middleware.py 的get_max_upload_size_bytes计算超出即返回带 CORS 头的 413。3. 端点总览核心资源类型官方文档将 API 归纳为几大资源族。下表结合 api/routers 的实际实现给出已确认的端点均以/api为前缀Notebooks —— 研究项目容器GET /api/notebooks—— 列表支持archived过滤与order_by排序order_by经过严格白名单校验仅允许name/created/updated与asc/desc见 notebooks.pyPOST /api/notebooks—— 新建GET /api/notebooks/{notebook_id}—— 详情响应含source_count、note_count读取时会写时打戳更新last_viewed_atPUT /api/notebooks/{notebook_id}—— 更新部分更新语义仅更新传入字段DELETE /api/notebooks/{notebook_id}—— 删除支持级联用?delete_exclusive_sourcestrue才会连带删除仅属于该笔记本的独占资料否则共享资料仅解除关联返回deleted_notes/deleted_sources/unlinked_sources统计POST /api/notebooks/{notebook_id}/sources/{source_id}/DELETE—— 为笔记本关联/移除已有资料通过 SurrealDB 图边reference实现见 notebooks.pyGET /api/notebooks/{notebook_id}/delete-preview—— 删除前预览影响范围GET /api/recently-viewed—— 最近查看的笔记本与资料limit范围 1–50默认 12Sources —— 内容单元PDF/URL/文本GET /api/sources—— 列表支持分页/排序/按笔记本过滤POST /api/sources—— 新增multipart 表单为主入口支持typeupload|link|textPOST /api/sources/json—— JSON 载荷创建向后兼容入口GET /api/sources/{source_id}—— 详情含处理状态与关联笔记本PUT /api/sources/{source_id}—— 更新标题/主题POST /api/sources/{source_id}/retry—— 对失败或卡住的资料重试处理处理中running/queued会被拒绝GET /api/sources/{source_id}/status—— 处理状态查询GET|HEAD /api/sources/{source_id}/download—— 下载原始文件带上传目录路径围栏校验POST /api/sources/{source_id}/insights—— 对资料执行自定义抽取见下文 Transformations资料的type在数据库中是计算字段有file_path即file有url即link否则为text见 sources.py。排序字段白名单为type/title/created/updated/insights_count/embedded。Notes —— 用户或 AI 生成的研究笔记GET /api/notes?notebook_id...—— 按笔记本过滤列表POST /api/notes—— 创建note_type仅允许human|aiAI 笔记未给标题时由 prompt graph 自动生成≤15 词见 notes.pyGET / PUT / DELETE /api/notes/{note_id}—— 读、改、删GET /api/notes/{note_id}/save-status等进阶端点以/docs实时展示为准Chat —— 会话式 AI 对话GET /api/chat/sessions?notebook_id...—— 笔记本下的会话列表POST /api/chat/sessions—— 创建会话支持model_override会话级模型覆盖GET /api/chat/sessions/{session_id}—— 取会话与消息消息状态由 LangGraph 线程状态恢复PUT / DELETE /api/chat/sessions/{session_id}—— 改标题/覆盖模型、删会话POST /api/chat/execute—— 发送消息并返回 AI 回复请求级model_override优先于会话级POST /api/chat/context—— 按context_config预构建笔记本上下文返回token_count与char_count估算便于在发送前核对上下文预算实现上会话通过图计算框架 LangGraph 的 checkpointerSqliteSaver持久化API 层用asyncio.to_thread包住同步的get_state/invoke避免阻塞事件循环详见 chat.py。源码级对话source chat另有/api/source-chat/...一组端点。Search / Ask —— 检索与综合问答POST /api/search—— 全文或向量检索POST /api/search/ask—— 提问并流式返回SSEPOST /api/search/ask/simple—— 同上但一次性返回 JSON非流式向量检索与 Ask 均要求已配置 embedding 模型否则返回 400提示语见 search.py 与 L148-L153。Ask 端点还会先校验strategy_model、answer_model、final_answer_model三个模型均存在。Transformations / Insights —— 自定义提示抽取洞察GET/POST /api/transformations—— 管理自定义抽取规则GET /api/sources/{source_id}/insights—— 查看资料已生成的洞察POST /api/insights/{insight_id}/save-as-note—— 把洞察转存为笔记insights.py嵌入与向量化相关另有/api/embedding与/api/embeddings/rebuild等端点Models / Credentials —— AI 供给配置GET /api/models?type...—— 列出已注册模型类型language/embedding/text_to_speech/speech_to_textPOST /api/models、DELETE /api/models/{model_id}—— 模型注册与删除同名同提供方同类型查重GET /api/models/defaults/PUT /api/models/defaults—— 默认槽位查询/更新部分更新以字段是否出现为准显式null表示清空但default_chat_model与default_embedding_model两个必要槽位只可重指派不可清空见 models.pyGET /api/models/providers—— 提供方可用性总览DB 凭据或环境变量任一存在即视为可用POST /api/models/auto-assign—— 依据提供方优先级自动填充必要默认槽位GET /api/models/discover/{provider}、POST /api/models/sync/{provider}、POST /api/models/sync—— 从提供方发现/同步模型凭据族均不返回真实 API Key仅元数据GET/POST /api/credentials、GET/PUT/DELETE /api/credentials/{id}、POST /api/credentials/{id}/test|discover|register-models、GET /api/credentials/status|env-status、POST /api/credentials/migrate-from-env见 credentials.py其它Podcasts播客生成、episode/speaker profiles、providers、capabilities、languages、settings、config、auth 等均有独立路由文件全部可经/docs查阅。4. 通用调用模式Common Patterns4.1 分页、过滤与排序# 分页limit offsetsources 的 limit 合法范围 1–100默认 50 curl http://localhost:5055/api/sources?limit20offset10 \ -H Authorization: Bearer your_password # 按笔记本过滤 按创建时间升序排序 curl http://localhost:5055/api/sources?notebook_idnotebook:abcsort_bycreatedsort_orderasc \ -H Authorization: Bearer your_password笔记本身也存在过滤GET /api/notes?notebook_idnotebook:abc。笔记本列表则可用GET /api/notebooks?archivedtrueorder_byname%20asc。4.2 异步操作Async Operations从 0.2.x 开始资料处理source processing与播客生成等耗时操作默认异步执行请求立即返回资源 ID command_id后台由 command/job 系统处理客户端轮询状态# 1) 提交异步资料处理 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typeupload \ -F notebooks[\notebook:abc\] \ -F async_processingtrue \ -F filedocument.pdf # 响应形如{id:source:src001,command_id:command:cmd123, ...}实际的轮询端点是命令command/job族# 2) 轮询 job 状态 curl http://localhost:5055/api/commands/jobs/command:cmd123 \ -H Authorization: Bearer your_password # 响应包含 statusqueued/running/completed/failed...、result、error_message、progress 等字段完整命令管理端点见 commands.py包括POST /api/commands/jobs—— 提交任意已注册命令到后台GET /api/commands/jobs/{job_id}—— 查询单个 jobGET /api/commands/jobs?command_filterstatus_filterlimit—— 过滤列表DELETE /api/commands/jobs/{job_id}—— 取消 jobGET /api/commands/registry/debug—— 调试用列出全部已注册命令注意官方文档给出的示例路径是简化的/commands/{id}以实际实现为准时应使用/api/commands/jobs/...。异步路径下源码会先落库资料记录与笔记本关联让 UI 立即可见再提交process_source命令并随后把command_id写回 source 记录若提交失败会回滚删除刚建的记录见 sources.py。同步路径则用 5 分钟超时在线执行。老资料无command字段在/status会被标记为 legacy。4.3 流式响应SSEPOST /api/search/ask以Server-Sent Events流式返回多阶段结果过程中先后产出不同type的事件载荷curl -N http://localhost:5055/api/search/ask \ -H Authorization: Bearer your_password \ -H Content-Type: application/json \ -d {question:What is AI?,strategy_model:...,answer_model:...,final_answer_model:...} # 输出形如 # data: {type:strategy,reasoning:...,searches:[{term:...,instructions:...}]} # data: {type:answer,content:...} # data: {type:final_answer,content:...} # data: {type:complete,final_answer:...}事件序列由 search.py 驱动先出strategy检索策略与子查询再逐条出answer然后是final_answer最后complete结束信号出错时输出{type:error,message:...}。响应头包含Cache-Control: no-cache、Connection: keep-alive并显式设置X-Accel-Buffering: no以穿透 Nginx 等反向代理的缓冲层。4.4 Multipart 文件上传POST /api/sources是 multipart 表单端点由 sources.py 的parse_source_form_data解析。三类内容的最小请求# 上传文件 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typeupload \ -F notebooks[\notebook:abc\] \ -F embedtrue \ -F filedocument.pdf # 抓取链接URL 需经 SSRF 校验见 _build_content_state curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typelink -F urlhttps://example.com/article \ -F notebook_idnotebook:abc # 纯文本 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typetext -F content研究素材正文... \ -F notebook_idnotebook:abc支持的表单字段还包括title、notebooksJSON 数组字符串可一次关联多个笔记本、transformationsJSON 数组字符串创建即附加抽取规则、embed是否嵌入、delete_source、async_processing。字符串布尔值接受true/1/yes/on。值得关注的工程细节均为源码确认上传文件名会剥离目录成分并做路径穿越防护同名冲突时以name (1).pdf递增并原子占位touch(exist_okFalse)防止并发覆盖竞态写盘放入线程池避免阻塞事件循环文件在真正入库前由 content-core 做类型预检不支持的类型直接 415 拒绝而非把注定失败的任务送进后台。5. 错误处理与状态码语义所有错误统一返回 JSON格式为{detail: Notebook not found}常见状态码Code含义示例200成功操作完成400错误请求输入非法、排序字段不在白名单、向量检索未配置 embedding 模型、资料正在处理中无法 retry404资源不存在笔记本/资料/会话/模型未找到409冲突资源已存在500服务器错误数据库或处理异常502上游错误外部 AI 提供方不可达由 NetworkError/ExternalServiceError 映射415不支持的类型上传了 content-core 无法抽取的文件类型状态码并非随意约定全局异常处理器把领域层异常一一映射为 HTTP 状态见 api/main.py——NotFoundError→404、InvalidInputError→400、AuthenticationError→401、RateLimitError→429、ConfigurationError→422、NetworkError/ExternalServiceError→502、UnsupportedTypeException→415。同时异常处理器会自动补写 CORS 头确保跨域环境下错误响应也能被前端读取当 Nginx 等反向代理先于应用返回 413 时需在代理层自行补 CORS 头main.py 有明确注释。测试 test_typed_exceptions_reach_handlers.py 与 test_error_message_sanitization.py 对这类映射与脱敏行为做了回归保障。6. 开发者速查清单官方文档的要点结合源码可整理为以交互式文档为权威Swagger UIhttp://localhost:5055/docs能实时展示全部端点、请求/响应 Schema优先于背记鉴权所有请求加Authorization: Bearer OPEN_NOTEBOOK_PASSWORD学习路径一节中X-Password 头的表述系历史遗留真实中间件校验的是 Bearer 头排查调试查看 API 容器日志docker logs或仓库根目录run_api.py的本地运行方式日志框架为 loguru流式端点需特殊处理SSE 不是标准 JSON 一次性返回要用可增量解析的 HTTP 客户端异步任务务必轮询提交后立即返回完成前不可假设成功轮询/api/commands/jobs/{command_id}向量检索依赖 embedding 模型先检查/api/models与默认槽位是否配置模型覆盖是每请求/每会话的放在请求体model_override或会话配置里而非全局配置文件CORS开发默认全放行生产通过CORS_ORIGINS收紧。推荐的学习路径与文档一致并补全真实路径认证为所有请求添加Authorization: Bearer头建笔记本POST /api/notebooksbody 带name与description加资料POST /api/sources用文件/URL/文本三种type提问POST /api/chat/execute对笔记本内容对话或POST /api/search/ask/simple一次问答进阶/api/search混合检索、/api/transformations自定义抽取、/api/search/askSSE 流式消费。前端同构调用可参考 frontend/src/lib/api 下的 TypeScript 客户端封装以及 frontend/src/app/api/search/ask/route.ts 对 SSE 的代理转发示例。7. 生产环境注意事项结合官方文档与当前实现上线前必须处理替换密码认证改用 OAuth 2.0 / JWT / API Key并配合CORS_ORIGINS限制前端来源见 安全配置限流通过反向代理Nginx、CloudFlare、Kong 等增加速率限制与请求体上限OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB是应用层兜底代理层可先拦截超限请求CORS 收紧默认CORS_ORIGINS未设置时允许任意来源并打印告警日志生产务必显式配置HTTPS 终结经反向代理启用 TLS并注意给流式接口关闭缓冲对应代码中X-Accel-Buffering: no的用意完整方案见 反向代理设置API 版本化当前版本策略是隐式的未暴露显式版本号对外提供服务时应自行规划/v1/...等版本策略启动自检与迁移应用在 lifespan 阶段会等待 SurrealDB 就绪并自动执行数据库迁移最多重试 12 次、指数退避 1s→5s迁移失败会 fail-fast 拒绝启动防止旧 Schema 误服务见 api/main.py。相关行为由 test_startup_migration_retry.py 覆盖凭据安全创建基于 DB 的 AI 凭据前必须先配置OPEN_NOTEBOOK_ENCRYPTION_KEY否则启动会告警、写入将失败见 main.py 与 credentials.py。完整的部署参数数据库连接、上传目录、加密密钥、CORS 等请查阅 环境变量参考 与 配置说明API 变更记录同步在 CHANGELOG.md 中维护。本文所引端点与行为均以仓库当前源码为准路由装配见 api/main.py认证中间件见 api/auth.py各资源端点见 api/routers 目录官方 API 参考原始文档位于 docs/7-DEVELOPMENT/api-reference.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 REST API 完整参考：掌握认证、核心资源与异步流式开发
Open Notebook REST API 完整参考掌握认证、核心资源与异步流式开发【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook本文是 Open NotebookNotebook LM 的开源实现REST API 的开发实战指南。它基于仓库内官方文档 api-reference.md并结合 api/main.py 及 api/routers 下的真实实现与测试交叉验证帮助你快速理解该项目的接口契约、认证模型、通用调用模式分页、异步任务、SSE 流式、文件上传以及错误处理与生产部署要点。读完本文你将能够直接调用 curl / 编写客户端独立完成「创建笔记本 → 导入资料 → 提问对话 → 提取洞察」的完整自动化工作流。1. API 基础Base URL 与交互式文档Open Notebook 的全部 HTTP 端点由 FastAPI 后端统一提供。按照文档约定开发环境默认 Base URL 为http://localhost:5055一个容易被忽略但极其重要的实现细节是所有业务路由统一挂载在/api前缀之下。参见 api/main.py 中数十次app.include_router(..., prefix/api, ...)的注册方式因此 notebooks、sources、search、chat、models、credentials、commands 等端点的完整路径实际是/api/notebooks、/api/sources、/api/search/ask…… 下面小节中的 curl 示例已按此真实前缀给出。FastAPI 会自动生成三套交互式文档是排查请求/响应结构与调试的首选工具Swagger UIhttp://localhost:5055/docsReDochttp://localhost:5055/redocOpenAPI Schemahttp://localhost:5055/openapi.json这三个路径连同/、/health、/api/auth/status、/api/config一起被认证中间件排除在鉴权之外见 api/auth.py 与 api/main.py因此可以直接在浏览器中打开。此外有两个用于健康检查与状态探测的根级端点无需认证端点说明GET /返回{message: Open Notebook API is running}GET /health返回{status: healthy}两者定义于 api/main.py。其中/health被 docker 编排脚本如 scripts/wait-for-api.sh用作就绪探针。2. 认证机制从开发密码到生产加固2.1 开发模式Bearer 密码认证当前版本的 API 采用单密码 Bearer 认证密码通过环境变量OPEN_NOTEBOOK_PASSWORD配置curl http://localhost:5055/api/notebooks \ -H Authorization: Bearer your_password认证逻辑在中间件 api/auth.py 中实现几点值得开发者注意的边界行为未设置密码 鉴权完全关闭PasswordAuthMiddleware的注释明确写道「Auth is fully disabled (no hardcoded default password) if OPEN_NOTEBOOK_PASSWORD is not set」即仓库没有任何硬编码默认口令支持 Docker Secrets除环境变量外还可通过OPEN_NOTEBOOK_PASSWORD_FILE从挂载的 secret 文件读取密码支持 CORS 预检OPTIONS请求跳过认证防时序侧信道密码比对使用secrets.compare_digest常量时间比较统一 401 语义缺失头、格式错误、口令不符分别返回不同的detail但都会附带WWW-Authenticate: Bearer响应头。⚠️ 文档明确警告该密码方案仅限开发环境生产环境必须替换为 OAuth 2.0推荐、JWT 或 API Key。完整的生产加固说明、Docker Secrets 配置示例与openssl rand -base64 24生成强密码的方法见 安全配置。2.2 路由装配与鉴权白名单后端进程启动时还会执行两件与安全相关的事读取并解析 CORS 白名单默认CORS_ORIGINS未设置时允许任意来源*并自动关闭allow_credentials避免通配符来源 凭据的反射风险显式设置具体的来源后才会开启凭据支持见 api/main.py 与 L225-L277在认证外层叠加请求体大小限制OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB控制单次请求体上限默认值由 api/middleware.py 的get_max_upload_size_bytes计算超出即返回带 CORS 头的 413。3. 端点总览核心资源类型官方文档将 API 归纳为几大资源族。下表结合 api/routers 的实际实现给出已确认的端点均以/api为前缀Notebooks —— 研究项目容器GET /api/notebooks—— 列表支持archived过滤与order_by排序order_by经过严格白名单校验仅允许name/created/updated与asc/desc见 notebooks.pyPOST /api/notebooks—— 新建GET /api/notebooks/{notebook_id}—— 详情响应含source_count、note_count读取时会写时打戳更新last_viewed_atPUT /api/notebooks/{notebook_id}—— 更新部分更新语义仅更新传入字段DELETE /api/notebooks/{notebook_id}—— 删除支持级联用?delete_exclusive_sourcestrue才会连带删除仅属于该笔记本的独占资料否则共享资料仅解除关联返回deleted_notes/deleted_sources/unlinked_sources统计POST /api/notebooks/{notebook_id}/sources/{source_id}/DELETE—— 为笔记本关联/移除已有资料通过 SurrealDB 图边reference实现见 notebooks.pyGET /api/notebooks/{notebook_id}/delete-preview—— 删除前预览影响范围GET /api/recently-viewed—— 最近查看的笔记本与资料limit范围 1–50默认 12Sources —— 内容单元PDF/URL/文本GET /api/sources—— 列表支持分页/排序/按笔记本过滤POST /api/sources—— 新增multipart 表单为主入口支持typeupload|link|textPOST /api/sources/json—— JSON 载荷创建向后兼容入口GET /api/sources/{source_id}—— 详情含处理状态与关联笔记本PUT /api/sources/{source_id}—— 更新标题/主题POST /api/sources/{source_id}/retry—— 对失败或卡住的资料重试处理处理中running/queued会被拒绝GET /api/sources/{source_id}/status—— 处理状态查询GET|HEAD /api/sources/{source_id}/download—— 下载原始文件带上传目录路径围栏校验POST /api/sources/{source_id}/insights—— 对资料执行自定义抽取见下文 Transformations资料的type在数据库中是计算字段有file_path即file有url即link否则为text见 sources.py。排序字段白名单为type/title/created/updated/insights_count/embedded。Notes —— 用户或 AI 生成的研究笔记GET /api/notes?notebook_id...—— 按笔记本过滤列表POST /api/notes—— 创建note_type仅允许human|aiAI 笔记未给标题时由 prompt graph 自动生成≤15 词见 notes.pyGET / PUT / DELETE /api/notes/{note_id}—— 读、改、删GET /api/notes/{note_id}/save-status等进阶端点以/docs实时展示为准Chat —— 会话式 AI 对话GET /api/chat/sessions?notebook_id...—— 笔记本下的会话列表POST /api/chat/sessions—— 创建会话支持model_override会话级模型覆盖GET /api/chat/sessions/{session_id}—— 取会话与消息消息状态由 LangGraph 线程状态恢复PUT / DELETE /api/chat/sessions/{session_id}—— 改标题/覆盖模型、删会话POST /api/chat/execute—— 发送消息并返回 AI 回复请求级model_override优先于会话级POST /api/chat/context—— 按context_config预构建笔记本上下文返回token_count与char_count估算便于在发送前核对上下文预算实现上会话通过图计算框架 LangGraph 的 checkpointerSqliteSaver持久化API 层用asyncio.to_thread包住同步的get_state/invoke避免阻塞事件循环详见 chat.py。源码级对话source chat另有/api/source-chat/...一组端点。Search / Ask —— 检索与综合问答POST /api/search—— 全文或向量检索POST /api/search/ask—— 提问并流式返回SSEPOST /api/search/ask/simple—— 同上但一次性返回 JSON非流式向量检索与 Ask 均要求已配置 embedding 模型否则返回 400提示语见 search.py 与 L148-L153。Ask 端点还会先校验strategy_model、answer_model、final_answer_model三个模型均存在。Transformations / Insights —— 自定义提示抽取洞察GET/POST /api/transformations—— 管理自定义抽取规则GET /api/sources/{source_id}/insights—— 查看资料已生成的洞察POST /api/insights/{insight_id}/save-as-note—— 把洞察转存为笔记insights.py嵌入与向量化相关另有/api/embedding与/api/embeddings/rebuild等端点Models / Credentials —— AI 供给配置GET /api/models?type...—— 列出已注册模型类型language/embedding/text_to_speech/speech_to_textPOST /api/models、DELETE /api/models/{model_id}—— 模型注册与删除同名同提供方同类型查重GET /api/models/defaults/PUT /api/models/defaults—— 默认槽位查询/更新部分更新以字段是否出现为准显式null表示清空但default_chat_model与default_embedding_model两个必要槽位只可重指派不可清空见 models.pyGET /api/models/providers—— 提供方可用性总览DB 凭据或环境变量任一存在即视为可用POST /api/models/auto-assign—— 依据提供方优先级自动填充必要默认槽位GET /api/models/discover/{provider}、POST /api/models/sync/{provider}、POST /api/models/sync—— 从提供方发现/同步模型凭据族均不返回真实 API Key仅元数据GET/POST /api/credentials、GET/PUT/DELETE /api/credentials/{id}、POST /api/credentials/{id}/test|discover|register-models、GET /api/credentials/status|env-status、POST /api/credentials/migrate-from-env见 credentials.py其它Podcasts播客生成、episode/speaker profiles、providers、capabilities、languages、settings、config、auth 等均有独立路由文件全部可经/docs查阅。4. 通用调用模式Common Patterns4.1 分页、过滤与排序# 分页limit offsetsources 的 limit 合法范围 1–100默认 50 curl http://localhost:5055/api/sources?limit20offset10 \ -H Authorization: Bearer your_password # 按笔记本过滤 按创建时间升序排序 curl http://localhost:5055/api/sources?notebook_idnotebook:abcsort_bycreatedsort_orderasc \ -H Authorization: Bearer your_password笔记本身也存在过滤GET /api/notes?notebook_idnotebook:abc。笔记本列表则可用GET /api/notebooks?archivedtrueorder_byname%20asc。4.2 异步操作Async Operations从 0.2.x 开始资料处理source processing与播客生成等耗时操作默认异步执行请求立即返回资源 ID command_id后台由 command/job 系统处理客户端轮询状态# 1) 提交异步资料处理 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typeupload \ -F notebooks[\notebook:abc\] \ -F async_processingtrue \ -F filedocument.pdf # 响应形如{id:source:src001,command_id:command:cmd123, ...}实际的轮询端点是命令command/job族# 2) 轮询 job 状态 curl http://localhost:5055/api/commands/jobs/command:cmd123 \ -H Authorization: Bearer your_password # 响应包含 statusqueued/running/completed/failed...、result、error_message、progress 等字段完整命令管理端点见 commands.py包括POST /api/commands/jobs—— 提交任意已注册命令到后台GET /api/commands/jobs/{job_id}—— 查询单个 jobGET /api/commands/jobs?command_filterstatus_filterlimit—— 过滤列表DELETE /api/commands/jobs/{job_id}—— 取消 jobGET /api/commands/registry/debug—— 调试用列出全部已注册命令注意官方文档给出的示例路径是简化的/commands/{id}以实际实现为准时应使用/api/commands/jobs/...。异步路径下源码会先落库资料记录与笔记本关联让 UI 立即可见再提交process_source命令并随后把command_id写回 source 记录若提交失败会回滚删除刚建的记录见 sources.py。同步路径则用 5 分钟超时在线执行。老资料无command字段在/status会被标记为 legacy。4.3 流式响应SSEPOST /api/search/ask以Server-Sent Events流式返回多阶段结果过程中先后产出不同type的事件载荷curl -N http://localhost:5055/api/search/ask \ -H Authorization: Bearer your_password \ -H Content-Type: application/json \ -d {question:What is AI?,strategy_model:...,answer_model:...,final_answer_model:...} # 输出形如 # data: {type:strategy,reasoning:...,searches:[{term:...,instructions:...}]} # data: {type:answer,content:...} # data: {type:final_answer,content:...} # data: {type:complete,final_answer:...}事件序列由 search.py 驱动先出strategy检索策略与子查询再逐条出answer然后是final_answer最后complete结束信号出错时输出{type:error,message:...}。响应头包含Cache-Control: no-cache、Connection: keep-alive并显式设置X-Accel-Buffering: no以穿透 Nginx 等反向代理的缓冲层。4.4 Multipart 文件上传POST /api/sources是 multipart 表单端点由 sources.py 的parse_source_form_data解析。三类内容的最小请求# 上传文件 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typeupload \ -F notebooks[\notebook:abc\] \ -F embedtrue \ -F filedocument.pdf # 抓取链接URL 需经 SSRF 校验见 _build_content_state curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typelink -F urlhttps://example.com/article \ -F notebook_idnotebook:abc # 纯文本 curl -X POST http://localhost:5055/api/sources \ -H Authorization: Bearer your_password \ -F typetext -F content研究素材正文... \ -F notebook_idnotebook:abc支持的表单字段还包括title、notebooksJSON 数组字符串可一次关联多个笔记本、transformationsJSON 数组字符串创建即附加抽取规则、embed是否嵌入、delete_source、async_processing。字符串布尔值接受true/1/yes/on。值得关注的工程细节均为源码确认上传文件名会剥离目录成分并做路径穿越防护同名冲突时以name (1).pdf递增并原子占位touch(exist_okFalse)防止并发覆盖竞态写盘放入线程池避免阻塞事件循环文件在真正入库前由 content-core 做类型预检不支持的类型直接 415 拒绝而非把注定失败的任务送进后台。5. 错误处理与状态码语义所有错误统一返回 JSON格式为{detail: Notebook not found}常见状态码Code含义示例200成功操作完成400错误请求输入非法、排序字段不在白名单、向量检索未配置 embedding 模型、资料正在处理中无法 retry404资源不存在笔记本/资料/会话/模型未找到409冲突资源已存在500服务器错误数据库或处理异常502上游错误外部 AI 提供方不可达由 NetworkError/ExternalServiceError 映射415不支持的类型上传了 content-core 无法抽取的文件类型状态码并非随意约定全局异常处理器把领域层异常一一映射为 HTTP 状态见 api/main.py——NotFoundError→404、InvalidInputError→400、AuthenticationError→401、RateLimitError→429、ConfigurationError→422、NetworkError/ExternalServiceError→502、UnsupportedTypeException→415。同时异常处理器会自动补写 CORS 头确保跨域环境下错误响应也能被前端读取当 Nginx 等反向代理先于应用返回 413 时需在代理层自行补 CORS 头main.py 有明确注释。测试 test_typed_exceptions_reach_handlers.py 与 test_error_message_sanitization.py 对这类映射与脱敏行为做了回归保障。6. 开发者速查清单官方文档的要点结合源码可整理为以交互式文档为权威Swagger UIhttp://localhost:5055/docs能实时展示全部端点、请求/响应 Schema优先于背记鉴权所有请求加Authorization: Bearer OPEN_NOTEBOOK_PASSWORD学习路径一节中X-Password 头的表述系历史遗留真实中间件校验的是 Bearer 头排查调试查看 API 容器日志docker logs或仓库根目录run_api.py的本地运行方式日志框架为 loguru流式端点需特殊处理SSE 不是标准 JSON 一次性返回要用可增量解析的 HTTP 客户端异步任务务必轮询提交后立即返回完成前不可假设成功轮询/api/commands/jobs/{command_id}向量检索依赖 embedding 模型先检查/api/models与默认槽位是否配置模型覆盖是每请求/每会话的放在请求体model_override或会话配置里而非全局配置文件CORS开发默认全放行生产通过CORS_ORIGINS收紧。推荐的学习路径与文档一致并补全真实路径认证为所有请求添加Authorization: Bearer头建笔记本POST /api/notebooksbody 带name与description加资料POST /api/sources用文件/URL/文本三种type提问POST /api/chat/execute对笔记本内容对话或POST /api/search/ask/simple一次问答进阶/api/search混合检索、/api/transformations自定义抽取、/api/search/askSSE 流式消费。前端同构调用可参考 frontend/src/lib/api 下的 TypeScript 客户端封装以及 frontend/src/app/api/search/ask/route.ts 对 SSE 的代理转发示例。7. 生产环境注意事项结合官方文档与当前实现上线前必须处理替换密码认证改用 OAuth 2.0 / JWT / API Key并配合CORS_ORIGINS限制前端来源见 安全配置限流通过反向代理Nginx、CloudFlare、Kong 等增加速率限制与请求体上限OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB是应用层兜底代理层可先拦截超限请求CORS 收紧默认CORS_ORIGINS未设置时允许任意来源并打印告警日志生产务必显式配置HTTPS 终结经反向代理启用 TLS并注意给流式接口关闭缓冲对应代码中X-Accel-Buffering: no的用意完整方案见 反向代理设置API 版本化当前版本策略是隐式的未暴露显式版本号对外提供服务时应自行规划/v1/...等版本策略启动自检与迁移应用在 lifespan 阶段会等待 SurrealDB 就绪并自动执行数据库迁移最多重试 12 次、指数退避 1s→5s迁移失败会 fail-fast 拒绝启动防止旧 Schema 误服务见 api/main.py。相关行为由 test_startup_migration_retry.py 覆盖凭据安全创建基于 DB 的 AI 凭据前必须先配置OPEN_NOTEBOOK_ENCRYPTION_KEY否则启动会告警、写入将失败见 main.py 与 credentials.py。完整的部署参数数据库连接、上传目录、加密密钥、CORS 等请查阅 环境变量参考 与 配置说明API 变更记录同步在 CHANGELOG.md 中维护。本文所引端点与行为均以仓库当前源码为准路由装配见 api/main.py认证中间件见 api/auth.py各资源端点见 api/routers 目录官方 API 参考原始文档位于 docs/7-DEVELOPMENT/api-reference.md。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考