# Dify

[Dify](https://docs.dify.ai/) is an AI application platform for building chat applications, workflows, agents, retrieval pipelines, tools, and model-powered APIs. Its official OpenAI-API-compatible model provider plugin lets a workspace add a model served through a custom API endpoint.

Configure that plugin with an AISIX proxy URL, caller API key, and model alias. Dify then uses the alias from application and workflow model nodes, while AISIX manages the upstream provider credential, routing, policy, and telemetry.

Dify is the AISIX client in this integration. It is not an upstream model provider, and AISIX does not replace Dify's workflow engine, application state, knowledge bases, tools, or published application APIs.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before starting, prepare the following:

* A Dify workspace where you can install plugins and configure model providers.
* An AISIX proxy URL the Dify deployment can reach.
* An AISIX caller API key dedicated to Dify or the application.
* A chat-capable model alias the caller key can access through the [OpenAI-Compatible API](https://docs.api7.ai/ai-gateway/endpoints/openai-compatible-chat.md).
* Context-window and maximum-output-token limits supported by every eligible target behind the AISIX alias.

## Install the Model Provider Plugin[​](#install-the-model-provider-plugin "Direct link to Install the Model Provider Plugin")

In the Dify Marketplace, find and install the official [OpenAI-API-compatible model provider plugin](https://marketplace.dify.ai/plugins/langgenius/openai_api_compatible) published by `langgenius`.

The plugin is versioned independently from the Dify application. When testing or troubleshooting the integration, record both the Dify version and plugin version so a later plugin change is not mistaken for an AISIX behavior change.

## Add the AISIX Model[​](#add-the-aisix-model "Direct link to Add the AISIX Model")

Open **Integrations → Model Provider** in the workspace, select **OpenAI-API-compatible**, and add a model with these values:

| Field                       | Value                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------ |
| Model Type                  | **LLM**                                                                              |
| Model Name                  | The AISIX model alias, for example `support-agent-prod`                              |
| API Key                     | The AISIX caller API key                                                             |
| API Base URL                | The AISIX proxy API root through `/v1`, for example `https://gateway.example.com/v1` |
| model name for API endpoint | Leave empty when **Model Name** is already the AISIX alias                           |
| Completion mode             | **Chat**                                                                             |
| API Type                    | **Chat Completions API (/chat/completions)**                                         |
| Model context size          | The lowest context limit across every eligible target behind the alias               |
| Upper bound for max tokens  | The lowest maximum output across every eligible target behind the alias              |
| Function Call Type          | **Not Support** for the initial text test                                            |

Save the model configuration. The plugin uses the API key as a bearer credential and sends the configured model name to the OpenAI-compatible endpoint. Do not add `/chat/completions` to **API Base URL**.

## Verify an Application Request[​](#verify-an-application-request "Direct link to Verify an Application Request")

Create or open a Dify chat application or workflow, select the configured AISIX model, and run a preview with a short prompt.

Confirm these results:

* Dify displays the model response.
* AISIX records a successful `POST /v1/chat/completions` request.
* The recorded caller key and model match the Dify model-provider configuration.

Dify applications may issue additional model calls for agent planning, question classification, parameter extraction, or other workflow nodes. Configure every model node that should use AISIX, and inspect the complete workflow before assuming all model traffic uses the same connection.

## Enable Tool Calls[​](#enable-tool-calls "Direct link to Enable Tool Calls")

After the text request succeeds, edit the model-provider configuration and set **Function Call Type** to **Tool Call** if the Dify application uses agent tools. Set **Stream function calling** to **Support** only when the selected model alias and upstream model support streamed OpenAI-compatible tool calls.

Run a complete agent tool test and confirm that Dify executes the expected tool, returns the tool result to the model, and produces a final answer. A successful text request does not verify these additional requests or the tool-call stream.

If tool behavior is inconsistent, return **Function Call Type** to **Not Support** while you inspect the Dify plugin, AISIX, and upstream model logs. Do not label a model as tool-capable only because the configuration field is available.

## Troubleshoot Dify Requests[​](#troubleshoot-dify-requests "Direct link to Troubleshoot Dify Requests")

| Symptom                                                       | Check                                                                                                                                          |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Model validation fails                                        | Confirm **API Base URL** reaches AISIX and uses the `/v1` API root without `/chat/completions`.                                                |
| Request returns `401`                                         | Confirm **API Key** contains the AISIX caller key, not an upstream provider key.                                                               |
| Request returns `403`                                         | Confirm the caller key can access the alias entered as **Model Name**.                                                                         |
| Request uses the wrong model                                  | Leave **model name for API endpoint** empty, or set it to the same AISIX alias deliberately.                                                   |
| Agent does not call a tool                                    | Confirm **Function Call Type** is **Tool Call** and verify that the selected upstream model supports the Dify tool schema.                     |
| Streamed tool calls fail but non-streaming tool calls succeed | Set **Stream function calling** to **Not Support**, then compare the plugin's streamed request and response with the AISIX tool-call contract. |

## Next Steps[​](#next-steps "Direct link to Next Steps")

* [OpenAI-Compatible API](https://docs.api7.ai/ai-gateway/endpoints/openai-compatible-chat.md): review the endpoint Dify calls.
* [Tool Calling](https://docs.api7.ai/ai-gateway/endpoints/tool-calling.md): verify the model and gateway tool-call contract.
* [Metrics and Usage Events](https://docs.api7.ai/ai-gateway/observability/metrics-and-usage-events.md): inspect Dify model traffic in AISIX.
