跳转到内容
悠然 AI 文档

其他兼容客户端

悠然 AI 可以接入大量支持 OpenAI 协议的第三方客户端，但“OpenAI 兼容”并不等于所有 OpenAI 功能都可用。客户端还需要允许自定义 Base URL、API Key 和模型 ID，并且只调用悠然 AI 已开放的端点。

兼容条件

Section titled “兼容条件”

接入前请确认客户端同时满足以下条件：

条件 悠然 AI 要求
Base URL 可以自定义为 https://youran-ai.du-fu.com/api
API Key 使用标准 Authorization: Bearer 请求头
模型列表 请求 GET {Base URL}/models，或允许手工填写模型 ID
对话协议 支持 OpenAI Chat Completions，或 OpenAI Responses
流式输出 能处理标准 SSE 流式响应
模型名称 允许使用 /api/models 返回的实际模型 ID

悠然 AI 当前公开的 OpenAI 兼容端点包括：

方法 最终请求地址
GET https://youran-ai.du-fu.com/api/models
POST https://youran-ai.du-fu.com/api/chat/completions
POST https://youran-ai.du-fu.com/api/responses

不兼容或仅部分兼容的情况

Section titled “不兼容或仅部分兼容的情况”

以下客户端不能直接保证可用：

  • Base URL 固定为 https://api.openai.com/v1，不允许修改。
  • 强制在自定义 Base URL 后再追加 /v1，且无法关闭。
  • 只能使用 OpenAI 官方 OAuth 登录，不接受独立 API Key。
  • 模型被固定在客户端内置白名单中，无法填写 /api/models 返回的模型 ID。
  • 必须调用 Embeddings、Images、Audio、Files、Assistants、Batches 或其他未开放的 OpenAI 端点。
  • 依赖 OpenAI 官方专属能力，而不是标准 Chat Completions 或 Responses 请求格式。

遇到不确定的客户端时，先查找设置中的 “OpenAI Compatible”“Custom OpenAI”“API Base” 或 “Endpoint” 选项，再对照本页的三个公开端点。

示例一：Cherry Studio（国内）

Section titled “示例一：Cherry Studio（国内）”

Cherry Studio 是国内用户常用的开源桌面 AI 客户端，支持 Windows、macOS 和 Linux。它可以添加 OpenAI 类型的自定义服务商，并单独配置 API 地址、API Key 和模型 ID。

  1. 打开 设置 → 模型服务，点击服务商列表底部的 添加。
  2. 服务商名称填写“悠然 AI”，服务商类型选择 OpenAI。
  3. 按下表完成配置：
字段 填写内容
API 密钥 当前悠然 AI API Key
API 地址 https://youran-ai.du-fu.com/api
模型 手工添加 /api/models 返回的一个实际模型 ID
启用状态 打开
  1. 点击 API 密钥右侧的 检查。验证通过后，在聊天页面选择刚添加的服务商和模型。
  2. 先使用纯文本对话确认连接。图片、知识库或联网等增强功能可能调用悠然 AI 尚未开放的端点，是否可用取决于客户端的实际请求。

具体界面与操作见 Cherry Studio 自定义服务商官方文档。

示例二：Chatbox（国内）

Section titled “示例二：Chatbox（国内）”

Chatbox 是国内开发的开源跨平台 AI 客户端。它将 API 主机与 API 路径分开配置，因此需要覆盖默认的 /v1/chat/completions 路径。

  1. 打开 设置 → 模型提供方，点击底部的 添加。
  2. 提供方名称填写“悠然 AI”，API 类型选择 OpenAI API 兼容。
  3. 按下表完成配置：
字段 填写内容
API 密钥 当前悠然 AI API Key
API 主机 https://youran-ai.du-fu.com
API 路径 /api/chat/completions
模型 手工添加 /api/models 返回的一个实际模型 ID
模型能力 首次接入可不勾选，按纯文本模型验证
  1. 保存后点击 检查。连接成功后，回到首页新建对话并选择刚添加的模型。

具体界面与字段说明见 Chatbox 模型配置官方文档。

Cursor

Section titled “Cursor”

Cursor 已按操作系统拆分为独立工具页面：

  • Windows：Cursor：包含完整的 API Key、Base URL、模型和验证步骤。
  • macOS：Cursor：配置与 Windows 完全一致，页面会跳转到同一配置说明。

示例三：Aider

Section titled “示例三：Aider”

Aider 是终端中的开源 AI 编程助手。它的官方文档支持使用 OPENAI_API_BASE、OPENAI_API_KEY 和 openai/<MODEL_ID> 连接 OpenAI 兼容服务。

安装

Section titled “安装”

macOS 或 Linux：

Shell
curl -LsSf https://aider.chat/install.sh | sh

Windows PowerShell：

PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"

查询模型

Section titled “查询模型”
Shell
curl -sS https://youran-ai.du-fu.com/api/models \
  -H "Authorization: Bearer <YOURAN_API_KEY>"

配置并启动

Section titled “配置并启动”

macOS 或 Linux：

Shell
export OPENAI_API_BASE="https://youran-ai.du-fu.com/api"
export OPENAI_API_KEY="<YOURAN_API_KEY>"
aider --model "openai/<MODEL_ID>"

Windows PowerShell：

PowerShell
$env:OPENAI_API_BASE = "https://youran-ai.du-fu.com/api"
$env:OPENAI_API_KEY = "<YOURAN_API_KEY>"
aider --model "openai/<MODEL_ID>"

<MODEL_ID> 必须替换为模型列表中的真实 ID。Aider 如果提示模型元数据未知，不代表连接失败；先确认是否已经收到模型回复，再根据需要补充 Aider 的模型元数据配置。

完整选项见 Aider OpenAI 兼容接口文档。

示例四：Open WebUI

Section titled “示例四：Open WebUI”

Open WebUI 是常用的开源网页聊天界面，支持将 OpenAI 兼容服务添加为后台连接。

  1. 使用管理员账号打开 Admin Settings → Connections → OpenAI。
  2. 点击 Add Connection，选择标准 OpenAI Compatible 连接。
  3. 按下表填写：
字段 填写内容
URL https://youran-ai.du-fu.com/api
API Key 当前悠然 AI API Key
API Type Chat Completions
Model IDs 可以留空自动读取，或填写 /api/models 返回的模型 ID
  1. 保存连接，在模型选择器中选择悠然 AI 返回的模型并发起对话。

Open WebUI 会使用 {URL}/models 验证连接，因此这里会请求 /api/models，与悠然 AI 当前接口一致。如果模型缓存尚未刷新，可以在连接的 Model IDs (Filter) 中手工加入实际模型 ID。

完整步骤见 Open WebUI 的 OpenAI Compatible 官方指南。

接入失败时检查

Section titled “接入失败时检查”
  1. Base URL 是否严格为 https://youran-ai.du-fu.com/api。
  2. 模型 ID 是否来自当前 /api/models 响应。
  3. 客户端实际请求的是 /chat/completions、/responses 还是未支持的其他路径。
  4. 请求头是否为 Authorization: Bearer <YOURAN_API_KEY>。
  5. API Key 是否仍然有效，所属用户是否具有可用额度。

仍然无法连接时，请记录客户端实际请求路径与 HTTP 状态码，再前往故障排查。