diff --git a/docs.json b/docs.json index 72b26598..46ec2e43 100644 --- a/docs.json +++ b/docs.json @@ -70,6 +70,16 @@ "zh-Hans/concepts/async-tasks" ] }, + { + "group": "生态集成", + "icon": "puzzle-piece", + "pages": [ + "zh-Hans/integrations/n8n", + "zh-Hans/integrations/dify", + "zh-Hans/integrations/gitlab-ci", + "zh-Hans/integrations/open-webui" + ] + }, { "group": "AI 聊天", "icon": "comments", @@ -812,6 +822,16 @@ "en/concepts/async-tasks" ] }, + { + "group": "Integrations", + "icon": "puzzle-piece", + "pages": [ + "en/integrations/n8n", + "en/integrations/dify", + "en/integrations/gitlab-ci", + "en/integrations/open-webui" + ] + }, { "group": "AI Chat", "icon": "comments", diff --git a/en/integrations/dify.mdx b/en/integrations/dify.mdx new file mode 100644 index 00000000..a294ec7f --- /dev/null +++ b/en/integrations/dify.mdx @@ -0,0 +1,29 @@ +--- +title: "Use AceDataCloud models in Dify" +description: "Configure an OpenAI API-compatible model provider in Dify." +--- + +Dify's OpenAI API-compatible model provider can call AceDataCloud chat models. You can configure a model in Dify without installing an AceDataCloud plugin. + +## Configure the model + +1. Create an [AceDataCloud API token](https://platform.acedata.cloud/console/applications). +2. In Dify, open **Settings → Model Provider** and install [OpenAI-API-compatible](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible) from the Marketplace if it is not already installed. +3. Add a chat model using these values: + +| Field | Value | +| --- | --- | +| API Base URL | `https://api.acedata.cloud/v1` | +| API key | Your AceDataCloud token | +| Model name | `gpt-5.5`, or another [supported chat model](https://platform.acedata.cloud/documents/openai-chat-completions) | +| Model type | LLM | +| Completion mode | Chat | +| API type | Chat Completions API | + +4. Save and test the model, then select it in a Dify **LLM** node. + +The Base URL ends in `/v1`. Do not add `/chat/completions`; Dify adds the operation path. The older `/openai/v1` URL does not serve this endpoint. + +Each test or workflow run uses your AceDataCloud balance. Check the model's current price and Dify's retry settings before publishing a workflow. Keep the API key in Dify's provider credential settings, never in a prompt or workflow export. + +For the request and response schema, see [Chat Completions](/en/guides/openai/openai_chat_completions). diff --git a/en/integrations/gitlab-ci.mdx b/en/integrations/gitlab-ci.mdx new file mode 100644 index 00000000..e5469b5f --- /dev/null +++ b/en/integrations/gitlab-ci.mdx @@ -0,0 +1,19 @@ +--- +title: "Call AceDataCloud from GitLab CI" +description: "Run a manual pipeline job that summarizes a commit title with a chat model." +--- + +Use a GitLab CI job to call the AceDataCloud Chat Completions API. The [sample pipeline](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/gitlab/acedatacloud-chat.gitlab-ci.yml) summarizes the latest commit title and saves the result as a short-lived artifact. The job is manual and runs only on the default branch. + +## Set up the job + +1. Create an [AceDataCloud API token](https://platform.acedata.cloud/console/applications). +2. In your GitLab project, open **Settings → CI/CD → Variables**. Add `ACEDATACLOUD_API_TOKEN` as a masked and hidden variable. Protect the variable and the default branch. +3. Copy the [sample pipeline YAML](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/gitlab/acedatacloud-chat.gitlab-ci.yml) into your `.gitlab-ci.yml`. If your pipeline already has `stages`, add `report` to that list and copy only the job. +4. Run a pipeline on the default branch, start the manual **acedatacloud_commit_summary** job, and download `summary.txt` from its artifacts. + +The job sends `CI_COMMIT_TITLE` to AceDataCloud. Do not send confidential commit text unless your project's data policy allows it. Each manual run makes one billable API request; check the model's current price before enabling other triggers. The token stays in GitLab's CI/CD variable store and is not written to the artifact. + +To summarize a different input, change the `jq --arg title` line and the prompt in the sample. Keep the token in the CI/CD variable and encode user-controlled text with `jq --arg`, not shell string interpolation inside JSON. The request schema is documented in [Chat Completions](/en/guides/openai/openai_chat_completions). + +This is a copyable CI example. Publishing a reusable component to the [GitLab CI/CD Catalog](https://docs.gitlab.com/ci/components/) requires a GitLab-hosted component project and a release. diff --git a/en/integrations/n8n.mdx b/en/integrations/n8n.mdx new file mode 100644 index 00000000..e70b2264 --- /dev/null +++ b/en/integrations/n8n.mdx @@ -0,0 +1,22 @@ +--- +title: "Use AceDataCloud in n8n" +description: "Import a chat workflow and connect it to your AceDataCloud API token." +--- + +Use n8n's HTTP Request node to call AceDataCloud. The [sample workflow](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/n8n/acedatacloud-chat.json) sends a prompt to the Chat Completions API and returns the response and token usage. It uses only built-in n8n nodes. + +## Import the workflow + +1. Create an [AceDataCloud API token](https://platform.acedata.cloud/console/applications). +2. In n8n, create a workflow and choose **Import from URL**. Paste the [sample workflow URL](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/n8n/acedatacloud-chat.json). You can also download the JSON file and choose **Import from File**. +3. Open **AceDataCloud chat**. Under **Authentication → Generic Credential Type**, select **Bearer Auth** and create a credential containing your AceDataCloud token. Paste only the token; n8n adds the `Bearer ` prefix. Save the credential and select it in this node. +4. In **Set prompt and model**, replace the sample prompt and choose a [supported chat model](https://platform.acedata.cloud/documents/openai-chat-completions). +5. Select **Execute workflow**. The HTTP Request output contains `choices[0].message.content` and `usage`. + +Keep the token in the n8n credential. Do not put it in the workflow JSON or a Set node. Each execution calls a billable API; review the model's current price before activating a schedule or webhook. + +## Customize the flow + +Replace the manual trigger with your own trigger. Map its text to `prompt` in **Set prompt and model**. The HTTP Request node sends a non-streaming `POST` to `https://api.acedata.cloud/v1/chat/completions`; n8n can then pass the result to another node. For the request and response schema, see [Chat Completions](/en/guides/openai/openai_chat_completions). + +If the request fails, check the node's selected credential, whether the token was pasted without a `Bearer ` prefix, the model name, and your available balance. An authentication or billing error should be fixed before rerunning the workflow. diff --git a/en/integrations/open-webui.mdx b/en/integrations/open-webui.mdx new file mode 100644 index 00000000..359d2c5e --- /dev/null +++ b/en/integrations/open-webui.mdx @@ -0,0 +1,17 @@ +--- +title: "Use AceDataCloud in Open WebUI" +description: "Connect an AceDataCloud chat model through Open WebUI's OpenAI-compatible provider." +--- + +Open WebUI supports OpenAI-compatible Chat Completions endpoints. Connect it directly to AceDataCloud; no custom Pipe or provider module is needed. + +## Add the connection + +1. Create an [AceDataCloud API token](https://platform.acedata.cloud/console/applications). +2. In Open WebUI, open **Settings → Admin → Connections**. Under **Manage OpenAI API Connections**, choose **Add Connection**. +3. Enter `https://api.acedata.cloud/v1` as the URL and your AceDataCloud token as the API key. +4. Add `gpt-5.5` to **Model IDs** if it is not discovered automatically. Save the connection, select that model in a new chat, and send a short prompt. + +Open WebUI's **Verify Connection** calls `/models`; a failed discovery check is not proof that Chat Completions failed. If it fails, add the model ID manually and test an actual chat request. AceDataCloud's `/v1/models` and `/v1/chat/completions` routes accept the same Bearer token. Use only models listed in the [current catalog](https://platform.acedata.cloud/documents/openai-chat-completions). + +Keep the token in Open WebUI's connection settings. Each test prompt can incur API charges; check the model's current price. For protocol details, see [Chat Completions](/en/guides/openai/openai_chat_completions) and the [Open WebUI provider guide](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/). diff --git a/examples/gitlab/acedatacloud-chat.gitlab-ci.yml b/examples/gitlab/acedatacloud-chat.gitlab-ci.yml new file mode 100644 index 00000000..5f1dbfec --- /dev/null +++ b/examples/gitlab/acedatacloud-chat.gitlab-ci.yml @@ -0,0 +1,34 @@ +stages: + - report + +acedatacloud_commit_summary: + stage: report + image: alpine:3.23 + variables: + GIT_STRATEGY: none + rules: + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + when: manual + allow_failure: true + - when: never + before_script: + - apk add --no-cache curl jq + script: + - | + set -eu + : "${ACEDATACLOUD_API_TOKEN:?Set a masked CI/CD variable}" + jq -n --arg title "$CI_COMMIT_TITLE" '{ + model: "gpt-5.5", + messages: [{role: "user", content: ("Summarize this commit title in one sentence: " + $title)}], + stream: false + }' > request.json + curl --fail-with-body --silent --show-error --retry 0 \ + -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \ + -H "Content-Type: application/json" \ + --data @request.json \ + https://api.acedata.cloud/v1/chat/completions > response.json + jq -er '.choices[0].message.content | select(type == "string" and length > 0)' response.json > summary.txt + artifacts: + paths: + - summary.txt + expire_in: 1 day diff --git a/examples/n8n/acedatacloud-chat.json b/examples/n8n/acedatacloud-chat.json new file mode 100644 index 00000000..baa989e6 --- /dev/null +++ b/examples/n8n/acedatacloud-chat.json @@ -0,0 +1,78 @@ +{ + "name": "AceDataCloud: run a chat prompt", + "nodes": [ + { + "parameters": {}, + "id": "e8b9d998-a119-426b-aa8a-47f71848f5a1", + "name": "When clicking Execute workflow", + "type": "n8n-nodes-base.manualTrigger", + "typeVersion": 1, + "position": [240, 300] + }, + { + "parameters": { + "assignments": { + "assignments": [ + { + "id": "aa1895bb-3ab4-4517-acfd-c28e7eb7e0c2", + "name": "prompt", + "value": "Summarize why automation matters in one sentence.", + "type": "string" + }, + { + "id": "925408cb-5050-48da-a889-fd9e2ed2e45a", + "name": "model", + "value": "gpt-5.5", + "type": "string" + } + ] + }, + "options": {} + }, + "id": "0aed7632-a0df-47a9-924d-8850b1613260", + "name": "Set prompt and model", + "type": "n8n-nodes-base.set", + "typeVersion": 3.4, + "position": [460, 300] + }, + { + "parameters": { + "method": "POST", + "url": "https://api.acedata.cloud/v1/chat/completions", + "authentication": "genericCredentialType", + "genericAuthType": "httpBearerAuth", + "sendBody": true, + "contentType": "json", + "specifyBody": "json", + "jsonBody": "={{ JSON.stringify({ model: $json.model, messages: [{ role: 'user', content: $json.prompt }], stream: false }) }}", + "options": { + "timeout": 300000, + "redirect": { + "redirect": { + "followRedirects": false + } + } + } + }, + "id": "534f922e-7b7c-46da-a9ef-51701db9d73b", + "name": "AceDataCloud chat", + "type": "n8n-nodes-base.httpRequest", + "typeVersion": 4.3, + "position": [700, 300] + } + ], + "connections": { + "When clicking Execute workflow": { + "main": [[{"node": "Set prompt and model", "type": "main", "index": 0}]] + }, + "Set prompt and model": { + "main": [[{"node": "AceDataCloud chat", "type": "main", "index": 0}]] + } + }, + "active": false, + "settings": { + "executionOrder": "v1" + }, + "pinData": {}, + "tags": [] +} diff --git a/zh-Hans/integrations/dify.mdx b/zh-Hans/integrations/dify.mdx new file mode 100644 index 00000000..810beebb --- /dev/null +++ b/zh-Hans/integrations/dify.mdx @@ -0,0 +1,29 @@ +--- +title: "在 Dify 中使用 AceDataCloud 模型" +description: "用 Dify 的 OpenAI API 兼容模型供应商接入 AceDataCloud。" +--- + +Dify 的 OpenAI API 兼容模型供应商可以调用 AceDataCloud 聊天模型。配置模型时无需安装 AceDataCloud 专属插件。 + +## 配置模型 + +1. [创建 AceDataCloud API Token](https://platform.acedata.cloud/console/applications)。 +2. 在 Dify 中打开 **设置 → 模型供应商**。如果尚未安装，从 Marketplace 安装 [OpenAI-API-compatible](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible)。 +3. 添加聊天模型，填写： + +| 字段 | 值 | +| --- | --- | +| API Base URL | `https://api.acedata.cloud/v1` | +| API Key | 你的 AceDataCloud Token | +| 模型名称 | `gpt-5.5`，或其他[受支持的聊天模型](https://platform.acedata.cloud/documents/openai-chat-completions) | +| 模型类型 | LLM | +| 对话类型 | Chat（对话） | +| API 类型 | Chat Completions API | + +4. 保存并测试模型，然后在 Dify 的 **LLM** 节点中选择它。 + +Base URL 以 `/v1` 结尾，不要再加 `/chat/completions`；Dify 会自行拼接操作路径。旧的 `/openai/v1` 地址不提供此接口。 + +每次测试或运行工作流都会产生 AceDataCloud 用量。发布工作流前，检查模型当前价格及 Dify 的重试设置。API Key 只存放在 Dify 的供应商凭据设置中，不要写进提示词或工作流导出文件。 + +请求和响应结构见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions)。 diff --git a/zh-Hans/integrations/gitlab-ci.mdx b/zh-Hans/integrations/gitlab-ci.mdx new file mode 100644 index 00000000..2cf9bacb --- /dev/null +++ b/zh-Hans/integrations/gitlab-ci.mdx @@ -0,0 +1,19 @@ +--- +title: "从 GitLab CI 调用 AceDataCloud" +description: "用手动流水线任务调用聊天模型，总结提交标题。" +--- + +可以在 GitLab CI 任务中调用 AceDataCloud Chat Completions API。[示例流水线](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/gitlab/acedatacloud-chat.gitlab-ci.yml)总结最新提交的标题，并将结果保存为短期 Artifact。任务只在默认分支显示，且需要手动启动。 + +## 配置任务 + +1. [创建 AceDataCloud API Token](https://platform.acedata.cloud/console/applications)。 +2. 在 GitLab 项目中打开 **Settings → CI/CD → Variables**，添加名为 `ACEDATACLOUD_API_TOKEN` 的变量，设为 masked 和 hidden，并保护该变量及默认分支。 +3. 将[示例流水线 YAML](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/gitlab/acedatacloud-chat.gitlab-ci.yml)复制到项目的 `.gitlab-ci.yml`。如果已有 `stages`，将 `report` 加入现有列表，然后只复制示例任务。 +4. 在默认分支运行流水线，手动启动 **acedatacloud_commit_summary** 任务，从 Artifact 下载 `summary.txt`。 + +任务会将 `CI_COMMIT_TITLE` 发送给 AceDataCloud。如果提交标题包含敏感内容，请先确认项目的数据使用规则。每次手动运行产生一次计费 API 请求；更改触发方式前请查看模型当前价格。Token 保留在 GitLab 的 CI/CD 变量中，不会写入 Artifact。 + +要总结其他输入，可修改示例中的 `jq --arg title` 和提示词。请继续将 Token 放在 CI/CD 变量中，并用 `jq --arg` 编码用户可控文本，不要在 JSON 字符串里直接拼接 shell 变量。请求结构见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions)。 + +这是可复制的 CI 示例。要将可复用组件发布到 [GitLab CI/CD Catalog](https://docs.gitlab.com/ci/components/)，还需要 GitLab 托管的组件项目和 Release。 diff --git a/zh-Hans/integrations/n8n.mdx b/zh-Hans/integrations/n8n.mdx new file mode 100644 index 00000000..9566fb24 --- /dev/null +++ b/zh-Hans/integrations/n8n.mdx @@ -0,0 +1,22 @@ +--- +title: "在 n8n 中使用 AceDataCloud" +description: "导入聊天工作流，用 AceDataCloud API Token 运行。" +--- + +使用 n8n 自带的 HTTP Request 节点调用 AceDataCloud。[示例工作流](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/n8n/acedatacloud-chat.json)向 Chat Completions API 发送提示词，并返回回复和 Token 用量，无需安装社区节点。 + +## 导入工作流 + +1. [创建 AceDataCloud API Token](https://platform.acedata.cloud/console/applications)。 +2. 在 n8n 中新建工作流，选择 **Import from URL**，填入[示例工作流地址](https://raw.githubusercontent.com/AceDataCloud/Docs/main/examples/n8n/acedatacloud-chat.json)。也可以下载 JSON 文件后选择 **Import from File**。 +3. 打开 **AceDataCloud chat** 节点，在 **Authentication → Generic Credential Type** 中选择 **Bearer Auth**，创建凭据并填入 AceDataCloud Token。只需填 Token 本身，n8n 会自动添加 `Bearer ` 前缀。保存后在节点中选中这个凭据。 +4. 在 **Set prompt and model** 节点修改示例提示词，并选择[受支持的聊天模型](https://platform.acedata.cloud/documents/openai-chat-completions)。 +5. 点击 **Execute workflow**。HTTP Request 的输出包含 `choices[0].message.content` 和 `usage`。 + +请把 Token 只存放在 n8n 凭据中，不要写入工作流 JSON 或 Set 节点。每次运行都会产生 API 用量；启用定时或 Webhook 触发前，请先查看模型当前价格。 + +## 扩展工作流 + +可将手动触发器换成自己的触发器，再把输入文本映射到 **Set prompt and model** 中的 `prompt`。HTTP Request 节点向 `https://api.acedata.cloud/v1/chat/completions` 发送非流式 `POST` 请求，后续节点可以直接使用返回结果。请求和响应结构见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions)。 + +请求失败时，检查节点选择的凭据、Token 是否误带 `Bearer ` 前缀、模型名称和可用余额。遇到鉴权或余额错误，先排除原因再重试。 diff --git a/zh-Hans/integrations/open-webui.mdx b/zh-Hans/integrations/open-webui.mdx new file mode 100644 index 00000000..bbf7ced4 --- /dev/null +++ b/zh-Hans/integrations/open-webui.mdx @@ -0,0 +1,17 @@ +--- +title: "在 Open WebUI 中使用 AceDataCloud" +description: "通过 Open WebUI 的 OpenAI 兼容供应商连接 AceDataCloud 聊天模型。" +--- + +Open WebUI 支持 OpenAI 兼容的 Chat Completions 接口，可以直接连接 AceDataCloud，无需编写自定义 Pipe 或供应商模块。 + +## 添加连接 + +1. [创建 AceDataCloud API Token](https://platform.acedata.cloud/console/applications)。 +2. 在 Open WebUI 中打开 **Settings → Admin → Connections**，在 **Manage OpenAI API Connections** 下选择 **Add Connection**。 +3. URL 填 `https://api.acedata.cloud/v1`，API Key 填 AceDataCloud Token。 +4. 如果没有自动发现模型，在 **Model IDs** 中手动加入 `gpt-5.5`。保存连接，在新对话中选中该模型并发送简短提示词。 + +Open WebUI 的 **Verify Connection** 会请求 `/models`；模型发现失败不等于 Chat Completions 调用失败。此时可手动添加模型 ID，再用真实聊天请求验证。AceDataCloud 的 `/v1/models` 和 `/v1/chat/completions` 路由均使用 Bearer Token。请以[当前模型目录](https://platform.acedata.cloud/documents/openai-chat-completions)为准。 + +Token 只存放在 Open WebUI 的连接设置中。测试提示词可能产生 API 用量，请先查看模型当前价格。协议细节见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions)和 [Open WebUI 官方指南](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)。