企业官网建设流程全解析

Karakeep 自动打标的 OpenAI 成本指南：文本与图片 Tagging 的模型选型与费用控制

【免费下载链接】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）：保存链接、笔记或图片后，系统会自动调用 LLM 为书签生成标签。本指南围绕 v0.29.0 版本文档中关于 OpenAI 成本的说明，结合仓库源码，为你完整梳理文本打标与图片打标各自使用的模型、成本量级、费用产生原理，以及如何在docker-compose.yml与环境变量层面进行模型替换和成本控制。读完本文，你将能准确预估自建实例的 AI 打标开销，并学会通过配置参数与源码级机制把费用压到最低。

一、为什么 AI 打标会产生 OpenAI 成本

Karakeep 的 AI 打标由独立的 inference worker 承担。从 apps/workers/workers/inference/inferenceWorker.ts 可以看到，worker 从OpenAIQueue队列中取出summarize或tag类型的任务，并通过InferenceClientFactory.build()构建推理客户端后执行runTagging。也就是说，只要开启了自动打标（INFERENCE_ENABLE_AUTO_TAGGING默认即为true），每次保存书签都会向 LLM 服务商发起一次推理请求，按 token 计费，因此会产生持续性的 API 费用。

这笔费用有两个决定性因素：

1. 模型单价：文本与图片打标分别使用不同的模型，单价差异直接决定成本；
2. 每次推理的 token 消耗：主要由正文/图片输入长度决定，Karakeep 通过上下文截断与低分辨率模式加以控制。

官方文档明确指出：成本仅在你启用自动打标时才会产生。如果你完全关闭自动打标，就不会有推理费用（本地部署且关闭该功能时尤为明显）。

二、文本打标：gpt-4.1-mini 与"每美元 3000+ 书签"

2.1 使用的模型

在 v0.29.0 版本中，文本打标（text tagging）使用 OpenAI 的gpt-4.1-mini模型。该模型在 OpenAI 定价体系中属于低成本档位（官方定价页），官方文档估算：不到 1 美元即可为 3000+ 条书签生成标签。

需要注意版本差异：当前仓库 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默认值已更新为更新的模型，而图像模型默认值仍为gpt-4o-mini。v0.29.0 时代文档中的gpt-4.1-mini代表了当时默认配置；无论哪个版本，你都可以通过INFERENCE_TEXT_MODEL环境变量自由切换模型。

2.2 每次推理消耗多少 token

单次文本打标的 token 消耗并非固定值，而是取决于文章内容大小。从 packages/shared/prompts.server.ts 的实现看，Karakeep 在发送请求前会做两件事：

• 用js-tiktoken的o200k_base编码器对 prompt 模板计算 token 数；
• 用INFERENCE_CONTEXT_LENGTH（默认 2048）减去模板占用的 token 数，得到可用配额后，对正文执行truncateContent截断。

同时preprocessContent会把连续 10 个以上的空白字符压缩为 1 个，避免无意义的 token 浪费。这意味着即使文章很长，送入模型的内容也会被限制在上下文窗口内，防止单次费用失控。

2.3 打标请求的实际调用

文本打标请求经由 packages/shared/inference.ts 的OpenAIInferenceClient.inferFromText发出：

• 使用chat.completions.create，模型取INFERENCE_TEXT_MODEL；
• 通过response_format强制模型按 JSON 结构返回标签（结构化输出由 tagging.ts 中的openAIResponseSchema定义，要求返回tags: string[]）；
• 返回结果中记录usage.total_tokens，供日志统计。

打标入口runTagging（tagging.ts）还会检查全局开关INFERENCE_ENABLE_AUTO_TAGGING与用户级设置autoTaggingEnabled，任一关闭都会跳过任务——这是控制成本的第一道闸门。

三、图片打标：gpt-4o-mini 与低分辨率模式

3.1 使用的模型

图片上传后，Karakeep 使用gpt-4o-mini从图片中提取标签（默认配置见 packages/shared/config.ts）。官方文档估算：不到 1 美元即可完成 1000+ 张图片的推理。

3.2 低分辨率模式：固定 token 的关键

