Khoj 接入统一 API:两个配置入口

先说结论:首跑用环境变量,之后用管理后台

Khoj 的自部署 compose 文件里有一行注释掉的 OPENAI_BASE_URL,按官方原话是给其它 OpenAI API 兼容供应商用的。首次启动之前把它设成 https://api.kkaiapi.com/v1,OPENAI_API_KEY 放网关 Key,Khoj 的初始化会做一件相当贴心的事:查询端点的模型列表,把每一个端点提供的 ID 播种进自己的聊天模型表,不用手动录入,目录就出现在了 Khoj 的模型选择器里。 对一个已经初始化过的服务器,改用管理后台。新建一个 AI Model API 条目(字段:Name、Api Key、Api Base Url)指向网关,再新建 Chat Model 条目,Name 填精确的模型 ID,Model Type 设成 Openai,关联到那个 AI Model API。两个入口都记录在 Khoj 的 OpenAI 代理指南里。

services:
  server:
    environment:
      - OPENAI_BASE_URL=https://api.kkaiapi.com/v1
      - OPENAI_API_KEY=sk-你的kkaiapi密钥

Khoj 拿聊天模型做什么

Khoj(GitHub 上的 khoj-ai,约 3.6 万星标)是一个可自部署的 AI 第二大脑:给笔记和文档(markdown、org-mode、PDF 等)建索引,让你在上面聊天、跑带自己人设和工具的自定义 Agent、按 cron 排程的自动化,以及发起多步研究。有一个托管应用,但自定义端点适用的是自部署服务器,这一页说的也是这种部署方式。 上面每一项功能都经过你选定的聊天模型。文档聊天会把检索到的笔记片段打进提示词,Agent 加上工具调用和人设指令,自动化无人值守跑同一条管线,研究模式每个问题会串联很多次模型调用。Model Type 设成 Openai 会让 Khoj 对关联的 AI Model API 的 Api Base Url 说 /v1/chat/completions,把模型 Name 作为纯字符串转发,这也是为什么只要端点提供,Claude 或 DeepSeek 的 ID 就能用在这里。 搜索用的 Embedding 是另一个子系统。Khoj 默认用一个本地 sentence-transformers 模型给文档做 Embedding,所以不管对聊天端点做什么改动,索引和语义搜索都照常工作。把聊天路由到网关,挪动的只是推理这部分的账单。

完整配置:管理后台三步

在一个已运行的服务器上,整套接入就是三个管理页面。第一步,加 AI Model API:打开 /server/admin/database/aimodelapi/add,起个名字,把网关 Key 粘进 Api Key,Api Base Url 设成 https://api.kkaiapi.com/v1。 第二步,加聊天模型:在 /server/admin/database/chatmodel/add,Name 设成一个精确的目录 ID(claude-sonnet-4-6、deepseek-v4-flash),Model Type 设成 Openai,关联刚建好的 Ai Model Api 条目,把 Max prompt size 设成一个匹配模型上下文窗口的数值。官方文档建议 OpenAI 类型的模型把 Tokenizer 留空。想让选择器里出现哪个模型就重复这一步。 第三步,选模型:在 /settings 里,把新的聊天模型选成默认值。Agent 能按各自的设置覆盖模型,这就是为什么一个 Khoj 实例能给日常自动化跑一个快速 ID、给研究跑一个旗舰 ID。

1) /server/admin/database/aimodelapi/add
   Name:         kkaiapi
   Api Key:      sk-你的kkaiapi密钥
   Api Base Url: https://api.kkaiapi.com/v1

2) /server/admin/database/chatmodel/add
   Name:         claude-sonnet-4-6   (精确目录 ID)
   Model Type:   Openai
   Ai Model Api: kkaiapi
   Max prompt size: 100000

3) /settings -> 选新的聊天模型

给第二大脑选模型

因为聊天模型是对着一个 AI Model API 添加的行,选择器里留两三个 ID 不花什么代价。实际做法是一个快速默认加一个旗舰升级,两者共用同一个 Key,用量日志显示每个档位在自己的笔记上到底花了多少。

• 文档聊天是输入密集型的:检索到的笔记片段远大于答案。每输入 token 的单价决定了每个问题的成本,这让 claude-haiku-4-5-20251001、deepseek-v4-flash 或 gemini-3.5-flash 适合日常查阅
• 研究模式会放大调用次数。一个研究问题能串联很多轮模型调用,所以这个槽位分配的 ID 对账单的影响比任何其它设置都大;claude-sonnet-4-6 是平衡的选择,gpt-5.4 是升级选项
• 定时自动化无人值守跑。按订阅一样给它定价:每天调用次数乘以每次调用的 token,这正是按 Key 的用量日志会报出来的数字
• 个人知识库充满矛盾(计划会变、笔记会过期),模型在标记冲突笔记而不是把它们混在一起这件事上表现不同;在同一批问题上先测两个 ID 再定下来
• Max prompt size 是 Khoj 里按聊天模型设置的,一个长上下文 ID 只有在把这个字段调大之后才划算

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

Khoj 专属的翻车点

环境变量是首跑种子,不是活配置。OPENAI_BASE_URL 只在初始化期间被读取,用来创建供应商条目和发现模型;在一个已经初始化过的服务器上,改 compose 文件不会产生任何看得见的变化。之后想改动用管理后台,或者真想要一次全新播种就重置数据库。 占位 Key 的陷阱:设了 OPENAI_BASE_URL 却没设 OPENAI_API_KEY 时,Khoj 会填一个占位 Key,让 Ollama 这类本地服务器能正常工作。网关需要一个真实的 Key,所以如果首跑播种时没带 Key,聊天会一直报认证错误,直到把 Key 粘进管理后台的 AI Model API 条目。 自动发现会把所有东西都播种进来。因为初始化会列出端点提供的每一个模型,一个多厂商网关可能播种出一张很长的模型表。这没什么危害,但值得在管理后台里修剪一下,让选择器保持可用。 聊天模型的 Name 要精确。Khoj 原样转发这个值,拼错了会在第一条消息时报模型不存在,网关的 /v1/models 输出是权威拼写。如果笔记的语义搜索出问题,那是本地 Embedding 子系统的事,和聊天端点无关。

谁会把 Khoj 接到一个网关上

• 想在自己的笔记上获得旗舰模型聊天体验、又不想给每个模型家族各开一个厂商账号的自部署用户,一个 Key 覆盖 Claude、GPT、DeepSeek、Gemini
• 每天跑定时自动化的用户,一个快速 ID 能让循环成本保持平坦,用量日志让它看得见
• 注重隐私的部署,索引和 Embedding 保留在本地,只把聊天提示词暴露给一个可审计的端点
• 在完全相同的个人语料库上对比聊天模型的爱折腾用户,每个候选是对着同一个 AI Model API 加一行聊天模型
• 拿不到某家厂商官方支付渠道的开发者,充值即用不需要海外卡

验证接入与排查首次聊天

先检查网关:用你的 Key 列出模型,确认打算注册的 ID 都在。Khoj 自己的自动发现在首跑播种时做的是同一次调用,这条 curl 能跑通,播种也就能跑通。 失败点定位得很清楚。认证错误说明 AI Model API 条目上的 Api Key 不对,或者还是播种时的占位值。模型不存在说明聊天模型的 Name 和目录拼写不一致。回答半途截断多半是 Max prompt size 或模型的输出上限设得太低,配不上这次对话。索引和搜索的问题是本地 Embedding 管线的事,和这个端点无关。 聊天能跑起来之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。自动化和研究跑批是第二大脑成本最容易藏起来的地方,按 Key 的用量能让你按功能看清楚,而不是等到月底账单上一个惊喜。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $KKAIAPI_KEY" | head -50

常见问题