接入方式
Cherry Studio 直接从当前电脑向 KingFlow AI 发送 OpenAI 兼容请求。API Key 会保存在客户端所在设备。
| 环节 | 职责 | 注意事项 |
|---|---|---|
| Cherry Studio | 保存服务商配置并发送聊天请求 | API Key 位于当前设备 |
| KingFlow AI | 校验密钥 统计用量并按模型 ID 路由 | 使用 OpenAI 兼容接口 |
| 上游模型 | 生成文本 代码或其他结果 | 能力取决于具体模型和通道 |
开始前的准备
- 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
- 从 KingFlow 控制台复制准备使用的完整模型 ID。模型名称相近时不要手工猜写。
- 从 Cherry Studio 官方发布页下载与系统和处理器架构匹配的版本。
- 准备一段不含隐私信息的测试提示词，首次联调不要上传正式文件或业务数据。
安装 Cherry Studio
| 系统 | 推荐下载 | 安装提示 |
|---|---|---|
| Windows | x64 或 ARM64 安装版 | 旧系统先确认兼容性和运行库 |
| **cOS | Apple 芯片或 Intel 对应版本 | 首次打开按系统提示确认来源 |
| Linux | AppI**ge DE* 或 RPM | 按发行版和处理器架构选择 |
先验证 KingFlow 接口
curl https://api.**nju**shen.com/v1/chat/completions \
-H "Authorization: *earer ${KINGFLOW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "<KingFlow控制台中的完整模型ID>",
"messages": [{"role": "user", "content": "只回复：连接成功"}],
"stream": false
}' 添加自定义服务商
| 设置项 | 填写内容 | 说明 |
|---|---|---|
| 服务商名称 | KingFlow AI | 便于在模型选择器中识别 |
| 服务商类型 | OpenAI | 使用 OpenAI 兼容聊天接口 |
| API Key | sk-你的密钥 | 粘贴完整密钥 不要增加引号 |
| API 地址 | https://api.**nju**shen.com/v1 | 填写根地址 不写 chat/completions |
| 服务商开关 | 开启 | 关闭时模型不会出现在选择器中 |
- 启动 Cherry Studio，打开左侧设置，再进入模型服务或服务商设置。不同版本的名称可能略有差异。
- 点击添加服务商，名称填写 KingFlow AI，服务商类型选择 OpenAI。
- 在 API 地址中填写 https://api.**nju**shen.com/v1，在 API Key 中粘贴自己的 sk- 密钥。
- 点击管理模型或添加模型。优先从返回的模型列表中选择，并点击模型右侧的加号加入当前服务商。
- 如果模型列表无法自动获取，手动输入 KingFlow 控制台显示的完整模型 ID。先只添加一个文本模型。
- 点击 API Key 输入框旁的检查按钮。检查会使用已添加列表中的最后一个聊天模型，因此要确保该模型可用。
- 确认检查成功后，打开服务商右上角的启用开关，返回聊天页选择 KingFlow AI 模型。
确认 API 地址
Cherry Studio 会拼接聊天端点，因此只填写 KingFlow 的 /v1 根地址。
| 情况 | 地址示例 | 处理原则 |
|---|---|---|
| 推荐写法 | https://api.**nju**shen.com/v1 | 标准 OpenAI 兼容根地址 |
| 不要填写 | https://api.**nju**shen.com/v1/chat/completions | 客户端会自动拼接聊天路径 |
| 不要重复 | .../v1/v1 | 升级或迁移配置时检查重复版本段 |
| 特殊完整地址 | 以服务商文档为准并按客户端规则处理 | 仅用于非标准路由 本教程不需要 |
添加和选择模型
- 打开 KingFlow AI 服务商的模型管理窗口，先尝试获取可用模型。
- 点击目标模型右侧的加号，将其加入服务商页面的模型列表。
- 自动列表为空时，复制 KingFlow 控制台中的完整模型 ID 并手动添加。
- 为便于排错，首轮只保留一个已授权的聊天模型；连接成功后再逐个增加。
- 回到聊天页新建会话，从顶部模型选择器选择 KingFlow AI 和目标模型。
| 任务 | 模型选择 | 参数起点 |
|---|---|---|
| 日常问答 | 选择响应快 成本适中的文本模型 | 温度可从 0.5 到 0.8 试用 |
| 代码与分析 | 选择支持长上下文或推理的模型 | 温度可从 0.1 到 0.3 起步 |
| 长文档 | 确认上下文窗口和文件能力 | 先用小文件验证 再扩大规模 |
| 图像或工具 | 确认模型与接口均支持对应能力 | 不能只按模型名称判断 |
完成首次对话验证
- 发送一句短问题，确认模型返回完整内容且没有 401、404 或 503。
- 连续追问两到三轮，确认上下文能够延续，回复不会异常截断。
- 新建另一个会话并切换模型，确认服务商名称和模型选择器显示正确。
- 检查 KingFlow 控制台中的调用记录或余额变化，确认请求归属当前密钥。
- 关闭并重新打开 Cherry Studio，确认服务商、模型列表和默认模型仍然保留。
日常使用建议
- 可以为不同任务创建独立助手。例如将代码助手固定到低温度模型，将写作助手固定到更自然的参数。
- 切换模型不会自动清除当前对话上下文。如果不同模型的上下文或能力差异较大，建议新建会话再切换。
- Cherry Studio 支持在同一服务商中配置多个密钥并按顺序轮换，多个密钥需用英文逗号分隔。仅在密钥均属于你且配额规则明确时使用。
- Token 计数和客户端显示通常是估算值，实际计费以 KingFlow 控制台记录为准。
保护 API Key 和业务数据
- 桌面客户端需要在本机保存 API Key。只在受信任设备上配置，避免在公用电脑或远程共享桌面中长期保存。
- 不要把完整密钥写进截图、教程、聊天消息、同步笔记或公开问题反馈。演示内容应使用 sk-**** 之类的占位符。
- 为不同设备或成员创建独立密钥，并在 KingFlow 控制台设置合理的额度和有效期。设备丢失时可以单独撤销。
- 定期检查调用明细。发现异常请求时先撤销旧密钥，再创建新密钥并更新客户端。
- 发送文件前确认其敏感级别。客户端配置成功不代表所有业务数据都适合提交给外部模型。
常见故障排查
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 检查按钮失败 | 最后一个模型不可用或未添加聊天模型 | 先只保留一个已授权文本模型再检查 |
| 401 未授权 | 密钥错误 已停用或额度不可用 | 重新复制密钥并检查控制台状态 |
| 404 模型不存在 | 模型 ID 错误或分组不支持 | 从控制台复制完整模型 ID |
| 404 接口不存在 | 地址包含重复路径或写入完整端点 | 改回 https://api.**nju**shen.com/v1 |
| 503 暂时不可用 | 上游通道繁忙或暂无可用账号 | 稍后有限重试或切换已授权模型 |
| 模型选择器找不到 | 模型未加入列表或服务商未启用 | 点击加号添加模型并开启服务商开关 |
| 回复中途停止 | 输出上限 网络中断或模型限制 | 缩短请求 检查参数并再次测试 |
| 费用异常 | 密钥泄露或多设备共用难以审计 | 撤销密钥并为设备分配独立密钥 |
完成检查清单
- Cherry Studio 安装包来自官方发布渠道并匹配设备架构。
- KingFlow 最小 curl 请求已经成功。
- 自定义服务商类型为 OpenAI，API 地址为 https://api.**nju**shen.com/v1。
- 目标模型 ID 来自 KingFlow 控制台，没有手工猜写。
- 连通性检查成功，服务商启用开关已经打开。
- 短对话、连续对话、模型切换和重启验证均已通过。
- API Key 没有出现在截图、聊天记录或公开文件中。
