企业官网建设流程全解析

Karakeep（Hoarder）自动打标签的 OpenAI 成本详解：文本与图片推理的费用构成与优化配置

【免费下载链接】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

本篇指南以项目文档 06-openai.md 为骨架，深入讲解 Karakeep（原 Hoarder）在启用 AI 自动打标签（Automatic Tagging）时调用 OpenAI 所产生的费用构成、两种推理类型（文本与图片）的计费特点，并结合仓库源码说明如何通过环境变量精确控制成本。读完本文，你将掌握文本/图片标签推理的模型选型、成本估算方法，以及INFERENCE_*系列配置项对费用与效果的实际影响。

一、自动打标签为什么会产生 OpenAI 费用

Karakeep 是一款自托管的"收藏一切"应用（链接、笔记与图片），其核心卖点之一就是基于 AI 的自动标签（AI-based automatic tagging）。当自动打标签功能开启时，服务会调用 LLM 对收藏内容执行推理，而每次推理都会消耗 token，从而产生费用。

从源码看，推理能力的启用条件非常明确：在 packages/shared/config.ts 中，inference.isConfigured被定义为!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL，也就是说：

• 设置OPENAI_API_KEY（或兼容的 OpenAI 端点）即可启用基于 OpenAI 的推理；
• 设置OLLAMA_BASE_URL则切换为本地 Ollama 推理（不产生 OpenAI 费用，但需要自有算力）。

同时，INFERENCE_ENABLE_AUTO_TAGGING默认值为true（见 packages/shared/config.ts），意味着只要配置了 API Key，自动打标签默认就是开启的——这也是新手最容易忽略、最先产生账单的地方。

Karakeep 的推理分两类：文本打标签（Text Tagging）与图片打标签（Image Tagging），两者使用不同的模型与计费策略，下面分别展开。

二、文本打标签（Text Tagging）：gpt-4.1-mini 与成本估算

在 v0.28.0 版本中，文本打标签默认使用gpt-4.1-mini模型（参见 version-v0.28.0/03-configuration.md 中INFERENCE_TEXT_MODEL的默认值）。该模型定位为低成本、高吞吐，非常适合标签生成这类短输出任务。

文档给出的成本经验值是：大约 3000+ 条书签的标签生成费用不到 1 美元。需要说明的是，这是"roughly"（粗略）的估算，单次推理的实际费用取决于每篇文章的内容体量——内容越长，送入模型的 token 越多，费用越高。

值得注意的是，随着版本演进，文本模型的默认值已经发生变化：当前主干代码（packages/shared/config.ts）中INFERENCE_TEXT_MODEL默认已变为gpt-5.6-luna，当前文档 docs/docs/06-administration/03-openai.md 给出的估算也相应提升到 6000+ 条书签不到 1 美元。以你部署的版本对应的文档为准，估算量级会随模型定价与内容长度浮动。

文本推理的底层调用链

文本打标签的完整流程在 apps/workers/workers/inference/tagging.ts 中实现：

1. runTagging检查全局配置INFERENCE_ENABLE_AUTO_TAGGING与用户级偏好（autoTaggingEnabled），命中任一关闭即跳过；
2. buildPrompt拼装提示词：对链接书签取URL + Title + Description + Content，对文本书签直接取正文；
3. 提示词最终经由 packages/shared/prompts.server.ts 的buildTextPrompt构造，其中会先计算提示词模板自身的 token 数，再用INFERENCE_CONTEXT_LENGTH减去模板占用的部分，剩余额度用于截断正文（truncateContent）——正文永远会被裁剪到上下文窗口之内；
4. 最终调用 packages/shared/inference.ts 中OpenAIInferenceClient.inferFromText，走chat.completions.create完成推理，并把usage.total_tokens返回给上层记录日志。

日志中会明确打印单次推理消耗的 token 数：

[inference][jobId] Inferring tag for bookmark "..." used 1234 tokens and inferred: [tag1, tag2]

（对应 apps/workers/workers/inference/tagging.ts），这对你核对账单、估算费用非常有帮助。

三、图片打标签（Image Tagging）：gpt-4o-mini 与低分辨率模式

对于上传的图片，Karakeep 使用gpt-4o-mini模型提取标签（INFERENCE_IMAGE_MODEL默认值，见 packages/shared/config.ts）。图片推理的计费与文本不同：OpenAI 对视觉输入按图片的 token 消耗计费，而 token 数取决于图片分辨率模式。

