LibreChat 自定义端点配置

先说结论:librechat.yaml 里一个块

LibreChat 的自定义端点配置在 librechat.yaml 的 endpoints.custom 下,是一份数组,每个条目对应一个供应商。三个关键字段是 name(端点选择器里显示的标签)、apiKey(支持 ${变量名} 形式插值环境变量,所以 Key 留在 .env 里,永远不出现在 YAML 里)、baseURL。对 kkaiapi 来说 baseURL 是 https://api.kkaiapi.com/v1,要带上 /v1,因为 LibreChat 会在你给的 base 后面拼接 /chat/completions 这类路由路径。 models 块决定模型下拉里显示什么。把 models.fetch 设成 true,LibreChat 加载时会去查端点的 /v1/models 列表,目录里的每个 ID 就都能直接选,不用手写维护一份列表。models.default 仍然是必填的数组,是 fetch 之前或者 fetch 失败时的兜底展示。这是有据可查的上游配置,不是打的补丁:LibreChat 文档里的自定义端点对象结构定义了这里用到的每一个键。

version: 1.2.1
endpoints:
  custom:
    - name: "kkaiapi"
      apiKey: "${KKAIAPI_KEY}"
      baseURL: "https://api.kkaiapi.com/v1"
      models:
        default: ["claude-sonnet-4-6"]
        fetch: true

LibreChat 怎么路由自定义端点

LibreChat(GitHub 上的 danny-avila,约 41K 星标)是部署量最大的自建 ChatGPT 式界面:多用户、多模型,带对话搜索、Agent、文件处理和按用户密钥。和那些写死一份供应商列表的客户端不同,它的 endpoints.custom 数组接受任何 OpenAI 兼容服务,文档里几个知名供应商就是靠这个机制配置的。 当用户从一个自定义端点里选了一个模型,LibreChat 会向那个端点的 baseURL 发一个标准 /v1/chat/completions 请求,模型字段按纯字符串传递。客户端不关心这个模型是哪家训练的;当 baseURL 背后的端点服务多个厂商,一条 librechat.yaml 条目就能把 Claude、GPT、Gemini、DeepSeek、GLM 的 ID 放进同一个下拉框,用户可以在对话中途换厂商,就像换两个 GPT 变体一样简单。 这直接省掉了常见的 LibreChat 多供应商配置。不用给每家厂商配一个各自的 .env 密钥和各自的计费面,一个条目一个 Key 就覆盖整个目录,管理员在一个地方看每个模型的用量,不用去核对好几个厂商的仪表盘。

完整配置:YAML、.env、Docker 挂载

在项目根目录创建 librechat.yaml,把 Key 放进 .env。YAML 里的 ${KKAIAPI_KEY} 引用会在启动时从环境解析,所以配置文件本身能安心提交进版本控制。 首次配置最容易漏掉的一步是 Docker 特有的:容器默认看不到你的 librechat.yaml,除非挂载它。文档要求你创建 docker-compose.override.yml,把 ./librechat.yaml 绑定挂载到 /app/librechat.yaml,再重建容器。之后改动 YAML 同样需要重启,因为文件只在启动时读取,不是被实时监听的。 几个可选字段值得在网关条目上设置。titleConvo 打开自动生成对话标题,titleModel 选负责写标题的模型;LibreChat 文档记录的 titleModel 默认值是 gpt-3.5-turbo,一个非 OpenAI 端点可能不提供的 ID,所以显式设成一个快速的目录 ID,或者用特殊值 current_model。modelDisplayLabel 控制助手消息上显示的名字。apiKey 还接受特殊值 user_provided,如果你想让每个用户粘贴自己的 Key,而不是共享服务器的 Key。

version: 1.2.1
endpoints:
  custom:
    - name: "kkaiapi"
      apiKey: "${KKAIAPI_KEY}"
      baseURL: "https://api.kkaiapi.com/v1"
      models:
        default: ["claude-sonnet-4-6", "gpt-5.5", "deepseek-v4-pro"]
        fetch: true
      titleConvo: true
      titleModel: "claude-haiku-4-5-20251001"
      modelDisplayLabel: "kkaiapi"

