knowledgebase_update

Author: r3-yamauchi
Version: 0.0.1
Type: tool

English | Japanese

Description

adds two focused tools to your Dify workspace— (text) and (file)—so you can register documents in a knowledge base dataset without writing HTTP requests. Both tools wrap Dify's knowledge APIs, handling validation, UPSERT behaviour, and optional chunking configuration for you.

The source code of this plugin is available in the GitHub repository.

Features

• Maintain a text-first tool that automatically chooses between and .
• Provide an tool that accepts Dify File objects, base64 strings, or downloadable URLs and invokes the file-based APIs.
• Target documents by ID with the optional parameter, ensuring updates land on the intended record.
• Perform document UPSERTs by searching for matching names before issuing updates.
• Share validation of indexing options and JSON across both tools for consistent behaviour.
• Enforce compatible chunking and language combinations so that Q&A mode always includes a language hint.
• Surface clear error hints for common HTTP responses and log each operation outcome for auditability.
• Honour document names: when is provided it is stored and used (case-insensitively) to find existing documents even when is omitted.
• Centralise credential handling via provider settings (, ) so workflows stay tidy.
• Emit both a human-readable summary and a JSON payload that surfaces the resulting for downstream steps.

Prerequisites

• Dify SaaS or self-hosted instance with plugin support enabled
• API Secret with permission to manage the target knowledge base dataset
• Dataset ID for the destination knowledge base

Installation & Setup

1. Install the plugin from the Dify Marketplace or upload this package manually.
2. In the provider settings, supply:
   • API URI – e.g. for SaaS
   • API Secret – knowledge-base API key created in the target dataset
   • (Optional) Timeout (seconds) – overrides the default 30-second HTTP timeout
   • (Optional) Retry Attempts – number of retries for network errors or 5xx responses (default 0)
3. Add either the or tool node to a workflow and configure the parameters described below.

Tool Parameters

The plugin ships two tools that share the same validation and UPSERT logic:

• : accepts raw text and calls Dify's or .
• : accepts file inputs and calls or .

tool (text upload)

Parameter	Required	Default	Description
	✅	–	Target dataset ID in the knowledge base.
	❌	–	Existing document identifier used to update directly; validated before the request is sent.
	✅ (unless is provided)	–	Document name applied to the record and used to resolve UPSERTs when no is given (case-insensitive).
	✅	–	Raw text content that will be indexed.
	✅		Indexing quality mode ( or ).
	❌	–	Chunking strategy (, , or ).
	❌	–	Document language hint. Required when is ; otherwise must be omitted.
	✅		JSON string describing preprocessing and segmentation.
	❌	–	Per-tool timeout in seconds; falls back to the provider value when omitted.
	❌	–	Per-tool retry count for network errors and 5xx responses; defaults to the provider setting.

If is omitted for the tool and no filename can be derived from the file payload, the tool raises an error.

tool (file upload)

Parameter	Required	Default	Description
	✅	–	Target dataset ID in the knowledge base.
	❌	–	Existing document identifier used to update directly; validated before the request is sent.
	❌	–	Document name applied when creating or updating; also used to locate existing records when is omitted (case-insensitive). The uploaded multipart filename mirrors this value—if the name has no extension, the original file extension is appended. Falls back to the uploaded filename when blank.
	✅	–	Dify file object or compatible file payload. The original file name is reused when is empty.
	✅		Indexing quality mode ( or ).
	❌	–	Chunking strategy (, , or ).
	❌	–	Document language hint. Required when is ; otherwise must be omitted.
	✅		JSON string describing preprocessing and segmentation.
	❌	–	Per-tool timeout in seconds; falls back to the provider value when omitted.
	❌	–	Per-tool retry count for network errors and 5xx responses; defaults to the provider setting.

Processing Flow

1. Read / from provider credentials and assert is present in tool parameters.
2. Validate required content inputs ( for , for ).
3. Parse JSON and verify mode-specific requirements (automatic vs custom/hierarchical).
4. If is provided, update the document directly; otherwise look up by (case-insensitive) to decide whether to update or create. When has no extension, the source file extension is appended before uploading so Dify receives a valid filename.
5. Call the corresponding Dify endpoint ( / or / ) with the prepared payload.
6. Return the JSON response with helpful defaults (, fallback when absent).

Usage Example

The tool returns the JSON payload produced by Dify, including the detected and .

Troubleshooting

• Missing credentials – Ensure both and are configured on the provider before running workflows.
• Required content missing – needs , while needs .
• Document name is required – The tool always needs ; the tool can infer it from the file metadata when omitted.
• Document ID not found – When is provided but the dataset does not contain it, the tool raises an error before sending the update.
• Invalid JSON format for process_rule – Check quoting/escaping; the plugin expects a valid JSON string.
• Failed to create/update document: ... – Review the Dify response for details (e.g. dataset ID mismatch, file too large, permission error).
• doc_language can only be provided when doc_form is set to qa_model – Adjust the chunking mode or remove the language hint.
• HTTP 401/403/404 – The plugin now adds hints to these errors; verify credentials, permissions, or dataset IDs according to the message.
• Request rejected: Verify payload fields and formats – Ensure the uploaded filename includes a valid extension. The tool appends the original file's extension when omits it; double-check that the provided name or the source file includes one.

Privacy Policy

Data Handling

This plugin processes the following data:

1. PDF Files: various file types uploaded by users are sent to the knowledge base via the Dify API
2. API Credentials: API URI stored in plugin settings and API Secret supplied per tool invocation are used for authenticating requests to the Dify API
3. Knowledge Base ID: Dataset ID specified as a tool parameter is used to identify the upload destination

Data Storage

• The plugin does not store data locally
• All data is sent to the specified knowledge base via the Dify API
• API URI is managed by Dify's plugin system. API secrets should be injected at runtime through Dify workflows or environment secrets so they are not persisted with the provider configuration.

Security

• API communications are encrypted via HTTPS
• API secrets are not stored by the provider; inject them via secure workflow variables or environment secrets at execution time.

Third-Party Disclosure

This plugin does not send data to any third parties other than the Dify API endpoint specified by the user.

License

This project is released under the MIT License.