Open Notebook 接入 OpenAI-Compatible 服务商完整指南：LM Studio / vLLM / Text Generation WebUI 等本地推理服务配置实战

Open Notebook 接入 OpenAI-Compatible 服务商完整指南LM Studio / vLLM / Text Generation WebUI 等本地推理服务配置实战【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebookOpen Notebook开源 Notebook LM 实现允许通过标准的 OpenAI API 格式连接任意推理服务从而把 LM Studio、vLLM、Text Generation WebUI、llama.cpp server、LocalAI 等本地或自建模型服务器接入到文档问答、笔记处理与 AI 播客工作流中。本文以 docs/5-CONFIGURATION/openai-compatible.md 为主线结合仓库中 provider 注册表、连接测试器与模型发现模块的源码实现为你讲解 OpenAI-Compatible 凭据与模型的完整配置方法、Docker 网络要点、多模态按需分流以及故障排查手段。阅读提醒本文描述的是“自建/本地推理服务”接入方式。若你使用的是 Ollama 或 oMLX项目提供了原生 Provider见 Ollama 配置 与 oMLX 配置不必走 OpenAI-Compatible 通道而 OpenAI、Anthropic、Google 等云端厂商的接入方式请参考 AI 服务商总览。什么是 OpenAI-Compatible所谓“OpenAI-Compatible”是指服务商实现与 OpenAI 相同或子集的 HTTP API 契约。只要服务器实现了以下任一接口形态Open Notebook 就能直接对接POST /v1/chat/completions POST /v1/embeddings POST /v1/audio/speech也就是说Open Notebook 并不关心模型权重来自哪里只关心服务是否用这一套请求/响应格式对外提供能力。只要格式兼容Chat 语言模型、Embedding 向量模型、TTS 语音合成与 STT 语音识别都能被统一接入。常见兼容服务器一览服务器适用场景默认端口/地址LM Studio桌面 GUI开箱即用地跑本地模型http://localhost:1234/v1Text Generation WebUI功能完整的本地推理oobaboogahttp://localhost:5000/v1vLLM高性能服务化推理http://localhost:8000/v1Ollama简单的本地模型管理建议使用原生 Provider见 Ollama 配置oMLXApple Silicon / MLX建议使用原生 Provider见 oMLX 配置LocalAI本地 AI 推理按安装配置llama.cpp server轻量级推理按启动参数指定在源码中的定位在 Open Notebook 的 Provider 体系里openai_compatible是一个一等公民 Provider。你可以在 open_notebook/ai/provider_registry.py 的 Provider 注册表中看到它的规格定义ProviderSpec( nameopenai_compatible, display_nameOpenAI Compatible, modalities_ALL_MODALITIES, # language / embedding / speech_to_text / text_to_speech required_any_env(OPENAI_COMPATIBLE_BASE_URL, OPENAI_COMPATIBLE_API_KEY), test_modelNone, # Dynamic - uses first available model docs_url.../docs/5-CONFIGURATION/openai-compatible.md, ),这一段源码透露了几个关键事实该 Provider 支持全部四种模态_ALL_MODALITIES (language, embedding, speech_to_text, text_to_speech)因此一套凭据理论上可以为文档嵌入、聊天、播客 TTS/STT 提供模型来源。它的注册要求是“BASE_URL 与 API_KEY 至少配置其一”required_any_env这正是“本地服务通常不需要真实 Key只要一个占位符”的底层依据。test_modelNone表示连接测试不依赖固定模型名而是动态获取服务器的模型列表进行探测详见下文“连接测试原理”。该注册表同时是 API 与前端渲染 Provider 列表的唯一数据源GET /api/providers直接返回PROVIDERS.values()前端 “Settings” 中的 Provider 下拉项即由此生成参见 provider_registry.py 头注释。快速上手以 LM Studio 为例Step 1安装并启动 LM Studio从 lmstudio.ai 下载并安装 LM Studio启动后下载一个模型例如 Llama 3 系列在应用内启动本地推理服务器默认端口1234。启动后即可用 curl 快速验证服务是否就绪curl http://localhost:1234/v1/models若返回形如{object:list,data:[{id:...,object:model,...}]}的 JSON说明本地 API 已可用。Step 2在设置界面中添加凭据推荐进入Settings设置→ API Keys点击Add Credential添加凭据Provider 选择OpenAI-Compatible填写 Base URLDocker 部署http://host.docker.internal:1234/v1本机直接运行http://localhost:1234/v1API Key 填写占位符lm-studioLM Studio 本身不校验 Key但部分客户端要求非空点击Save保存再点击Test Connection测试连接。凭据以credential记录形式存储于 SurrealDB 中API Key 在落库前会加密见 open_notebook/domain/credential.py 的_prepare_save_data。运行期会由 key_provider.py 的_provision_openai_compatible()把库中的 Key/Base URL 反写为OPENAI_COMPATIBLE_*环境变量供底层推理库使用——这就是“数据库优先、环境变量兜底”的配置机制。Step 3在 Open Notebook 中添加模型进入Settings设置→ Models点击Add Model添加模型按下表配置Provider服务商openai_compatibleModel Name模型名与 LM Studio 中加载的模型名完全一致Display Name显示名例如LM Studio - Llama 3点击Save保存。保存后该模型会出现在model表中并绑定到该凭据之后即可在默认模型下拉框中选用它参考 open_notebook/ai/models.py 的Model域模型name/provider/type/credential。配置方式Settings UI 与已废弃的环境变量通过 Settings UI 配置推荐OpenAI-Compatible Provider 的标准配置路径都在设置界面完成进入Settings → API Keys点击Add Credential → OpenAI-Compatible填写 Base URL 与 API Key本地服务如不需要可填占位符可选为 LLM、Embedding、TTS、STT 分别配置独立的服务 URL详见下文“一凭据多服务地址”点击Save随后Test Connection。遗留方式环境变量Deprecated已弃用以下环境变量为历史兼容方案建议改用 Settings UI。环境变量方式仍被 key_provider.py 作为“环境变量兜底”保留当数据库中没有对应凭据时模型创建与请求会读取这些变量。语言模型ChatOPENAI_COMPATIBLE_BASE_URLhttp://localhost:1234/v1 OPENAI_COMPATIBLE_API_KEYoptional-api-keyEmbedding向量化OPENAI_COMPATIBLE_BASE_URL_EMBEDDINGhttp://localhost:1234/v1 OPENAI_COMPATIBLE_API_KEY_EMBEDDINGoptional-api-keyText-to-Speech语音合成OPENAI_COMPATIBLE_BASE_URL_TTShttp://localhost:8969/v1 OPENAI_COMPATIBLE_API_KEY_TTSoptional-api-keySpeech-to-Text语音识别OPENAI_COMPATIBLE_BASE_URL_STThttp://localhost:9000/v1 OPENAI_COMPATIBLE_API_KEY_STToptional-api-key这组变量与 UI 中“每模态独立 URL”的能力一一对应。注意 UI 配置是持久化优先的模型发现逻辑discover_openai_compatible_models()model_discovery.py会先尝试从credential记录读取base_url/api_key读不到才回退到环境变量。所以如果你同时设置了环境变量与数据库凭据数据库中的值优先。Docker 部署下的网络连通性当 Open Notebook 运行在 Docker 容器中、而你的兼容服务器运行在宿主机上时localhost指向的是容器自身必须换用宿主机可达地址macOS / WindowsDocker DesktopBase URLhttp://host.docker.internal:1234/v1Linux方案 1 —— Docker 网桥 IPBase URLhttp://172.17.0.1:1234/v1方案 2 —— 使用宿主机网络模式启动容器docker run --network host ...此时容器与宿主机共享网络栈可直接使用http://localhost:1234/v1同一 Docker 网络内推荐用于 compose 编排# docker-compose.yml services: open-notebook: # ... lm-studio: # 你的 LM Studio 容器 ports: - 1234:1234此时在Settings → API Keys中填写服务名而非 IPhttp://lm-studio:1234/v1源码佐证Open Notebook 侧的连接测试connection_tester.py会对 Base URL 做DNS 固定pinned再请求prepare_pinned_http_target即先验证 URL 合法性再在请求时解析并锁定目标地址以缩小 DNS rebinding 的 TOCTOU 风险窗口。因此你填写的 Base URL 必须能解析到可路由的服务地址。Text Generation WebUI 接入以启用 API 的方式启动python server.py --api --listen--api开启 OpenAI 兼容的 API 端点--listen允许外部访问Docker 场景必需。在 Open Notebook 中配置在Settings → API Keys中添加一条OpenAI-Compatible凭据Base URL 填http://localhost:5000/v1Docker Compose 编排示例# 加入你的 docker-compose.yml需要 surrealdb 服务见安装指南 services: text-gen: image: atinoda/text-generation-webui:default ports: - 5000:5000 - 7860:7860 volumes: - ./models:/app/models command: --api --listen open-notebook: image: lfnovo/open_notebook:v1-latest pull_policy: always depends_on: - text-gen随后在Settings → API Keys中添加OpenAI-Compatible凭据Base URL 填http://text-gen:5000/v1vLLM 接入启动 vLLM 服务python -m vllm.entrypoints.openai.api_server \ --model meta-llama/Llama-3.1-8B-Instruct \ --port 8000在 Open Notebook 中配置在Settings → API Keys中添加OpenAI-Compatible凭据Base URL 填http://localhost:8000/v1带 GPU 的 Docker Compose 编排# 加入你的 docker-compose.yml需要 surrealdb 服务见安装指南 services: vllm: image: vllm/vllm-openai:latest command: --model meta-llama/Llama-3.1-8B-Instruct ports: # 仅监听 localhostvLLM 默认无鉴权映射到宿主机 8001 # 因为 SurrealDB 已占用 8000。Open Notebook 始终通过 # compose 网络内的 http://vllm:8000/v1 访问 vLLM。 - 127.0.0.1:8001:8000 volumes: - ~/.cache/huggingface:/root/.cache/huggingface deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] open-notebook: image: lfnovo/open_notebook:v1-latest pull_policy: always depends_on: - vllm注意示例中两个细节其一vLLM 默认不带鉴权因此宿主机端口刻意127.0.0.1绑定避免暴露公网其二8000 已被 SurrealDB 占用因此映射到宿主机的 8001但容器间互访仍用 compose 内部地址http://vllm:8000/v1。然后添加OpenAI-Compatible凭据Base URL 填http://vllm:8000/v1在 Open Notebook 中添加模型通过 Settings UI进入Settings → Models在对应分区点击Add ModelProvider选择openai_compatibleModel Name必须与服务器期望的模型名完全一致Display Name填写你便于识别的名称点击Save。模型名称格式不同服务器对“模型名”的语义不同务必按其格式填写服务器模型名格式LM Studio与 LM Studio UI 中显示的一致vLLMHuggingFace 模型路径如meta-llama/Llama-3.1-8B-InstructText Generation WebUI与 UI 中加载的名称一致llama.cpp模型文件名如llama-3-8b-q4_k_m.gguf模型名不匹配时服务器通常会返回 “model not found”。你可以先调用服务器的模型列表端点核对见下节“测试连接”。模型自动发现Discover除了手动添加Open Notebook 还支持“一键发现并注册”。后端路由POST /credentials/{id}/discover见 api/routers/credentials.py会调用discover_with_config对于openai_compatible凭据底层实现是 model_discovery.py 的discover_openai_compatible_models()其流程为先从credential读取base_url与api_key为空时回退到环境变量请求GET {base_url}/models自动避免/models重复拼接见_models_endpoint携带Authorization: Bearer {key}对返回的每个模型id调用classify_model_type(id, openai)按命名规律归类为language/embedding/speech_to_text/text_to_speech如text-embedding→ embedding、whisper→ STT、tts→ TTS无法识别默认归为language去重后批量写入model表sync_provider_models先批量查库避免 N1。发现失败如 HTTP 状态码错误只会记录警告日志并返回空列表不会中断整个流程。你可以在该弹窗中审阅分类结果后确认注册。测试连接直接测试 API 端点# 测试 chat completions curl http://localhost:1234/v1/chat/completions \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: Hello}] }# 列出服务器可用模型对照“模型名”填写是否正确 curl http://localhost:1234/v1/models从容器内部测试docker exec -it open-notebook curl http://host.docker.internal:1234/v1/models连接测试原理源码级Settings 里的Test Connection背后是两套测试逻辑见 api/credentials_service.py 与 connection_tester.py凭据级连接测试对openai_compatible执行_test_openai_compatible_connection(base_url, api_key)。它请求GET {base_url}/models自动处理已带/models后缀的情况对返回的data数组取前几个模型名拼入成功提示。关键判定逻辑在classify_provider_test_error()只有401Key 无效、403权限不足与连接/超时才算失败而“模型不存在/已下线、被限流429/quota”都视为“凭据与端点工作正常”——因为能到达模型层本身就证明了连接可用。测试成功后界面会显示类似Connected. N models available: xxx, yyy ...。模型级测试对已注册的单个模型调用test_individual_model()它会用底层 esperanto 库真的发一次请求——语言模型发Hi!、Embedding 模型嵌入This is a test.并回显维度、TTS 用默认音色openai_compatible默认音色为alloy合成一段音频并回显字节数、STT 用仓库自带的语音样本assets/test_speech.mp3做真实转写并回显文本。故障排查TroubleshootingConnection Refused连接被拒绝问题无法连接到服务器 排查步骤 1. 确认服务器正在运行 2. 确认端口号填写正确 3. 用 curl 直连测试见上文 4. 检查 Docker 网络容器内需用 host.docker.internal / 网桥 IP / 服务名 5. 确认防火墙放行该端口Model Not Found模型不存在问题服务器返回 model not found 排查步骤 1. 确认模型已在服务器中加载 2. 核对模型名拼写是否与服务端完全一致 3. 列出可用模型curl http://localhost:1234/v1/models 4. 更新 Open Notebook 中的模型名Slow Responses响应缓慢问题请求耗时过长 优化建议 1. 检查服务器资源占用内存、GPU 2. 换用更小或量化后的模型 3. 缩短上下文长度 4. 启用 GPU 加速若硬件支持Authentication Errors鉴权失败问题返回 401 或鉴权失败 排查步骤 1. 确认服务器是否真的要求 API Key 2. 在凭据中设置 API KeySettings → API Keys 3. 部分服务器要求“非空即可”可填占位符如 not-needed结合源码补充连接测试返回的鉴权类错误文案即来自_test_openai_compatible_connection的 401/403 分支Invalid API key/API key lacks required permissions错误信息不会回显完整异常原文避免把内部实现细节暴露给前端。Timeout Errors请求超时问题请求超时 排查步骤 1. 模型可能仍在加载首次请求通常较慢 2. 适当增大超时设置 3. 查看服务器日志定位错误 4. 减小请求体/上下文体积一凭据多服务地址为不同任务分流到不同服务器OpenAI-Compatible 的价值之一是“模型多样化”你完全可以让 Chat 走一台机器、Embedding 走另一台、语音合成与识别各走各的。在Settings → API Keys添加OpenAI-Compatible凭据时可以按需配置LLM URL例如http://localhost:1234/v1LM Studio 的语言模型Embedding URL例如http://localhost:8080/v1另一台服务器的向量模型TTS URL例如http://localhost:8969/v1Speaches 语音合成STT URL例如http://localhost:9000/v1Speaches 语音识别这些字段分别落库为base_url与endpoint_llm/endpoint_embedding/endpoint_stt/endpoint_tts见 open_notebook/domain/credential.py并由to_esperanto_config()转换为 esperanto 底层的按模态配置键实现真正意义上的“一套凭据、四种模态、四台服务器”。另外也可以为每个用途单独添加一条凭据各自带独立 Base URL再为模型分别绑定对应凭据。具体到 TTS/STT 的落地配置参考 本地 TTSSpeaches配置 与 本地 STTSpeaches配置。性能与资源选型建议模型规模与硬件模型参数量所需内存RAM推理速度7B8GB快13B16GB中70B64GB慢量化使用量化模型Q4、Q5可在显著降低内存占用的同时保持较快的推理llama-3-8b-q4_k_m.gguf → ~4GB RAM速度快 llama-3-8b-f16.gguf → ~16GB RAM速度慢GPU 加速在推理服务器侧开启 GPU 可大幅提速LM StudioSettings → GPU layersvLLMCUDA 环境下自动启用llama.cpp--n-gpu-layers 35小贴士若你的嵌入式向量模型或小模型追求极低延迟可优先选择量化 GGUF llama.cpp 这类轻量栈若追求高并发吞吐vLLM 的 PagedAttention 与连续批处理更具优势。这些都是选型层面的经验性建议实际表现请以本机实测为准。原生 Provider vs OpenAI-Compatible如何选择维度原生 Provider如 Ollama/oMLXOpenAI-Compatible配置只需填 API Key / 少量参数需要部署服务器 手动配置模型固定为官方模型目录任意兼容模型自由度最高成本按 token 计费云端本地运行通常免费速度通常较快托管/专用取决于你的硬件功能深度集成、完整支持基础能力子集推荐使用 OpenAI-Compatible 的场景运行本地模型隐私敏感、离线环境使用自定义/微调模型原生 Provider 目录里没有的对数据隐私有硬性要求希望请求不出本机需要精细化成本控制。提示如果你已经在跑 Ollama 或 oMLX项目提供了原生 Provider支持更贴合的默认上下文配置如 Ollama 的num_ctx上下文窗口调优因此官方建议优先使用原生通道见 Ollama 配置 与 oMLX 配置OpenAI-Compatible 更适合上述四类“非标”场景。相关文档本地 TTSSpeaches配置 —— 本地文本转语音本地 STTSpeaches配置 —— 本地语音转文本AI 服务商总览 —— 全部 Provider 选项Ollama 配置 —— 原生 Ollama 集成oMLX 配置 —— 原生 oMLXApple Silicon集成配置与高级选项 —— 更多系统级配置AI 上下文与 RAG 说明 —— 理解模型在问答链路中的角色小结OpenAI-Compatible 通道是 Open Notebook 连接“自家模型”的标准桥梁只需一个 Base URL 一个多半是占位符的API Key就能把 LM Studio、vLLM、Text Generation WebUI、llama.cpp server、LocalAI 等任意符合 OpenAI API 契约的服务变成文档问答与内容处理引擎。配置时把握四个要点即可模型名必须与服务端完全一致用/v1/models核对容器部署注意网络边界host.docker.internal/ 网桥 IP / compose 服务名测试连接看三类错误401 鉴权、403 权限、网络/超时——其余“模型不可用”不代表连接失败按需为 LLM / Embedding / TTS / STT 拆分服务地址把不同负载交给最合适的服务器。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考