# Dify

[Dify](https://docs.dify.ai/) 是一个 AI 应用平台，可用于构建聊天应用、工作流、Agent、检索流水线、工具和模型驱动的 API。其官方 OpenAI-API-compatible 模型服务提供方插件支持在工作区中添加通过自定义 API 端点提供的模型。

为该插件配置 AISIX 代理 URL、调用方 API Key 和模型别名。随后，Dify 可以在应用和工作流的模型节点中使用该别名，由 AISIX 管理上游服务提供方凭证、路由、策略和遥测。

在此集成中，Dify 是 AISIX 的客户端，而非上游模型服务提供方。AISIX 不会替代 Dify 的工作流引擎、应用状态、知识库、工具或已发布的应用 API。

[]()

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始之前，请准备以下内容：

* 具有插件安装和模型服务提供方配置权限的 Dify 工作区。
* Dify 部署环境可访问的 AISIX 代理 URL。
* 专用于 Dify 或应用的 AISIX 调用方 API Key。
* 支持聊天的模型别名，且调用方密钥可通过[兼容 OpenAI 的 API](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md) 访问该别名。
* AISIX 别名后所有可选目标均支持的上下文窗口和最大输出 Token 限制。

[]()

## 安装模型服务提供方插件[​](#install-the-model-provider-plugin "安装模型服务提供方插件的直接链接")

在 Dify Marketplace 中查找并安装由 `langgenius` 发布的官方 [OpenAI-API-compatible 模型服务提供方插件](https://marketplace.dify.ai/plugins/langgenius/openai_api_compatible)。

该插件的版本独立于 Dify 应用版本。测试集成或排查问题时，请同时记录 Dify 和插件的版本，避免将后续插件变更误认为 AISIX 的行为变化。

[]()

## 添加 AISIX 模型[​](#add-the-aisix-model "添加 AISIX 模型的直接链接")

在工作区中打开 **Integrations → Model Provider**，选择 **OpenAI-API-compatible**，并使用以下值添加模型：

| 字段                        | 值                                                                         |
| --------------------------- | -------------------------------------------------------------------------- |
| Model Type                  | **LLM**                                                                    |
| Model Name                  | AISIX 模型别名，例如 `support-agent-prod`                                  |
| API Key                     | AISIX 调用方 API Key                                                       |
| API Base URL                | 包含 `/v1` 的 AISIX 代理 API 根路径，例如 `https://gateway.example.com/v1` |
| model name for API endpoint | 如果 **Model Name** 已是 AISIX 别名，则留空                                |
| Completion mode             | **Chat**                                                                   |
| API Type                    | **Chat Completions API (/chat/completions)**                               |
| Model context size          | 别名后所有可选目标中最低的上下文限制                                       |
| Upper bound for max tokens  | 别名后所有可选目标中最低的最大输出限制                                     |
| Function Call Type          | 初次文本测试时选择 **Not Support**                                         |

保存模型配置。插件将 API Key 用作 Bearer 凭证，并将配置的模型名称发送到兼容 OpenAI 的端点。不要在 **API Base URL** 后追加 `/chat/completions`。

[]()

## 验证应用请求[​](#verify-an-application-request "验证应用请求的直接链接")

创建或打开一个 Dify 聊天应用或工作流，选择已配置的 AISIX 模型，并使用简短提示词运行预览。

确认以下结果：

* Dify 显示模型响应。
* AISIX 记录一条成功的 `POST /v1/chat/completions` 请求。
* 记录中的调用方密钥和模型与 Dify 模型服务提供方配置一致。

Dify 应用可能为 Agent 规划、问题分类、参数提取或其他工作流节点发起额外的模型调用。请为所有需要使用 AISIX 的模型节点进行配置，并检查完整工作流，不要假定所有模型流量均使用同一个连接。

[]()

## 启用工具调用[​](#enable-tool-calls "启用工具调用的直接链接")

文本请求成功后，如果 Dify 应用使用 Agent 工具，请编辑模型服务提供方配置，将 **Function Call Type** 设置为 **Tool Call**。只有当选定的模型别名和上游模型均支持兼容 OpenAI 的流式工具调用时，才将 **Stream function calling** 设置为 **Support**。

运行一次完整的 Agent 工具测试，确认 Dify 执行预期工具、向模型返回工具结果，并生成最终回答。文本请求成功并不能验证这些额外请求或工具调用流。

如果工具行为不一致，请将 **Function Call Type** 恢复为 **Not Support**，同时检查 Dify 插件、AISIX 和上游模型的日志。不要仅因为存在配置字段，就将模型标记为支持工具调用。

[]()

## Dify 请求故障排查[​](#troubleshoot-dify-requests "Dify 请求故障排查的直接链接")

| 现象                               | 检查项                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| 模型验证失败                       | 确认 **API Base URL** 可访问 AISIX，且使用 `/v1` API 根路径，不包含 `/chat/completions`。                    |
| 请求返回 `401`                     | 确认 **API Key** 填写的是 AISIX 调用方密钥，而非上游服务提供方密钥。                                         |
| 请求返回 `403`                     | 确认调用方密钥可访问 **Model Name** 中填写的别名。                                                           |
| 请求使用了错误的模型               | 将 **model name for API endpoint** 留空，或明确设置为同一个 AISIX 别名。                                     |
| Agent 未调用工具                   | 确认 **Function Call Type** 为 **Tool Call**，并验证选定的上游模型支持 Dify 工具 Schema。                    |
| 非流式工具调用成功，但流式调用失败 | 将 **Stream function calling** 设置为 **Not Support**，然后对照 AISIX 工具调用约定检查插件的流式请求与响应。 |

[]()

## 下一步[​](#next-steps "下一步的直接链接")

* [兼容 OpenAI 的 API](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md)：查看 Dify 调用的端点。
* [工具调用](https://docs.apiseven.com/ai-gateway/endpoints/tool-calling.md)：验证模型和网关的工具调用约定。
* [指标与用量事件](https://docs.apiseven.com/ai-gateway/observability/metrics-and-usage-events.md)：在 AISIX 中检查 Dify 模型流量。
