Cherry Studio API使用指南-平芜编程栈

Cherry Studio API使用指南

【免费下载链接】cherry-studio🍒 Cherry Studio is a desktop client that supports for multiple LLM providers. Support deepseek-r1项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

基础指南

关于Cherry Studio

Cherry Studio是一款支持多LLM提供商的桌面客户端，为开发者提供统一API接口访问不同AI服务，目前已支持DeepSeek-R1等模型，具备对话管理、流式响应等核心功能。

环境准备

从官方渠道获取Cherry Studio客户端并完成安装
通过以下命令启动服务

cherry-studio start --port 8080 --api-key your-api-key

认证方式

所有API请求需在Header中包含认证信息：

Authorization: Bearer your-api-key

核心功能

🔑 主要能力

多LLM提供商集成：统一接口访问不同AI服务
对话管理：维护多轮对话上下文
流式响应：实时获取文本生成结果
文件处理：文档上传和分析功能（开发中）
插件系统：扩展功能模块支持（开发中）

消息生命周期

Cherry Studio的消息处理流程涉及多个组件协同工作，包括网络搜索、知识库、大模型、MCP等模块，以下是完整的消息生命周期图示：

接口详解

聊天补全接口

端点:POST /api/v1/chat/completions

请求参数

model: 模型ID（必填）
messages: 对话消息数组，每个消息包含role和content字段
temperature: 生成温度，0-1之间，默认0.7
stream: 是否启用流式响应，默认false
provider: 模型提供商，如deepseek、openai等

示例代码

fetch('http://localhost:8080/api/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ model: 'deepseek-r1', messages: [{ role: 'user', content: 'Hello' }], stream: false }) }).then(res => res.json()).then(data => console.log(data));

注意：流式响应与普通响应的处理方式不同，需要通过WebSocket或读取流的方式接收数据

模型列表接口

端点:GET /api/v1/models

响应说明

返回当前支持的所有模型列表，包括模型ID、创建时间、所属提供商等信息。

示例响应

{ "object": "list", "data": [ { "id": "deepseek-r1", "object": "model", "created": 1677652288, "owned_by": "deepseek" }, { "id": "gpt-4", "object": "model", "created": 1677652288, "owned_by": "openai" } ] }

流式聊天接口

端点:POST /api/v1/chat/completions（stream=true）

示例代码

const response = await fetch('http://localhost:8080/api/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ model: 'deepseek-r1', messages: [{ role: 'user', content: 'Hello' }], stream: true }) }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); // 处理流式数据 }

高级应用

配置管理

关键配置参数：

api.port: 服务端口，默认8080
providers.*.api_key: 各提供商API密钥
logging.level: 日志级别，默认info

环境变量配置：

CHERRY_API_KEY: API认证密钥
DEEPSEEK_API_KEY: DeepSeek API密钥
CHERRY_PORT: 服务端口

最佳实践

错误处理

常见错误代码及处理方式：

invalid_api_key: 401，检查API密钥是否正确
rate_limit_exceeded: 429，减少请求频率
model_not_found: 404，确认模型ID是否正确

性能优化

实现请求重试机制，处理临时网络问题
合理设置temperature和max_tokens参数
对高频接口使用缓存机制

常见问题

连接超时

检查服务是否正常运行
验证端口是否正确且未被占用
检查防火墙设置是否阻止连接

响应异常

查看服务日志获取详细错误信息
确认请求参数格式是否正确
检查模型提供商服务状态

扩展开发

Cherry Studio支持自定义提供商集成，通过实现Provider接口可以添加新的AI服务支持。详细开发指南请参考源代码中的示例实现。

小贴士：开发自定义提供商时，建议先熟悉现有提供商的实现方式，位于src/main/services/agents/providers/目录下

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Cherry Studio API使用指南