Karakeep 多 AI 提供商接入指南：OpenAI 兼容 API 与 Ollama 本地推理的完整配置实战-育师

Karakeep 多 AI 提供商接入指南：OpenAI 兼容 API 与 Ollama 本地推理的完整配置实战

【免费下载链接】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（原 Hoarder）自托管书签应用的 AI 能力展开，讲解如何为自动标签（automatic tagging）与内容摘要（summarization）配置不同的 LLM 提供商。Karakeep 支持 OpenAI 官方服务、一切 OpenAI 兼容的 API 端点（如 Gemini、OpenRouter、Perplexity、Azure、Cloudflare），以及本地部署的 Ollama。读完本文，你将掌握全部 6 类提供商的完整环境变量配置方案、模型选择要点、结构化输出兼容性问题，以及嵌入模型（Embedding）的配套设置，可直接套用到自己的 Docker 或裸机部署中。

关联文档为 docs/versioned_docs/version-v0.29.0/14-guides/05-different-ai-providers.md，所有环境变量的定义与默认值均可在 packages/shared/config.ts 中找到，底层推理调用链实现在 packages/shared/inference.ts。

配置机制概述：一切皆环境变量

Karakeep 的 AI 推理配置完全通过环境变量完成，核心入口有两个：

OPENAI_API_KEY：OpenAI（或兼容服务）的 API 密钥；
OLLAMA_BASE_URL：本地 Ollama 服务的地址。

在 packages/shared/config.ts 中，这些变量被定义为可选的字符串，并通过serverConfig.inference汇总供业务代码使用。关键的决策逻辑在 packages/shared/inference.ts 的InferenceClientFactory.build()中：

if (serverConfig.inference.openAIApiKey) { return OpenAIInferenceClient.fromConfig(); } if (serverConfig.inference.ollamaBaseUrl) { return OllamaInferenceClient.fromConfig(); } return null;

即：只要设置了OPENAI_API_KEY，就优先走 OpenAI 兼容路径；只有未设置该密钥时，才会尝试使用OLLAMA_BASE_URL。这一优先级决定了在配置 Ollama 时必须确保OPENAI_API_KEY为空，否则会静默使用错误的客户端。若两者都未配置，推理客户端返回null，自动标签功能将被跳过（见 docs/docs/03-configuration/01-environment-variables.md 中 "Inference Configs" 一节的说明）。

OpenAI：最简配置

如果直接使用 OpenAI 官方 API，只需设置一个密钥即可：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # You can change the default models by uncommenting the following lines, and choosing your model. # INFERENCE_TEXT_MODEL=gpt-4.1-mini # INFERENCE_IMAGE_MODEL=gpt-4o-mini

说明：

INFERENCE_TEXT_MODEL用于文本标签与摘要推理；INFERENCE_IMAGE_MODEL用于图片标签提取（该模型必须支持视觉输入）。
在 packages/shared/inference.ts 的inferFromText()中，文本推理通过chat.completions.create以单条user消息发送完整 prompt；图片推理（inferFromImage()）则以data:${contentType};base64,${image}的形式将图片以 base64 内联传给image_url，并固定使用detail: "low"低分辨率模式来控制成本。
所有请求都带上了X-Title: Karakeep与HTTP-Referer自定义头（inference.ts），便于在部分 OpenAI 兼容平台（如 OpenRouter）上识别来源。

Ollama：本地模型推理

Ollama 允许你在自己的服务器上运行 LLM。需要把 Ollama 的地址传给 Karakeep，并确保该地址从 Karakeep 容器内部可访问（例如不能写localhost，因为那会指向容器自身）。

# MAKE SURE YOU DON'T HAVE OPENAI_API_KEY set, otherwise it takes precedence. OLLAMA_BASE_URL=http://ollama.mylab.com:11434 # Make sure to pull the models in ollama first. Example models: INFERENCE_TEXT_MODEL=gemma3 INFERENCE_IMAGE_MODEL=llava # If the model you're using doesn't support structured output, you also need: # INFERENCE_OUTPUT_SCHEMA=plain

要点：

先要在 Ollama 中ollama pull对应模型（如gemma3、llava）。
图片模型必须支持视觉 API（如llava），否则图片标签无法工作。
OLLAMA_BASE_URL指向 Ollama 的原生 API（默认端口 11434）。OllamaInferenceClient使用ollama官方 SDK 进行推理，代码路径同样在 packages/shared/inference.ts 之后。
可选变量OLLAMA_KEEP_ALIVE控制模型在内存中的驻留时长（如5m、-1m永久驻留、0立即卸载），可显著影响反复推理时的响应速度；INFERENCE_FETCH_TIMEOUT_SEC（默认 300）控制对 Ollama 服务器请求的超时。
慢速 GPU 场景下建议适当调大INFERENCE_JOB_TIMEOUT_SEC（默认 30），避免推理任务被判定超时。
若模型不支持结构化输出，必须将INFERENCE_OUTPUT_SCHEMA设为plain。在 inference.ts 的mapOpenAIResponseFormat()中，structured模式使用zodResponseFormat强制按 Zod Schema 输出，json模式要求模型支持 JSON mode，而plain不附加任何约束、兼容性最广——但模型可能不按预期格式输出数据。

