> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Dify 中使用 Ace Data Cloud

> 连接聊天模型、运行第一个工作流，并核对用量和排查错误。

将 Ace Data Cloud 聊天模型接入 Dify，用于 **LLM** 节点、Chatflow 或 Agent。你需要 Dify 工作区的所有者或管理员权限、Ace Data Cloud API Key，以及所选模型的访问权限。

## 选择安装路径

| 路径 | 当前可用状态 | 需要配置 |
| - | - | - |
| Dify 的 **OpenAI-API-compatible** 供应商 | 可从[官方 Marketplace](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible) 安装 | Base URL、模型 ID 和 API Key |
| **Ace Data Cloud** 模型供应商 | 已提交 Marketplace 审核，尚未验证上架 | 模型 ID 和 API Key；接口地址固定 |

<Note>
  Ace Data Cloud 专属供应商正在[等待审核](https://github.com/langgenius/dify-plugins/pull/3219)，目前尚未确认能在市场搜索、安装，也不是默认预装。需要立即接入时，使用已有的官方兼容供应商。此前退役的第一方 Dify 工具插件集合不是接入前提。
</Note>

## 准备 API Key

1. 登录 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，开通需要的聊天服务，检查余额和[模型当前价格](https://platform.acedata.cloud/models)。
2. 在**凭据**中创建 Key。服务 Key 只适用于对应服务；全局 Key 可用于账户有权访问的多个服务。首次使用 `gpt-4.1-mini` 测试时，确认 Key 有权调用该聊天模型。
3. 将 Key 存入 Dify 的模型供应商凭据设置。Key 会在工作区内共享，测试时建议使用单独的开发 Key。不要把 Key 写入提示词、截图、工作流导出文件或代码仓库。

使用 Ace Data Cloud Key 的请求消耗 Ace Data Cloud 账户余额，Dify 的模型额度不会代付这些请求。

## 配置当前可安装的兼容供应商

打开 **Integrations → Model Provider（集成 → 模型供应商）**。旧版导航中位于**设置 → 模型供应商**。安装 [OpenAI-API-compatible](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible)，然后选择**添加模型**。

| 字段 | 首次测试填写值 |
| - | - |
| 模型名称 / ID | `gpt-4.1-mini` |
| 模型类型 | LLM |
| API Base URL / 接口地址 | `https://api.acedata.cloud/v1` |
| API Key | 你的 Ace Data Cloud Key |
| 对话类型 | Chat（对话） |
| API 类型（如有） | Chat Completions API |
| 上下文 Token 限制 | `4096` |
| 最大输出 Token 数 | `1024` |

Base URL 以 `/v1` 结尾。Dify 会拼接 `/chat/completions`，不要自己添加，也不要使用 `/openai/v1`。上面的 Token 数是保守的测试设置，不代表模型最大容量。

首次文本测试先关闭可选的思考、联网搜索、结构化输出、图片输入和工具调用，然后保存模型。兼容供应商验证凭据时可能发送一个小型模型请求，因此也可能产生 API 用量。

### 专属供应商上架后的配置

当官方 Marketplace 出现 **Ace Data Cloud** 后，安装该供应商，在供应商卡片中选择**添加模型**，填写准确的模型 ID 和 API Key，并在模型文档支持的范围内设置上下文和输出限制。无需填写 Base URL；插件使用固定的 `https://api.acedata.cloud/v1/chat/completions`。

当前提交的插件通过只读 `/v1/models` 请求验证 Key 和模型 ID。保存配置不会生成付费回答，但也不证明余额、模型权限及所有可选能力都可用。请用一个简短的真实请求确认。

本指南的两条路径都使用 **Chat Completions**。不要在这里填写生图、Embedding 或仅支持 Messages 的模型，例如 `claude-opus-5-5`、`claude-sonnet-5-5`。模型出现在 `/v1/models` 列表中，不代表它支持这一协议或全部可选功能。

## 运行第一个工作流

创建空白 **Workflow（工作流）**，连接以下节点：

```text theme={null}
开始 → LLM → 输出
```

1. 在**开始**节点添加必填文本输入 `question`。
2. 在 **LLM** 节点选择刚配置的供应商和 `gpt-4.1-mini`。使用变量选择器，将用户提示词设为**开始 → question**。首次检查将最大输出 Token 数设为 `64`，并关闭重试。
3. 在\*\*输出（Output）\*\*节点添加名为 `answer` 的输出，值选择 **LLM → text**。旧版中该节点叫 **End（结束）**。工作流成功但没有输出节点时，调用方可能收不到数据。
4. 在预览中输入 `Reply only DIFY_OK`。确认 LLM 节点成功，输出包含 `DIFY_OK`，运行记录中显示 Token 用量。
5. 如果使用 **Chatflow**，通过\*\*回答（Answer）\*\*节点输出 **LLM → text**。预览和用量检查通过后再发布应用。

## 启用工具或图片

仅对支持工具调用的模型启用**工具调用**；支持流式工具调用时再单独开启对应选项。在 **Agent** 节点选择该模型，并添加一个适当的工具。查看运行轨迹中的工具名称和参数、工具返回结果及最终回答。模型选择了工具与最终回答成功，需要分别确认。

仅对支持视觉的模型开启**图片输入**。通过 Dify 支持的文件输入添加一张小图片，并提出一个简单问题。文本调用成功只证明文本链路，不能作为图片、结构化输出或其他功能的验证结果。

## 核对用量与费用

首调后打开 [Ace Data Cloud 用量](https://platform.acedata.cloud/console/usages)，按测试 Key 和时间范围筛选。将模型、状态和请求详情与 Dify 运行记录对应，检查实际扣减。需要支持时保留请求或 trace ID，不要发送 API Key。

用量以 **Credits** 计量。USD 换算为 `Credits ×（套餐价格 / 套餐额度）`，应使用你的当前套餐。专属供应商会返回 Token 用量，但不提供固定 USD 估价，因此 Dify 可能显示零预估费用；这不代表 API 免费。以 Ace Data Cloud 用量记录为准。重试、循环和 Agent 的多个工具轮次，都可能增加模型请求。

## 排查问题

| 现象 | 检查方法 |
| - | - |
| 在市场中搜不到 Ace Data Cloud | 专属供应商仍待发布。可先使用官方兼容供应商，或查看上面的审核状态。 |
| 保存失败，或 HTTP 400/401 | 检查 Base URL、Key、Key 范围、模型 ID 和 Chat Completions 模式。 |
| HTTP 403 | 检查模型权限、服务开通状态及内容策略限制。 |
| HTTP 429 | 降低并发，等待后再试。 |
| HTTP 5xx 或超时 | 查看[服务状态](https://status.acedata.cloud)、请求 trace，并确认 Dify 服务器能访问 `api.acedata.cloud:443`。避免连续盲目重试。 |
| 工具没有执行 | 检查模型是否支持、供应商工具选项是否开启，以及 Agent 节点是否已配置工具。 |
| 工作流成功但没有回答 | 将 **LLM → text** 映射到**输出 → answer**，或 Chatflow 的**回答**节点。 |
| Dify 显示零费用 | 核对 Ace Data Cloud 实际扣减；Dify 估价不是账单。 |

## 验证范围与维护

提交的专属供应商已通过单元测试、官方包检查、serverless 安装检查和插件包 CLI 的真实调用。`gpt-4.1-mini` 还验证了文本、流式工具调用及工具结果续聊。这些结果不代表已完成 Dify Community Edition／Cloud 界面安装、官方上架，也不代表所有模型和可选能力均已通过验证。

通过 Dify 插件管理器保持供应商版本更新。更换模型时重新检查 ID 和价格，将更新应用到生产前，先测试一个小型工作流。需要帮助时使用[供应商仓库](https://github.com/AceDataCloud/dify-model-provider/issues)或联系 `dev@acedata.cloud`。

协议详情见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions) 和 [Dify 模型供应商文档](https://docs.dify.ai/en/use-dify/workspace/model-providers)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.