这是图片打标成本控制的核心机制。在 packages/shared/inference.ts 的inferFromImage中，图片以data:${contentType};base64,${image}的 data URL 形式随请求发送，并显式设置：

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

detail: "low"即 OpenAI 的低分辨率模式：无论原图尺寸多大，模型都按固定的低分辨率规格处理，消耗固定数量的 token（而不是随图片尺寸线性增长）。这正是"1000+ 张图片不到 1 美元"估算成立的技术前提——费用与图片像素解耦，仅与张数相关。

3.3 图片打标流程与例外情况

图片打标在 tagging.ts 的inferTagsFromImage中实现：

1. 通过readAsset读取用户资产并转为 base64；
2. 若contentType为 GIF，直接跳过推理（GIF 不参与打标，避免动画帧带来的额外开销）；
3. 使用buildImagePrompt构造提示词，连同图片一起提交给gpt-4o-mini。

另外，仓库还支持对 PDF 附件执行文本式打标（inferTagsFromPDF），走INFERENCE_TEXT_MODEL通道，成本模型与文本打标一致。

四、成本控制全景：从开关到参数的完整清单

综合官方文档与源码，控制 AI 打标成本的可操作点如下：

其余推理相关参数（如INFERENCE_NUM_WORKERS、INFERENCE_JOB_TIMEOUT_SEC、INFERENCE_LANG等）的完整定义与默认值均可在 packages/shared/config.ts 中查到。

五、如何接入 OpenAI 并替换模型

5.1 最小配置

只需设置OPENAI_API_KEY即可启用默认的 OpenAI 打标。在 Docker 部署中，配置位于 docker/docker-compose.yml 的environment段：

environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 OPENAI_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5.2 按需覆盖默认模型

若想更换模型，取消注释并修改对应环境变量即可：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 默认文本打标模型，可自行替换 INFERENCE_TEXT_MODEL=gpt-4.1-mini # 默认图片打标模型 INFERENCE_IMAGE_MODEL=gpt-4o-mini

关于模型切换有两个值得注意的源码细节：

• InferenceClientFactory.build()（packages/shared/inference.ts）优先使用OPENAI_API_KEY构建 OpenAI 客户端，仅当其缺失时才回退到OLLAMA_BASE_URL构建 Ollama 客户端；
• 若你希望通过代理或自定义 endpoint 访问，可配置OPENAI_BASE_URL与OPENAI_PROXY_URL（见 config.ts），这同时也是接入 OpenAI 兼容服务商（如 Ollama、Gemini、OpenRouter、Perplexity、Azure、Cloudflare）的通用通道，完整示例可参考仓库文档 docs/docs/03-configuration/02-different-ai-providers.md。

六、通过日志观察与核对成本

每次打标完成后，worker 会在日志中输出 token 消耗。在 tagging.ts 中：

logger.info( `[inference][${jobId}] Inferring tag for bookmark "${bookmark.id}" used ${response.totalTokens} tokens and inferred: ${tags}`, );

同时通过addLogFields记录inference.total_tokens与inference.tagging.num_generated_tags，并附带inference.model、inference.prompt.size等字段。你可以在服务日志中按书签维度核对单次推理的 token 数，结合模型单价（以 OpenAI 官方定价为准）核算实际花费，也可以据此评估是否需要对模型或上下文长度做进一步调优。

七、结语

Karakeep 的 AI 打标成本在架构上被设计得相当可控：文本侧通过 tiktoken 预计算与上下文截断限制输入规模，图片侧通过detail: "low"低分辨率模式把单张图片的 token 消耗固定下来，再叠加"按需开启、按模型选型、按用户关闭"的三层开关，让自托管用户能够以极低的成本获得自动标签能力——按 v0.29.0 官方文档估算，文本打标不到 1 美元可覆盖 3000+ 书签，图片打标不到 1 美元可覆盖 1000+ 图片。若想进一步压减开支，优先从INFERENCE_TEXT_MODEL、INFERENCE_CONTEXT_LENGTH与INFERENCE_ENABLE_AUTO_TAGGING三个参数入手，并结合日志中的 token 统计做针对性调整。

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