Karakeep AI Provider 配置指南OpenAI、Ollama、Gemini 等多供应商推理与 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/hoarderKarakeepHoarder使用 LLM 供应商完成书签的自动标签AI tagging、自动摘要summarization并使用 Embedding 模型支撑语义搜索与标签建议优化。本文以 version-v0.31.0 的 AI Provider 配置文档 为主线完整覆盖 OpenAI、Ollama、Gemini、OpenRouter、Perplexity、Azure、Cloudflare 的接入方式并深入其配置解析与推理客户端源码让你能根据成本、隐私与模型能力自由切换推理后端。配置总览三类环境变量Karakeep 的 AI 能力由三组环境变量驱动全部在服务启动时通过 packages/shared/config.ts 中的 Zod Schema 解析serverConfigSchema.parse(process.env)推理配置InferenceOPENAI_API_KEY/OLLAMA_BASE_URL二选一作为推理入口配合INFERENCE_TEXT_MODEL文本推理、INFERENCE_IMAGE_MODEL图像推理指定模型Embedding 配置EMBEDDING_TEXT_MODEL、EMBEDDING_DIMENSIONS、EMBEDDING_CONTEXT_LENGTH等用于语义搜索可选增强配置INFERENCE_OUTPUT_SCHEMA结构化输出、INFERENCE_ENABLE_AUTO_TAGGING、INFERENCE_ENABLE_AUTO_SUMMARIZATION等。从源码看inference.isConfigured的判定条件是!!OPENAI_API_KEY || !!OLLAMA_BASE_URL见 packages/shared/config.ts而EmbeddingClientFactory.build()则优先使用独立的EMBEDDING_OPENAI_API_KEY/EMBEDDING_OPENAI_BASE_URL未设置时回退到推理配置见 packages/shared/inference.ts。这意味着 Embedding 供应商可以与推理供应商完全独立。OpenAI最简单的接入方式直接传入OPENAI_API_KEY即可启用自动打标签OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可通过取消注释覆盖默认模型 # INFERENCE_TEXT_MODELgpt-4.1-mini # INFERENCE_IMAGE_MODELgpt-4o-mini源码佐证在 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默认值是gpt-5.6-lunaINFERENCE_IMAGE_MODEL默认gpt-4o-mini只要设置了OPENAI_API_KEY且未覆盖OPENAI_BASE_URL就会命中useMaxCompletionTokens自动为true的默认分支packages/shared/config.ts即使用较新的max_completion_tokens参数调用 API。请求由OpenAIInferenceClient.inferFromText()发起packages/shared/inference.ts文本与图像推理分别使用INFERENCE_TEXT_MODEL与INFERENCE_IMAGE_MODEL图像以 base64 data URL 形式、detail: low方式送入多模态消息。Ollama本地推理服务器的两种接法Ollama 让你在自己的机器上运行 LLM 服务。要点是传给 Karakeep 的必须是容器内可达的地址例如http://ollama.mylab.com:11434不要使用localhost否则容器内无法访问宿主机。Ollama 提供两个 API 端点OpenAI 兼容 API推荐——使用/v1chat 端点自动处理消息格式原生 Ollama API——部分模型需要手动格式化。方案一OpenAI 兼容 API推荐对各类模型的兼容性更稳定OPENAI_API_KEYollama OPENAI_BASE_URLhttp://ollama.mylab.com:11434/v1 # 先确保已在 ollama 中 pull 对应模型示例 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava方案二原生 Ollama API# 注意切勿同时设置 OPENAI_API_KEY否则其优先级更高会覆盖 Ollama 配置 OLLAMA_BASE_URLhttp://ollama.mylab.com:11434 # 先确保已在 ollama 中 pull 对应模型示例 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava # 如果所选模型不支持结构化输出还需要设置 # INFERENCE_OUTPUT_SCHEMAplain优先级机制InferenceClientFactory.build()packages/shared/inference.ts先检查openAIApiKey再检查ollamaBaseUrl——这就是为什么文档强调原生 Ollama 方案下不能设置OPENAI_API_KEY。原生路径由OllamaInferenceClient实现使用流式ollama.generate()累积响应packages/shared/inference.ts并可通过OLLAMA_KEEP_ALIVE控制模型在内存中的驻留时长如5m、-1m永久驻留、0立即卸载。排错提示如果你在使用某些特殊模型尤其是 OpenAI 的 gpt-oss 系列或其他要求特定 chat 格式的模型时遇到问题请改用 OpenAI 兼容 API 端点。Gemini使用 Google 的 OpenAI 兼容端点Gemini 提供了 OpenAI 兼容 API。你需要从 Google AI Studio 获取 API Key并且即使使用免费层也必须开通结算账户billing accountOPENAI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta OPENAI_API_KEYYOUR_API_KEY # 示例模型 INFERENCE_TEXT_MODELgemini-2.5-flash-lite INFERENCE_IMAGE_MODELgemini-2.5-flash-liteOpenRouter聚合多家模型OpenRouter 聚合了多家模型供应商通过其 OpenAI 兼容端点可统一调用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-scoutPerplexityOPENAI_BASE_URLhttps://api.perplexity.ai OPENAI_API_KEYYour Perplexity API Key INFERENCE_TEXT_MODELsonar-pro INFERENCE_IMAGE_MODELsonar-proAzureAzure OpenAI 兼容 APIAzure 提供 OpenAI 兼容 API。你可以从 Azure AI Foundry 门户的 Overview 页面或 Azure 门户中资源的 Keys Endpoints 处获取 API Key。:::warning 在 Azure 上模型名称即你部署模型时指定的部署名称deployment name它可能与基础模型名不同。INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL必须填写你的部署名称。 :::# 通过 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_NAMECloudflareWorkers AICloudflare 支持 OpenAI 兼容端点。你可以在 Cloudflare 控制台Workers AI生成 API TokenOPENAI_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 INFERENCE_OUTPUT_SCHEMAjson注意 Cloudflare 示例中显式设置了INFERENCE_OUTPUT_SCHEMAjson——当模型不支持 OpenAI 的structured outputJSON Schema 约束时可回退到 JSON 模式。该参数的完整取值与行为见下文输出格式控制。输出格式控制INFERENCE_OUTPUT_SCHEMA 与结构化输出INFERENCE_OUTPUT_SCHEMA控制推理结果如何约束为程序可解析的格式取值有三个默认structured取值含义适用场景structured使用 JSON SchemaOpenAI 侧为zodResponseFormatOllama 侧为 Zod 4 的 JSON Schema 发射器强制结构化首选模型支持结构化输出时json使用 JSON 模式json_object模型支持 JSON 模式但不支持完整结构化输出plain不附加格式约束靠提示词输出所有模型都支持但输出格式可能不稳定实现见 packages/shared/inference.tsOpenAI 的mapOpenAIResponseFormat与 packages/shared/inference.tsOllama 的mapInferenceOutputSchema。旧参数INFERENCE_SUPPORTS_STRUCTURED_OUTPUT已废弃true等价于structured、false等价于plain见 packages/shared/config.ts。其他重要的推理调优参数在 docs/docs/03-configuration/01-environment-variables.md 的 Inference Configs 一节中以下参数与供应商配置配合使用INFERENCE_CONTEXT_LENGTH默认 2048传给推理模型的 token 上限内容超长会被截断。调大可提升标签质量但会增加推理成本OpenAI 按 token 计费Ollama 则消耗更多本地资源INFERENCE_MAX_OUTPUT_TOKENS默认 2048允许模型生成的最大 token 数控制标签/摘要等内容的长度INFERENCE_ENABLE_AUTO_TAGGING默认true与INFERENCE_ENABLE_AUTO_SUMMARIZATION默认false开关自动标签与自动摘要INFERENCE_JOB_TIMEOUT_SEC默认 30推理任务超时Ollama 在无强 GPU 时应适当调大INFERENCE_FETCH_TIMEOUT_SEC默认 300仅 Ollama 生效指到 Ollama 服务器的 fetch 请求超时INFERENCE_LANG默认english标签生成语言INFERENCE_NUM_WORKERS默认 1推理并发 worker 数OLLAMA_KEEP_ALIVE模型驻留内存时长OPENAI_PROXY_URL/OPENAI_TIMEOUT_SEC/OPENAI_SERVICE_TIERauto/default/flex/OPENAI_REASONING_EFFORTOpenAI 专用进阶参数其中OPENAI_TIMEOUT_SEC未设置时使用 OpenAI SDK 默认的 10 分钟。Embedding 模型语义搜索与自动索引除推理外Karakeep 还用 Embedding 模型支撑语义搜索和标签建议优化。三个核心参数EMBEDDING_TEXT_MODEL EMBEDDING_DIMENSIONS EMBEDDING_CONTEXT_LENGTHEMBEDDING_TEXT_MODEL默认text-embedding-3-smallpackages/shared/config.tsEMBEDDING_DIMENSIONS默认1536是向量存储期望的维度必须与模型/供应商实际输出一致EMBEDDING_CONTEXT_LENGTH默认8000超出该字符数的书签内容会在生成向量前被截断。独立的 Embedding 供应商Embedding 可以使用与推理不同的 OpenAI 兼容供应商两个覆盖项可独立设置未设置的值自动回退到对应的OPENAI_*配置EMBEDDING_OPENAI_API_KEYembedding-provider-api-key EMBEDDING_OPENAI_BASE_URLhttps://embedding-provider.example.com/v1回退逻辑见 packages/shared/inference.ts当EMBEDDING_OPENAI_API_KEY或EMBEDDING_OPENAI_BASE_URL存在时优先构建独立 Embedding 客户端API Key 缺省取OPENAI_API_KEYbase URL 缺省取OPENAI_BASE_URL。维度覆盖参数的一致性约束对于支持多种输出维度的 Embedding 模型用EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE向供应商请求指定维度OpenAI 侧通过dimensions字段传递见 packages/shared/inference.ts。它的值必须与EMBEDDING_DIMENSIONS一致否则 Karakeep 会启动失败——这是 packages/shared/config.ts 中的硬校验EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE768 EMBEDDING_DIMENSIONS768此外每次 Embedding 响应都会经过validateEmbeddingDimensions()校验维度与EMBEDDING_DIMENSIONS匹配packages/shared/inference.ts不匹配会直接抛错。启用自动索引与换模型的注意事项配置好 Embedding 模型后还需要为书签启用自动 Embedding 生成EMBEDDING_ENABLE_AUTO_INDEXINGtrue若未显式设置默认策略是使用默认 OpenAI 推理配置未设置OLLAMA_BASE_URL/OPENAI_BASE_URL且设置了OPENAI_API_KEY时自动开启否则需手动开启packages/shared/config.ts。重要警告不同模型的 Embedding 互不兼容。如果日后更换 Embedding 模型或调整维度需要为所有书签重新生成 Embedding。容器部署时的落地示例官方 e2e 测试的 docker-compose.yml 展示了一套完整的推理 Embedding 环境变量组合使用 OpenAI 兼容 mock 端点OPENAI_API_KEY: aimock-test-key OPENAI_BASE_URL: http://aimock:4010/v1 EMBEDDING_DIMENSIONS: 384 EMBEDDING_ENABLE_AUTO_INDEXING: true INFERENCE_ENABLE_AUTO_SUMMARIZATION: true实际部署时将上述变量填入你的 compose 文件的environment段即可Docker 安装与配置流程参见 docs/versioned_docs/version-v0.31.0/02-installation/01-docker.md。若使用 Ollama记得把地址改成容器网络内可达的主机名如http://ollama:11434并先执行ollama pull gemma3、ollama pull llava等命令拉取模型。总结如何选择你的供应商组合追求开箱即用直接设置OPENAI_API_KEY默认模型即可工作注重隐私与本地部署使用 Ollama推荐走/v1OpenAI 兼容端点并注意不要同时设置OPENAI_API_KEY成本敏感或多模型对比OpenRouter / Perplexity 是聚合型选项已上云使用 Azure / Cloudflare / Gemini均为 OpenAI 兼容端点只需替换OPENAI_BASE_URL与OPENAI_API_KEY并注意 Azure 的部署名称规则启用语义搜索配置EMBEDDING_*系列变量保持维度一致并设置EMBEDDING_ENABLE_AUTO_INDEXINGtrue。所有配置项均可在启动时被 packages/shared/config.ts 校验并落入运行时配置对象配合 packages/shared/inference.ts 的客户端工厂实现Karakeep 让你用同一套环境变量体系灵活对接几乎所有主流 LLM 服务。【免费下载链接】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），仅供参考