Setup
The mount reads the Dify Knowledge Base API with a Knowledge API key:- In Dify, open Knowledge, click Service API in the top right, then API Key, and create a key. Only workspace owners and admins can.
- Give the key access to all knowledge bases or to the one to mount. The scope cannot change later.
- Copy the Service API endpoint from the same panel:
https://api.dify.ai/v1on Dify Cloud, the instance’s own/v1URL when self-hosted. - Copy the dataset ID, the value after
/datasets/in the knowledge base URL. - Keep API Access on for that knowledge base (it is on by default).
Give documents a slug
Give documents a slug
A document’s path is the value of its
slug metadata field. Without one,
the file takes the document name. slug_metadata_name picks another field,
such as path.In the Knowledge UI, open each document and add a metadata item named
slug. Documents uploaded through the API carry the same item in their
metadata.- Forward slashes make folders; leading and trailing slashes are trimmed.
- No empty segment,
.or... - Values stay unique: two documents with one slug fail as a duplicate path.
- A slug is never a parent of another:
guidesandguides/quickstart.mdcollide.
Scoped search on name-based files
Scoped search on name-based files
search limited to a path filters Dify retrieval by the slug field, or by
document_name for a document without one. That filter needs Built-in
Fields turned on in the dataset’s metadata settings, with
document_name available. Without it, scoped search on name-based files
may return nothing, while ls, find, cat and grep still work. A slug
on every document gives the most predictable paths.Connect
- YAML
- Python
- TypeScript
workspace.yaml
Layout
- Only enabled, fully indexed, unarchived documents appear.
- A file is plain text, its segments joined by line breaks, whatever the original format.
- The
searchCLI asks Dify’s retrieval with--method semantic,fulltext,hybridorkeyword;--top-kis capped at 100.
Sample runs
SDK guides
Python
Every config field, the VFS.md and write support.
TypeScript
Every config field, the VFS.md and write support.