AI RAG retrieval proxy plugin - connect Dify to RAGFlow and Bailian - API Gateway

Features

The AI RAG retrieval proxy plugin lets AI applications, such as Dify, connect to and retrieve from external RAG engines like RAGFlow and the Bailian knowledge base by translating retrieval protocols and transforming retrieval results.

Runtime properties

Plugin execution phase: default.
Plugin execution priority: 150.

Configuration

Basic configuration

Parameter	Type	Required	Default	Description
`rag_proxy.provider.name`	string	Required	-	The external knowledge base type. Valid values: `ragflow` and `bailian`.
`rag_proxy.source.name`	string	Optional	dify	The calling application type. Only `dify` is supported.
`rag_proxy.source.enable_to_proxy_api_key`	boolean	Optional	false	Enables API key validation between AI Gateway and the calling application. When `true`, the calling application's API key must match the gateway-configured key, or requests fail.
`rag_proxy.source.to_proxy_api_key`	string	Optional	-	The API key provided by the calling application. When set, AI Gateway validates incoming requests against this value.

RAGFlow configuration

Configure the following parameters when rag_proxy.provider.name is ragflow.

Parameter	Type	Required	Default	Description
`rag_proxy.provider.api_key`	string	Required	-	The RAGFlow API key. Obtain it from the RAGFlow console: profile avatar > API > RAGFlow API.
`rag_proxy.provider.dataset_ids`	list[string]	Optional	-	The RAGFlow dataset ID for retrieval. If omitted, you must specify it in Dify's external knowledge base configuration, which takes precedence.
`rag_proxy.provider.document_ids`	list[string]	Optional	-	The IDs of the documents in RAGFlow to retrieve from, which limits the search scope.
`rag_proxy.provider.similarity_threshold`	float	Optional	0.0	Minimum similarity score. Chunks below this threshold are excluded. Also configurable on the Dify retrieval page.
`rag_proxy.provider.top_n`	integer	Optional	30	Number of top-scoring chunks to return. Also configurable on the Dify retrieval page.
`rag_proxy.provider.vector_similarity_weight`	float	Optional	0.3	Weight for vector cosine similarity. The remainder `(1-x)` is applied to semantic similarity.
`rag_proxy.provider.keyword`	boolean	Optional	false	Enables keyword-based matching.
`rag_proxy.provider.rerank_id`	integer	Optional	-	The rerank model ID in the RAG engine. Specifying this value enables reranking (disabled by default). Supported models are listed in RAGFlow documentation.

To set up a RAGFlow knowledge base, follow the Configure knowledge base guide.

Retrieval parameter details are in the Retrieve chunks API reference.

Example basic configuration:

rag_proxy:
  provider:
    name: 'ragflow'
    api_key: "xxxxxxxx"

Bailian configuration

Configure the following parameters when rag_proxy.provider.name is bailian.

Parameter	Type	Required	Default	Description
`rag_proxy.provider.api_key`	string	Required	-	The Model Studio API key. Generate one from the Model Studio API-KEY page.
`rag_proxy.provider.index_id`	string	Optional	-	The Bailian knowledge base ID. Locate this ID by following the Knowledge Base API Guide.
`rag_proxy.provider.enable_reranking`	bool	Optional	true	Enables or disables reranking.
`rag_proxy.provider.rerank_min_score`	float	Optional	The similarity threshold configured for the current knowledge base.	Takes effect only when reranking is enabled. Chunks with a post-rerank similarity score below this threshold are excluded. Value range: `[0.01-1.00]`.
`rag_proxy.provider.rerank_top_n`	integer	Optional	5	Takes effect only when reranking is enabled. Number of top-ranked chunks to return. Value range: `[1-20]`.
`rag_proxy.provider.save_retriever_history`	bool	Optional	false	Saves historical retrieval data when enabled.
`rag_proxy.provider.dense_similarity_top_k`	integer	Optional	100	Number of most similar text chunks to retrieve by vector similarity. Value range: `[0-100]`. The sum of dense_similarity_top_k and sparse_similarity_top_k must not exceed 200.
`rag_proxy.provider.sparse_similarity_top_k`	integer	Optional	100	Number of text chunks to retrieve by keyword matching. Value range: `[0-100]`. The sum of dense_similarity_top_k and sparse_similarity_top_k must not exceed 200.

To set up a Bailian knowledge base, follow the Bailian knowledge base operation and usage guide.

Retrieval parameter details are in Retrieve from a knowledge base.

Example basic configuration:

rag_proxy:
  provider:
    name: 'bailian'
    api_key: 'sk-xxxxxx'

Procedure

The following examples connect Dify to RAGFlow and a Bailian knowledge base through the AI RAG retrieval proxy plugin.

Connect Dify to RAGFlow

