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

# Dify

`agentscope-extensions-rag-dify` integrates with [Dify](https://dify.ai/) datasets, reusing knowledge bases you already maintain in Dify.

## When to use

* Your team operates content and document management in Dify.
* You want to leverage Dify's multiple retrieval modes (keyword / semantic / hybrid / full-text).

## Add the dependency

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-rag-dify</artifactId>
    <version>${agentscope.version}</version>
</dependency>
```

## Quickstart

```java theme={null}
import io.agentscope.core.rag.integration.dify.DifyKnowledge;
import io.agentscope.core.rag.integration.dify.DifyRAGConfig;
import io.agentscope.core.rag.integration.dify.RetrievalMode;
import io.agentscope.core.rag.model.RetrieveConfig;

DifyRAGConfig config = DifyRAGConfig.builder()
    .apiKey(System.getenv("DIFY_RAG_API_KEY"))
    .datasetId("your-dataset-id")
    .retrievalMode(RetrievalMode.HYBRID_SEARCH)
    .enableRerank(true)
    .build();

DifyKnowledge knowledge = DifyKnowledge.builder()
    .config(config)
    .build();

List<Document> hits = knowledge.retrieve(
    "How do I renew my membership?",
    RetrieveConfig.builder().limit(5).scoreThreshold(0.5).build()
).block();
```

## Retrieval modes

`RetrievalMode` selects how Dify searches the dataset:

| Enum | Description |
| - | - |
| `KEYWORD_SEARCH` | Keyword only |
| `SEMANTIC_SEARCH` | Vector / semantic only |
| `HYBRID_SEARCH` | Keyword + vector hybrid (recommended) |
| `FULL_TEXT_SEARCH` | Full-text |

## Self-hosted Dify

Point `baseUrl` at your deployment:

```java theme={null}
DifyRAGConfig config = DifyRAGConfig.builder()
    .apiKey("dataset-xxx")
    .baseUrl("https://dify.mycompany.com")
    .datasetId("ds-xxxx")
    .retrievalMode(RetrievalMode.HYBRID_SEARCH)
    .build();
```

## Metadata filtering

Use `MetadataFilter / MetadataFilterCondition` to filter by metadata fields you've configured in Dify:

```java theme={null}
DifyRAGConfig config = DifyRAGConfig.builder()
    .apiKey(apiKey)
    .datasetId(datasetId)
    .retrievalMode(RetrievalMode.HYBRID_SEARCH)
    .metadataFilter(MetadataFilter.builder()
        .conditions(List.of(
            MetadataFilterCondition.builder()
                .name("category").comparisonOperator("=")
                .value(List.of("faq")).build()))
        .logicalOperator("and")
        .build())
    .build();
```

## Retrieval only

`addDocuments(...)` is unsupported — use the Dify console: log in → Knowledge → choose dataset → upload documents → wait for indexing. This matches Bailian, HayStack, and RAGFlow.

## Key parameters

| Field | Notes |
| - | - |
| `apiKey` | Dify dataset API key (required) |
| `datasetId` | Dataset ID (required) |
| `baseUrl` | Default `https://api.dify.ai/v1`, override for self-hosted |
| `retrievalMode` | See table above |
| `enableRerank` | Enable rerank |
| `metadataFilter` | Metadata filter conditions |


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