新版文档（docs/docs/03-configuration/02-different-ai-providers.md）还推荐了另一种更稳妥的接法：使用 Ollama 的 OpenAI 兼容端点（OPENAI_BASE_URL=http://ollama.mylab.com:11434/v1，OPENAI_API_KEY=ollama），由/v1端点自动处理消息格式，对部分要求特定 chat 格式的模型兼容性更好。

Gemini：通过 OpenAI 兼容 API 接入

Gemini 提供了 OpenAI 兼容 API，从 Google AI Studio 获取 API Key 后即可配置：

OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta OPENAI_API_KEY=YOUR_API_KEY # Example models: INFERENCE_TEXT_MODEL=gemini-2.0-flash INFERENCE_IMAGE_MODEL=gemini-2.0-flash

要点：

由于OPENAI_API_KEY已设置，Karakeep 会走 OpenAI 兼容客户端，仅将OPENAI_BASE_URL指向 Gemini 的端点。buildOpenAIClient()会把该 URL 作为baseURL传给 OpenAI SDK（inference.ts）。
注意：Gemini 需要先在 Google Cloud / AI Studio 配置计费账户（即使是免费额度），否则请求可能被拒。

OpenRouter：聚合多模型的统一入口

OpenRouter 聚合了大量开源与商业模型，同样暴露 OpenAI 兼容 API：

OPENAI_BASE_URL=https://openrouter.ai/api/v1 OPENAI_API_KEY=YOUR_API_KEY # Example models: INFERENCE_TEXT_MODEL=meta-llama/llama-4-scout INFERENCE_IMAGE_MODEL=meta-llama/llama-4-scout

要点：

模型名必须使用 OpenRouter 的完整格式（组织/模型名），如meta-llama/llama-4-scout。
文本模型与图片模型均可指向同一模型；若所选模型不支持视觉，则图片标签会失败。
由于 Karakeep 发送的请求带X-Title/HTTP-Referer头，OpenRouter 后台可以正确统计到来自 Karakeep 的调用。

Perplexity：Sonar 系列模型

Perplexity 的 API 同样兼容 OpenAI 格式：

OPENAI_BASE_URL: https://api.perplexity.ai OPENAI_API_KEY: Your Perplexity API Key INFERENCE_TEXT_MODEL: sonar-pro INFERENCE_IMAGE_MODEL: sonar-pro

要点：OPENAI_BASE_URL必须指向https://api.perplexity.ai；若你的 Perplexity 模型不支持结构化输出，同样需要设置INFERENCE_OUTPUT_SCHEMA=plain。

Azure：部署名即模型名

Azure 提供了 OpenAI 兼容 API。API Key 可在 Azure AI Foundry Portal 的 Overview 页面，或 Azure Portal 中资源的 "Keys + Endpoints" 处获取。

:::warning模型名就是你在部署模型时指定的部署名（deployment name），它可能与底层基础模型名不一致（如基础模型gpt-4o但部署名为my-gpt4o-deploy）。INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL必须填写部署名。 :::

# Deployed via Azure AI Foundry: OPENAI_BASE_URL=https://{your-azure-ai-foundry-resource-name}.cognitiveservices.azure.com/openai/v1/ # Deployed via Azure OpenAI Service: OPENAI_BASE_URL=https://{your-azure-openai-resource-name}.openai.azure.com/openai/v1/ OPENAI_API_KEY=YOUR_API_KEY INFERENCE_TEXT_MODEL=YOUR_DEPLOYMENT_NAME INFERENCE_IMAGE_MODEL=YOUR_DEPLOYMENT_NAME

要点：

两种部署途径（AI Foundry 与 Azure OpenAI Service）的 base URL 格式不同，注意区分。
URL 末尾的/openai/v1/是 OpenAI SDK 拼接路径所必需的，不要遗漏。

补充：Cloudflare Workers AI

在同一主题的新版文档（docs/docs/03-configuration/02-different-ai-providers.md）中还给出了 Cloudflare 的配置方式。Cloudflare Workers AI 同样支持 OpenAI 兼容端点，可在 Cloudflare 控制台（Workers AI）生成 API Token：

OPENAI_BASE_URL=https://api.cloudflare.com/client/v4/accounts/{your-account-id}/ai/v1 OPENAI_API_KEY=Your Cloudflare Workers AI Token # Example models: INFERENCE_TEXT_MODEL=@cf/meta/llama-3.1-8b-instruct-fast INFERENCE_IMAGE_MODEL=@cf/meta/llama-3.2-11b-vision-instruct EMBEDDING_TEXT_MODEL=@cf/google/embeddinggemma-300m EMBEDDING_DIMENSIONS=768 EMBEDDING_CONTEXT_LENGTH=2048 INFERENCE_OUTPUT_SCHEMA=json

其中@cf/...是 Cloudflare 的模型命名格式；由于部分 CF 模型不支持严格结构化输出，示例中显式设置了INFERENCE_OUTPUT_SCHEMA=json。

模型参数与输出格式调优

无论选择哪家提供商，以下几个环境变量直接影响推理质量与成本（定义与默认值见 packages/shared/config.ts）：

变量	默认值	说明
`INFERENCE_TEXT_MODEL`	gpt-5.6-luna（当前仓库）	文本标签/摘要推理模型
`INFERENCE_IMAGE_MODEL`	gpt-4o-mini	图片标签提取模型（需支持视觉）
`INFERENCE_CONTEXT_LENGTH`	2048	传给推理模型的最大 token 数，超出部分截断；调大可提升标签质量，但成本（OpenAI 按量计费 / Ollama 按资源）也随之上升
`INFERENCE_MAX_OUTPUT_TOKENS`	2048	模型响应的最大 token 数，控制 AI 生成内容的长度
`INFERENCE_OUTPUT_SCHEMA`	structured	可选`structured`/`json`/`plain`；structured 为最优，不支持时依次回退到 json、plain
`INFERENCE_ENABLE_AUTO_TAGGING`	true	是否启用自动 AI 标签
`INFERENCE_ENABLE_AUTO_SUMMARIZATION`	false	是否启用自动 AI 摘要
`INFERENCE_NUM_WORKERS`	1	AI 推理任务的并发工作进程数
`INFERENCE_JOB_TIMEOUT_SEC`	30	推理任务超时；Ollama 无强 GPU 时建议调大
`INFERENCE_FETCH_TIMEOUT_SEC`	300	（Ollama）请求 Ollama 服务器的超时
`OPENAI_TIMEOUT_SEC`	未设置（SDK 默认 10 分钟）	OpenAI 兼容请求的超时
`OPENAI_PROXY_URL`	未设置	请求 OpenAI 兼容 API 时使用的 HTTP 代理

INFERENCE_OUTPUT_SCHEMA的三种取值在 packages/shared/inference.ts 中对应三种response_format：structured通过zodResponseFormat强制 schema 校验，json使用{"type": "json_object"}，plain不附加约束。这也是"模型不支持结构化输出时必须改为 plain"的原因。

配套：Embedding 模型配置

除了标签与摘要，Karakeep 还使用 Embedding 模型支撑语义搜索与标签建议优化。由于关联文档的生态配套，这里一并给出关键变量（详见 docs/docs/03-configuration/01-environment-variables.md）：

EMBEDDING_TEXT_MODEL=text-embedding-3-small EMBEDDING_DIMENSIONS=1536 EMBEDDING_CONTEXT_LENGTH=8000 EMBEDDING_ENABLE_AUTO_INDEXING=true

EMBEDDING_DIMENSIONS（默认 1536）是向量库期望的维度，必须与模型/提供商实际输出一致。在 inference.ts 的validateEmbeddingDimensions()中，若返回向量维度与配置不符会直接抛错。
支持多输出维度的模型可用EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE向提供商请求指定维度，其值必须与EMBEDDING_DIMENSIONS一致，否则 Karakeep 启动失败。
Embedding 可以单独使用另一个 OpenAI 兼容提供商：EMBEDDING_OPENAI_API_KEY与EMBEDDING_OPENAI_BASE_URL未设置时，会自动回退到对应的OPENAI_*变量（见 EmbeddingClientFactory.build()）。
不同模型的 Embedding 互不兼容：一旦更换 Embedding 模型或维度，必须为所有书签重新生成 Embedding。

总结与排错清单

配置 AI 提供商的核心思路：OpenAI 官方只需密钥；其他提供商一律通过OPENAI_BASE_URL走 OpenAI 兼容协议；本地推理用OLLAMA_BASE_URL且不能同时设置OPENAI_API_KEY。常见问题速查：

自动标签完全不工作：检查是否同时未设置OPENAI_API_KEY与OLLAMA_BASE_URL（此时推理客户端为null，自动标签被跳过）。
配置了 Ollama 但请求打到了 OpenAI：OPENAI_API_KEY已被设置，按优先级覆盖了 Ollama，请清除该变量。
模型报结构化输出错误：将INFERENCE_OUTPUT_SCHEMA从structured降级为json，仍不行则用plain。
Azure 返回模型不存在：INFERENCE_TEXT_MODEL需填部署名而非基础模型名。
容器内连不上 Ollama：地址不能写localhost，应写宿主机可路由的主机名/IP，并确认 11434 端口可达。