Create a retrieval service for RAGFlow in AI Gateway.
1. Go to the Instance page in the AI Gateway console. In the top menu bar, select the region of your target instance, and then click the target Instance ID.
2. In the left-side navigation pane, choose Service, and then click Create Service.
3. For a RAGFlow instance with a fixed address, set Service Source to Fixed Address and set the port to 80. If your RAGFlow instance runs as a container in the same VPC, select Container Service instead.
Create a route for the Agent API.
1. Create a custom Agent API.
  
  In the gateway instance console, choose Agent API > Create Agent API. Set Protocol to Custom.
2. Create a route for the Agent API.
  
  Navigate to the Agent API that you created and click Create Route. Ensure that the path ends with /retrieval and select the RAGFlow retrieval service that you created in Step 1.
Obtain the API key and configure the plugin in AI Gateway.
1. In the RAGFlow console, click your profile avatar and go to API > API KEY to copy your API key.
2. In the gateway instance console, choose Plug-in, and then click Install Plug-in. For Plugin Type, select AI. Find the AI RAG retrieval proxy plugin and click Install and Configure to open the rule configuration page. Configure the parameters accordingly. Enable the plugin and click Save.
Create an external knowledge base API in Dify.

In the Dify console, click Knowledge Base > External Knowledge Base API > Add External Knowledge Base API. Set the API Endpoint to the gateway endpoint combined with the Agent API route path (http(s)://{endpoint}/{agent api path}), excluding the /retrieval suffix. Define your own API Key.

Important
If you have configured the rag_proxy.source.enable_to_proxy_api_key and rag_proxy.source.to_proxy_api_key parameters in the plugin, ensure that the API key you define here matches the value of rag_proxy.source.to_proxy_api_key. Otherwise, authentication will fail, and AI Gateway will not route the request.
Connect to the external knowledge base in Dify.
1. Obtain the knowledge base namespace ID.
  
  In the RAGFlow console, open the target knowledge base. The namespace ID appears in the browser address bar URL.
2. Configure the knowledge base information.
  
  In the Dify console, go to Knowledge Base > Connect to External Knowledge Base. Enter a Knowledge Base Name and Description. For External Knowledge Base API, select the API from Step 4. Enter the namespace ID in the External Knowledge Base ID field, and then click Connect.
Test the retrieval.

In Dify, open the knowledge base you created. On the Retrieval Test tab, enter test text. If the service returns expected text chunks, the connection is successful.

Connect Dify to the Bailian knowledge base

Create a retrieval service for Model Studio in AI Gateway.
1. Go to the Instance page in the AI Gateway console. In the top menu bar, select the region of your target instance, and then click the target Instance ID.
2. In the left-side navigation pane, choose Service, and then click Create Service. Set Service Source to DNS Domain Name.
Create a custom Agent API route in AI Gateway.
1. Create a custom Agent API.
  
  In the left-side navigation pane, choose Agent API > Create Agent API. Customize the Domain Name and Base Path. Set Protocol to Custom.
2. Create a route for the Agent API.
  
  Navigate to the Agent API that you created and click Create Route. Ensure that the path ends with /retrieval and select the Model Studio retrieval service that you created in Step 1.
Obtain the API key and configure the plugin in AI Gateway.
1. Log on to the Model Studio platform and obtain an API key.
2. In the gateway instance console, choose Plug-in, and then click Install Plug-in. For Plugin Type, select AI. Find the AI RAG retrieval proxy plugin and click Install and Configure to open the rule configuration page. Configure the parameters accordingly. Enable the plugin and click Save.
Create an external knowledge base API in Dify.

In the Dify console, click Knowledge Base > External Knowledge Base API > Add External Knowledge Base API. Set the API Endpoint to the gateway endpoint combined with the Agent API route path (http(s)://{endpoint}/{agent api path}), excluding the /retrieval suffix. Define your own API Key.

Important
If you have configured the rag_proxy.source.enable_to_proxy_api_key and rag_proxy.source.to_proxy_api_key parameters in the plugin, ensure that the API key you define here matches the value of rag_proxy.source.to_proxy_api_key. Otherwise, authentication will fail, and AI Gateway will not route the request.
Connect to the external knowledge base in Dify.
1. Obtain the Bailian knowledge base ID.
  
  In the Model Studio console, open the Knowledge Base page. Select the target knowledge base and note its ID.
2. Configure the knowledge base information.
  
  In the Dify console, go to Knowledge Base > Connect to External Knowledge Base. Enter a Knowledge Base Name and Description. For External Knowledge Base API, select the API from Step 4. For External Knowledge Base ID, enter the ID in the format {knowledge base ID}, and then click Connect.
Test the retrieval.

In Dify, open the knowledge base you created. On the Retrieval Test tab, enter test text. If the service returns expected text chunks, the connection is successful.