Skip to main content

​
Dependencies

No additional dependencies are required beyond the Python package. The Dify resource uses httpx for async API calls. For credential setup, see the Dify Setup guide.

​
Configuration

import os

from mirage import MountMode, Workspace
from mirage.resource.dify import DifyConfig, DifyResource

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
)
resource = DifyResource(config=config)
ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)

​
Config Reference

FieldRequiredDefaultDescription
api_keyYesDify Knowledge API key
base_urlYesDify API base URL
dataset_idYesDify Knowledge dataset
slug_metadata_nameNoslugDify document metadata name used as the virtual path slug
DifyConfig normalizes base_url by removing a trailing slash and trims slug_metadata_name.

​
Environment Example

# .env.development
DIFY_API_KEY=dataset-...
DIFY_BASE_URL=https://api.dify.ai/v1
DIFY_DATASET_ID=...
DIFY_SLUG_METADATA_NAME=slug

​
Metadata Setup

For stable filesystem paths and scoped search, add a Dify document metadata field named by slug_metadata_name. The default field name is slug. 
name: slug
value: guides/quickstart.md
If your Dify metadata field is named path instead, configure: 
config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name="path",
)
Mirage maps that document to: 
/knowledge/guides/quickstart.md
If a document does not have the configured slug metadata field, Mirage uses the document name as the path. To make scoped search work for those name-based documents, enable Dify’s Built-in Fields in the dataset metadata settings so document_name can be used as a metadata filter. See Dify Setup for the full metadata checklist.