想体验本地大模型的强大能力，又希望拥有便捷的UI交互界面？Cherry Studio 正是你所需的工具。本教程将带你一步步完成从下载到配置的全流程，重点演示如何将vLLM部署在算力卡（如Ascend 910B4）上的本地大模型，通过OpenAI API兼容格式接入Cherry Studio。
核心内容
- Cherry Studio如何接入vLLM部署的本地大模型
- 详细步骤：从下载Cherry Studio到配置本地模型
- 注意事项：模型名称、API配置及OpenAI API兼容性问题
什么是Cherry Studio？
Cherry Studio 是一款便捷易用的UI客户端，其LLM来源既可以是各大云服务厂商，也可以是本地部署的大模型。下载后默认启用的模型服务商是硅基流动，使用起来快速而简单（参考：使用硅基流动API + Cherry Studio解锁DeepSeek R1满血版体验攻略）。
如何接入本地模型
下面我们将进入实际操作，具体步骤分为四步。
第一步：下载并安装Cherry Studio
从官方渠道下载Cherry Studio客户端，并完成安装。
小提示：安装后首次打开时，默认会连接到硅基流动服务。你可以稍后在设置中切换为本地模型。
第二步：进入模型服务设置
在Cherry Studio主界面，点击左侧的 设置（齿轮图标）→ 模型服务 → 选择 Ollama（注意：即便你的本地推理服务基于vLLM，Ollama与vLLM等中间件都支持OpenAI API兼容格式，因此选择Ollama条目即可完成配置）。
第三步：添加模型并配置API
- 点击下方的 添加 按钮。
- 在弹出的对话框中，填入你部署本地模型时设置的 模型名称（model-name），必须与vLLM部署时指定的名称完全一致。
- 点击 管理，将刚才添加的模型选中并确认。
- 接下来配置 API地址：一般格式为
http://你的服务器IP:端口/v1（例如http://192.168.1.100:8000/v1）。如果你没有设置API密钥，则无需填写API Key字段。
第四步：测试连接并选择默认模型
- 在模型服务界面，点击 检测 按钮。如果一切通畅，会提示 “连接成功”。
- 进入 默认模型 → 默认助手模型，从下拉列表中选择你刚添加的本地模型（即部署的ollama模型）。
完成上述步骤后，在主对话界面顶部的模型选择器中，就能看到你配置的本地模型了。
注意事项
- 模型名称必须准确：添加模型时填入的名称要和vLLM启动时指定的
--model-name或model参数完全一致，否则无法识别。 - API地址格式：请确认末尾包含
/v1，例如http://localhost:8000/v1。 - 关于OpenAI API兼容：虽然Cherry Studio设置界面也有“OpenAI”服务选项，但经过测试，直接选择OpenAI条目可能会因为API调用格式差异而失败。使用 Ollama 服务项来对接vLLM部署的模型是更稳定、更简洁的方案。
- API Key：如果vLLM启动时没有设置API Key，保持Cherry Studio中的API Key字段为空即可。
常见问题
Q1：为什么我点击“检测”时提示连接失败？
请检查以下几点：
- 确保vLLM服务已经成功启动，并且监听在正确的IP和端口上。
- 验证API地址格式是否正确（末尾须有
/v1）。 - 如果Cherry Studio和推理服务不在同一台机器，请确认防火墙已放行对应端口。
Q2：为什么Cherry Studio的“OpenAI”服务选项无法连接我的vLLM？
因为vLLM提供的OpenAI兼容接口在部分调用细节（如端点路径、请求格式）上与Cherry Studio的“OpenAI”默认配置不完全一致。经过实践，选择 Ollama 服务项可以完美兼容vLLM，所以推荐使用Ollama条目来配置。
Q3：我添加了模型名称，但对话时仍然看不到这个模型？
请确认你在“模型服务”中已经完成了 管理 操作（将添加的模型勾选启用），并且已经在“默认助手模型”里选择了该模型。此外，检测连接成功后，可能需要重启Cherry Studio才能使新模型完全生效。
通过以上步骤，你已经成功将本地vLLM部署的大模型与Cherry Studio连接起来。现在你可以享受流畅的本地AI对话体验，同时保留数据本地化的优势。如果配置过程中遇到其他问题，欢迎参考社区文档或留言交流。