给共享聊天工作区选模型

因为每个模型都走同一个 Key 计费,管理员实际的做法是看一周控制台用量,看用户真正点了哪些模型,把 models.default 收窄到匹配的范围,同时保持 fetch 打开,让高级用户仍能够到完整列表。

• 日常主力聊天要一个强通用模型。claude-sonnet-4-6 和 gpt-5.5 能扛住长对话、文件讨论和 Agent 运行,不用为每条消息焦虑选哪个模型
• 高频短问题是走量工作。claude-haiku-4-5-20251001 和 gemini-3.5-flash 回答快,能防止一个多用户部署把花费集中在随手一问上
• 标题生成在每次对话都会触发。把 titleModel 指向一个快速 ID;拿旗舰价格写六个字的标题,是 LibreChat 部署里最常见的隐性浪费
• 多语言团队应该在自己真实的语言混合场景里测 deepseek-v4-pro 和 glm-5.2;一个多厂商下拉框能让这变成应用内对比,而不是重新配置
• models.fetch 意味着新的目录模型不用改 YAML 就能出现,上游新加的模型在下次列表刷新时就能选

主力模型价格

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

LibreChat 专属的翻车点

配置悄悄没生效是最经典的坑,几乎都是 Docker 挂载的问题。没有 docker-compose.override.yml 的绑定挂载,容器就跑在完全没有 librechat.yaml 的状态下,自定义端点永远不会出现在选择器里,也不会有任何报错。先确认文件确实在容器里存在,再排查别的。 一个字面显示成 ${KKAIAPI_KEY} 的 apiKey 意味着服务器启动时的环境里没有这个变量;插值发生在启动时从 .env 读取,后加的 Key 需要重启容器。表现症状是网关返回一个鉴权信息乱七八糟的 401。 baseURL 没带 /v1 会让每个请求都 404,因为 LibreChat 会在给定的 base 后面拼接 /chat/completions。反过来的错误是把一整条 completions 网址填进 baseURL,那属于单独的 directEndpoint 选项,不该和普通条目混用。 fetch 关闭时模型下拉是空的,说明 models.default 缺失或者是空数组,它是必填的数组。fetch 打开时下拉是空的,通常是 fetch 本身失败了,又绕回 Key 或 baseURL 的问题。端点本身能用但对话标题失败,是 titleModel 默认值指向了一个网关不提供的 ID,显式设置它。

哪些人会把 LibreChat 接到一个网关上

• 自建共享聊天工作区的团队,想要一个下拉框里有 Claude、GPT、Gemini、DeepSeek,不用维护一份 endpoints.custom 条目加一个厂商账号
• 跑多用户部署、需要单一用量视图的管理员,按 Key 的日志能显示团队实际用了哪些模型,不用去合并厂商仪表盘
• 给部门发各自 Key 的运营者:同一份 YAML,一个部门一个 Key,用量日志就是按团队的成本报表
• 用一个按量计费端点替换几份聊天订阅的家庭或小团队,按用了多少 token 付费,而不是按座位付费
• 手头没有某家厂商官方支付渠道的开发者,充值即用不需要海外卡

验证接入与排查首条消息

动 LibreChat 之前先证明网关这一半没问题:用你的 Key 列出模型,确认 models.default 里的 ID 都在里面。这一步通过之后,剩下的症状都在 LibreChat 这一侧。 然后启动整套服务,打开端点选择器。kkaiapi 条目出现说明 YAML 加载成功;模型列表填充了说明 fetch 和 Key 都对;第一次回复说明聊天路径通了。按这个顺序逐一确认,而不是一次全看,因为挂载、环境变量、baseURL 各自对应一套独立的失败模式。 消息跑通之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。一个共享的 LibreChat 实例正是用量会悄悄集中在两三个模型上的典型场景,用量日志能在账单出来之前告诉你是哪几个。

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

常见问题