Karakeep 多模型 AI Provider 接入完全指南OpenAI、Ollama、Gemini、Azure 与 Embedding 配置详解【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本文基于 Karakeep原 Hoarderv0.33.0 官方文档 02-different-ai-providers.md系统讲解如何为自托管的收藏夹应用配置不同的大语言模型LLM推理与向量嵌入Embedding服务。Karakeep 使用 LLM 完成书签的自动打标签AI tagging与自动摘要summarization并使用 Embedding 模型支撑语义搜索与标签建议优化。读完本文你将掌握 OpenAI 兼容 API 的通用接入原理、Ollama 本地推理的两种接入方式以及 Gemini、OpenRouter、Perplexity、Azure、Cloudflare 等主流提供商的具体配置方法并能正确调校 Embedding 模型的维度与上下文长度避免因配置不一致导致服务启动失败。一、先理解 Karakeep 的 AI 架构推理与嵌入是两条独立链路在动手配置前先厘清 Karakeep 中 AI 能力的两大组成部分这决定了你后续该配置哪些环境变量。从 packages/shared/config.ts 的配置解析逻辑可以看到服务端配置被拆分为inference推理与embedding嵌入两块推理链路inference负责文本打标签与摘要生成使用INFERENCE_TEXT_MODEL文本模型与INFERENCE_IMAGE_MODEL图像模型支持视觉能力例如识别图片书签并打标签嵌入链路embedding负责将书签内容转换为向量用于语义搜索semantic search与标签建议的精细化使用EMBEDDING_TEXT_MODEL。两者的是否已配置判定条件也各不相同见 packages/shared/config.ts推理链路配置完成的标志设置了OPENAI_API_KEY或OLLAMA_BASE_URL之一嵌入链路配置完成的标志设置了OPENAI_API_KEY、OLLAMA_BASE_URL或EMBEDDING_OPENAI_BASE_URL之一。这意味着即使你只配置了 Ollama 做本地打标签只要 Ollama 上拉取了合适的嵌入模型嵌入链路也能自动复用同一地址工作而如果你把推理和嵌入分别指向不同的提供商则需要显式设置EMBEDDING_OPENAI_*系列变量。在客户端工厂层面packages/shared/inference.ts 中的InferenceClientFactory与EmbeddingClientFactory展示了实际的客户端选择顺序InferenceClientFactory.build()优先使用 OpenAI 兼容客户端只要设置了OPENAI_API_KEY否则回退到 Ollama 原生客户端设置了OLLAMA_BASE_URLEmbeddingClientFactory.build()优先使用独立嵌入配置EMBEDDING_OPENAI_API_KEY或EMBEDDING_OPENAI_BASE_URL未设置时回退到推理链路的 OpenAI 配置最后才回退到推理客户端本身此时嵌入与推理共享同一提供商。// packages/shared/inference.ts — 客户端选择逻辑节选 if (serverConfig.inference.openAIApiKey) { return OpenAIInferenceClient.fromConfig(); } if (serverConfig.inference.ollamaBaseUrl) { return OllamaInferenceClient.fromConfig(); }理解这一点后下面针对不同提供商的配置就水到渠成了。二、OpenAI 官方最简单的一条路如果直接使用 OpenAI 官方 API只需设置OPENAI_API_KEY一个变量即可不需要指定OPENAI_BASE_URL官方地址是 SDK 内置默认值。OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 如需覆盖默认模型取消注释并按需选择模型 # INFERENCE_TEXT_MODELgpt-4.1-mini # INFERENCE_IMAGE_MODELgpt-4o-mini # EMBEDDING_TEXT_MODELtext-embedding-3-small # EMBEDDING_DIMENSIONS1536 # EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE1536相关变量的默认值可在 packages/shared/config.ts 中确认变量默认值说明INFERENCE_TEXT_MODELgpt-5.6-luna文本推理打标签/摘要模型INFERENCE_IMAGE_MODELgpt-4o-mini图像推理模型需支持视觉 APIEMBEDDING_TEXT_MODELtext-embedding-3-small文本嵌入模型EMBEDDING_DIMENSIONS1536向量库期望的嵌入维度EMBEDDING_CONTEXT_LENGTH8000传入嵌入模型的最大字符数超长内容会被截断需要注意EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE与EMBEDDING_DIMENSIONS的关系前者用于向支持可变输出维度的嵌入模型如 text-embedding-3 系列请求指定维度的向量其值必须与EMBEDDING_DIMENSIONS一致。这一校验是硬性的——在 packages/shared/config.ts 中若两者不相等配置解析会直接抛出致命错误导致服务无法启动if ( obj.embedding.textModelDimensionOverride ! undefined obj.embedding.textModelDimensionOverride ! obj.embedding.dimensions ) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE must match EMBEDDING_DIMENSIONS, fatal: true, }); }三、Ollama本地推理的两种接入方式Ollama 是 Karakeep 官方支持的本地 LLM 服务器。使用 Ollama 时你需要把 Ollama 的地址传给 Karakeep并确保该地址能从 Karakeep 容器内部访问例如在 docker-compose 中使用服务名ollama:11434而不是localhost:11434。官方文档明确给出了两种 API 接入方式推荐优先使用第一种。方式一OpenAI 兼容 API推荐Ollama 提供/v1的 OpenAI 兼容端点它会自动处理消息格式化兼容性更好尤其适合那些对聊天格式有特殊要求的模型如 OpenAI 的 gpt-oss 系列。OPENAI_API_KEYollama OPENAI_BASE_URLhttp://ollama.mylab.com:11434/v1 # 先确保这些模型已在 ollama 中 pull 过 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava EMBEDDING_TEXT_MODELembeddinggemma EMBEDDING_DIMENSIONS768 EMBEDDING_CONTEXT_LENGTH2048这里OPENAI_API_KEY的值可以是任意占位字符串示例用ollama因为请求会通过 OpenAI 兼容层转发给本地 Ollama鉴权并不真正发生。注意EMBEDDING_CONTEXT_LENGTH默认是 8000而 embeddinggemma 类模型的上下文较短需要按模型实际能力下调。方式二Ollama 原生 API也可以直接使用 Ollama 原生 API此时绝对不能设置OPENAI_API_KEY否则会优先走 OpenAI 兼容链路导致原生配置不生效。# 注意不要设置 OPENAI_API_KEY否则它优先于 OLLAMA_BASE_URL OLLAMA_BASE_URLhttp://ollama.mylab.com:11434 # 先确保这些模型已在 ollama 中 pull 过 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava EMBEDDING_TEXT_MODELembeddinggemma EMBEDDING_DIMENSIONS768 EMBEDDING_CONTEXT_LENGTH2048 # 如果模型不支持结构化输出还需要 # INFERENCE_OUTPUT_SCHEMAplain在源码层面Ollama 原生客户端的行为可以在 packages/shared/inference.ts 的OllamaInferenceClient中看到它使用ollama.generate流式接口将INFERENCE_CONTEXT_LENGTH映射为num_ctx、将INFERENCE_MAX_OUTPUT_TOKENS映射为num_predict并支持OLLAMA_KEEP_ALIVE控制模型在内存中的驻留时间例如5m表示 5 分钟-1m表示常驻0表示用完即卸载见 01-environment-variables.md。:::tip 经验提示 如果你在 Ollama 上遇到某些模型输出异常尤其是不支持结构化输出或对聊天格式敏感的场景官方建议改用 OpenAI 兼容 API 端点。此外Ollama 运行在无独立 GPU 的机器上时推理可能较慢可适当调大INFERENCE_JOB_TIMEOUT_SEC默认 30 秒与INFERENCE_FETCH_TIMEOUT_SEC默认 300 秒。 :::四、Gemini通过 OpenAI 兼容端点接入Google Gemini 提供了 OpenAI 兼容 API需要先从 Google AI Studio 获取 API Key且即使使用免费额度也需要配置结算账号billing account。OPENAI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta OPENAI_API_KEYYOUR_API_KEY # 示例模型 INFERENCE_TEXT_MODELgemini-2.5-flash-lite INFERENCE_IMAGE_MODELgemini-2.5-flash-lite EMBEDDING_TEXT_MODELgemini-embedding-2 EMBEDDING_DIMENSIONS3072由于 Gemini 走的是 OpenAI 兼容层其鉴权、请求格式均由 Karakeep 的OpenAIInferenceClient统一处理见 packages/shared/inference.ts因此无需额外代码适配。五、OpenRouter、Perplexity聚合平台与搜索型 APIOpenRouterOpenRouter 聚合了多个厂商的模型同样暴露 OpenAI 兼容的/api/v1端点。模型名需要按provider/model的完整格式填写OPENAI_BASE_URLhttps://openrouter.ai/api/v1 OPENAI_API_KEYYOUR_API_KEY # 示例模型 INFERENCE_TEXT_MODELmeta-llama/llama-4-scout INFERENCE_IMAGE_MODELmeta-llama/llama-4-scout EMBEDDING_TEXT_MODELopenai/text-embedding-3-smallPerplexityPerplexity 以搜索增强的sonar系列模型闻名接入方式同样简单OPENAI_BASE_URLhttps://api.perplexity.ai OPENAI_API_KEYYOUR_PERPLEXITY_API_KEY INFERENCE_TEXT_MODELsonar-pro INFERENCE_IMAGE_MODELsonar-pro六、Azure注意模型名是部署名Azure 提供 OpenAI 兼容 API。API Key 可以在 Azure AI Foundry 门户的 Overview 页面获取或在 Azure 门户中对应资源的 Keys Endpoints 处获取。:::warning 关键陷阱 Azure 中INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL填写的必须是部署名deployment name而不是基础模型名。部署名是你在部署模型时指定的名称可能与基础模型名不同例如基础模型是gpt-4o部署名可能是my-gpt4o-prod。 :::# 通过 Azure AI Foundry 部署 OPENAI_BASE_URLhttps://{your-azure-ai-foundry-resource-name}.cognitiveservices.azure.com/openai/v1/ # 通过 Azure OpenAI Service 部署 OPENAI_BASE_URLhttps://{your-azure-openai-resource-name}.openai.azure.com/openai/v1/ OPENAI_API_KEYYOUR_API_KEY INFERENCE_TEXT_MODELYOUR_DEPLOYMENT_NAME INFERENCE_IMAGE_MODELYOUR_DEPLOYMENT_NAME七、CloudflareWorkers AI 的 OpenAI 兼容端点Cloudflare Workers AI 同样支持 OpenAI 兼容端点API Token 需要从 Cloudflare 控制台的 Workers AI 页面生成。模型名使用 Cloudflare 的cf/...命名空间格式OPENAI_BASE_URLhttps://api.cloudflare.com/client/v4/accounts/{your-account-id}/ai/v1 OPENAI_API_KEYYour Cloudflare Workers AI Token # 示例模型 INFERENCE_TEXT_MODELcf/meta/llama-3.1-8b-instruct-fast INFERENCE_IMAGE_MODELcf/meta/llama-3.2-11b-vision-instruct EMBEDDING_TEXT_MODELcf/google/embeddinggemma-300m EMBEDDING_DIMENSIONS768 EMBEDDING_CONTEXT_LENGTH2048 INFERENCE_OUTPUT_SCHEMAjson注意 Cloudflare 示例中显式设置了INFERENCE_OUTPUT_SCHEMAjson。这是因为部分模型不支持 Karakeep 默认的structured输出模式需要降级为 JSON 模式。下文专门解释这一参数。八、深入理解INFERENCE_OUTPUT_SCHEMA结构化、JSON 与纯文本INFERENCE_OUTPUT_SCHEMA是接入非 OpenAI 官方模型时最常需要调整的参数之一可取值structured、json、plain默认structured见 packages/shared/config.ts。它控制打标签/摘要时如何约束模型的输出格式取值含义适用场景structured使用 Zod 生成 JSON Schema通过response_format严格约束输出OpenAI 的 structured output / Ollama 的 JSON Schema format首选模型支持结构化输出时质量最高json仅要求模型输出 JSONOpenAI 的json_object模式 / Ollama 的format: json模型不支持结构化输出但支持 JSON 模式plain不约束格式依赖模型自然输出兜底方案所有模型都支持但输出格式可能不稳定在源码 packages/shared/inference.ts 中OpenAI 链路的映射逻辑清晰可见structured对应zodResponseFormat(schema, schema)json对应{ type: json_object }plain则不设置response_format。Ollama 链路同文件第 466-476 行的映射为structured使用 Zod 4 原生 JSON Schema 发射器z.toJSONSchema(...)json使用jsonplain不设置format。注INFERENCE_SUPPORTS_STRUCTURED_OUTPUT已被官方标记为DEPRECATED应改用INFERENCE_OUTPUT_SCHEMA。设为true等价于structured设为false等价于plain。九、Embedding 模型维度、上下文与独立提供商9.1 三个核心参数Karakeep 使用嵌入模型支撑语义搜索与标签建议精化。配置嵌入模型时通常需要同时设定维度与上下文长度EMBEDDING_TEXT_MODEL EMBEDDING_DIMENSIONS EMBEDDING_CONTEXT_LENGTHEMBEDDING_TEXT_MODEL用于生成文本向量的模型名EMBEDDING_DIMENSIONS向量库vector store期望的向量维度必须与嵌入模型/提供商的实际输出一致默认 1536EMBEDDING_CONTEXT_LENGTH传入嵌入模型的最大字符数书签内容超过此长度会被截断默认 8000。9.2 嵌入链路使用独立的提供商嵌入请求可以指向与推理不同的 OpenAI 兼容提供商两个覆盖项各自独立未设置的值会回退到对应的OPENAI_*配置EMBEDDING_OPENAI_API_KEYembedding-provider-api-key EMBEDDING_OPENAI_BASE_URLhttps://embedding-provider.example.com/v1从 packages/shared/config.ts 可以看到EMBEDDING_OPENAI_BASE_URL的设置会单独点亮嵌入链路的isConfigured而 packages/shared/inference.ts 的EmbeddingClientFactory会优先使用这套独立配置未设置时再回退到推理配置。9.3 可变维度模型的覆盖参数对于支持多种输出维度的嵌入模型如 OpenAI text-embedding-3 系列用EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE向提供商请求指定维度EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE768 EMBEDDING_DIMENSIONS768再次强调两者的值必须一致否则 Karakeep 会拒绝启动校验逻辑见 packages/shared/config.ts。在请求发出时packages/shared/inference.ts 中的OpenAIEmbeddingClient.generateEmbeddingFromText会把该覆盖值作为dimensions参数传给 OpenAI 兼容端点。9.4 开启自动嵌入索引配置好嵌入模型后还需要开启书签的自动嵌入生成EMBEDDING_ENABLE_AUTO_INDEXINGtrue一个容易被忽略的细节EMBEDDING_ENABLE_AUTO_INDEXING在使用默认 OpenAI 配置未设置 Ollama、未覆盖 OpenAI base URL时默认即为开启但一旦你自定义了推理提供商设置了OLLAMA_BASE_URL或OPENAI_BASE_URL就必须手动显式开启见 packages/shared/config.ts。语义搜索SEMANTIC_SEARCH_ENABLED默认true也依赖此开关与嵌入链路的可用性。9.5 更换模型的代价必须重新生成全部嵌入:::warning 重要提醒 不同嵌入模型生成的向量互不兼容。如果你更换了嵌入模型或改变了向量维度必须为所有书签重新生成嵌入否则语义搜索将失效或产生错误结果。 :::十、其他值得关注的推理调优参数除了上文各提供商示例中的变量以下几项对推理质量与成本影响较大默认值均可在 packages/shared/config.ts 或 01-environment-variables.md 中核实变量默认值说明INFERENCE_CONTEXT_LENGTH2048传入推理模型的最大 token 数超出部分被截断。值越大标签质量越好但成本越高OpenAI 按量计费、Ollama 消耗资源需参考模型的最大上下文INFERENCE_MAX_OUTPUT_TOKENS2048模型响应的最大 token 数控制标签/摘要的长度上限INFERENCE_LANGenglish生成标签使用的语言INFERENCE_ENABLE_AUTO_TAGGINGtrue是否启用自动打标签INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否启用自动摘要默认关闭INFERENCE_JOB_TIMEOUT_SEC30推理任务超时时间Ollama 无 GPU 时可调大INFERENCE_FETCH_TIMEOUT_SEC300对 Ollama 服务器的请求超时INFERENCE_NUM_WORKERS1并发推理 worker 数请求量大时可调大EMBEDDING_NUM_WORKERS1并发嵌入生成 worker 数EMBEDDING_JOB_TIMEOUT_SEC60嵌入生成与向量索引任务超时OPENAI_PROXY_URL未设置OpenAI 请求的 HTTP 代理地址如http://proxy.example.com:8080国内网络环境常用OPENAI_SERVICE_TIER未设置OpenAI 服务层级auto/default/flexflex 更便宜但响应更慢OPENAI_REASONING_EFFORT未设置推理模型的推理强度none/minimal/low/medium/high/xhighOLLAMA_KEEP_ALIVE未设置模型在 Ollama 内存中的驻留时间如5m、-1m、0另外推理与嵌入任务均在 worker 中异步执行相关 worker 入口位于 apps/workers/workers/inference/inferenceWorker.ts你可以通过WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS精确控制运行哪些 worker。十一、快速自查清单完成配置后建议按以下清单核验推理链路OPENAI_API_KEY或OLLAMA_BASE_URL至少设置一个否则自动打标签会被跳过见 01-environment-variables.mdOllama 容器网络OLLAMA_BASE_URL/OPENAI_BASE_URL不能写localhost应使用 docker-compose 服务名或局域网可达地址模型已拉取在 Ollama 中先ollama pull好文本、图像与嵌入模型维度一致性EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE若设置必须等于EMBEDDING_DIMENSIONS否则启动失败输出模式若模型不支持结构化输出设置INFERENCE_OUTPUT_SCHEMAjson或plain自动索引自定义提供商时记得显式设置EMBEDDING_ENABLE_AUTO_INDEXINGtrue超时调优Ollama 无 GPU 或网络较慢时适当调大INFERENCE_JOB_TIMEOUT_SEC/INFERENCE_FETCH_TIMEOUT_SEC。结语Karakeep 的 AI 能力围绕推理与嵌入两条链路设计得益于对 OpenAI 兼容 API 的广泛支持绝大多数主流提供商都可以通过OPENAI_BASE_URLOPENAI_API_KEY快速接入本地部署则优先推荐 Ollama 的 OpenAI 兼容端点。配置的核心要诀是选对模型、对齐维度、匹配输出模式并在更换嵌入模型后重新生成全部向量。相关配置变量的完整权威清单可查阅 01-environment-variables.md 与 packages/shared/config.ts本指南对应的版本化文档位于 02-different-ai-providers.md。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考