企业官网建设流程全解析

Cherry Studio 接入私有模型：3 步把自训练端点接进对话列表

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

团队刚把一个微调模型部署到内网，服务跑通了，怎么让它出现在 Cherry Studio 的模型下拉框里？其实 Cherry Studio 自定义模型的接入比想象中省事：不用改客户端任何代码，只要后端提供一个 OpenAI 兼容的端点，在设置页填好地址和模型标识，就能直接开聊。下面按「先跑通 → 看字段 → 对契约 → 查坑 → 调性能」的顺序讲一遍。

快速上手：三步把私有模型接进对话列表

1. 服务侧：让推理端点兼容 OpenAI Chat Completions 协议即可，vLLM、Ollama、LM Studio 这类现成方案开箱就是，不用自研网关。
2. 客户端：打开 Cherry Studio 的「设置 → 提供商设置」，新增一个自定义提供商，填名称、端点地址（baseURL）和 API Key（服务不做鉴权的话 Key 随便填个占位值）。
3. 加模型：在该提供商下添加一个模型，填模型 ID 和上下文长度，保存后它就出现在会话的模型列表里，选中即聊。

这三步走完，模型就已经在对话列表里了，剩下的都是细节打磨。

模型端点配置：哪些字段不能省

设置页的字段看着多，真正决定接入成败的就这五个，逐个说：

• 端点地址（baseURL）：请求组装时的根路径，只填到网关基础段、别带具体接口路径，例如http://192.168.1.20:8000/v1。
• 协议族（adapter family）：决定客户端怎么打包请求。OpenAI 兼容端点选openai-chat-completions，Anthropic 风格服务选anthropic-messages，Ollama 走自己的选项，选错直接 404。
• API Key：服务没鉴权也建议填个占位值，部分内网网关会检查请求头是否存在，空值反而容易挂。
• 模型 ID：请求体model字段里发出的字面值，必须和服务端注册的模型名一字不差；下拉框里的显示名随便起，不影响这个值。
• 上下文长度（contextWindow）：模型能接受的总 token 数，按微调模型的实际值填，填小了对话中途就会被截断。

可选的最大输出长度（maxOutputTokens）建议也顺手填一下，它给单次回复封顶，防止模型把上下文聊爆。

这些配置保存在本地，客户端在每次发送时读取并决定走哪个适配器、打哪个 URL，属于纯本地解析，不与服务端做额外握手。

服务端契约：请求和长什么样

只要端点能吃下面这种形状的请求、回对应形状，就算合格。非流式响应里客户端会读choices[0].message.content、finish_reason和usage；流式则是 SSE，每个 chunk 带choices[0].delta.content片段，以data: [DONE]收尾。一个最小可用的端点大概长这样：

@app.post("/v1/chat/completions") def chat(req: ChatRequest): text = model.generate(req.messages, max_tokens=req.max_tokens) return { "id": "cmpl-local", "model": req.model, "choices": [{ "index": 0, "message": {"role": "assistant", "content": text}, "finish_reason": "stop", }], "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}, }

配置里的 Provider 信息正是从本地存储取出后注入这条请求链的，这也是为什么端点填错时客户端能立刻报 404 而不是超时。

接入后建议先用 curl 冒烟一次，确认协议层没问题再进客户端：

curl http://192.168.1.20:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"my-finetune-v3","messages":[{"role":"user","content":"hi"}],"stream":false}'

踩坑速查：四个高频问题

发送报 404，但连接测试通过。十有八九是端点地址里已经把/chat/completions拼进去了，客户端会再拼一层路径。地址里只留基础段，接口路径交给客户端。

返回 401 / Unauthorized。先确认请求头真的带上了 Key，再检查 Key 末尾有没有多敲空格或换行——复制粘贴时这个坑特别常见。

回复一次性全量出现，没有流式效果。说明服务端没处理stream: true。可以先用非流式把链路跑通，再补 SSE 分段输出，别在两个问题里同时调试。

对话聊一半就断了或变敷衍。多半是上下文长度填小了，请求的max_tokens加上历史消息超过了contextWindow，调大后重试即可。

性能与资源调优：能落地的三件事

量化加载（4-bit / 8-bit）是内存压力下的首选，同一模型显存占用能砍到原来的三分之一左右，质量损失通常在可接受范围。给推理 worker 的并发数设上限，单卡吃两三个并发流就到极限，排队比把服务打挂强得多。如果首 token 延迟偏高，优先确认模型跑在本地 GPU 且开启了 KV cache，这两点的收益远大于在客户端调参数。

收尾

说白了，Cherry Studio 接入私有模型在客户端侧没有任何黑魔法：端点做到 OpenAI 兼容、地址和模型 ID 填对，就能开聊；模型目录与解析机制的细节可以看 provider-registry 的说明，请求如何从协议族映射到具体适配器则写在 provider-resolution 文档 里。遇到怪问题别闷头猜，直接在项目里提一个 Issue 附上服务端日志，大概率有人踩过同一个坑。

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio