给 Cherry Studio 接入私有模型自定义模型完整教程【免费下载链接】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你的 LLM 跑在 vLLM、Ollama 或某个内网网关上而 Cherry Studio 默认列表里只有那些商业大厂商——想接入自己的私有模型时路径其实很短加一个 OpenAI 兼容端点再挂上模型 ID 就行。这篇教程带你走通从填 URL 到请求真正打到模型服务的全过程。Cherry Studio 的自定义模型接入本质是加一个 Provider 加一个 Model两步只要你的私有服务讲 OpenAI 兼容协议在设置页填好基地址、模型 ID 和能力开关即可不需要写任何代码。本文按三步跑通 → 机制拆解 → 配置逐项说明 → 避坑实录的顺序展开核心关键词是 Cherry Studio 自定义模型顺带覆盖私有模型怎么接OpenAI 兼容端点怎么配这两个长尾问题。三步跑通最小闭环先给结论一个 OpenAI 兼容的/v1/chat/completions服务在 Cherry Studio 里接入只需要三个动作。第一步确认你的服务能用裸协议对话。这一步是干嘛的——在动 Cherry Studio 之前先证明端点本身是活的把后面连不上的排查面缩到最小curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxx \ -d {model: my-model, messages: [{role: user, content: hi}]}curl 能吐回正常的choices结构再往下走吐 404 或 401问题在服务侧与 Cherry Studio 无关。第二步在 Provider 设置里建连接。打开「设置 → 提供商」选一个 OpenAI 兼容的提供商或自定义 Provider填入基地址Base URL和 API Key。注意这里填的是根地址例如http://localhost:8000具体打到哪个路由由后面的端点类型决定不要手动拼/v1/chat/completions。第三步在这个 Provider 下添加模型。模型抽屉里有几个字段Model ID与服务端返回的model字段一致、显示名、上下文窗口、最大输入/输出 Token、端点类型、能力开关。Model ID 填对其他保持默认就能正常对话了。到这里最小闭环已经通了新会话里选中这个模型发消息返回正常即接入成功。它到底是怎么跑起来的界面填完的字段在请求发出时会经历一条固定的解析链看懂这条链后面所有配置项就都通了渲染进程里useChat发送消息经 Electron IPC 的ai.stream.open通道交给主进程src/main/ipc/handlers/ai.ts。主进程按模型 → 端点类型解析这次请求该走哪套协议。关键一步是查provider.endpointConfigs[endpointType].adapterFamily你选了anthropic-messages就走 Anthropic SDK没配就默认落到openai-compatible——这就是为什么大多数私有模型什么都不用选也能跑。解析出 SDK 后用第二步填的 Base URL 和 Key 构造 provider 配置apiKey/baseURL发起流式请求。流式 chunk 在主进程内扇出广播给窗口渲染、落库持久化到 SQLite、推给 SSE 通道。这条链的设计意图可以概括为一句话协议选择在建 Provider 时就写死了运行时只做只读解析所以你不会在聊天中途遇到同一句话一会儿走 OpenAI 一会儿走 Anthropic的灵异现象。完整解析逻辑见 docs/references/ai/provider-resolution.md代码在 src/main/ai/provider/。配置项逐个说真正值得改的只有四个模型抽屉里的字段不少但 90% 的人只需要动这四个其余分组、价格、备注一笔带过即可。基地址Base URL——为什么这么设它决定所有请求的根。内网模型服务常挂在网关后面比如https://llm.internal/v1填成网关根就行如果服务本身要求带/v1前缀才能路由那就带上。它是连接不上类问题第一嫌疑位后面避坑还会再讲。Model ID——为什么必须精确它原样发进请求体的model字段服务端靠它做路由。你本地跑的是qwen2.5-7b-instruct就填这个别填显示名。填错的症状不是报错而是服务端返回model not found容易被误判为Cherry Studio 的 bug。上下文窗口contextWindow与最大输出 Token——为什么建议填Cherry Studio 靠这两个数做上下文裁剪和用量展示。不填就走保守默认表现为长对话被提前截断、顶部 token 计数不准。按模型训练时的真实值填7B 级常见 32K/8K具体看你的推理框架配置不要拍脑袋填 128K。端点类型与能力开关——什么时候需要动端点类型决定协议族openai-chat-completions是默认且覆盖最广的选择只有当你的服务是 Anthropic Messages 协议或 Responses 协议时才改。能力开关里reasoning和function_call两个按模型实际能力开开了function_call但模型不支持模型会吐出格式错误的工具调用不开Agent 功能在该模型上静默降级。这些坑我替你踩过现象请求一律 404但 curl 明明通的。原因curl 用的是带/v1/chat/completions的全路径而基地址里也填了这段最终拼成了.../v1/chat/completions/v1/chat/completions。 处理基地址只留根到网关或服务的 host 级路径交给端点类型去拼改完用第二步的 curl 对照验证一次。现象短对话正常长对话回答质量断崖式下跌且没有报错。原因没填上下文窗口Cherry Studio 按保守默认值裁剪历史早期对话轮次被悄悄丢掉了。 处理按模型真实窗口补填contextWindow同时确认maxOutputTokens没被填得比窗口还大。现象开了 Agent/工具调用模型开始输出乱码般的函数片段。原因模型能力开关勾了function_call但私有模型根本没做工具调用训练协议层把它的胡言乱语当成合法 tool call 解析。 处理把该模型的能力开关关掉只用它的纯对话能力如果确实有工具调用需求换经过 tool-calling 对齐的 checkpoint 重新部署。收个尾Cherry Studio 自定义模型接入门槛并不高一个 OpenAI 兼容端点、一个 Model ID私有模型就能进你的工作流。想继续深入推荐从 docs/references/ai/core-architecture.md 的端到端消息流讲起再到 packages/provider-registry 看预设 Provider 目录是怎么和你手填的配置合并的。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 给 Cherry Studio 接入私有模型：自定义模型完整教程
给 Cherry Studio 接入私有模型自定义模型完整教程【免费下载链接】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你的 LLM 跑在 vLLM、Ollama 或某个内网网关上而 Cherry Studio 默认列表里只有那些商业大厂商——想接入自己的私有模型时路径其实很短加一个 OpenAI 兼容端点再挂上模型 ID 就行。这篇教程带你走通从填 URL 到请求真正打到模型服务的全过程。Cherry Studio 的自定义模型接入本质是加一个 Provider 加一个 Model两步只要你的私有服务讲 OpenAI 兼容协议在设置页填好基地址、模型 ID 和能力开关即可不需要写任何代码。本文按三步跑通 → 机制拆解 → 配置逐项说明 → 避坑实录的顺序展开核心关键词是 Cherry Studio 自定义模型顺带覆盖私有模型怎么接OpenAI 兼容端点怎么配这两个长尾问题。三步跑通最小闭环先给结论一个 OpenAI 兼容的/v1/chat/completions服务在 Cherry Studio 里接入只需要三个动作。第一步确认你的服务能用裸协议对话。这一步是干嘛的——在动 Cherry Studio 之前先证明端点本身是活的把后面连不上的排查面缩到最小curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxx \ -d {model: my-model, messages: [{role: user, content: hi}]}curl 能吐回正常的choices结构再往下走吐 404 或 401问题在服务侧与 Cherry Studio 无关。第二步在 Provider 设置里建连接。打开「设置 → 提供商」选一个 OpenAI 兼容的提供商或自定义 Provider填入基地址Base URL和 API Key。注意这里填的是根地址例如http://localhost:8000具体打到哪个路由由后面的端点类型决定不要手动拼/v1/chat/completions。第三步在这个 Provider 下添加模型。模型抽屉里有几个字段Model ID与服务端返回的model字段一致、显示名、上下文窗口、最大输入/输出 Token、端点类型、能力开关。Model ID 填对其他保持默认就能正常对话了。到这里最小闭环已经通了新会话里选中这个模型发消息返回正常即接入成功。它到底是怎么跑起来的界面填完的字段在请求发出时会经历一条固定的解析链看懂这条链后面所有配置项就都通了渲染进程里useChat发送消息经 Electron IPC 的ai.stream.open通道交给主进程src/main/ipc/handlers/ai.ts。主进程按模型 → 端点类型解析这次请求该走哪套协议。关键一步是查provider.endpointConfigs[endpointType].adapterFamily你选了anthropic-messages就走 Anthropic SDK没配就默认落到openai-compatible——这就是为什么大多数私有模型什么都不用选也能跑。解析出 SDK 后用第二步填的 Base URL 和 Key 构造 provider 配置apiKey/baseURL发起流式请求。流式 chunk 在主进程内扇出广播给窗口渲染、落库持久化到 SQLite、推给 SSE 通道。这条链的设计意图可以概括为一句话协议选择在建 Provider 时就写死了运行时只做只读解析所以你不会在聊天中途遇到同一句话一会儿走 OpenAI 一会儿走 Anthropic的灵异现象。完整解析逻辑见 docs/references/ai/provider-resolution.md代码在 src/main/ai/provider/。配置项逐个说真正值得改的只有四个模型抽屉里的字段不少但 90% 的人只需要动这四个其余分组、价格、备注一笔带过即可。基地址Base URL——为什么这么设它决定所有请求的根。内网模型服务常挂在网关后面比如https://llm.internal/v1填成网关根就行如果服务本身要求带/v1前缀才能路由那就带上。它是连接不上类问题第一嫌疑位后面避坑还会再讲。Model ID——为什么必须精确它原样发进请求体的model字段服务端靠它做路由。你本地跑的是qwen2.5-7b-instruct就填这个别填显示名。填错的症状不是报错而是服务端返回model not found容易被误判为Cherry Studio 的 bug。上下文窗口contextWindow与最大输出 Token——为什么建议填Cherry Studio 靠这两个数做上下文裁剪和用量展示。不填就走保守默认表现为长对话被提前截断、顶部 token 计数不准。按模型训练时的真实值填7B 级常见 32K/8K具体看你的推理框架配置不要拍脑袋填 128K。端点类型与能力开关——什么时候需要动端点类型决定协议族openai-chat-completions是默认且覆盖最广的选择只有当你的服务是 Anthropic Messages 协议或 Responses 协议时才改。能力开关里reasoning和function_call两个按模型实际能力开开了function_call但模型不支持模型会吐出格式错误的工具调用不开Agent 功能在该模型上静默降级。这些坑我替你踩过现象请求一律 404但 curl 明明通的。原因curl 用的是带/v1/chat/completions的全路径而基地址里也填了这段最终拼成了.../v1/chat/completions/v1/chat/completions。 处理基地址只留根到网关或服务的 host 级路径交给端点类型去拼改完用第二步的 curl 对照验证一次。现象短对话正常长对话回答质量断崖式下跌且没有报错。原因没填上下文窗口Cherry Studio 按保守默认值裁剪历史早期对话轮次被悄悄丢掉了。 处理按模型真实窗口补填contextWindow同时确认maxOutputTokens没被填得比窗口还大。现象开了 Agent/工具调用模型开始输出乱码般的函数片段。原因模型能力开关勾了function_call但私有模型根本没做工具调用训练协议层把它的胡言乱语当成合法 tool call 解析。 处理把该模型的能力开关关掉只用它的纯对话能力如果确实有工具调用需求换经过 tool-calling 对齐的 checkpoint 重新部署。收个尾Cherry Studio 自定义模型接入门槛并不高一个 OpenAI 兼容端点、一个 Model ID私有模型就能进你的工作流。想继续深入推荐从 docs/references/ai/core-architecture.md 的端到端消息流讲起再到 packages/provider-registry 看预设 Provider 目录是怎么和你手填的配置合并的。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考