企业官网建设流程全解析

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/hoarder

Karakeep（Hoarder）使用 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)）：

• 推理配置（Inference）：OPENAI_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_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可通过取消注释覆盖默认模型 # INFERENCE_TEXT_MODEL=gpt-4.1-mini # INFERENCE_IMAGE_MODEL=gpt-4o-mini

源码佐证：在 packages/shared/config.ts 中，INFERENCE_TEXT_MODEL的默认值是gpt-5.6-luna，INFERENCE_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 端点：

1. OpenAI 兼容 API（推荐）——使用/v1chat 端点，自动处理消息格式；
2. 原生 Ollama API——部分模型需要手动格式化。

方案一：OpenAI 兼容 API（推荐）

对各类模型的兼容性更稳定：

OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://ollama.mylab.com:11434/v1 # 先确保已在 ollama 中 pull 对应模型，示例： INFERENCE_TEXT_MODEL=gemma3 INFERENCE_IMAGE_MODEL=llava

方案二：原生 Ollama API

# 注意：切勿同时设置 OPENAI_API_KEY，否则其优先级更高，会覆盖 Ollama 配置 OLLAMA_BASE_URL=http://ollama.mylab.com:11434 # 先确保已在 ollama 中 pull 对应模型，示例： INFERENCE_TEXT_MODEL=gemma3 INFERENCE_IMAGE_MODEL=llava # 如果所选模型不支持结构化输出，还需要设置： # INFERENCE_OUTPUT_SCHEMA=plain

优先级机制：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 account）：

OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta OPENAI_API_KEY=YOUR_API_KEY # 示例模型： INFERENCE_TEXT_MODEL=gemini-2.5-flash-lite INFERENCE_IMAGE_MODEL=gemini-2.5-flash-lite

OpenRouter：聚合多家模型

OpenRouter 聚合了多家模型供应商，通过其 OpenAI 兼容端点可统一调用：

OPENAI_BASE_URL=https://openrouter.ai/api/v1 OPENAI_API_KEY=YOUR_API_KEY # 示例模型（使用供应商/模型 的命名格式）： INFERENCE_TEXT_MODEL=meta-llama/llama-4-scout INFERENCE_IMAGE_MODEL=meta-llama/llama-4-scout

Perplexity

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

Azure：Azure OpenAI 兼容 API

Azure 提供 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_URL=https://{your-azure-ai-foundry-resource-name}.cognitiveservices.azure.com/openai/v1/ # 通过 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

Cloudflare：Workers AI

Cloudflare 支持 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 # 示例模型： INFERENCE_TEXT_MODEL=@cf/meta/llama-3.1-8b-instruct-fast INFERENCE_IMAGE_MODEL=@cf/meta/llama-3.2-11b-vision-instruct INFERENCE_OUTPUT_SCHEMA=json

注意 Cloudflare 示例中显式设置了INFERENCE_OUTPUT_SCHEMA=json——当模型不支持 OpenAI 的structured output（JSON Schema 约束）时，可回退到 JSON 模式。该参数的完整取值与行为见下文"输出格式控制"。

输出格式控制：INFERENCE_OUTPUT_SCHEMA 与结构化输出

INFERENCE_OUTPUT_SCHEMA控制推理结果如何约束为程序可解析的格式，取值有三个（默认structured）：

实现见 packages/shared/inference.ts（OpenAI 的mapOpenAIResponseFormat）与 packages/shared/inference.ts（Ollama 的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_TIER（auto/default/flex）/OPENAI_REASONING_EFFORT：OpenAI 专用进阶参数，其中OPENAI_TIMEOUT_SEC未设置时使用 OpenAI SDK 默认的 10 分钟。

Embedding 模型：语义搜索与自动索引

除推理外，Karakeep 还用 Embedding 模型支撑语义搜索和标签建议优化。三个核心参数：

EMBEDDING_TEXT_MODEL= EMBEDDING_DIMENSIONS= EMBEDDING_CONTEXT_LENGTH=

• EMBEDDING_TEXT_MODEL默认text-embedding-3-small（packages/shared/config.ts）；
• EMBEDDING_DIMENSIONS默认1536，是向量存储期望的维度，必须与模型/供应商实际输出一致；
• EMBEDDING_CONTEXT_LENGTH默认8000，超出该字符数的书签内容会在生成向量前被截断。

独立的 Embedding 供应商

Embedding 可以使用与推理不同的 OpenAI 兼容供应商，两个覆盖项可独立设置，未设置的值自动回退到对应的OPENAI_*配置：

EMBEDDING_OPENAI_API_KEY=embedding-provider-api-key EMBEDDING_OPENAI_BASE_URL=https://embedding-provider.example.com/v1

回退逻辑见 packages/shared/inference.ts：当EMBEDDING_OPENAI_API_KEY或EMBEDDING_OPENAI_BASE_URL存在时优先构建独立 Embedding 客户端，API Key 缺省取OPENAI_API_KEY，base 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_OVERRIDE=768 EMBEDDING_DIMENSIONS=768

此外，每次 Embedding 响应都会经过validateEmbeddingDimensions()校验维度与EMBEDDING_DIMENSIONS匹配（packages/shared/inference.ts），不匹配会直接抛错。

启用自动索引与换模型的注意事项

配置好 Embedding 模型后，还需要为书签启用自动 Embedding 生成：

EMBEDDING_ENABLE_AUTO_INDEXING=true

若未显式设置，默认策略是：使用默认 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_INDEXING=true。

所有配置项均可在启动时被 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