企业官网建设流程全解析

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 Notebook（Notebook 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 UI：http://localhost:5055/docs
• ReDoc：http://localhost:5055/redoc
• OpenAPI Schema：http://localhost:5055/openapi.json

这三个路径连同/、/health、/api/auth/status、/api/config一起被认证中间件排除在鉴权之外（见 api/auth.py 与 api/main.py），因此可以直接在浏览器中打开。

此外有两个用于健康检查与状态探测的根级端点（无需认证）：

两者定义于 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 路由装配与鉴权白名单

后端进程启动时还会执行两件与安全相关的事：

1. 读取并解析 CORS 白名单：默认CORS_ORIGINS未设置时允许任意来源（*），并自动关闭allow_credentials，避免"通配符来源 + 凭据"的反射风险；显式设置具体的来源后才会开启凭据支持，见 api/main.py 与 L225-L277；
2. 在认证外层叠加请求体大小限制：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.py）
• POST /api/notebooks—— 新建
• GET /api/notebooks/{notebook_id}—— 详情（响应含source_count、note_count，读取时会"写时打戳"更新last_viewed_at）
• PUT /api/notebooks/{notebook_id}—— 更新（部分更新语义：仅更新传入字段）
• DELETE /api/notebooks/{notebook_id}—— 删除，支持级联；用?delete_exclusive_sources=true才会连带删除仅属于该笔记本的独占资料，否则共享资料仅解除关联（返回deleted_notes/deleted_sources/unlinked_sources统计）
• POST /api/notebooks/{notebook_id}/sources/{source_id}/DELETE—— 为笔记本关联/移除已有资料（通过 SurrealDB 图边reference实现，见 notebooks.py）
• GET /api/notebooks/{notebook_id}/delete-preview—— 删除前预览影响范围
• GET /api/recently-viewed—— 最近查看的笔记本与资料（limit范围 1–50，默认 12）

Sources —— 内容单元（PDF/URL/文本）

• GET /api/sources—— 列表，支持分页/排序/按笔记本过滤
• POST /api/sources—— 新增（multipart 表单为主入口，支持type=upload|link|text）
• POST /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|ai；AI 笔记未给标题时由 prompt graph 自动生成（≤15 词），见 notes.py
• GET / 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 的 checkpointer（SqliteSaver）持久化，API 层用asyncio.to_thread包住同步的get_state/invoke，避免阻塞事件循环，详见 chat.py。源码级对话（source chat）另有/api/source-chat/...一组端点。

Search / Ask —— 检索与综合问答

• POST /api/search—— 全文或向量检索
• POST /api/search/ask—— 提问并流式返回（SSE）
• POST /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_text）
• POST /api/models、DELETE /api/models/{model_id}—— 模型注册与删除（同名同提供方同类型查重）
• GET /api/models/defaults/PUT /api/models/defaults—— 默认槽位查询/更新（部分更新以字段"是否出现"为准，显式null表示清空，但default_chat_model与default_embedding_model两个必要槽位只可重指派不可清空，见 models.py）
• GET /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 Patterns）

4.1 分页、过滤与排序

# 分页：limit + offset（sources 的 limit 合法范围 1–100，默认 50） curl 'http://localhost:5055/api/sources?limit=20&offset=10' \ -H "Authorization: Bearer your_password" # 按笔记本过滤 + 按创建时间升序排序 curl 'http://localhost:5055/api/sources?notebook_id=notebook:abc&sort_by=created&sort_order=asc' \ -H "Authorization: Bearer your_password"

笔记本身也存在过滤：GET /api/notes?notebook_id=notebook:abc。笔记本列表则可用GET /api/notebooks?archived=true&order_by=name%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 "type=upload" \ -F "notebooks=[\"notebook:abc\"]" \ -F "async_processing=true" \ -F "file=@document.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" # 响应包含 status（queued/running/completed/failed...）、result、error_message、progress 等字段

完整命令管理端点见 commands.py，包括：