低分辨率模式（low resolution）是成本关键

文档明确指出：为了降低成本，Karakeep 使用低分辨率模式（low resolution mode），即无论图片多大，都消耗固定数量的 token。这一点在源码中得到直接印证——packages/shared/inference.ts 中inferFromImage构造消息时，图片被以 base64 内联（data:${contentType};base64,${image}）并通过detail: "low"明确指定了低分辨率模式：

{ type: "image_url", image_url: { url: `data:${contentType};base64,${image}`, detail: "low", }, }

配合该策略，文档给出的经验值是：1000+ 张图片的标签推理费用不到 1 美元。

图片推理的完整链路

图片打标签流程同样位于 apps/workers/workers/inference/tagging.ts 的inferTagsFromImage中：

1. 通过readAsset读取用户资产（asset），若为 GIF 则直接跳过（GIF 不做视觉推理）；
2. 将图片二进制转为 base64 字符串；
3. 调用inferenceClient.inferFromImage，传入图片 MIME 类型与 base64 数据；
4. 推理结果按openAIResponseSchema（{ tags: z.array(z.string()) }）解析，并从结果中剥离#前缀、去除首尾空白后落库。

此外，PDF 书签也走文本推理路径（inferTagsFromPDF），提取的文本内容同样受INFERENCE_CONTEXT_LENGTH截断约束。

四、控制成本的配置清单与参数说明

费用 = 单次推理成本 × 推理次数。Karakeep 提供了丰富的环境变量来控制这两个维度。以下是 v0.28.0 文档（version-v0.28.0/03-configuration.md）与当前主干 packages/shared/config.ts 中与推理成本直接相关的配置项汇总：

以上变量的完整解析逻辑集中在 packages/shared/config.ts（INFERENCE_*、OPENAI_*系列在 L76-L113 定义），是最权威的"参数字典"。

成本控制实践建议

1. 先确认是否真的需要 AI 打标签：若你的收藏以人工标签为主，将INFERENCE_ENABLE_AUTO_TAGGING=false可立即把推理费用归零；
2. 控制INFERENCE_CONTEXT_LENGTH：这是影响单次文本推理费用最大的旋钮。文档提醒其默认值偏小，调大能提升标签质量，但费用与算力开销随之上升，建议按内容平均长度逐步试探；
3. 图片保持低分辨率模式：Karakeep 已默认使用detail: "low"，无需额外配置，也无需自行压缩图片；
4. 监控单次 token 消耗：从推理日志中读取used N tokens字段，结合模型单价即可精确估算月度账单；
5. 善用INFERENCE_NUM_WORKERS：并发数不影响单价，但在批量补打标签（对历史书签批量重跑）时可显著缩短总耗时，减少峰值期焦虑；
6. 考虑替代提供方：若想进一步压低成本，可将OPENAI_BASE_URL指向 OpenRouter、Perplexity、Cloudflare Workers AI 等 OpenAI 兼容端点，或直接用本地 Ollama（OLLAMA_BASE_URL）实现零 API 费用，详见 docs/docs/03-configuration/02-different-ai-providers.md。

五、写在最后：费用之外的注意事项

• 标签质量与模型强相关：文档明确警告"标签质量取决于所选模型的质量"，追求极致成本时不要牺牲可用性；
• 推理失败也会计费风险：源码中parseJsonFromLLMResponse对模型返回做了多层 JSON 兜底解析（apps/workers/workers/inference/tagging.ts），若模型未按预期返回 JSON，任务会报错但 token 已消耗——选择支持结构化输出的模型（INFERENCE_OUTPUT_SCHEMA=structured）可显著降低此类重试成本；
• 版本间默认模型会变化：本文以 v0.28.0 文档的gpt-4.1-mini为基线展开，若你运行的是更新版本，请以对应版本的 docs/docs/06-administration/03-openai.md 与 packages/shared/config.ts 中的默认值为准重新估算。

通过理解"文本按 token 计费、图片按低分辨率固定 token 计费"这两条主线，再配合INFERENCE_*配置的精细调优，你完全可以在保持自动打标签体验的同时，把 OpenAI 账单控制在极低水平。

【免费下载链接】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