• POST /api/commands/jobs—— 提交任意已注册命令到后台
• GET /api/commands/jobs/{job_id}—— 查询单个 job
• GET /api/commands/jobs?command_filter=&status_filter=&limit=—— 过滤列表
• DELETE /api/commands/jobs/{job_id}—— 取消 job
• GET /api/commands/registry/debug—— 调试用，列出全部已注册命令

注意：官方文档给出的示例路径是简化的/commands/{id}，以实际实现为准时应使用/api/commands/jobs/...。异步路径下，源码会先落库资料记录与笔记本关联（让 UI 立即可见），再提交process_source命令，并随后把command_id写回 source 记录；若提交失败会回滚删除刚建的记录（见 sources.py）。同步路径则用 5 分钟超时在线执行。老资料（无command字段）在/status会被标记为 legacy。

4.3 流式响应（SSE）

POST /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 "type=upload" \ -F "notebooks=[\"notebook:abc\"]" \ -F "embed=true" \ -F "file=@document.pdf" # 抓取链接（URL 需经 SSRF 校验，见 _build_content_state） curl -X POST http://localhost:5055/api/sources \ -H "Authorization: Bearer your_password" \ -F "type=link" -F "url=https://example.com/article" \ -F "notebook_id=notebook:abc" # 纯文本 curl -X POST http://localhost:5055/api/sources \ -H "Authorization: Bearer your_password" \ -F "type=text" -F "content=研究素材正文..." \ -F "notebook_id=notebook:abc"

支持的表单字段还包括：title、notebooks（JSON 数组字符串，可一次关联多个笔记本）、transformations（JSON 数组字符串，创建即附加抽取规则）、embed（是否嵌入）、delete_source、async_processing。字符串布尔值接受true/1/yes/on。

值得关注的工程细节（均为源码确认）：上传文件名会剥离目录成分并做路径穿越防护，同名冲突时以name (1).pdf递增并原子占位（touch(exist_ok=False)，防止并发覆盖竞态）；写盘放入线程池避免阻塞事件循环；文件在真正入库前由 content-core 做类型预检，不支持的类型直接 415 拒绝而非把注定失败的任务送进后台。

5. 错误处理与状态码语义

所有错误统一返回 JSON，格式为：

{"detail": "Notebook not found"}

常见状态码

状态码并非随意约定：全局异常处理器把领域层异常一一映射为 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. 开发者速查清单

官方文档的要点结合源码可整理为：

1. 以交互式文档为权威：Swagger UI（http://localhost:5055/docs）能实时展示全部端点、请求/响应 Schema，优先于背记；
2. 鉴权：所有请求加Authorization: Bearer <OPEN_NOTEBOOK_PASSWORD>（学习路径一节中"X-Password 头"的表述系历史遗留，真实中间件校验的是 Bearer 头）；
3. 排查调试：查看 API 容器日志（docker logs）或仓库根目录run_api.py的本地运行方式；日志框架为 loguru；
4. 流式端点需特殊处理：SSE 不是标准 JSON 一次性返回，要用可增量解析的 HTTP 客户端；
5. 异步任务务必轮询：提交后立即返回，完成前不可假设成功；轮询/api/commands/jobs/{command_id}；
6. 向量检索依赖 embedding 模型：先检查/api/models与默认槽位是否配置；
7. 模型覆盖是"每请求/每会话"的：放在请求体（model_override）或会话配置里，而非全局配置文件；
8. CORS：开发默认全放行；生产通过CORS_ORIGINS收紧。

推荐的学习路径（与文档一致并补全真实路径）：

1. 认证：为所有请求添加Authorization: Bearer头；
2. 建笔记本：POST /api/notebooks（body 带name与description）；
3. 加资料：POST /api/sources，用文件/URL/文本三种type；
4. 提问：POST /api/chat/execute对笔记本内容对话，或POST /api/search/ask/simple一次问答；
5. 进阶：/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