# App Toolkit
Source: https://docs.dify.ai/en/cloud/use-dify/build/additional-features
Optional features that make your Dify apps more useful
Dify apps come with optional features you can enable to improve the end-user experience. Open the **Features** panel of the builder to see what's available for your app type.
![Features Panel in Chatbots, Agents, and Text Generators]()
![Features Panel in Chatflows]()
## Conversation Opener
Set an opening message that greets users at the start of each conversation, with optional suggested questions to guide them toward what the app does well.
You can insert variables into the opening message and suggested questions to personalize the experience.
* In the opening message, type `{` or `/` to insert variables from the picker.
* In suggested questions, type variable names manually in `{{variable_name}}` format.
![Configuration]()
![Web App]()
## Follow-up
When enabled, follow-up questions are generated after each response to help users continue the conversation.
Click **Settings** to pick the model that generates the questions, or write a custom prompt (up to 1,000 characters) to adjust the number, wording, or length of the questions.
## Text to Speech
Convert AI responses to audio. You can configure the language and voice to match your app's audience, and enable **Auto Play** to stream audio automatically as the AI responds.
**Text to Speech** uses your workspace's text-to-speech model (set in **Integrations** > **Model Provider** > **Default Models**).
The feature only appears in the **Features** panel when a default TTS model is configured.
## Speech to Text
Enable voice input for the chat interface. When enabled, your end users can dictate messages instead of typing by clicking the microphone button.
**Speech to Text** uses your workspace's speech-to-text model (set in **Integrations** > **Model Provider** > **Default Models**).
The feature only appears in the **Features** panel when a default STT model is configured.
## File Upload
Allow end users to send files at any point during a conversation. You can configure which file types to accept, the upload method, and the maximum number of files per message.
Per-file size limits:
* Images: 10 MB
* Documents: 15 MB
* Audio: 50 MB
* Video: 100 MB
## Citations and Attributions
Show the source documents behind AI responses. When enabled, responses that draw from a connected knowledge base display numbered citations linking back to the original documents and chunks.
![Citations and Attributions]()
## Content Moderation
Filter inappropriate content in user inputs, AI outputs, or both. Choose a moderation provider based on your needs:
* **OpenAI Moderation**: Use OpenAI's dedicated moderation model to detect harmful content across multiple categories.
* **Keywords**: Define a list of blocked terms. Any match triggers the preset response.
* **Custom Endpoint**: Connect a custom moderation endpoint for your own filtering logic.
When content is flagged, the app replaces it with a preset response that you define.
## Annotation Reply
Define curated Q\&A pairs that take priority over LLM responses. When a user's query **semantically** matches an annotation above the score threshold (how closely a query must match), the curated answer is returned directly without calling the LLM.
You can configure the score threshold and the embedding model used for semantic matching.
To create and manage your annotations:
* Convert existing conversations into annotations directly from **Debug & Preview** or **Logs** by clicking the **Add annotation** icon on any LLM response.
Once a message is annotated, the icon changes to **Edit**, so you can modify the annotation in place.
![Add Annotation Icon]()
* In **Annotations**, manually add new Q\&A pairs, manage existing annotations, and view hit history. Click `...` to bulk import or bulk export.
![Bulk Annotation Operation]()
## More Like This
Generate alternative outputs for the same input. Once enabled, each generated result includes a button to produce a variation, so you can explore different responses without re-entering your query.
![More Like This]()
You can generate up to 2 variations per result. Each variation uses additional tokens.
# Agent
Source: https://docs.dify.ai/en/cloud/use-dify/build/agent
Chat-style apps where the model can reason, make decisions, and use tools autonomously
[A new kind of Agent](/en/cloud/use-dify/build/new-agent/overview) is in beta: it works in a sandbox of its own, and you build it once to use as a chat app or inside workflows.
Agents are chat-style apps where the model can reason through a task, decide what to do next, and use tools when needed to complete the user's request.
Use it when you want the model to autonomously decide how to approach a task using available tools, without designing a multi-step workflow. For example, building a data analysis assistant that can fetch live data, generate charts, and summarize findings on its own.
Agents keep up to 500 messages or 2,000 tokens of history per conversation. If either limit is exceeded, the oldest messages will be removed to make room for new ones.
Agents support optional features like conversation openers, follow-up suggestions, and more. See [App Toolkit](/en/cloud/use-dify/build/additional-features) for details.
## Configure
### Write the Prompt
The prompt tells the model what to do, how to respond, and what constraints to follow. For an agent, the prompt also guides how the model reasons through tasks and decides when to use tools, so be specific about the workflow you expect.
Here are some tips for writing effective prompts:
* **Define the persona**: Describe who the model should act as and the expertise it should draw on.
* **Specify the output format**: Describe the structure, length, or style you expect.
* **Set constraints**: Tell the model what to avoid or what rules to follow.
* **Guide tool usage**: Mention specific tools by name and describe when they should be used.
* **Outline the workflow**: Break down complex tasks into logical steps the model should follow.
#### Create Dynamic Prompts with Variables
To adapt the agent to different users or contexts without rewriting the prompt each time, add variables to collect the necessary information upfront.
Variables are placeholders in the prompt—each one appears as an input field that users fill in before the conversation starts, and their values are injected into the prompt at runtime. Users can also update variable values mid-conversation, and the prompt will adjust accordingly.
For example, a data analysis agent might use a domain variable so users can specify which area to focus on:
```text wrap theme={null}
You are a data analyst specializing in {{domain}}. Help users explore and understand their data.
When asked a question, use available data tools to fetch the relevant information. If the result suits a visual format, generate a chart. Explain your findings in plain language.
Keep responses concise. If a question is ambiguous, ask for clarification before fetching data.
```
While drafting the prompt, type `/` > **New Variable** to quickly insert a named placeholder. You can configure its details in the **Variables** section later.
Choose the variable type that matches the input you expect:
Accepts up to 256 characters. Use it for names, email addresses, titles, or any brief text input that fits on a single line.
Allows long-form text without length restrictions. It gives users a multi-line text area for detailed descriptions.
Displays a dropdown menu with predefined options.
Restricts input to numerical values only—ideal for quantities, ratings, IDs, or any data requiring mathematical processing.
Provides a simple yes/no option. When a user checks the box, the output is `true`; otherwise, it's `false`. Use it for confirmations or any case that requires a binary choice.
Fetches variable values from an external API at runtime instead of collecting them from users.
Use it when your prompt needs dynamic data from an external source, such as live weather conditions or database records. See [Custom Endpoints](/en/cloud/use-dify/workspace/api-extension/api-extension) for details.
**Label Name** is what end users see for each input field.
#### Generate or Improve the Prompt with AI
If you're unsure where to start or want to refine the existing prompt, click **Generate** to let an LLM help you draft it.
Describe what you want from scratch, or reference `current_prompt` and specify what to improve. For more targeted results, add an example in **Ideal Output**.
Each generation is saved as a version, so you can experiment and roll back freely.
### Extend the Agent with Dify Tools
Add [Dify tools](/en/cloud/use-dify/workspace/tools) to enable the model to interact with external services and APIs for tasks beyond text generation, such as fetching live data, searching the web, or querying databases.
The model decides when and which tools to use based on each query. To guide this more precisely, mention specific tool names in your prompt and describe when they should be used.
![Tool Name]()
You can disable or remove added tools, and modify their configuration. If a tool requires authentication, select an existing credential or create a new one.
To change the default credential, go to **Integrations** > **Tools** > **Tool Plugin**.
#### Maximum Iterations
**Maximum Iterations** in **Agent Settings** limits how many times the model can repeat its reasoning-and-action cycle (think, call a tool, process the result) for a single request.
Increase this value for complex, multi-step tasks that require multiple tool calls. Higher values increase latency and token costs.
### Ground Responses in Your Own Data
To ground the model's responses in your own data rather than general knowledge, add a knowledge base.
The model evaluates each user query against your knowledge base descriptions and decides whether retrieval is needed—you don't need to mention knowledge bases in your prompt.
**The more detailed your knowledge base description, the better the model can determine relevance**, leading to more accurate and targeted retrieval.
An Agent app has no app-level retrieval settings. Each knowledge base is queried independently using its own settings you've configured. When you add several, the agent picks which to query and does not rerank results across them.
#### Search Within Specific Documents
By default, retrieval searches across the entire knowledge base. To restrict retrieval to specific documents, enable manual or automatic metadata filtering.
This improves retrieval precision, especially when your knowledge base is large or contains content for different contexts.
For creating and managing document metadata, see [Metadata](/en/cloud/use-dify/knowledge/metadata).
### Process Multimodal Inputs
To allow end users to upload files, select a model with the corresponding multimodal capabilities. The relevant file type toggles—**Vision**, **Audio**, or **Document**—appear once the model supports them, and you can enable each as needed.
You can quickly identify a model's supported modalities by its tags.
![Model Tags]()
Click **Settings** under **Vision** to configure how files are accepted and processed. Upload settings apply across all enabled file types.
* **Resolution**: Controls the detail level for **image** processing only.
* **High**: Better accuracy for complex images but uses more tokens
* **Low**: Faster processing with fewer tokens for simple images
* **Upload Method**: Choose whether users can upload from their device, paste a URL, or both.
* **Upload Limit**: The maximum number of files a user can upload per message.
## Debug & Preview
In the preview panel on the right, test your agent in real time. Select a model, type a message, and send it to see how the agent responds.
You can adjust a model's parameters to control how it generates responses. Available parameters and presets vary by model.
To compare outputs across different models, click **Debug as Multiple Models** to run up to 4 models simultaneously.
![Debug with Multiple Models]()
We recommend selecting models that are strong at **reasoning** and **natively support tool calling**.
An agent needs to judge *when* to use a tool, *which tool* fits the task, and *how* to interpret the result—this depends on the model's reasoning ability. Models with built-in tool-call support also execute these decisions more reliably.
You can verify your model's tool-call support in **Agent Settings**, where the system automatically displays the agent mode:
* **Function Calling** for models with native support, meaning they can call tools directly.
* **ReAct** for others, so Dify guides them to use tools through a prompting strategy.
## Publish
When you're happy with the results, click **Publish** to make your app available. See [Publish](/en/cloud/use-dify/publish/README) for the full list of publishing options.
# Chatbot
Source: https://docs.dify.ai/en/cloud/use-dify/build/chatbot
The simplest way to build a conversational app with a model and a prompt
Chatbots are conversational apps where users interact with the model through a chat interface.
Use it for tasks that benefit from back-and-forth interaction but don't require tool calls or a multi-step workflow—for example, building an internal Q\&A assistant grounded in your team's knowledge base.
Chatbots keep up to 500 messages or 2,000 tokens of history per conversation. If either limit is exceeded, the oldest messages will be removed to make room for new ones.
Chatbots also support optional features like conversation openers, follow-up suggestions, and more. See [App Toolkit](/en/cloud/use-dify/build/additional-features) for details.
## Configure
### Write the Prompt
The prompt tells the model what to do, how to respond, and what constraints to follow. It shapes how the model behaves throughout the conversation, so think of it as defining a consistent persona rather than describing a one-off task.
Here are some tips for writing effective prompts:
* **Define the persona**: Describe who the model should act as and the tone it should use.
* **Specify the output format**: Describe the structure, length, or style you expect.
* **Set constraints**: Tell the model what to avoid or what rules to follow.
#### Create Dynamic Prompts with Variables
To adapt your chatbot to different users or contexts without rewriting the prompt each time, add variables to collect the necessary information upfront.
Variables are placeholders in the prompt—each one appears as an input field that users fill in before the conversation starts, and their values are injected into the prompt at runtime. Users can also update variable values mid-conversation, and the prompt will adjust accordingly.
For example, an onboarding assistant might use `role` and `language` to tailor its responses:
```text wrap theme={null}
You are an onboarding assistant for new {{role}} hires. Answer questions about company processes and policies. Keep answers friendly and concise, and respond in {{language}}.
```
While drafting the prompt, type `/` > **New Variable** to quickly insert a named placeholder. You can configure its details in the **Variables** section later.
Choose the variable type that matches the input you expect:
Accepts up to 256 characters. Use it for names, email addresses, titles, or any brief text input that fits on a single line.
Allows long-form text without length restrictions. It gives users a multi-line text area for detailed descriptions.
Displays a dropdown menu with predefined options.
Restricts input to numerical values only—ideal for quantities, ratings, IDs, or any data requiring mathematical processing.
Provides a simple yes/no option. When a user checks the box, the output is `true`; otherwise, it's `false`. Use it for confirmations or any case that requires a binary choice.
Fetches variable values from an external API at runtime instead of collecting them from users.
Use it when your prompt needs dynamic data from an external source, such as live weather conditions or database records. See [Custom Endpoints](/en/cloud/use-dify/workspace/api-extension/api-extension) for details.
**Label Name** is what end users see for each input field.
#### Generate or Improve the Prompt with AI
If you're unsure where to start or want to refine the existing prompt, click **Generate** to let an LLM help you draft it.
Describe what you want from scratch, or reference `current_prompt` and specify what to improve. For more targeted results, add an example in **Ideal Output**.
Each generation is saved as a version, so you can experiment and roll back freely.
### Ground Responses in Your Own Data
To ground the model's responses in your own data rather than general knowledge, add a knowledge base.
Each time a user sends a message, it is used as the search query to retrieve relevant content from the knowledge base, which is then injected into the prompt as context for the model.
#### Configure App-Level Retrieval Settings
To fine-tune how retrieval results are processed, click **Retrieval Setting**.
There are two layers of retrieval settings—the knowledge base level and the app level.
Think of them as two consecutive filters: the knowledge base settings determine the initial pool of results, and the app settings further rerank the results or narrow down the pool.
* **Rerank Settings**
* **Weighted Score**
The relative weight between semantic similarity and keyword matching during reranking. Higher semantic weight favors meaning relevance, while higher keyword weight favors exact matches.
Weighted Score is available only when all added knowledge bases are indexed with **High Quality** mode.
* **Rerank Model**
The rerank model to re-score and reorder all the results based on their relevance to the query.
If any multimodal knowledge bases are added, select a multimodal rerank model (marked with a **Vision** tag) as well. Otherwise, retrieved images will be excluded from reranking and the final output.
* **Top K**
The maximum number of top results to return after reranking.
When a rerank model is selected, this value will be automatically adjusted based on the model's maximum input capacity (how much text the model can process at once).
* **Score Threshold**
The minimum similarity score for returned results. Results scoring below this threshold are excluded. Use higher thresholds for stricter relevance or lower thresholds to include broader matches.
#### Search Within Specific Documents
By default, retrieval searches across the entire knowledge base. To restrict retrieval to specific documents, enable manual or automatic metadata filtering.
This improves retrieval precision, especially when your knowledge base is large or contains content for different contexts.
For creating and managing document metadata, see [Metadata](/en/cloud/use-dify/knowledge/metadata).
### Process Multimodal Inputs
To allow end users to upload files, select a model with the corresponding multimodal capabilities. The relevant file type toggles—**Vision**, **Audio**, or **Document**—appear once the model supports them, and you can enable each as needed.
You can quickly identify a model's supported modalities by its tags.
![Model Tags]()
Click **Settings** under **Vision** to configure how files are accepted and processed. Upload settings apply across all enabled file types.
* **Resolution**: Controls the detail level for **image** processing only.
* **High**: Better accuracy for complex images but uses more tokens
* **Low**: Faster processing with fewer tokens for simple images
* **Upload Method**: Choose whether users can upload from their device, paste a URL, or both.
* **Upload Limit**: The maximum number of files a user can upload per message.
## Debug & Preview
In the preview panel on the right, test your chatbot in real time. Select a model that best fits your task, type a message, and send it to see how the model responds.
After selecting a model, you can adjust its parameters to control how it generates responses. Available parameters and presets vary by model.
To compare outputs across different models, click **Debug as Multiple Models** to run up to 4 models simultaneously.
![Debug with Multiple Models]()
## Publish
When you're happy with the results, click **Publish** to make your app available. See [Publish](/en/cloud/use-dify/publish/README) for the full list of publishing options.
# Go to Anything
Source: https://docs.dify.ai/en/cloud/use-dify/build/goto-anything
Search and jump to apps, agents, knowledge bases, integrations, and workflow nodes from anywhere with a keyboard shortcut
The **Go to Anything** overlay is a search box for the whole console: type once to find apps, agents, knowledge bases, Marketplace integrations, and nodes on the canvas you're editing, or run quick commands.
### Open the Overlay
Press `⌘ + K` on macOS or `Ctrl + K` on Windows/Linux, or click the search button at the top of the sidebar.
If the shortcut doesn't respond, another app or browser extension may be using it. The sidebar button always works.
### Search with @
Type a keyword to search everything at once; results are grouped by category. Prefix a scope to narrow the search:
* `@app` – search your applications
* `@knowledge` or `@kb` – search knowledge bases
* `@plugin` – search integrations on the Marketplace
* `@agent` – search your agents
* `@node` – search nodes on the open canvas (available for workflows and knowledge pipelines)
Navigate results with the arrow keys and press `Enter` to open the selected item.
### Run Commands with /
Type `/` to see every command, or keep typing to filter:
| Command | What it does |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| `/create` / `/new` | describe an app and Dify builds it as a Workflow or Chatflow; pick the type yourself or choose **Auto** to let the AI decide |
| `/refine` / `/improve` | describe a change and Dify applies it to the Workflow or Chatflow you're editing (only when one is open) |
| `/go` | jump to a main section of the console |
| `/docs` | open the help documentation |
| `/discord` | open the Discord community |
| `/models` | open the system model settings |
| `/account` | go to your account page |
| `/theme` | switch the interface theme |
| `/language` / `/lang` | change the interface language |
# Build an Agent
Source: https://docs.dify.ai/en/cloud/use-dify/build/new-agent/build
Create an agent and shape what it can do, by hand or by describing what you want
The new Agent is in beta.
## Create an Agent
From **Agents**, click **Create** > **Create from Blank** and give the agent a name; optionally add a role such as *Research Assistant* and a description. Then you shape everything else in **Configure**.
To create an agent from a shared DSL file, choose **Import DSL file**. Skills and files aren't included, so add them after importing.
Creating and managing agents requires the Editor role or above.
## Configure Its Capabilities
Set up each capability by hand, or describe what you want and build it by chatting in [Build mode](#build-by-chatting).
Everything you set up in **Configure** is saved as the agent's capabilities and used in every task later. Separately, the agent works inside its own *sandbox* with 20 GB of storage, where it runs commands and handles files as it goes.
The agent's capabilities can only be changed here: even if an end user asks a published agent to change its own prompt, skills, or tools, it won't.
### Model
Pick the chat model the agent runs on. Favor models that are strong at reasoning and natively support tool calling, since the agent has to judge when to act, which tool fits, and how to read the result.
Agent performance rises and falls with the model, so pick a recent one.
Older models often can't make full use of the sandbox: a common symptom is an agent that never runs commands or installs tools, even when the task needs it.
### Prompt
In the prompt, set the agent's role and how it should approach its work. Be specific about how it should reason, when to lean on its tools, and what to avoid.
A few things worth covering:
* **Persona and goal**: who the agent acts as and what it's trying to achieve.
* **Approach**: the steps or order you expect for a typical task.
* **Tool and file use**: when to reach for each, named explicitly.
* **Output**: the format, length, or tone you want back.
You can point the agent at a specific skill, file, or tool, or leave the choice to the agent:
* **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one.
* **Just add it to its section** and let the agent decide on its own when to use it. Best when you'd rather trust the agent's judgment than script every move.
### Skills
A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers just that task.
For example, a support agent's prompt might set its role as a customer helper that handles any issue, while its `refund-requests` skill covers only refunds: look up the order, refund only within 30 days, and end with a help-center link.
Click **Add** to upload a skill package: a `.zip` or `.skill` file with a `SKILL.md` inside, up to 50 MB. See [Agent Skills](https://agentskills.io/home) for the package format.
You can also have the agent create skills for you in [Build mode](#build-by-chatting).
To make a Dify tool or file part of the agent's own capabilities, add it to the agent directly rather than inside a skill package.
### Files
Files are reference documents the agent can read while it works, like specs, templates, or guidelines. Unlike a skill, a file is just material to read, not a procedure to run.
Size limits depend on file type:
| File type | Limit |
| :-------- | :----- |
| Documents | 15 MB |
| Images | 10 MB |
| Video | 100 MB |
| Audio | 50 MB |
You can also have the agent create files and save them here in [Build mode](#build-by-chatting). Files the agent creates and saves are capped at 50 MB each.
### Tools
Give the agent [Dify tools](/en/cloud/use-dify/workspace/tools) so it can act beyond the chat: plugins, custom APIs, workflows, and MCP servers from your workspace. Some tools need authentication before use.
Beyond the Dify tools you add here, the agent can also install and run command-line tools on its own inside the sandbox when it needs one. Those tools don't appear in the Tools list.
Tools the agent installs in [Build mode](#build-by-chatting) can stay available after publishing, while anything installed during a published run is temporary.
### Environment Variables
Under **Advanced Settings**, you can add **environment variables**: key-value pairs the agent can read in its sandbox while it works.
Say your agent's skills all work with the same order system: one checks stock, one files orders, one pulls reports. Store the system's address here as `ORDER_API_URL`, and every script reads it by name. To switch from the test system to the production one, update this one value, and all of them follow.
Import a `.env` file to add several at once. You can also have the agent set them up in [Build mode](#build-by-chatting).
## Build by Chatting
Instead of setting everything up by hand, you can build the agent by describing what it should do, and as you chat it sets up *skills*, *files*, and *environment variables* itself.
For example, your first message might be:
```text wrap theme={null}
Build an agent that turns raw meeting notes into structured minutes: attendees, decisions, and action items.
```
You're talking to the live agent: test it as you build, watch how it behaves, and refine it in the same build chat.
As the agent works, it edits the configuration in the panel directly, and you can see all changes listed in **Build draft**. Click **Apply** to keep them, or **Discard** to drop. Either one exits Build mode and clears the conversation.
**Discard** drops everything from this build chat: any changes to the configuration and persistent files in the [**File system**](#file-system).
While you're in Build mode, the configuration panel is read-only—just tell the agent what you want to change.
### File System
In Build mode, the agent handles real files in its sandbox: artifacts it generates, programs it installs on its own, and everything else it's working with. During a build chat, click **File system** in the top-right corner to browse them.
Since a build chat is where you shape the agent itself, whatever it adds (a template it drafted, a tool it installed) is **Persistent** by default, kept for every future conversation and workflow run. In effect, these files are part of the agent's setup, like its prompt and skills.
For one-off work, like a test file or a converter it only needs once, tell the agent in the chat, e.g. "keep this file temporary": it goes under **Temporary** and is cleared when this build chat ends.
In published runs, whatever the agent adds is always temporary, so nothing that happens in a run changes the agent itself.
### The Build Note
In build chats, the agent records what it set up in a *build note*, a `build_note.md` that appears in **Files** the first time you **Apply**.
The note is saved with the agent's setup, and it reads the note back at the start of every new conversation, combining it with your **Prompt** to form its instructions.
After you apply, open the build note and read what the agent captured:
* If it covers what you want, you're set.
* To change what it says, have the agent revise it in Build mode.
The agent maintains only the auto-generated build note: a downloaded copy you re-upload is just an ordinary file, and the next build chat creates a fresh note alongside it.
* If anything's missing, add it to the **Prompt**.
* To start over with a clean record, delete the note in **Files**.
Across build chats, the note also serves as the agent's *memory*. If you shaped the meeting-minutes agent in one chat, a later chat to add action-item owners starts from the format and decisions you already settled, not from scratch.
## Preview
Switch the right panel from **Build** to **Preview** to try the agent exactly as end users will experience it once published: clean replies and your Chat Features active.
Chatting in Preview mode never changes the agent's configuration, so use it as the final check before you publish.
## Publish
Your edits autosave as a draft. When the agent is ready, publish it to make that version live. Open the version history anytime to revisit or restore an earlier version.
Restoring a version also restores the persistent files in the agent's sandbox to that version.
To polish the chat experience, you can add extras like a welcome message, suggested questions, and voice in **Chat Features**. See [App Toolkit](/en/cloud/use-dify/build/additional-features) for details.
From the **Access Point** tab, host it as a web app at a shareable link, embed it in your site, or call it from your code through the [service API](/en/api-reference/guides/agent).
You can also invite the agent into a workflow's [Agent node](/en/cloud/use-dify/nodes/agent#new-agent) to handle a step.
To share the agent across workspaces, export it as a DSL file. Skills and files aren't included, so share them alongside.
### Run Limits
* **Time**
A single agent run is stopped after 1 hour, whichever access point it starts from (web app, service API, or a workflow), and the unfinished reply is discarded.
If a run gets cut off, try again or break the task into smaller steps.
* **Model requests**
Every call the agent makes to its model counts toward a cap of 500 per run, so heavy reasoning and frequent tool use spend it faster.
Try breaking the task into smaller steps to keep each run within the cap.
* **Reply files**
Each file the agent sends back in a reply can be up to 50 MB, and larger files aren't delivered.
## Troubleshooting
Models served through OpenAI-compatible endpoints (vLLM and similar) often lack full native tool-calling support, which the agent depends on in build chats as well as published runs.
Pick a model that supports tool calling natively. If a compatible model still errors, check **Token parameter name** in the model's settings on the provider: some newer models require `max_completion_tokens`, and auto-detection can guess wrong.
Some OpenAI models reject tool calls when reasoning is enabled over the Chat Completions protocol. For those, set the provider credential's **API Protocol** to Responses API.
Image upload can be turned on in **Chat Features** regardless of whether the agent's model supports vision. With a non-vision model, the agent may error on an image or reply as if none was sent.
Switch to a model that supports vision: look for the Vision tag when picking the model.
The agent's sandbox runs in the cloud, so hosts on your private network aren't reachable. Public URLs work; for internal material, add it to the agent's [Files](#files) instead.
# Agent
Source: https://docs.dify.ai/en/cloud/use-dify/build/new-agent/overview
Build an agent once, then put it to work as a standalone app or inside a workflow
The new Agent is in beta.
An *Agent* is an AI worker you set up once and then put to work. It's a different kind of agent than the [Legacy Agent app](/en/cloud/use-dify/build/agent):
* It works in a **sandbox of its own**: it runs commands, installs programs, and reads and writes files, so it takes on open-ended work rather than just calling the tools you configured.
* You [build](/en/cloud/use-dify/build/new-agent/build) it **once** and use it **two ways**: on its own as a chat app, or as [a step](/en/cloud/use-dify/nodes/agent#new-agent) inside a workflow.
Create, configure, and manage your agents on the **Agents** page. Open one anytime to refine it or revisit an earlier version.
## Capability and Task
An Agent separates what it *is* from what you ask it to *do*:
* **Its *capability* (think of it as the agent's soul) is who the agent is.**
The role and prompt you write, the model it runs on, and the skills, Dify tools, and files you give it. You shape it once and keep refining it as you learn what the agent needs.
* **Its *task* is what you ask it to do on a given run.**
When the agent works on its own, the task is the message you send it. When it works inside a workflow, the task is the instruction you give the node.
It's the same split as hiring someone: you choose a person for what they can do, then give them a specific task. Strong results need both: the right person for the job and a clear brief.
## Two Ways to Use an Agent
### On Its Own
The agent runs as its own chat app. You give it tasks by chatting, and you can publish it as a web app or call it through the service API.
Each conversation has its own memory: how much the agent keeps in mind depends on the model's context window, and a new conversation starts fresh.
Choose this when a single capable worker can reach the goal on its own: a support assistant that looks things up and answers, or a research agent that gathers sources and summarizes them.
### Inside a Workflow
You invite the agent into an [Agent node](/en/cloud/use-dify/nodes/agent#new-agent) to handle one step of a larger process. There you set only the task you want done. It's like asking a colleague to take care of one thing: you describe the task, and they bring their own skills to it.
Choose this when the work needs structure around it: several steps in a set order, branching on conditions, other kinds of nodes, or a few specialized agents handing off to each other.
However the agent runs, its sessions collect in one place: the **Logs** page, where each row carries its source—the agent's web app or a workflow that uses it.
# Orchestration Logic
Source: https://docs.dify.ai/en/cloud/use-dify/build/orchestrate-node
How to arrange, nest, or reuse nodes when building a Workflow or Chatflow
## Serial and Parallel Execution
![Serial vs. Parallel Execution]()
When building a workflow, you can arrange nodes in series or in parallel:
* **In series**, nodes run one after another. Each node can read variables from any node earlier in the chain.
* **In parallel**, nodes run at the same time. They can't read each other's variables, but where parallel branches converge, the downstream node can read from all of them.
A single execution path supports up to 50 nodes.
## Node Reuse
All nodes except User Input can be copied and pasted within the same workflow, across workflows, or across Dify instances, though there might be compatibility issues between Dify versions.
Pasting across workflows or Dify instances requires the Dify page to be served over HTTPS or accessed via a loopback address (such as `http://localhost` or `http://127.0.0.1`).
When you paste a node, its configuration moves with it, but the availability of anything that depends on the surrounding environment is re-evaluated at the destination:
* **Workflow-specific resources**, such as variables
* **Workspace-specific resources**, such as integrations and knowledge bases
## Iteration and Loop
For nodes that should run multiple times (once per item in a list or until a condition is met), place them inside an [Iteration](/en/cloud/use-dify/nodes/iteration) or [Loop](/en/cloud/use-dify/nodes/loop) node.
# Handle Errors
Source: https://docs.dify.ai/en/cloud/use-dify/build/predefined-error-handling-logic
[LLM](/en/cloud/use-dify/nodes/llm), [HTTP](/en/cloud/use-dify/nodes/http-request), [Code](/en/cloud/use-dify/nodes/code), and [Tool](/en/cloud/use-dify/nodes/tools)
nodes support error handling out-of-box. When a node fails, it can take one of the three behaviors below:
The default behavior. When a node fails, the whole workflow stops. You get the original error message.
Use this when:
* You're testing and want to see what broke
* The workflow can't continue without this step
When a node fails, use a backup value instead. The workflow keeps running.
**Requirements**
* The default value must match the node's output type -- if it outputs a string, your default must be a string.
**Example**
Your LLM node normally returns analysis, but sometimes it fails due to rate limits. Set a default value like:
```
"Sorry, I'm temporarily unavailable. Please try again in a few minutes."
```
Now users get a helpful message instead of a broken workflow.
When a node fails, trigger a separate flow to handle the error.
The fail branch is highlighted in orange. You can:
* Send error notifications
* Try a different approach
* Log the error for debugging
* Use a backup service
**Example**
Your main API fails, so the fail branch calls a backup API instead. Users never know there was a problem.
## Error in Loop/Iteration Nodes
When child nodes fail inside loops and iterations, these control flow nodes have their own error behaviors.
**Loop nodes** always stop immediately when any child node fails. The entire loop terminates and returns the error, preventing any further iterations from running.
**Iteration nodes** let you choose how to handle child node failures through the error handling mode setting:
* `terminated` - Stops processing immediately when any item fails (default)
* `continue-on-error` - Skips the failed item and continues with the next one
* `remove-abnormal-output` - Continues processing but filters out failed items from the final output
When you set an iteration to `continue-on-error`, failed items return `null` in the output array. When you use `remove-abnormal-output`, the output array only contains successful results, making it shorter than the input array.
## Error variables
When using default value or fail branch, you get two special variables:
* `error_type` - What kind of error happened (see [Error Types](/en/cloud/use-dify/debug/error-type))
* `error_message` - The actual error details
Use these to:
* Show users helpful messages
* Send alerts to your team
* Choose different recovery strategies
* Log errors for debugging
**Example**
```
{% if error_type == "rate_limit" %}
Too many requests. Please wait a moment and try again.
{% else %}
Something went wrong. Our team has been notified.
{% endif %}
```
# Hotkeys
Source: https://docs.dify.ai/en/cloud/use-dify/build/shortcut-key
Keyboard shortcuts for building workflows faster in Dify
Speed up your workflow building with keyboard shortcuts.
**[Go to Anything](/en/cloud/use-dify/build/goto-anything)**: Press `Cmd+K` (macOS) or `Ctrl+K` (Windows) anywhere in Dify to find and jump to almost anything.
* Type `@` to search apps, integrations, knowledge bases, or workflow nodes.
* Type `/` to run a command like `/docs`, `/theme`, or `/language`.
![Go to Anything Search Interface]()
## Selection and Editing
With one or more nodes selected on the canvas:
| Windows | macOS | Action |
| :------------- | :------------- | :------------------------------------------------- |
| `Ctrl` + `C` | `Cmd` + `C` | Copy |
| `Ctrl` + `V` | `Cmd` + `V` | Paste |
| `Ctrl` + `D` | `Cmd` + `D` | Duplicate |
| `Delete` | `Delete` | Delete selected nodes or edges |
| `Shift` (hold) | `Shift` (hold) | Highlight the selected node's variable connections |
## Canvas Modes
| Windows | macOS | Action |
| :------ | :---- | :-------------------- |
| `V` | `V` | Pointer mode (select) |
| `H` | `H` | Hand mode (pan) |
| `C` | `C` | Comment mode |
## Zoom and Layout
| Windows | macOS | Action |
| :------------ | :------------ | :------------- |
| `Ctrl` + `1` | `Cmd` + `1` | Zoom to fit |
| `Ctrl` + `=` | `Cmd` + `=` | Zoom in |
| `Ctrl` + `-` | `Cmd` + `-` | Zoom out |
| `Shift` + `1` | `Shift` + `1` | Zoom to 100% |
| `Shift` + `5` | `Shift` + `5` | Zoom to 50% |
| `Ctrl` + `O` | `Cmd` + `O` | Organize nodes |
## History
| Windows | macOS | Action |
| :--------------------- | :-------------------- | :----- |
| `Ctrl` + `Z` | `Cmd` + `Z` | Undo |
| `Ctrl` + `Y` | `Cmd` + `Y` | Redo |
| `Ctrl` + `Shift` + `Z` | `Cmd` + `Shift` + `Z` | Redo |
## Testing
| Windows | macOS | Action |
| :---------- | :------------- | :------- |
| `Alt` + `R` | `Option` + `R` | Test run |
# Snippets
Source: https://docs.dify.ai/en/cloud/use-dify/build/snippet
Reuse and share groups of nodes across workflows
Useful node patterns have a way of showing up in more than one workflow. Without a way to save and reuse them, you end up rebuilding the same logic every time: a particular chain of LLM and tool nodes, a data processing sequence, or a multi-step summarization pipeline.
Save a group of nodes as a reusable unit by turning them into a *snippet*: build the logic once, reuse it across workflows, and share it with your team to save others the effort of building the same thing from scratch.
You can also export snippets as DSL files to share them across workspaces.
## Create a Snippet
There are three ways to create a snippet:
* **From a workflow**
Select the nodes you want to reuse, then right-click and choose **Create Snippet**.
Their configurations are saved into the snippet. Any external variables they reference (outputs from nodes you didn't select, environment variables, and so on) become the snippet's [Input Variables](#edit-a-snippet).
An exception: an LLM node that takes its model from an environment variable keeps that model configuration as a fixed setting, so the snippet uses the same model wherever you add it.
* **From scratch**
In **Studio**, click **Snippets** at the top-right corner, then click **Create Snippet** > **Create from blank** to start with an empty canvas.
* **From a DSL file**
In **Studio**, click **Snippets** at the top-right corner, then click **Create Snippet** > **Import DSL file** to import an existing snippet.
A snippet you create is shared with your workspace. What each member can do with it depends on their workspace role; see [Permissions](#permissions).
## Edit a Snippet
Building a snippet works much like building a standard workflow, with two differences.
First, a few nodes aren't available. Because a snippet plugs into a workflow instead of running on its own, it has no Start node (User Input or Triggers) and no end node (Output for Workflows, Answer for Chatflows). Knowledge Retrieval and Human Input aren't supported yet either.
Second, because a snippet has no Start node to collect input, you define **Input Variables** that specify what data it expects to receive, such as a variable from an upstream node. When a snippet is added to a workflow, these input variables become the connection points.
## Publish a Snippet
As you edit, your changes save automatically as a draft, so you can pick up where you left off next time. When the draft is ready, click **Publish** to make it usable. A workflow always uses the published version, never a draft.
Every publish is kept in the snippet's version history, where you can review or restore an earlier version.
## Add a Snippet to a Workflow
Right-click on the canvas, select **Add Node** > **Snippets**, then choose one to insert. Only published snippets appear here.
The snippet is added to your canvas as a copy. In the inserted nodes, set each input variable to the appropriate variable from your workflow, so they receive the data they expect.
Editing the original snippet later won't change workflows that already use it, and vice versa.
## Permissions
What you can do with a snippet depends on your workspace role:
| Action | Roles |
| :------------------------------------ | :-------------------------------------- |
| View the snippet list | Owner, Admin, Editor |
| Create, edit, and publish snippets | Owner, Admin, Editor |
| Delete snippets | Owner, Admin |
| Add a published snippet to a workflow | Anyone who can edit the target workflow |
Members with the Normal role don't see the snippet list.
# Text Generator
Source: https://docs.dify.ai/en/cloud/use-dify/build/text-generator
Simple single-turn apps for generating text from a prompt and user inputs
Text Generators are simple single-turn apps: you write a prompt, provide inputs, and the model generates a response.
It's a good fit for tasks that don't require multi-turn conversation, tool calls, or a multi-step workflow. Just a clear input, one model call, and a ready-to-use output.
Text Generators support optional features like generating multiple outputs at once, text to speech, and content moderation. See [App Toolkit](/en/cloud/use-dify/build/additional-features) for details.
## Configure
### Write the Prompt
The prompt tells the model what to do, how to respond, and what constraints to follow.
Since a Text Generator runs in a single turn with no conversation history, the prompt is the model's only source of context—include everything it needs to produce the right output in one pass.
Here are some tips for writing effective prompts:
* **Define the task clearly**: State what the model should produce (e.g., a translation, a summary, a SQL statement).
* **Specify the output format**: Describe the structure, length, or style you expect.
* **Set constraints**: Tell the model what to avoid or what rules to follow.
Because a Text Generator always requires user input to run, a paragraph-type `query` variable is automatically inserted into the prompt when you create a new app. You can rename `query` or change its type.
Variables are placeholders—each one becomes an input field that users fill in before running the app, and their values are substituted into the prompt at runtime. For example:
```text wrap theme={null}
You are a professional editor. Summarize the following text into 3 concise bullet points. Use neutral tone and avoid adding information not present in the original text.
{{query}}
```
While drafting the prompt, type `/` > **New Variable** to quickly insert a named placeholder. You can configure its details in the **Variables** section later.
Choose the variable type that matches the input you expect:
Accepts up to 256 characters. Use it for names, email addresses, titles, or any brief text input that fits on a single line.
Allows long-form text without length restrictions. It gives users a multi-line text area for detailed descriptions.
Displays a dropdown menu with predefined options.
Restricts input to numerical values only—ideal for quantities, ratings, IDs, or any data requiring mathematical processing.
Provides a simple yes/no option. When a user checks the box, the output is `true`; otherwise, it's `false`. Use it for confirmations or any case that requires a binary choice.
Fetches variable values from an external API at runtime instead of collecting them from users.
Use it when your prompt needs dynamic data from an external source, such as live weather conditions or database records. See [Custom Endpoints](/en/cloud/use-dify/workspace/api-extension/api-extension) for details.
**Label Name** is what end users see for each input field.
#### Create Dynamic Prompts with Variables
To adapt your app to different users or contexts without rewriting the prompt each time, add more variables.
Each variable collects a specific piece of information upfront and injects it into the prompt at runtime.
For example, an SQL generator might use `database_type` to adapt the output dialect while `query` captures the user's natural language request:
```text wrap theme={null}
You are an SQL generator. Translate the following natural language query into a {{database_type}} SQL statement: {{query}}
```
#### Generate or Improve the Prompt with AI
If you're unsure where to start or want to refine the existing prompt, click **Generate** to let an LLM help you draft it.
Describe what you want from scratch, or reference `current_prompt` and specify what to improve. For more targeted results, add an example in **Ideal Output**.
Each generation is saved as a version, so you can experiment and roll back freely.
### Ground Responses in Your Own Data
To ground the model's responses in your own data rather than general knowledge, add a knowledge base and select an existing variable as the **Query Variable**.
When a user runs the app and fills in that field, its value is used as the search query to retrieve relevant content from the knowledge base. The retrieved content is then injected into the prompt as context, so the model can generate a more informed response.
For example, suppose your knowledge base contains style guides for different content types—blog posts, social media captions, product descriptions, and so on.
In a content writing app, set `content_type` as the **Query Variable**. When a user selects a content type, the app retrieves the matching style guide and generates copy that follows the corresponding writing standards.
Your prompt might look like this:
```text wrap theme={null}
You are a brand content writer. Write a {{content_type}} based on the following brief: {{brief}}
Follow the style and tone guidelines provided in the context.
```
#### Configure App-Level Retrieval Settings
To fine-tune how retrieval results are processed, click **Retrieval Setting**.
There are two layers of retrieval settings—the knowledge base level and the app level.
Think of them as two consecutive filters: the knowledge base settings determine the initial pool of results, and the app settings further rerank the results or narrow down the pool.
* **Rerank Settings**
* **Weighted Score**
The relative weight between semantic similarity and keyword matching during reranking. Higher semantic weight favors meaning relevance, while higher keyword weight favors exact matches.
Weighted Score is available only when all added knowledge bases are indexed with **High Quality** mode.
* **Rerank Model**
The rerank model to re-score and reorder all the results based on their relevance to the query.
If any multimodal knowledge bases are added, select a multimodal rerank model (marked with a **Vision** tag) as well. Otherwise, retrieved images will be excluded from reranking and the final output.
* **Top K**
The maximum number of top results to return after reranking.
When a rerank model is selected, this value will be automatically adjusted based on the model's maximum input capacity (how much text the model can process at once).
* **Score Threshold**
The minimum similarity score for returned results. Results scoring below this threshold are excluded. Use higher thresholds for stricter relevance or lower thresholds to include broader matches.
#### Search Within Specific Documents
By default, retrieval searches across the entire knowledge base. To restrict retrieval to specific documents, enable manual or automatic metadata filtering.
This improves retrieval precision, especially when your knowledge base is large or contains content for different contexts.
For creating and managing document metadata, see [Metadata](/en/cloud/use-dify/knowledge/metadata).
### Process Multimodal Inputs
To allow end users to upload files, select a model with the corresponding multimodal capabilities. The relevant file type toggles—**Vision**, **Audio**, or **Document**—appear once the model supports them, and you can enable each as needed.
You can quickly identify a model's supported modalities by its tags.
![Model Tags]()
Click **Settings** under **Vision** to configure how files are accepted and processed. Upload settings apply across all enabled file types.
* **Resolution**: Controls the detail level for **image** processing only.
* **High**: Better accuracy for complex images but uses more tokens
* **Low**: Faster processing with fewer tokens for simple images
* **Upload Method**: Choose whether users can upload from their device, paste a URL, or both.
* **Upload Limit**: The maximum number of files a user can upload per run.
## Debug & Preview
In the preview panel on the right, test your app in real time. Select a model that best fits your task, fill in the input fields, and click **Run** to see the output.
After selecting a model, you can adjust its parameters to control how it generates responses. Available parameters and presets vary by model.
To compare outputs across different models, click **Debug as Multiple Models** to run up to 4 models simultaneously.
![Debug with Multiple Models]()
## Publish
When you're happy with the results, click **Publish** to make your app available. See [Publish](/en/cloud/use-dify/publish/README) for the full list of publishing options.
When running the web app, end users can save individual outputs for future reference.
![Save Output]()
# Version Control
Source: https://docs.dify.ai/en/cloud/use-dify/build/version-control
Track changes and manage versions in Chatflow and Workflow apps.
Only available for Chatflow and Workflow apps right now.
## How it works
**Current Draft**: Your working version. This is where you make changes. Not live for users.
**Latest Version**: The live version users see.
**Previous Versions**: Older published versions.
## Publish versions
Click **Publish** → **Publish Update** to make your draft live.
Your draft becomes the new Latest Version, and you get a fresh draft to work in.
## View versions
Click the history icon to see all versions:
Filter by:
* **All versions** or **only yours**
* **Only named versions** (skip auto-generated names)
## Manage versions
**Name a version**: Give it a proper name instead of the auto-generated one
**Edit version info**: Change the name and add release notes
**Delete old versions**: Clean up versions you don't need
You can't delete the Current Draft or Latest Version.
**Restore a version**: Load an old version back into your draft
This replaces your current draft completely. Make sure you don't have unsaved work.
Restoring a version, exporting a specific version's DSL, and running a specific published version through the [Service API](/en/api-reference/workflow-runs/run-workflow-by-id) are available on paid plans. On the Sandbox plan, apps always run the latest published version.
## Example workflow
Here's how versions work through a typical development cycle:
### 1. Start with a draft
### 2. Publish first version
### 3. Publish second version
### 4. Restore old version to draft
### 5. Publish the restored version
Complete demo:
## Tips
* Always test in draft before publishing
* Use descriptive version names for important releases
* Restore versions when you need to rollback quickly
* Keep old versions around for reference
# Workflow & Chatflow
Source: https://docs.dify.ai/en/cloud/use-dify/build/workflow-chatflow
Build agentic workflows that combine AI models, tools, and logic into reliable, repeatable processes
## Why Agentic Workflows
AI models are powerful, but on their own they can be unpredictable—they may hallucinate, miss steps, or produce inconsistent outputs. In production environments, especially for teams and enterprises where reliability matters, you need more control over how AI operates.
Agentic workflows solve this by embedding AI capabilities within a structured, repeatable process. Instead of relying on a single model to figure everything out, you design a flow that orchestrates models, tools, and logic step by step—with clear conditions, checkpoints, and fallback paths.
The AI is still doing the heavy lifting, but within boundaries you define.
## Workflow vs. Chatflow
Dify offers two app types for building agentic workflows: **Workflow** and **Chatflow**. Both are built on a shared visual canvas and node system.
To build a flow, connect nodes that each handle a specific step, such as calling a model, retrieving knowledge, running code, or branching on conditions. Most of the work is **drag, connect, and configure**—code is only needed when your logic calls for it.
Their core difference is how users interact with the app:
* A **Workflow** runs once from start to finish.
It takes an input, processes it through the flow, and returns a result. Use it for tasks like automated report generation, data processing pipelines, or batch processing.
* A **Chatflow** adds a conversation layer.
Users interact through a chat interface, and each message triggers the flow you designed before a response is generated. Use it for interactive assistants, guided Q\&A, or any conversational scenario that requires structured processing behind each reply.
Chatflows support optional features like content moderation, text to speech, and more. See [App Toolkit](/en/cloud/use-dify/build/additional-features) for details.
They also start and end with different nodes:
| | Workflow | Chatflow |
| :---------- | :-------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| Starts with | [User Input](/en/cloud/use-dify/nodes/user-input) or [Trigger](/en/cloud/use-dify/nodes/trigger/overview) | User Input |
| Ends with | [Output](/en/cloud/use-dify/nodes/output) node (optional) | [Answer](/en/cloud/use-dify/nodes/answer) node (required) |
A Trigger runs a workflow automatically: on a schedule, when a webhook fires, or from an integration event. Chatflows always start from a user message, so they don't have Triggers.
For how to compose either type, see [Orchestration Logic](/en/cloud/use-dify/build/orchestrate-node).
# Error Types
Source: https://docs.dify.ai/en/cloud/use-dify/debug/error-type
Each node type throws specific error classes that help you understand what went wrong and how to fix it.
## Node-specific errors
`CodeNodeError`
Your Python or JavaScript code threw an exception during execution
`OutputValidationError`
The data type your code returned doesn't match the output variable type you configured
`DepthLimitError`
Your code created nested data structures deeper than 5 levels
`CodeExecutionError`
The sandbox service couldn't execute your code - usually means the service is down
`VariableNotFoundError`
Your prompt template references a variable that doesn't exist in the workflow context
`InvalidContextStructureError`
You passed an array or object to the context field, which only accepts strings
`NoPromptFoundError`
The prompt field is completely empty
`ModelNotExistError`
No model is selected in the LLM node configuration
`LLMModeRequiredError`
The selected model doesn't have valid API credentials configured
`InvalidVariableTypeError`
Your prompt template isn't valid Jinja2 syntax or plain text format
`AuthorizationConfigError`
Missing or invalid authentication configuration for the API endpoint
`InvalidHttpMethodError`
HTTP method must be GET, HEAD, POST, PUT, PATCH, or DELETE
`ResponseSizeError`
API response exceeded the 10MB size limit
`FileFetchError`
Couldn't retrieve a file variable referenced in the request
`InvalidURLError`
The URL format is malformed or unreachable
`ToolParameterError`
Parameters passed to the tool don't match its expected schema
`ToolFileError`
The tool couldn't access required files
`ToolInvokeError`
The external tool API returned an error during execution
`ToolProviderNotFoundError`
The tool provider isn't installed or configured properly
## System-level errors
`InvokeConnectionError`
Network connection failed to the external service
`InvokeServerUnavailableError`
External service returned a 503 status or is temporarily down
`InvokeRateLimitError`
You've hit rate limits on the API or model provider
`QuotaExceededError`
Your usage quota has been exceeded for this service
# Run History
Source: https://docs.dify.ai/en/cloud/use-dify/debug/history-and-logs
Dify records detailed Run History every time your workflow runs. You can see what happened at both the application level and for individual nodes.
For Run History from live users after publishing, see [Logs](/en/cloud/use-dify/monitor/logs).
## Application Run History
Each workflow run creates a complete log entry. Click any entry to see three sections:
### Result
Shows the final output that users see. If the workflow failed, you'll see error messages here.
Only available for Workflow applications.
### Detail
Shows the original input, final output, and system metadata from the execution.
### Tracing
Shows exactly how your workflow executed, including which nodes ran in what order, how long each took, and where data flowed between them. This is useful for finding bottlenecks and understanding complex workflows with branches or loops.
## Node Run History
You can also check the last execution of any individual node. Click "Last run" in the node's config panel to see its most recent input, output, and timing details.
# Single Node
Source: https://docs.dify.ai/en/cloud/use-dify/debug/step-run
Test individual nodes or run through your workflow step-by-step to catch issues before publishing.
## Single node testing
You can test any node individually without running the entire workflow. Select the node, provide test input in its settings panel, and click Run to see the output.
After testing, click "Last run" to see execution details including inputs, outputs, timing, and any error messages.
Answer and End nodes don't support single node testing.
## Step-by-step execution
When you run nodes one at a time, their outputs are cached in the Variable Inspector. You can edit these cached variables to test different scenarios without re-running upstream nodes.
This is useful when you want to test how a node responds to different data without having to modify and re-run all the nodes before it. Just change the variable values in the inspector and run the node again.
## View execution history
Every node execution creates a record. Click "Last run" on any node to see its most recent execution details including what data went in, what came out, and how long it took.
# Variable Inspector
Source: https://docs.dify.ai/en/cloud/use-dify/debug/variable-inspect
The Variable Inspector shows you all the data flowing through your workflow. It captures inputs and outputs from each node after they run, so you can see what's happening and test different scenarios.
## View variables
After any node runs, its output variables appear in the inspector panel at the bottom of the screen. Click any variable to see its full content.
## Edit variables
You can edit most variable values by clicking on them. When you run downstream nodes, they'll use your edited values instead of the original ones. This lets you test different scenarios without re-running the entire workflow.
Editing variables here doesn't change the "Last run" record for the node that originally created them.
For example, if an LLM node generates SQL like `SELECT * FROM users`, you can edit it to `SELECT username FROM users` in the inspector and then re-run just the database node to see different results.
## Reset variables
Click the revert icon next to any variable to restore its original value, or click "Reset all" to clear all cached variables at once.
# Use Dify
Source: https://docs.dify.ai/en/cloud/use-dify/getting-started/introduction
Orchestrate, publish, and monitor AI applications in your workspace
Use Dify
Your workspace is where everything happens: build AI applications, ground them in your own data, then publish and monitor them.
Build workflows and chatflows on the visual canvas, plus agents, chatbots, and more.
Import documents and data so your apps can retrieve and cite them.
Ship your app as a web app, embed it in a website, or call it over the API.
Track usage, review logs, and refine answers with annotations.
Connect model providers, tools, data sources, and external services.
Ask the community or report a problem.
# Connect to External Knowledge Base
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/connect-external-knowledge-base
Integrate external knowledge sources with Dify applications through API connections to leverage custom RAG systems or third-party knowledge services
If your team maintains its own RAG system or hosts content in a third-party knowledge service like [AWS Bedrock](https://aws.amazon.com/bedrock/), you can connect these external sources to Dify instead of migrating content into Dify's built-in knowledge base.
This lets your AI applications retrieve information directly from your existing infrastructure while you retain full control over the retrieval logic and content management.
**Connecting an external knowledge base involves three steps**:
1. [Build an API service that Dify can query](#step-1-build-the-retrieval-api).
2. [Register the API endpoint in Dify](#step-2-register-an-external-knowledge-api).
3. [Connect a specific knowledge source through the registered API](#step-3-create-an-external-knowledge-base).
When your application runs, Dify sends retrieval requests to your endpoint and uses the returned chunks as context for LLM responses.
If you're connecting to LlamaCloud, install the [LlamaCloud plugin](https://marketplace.dify.ai/plugin/langgenius/llamacloud) instead of building a custom API. See the [video walkthrough](https://www.youtube.com/watch?v=FaOzKZRS-2E) for a complete setup demo.
If you're building a plugin for another knowledge service, the LlamaCloud plugin's [source code](https://github.com/langgenius/dify-official-plugins/tree/main/extensions/llamacloud) is available for reference.
Dify only has retrieval access to external knowledge bases. It cannot modify or manage your external content. You maintain the knowledge base and its retrieval logic independently.
## Step 1: Build the Retrieval API
Build an API service that implements the [External Knowledge API specification](/en/cloud/use-dify/knowledge/external-knowledge-api). Your service needs a single `POST` endpoint that accepts a search query and returns matching text chunks with similarity scores.
## Step 2: Register an External Knowledge API
An External Knowledge API stores your endpoint URL and authentication credentials. Multiple knowledge bases can share one API connection.
1. Go to **Knowledge**, click **External Knowledge API** in the upper-right corner, then click **Add an External Knowledge API**.
2. Fill in the following fields:
* **Name**: A label to distinguish this API connection from others.
* **API Endpoint**: The base URL of your external knowledge service. Dify appends `/retrieval` automatically when sending requests.
* **API Key**: The authentication credential for your service. Dify sends this as a Bearer token in the `Authorization` header.
Dify validates the connection by sending a test request to your endpoint when you save.
## Step 3: Create an External Knowledge Base
With the API registered, connect an external knowledge source to Dify. This creates a knowledge base in Dify that is linked to your external system.
1. Go to **Knowledge** and click **Connect to an External Knowledge Base**.
![Connect to External Knowledge Base]()
2. Fill in the following fields:
* **External Knowledge Name** and **Knowledge Description** (optional).
* **External Knowledge API**: Select the API connection you registered.
* **External Knowledge ID**: The identifier of the specific knowledge source within your external system, passed to your API as the `knowledge_id` field.
This is whatever ID your external service uses to distinguish between different knowledge bases. For example, a Bedrock knowledge base ARN or an ID you defined in your own system.
The **External Knowledge API** and **External Knowledge ID** cannot be changed after creation. To use a different API or knowledge source, create a new external knowledge base.
* **Retrieval Settings**:
* **Top K**: Maximum number of chunks to retrieve per query. Higher values return more results but may include less relevant content.
* **Score Threshold**: Minimum similarity score for returned chunks. Enable this to filter out low-relevance results. Use higher value for stricter relevance or lower value to include broader matches.
When disabled, all results up to the Top K limit are returned regardless of score.
Once created, the external knowledge base is available for use in your applications just like any built-in knowledge base. See [Integrate Knowledge Within Application](/en/cloud/use-dify/knowledge/integrate-knowledge-within-application) for details.
## Troubleshoot
### API Response Format Issues
If retrieval fails or returns unexpected results, verify your API response against the [External Knowledge API specification](/en/cloud/use-dify/knowledge/external-knowledge-api#response).
Common issues:
* The `metadata` field in each record must be an object (`{}`), not `null`. A `null` value causes errors in the retrieval pipeline.
* The `content` and `score` fields must be present in every record.
# Configure the Chunk Settings
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text
## What is Chunking?
Documents imported into knowledge bases are split into smaller segments called **chunks**. Think of chunking like organizing a large book into chapters and paragraphs: you can't quickly find specific information in one massive block of text, but well-organized sections make retrieval efficient.
When users ask questions, the system searches through these chunks for relevant information and provides it to the LLM as context. Without chunking, processing entire documents for every query would be slow and inefficient.
**Key Chunk Parameters**
* **Delimiter**: The character or sequence where text is split. For example, `\n\n` splits at paragraph breaks, `\n` at line breaks.
Delimiters are removed during chunking. For example, using `A` as the delimiter splits `CBACD` into `CB` and `CD`.
To avoid information loss, use non-content characters that don't naturally appear in your documents.
* **Maximum chunk length**: The maximum size of each chunk in characters. Text exceeding this limit is force-split regardless of delimiter settings.
## Choose a Chunk Mode
The chunk mode cannot be changed once the knowledge base is created. However, chunk settings like the delimiter and maximum chunk length can be adjusted at any time.
### Mode Overview
In General mode, all chunks share the same settings. Matched chunks are returned directly as retrieval results.
**Chunk Settings**
Beyond delimiter and maximum chunk length, you can also configure **Chunk overlap** to specify how many characters overlap between adjacent chunks. This helps preserve semantic connections and prevents important information from being split across chunk boundaries.
For example, with a 50-character overlap, the last 50 characters of one chunk will also appear as the first 50 characters of the next chunk.
In Parent-child mode, text is split into two tiers: smaller **child chunks** and larger **parent chunks**. When a query matches a child chunk, its entire parent chunk is returned as the retrieval result.
This solves a common retrieval dilemma: smaller chunks enable precise query matching but lack context, while larger chunks provide rich context but reduce retrieval accuracy.
Parent-child mode balances both: retrieving with precision and responding with context.
**Parent Chunk Settings**
Parent chunks can be created in **Paragraph** or **Full Doc** mode.
The document is split into multiple parent chunks based on the specified delimiter and maximum chunk length.
Suitable for lengthy documents with well-structured sections where each section provides meaningful context independently.
The entire document serves as a single parent chunk.
Suitable for small, cohesive documents where the full context is essential for understanding any specific detail.
In **Full Doc** mode:
* Only the first 10,000 tokens are processed. Content beyond this limit will be truncated.
* The parent chunk cannot be edited once created. To modify it, you must upload a new document.
**Child Chunk Settings**
Each parent chunk is further split into child chunks using their own delimiter and maximum chunk length settings.
### Quick Comparison
| Dimension | General Mode | Parent-child Mode |
| :------------------------------------------------------------------------------------------------ | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
| Chunking Strategy | Single-tier: all chunks use the same settings | Two-tier: separate settings for parent and child chunks |
| Retrieval Workflow | Matched chunks are directly returned | Child chunks are used for matching queries; parent chunks are returned to provide broader context |
| Compatible [Index Method](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods) | High Quality, Economical | High Quality only |
| Best For | Simple, self-contained content like glossaries or FAQs | Information-dense documents like technical manuals or research papers where context matters |
## Pre-process Text Before Chunking
Before splitting text into chunks, you can clean up irrelevant content to improve retrieval quality.
* **Replace consecutive spaces, newlines, and tabs**
* Three or more consecutive newlines → two newlines
* Multiple spaces → single space
* Tabs, form feeds, and special Unicode spaces → regular space
* **Remove all URLs and email addresses**
This setting is ignored in **Full Doc** mode.
## Preview Chunks
Click **Preview** to see how your content will be chunked. A limited number of chunks will be displayed for a quick review.
If the results don't perfectly match your expectations, choose the closest configuration; you can manually fine-tune chunks later. See [Manage Knowledge Content](/en/cloud/use-dify/knowledge/manage-knowledge/maintain-knowledge-documents) for details.
For multiple documents, click the file name at the top of the preview panel to switch between them.
# Upload Local Files
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/readme
Once a knowledge base is created, its data source cannot be changed later.
When creating a ready-to-use knowledge base, you can upload local files as its data source:
1. Click **Knowledge** > **Create** > **Create a ready-to-use knowledge base**.
2. Select **Import from file** as the data source, then upload your files.
Upload limits vary by plan:
| | Sandbox | Professional & Team |
| :--------------- | :------ | :------------------ |
| Files per upload | 1 | 50 |
| Size per file | 15 MB | 50 MB |
***
**For Images in Uploaded Files**
JPG, JPEG, PNG, and GIF images under 2 MB are automatically extracted as attachments to their corresponding chunks. These images can be managed independently and are returned alongside their chunks during retrieval.
URLs of extracted images remain in the chunk text, but you can safely remove these URLs to keep the text clean; this won't affect the extracted images.
If you select a multimodal embedding model (marked with a **Vision** icon) in index settings, the extracted images will also be embedded and indexed for retrieval.
Each chunk supports up to 10 image attachments; images beyond this limit will not be extracted.
The above extraction rule applies to:
* Images embedded in DOCX and XLSX files
Images embedded in other file types (e.g., PDF) can be extracted by using appropriate document extraction plugins in [knowledge pipelines](/en/cloud/use-dify/knowledge/knowledge-pipeline/readme).
* Images referenced via accessible URLs using the following Markdown syntax in any file type:
* ``
* ``
# Sync Data from Notion
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/sync-from-notion
Dify datasets support importing from Notion and setting up **synchronization** so that data updates in Notion are automatically synced to Dify.
Notion is connected through Dify's pre-configured integration. Authorize your workspace once and you're ready to import; no Notion app setup required.
### Authorization Verification
1. When creating a dataset and selecting the data source, click **Sync from Notion Content -- Bind Now** and follow the prompts to complete the authorization verification.
2. Alternatively, you can go to **Settings -- Data Sources -- Add Data Source**, click on the Notion source **Bind**, and complete the authorization verification.
### Import Notion Data
After completing the authorization verification, go to the create dataset page, click **Sync from Notion Content**, and select the authorized pages you need to import.
### Chunking and Cleaning
Next, choose a [chunking mode](/en/cloud/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text) and [indexing method](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods) for your knowledge base, then save it and wait for the automatically processing. Dify not only supports importing standard Notion pages but can also consolidate and save page attributes from database-type pages.
Images and files cannot be imported, and data from tables will be converted to text.
### Synchronize Notion Data
If your Notion content has been updated, you can sync the changes by clicking the **Sync** button for the corresponding page in the document list of your knowledge base. Syncing involves an embedding process, which will consume tokens from your embedding model.
# Import Data from Website
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/sync-from-website
The knowledge base supports crawling content from public web pages using third-party tools such as [Jina Reader](https://jina.ai/reader/) and [Firecrawl](https://www.firecrawl.dev/), parsing it into Markdown content, and importing it into the knowledge base.
[Firecrawl](https://www.firecrawl.dev/) and [Jina Reader](https://jina.ai/reader/) are both open-source web parsing tools that can convert web pages into clean Markdown format text that is easy for LLMs to recognize, while providing easy-to-use API services.
The following sections will introduce the usage methods for Firecrawl and Jina Reader respectively.
## Firecrawl
### **1. Configure Firecrawl API credentials**
Click on the avatar in the upper right corner, then go to the **DataSource** page, and click the **Configure** button next to Firecrawl.
Log in to the [Firecrawl website](https://www.firecrawl.dev/) to complete registration, get your API Key, and then enter and save it in Dify.
### 2. Scrape target webpage
On the knowledge base creation page, select **Sync from website**, choose Firecrawl as the provider, and enter the target URL to be crawled.
The configuration options include: Whether to crawl sub-pages, Page crawling limit, Page scraping max depth, Excluded paths, Include only paths, and Content extraction scope. After completing the configuration, click **Run** to preview the parsed pages.
### 3. Review import results
After importing the parsed text from the webpage, it is stored in the knowledge base documents. View the import results and click **Add URL** to continue importing new web pages.
## Jina Reader
### 1. Configure Jina Reader Credentials
Click on the avatar in the upper right corner, then go to the **DataSource** page, and click the **Configure** button next to Jina Reader.
Log in to the [Jina Reader website](https://jina.ai/reader/), complete registration, obtain the API Key, then fill it in and save.
### 2. Use Jina Reader to Crawl Web Content
On the knowledge base creation page, select **Sync from website**, choose Jina Reader as the provider, and enter the target URL to be crawled.
Configuration options include: whether to crawl subpages, maximum number of pages to crawl, and whether to use sitemap for crawling. After completing the configuration, click the **Run** button to preview the page links to be crawled.
After importing the parsed text from web pages into the knowledge base, you can review the imported results in the documents section. To add more web pages, click the **Add URL** button on the right to continue importing new pages.
After crawling is complete, the content from the web pages will be incorporated into the knowledge base.
# Create a Ready-to-Use Knowledge Base
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/introduction
To create a ready-to-use knowledge base:
1. Click **Knowledge** > **Create** > **Create a ready-to-use knowledge base**, then [upload local files](/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/readme), [sync data from Notion](/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/sync-from-notion), or [webpages](/en/cloud/use-dify/knowledge/create-knowledge/import-text-data/sync-from-website), or create an empty knowledge base.
2. [Configure the chunk settings](/en/cloud/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text) and preview the chunking results. This stage involves content preprocessing and structuring, where long texts are divided into multiple smaller chunks.
3. [Specify the index method and retrieval settings](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods). Once the knowledge base receives a user query, it searches existing documents according to preset retrieval methods and extracts highly relevant content chunks.
4. Wait for the data processing to complete.
# Specify the Index Method and Retrieval Settings
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods
After selecting the chunking mode, the next step is to define the index method for structured content.
## Select the Index Method
Similar to the search engines use efficient indexing algorithms to match search results most relevant to user queries, the selected index method directly impacts the retrieval efficiency of the LLM and the accuracy of its responses to knowledge base content.
The knowledge base offers two index methods: **High-Quality** and **Economical**, each with different retrieval setting options.
Once a knowledge base is created in the High Quality index method, it cannot switch to Economical later.
The High Quality index method uses an embedding model to convert content chunks into vector representations. This process is called embedding.
Think of these vectors as coordinates in a multi-dimensional space—the closer two points are, the more similar their meanings. This allows the system to find relevant information based on semantic similarity, not just exact keyword matches.
These vectors count toward your workspace's knowledge storage. See [Knowledge Data Storage Limit](/en/cloud/use-dify/knowledge/knowledge-storage-limit) for per-plan capacity and what happens at the limit.
To enable cross-modal retrieval—retrieving both text and images based on semantic relevance—select a multimodal embedding model (marked with a **Vision** icon). Images extracted from documents will then be embedded and indexed for retrieval.
Knowledge bases using such embedding models are labeled **Multimodal** on their cards.
![Multimodal Knowledge Base]()
The High-Quality index method supports three retrieval strategies: vector search, full-text search, or hybrid search. Learn more in [Configure the Retrieval Settings](#configure-the-retrieval-settings).
Using 10 keywords per chunk for retrieval, no tokens are consumed at the expense of reduced retrieval accuracy. For the retrieved blocks, only the inverted index method is provided to select the most relevant blocks.
If the performance of the economical indexing method does not meet your expectations, you can upgrade to the High-Quality indexing method in the Knowledge settings page.
## Configure the Retrieval Settings
Once the knowledge base receives a user query, it searches existing documents according to preset retrieval methods and extracts highly relevant content chunks. These chunks provide essential context for the LLM, ultimately affecting the accuracy and credibility of its answers.
Common retrieval methods include:
1. Semantic Retrieval based on vector similarity—where text chunks and queries are converted into vectors and matched via similarity scoring.
2. Keyword Matching using an inverted index (a standard search engine technique). Both methods are supported in Dify’s knowledge base.
Both retrieval methods are supported in Dify’s knowledge base. The specific retrieval options available depend on the chosen indexing method.
**High Quality**
In the **High-Quality** Indexing Method, Dify offers three retrieval settings: **Vector Search, Full-Text Search, and Hybrid Search**.
**Vector Search**
**Definition**: Vectorize the user’s question to generate a query vector, then compare it with the corresponding text vectors in the knowledge base to find the nearest chunks.
**Vector Search Settings**:
**Rerank Model**: Disabled by default. When enabled, a third-party Rerank model will sort the text chunks returned by Vector Search to optimize results. This helps the LLM access more precise information and improve output quality. Before enabling this option, go to **Integrations** > **Model Provider** and configure the Rerank model's API key.
If the selected embedding model is multimodal, select a multimodal rerank model (marked with a **Vision** icon) as well. Otherwise, retrieved images will be excluded from reranking and the retrieval results.
> Enabling this feature will consume tokens from the Rerank model. For more details, refer to the associated model’s pricing page.
**TopK**: Determines how many text chunks, deemed most similar to the user’s query, are retrieved. It also automatically adjusts the number of chunks based on the chosen model’s context window. The default value is **3**, and higher numbers will recall more text chunks.
**Score Threshold**: Sets the minimum similarity score required for a chunk to be retrieved. Only chunks exceeding this score are retrieved. The default value is **0.5**. Higher thresholds demand greater similarity and thus result in fewer chunks being retrieved.
> The TopK and Score configurations are only effective during the Rerank phase. Therefore, to apply either of these settings, it is necessary to add and enable a Rerank model.
**Full-Text Search**
**Definition**: Indexing all terms in the document, allowing users to query any terms and return text fragments containing those terms.
**Rerank Model**: Disabled by default. When enabled, a third-party Rerank model will sort the text chunks returned by Full-Text Search to optimize results. This helps the LLM access more precise information and improve output quality. Before enabling this option, go to **Integrations** > **Model Provider** and configure the Rerank model's API key.
If the selected embedding model is multimodal, select a multimodal rerank model (marked with a **Vision** icon) as well. Otherwise, retrieved images will be excluded from reranking and the retrieval results.
> Enabling this feature will consume tokens from the Rerank model. For more details, refer to the associated model’s pricing page.
**TopK**: Determines how many text chunks, deemed most similar to the user’s query, are retrieved. It also automatically adjusts the number of chunks based on the chosen model’s context window. The default value is **3**, and higher numbers will recall more text chunks.
**Score Threshold**: Sets the minimum similarity score required for a chunk to be retrieved. Only chunks exceeding this score are retrieved. The default value is **0.5**. Higher thresholds demand greater similarity and thus result in fewer chunks being retrieved.
> The TopK and Score configurations are only effective during the Rerank phase. Therefore, to apply either of these settings, it is necessary to add and enable a Rerank model.
**Hybrid Search**
**Definition**: This process combines full-text search and vector search, performing both simultaneously. It includes a reordering step to select the best-matching results from both search outcomes based on the user’s query.
In this mode, you can specify **"Weight settings"** without needing to configure the Rerank model API, or enable **Rerank model** for retrieval.
* **Weight Settings**
This feature enables users to set custom weights for semantic priority and keyword priority. Keyword search refers to performing a full-text search within the knowledge base, while semantic search involves vector search within the knowledge base.
* **Semantic Value of 1**
This activates only the semantic search mode. Utilizing embedding models, even if the exact terms from the query do not appear in the knowledge base, the search can delve deeper by calculating vector distances, thus returning relevant content. Additionally, when dealing with multilingual content, semantic search can capture meaning across different languages, providing more accurate cross-language search results.
* **Keyword Value of 1**
This activates only the keyword search mode. It performs a full match against the input text in the knowledge base, suitable for scenarios where the user knows the exact information or terminology. This approach consumes fewer computational resources and is ideal for quick searches within a large document knowledge base.
* **Custom Keyword and Semantic Weights**
In addition to enabling only semantic search or keyword search, we provide flexible custom weight settings. You can continuously adjust the weights of the two methods to identify the optimal weight ratio that suits your business scenario.
**Rerank Model**
Disabled by default. When enabled, a third-party Rerank model will sort the text chunks returned by Hybrid Search to optimize results. This helps the LLM access more precise information and improve output quality. Before enabling this option, go to **Integrations** > **Model Provider** and configure the Rerank model's API key.
If the selected embedding model is multimodal, select a multimodal rerank model (marked with a **Vision** icon) as well. Otherwise, retrieved images will be excluded from reranking and the retrieval results.
> Enabling this feature will consume tokens from the Rerank model. For more details, refer to the associated model’s pricing page.
The **"Weight Settings"** and **"Rerank Model"** settings support the following options:
**TopK**: Determines how many text chunks, deemed most similar to the user’s query, are retrieved. It also automatically adjusts the number of chunks based on the chosen model’s context window. The default value is **3**, and higher numbers will recall more text chunks.
**Score Threshold**: Sets the minimum similarity score required for a chunk to be retrieved. Only chunks exceeding this score are retrieved. The default value is **0.5**. Higher thresholds demand greater similarity and thus result in fewer chunks being retrieved.
**Economical**
In **Economical Indexing** mode, only the inverted index approach is available. An inverted index is a data structure designed for fast keyword retrieval within documents, commonly used in online search engines. Inverted indexing supports only the **TopK** setting.
**TopK**: Determines how many text chunks, deemed most similar to the user’s query, are retrieved. It also automatically adjusts the number of chunks based on the chosen model’s context window. The default value is **3**, and higher numbers will recall more text chunks.
### Reference
After specifying the retrieval settings, you can refer to the following documentation to review how keywords match with content chunks in different scenarios.
Learn how to test and cite your knowledge base retrieval
# External Knowledge API
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/external-knowledge-api
API specification that your external knowledge service must implement to integrate with Dify
This page defines the API contract your external knowledge service must implement for Dify to retrieve content from it. Once your API is ready, see [Connect to External Knowledge Base](/en/cloud/use-dify/knowledge/connect-external-knowledge-base) to register it in Dify.
## Authentication
Dify sends the API Key you configured as a Bearer token in every request:
```text theme={null}
Authorization: Bearer {API_KEY}
```
You define the authentication logic on your side. Dify only passes the key—it does not validate it.
## Request
```text theme={null}
POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}
```
Dify appends `/retrieval` to the endpoint URL you configured. If you registered `https://your-service.com`, Dify sends requests to `https://your-service.com/retrieval`.
### Body
| Property | Required | Type | Description |
| :------------------- | :------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledge_id` | Yes | string | The identifier of the knowledge source in your external system. This is the value you entered in the **External Knowledge ID** field when connecting. Use it to route queries to the correct knowledge source. |
| `query` | Yes | string | The user's search query. |
| `retrieval_setting` | Yes | object | Retrieval parameters. See [below](#retrieval_setting). |
| `metadata_condition` | No | object | Metadata filtering conditions. See [below](#metadata_condition). |
#### `retrieval_setting`
| Property | Required | Type | Description |
| :---------------- | :------- | :---- | :--------------------------------------------------------------------------------------------- |
| `top_k` | Yes | int | Maximum number of results to return. |
| `score_threshold` | Yes | float | Minimum similarity score (0-1). When score threshold is disabled in Dify, this value is `0.0`. |
#### `metadata_condition`
Dify passes metadata conditions to your API but does not currently provide a UI for users to configure them. This parameter is available for programmatic use only.
| Property | Required | Type | Description |
| :----------------- | :------- | :------------- | :----------------------------- |
| `logical_operator` | No | string | `and` or `or`. Default: `and`. |
| `conditions` | Yes | array\[object] | List of filter conditions. |
Each object in `conditions`:
| Property | Required | Type | Description |
| :-------------------- | :------- | :-------------------------------- | :-------------------------------------------------------- |
| `name` | Yes | string | Metadata field name to filter on. |
| `comparison_operator` | Yes | string | Comparison operator. See supported values below. |
| `value` | No | string, number, or array\[string] | Comparison value. Omit when using `empty` or `not empty`. |
| Operator | Description |
| :------------- | :--------------------------------- |
| `contains` | Contains a value |
| `not contains` | Does not contain a value |
| `start with` | Starts with a value |
| `end with` | Ends with a value |
| `is` | Equals a value |
| `is not` | Does not equal a value |
| `in` | Matches any value in a list |
| `not in` | Does not match any value in a list |
| `empty` | Is empty |
| `not empty` | Is not empty |
| `=` | Equals (numeric) |
| `≠` | Not equal (numeric) |
| `>` | Greater than |
| `<` | Less than |
| `≥` | Greater than or equal to |
| `≤` | Less than or equal to |
| `before` | Before a date |
| `after` | After a date |
### Example Request
```json theme={null}
{
"knowledge_id": "your-knowledge-id",
"query": "What is Dify?",
"retrieval_setting": {
"top_k": 3,
"score_threshold": 0.5
}
}
```
## Response
Return HTTP 200 with a JSON body containing a `records` array. If no results match the query, return an empty array: `{"records": []}`.
### `records`
| Property | Type | Description |
| :--------- | :----- | :----------------------------------------------------------------------------- |
| `content` | string | The retrieved text chunk. Dify uses this as the context passed to the LLM. |
| `score` | float | Similarity score (0–1). Used for score threshold filtering and result ranking. |
| `title` | string | Source document title. |
| `metadata` | object | Arbitrary key-value pairs preserved by Dify. |
Dify does not reject records with missing fields, but omitting `content` or `score` will produce incomplete or unranked results.
If you include `metadata` in a record, it must be an object (`{}`), not `null`. A `null` metadata value causes errors in Dify's retrieval pipeline.
### Example Response
```json theme={null}
{
"records": [
{
"content": "This is the document for external knowledge.",
"score": 0.98,
"title": "knowledge.txt",
"metadata": {
"path": "s3://dify/knowledge.txt",
"description": "dify knowledge document"
}
},
{
"content": "The Innovation Engine for GenAI Applications",
"score": 0.66,
"title": "introduce.txt",
"metadata": {}
}
]
}
```
## Error Handling
Dify checks the HTTP status code of your response. A non-200 status raises an error that surfaces to the user.
You can optionally return structured error information in JSON:
| Property | Type | Description |
| :----------- | :----- | :------------------------------------------ |
| `error_code` | int | An application-level error code you define. |
| `error_msg` | string | A human-readable error description. |
The following are suggested error codes. These are conventions, not enforced by Dify:
| Code | Suggested Usage |
| :--- | :---------------------------------- |
| 1001 | Invalid Authorization header format |
| 1002 | Authorization failed |
| 2001 | Knowledge base not found |
### Example Error Response
```json theme={null}
{
"error_code": 1002,
"error_msg": "Authorization failed. Please check your API key."
}
```
# Integrate Knowledge within Apps
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/integrate-knowledge-within-application
### Create an Application Integrated with Knowledge Base
A **"Knowledge Base"** can be used as an external information source to provide precise answers to user questions via LLM. You can associate an existing knowledge base with any [application type](/en/learn/key-concepts#dify-app) in Dify.
Taking a chat assistant as an example, the process is as follows:
1. Go to **Knowledge**, create a **ready-to-use knowledge base**, and upload your file
2. Go to **Studio**, create an application, and select **Chatbot**
3. Enter **Context**, click **Add**, and select one of the knowledge bases you created
4. Use **Metadata Filtering** to refine document search in your knowledge base
5. In **Context Settings -- Retrieval Setting**, configure the **Retrieval Setting**
6. Enable **Citation and Attribution** in **Add Features**
7. In **Debug and Preview**, input user questions related to the knowledge base for debugging
8. After debugging, click **Publish** button to make an AI application based on your own knowledge!
### Connect Knowledge and Set Retrieval Mode
In applications that utilize multiple knowledge bases, it is essential to configure the retrieval mode to enhance the precision of retrieved content. To set the retrieval mode for the knowledge bases, navigate to **Context -- Retrieval Settings -- Rerank Setting**.
#### Retrieval Setting
The retriever scans all knowledge bases linked to the application for text content relevant to the user's question. The results are then consolidated. Below is the technical flowchart for the Multi-path Retrieval mode:
This method simultaneously queries all knowledge bases connected in **"Context"**, seeking relevant text chucks across multiple knowledge bases, collecting all content that aligns with the user's question, and ultimately applying the Rerank strategy to identify the most appropriate content to respond to the user. This retrieval approach offers more comprehensive and accurate results by leveraging multiple knowledge bases simultaneously.
For instance, in application A, with three knowledge bases K1, K2, and K3. When a user send a question, multiple relevant pieces of content will be retrieved and combined from these knowledge bases. To ensure the most pertinent content is identified, the Rerank strategy is employed to find the content that best relates to the user's query, enhancing the precision and reliability of the results.
In practical Q\&A scenarios, the sources of content and retrieval methods for each knowledge base may differ. To manage the mixed content returned from retrieval, the Rerank strategy acts as a refined sorting mechanism. It ensures that the candidate content aligns well with the user's question, optimizing the ranking of results across multiple knowledge bases to identify the most suitable content, thereby improving answer quality and overall user experience.
Considering the costs associated with using Rerank and the needs of the business, the multi-path retrieval mode provides two Rerank settings:
**Weighted Score**
This setting uses internal scoring mechanisms and does not require an external Rerank model, thus **avoiding any additional processing costs**. You can select the most appropriate content matching strategy by adjusting the weight ratio sliders for semantics or keywords.
* **Semantic Value of 1**
This mode activates semantic retrieval only. By utilizing the Embedding model, the search depth can be enhanced even if the exact words from the query do not appear in the knowledge base, as it calculates vector distances to return the relevant content. Furthermore, when dealing with multilingual content, semantic retrieval can capture meanings across different languages, yielding more accurate cross-language search results.
* **Keyword Value of 1**
This mode activates keyword retrieval only. It matches the user's input text against the full text of the knowledge base, making it ideal for scenarios where the user knows the exact information or terminology. This method is resource-efficient, making it suitable for quickly retrieving information from large document repositories.
* **Custom Keyword and Semantic Weights**
In addition to enabling only semantic or keyword retrieval modes, we offer flexible custom Weight Score. You can determine the best weight ratio for your business scenario by continuously adjusting the weights of both.
**Rerank Model**
The Rerank model is an external scoring system that calculates the similarity score between the user's question and each candidate document provided, improving the results of semantic ranking and returning a list of documents sorted by similarity score from high to low.
While this method incurs some additional costs, it is more adept at handling complex knowledge base content, such as content that combines semantic queries and keyword matches, or cases involving multilingual returned content.
Dify currently supports multiple Rerank models. To use external Rerank models, you'll need to provide an API Key. Enter the API Key for the Rerank model (such as Cohere, Jina AI, etc.) on the "Model Provider" page.
**Adjustable Parameters**
* **TopK**: Determines how many text chunks, deemed most similar to the user’s query, are retrieved. It also automatically adjusts the number of chunks based on the chosen model’s context window. The default value is **3**, and higher numbers will recall more text chunks.
* **Score Threshold**: Sets the minimum similarity score required for a chunk to be retrieved. Only chunks exceeding this score are retrieved. The default value is **0.5**. Higher thresholds demand greater similarity and thus result in fewer chunks being retrieved.
### Metadata Filtering
#### Chatflow/Workflow
The **Knowledge Retrieval** node allows you to filter documents using metadata fields.
#### Steps
1. Select Filter Mode:
* **Disabled (Default)**: No metadata filtering.
* **Automatic**: Filters auto-configure from query variables in the **Knowledge Retrieval** node.
> Note: Automatic Mode requires model selection for document retrieval.
* **Manual**: Configure filters manually.
2. For Manual Mode, follow these steps:
1. Click **Conditions** to open the configuration panel.
2. Click **+Add Condition**:
* Select metadata fields within your chosen knowledge base from the dropdown list.
> Note: When multiple knowledge bases are selected, only common metadata fields are shown in the list.
* Use the search box to find specific fields.
3. Click **+Add Condition** to add more fields.
4. Configure filter conditions:
| Field Type | Operator | Description and Examples |
| ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| String | is | Exact match required. Example: `is "Published"` returns only documents marked exactly as "Published". |
| | is not | Excludes exact matches. Example: `is not "Draft"` returns all documents except those marked as "Draft". |
| | is empty | Returns documents where the field has no value. |
| | is not empty | Returns documents where the field has any value. |
| | contains | Matches partial text. Example: `contains "Report"` returns "Monthly Report", "Annual Report", etc. |
| | not contains | Excludes documents containing specified text. Example: `not contains "Draft"` returns documents without "Draft" in the field. |
| | starts with | Matches text at beginning. Example: `starts with "Doc"` returns "Doc1", "Document", etc. |
| | ends with | Matches text at end. Example: `ends with "2024"` returns "Report 2024", "Summary 2024", etc. |
| Number | = | Exact number match. Example: `= 10` returns documents marked with exactly 10. |
| | ≠ | Excludes specific number. Example: `≠ 5` returns all documents except those marked with 5. |
| | > | Greater than. Example: `> 100` returns documents with values above 100. |
| | \< | Less than. Example: `< 50` returns documents with values below 50. |
| | ≥ | Greater than or equal to. Example: `≥ 20` returns documents with values 20 or higher. |
| | ≤ | Less than or equal to. Example: `≤ 200` returns documents with values 200 or lower. |
| | is empty | Field has no value assigned. For example, `is empty` returns all documents where this field has no number assigned. |
| | is not empty | Field has a value assigned. For example, `is not empty` returns all documents where this field has a number assigned. |
| Date | is | Exact date match. Example: `is "2024-01-01"` returns documents dated January 1, 2024. |
| | before | Prior to date. Example: `before "2024-01-01"` returns documents dated before January 1, 2024. |
| | after | After date. Example: `after "2024-01-01"` returns documents dated after January 1, 2024. |
| | is empty | Returns documents with no date value. |
| | is not empty | Returns documents with any date value. |
5. Add filter values:
* **Variable**: Select from existing **Chatflow/Workflow** variables.
* **Constant**: Enter specific values.
> Time-type fields can only be filtered by constants The date picker is for time-type fields.
Filter values are case-sensitive and require exact matches. Example: a filter `starts with "App"` or `contains "App"` will match "Apple" but not "apple" or "APPLE".
6. Set logic operators:
* `AND`: Match all conditions
* `OR`: Match any condition
7. Click outside the panel to save your settings.
#### Chatbot
Access **Metadata Filtering** below **Knowledge** (bottom-left). Configuration steps are the same as in **Chatflow/Workflow**.
### View Linked Applications in the Knowledge Base
On the left side of the knowledge base, you can see all linked Apps. Hover over the circular icon to view the list of all linked apps. Click the jump button on the right to quickly browser them.
### Frequently Asked Questions
11. **How should I choose Rerank settings in multi-recall mode?**
If users know the exact information or terminology, you can use keyword search for precise matching. In that case, set **"Keywords" to 1** under Weight Settings.
If the knowledge base doesn't contain the exact terms or if a cross-lingual query is involved, we recommend setting **"Semantic" to 1** under Weight Settings.
If you are familiar with real user queries and want to adjust the ratio of semantics to keywords, they can manually tweak the ratio under **Weight Settings**.
If the knowledge base is complex, making simple semantic or keyword matches insufficient—and you need highly accurate answers and are willing to pay more—consider using a **Rerank Model** for content retrieval.
2. **What should I do if I encounter issues finding the "Weight Score" or the requirement to configure a Rerank model?**
Here's how the knowledge base retrieval method affects Multi-path Retrieval:
3. **What should I do if I cannot adjust the "Weight Score" when referencing multiple knowledge bases and an error message appears?**
This issue occurs because the embedding models used in the multiple referenced knowledge bases are inconsistent, prompting this notification to avoid conflicts in retrieval content. It is advisable to set and enable the Rerank model in the "Model Provider" or unify the retrieval settings of the knowledge bases.
4. **Why can't I find the "Weight Score" option in multi-recall mode, and only see the Rerank model?**
Please check whether your knowledge base is using the "Economical" index mode. If so, switch it to the "High Quality" index mode.
# Authorize Data Source
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/authorize-data-source
Dify supports connections to various external data sources. To ensure data security and access control, different data sources require appropriate authorization configurations. Dify provides two main authorization methods: **API Key** and **OAuth**.
## Access Data Source Authorization
In Dify, you can access data source authorization through the following two methods:
### I. Knowledge Pipeline Orchestration
When orchestrating a knowledge pipeline, select the data source node that requires authorization. Click **Connect** on the right panel.
![Knowledge Pipeline Authorization]()
### II. Settings
Click your avatar in the upper right corner and select **Settings**. Navigate to **Data Sources** and find the data source you wish to authorize.
![Settings Authorization]()
## Supported Data Source Authorization
| Data Source | API Key | OAuth |
| ------------ | ------- | ----- |
| Notion | ✅ | ✅ |
| Jina Reader | ✅ | |
| Firecrawl | ✅ | |
| Google Drive | | ✅ |
| Dropbox | | ✅ |
| OneDrive | | ✅ |
## Authorization Processes
### API Key Authorization
API Key authorization is a key-based authentication method suitable for enterprise-level services and developer tools. You need to generate API Keys from the corresponding service providers and configure them in Dify.
#### Process
1. On the **Data Source** page, navigate to the corresponding data source. Click **Configure** and then **Add API Key**.
![Add API Key]()
2. In the pop-up window, fill in the **Authorization Name** and **API Key**. Click **Save** to complete the setup.
![API Key Configuration]()
The API key will be securely encrypted. Once completed, you can start using the data source (e.g., Jina Reader) for knowledge pipeline orchestration.
![API Key Complete]()
### OAuth Authorization
OAuth is an open standard authorization protocol that allows users to authorize third-party applications to access their resources on specific service providers without exposing passwords.
#### Process
1. On the **Data Source** page, select an OAuth-supported data source. Click **Configure** and then **Add OAuth**.
![Add OAuth]()
2. Review the permission scope and click **Allow Access**.
#### OAuth Client Settings
Dify provides two OAuth client configuration methods: **Default** and **Custom**.
![OAuth Client Settings]()
The default client uses OAuth parameters that Dify pre-configures and maintains, so you can add credentials in one click without any extra setup.
The custom client lets you register your own OAuth application on the third-party platform and provide its parameters. Use it for data sources without a default client, or when you have specific security or compliance requirements.
**Process for Custom OAuth**
1. On the **Data Source** page, select an OAuth-supported data source. Click **Configure** and then the **Setting icon** on the right side of **Add OAuth**.
![Custom OAuth Settings]()
2. Choose **Custom**, enter the **Client ID** and **Client Secret**. Click **Save and Authorize** to complete the authorization.
![Custom OAuth Configuration]()
# Step 1: Create Knowledge Pipeline
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/create-knowledge-pipeline
Navigate to **Knowledge** at the top, then click **Create** > **Build a custom knowledge base**. There are three ways for you to get started.
### Build from Scratch
![Build from Scratch]()
Click Blank Knowledge Pipeline to build a custom pipeline from scratch. Choose this option when you need custom processing strategies based on specific data source and business requirements.
### Templates
Dify offers two types of templates: **Built-in Pipeline** and **Customized**. Both template cards display name of knowledge base, description, and tags (including chunk structure).
![Create Knowledge Pipeline 4 01]()
#### Built-in Pipeline
Built-in pipelines are official knowledge base templates pre-configured by Dify. These templates are optimized for common document structures and use cases. Simply click **Choose** to get started.
![Built-in Templates]()
**Types**
| Name | Chunk Structure | Index Method | Retrieval Setting | Description |
| ------------------- | ----------------- | ------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| General Mode-ECO | General | Economical | Inverted Index | Divide document content into smaller paragraphs, directly used for matching user queries and retrieval. |
| Parent-child-HQ | Parent-Child | High Quality | Hybrid Search | Adopt advanced chunking strategy, dividing document text into larger parent chunks and smaller child chunks. The parent chunks contain child chunks which ensure both retrieval precision and maintain contextual integrity. |
| Simple Q\&A | Question & Answer | High Quality | Vector Search | Convert tabular data into question-answer format, using question matching to quickly hit corresponding answer information. |
| LLM Generated Q\&A | Question & Answer | High Quality | Vector Search | Generate structured question-answer pairs with large language models based on original text paragraphs. Find relevant answer by using question matching mechanism. |
| Convert to Markdown | Parent-child | High Quality | Hybrid Search - Weighted Score | Designed for Office native file formats such as DOCX, XLSX, and PPTX, converting them to Markdown format for better information processing. ⚠️ Note: PDF files are not recommended. |
To preview the selected built-in pipeline, click **Details** on any template card. Then, check information in the popup window, including: orchestration structure, pipeline description, and chunk structure. Click **Use this Knowledge Pipeline** for orchestration.
![Template Details]()
#### Customized
![Customized Templates]()
Customized templates are user-created and published knowledge pipeline. You can choose a template to start, export the DSL, or view detailed information for any template.
![Template Actions]()
To create a knowledge base from a template, click **Choose** on the template card. You can also create knowledge base by clicking **Use this Knowledge Pipeline** when previewing a template. Click **More** to edit pipeline information, export pipeline, or delete the template.
### Import Pipeline
![Import DSL]()
Import a pipeline of a previously exported knowledge pipeline to quickly reuse existing configurations and modify them for different scenarios or requirements. Navigate to the bottom left of the page and click **Import from a DSL File**. Dify DSL is a YAML-based standard that defines AI application configurations, including model parameters, prompt design, and workflow orchestration. Similar to workflow DSL, knowledge pipeline uses the same YAML format standard to define processing workflows and configurations within a knowledge base.
What's in a knowledge pipeline DSL:
| Name | Description |
| ----------------------- | ------------------------------------------------------------------ |
| Data Sources | Local files, websites, online documents, online drive, web crawler |
| Data Processing | Document extraction, content chunking, cleaning strategies |
| Knowledge Configuration | Indexing methods, retrieval settings, storage parameters |
| Node Orchestration | Arrangement and sequence |
| User Input Form | Custom parameter fields (if configured) |
# Step 2: Orchestrate Knowledge Pipeline
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/knowledge-pipeline-orchestration
Imagine setting up a factory production line where each station (node) performs a specific task, and you connect them to assemble widgets into a final product. This is knowledge pipeline orchestration—a visual workflow builder that allows you to configure data processing sequences through a drag-and-drop interface. It provides control over document ingestion, processing, chunking, indexing, and retrieval strategies.
In this section, you'll learn about the knowledge pipeline process, understand different nodes, how to configure them, and customize your own data processing workflows to efficiently manage and optimize your knowledge base.
### Interface Status
When entering the knowledge pipeline orchestration canvas, you’ll see:
* **Tab Status**: Documents, Retrieval Test, and Settings tabs will be grayed out and unavailable at the moment
* **Essential Steps**: You must complete knowledge pipeline orchestration and publishing before uploading files
Your starting point depends on the template choice you made previously. If you chose **Blank Knowledge Pipeline**, you'll see a canvas that contains Knowledge Base node only. There'll be a note with guide next to the node that walks you through the general steps of pipeline creation.
![Blank Pipeline]()
If you selected a specific pipeline template, there'll be a ready-to-use workflow that you can use or modify on the canvas right away.
![Template Pipeline]()
## The Complete Knowledge Pipeline Process
Before we get started, let's break down the knowledge pipeline process to understand how your documents are transformed into a searchable knowledge base.
The knowledge pipeline includes these key steps:
Data Source → Data Processing (Extractor + Chunker) → Knowledge Base Node (Chunk Structure + Retrieval Setting) → User Input Field → Test & Publish
1. **Data Source**: Content from various data sources (local files, Notion, web pages, etc.)
2. **Data Processing**: Process and transform data content
* Extractor: Parse and structure document content
* Chunker: Split structured content into manageable segments
3. **Knowledge Base**: Set up chunk structure and retrieval settings
4. **User Input Field**: Define parameters that pipeline users need to input for data processing
5. **Test & Publish**: Validate and officially activate the knowledge base
***
## Step 1: Data Source
In a knowledge base, you can choose single or multiple data sources. Currently, Dify supports 4 types of data sources: **file upload, online drive, online documents, and web crawler**.
Visit the [Dify Marketplace](https://marketplace.dify.ai) for more data sources.
### File Upload
Upload local files through drag-and-drop or file selection.
**Configuration Options**
| Item | Description |
| ------------- | ------------------------------------------------------------------------------------------------- |
| File Format | Support PDF, XLSX, DOCX, etc. Users can customize their selection |
| Upload Method | Upload local files or folders through drag-and-drop or file selection. Batch upload is supported. |
**Limitations**
| Item | Description |
| ------------- | --------------------------------------------------------------- |
| File Quantity | 1 file per upload on Sandbox; up to 50 on Professional and Team |
| File Size | 15 MB per file; 50 MB on Professional and Team |
| Storage | Total document count and knowledge storage vary by plan. |
**Output Variables**
| Output Variable | Format |
| --------------- | --------------- |
| `{x} Document` | Single document |
***
### Online Document
#### Notion
Integrate with your Notion workspace to seamlessly import pages and databases, always keeping your knowledge base automatically updated.
**Configuration Options**
| Item | Option | Output Variable | Description |
| --------- | -------- | --------------- | ------------------------------------ |
| Extractor | Enabled | `{x} Content` | Structured and processed information |
| | Disabled | `{x} Document` | Original text |
***
### Web Crawler
Transform web content into formats that can be easily read by large language models. The knowledge base supports Jina Reader and Firecrawl.
#### Jina Reader
An open-source web parsing tool providing simple and easy-to-use API services, suitable for fast crawling and processing web content.
**Parameter Configuration**
| Parameter | Type | Description |
| ---------------- | -------- | ------------------------------------ |
| URL | Required | Target webpage address |
| Crawl sub-page | Optional | Whether to crawl linked pages |
| Use sitemap | Optional | Crawl by using website sitemap |
| Limit | Required | Set maximum number of pages to crawl |
| Enable Extractor | Optional | Choose data extraction method |
#### Firecrawl
An open-source web parsing tool that provides more refined crawling control options and API services. It supports deep crawling of complex website structures, recommended for batch processing and precise control.
**Parameter Configuration**
| Parameter | Type | Description |
| ------------------------- | -------- | -------------------------------------------------------------------------- |
| URL | Required | Target webpage address |
| Limit | Required | Set maximum number of pages to crawl |
| Crawl sub-page | Optional | Whether to crawl linked pages |
| Max depth | Optional | How many levels deep the crawler will traverse from the starting URL |
| Exclude paths | Optional | Specify URL patterns that should not be crawled |
| Include only paths | Optional | Crawl specified paths only |
| Extractor | Optional | Choose data processing method |
| Extract Only Main Content | Optional | Isolate and retrieve the primary, meaningful text and media from a webpage |
***
### Online Drive
Connect your online cloud storage services (e.g., Google Drive, Dropbox, OneDrive) and let Dify automatically retrieve your files. Simply select and import the documents you need for processing, without manually downloading and re-uploading files.
Need help with authorization? Please check [Authorize Data Source](/en/cloud/use-dify/knowledge/knowledge-pipeline/authorize-data-source) for detailed guidance on authorizing different data sources.
***
## Step 2: Set Up Data Processing Tools
In this stage, these tools extract, chunk, and transform the content for optimal knowledge base storage and retrieval. Think of this step like meal preparation. We clean raw materials up, chop them into bite-sized pieces, and organize everything, so the dish can be cooked up quickly when someone orders it.
To develop a custom data processing plugin that extracts multimodal data for multimodal embedding and retrieval, see [Build Tool Plugins for Multimodal Data Processing in Knowledge Pipelines](/en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool).
### Doc Processor
Documents come in different formats - PDF, XLSX, DOCX. However, LLM can't read these files directly. That's where extractors come in. They support multiple formats and handle the conversion, so your content is ready for the next step of the LLMs.
You can choose Dify's Doc Extractor to process files, or select tools based on your needs from Marketplace which offers Dify Extractor and third-party tools such as Unstructured.
Images in documents can be extracted using appropriate document processors. Extracted images are attached to their corresponding chunks, can be managed independently, and are returned alongside those chunks during retrieval.
URLs of extracted images remain in the chunk text, but you can safely remove these URLs to keep the text clean—this won't affect the extracted images.
Each chunk supports up to 10 image attachments; images beyond this limit will not be extracted.
If no images are extracted by the selected processor, Dify will automatically extract JPG, JPEG, PNG, and GIF images under 2 MB that are referenced via accessible URLs using the following Markdown syntax:
* ``
* ``
If you select a multimodal embedding model (marked with a **Vision** icon) in index settings, the extracted images will also be embedded and indexed for retrieval.
#### Doc Extractor
![Knowledge Pipeline Orchestration 4 01]()
As an information processing center, document extractor node identifies and reads files from input variables, extracts information, and finally converts them into a format that works with the next node.
For more information, please refer to the [Document Extractor](/en/cloud/use-dify/nodes/doc-extractor).
#### Dify Extractor
Dify Extractor is a built-in document parser presented by Dify. It supports multiple common file formats and is specially optimized for Doc files. It can extract and store images from documents and return image URLs.
![Dify Extractor]()
#### Unstructured
[Unstructured](https://marketplace.dify.ai/plugin/langgenius/unstructured) transforms documents into structured, machine-readable formats with highly customizable processing strategies. It offers multiple extraction strategies (auto, hi\_res, fast, OCR-only) and chunking methods (by\_title, by\_page, by\_similarity) to handle diverse document types, offering detailed element-level metadata including coordinates, confidence scores, and layout information. It's recommended for enterprise document workflows, processing of mixed file types, and cases that require precise control over document processing parameters.
Explore more tools in the [Dify Marketplace](https://marketplace.dify.ai).
***
### Chunker
Similar to human limited attention span, large language models cannot process huge amount of information simultaneously. Therefore, after information extraction, the chunker splits large document content into smaller and manageable segments (called "chunks").
Different documents require different chunking strategies. A product manual works best when split by product features, while research papers should be divided by logical sections. Dify offers 3 types of chunkers for various document types and use cases.
#### Overview of Different Chunkers
| Chunker Type | Highlights | Best for |
| -------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| General Chunker | Fixed-size chunks with customizable delimiters | Simple documents with basic structure |
| Parent-child Chunker | Dual-layer structure: precise matching + rich context | Complex documents requiring rich context preservation |
| Q\&A Processor | Processes question-answer pairs from spreadsheets | Structured Q\&A data from CSV/Excel files |
#### Common Text Pre-processing Rules
All chunkers support these text cleaning options:
| Preprocessing Option | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| Replace consecutive spaces, newlines and tabs | Clean up formatting by replacing multiple whitespace characters with single spaces |
| Remove all URLs and email addresses | Automatically detect and remove web links and email addresses from text |
#### General Chunker
Basic document chunking processing, suitable for documents with relatively simple structures. You can configure text chunking and text preprocessing rules according to the following configuration.
**Input and Output Variable**
| Type | Variable | Description |
| --------------- | ------------------ | --------------------------------------------------------------------------- |
| Input Variable | `{x} Content` | Complete document content that the chunker will split into smaller segments |
| Output Variable | `{x} Array[Chunk]` | Array of chunked content, each segment optimized for retrieval and analysis |
**Chunk Settings**
| Configuration Item | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Delimiter | Default value is `\n` (line breaks for paragraph segmentation). You can customize chunking rules following regex. The system will automatically execute segmentation when the delimiter appears in text. |
| Maximum Chunk Length | Specifies the maximum character limit within a segment. When this length is exceeded, forced segmentation will occur. |
| Chunk Overlap | When segmenting data, there is some overlap between segments. This overlap helps improve information retention and analysis accuracy, enhancing recall effectiveness. |
#### Parent-child Chunker
By using a dual-layer segmentation structure to resolve the contradiction between context and accuracy, parent-child clunker achieves the balance between precise matching and comprehensive contextual information in Retrieval Augmented Generation (RAG) systems.
**How Parent-child Chunker Works**
Child Chunks for query matching: Small, precise information segments (usually single sentences) to match user queries with high accuracy.
Parent Chunks provide rich context: Larger content blocks (paragraphs, sections, or entire documents) that contain the matching child chunks, giving the large language model (LLM) comprehensive background information.
| Type | Variable | Description |
| --------------- | ------------------------ | --------------------------------------------------------------------------- |
| Input Variable | `{x} Content` | Complete document content that the chunker will split into smaller segments |
| Output Variable | `{x} Array[ParentChunk]` | Array of parent chunks |
**Chunk Settings**
| Configuration Item | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Parent Delimiter | Set delimiter for parent chunk splitting |
| Parent Maximum Chunk Length | Set maximum character count for parent chunks |
| Child Delimiter | Set delimiter for child chunk splitting |
| Child Maximum Chunk Length | Set maximum character count for child chunks |
| Parent Mode | Choose between Paragraph (split text into paragraphs) or "Full Document" (use entire document as parent chunk) for direct retrieval |
#### Q\&A Processor
Combining extraction and chunking in one node, Q\&A Processor is specifically designed for structured Q\&A datasets from CSV and Excel files. Perfect for FAQ lists, shift schedules, and any spreadsheet data with clear question-answer pairs.
**Input and Output Variable**
| Type | Variable | Description |
| --------------- | -------------------- | ------------- |
| Input Variable | `{x} Document` | A single file |
| Output Variable | `{x} Array[QAChunk]` | QA chunk |
**Variable Configuration**
| Configuration Item | Description |
| -------------------------- | ------------------------------ |
| Column Number for Question | Set content column as question |
| Column Number for Answer | Set column answer as answer |
***
## Step 3: Configure Knowledge Base Node
Now that your documents are processed and chunked, it's time to set up how they'll be stored and retrieved. Here, you can select different indexing methods and retrieval strategies based on your specific needs.
Knowledge base node configuration includes: Input Variable, Chunk Structure, Index Method, and Retrieval Settings.
### Chunk Structure
![Chunk Structure]()
Chunk structure determines how the knowledge base organizes and indexes your document content. Choose the structure mode that best fits your document type, use case, and cost.
The knowledge base supports three chunk modes: **General Mode, Parent-child Mode, and Q\&A Mode**. If you're creating a knowledge base for the first time, we recommend choosing Parent-child Mode.
**Important Reminder**: Chunk structure cannot be modified once saved and published. Please choose carefully.
#### General Mode
Suitable for most standard document processing scenarios. It provides flexible indexing options—you can choose appropriate indexing methods based on different quality and cost requirements.
General mode supports both high-quality and economical indexing methods, as well as various retrieval settings.
#### Parent-child Mode
It provides precise matching and corresponding contextual information during retrieval, suitable for professional documents that need to maintain complete context.
Parent-child mode supports HQ (High Quality) mode only, offering child chunks for query matching and parent chunks for contextual information during retrieval.
#### Q\&A Mode
Create documents that pair questions with answers when using structured question-answer data. These documents are indexed based on the question portion, enabling the system to retrieve relevant answers based on query similarity.
Q\&A Mode supports HQ (High Quality) mode only.
### Input Variable
Input variables receive processing results from data processing nodes as the data source for knowledge base. You need to connect the output from chunker to the knowledge base as input.
The node supports different types of standard inputs based on the selected chunk structure:
* **General Mode**: x Array\[Chunk] - General chunk array
* **Parent-child Mode**: x Array\[ParentChunk] - Parent chunk array
* **Q\&A Mode**: x Array\[QAChunk] - Q\&A chunk array
### Index Method & Retrieval Settings
The index method determines how your knowledge base builds content indexes, while retrieval settings provide corresponding retrieval strategies based on the selected index method.
Think of it in this way: the index method determines how to organize your documents, while retrieval settings tell users what methods they can use to find documents.
The knowledge base provides two index methods: **High Quality** and **Economical**, each offering different retrieval setting options.
The High Quality method uses embedding models to convert chunks into numerical vectors, helping to compress and store large amounts of information more effectively. This enables the system to find semantically relevant accurate answers even when the user's question wording doesn't exactly match the document.
To enable cross-modal retrieval—retrieving both text and images based on semantic relevance—select a multimodal embedding model (marked with a **Vision** icon). Images extracted from documents will then be embedded and indexed for retrieval.
Knowledge bases using such embedding models are labeled **Multimodal** on their cards.
![Multimodal Knowledge Base]()
In the Economical method, each block uses 10 keywords for retrieval without calling embedding models, generating no costs.
For more details, see [Specify the Index Method and Retrieval Settings](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods).
| Index Method | Available Retrieval Settings | Description |
| ------------ | ---------------------------- | ----------------------------------------------------------------------- |
| High Quality | Vector Retrieval | Understand deeper meaning of queries based on semantic similarity |
| | Full-text Retrieval | Keyword-based retrieval providing comprehensive search capabilities |
| | Hybrid Retrieval | Combine both semantic and keywords |
| Economical | Inverted Index | Common search engine retrieval method, matches queries with key content |
If the selected embedding model is multimodal, select a multimodal rerank model (marked with a **Vision** icon) as well. Otherwise, retrieved images will be excluded from reranking and the retrieval results.
You can also refer to the table below for information on configuring chunk structure, index methods, parameters, and retrieval settings.
| Chunk Structure | Index Methods | Parameters | Retrieval Settings |
| ----------------- | -------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| General mode | High Quality
Economical | Embedding Model
Number of Keywords | Vector Retrieval
Full-text Retrieval
Hybrid Retrieval
Inverted Index |
| Parent-child Mode | High Quality Only | Embedding Model | Vector Retrieval
Full-text Retrieval
Hybrid Retrieval |
| Q\&A Mode | High Quality Only | Embedding Model | Vector Retrieval
Full-text Retrieval
Hybrid Retrieval |
***
## Step 4: Create User Input Form
User input forms are essential for collecting the initial information your pipeline needs to run effectively. Similar to [the User Input node](/en/cloud/use-dify/nodes/user-input) in workflow, this form gathers necessary details from users - such as files to upload, specific parameters for document processing - ensuring your pipeline has all the information it needs to deliver accurate results.
This way, you can create specialized input forms for different use scenarios, improving pipeline flexibility and usability for various data sources or document processing steps.
### Create User Input Form
There're two ways to create user input field:
1. **Pipeline Orchestration Interface**\
Click on the **Input field** to start creating and configuring input forms.\\
![]()
2. **Node Parameter Panel**\
Select a node. Then, in parameter input on the right-side panel, click + Create user input for new input items. New input items will also be collected in the Input Field. !\[Node Parameter Panel]\(/images/use-dify/knowledge/knowledge-pipeline-orchestration-10.png)
### Add User Input Fields
#### Unique Inputs for Each Entrance
![Knowledge Pipeline Orchestration 11]()
These inputs are specific to each data source and its downstream nodes. Users only need to fill out these fields when selecting the corresponding data source, such as different URLs for different data sources.
**How to create**: Click the `+` button on the right side of a data source to add fields for that specific data source. These fields can only be referenced by that data source and its subsequently connected nodes. ![These Inputs Are Specific to Each Data Source and Its Downstream Nodes]()
#### Global Inputs for All Entrances
![Knowledge Pipeline Orchestration 13]()
Global shared inputs can be referenced by all nodes. These inputs are suitable for universal processing parameters, such as delimiters, maximum chunk length, document processing configurations, etc. Users need to fill out these fields regardless of which data source they choose.
**How to create**: Click the `+` button on the right side of Global Inputs to add fields that can be referenced by any node.
### Supported Input Field Types
The knowledge pipeline supports seven types of input variables:
| Field Type | Description |
| ---------- | --------------------------------------------------------------------------------------------------- |
| Text | Short text input by knowledge base users, maximum length 256 characters |
| Paragraph | Long text input for longer character strings |
| Select | Fixed options preset by the orchestrator for users to choose from, users cannot add custom content |
| Boolean | Only true/false values |
| Number | Only accepts numerical input |
| Single | Upload a single file, supports multiple file types (documents, images, audio, and other file types) |
| File List | Batch file upload, supports multiple file types (documents, images, audio, and other file types) |
For more information about supported field types, see [User Input](/en/cloud/use-dify/nodes/user-input).
### Field Configuration Options
All input field types include: required, optional, and additional settings. You can set whether fields are required by checking the appropriate option.
| Setting | Name | Description | Example |
| ------------------------- | ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| Required Settings | Variable Name | Internal system identifier, usually named using English and underscores | `user_email` |
| | Display Name | Interface display name, usually concise and readable text | User Email |
| Type-specific Settings | | Special requirements for different field types | Text field max length 100 characters |
| Additional Settings | Default Value | Default value when user hasn't provided input | Number field defaults to 0, text field defaults to empty |
| | Placeholder | Hint text displayed when input box is empty | "Please enter your email" |
| | Tooltip | Explanatory text to guide user input, usually displayed on mouse hover | "Please enter a valid email address" |
| Special Optional Settings | | Additional setting options based on different field types | Validation of email format |
After completing configuration, click the preview button in the upper right corner to browse the form preview interface. You can drag and adjust field groupings. If an exclamation mark appears, it indicates that the reference is invalid after moving.
![Knowledge Pipeline Orchestration 15]()
***
## Step 5: Name the Knowledge Base
![Name Knowledge Base]()
By default, the knowledge base name will be "Untitled + number", permissions are set to "Only me", and the icon will be an orange book. If you import it from a DSL file, it will use the saved icon.
Edit knowledge base information by clicking **Settings** in the left panel and fill in the information below:
* **Name & Icon**\
Pick a name for your knowledge base.\
Choose an emoji, upload an image, or paste an image URL as the icon of this knowledge base.
* **Knowledge Description**\
Provide a brief description of your knowledge base. This helps the AI better understand and retrieve your data. If left empty, Dify will apply the default retrieval strategy.
* **Permissions**\
Select the appropriate access permissions from the dropdown menu.
***
## Step 6: Testing
You're almost there! This is the final step of the knowledge pipeline orchestration.
After completing the orchestration, you need to validate all the configuration first. Then, do some running tests and confirm all the settings. Finally, publish the knowledge pipeline.
### Configuration Completeness Check
Before testing, it's recommended to check the completeness of your configuration to avoid test failures due to missing configurations.
Click the checklist button in the upper right corner, and the system will display any missing parts.
![Knowledge Pipeline Orchestration 16]()
After completing all configurations, you can preview the knowledge base pipeline's operation through test runs, confirm that all settings are accurate, and then proceed with publishing.
### Test Run
![Knowledge Pipeline Orchestration 17]()
1. **Start Test**: Click the "Test Run" button in the upper right corner
2. **Import Test File**: Import files in the data source window that pops up on the right
**Important Note**: For better debugging and observation, only one file upload is allowed per test run.
3. **Fill Parameters**: After successful import, fill in corresponding parameters according to the user input form you configured earlier
4. **Start Test Run**: Click next step to start testing the entire pipeline
During testing, you can access [History Logs](/en/cloud/use-dify/monitor/logs) (track all run records with timestamps, execution status, and input/output summaries) and [Variable Inspector](/en/cloud/use-dify/debug/variable-inspect) (a dashboard at the bottom showing input/output data for each node to help identify issues and verify data flow) for efficient troubleshooting and error fixing.
![Testing Tools]()
# Step 5: Manage and Use Knowledge Base
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/manage-knowledge-base
After creating your knowledge base, continuous management and optimization will provide accurate contextual information for your applications. These are the options for follow-up maintenance.
### Knowledge Pipeline
View and modify your orchestrated pipeline nodes and configurations.
Find more information in [Manage Knowledge](/en/cloud/use-dify/knowledge/manage-knowledge/maintain-knowledge-documents).
![Knowledge Management]()
# Step 3: Publish Knowledge Pipeline
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/publish-knowledge-pipeline
After completing pipeline orchestration and debugging, click **Publish** and **Confirm** in the pop-up window.
Important reminder: Once published, the chunk structure cannot be modified.
Once it is published, you can:
**Add Documents (Go to add documents)**\
Click this option to jump to the knowledge base data source selection interface, where you can directly upload documents.
**Access API (Access API Reference)**\
Go to the API documentation page where you can get the knowledge base API calling methods and instructions.
**Publish as a Knowledge Pipeline**\
you can optionally use **Publish as a Knowledge Pipeline** to save it as a reusable template that will appear in the Customized section for future use.
**Publish as a Knowledge Pipeline** is available on Professional and Team. Sandbox accounts cannot publish pipelines as reusable templates. [Upgrade your plan](https://dify.ai/pricing) to unlock this feature.
# Build a Custom Knowledge Base
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/readme
To build a custom knowledge base, you design a knowledge pipeline. A knowledge pipeline is a document processing workflow that transforms raw data into searchable knowledge bases. As with orchestrating a workflow, you can visually combine and configure different processing nodes and tools to optimize data processing for better accuracy and relevance.
Every knowledge pipeline normally follows a structured flow through four key steps:
**Data Sources → Data Extraction → Data Processing → Knowledge Storage**
Each step serves a specific purpose: gathering content from various sources, converting it to processable text, refining it for search, and storing it in a format that enables fast, accurate retrieval.
Dify provides built-in pipeline templates that is optimized for certain use cases, or you can also create knowledge pipelines from scratch. In this session, we will go through creating options, general process of building knowledge pipelines, and how to manage it.
Start from built-in templates, blank knowledge pipeline or import existing pipeline.
Get to know how the knowledge pipeline works, orchestrate different nodes and make sure it’s ready to use.
Let's make it ready for document processing.
Add documents and process them into the searchable knowledge base.
Maintain documents, test retrieval, modify settings, and more.
# Step 4: Upload Files
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-pipeline/upload-files
After publishing knowledge pipeline, there're two ways to upload files as below:
A: Click **Go to Documents** in the success notification to add or manage documents. After entering Documents page, click **Add File** to upload.
B: Click **Go to Add Documents** to add documents.
### Upload Process
1. **Select Data Source**\
Choose from the data source types configured in your pipeline. Dify currently supports 4 types of data sources: File Upload (pdf, docx, etc.), Online Drive (Google Drive, OneDrive, etc.), Online Doc (Notion), and Web Crawler (Jina Reader, Firecrawl).
Please visit [Dify Marketplace](https://marketplace.dify.ai/) to install additional data sources.
2. **Fill in Processing Parameters and Preview**\
If you configured user input fields during pipeline orchestration, users will need to fill in the required parameters and variables at this step. After completing the form, click **Preview** to see chunking results. Click **Save & Process** to complete knowledge base creation and start data processing.
Important reminder: Chunk structure remains consistent with the pipeline configuration and won't change with user input parameters.
![Parameter Input]()
3. **Process Documents**\
Track the progress of document processing. After embedding is completed, click **Go to Document**.
![Processing Progress]()
4. **Access Documents List**\
Click **Go to Documents** to view the Documents page, where you can browse all uploaded file, processing status, etc.
![Documents List]()
# Knowledge Request Rate Limit
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-request-rate-limit
## What is Knowledge Request Rate Limit?
The knowledge request rate limit refers to the maximum number of actions that a workspace can perform in the knowledge base within one minute. These actions include creating datasets, managing documents, and running queries in apps or workflows.
## Limitations of Different Subscription Versions
Knowledge Request Rate Limit will vary by subscription level:
* **Sandbox**: 10/min
* **Professional**: 100/min
* **Team**: 1,000/min
For example, if a Sandbox user performs 10 hit tests within one minute, their workspace will be temporarily unable to perform the restricted actions during the following minute.
## Which Actions will be Limited by Knowledge Request Rate Limit when I Perform them?
When you perform the following actions, you will be limited by the frequency of Knowledge Base requests:
1. Creating empty datasets
2. Deleting datasets
3. Updating dataset settings
4. Uploading documents
5. Deleting documents
6. Updating documents
7. Disabling documents
8. Enabling documents
9. Archiving documents
10. Restoring archived documents
11. Pausing document processing
12. Resuming document processing
13. Adding segments
14. Deleting segments
15. Updating segments
16. Bulk importing segments
17. Performing hit tests
18. Querying the knowledge in apps or workflows (*Note: Multi-path recalls count as a single request.*)
# Knowledge Data Storage Limit
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/knowledge-storage-limit
What counts toward your plan's knowledge storage, what happens when you reach the limit, and how to free space
Every document indexed with the **High Quality** [index method](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods) stores its chunks as vectors (the numeric form that powers retrieval), and those vectors count toward your workspace's knowledge storage.
Each plan includes a fixed amount:
| Plan | Storage |
| :----------- | :------ |
| Sandbox | 50 MB |
| Professional | 5 GB |
| Team | 20 GB |
The workspace owner and admins can check current usage in **Settings** > **Billing** > **Knowledge Data Storage**.
## What Consumes Storage
Usage depends on how many vectors your documents produce, not on their raw file size. The more chunks a document is split into, the more vectors it produces.
In [Parent-child mode](/en/cloud/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text), every child chunk becomes a vector.
The embedding model matters too: each model outputs vectors of a fixed length, listed in the provider's documentation as its number of dimensions. For example, OpenAI's `text-embedding-3-large` uses nearly twice the storage per chunk of `text-embedding-3-small`.
As a result, a document can use several times its own file size in storage once indexed.
Documents indexed with the **Economical** method use keyword indexing instead of vectors and don't consume storage.
Usage reflects the actual storage your vectors occupy, measured periodically, so a delay is expected before the number changes after an upload or deletion.
## When an Upload Would Exceed the Limit
Every upload is checked before indexing. When the estimated total storage after the upload would exceed your plan's capacity, the document is kept in the document list but not indexed.
To bring it under the limit, split the file into smaller uploads, or raise the chunk size in the document's [chunk settings](/en/cloud/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text) so it produces fewer chunks, though larger chunks make each retrieved passage longer and less precise.
Alternatively, upgrade your plan for more capacity, then try again.
## When Storage Is Full
Once usage reaches your plan's limit, the workspace can no longer add knowledge content.
Uploading documents, adding or editing chunks, restoring archived documents, and re-indexing operations such as changing chunk settings are all blocked, including in knowledge bases that use **Economical** indexing.
To restore these actions, free space or upgrade your plan.
If a downgrade or an expired subscription leaves your data above the new plan's limit, nothing is deleted: your apps can still retrieve from these knowledge bases, but adding content stays blocked until usage fits the limit or you upgrade again.
## Free Up Storage
Delete the documents or knowledge bases you no longer need. Their vectors are removed, and the space returns to your quota.
The usage shown in **Settings** > **Billing** refreshes on a delay, so the number takes a while to drop after a deletion.
# Manage Knowledge Settings
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/manage-knowledge/introduction
Only the workspace owner, administrators, and editors can modify the knowledge base settings.
In a knowledge base, click the **Settings** icon in the left sidebar to enter its settings page.
| Settings | Description |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name & Icon | Identifies the knowledge base. |
| Description | Indicates the knowledge base's purpose and content. |
| Permissions | Defines which workspace members can access the knowledge base.Members granted access to a knowledge base have all the permissions listed in [Manage Knowledge Content](/en/cloud/use-dify/knowledge/manage-knowledge/maintain-knowledge-documents). |
| Index Method | Defines how document chunks are processed and organized for retrieval. For more details, see [Select the Index Method](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods#select-the-index-method). |
| Embedding Model | Specifies the embedding model used to convert document chunks into vector representations.Changing the embedding model will re-embed all chunks. |
| Summary Auto-Gen | Automatically generate summaries for document chunks.Once enabled, this only applies to newly added documents and chunks. For existing chunks, select the document(s) in the document list and click **Generate summary**. |
| Retrieval Settings | Defines how the knowledge base retrieves relevant content. For more details, see [Configure the Retrieval Settings](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods#configure-the-retrieval-settings). |
# Manage Knowledge Content
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/manage-knowledge/maintain-knowledge-documents
## Manage Documents
In a knowledge base, each imported item—whether a local file, a Notion page, or a web page—becomes a document.
From the document list, you can view and manage all these documents to keep your knowledge accurate, relevant, and up-to-date.
Click the knowledge base name at the top to quickly switch between knowledge bases.
![Manage Knowledge Documents]()
| Action | Description |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Add | Import a new document. |
| Modify Chunk Settings | Modify a document's chunking settings (excluding the chunk structure).Each document can have its own chunking settings, while the chunk structure is shared across the knowledge base and cannot be changed once set. |
| Delete | Permanently remove a document. **Deletion cannot be undone**. |
| Enable / Disable | Temporarily include or exclude a document from retrieval. Documents that have not been updated or retrieved for a certain period are automatically disabled to optimize performance. The inactivity period varies by subscription plan:- Sandbox: 7 days
- Professional & Team: 30 days
On Professional and Team plans, disabled documents can be re-enabled **with one click**. |
| Archive / Unarchive | Archive a document that you no longer need for retrieval but still want to keep. Archived documents are read-only and can be unarchived at any time. |
| Edit | Modify the content of a document by editing its chunks. See [Manage Chunks](#manage-chunks) for details. |
| Rename | Change the name of a document. |
## Manage Chunks
According to its chunk settings, every document is split into content chunks—the basic units for retrieval.
From the chunk list within a document, you can view and manage all its chunks to improve the retrieval efficiency and accuracy.
Click the document name in the upper-left corner to quickly switch between documents.
![Manage Knowledge Chunks]()
| Action | Description |
| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add | Add one or batch add multiple new chunks.
For documents chunked with Parent-child mode, both new parent and child chunks can be added. Adding chunks is available on Professional and Team. [Learn more](https://dify.ai/pricing). |
| Delete | Permanently remove a chunk. **Deletion cannot be undone**. |
| Enable / Disable | Temporarily include or exclude a chunk from retrieval. Disabled chunks cannot be edited. |
| Edit | Modify the content of a chunk. Edited chunks are marked **Edited**.
For knowledge bases using the Parent-child chunk mode: - When editing a parent chunk, you can choose to regenerate its child chunks or keep them unchanged.
- Editing a child chunk does not update its parent chunk.
|
| Add / Edit / Delete Keywords | Add or modify keywords (up to 10) for a chunk to improve its retrievability. Only available for knowledge bases using the Economical index method. |
| Add / Delete Image Attachments | Remove images extracted from documents or upload new ones within their corresponding chunk.
URLs of extracted images remain in the chunk text, but you can safely remove these URLs to keep the text clean—this won't affect the extracted images. Each chunk can have up to 10 image attachments, which are returned alongside it during retrieval. Images beyond this limit will not be extracted.If you select a multimodal embedding model (marked with a **Vision** icon), the extracted images will also be embedded and indexed for retrieval. |
| Add / Edit / Delete Summary | Add, modify, or remove a summary for a chunk.
Summaries are embedded and indexed for retrieval as well. When a summary matches a query, its corresponding chunk is also returned.Add identical summaries to multiple chunks to enable grouped retrieval, allowing related chunks to be returned together (subject to the Top K limit). |
## Best Practices
### Check Chunk Quality
After a document is chunked, carefully review each chunk to ensure it's semantically complete and appropriately sized for optimal retrieval accuracy and response relevance.
Common issues to watch for:
* Chunks are **too short**—may lack sufficient context, leading to semantic loss and inaccurate answers.
* Chunks are **too long**—may include irrelevant information, introducing semantic noise and lowering retrieval precision.
* Chunks are **semantically incomplete**—caused by forced chunking that cuts through sentences or paragraphs, resulting in missing or misleading content during retrieval.
### Use Child Chunks as Retrieval Hooks for Parent Chunks
For documents chunked with Parent-child mode, the system searches across child chunks but returns the parent chunks. Since editing a child chunk does not update its parent, you can treat child chunks as semantic tags or retrieval hints for their parent chunks.
To do this, rewrite child chunks into **keywords**, **summaries**, or **common user queries**. For example, if a parent chunk covers technical "LED Status Indicators", you could rephrase its child chunks as:
* *blinking light, won't turn on, red light, connection error, frozen* (keywords)
* *Guide to interpreting LED colors and troubleshooting hardware power or pairing issues* (summaries)
* *What does a solid red light mean?* (queries)
### Use Summaries to Bridge Query-Content Gaps
While high-quality indexing enables semantic search, raw chunks can still be hard to retrieve when they are too specific, noisy, or structurally complex to align well with user queries.
Summaries bridge this gap by providing a condensed semantic layer that makes the chunk's core intent explicit.
Use summaries when:
* **User queries differ from document language**: For technical documentation written formally, add summaries in the way users actually ask questions.
* **Concepts are implicit or buried in details**: Add high-level summaries that surface the core concepts and intent, so the chunk can be matched without relying on small details scattered across the text.
* **Raw text is non-textual**: When a chunk is primarily code, tables, logs, transcripts, or otherwise hard to match semantically, add descriptive summaries that clearly label what the chunk contains.
* **Related chunks should be retrieved together**: Apply identical summaries to a series of related chunks to enable grouped retrieval. This semantic glue allows multiple parts of a topic to be retrieved together, providing richer context.
The number of returned related chunks is subject to the Top K limit defined in the retrieval settings.
# Manage Document Metadata
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/metadata
## What is Metadata?
### Overview
Metadata is information that describes your data - essentially "data about data". Just as a book has a table of contents to help you understand its structure, metadata provides context about your data's content, origin, purpose, etc., making it easier for you to find and manage information in your knowledge base.
This guide aims to help you understand metadata and effectively manage your knowledge base.
### Core Concepts
* **Field**: The label of a metadata field (e.g., "author", "language").
* **Value**: The information stored in a metadata field (e.g., "Jack", "English").
* **Value Count**: The number of values contained in a metadata field, including duplicates. (e.g., "3").
* **Value Type**: The type of value a field can contain.
* Dify supports three value types:
* String: For text-based information
* Number: For numerical data
* Time: For dates/timestamps
## How to Manage My Metadata?
### Manage Metadata Fields in the Knowledge Base
You can create, modify, and delete metadata fields in the knowledge base.
> Any changes you make to metadata fields here affect your knowledge base globally.
#### Get Started with the Metadata Panel
**Access the Metadata Panel**
To access the Metadata Panel, go to **Knowledge Base** page and click **Metadata**.
**Built-in vs Custom Metadata**
|
Built-in Metadata |
Custom Metadata |
| Location |
Lower section of the Metadata panel |
Upper section of the Metadata panel |
| Activation |
Disabled by default; requires manual activation |
Add as needed |
| Generation |
System automatically extracts and generates field values |
User-defined and manually added |
| Editing |
Fields and values cannot be modified once generated |
Fields and values can be edited or deleted |
| Scope |
Applies to all existing and new documents when enabled |
Stored in metadata list; requires manual assignment to documents |
| Fields |
System-defined fields include:
- document\_name (string)
- uploader (string)
- upload\_date (time)
- last\_update\_date (time)
- source (string)
|
No default fields; all fields must be manually created |
| Value Types |
- String: For text values
- Number: For numerical values
- Time: For dates and timestamps
|
- String: For text values
- Number: For numerical values
- Time: For dates and timestamps
|
#### Create New Metadata Fields
To create a new metadata field:
1. Click **+Add Metadata** to open the **New Metadata** dialog.
2. Choose the value type.
3. Name the field.
> Naming rules: Use lowercase letters, numbers, and underscores only.
4. Click **Save** to apply changes.
#### Edit Metadata Fields
To edit a metadata field:
1. Click the edit icon next to a field to open the **Rename** dialog.
2. Enter the new name in the **Name** field.
> Note: You can only modify the field name, not the value type.
3. Click **Save** to apply changes.
> Note: Field changes update across all related documents in your knowledge base.
#### Delete Metadata Fields
To delete a metadata field, click the delete icon next to a field to delete it.
> Note: Deleting a field deletes it and all its values from all documents in your knowledge base.
### Edit Metadata
#### Bulk Edit Metadata in the Metadata Editor
You can edit metadata in bulk in the knowledge base.
**Access the Metadata Editor**
To access the Metadata Editor:
1. In the knowledge base, select documents using the checkboxes on the left.
2. Click **Metadata** in the bottom action bar to open the Metadata Editor.
**Bulk Add Metadata**
To add metadata in bulk:
1. Click **+Add Metadata** in the editor to:
* Add existing fields from the dropdown or from the search box.
* Create new fields via **+New Metadata**.
> New fields are automatically added to the knowledge base.
* Access the Metadata Panel to manage metadata fields via **Manage**.
2. *(Optional)* Enter values for new fields.
> The date picker is for time-type fields.
3. Click **Save** to apply changes.
**Bulk Update Metadata**
To update metadata in bulk:
1. In the editor:
* **Add Values**: Type directly in the field boxes.
* **Reset Values**: Click the blue dot that appears on hover.
* **Delete Values**: Clear the field or delete the **Multiple Value** card.
* **Delete fields**: Click the delete icon (fields appear struck through and grayed out).
> Note: This only deletes the field from this document, not from your knowledge base.
2. Click **Save** to apply changes.
**Set Update Scope**
Use **Apply to All Documents** to control changes:
* **Unchecked (Default)**: Updates only documents that already have the field.
* **Checked**: Adds or updates fields across all selected documents.
#### Edit Metadata on the Document Details Page
You can edit a single document's metadata on its details page.
**Access Metadata Edit Mode**
To edit a single document's metadata:
On the document details page, click **Start labeling** to begin editing.
**Add Metadata**
To add a single document's metadata fields and values:
1. Click **+Add Metadata** to:
* Create new fields via **+New Metadata**.
> New fields are automatically added to the knowledge base.
* Add existing fields from the dropdown or from the search box.
* Access the Metadata Panel via **Manage**.
2. *(Optional)* Enter values for new fields.
3. Click **Save** to apply changes.
**Edit Metadata**
To update a single document's metadata fields and values:
1. Click **Edit** in the top right to begin editing.
2. Edit metadata:
* **Update Values**: Type directly in value fields or delete it.
> Note: You can only modify the value, not the value name.
* **Delete Fields**: Click the delete icon.
> Note: This only deletes the field from this document, not from your knowledge base.
3. Click **Save** to apply changes.
## How to Filter Documents with Metadata?
See **Metadata Filtering** in *[Integrate Knowledge Base within Application](/en/cloud/use-dify/knowledge/integrate-knowledge-within-application)*.
## FAQ
* **What can I do with metadata?**
* Find information faster with smart filtering.
* Control access to sensitive content.
* Organize data more effectively.
* Automate workflows based on metadata rules.
* **Fields vs Values: What is the difference?**
| | Definition | Characteristics | Examples |
| ------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Metadata Fields in the Metadata Panel | System-defined attributes that describe document properties | Global fields accessible across all documents in the knowledge base | Author, Type, Date, etc. |
| Metadata Value on a document's detail page | Custom metadata tagged according to individual document requirements | Unique metadata values assigned based on document content and context | The "Author" field in Document A is set to "Mary" value, while in Document B it is set to "John" value. |
* **How do different delete options work?**
| Action | Steps | Impact | Outcome |
| ---------------------------------------- | ------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------- |
| Delete field in the Metadata Panel | In the Metadata Panel, click delete icon next to field | Global - affects all documents | Field and all values permanently deleted from the knowledge base |
| Delete field in the Metadata Editor | In the Metadata Editor, click delete icon next to field | Selected documents only | Field deleted from selected documents; remains in the knowledge base |
| Delete field on the document detail page | In the Edit Mode, click delete icon next to field | Current document only | Field deleted from current document; remains in the knowledge base |
# Knowledge
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/readme
## Introduction
Knowledge in Dify is a collection of your own data that can be integrated into your AI apps. It allows you to provide LLMs with domain-specific information as context, ensuring their responses are more accurate, relevant, and less prone to hallucinations.
This is made possible through Retrieval-Augmented Generation (RAG). It means that instead of relying solely on its pre-trained public data, the LLM uses your custom knowledge as an additional source of truth:
1. (Retrieval) When a user asks a question, the system first **retrieves the most relevant** information from the incorporated knowledge.
2. (Augmented) This retrieved information is then combined with the user's original query and sent to the LLM as **augmented context**.
3. (Generation) The LLM uses this context to generate a **more precise** answer.
Knowledge is stored and managed in knowledge bases. You can create multiple knowledge bases, each tailored to different domains, use cases, or data sources, and selectively integrate them into your application as needed.
## Build with Knowledge
With Dify knowledge, you can build AI apps that are grounded in your own data and domain-specific expertise. Here are some common use cases:
* **Customer support chatbots**: Build smarter support bots that provide accurate answers from your up-to-date product documentation, FAQs, and troubleshooting guides.
* **Internal knowledge portals**: Build AI-powered search and Q\&A systems for employees to quickly access company policies and procedures.
* **Content generation tools**: Build intelligent writing tools that generate reports, articles, or emails based on specific background materials.
* **Research & analysis applications**: Build applications that assist in research by retrieving and summarizing information from specific knowledge repositories like academic papers, market reports, or legal documents.
## Create Knowledge
* **[Create a ready-to-use knowledge base](/en/cloud/use-dify/knowledge/create-knowledge/introduction)**: Import data, define processing rules, and let Dify handle the rest. Fast and beginner-friendly.
* **[Build a custom knowledge base](/en/cloud/use-dify/knowledge/knowledge-pipeline/readme)**: Orchestrate more complex, flexible data processing workflows with custom steps and various integrations.
* **[Connect to an external knowledge base](/en/cloud/use-dify/knowledge/connect-external-knowledge-base)**: Sync directly from external knowledge bases via APIs to leverage existing data without migration.
## Manage & Optimize Knowledge
* **[Manage content](/en/cloud/use-dify/knowledge/manage-knowledge/maintain-knowledge-documents)**: View, add, modify, or delete documents and chunks to keep your knowledge current, accurate, and retrieval-ready.
* **[Test and validate retrieval](/en/cloud/use-dify/knowledge/test-retrieval)**: Simulate user queries to test how well your knowledge base retrieves relevant information.
* **[Enhance retrieval with metadata](/en/cloud/use-dify/knowledge/metadata)**: Add metadata to documents to enable filter-based searches and further improve retrieval precision.
* **[Adjust knowledge base settings](/en/cloud/use-dify/knowledge/manage-knowledge/introduction)**: Modify the index method, embedding model, and retrieval strategy at any time.
## Use Knowledge
**[Integrate into applications](/en/cloud/use-dify/knowledge/integrate-knowledge-within-application)**: Ground your AI app in your own knowledge.
***
**Read More**:
* [Dify v1.1.0: Filtering Knowledge Retrieval with Customized Metadata](https://dify.ai/blog/dify-v1-1-0-filtering-knowledge-retrieval-with-customized-metadata)
* [Dify v0.15.0: Introducing Parent-child Retrieval for Enhanced Knowledge](https://dify.ai/blog/introducing-parent-child-retrieval-for-enhanced-knowledge)
* [Introducing Hybrid Search and Rerank to Improve the Retrieval Accuracy of the RAG System](https://dify.ai/blog/hybrid-search-rerank-rag-improvement)
* [Dify.AI's New Dataset Feature Enhancements: Citations and Attributions](https://dify.ai/blog/difyai-new-dataset-features)
* [Text Embedding: Basic Concepts and Implementation Principles](https://dify.ai/blog/text-embedding-basic-concepts-and-implementation-principles)
* [Enhance Dify RAG with InfraNodus: Expand Your LLM's Context](https://dify.ai/blog/enhance-dify-rag-with-infranodus-expand-your-llm-s-context)
* [Dify.AI x Jina AI: Dify now Integrates Jina Embedding Model](https://dify.ai/blog/integrating-jina-embeddings-v2-dify-enhancing-rag-applications)
# Test Knowledge Retrieval
Source: https://docs.dify.ai/en/cloud/use-dify/knowledge/test-retrieval
In a knowledge base, click the **Retrieval Testing** icon in the left sidebar to enter the testing page.
Here, you can simulate user queries to test how well the knowledge base retrieves relevant information and experiment with different retrieval settings for optimal performance.
Retrieval settings adjusted here are temporary and only apply to the current test session.
For more about retrieval settings, see [Configure the Retrieval Settings](/en/cloud/use-dify/knowledge/create-knowledge/setting-indexing-methods#configure-the-retrieval-settings).
The **Records** section logs all retrieval events associated with this knowledge base, including:
* Queries tested directly on the **Retrieval Testing** page
* Retrieval requests made by any linked app—whether during test runs or in production
Test retrievals and regular retrievals share the same API endpoint.
# Dashboard
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/analysis
Monitor performance, costs, and user engagement through Dify's built-in analytics dashboard
The dashboard tracks four metrics over time to show how your application performs:
![Monitoring Dashboard]()
**Total Messages**: Conversation volume\
**Active Users**: Users with meaningful interactions (more than one exchange)\
**Average User Interactions**: Engagement depth per session\
**Token Usage**: Resource consumption and costs
Use the time selector to view trends over different periods. Click **"Tracing app performance"** to connect external observability platforms like Langfuse or LangSmith for deeper analytics.
# Annotation System
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/annotation-reply
Build a curated library of high-quality responses to improve consistency and bypass AI generation
Annotations let you create a curated library of perfect responses for specific questions. When users ask similar questions, Dify returns your pre-written answers instead of generating new responses, ensuring consistency and eliminating AI hallucinations for critical topics.
## When to Use Annotations
**Enterprise Standards**
Create definitive answers for policy questions, product information, or customer service scenarios where consistency is critical.
**Rapid Prototyping**
Quickly improve demo applications by curating high-quality responses without retraining models or complex prompt engineering.
**Quality Assurance**
Ensure certain sensitive or important questions always receive your approved responses rather than potentially variable AI-generated content.
## How Annotations Work
When annotation reply is enabled:
1. User asks a question
2. System searches existing annotations for semantic matches
3. If a match above the similarity threshold is found, returns the curated response
4. If no match, proceeds with normal AI generation
5. Track which annotations get used and how often
This creates a "fast path" for known good answers while maintaining AI flexibility for new questions.
## Set Up Annotations
**Enable in App Configuration**
Navigate to **Orchestrate → Add Features** and enable annotation reply. Configure the similarity threshold and embedding model for matching.
**Similarity Threshold**: Higher values require closer matches. Start with moderate settings and adjust based on hit rates.
**Embedding Model**: Used to vectorize questions for semantic matching. Changing the model regenerates all embeddings.
## Create Annotations
**From Conversations**
In debug mode or logs, click on AI responses and edit them into the perfect answer. Save as an annotation for future use.
**Bulk Import**
Download the template, create Q\&A pairs in the specified format, and upload for batch annotation creation.
**Manual Entry**
Add annotations directly in **Annotations** with custom questions and responses.
## Manage Annotation Quality
**Hit Tracking**
Monitor which annotations are matched, how often they're used, and the similarity scores of matches. This shows which annotations provide value.
**Continuous Refinement**
Review hit history to improve annotation coverage and accuracy. Questions that consistently miss your annotations indicate gaps in coverage.
**A/B Testing**
Compare user satisfaction rates before and after annotation implementation to measure impact.
## Annotation Analytics
**Hit Rate Analysis**
Track which annotations are frequently matched and which are never used. Remove unused annotations and expand successful patterns.
**Question Patterns**
Identify common user question types that would benefit from annotation coverage.
**Match Quality**
Review similarity scores to ensure annotations are triggering for appropriate questions without false matches.
# Integrate with Alibaba Cloud Monitor
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-aliyun
Send traces and metrics from Dify applications to Alibaba Cloud Monitor (ARMS) via OpenTelemetry
## What is Alibaba Cloud Monitor
Alibaba Cloud provides a fully managed, maintenance-free observability platform that enables one-click monitoring, tracing, and evaluation of Dify applications.
Alibaba Cloud Monitor natively supports Python/Golang/Java applications through [LoongSuite](https://github.com/alibaba/loongsuite-python-agent) agents and open-source OpenTelemetry agents. In addition to one-click monitoring of Dify LLM applications, it also supports end-to-end observability of Dify components and their upstream and downstream dependencies through non-invasive agents.
For more details, please refer to the [Cloud Monitor documentation](https://www.alibabacloud.com/help/en/cms/cloudmonitor-1-0/product-overview/what-is-cloudmonitor?spm=a3c0i.63551.2277339270.1.76c7112eeKEvSr).
## How to Configure Alibaba Cloud Monitor
### 1. Get Alibaba Cloud Endpoint and License Key
1. Log in to the [ARMS console](https://account.alibabacloud.com/login/login.htm?spm=5176.12901015-2.0.0.68d74b84XRatpU), and click **Integration Center** in the left navigation bar.
2. In the **Server-side Applications** area, click the **OpenTelemetry** card.
3. In the **OpenTelemetry** panel that appears, select **gRPC** as the export protocol, and select the connection method and region according to your actual deployment.
4. Save the **Public Endpoint** and **Authentication Token (License Key)**.
The Endpoint does not include a port number, for example `http://tracing-cn-heyuan.arms.aliyun.com`.
### 2. Configure Cloud Monitor in Dify
1. Log in to the Dify console and navigate to the application you want to monitor.
2. Open **Monitoring** in the left navigation bar.
3. Click **Tracing app performance**, then click **Configure** in the **Cloud Monitor** area.
4. In the dialog that appears, enter the **License Key** and **Endpoint** obtained in step 1, and customize the **App Name** (the application name displayed in the ARMS console), then click **Save & Enable**.
## View Monitoring Data in Alibaba Cloud Monitor
After configuration, debug or production data from applications in Dify can be monitored in Cloud Monitor.
### Method 1: Jump to ARMS Console from Dify Application
In the Dify console, select an application with tracing enabled, go to **Tracing Configuration**, and click **View** in the **Cloud Monitor** area.
### Method 2: View Directly in ARMS Console
Go to the corresponding Dify application in the **LLM Application Monitoring > Application List** page of the ARMS console.
## Access More Data
Cloud Monitor provides multi-language non-invasive agents that support accessing various components of the Dify cluster to achieve end-to-end tracing.
| Dify Component | Agent | Details |
| -------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nginx | OpenTelemetry Agent | [Use OpenTelemetry for Nginx Tracing](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx?spm=a2c63.l28256.help-menu-search-90275.d_1) |
| API | LoongSuite-Python Agent | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) |
| Sandbox | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) |
| Worker | OpenTelemetry Agent | [Submit Python Application Data via OpenTelemetry](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications?spm=a2c63.p38356.help-menu-90275.d_2_0_5_0.18ee53a4EGoGuS) |
| Plugin-Daemon | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) |
## Monitoring Data List
Cloud Monitor supports collecting data from Dify's Workflow/Chatflow/Chat/Agent applications, including execution details of workflows and workflow nodes, covering model calls, tool calls, knowledge retrieval, execution details of various process nodes, as well as metadata such as conversations and user information.
### Workflow/Chatflow Trace Information
| Workflow |
Alibaba Cloud Monitor Trace |
| workflow\_id |
Unique identifier of the Workflow |
| conversation\_id |
Conversation ID |
| workflow\_run\_id |
ID of this run |
| tenant\_id |
Tenant ID |
| elapsed\_time |
Duration of this run |
| status |
Run status |
| version |
Workflow version |
| total\_tokens |
Total tokens used in this run |
| file\_list |
List of processed files |
| triggered\_from |
Source that triggered this run |
| workflow\_run\_inputs |
Input data for this run |
| workflow\_run\_outputs |
Output data for this run |
| error |
Errors that occurred during this run |
| query |
Query used during runtime |
| workflow\_app\_log\_id |
Workflow application log ID |
| message\_id |
Associated message ID |
| start\_time |
Run start time |
| end\_time |
Run end time |
**Workflow Trace Metadata**
* workflow\_id - Unique identifier of the Workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of this run
* tenant\_id - Tenant ID
* elapsed\_time - Duration of this run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in this run
* file\_list - List of processed files
* triggered\_from - Trigger source
### Message Trace Information
| Message |
Alibaba Cloud Monitor Trace |
| message\_id |
Message ID |
| message\_data |
Message data |
| user\_session\_id |
User's session\_id |
| conversation\_model |
Conversation model |
| message\_tokens |
Number of tokens in the message |
| answer\_tokens |
Number of tokens in the answer |
| total\_tokens |
Total tokens in message and answer |
| error |
Error information |
| inputs |
Input data |
| outputs |
Output data |
| file\_list |
List of processed files |
| start\_time |
Start time |
| end\_time |
End time |
| message\_file\_data |
File data associated with the message |
| conversation\_mode |
Conversation mode |
**Message Trace Metadata**
* conversation\_id - ID of the conversation to which the message belongs
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether it is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
* message\_id - Message ID
### Dataset Retrieval Trace Information
| Dataset Retrieval |
Alibaba Cloud Monitor Trace |
| message\_id |
Message ID |
| inputs |
Input content |
| documents |
Document data |
| start\_time |
Start time |
| end\_time |
End time |
| message\_data |
Message data |
**Dataset Retrieval Trace Metadata**
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether it is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
### Tool Trace Information
| Tool |
Alibaba Cloud Monitor Trace |
| message\_id |
Message ID |
| tool\_name |
Tool name |
| start\_time |
Start time |
| end\_time |
End time |
| tool\_inputs |
Tool inputs |
| tool\_outputs |
Tool outputs |
| message\_data |
Message data |
| error |
Error information (if any) |
| inputs |
Input content of the message |
| outputs |
Answer content of the message |
| tool\_config |
Tool configuration |
| time\_cost |
Time cost |
| tool\_parameters |
Tool parameters |
| file\_url |
URL of associated file |
**Tool Trace Metadata**
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Creator role
* created\_user\_id - Creator user ID
# Integrate with Arize
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-arize
### What is Arize
[Arize AX](https://arize.com/products/ax/) is [Arize AI](https://arize.com/?utm_source=dify-docs\&utm_medium=partner\&utm_campaign=partner-docs\&utm_content=integrate-arize)'s full-featured platform for observability, online and offline evaluation, monitoring, and experimentation in LLM and agent-driven applications. Built for production teams, AI-native companies, and enterprises, it runs as a managed cloud service or an enterprise self-hosted deployment.
If you'd rather run an open-source stack for experimentation or single-container self-hosting, set up the [Phoenix integration](/en/cloud/use-dify/monitor/integrations/integrate-phoenix) instead.
Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality.
### How to Configure Arize
#### 1. Register/Login to [Arize](https://app.arize.com/auth/join)
#### 2. Get your Arize API Key
Retrieve your Arize API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it:
#### 3. Integrate Arize with Dify
Configure Arize in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key**, **Space ID** and **project name** created in Arize into the configuration and save.
Once successfully saved, you can view the monitoring status on the current page.
### Monitoring Data List
#### **Workflow/Chatflow Trace Information**
**Used to track workflows and chatflows**
| Workflow |
Arize Trace |
| workflow\_app\_log\_id/workflow\_run\_id |
id |
| user\_session\_id |
- placed in metadata |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| error |
error |
| \[workflow] |
tags |
| "conversation\_id/none for workflow" |
conversation\_id in metadata |
**Workflow Trace Info**
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
* workflow\_run\_inputs - Input data for the current run
* workflow\_run\_outputs - Output data for the current run
* error - Errors encountered during the current run
* query - Query used during the run
* workflow\_app\_log\_id - Workflow application log ID
* message\_id - Associated message ID
* start\_time - Start time of the run
* end\_time - End time of the run
* workflow node executions - Information about workflow node executions
* Metadata
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
#### **Message Trace Information**
**Used to track LLM-related conversations**
| Chat |
Arize LLM |
| message\_id |
id |
| user\_session\_id |
- placed in metadata |
| "llm" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| \["message", conversation\_mode] |
tags |
| conversation\_id |
conversation\_id in metadata |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - User session ID
* conversation\_model - Conversation mode
* message\_tokens - Number of tokens in the message
* answer\_tokens - Number of tokens in the answer
* total\_tokens - Total number of tokens in the message and answer
* error - Error information
* inputs - Input data
* outputs - Output data
* file\_list - List of processed files
* start\_time - Start time
* end\_time - End time
* message\_file\_data - File data associated with the message
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Moderation Trace Information**
**Used to track conversation moderation**
| Moderation |
Arize Tool |
| user\_id |
- placed in metadata |
| “moderation" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["moderation"] |
tags |
**Moderation Trace Info**
* message\_id - Message ID
* user\_id: User ID
* workflow\_app\_log\_id - Workflow application log ID
* inputs - Moderation input data
* message\_data - Message data
* flagged - Whether the content is flagged for attention
* action - Specific actions taken
* preset\_response - Preset response
* start\_time - Moderation start time
* end\_time - Moderation end time
* Metadata
* message\_id - Message ID
* action - Specific actions taken
* preset\_response - Preset response
#### **Suggested Question Trace Information**
**Used to track suggested questions**
| Suggested Question |
Arize LLM |
| user\_id |
- placed in metadata |
| "suggested\_question" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["suggested\_question"] |
tags |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input content
* outputs - Output content
* start\_time - Start time
* end\_time - End time
* total\_tokens - Number of tokens
* status - Message status
* error - Error information
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Status message
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Dataset Retrieval Trace Information**
**Used to track knowledge base retrieval**
| Dataset Retrieval |
Arize Retriever |
| user\_id |
- placed in metadata |
| "dataset\_retrieval" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["dataset\_retrieval"] |
tags |
| message\_id |
parent\_run\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input content
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Tool Trace Information**
**Used to track tool invocation**
| Tool |
Arize Tool |
| user\_id |
- placed in metadata |
| tool\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["tool", tool\_name] |
tags |
#### **Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error information, if any
* inputs - Inputs for the message
* outputs - Outputs of the message
* tool\_config - Tool configuration
* time\_cost - Time cost
* tool\_parameters - Tool parameters
* file\_url - URL of the associated file
* Metadata
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information, if any
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Role of the creator
* created\_user\_id - User ID of the creator
**Generate Name Trace Information**
**Used to track conversation title generation**
| Generate Name |
Arize Tool |
| user\_id |
- placed in metadata |
| "generate\_conversation\_name" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["generate\_name"] |
tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated conversation name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
# Integrate with Langfuse
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-langfuse
### What is Langfuse
Langfuse is an open-source LLM engineering platform that helps teams collaborate on debugging, analyzing, and iterating their applications.
Introduction to Langfuse: [https://langfuse.com/](https://langfuse.com/)
### How to Configure Langfuse
1. Register and log in to Langfuse on the [official website](https://langfuse.com/)
2. Create a project in Langfuse. After logging in, click **New** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring.
Edit a name for the project.
3. Create project API credentials. In the left sidebar of the project, click **Settings** to open the settings.
In Settings, click **Create API Keys** to create project API credentials.
Copy and save the **Secret Key**, **Public Key**, and **Host**.
4. Configure Langfuse in Dify. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **Secret Key, Public Key, Host** created in Langfuse into the configuration and save.
Once successfully saved, you can view the status on the current page. If it shows as started, it is being monitored.
### View Monitoring Data in Langfuse
After configuration, debugging or production data of the application in Dify can be viewed in Langfuse.
### List of monitoring data
#### Trace the information of Workflow and Chatflow
**Tracing Workflow and Chatflow**
| Workflow |
LangFuse Trace |
| workflow\_app\_log\_id/workflow\_run\_id |
id |
| user\_session\_id |
user\_id |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| Model token consumption |
usage |
| metadata |
metadata |
| error |
level |
| error |
status\_message |
| \[workflow] |
tags |
| \["message", conversation\_mode] |
session\_id |
| conversion\_id |
parent\_observation\_id |
**Workflow Trace Info**
* workflow\_id - Unique ID of Workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - Workflow ID of this runtime
* tenant\_id - Tenant ID
* elapsed\_time - Elapsed time at this runtime
* status - Runtime status
* version - Workflow version
* total\_tokens - Total token used at this runtime
* file\_list - List of files processed
* triggered\_from - Source that triggered this runtime
* workflow\_run\_inputs - Input of this workflow
* workflow\_run\_outputs - Output of this workflow
* error - Error Message
* query - Queries used at runtime
* workflow\_app\_log\_id - Workflow Application Log ID
* message\_id - Relevant Message ID
* start\_time - Start time of this runtime
* end\_time - End time of this runtime
* workflow node executions - Workflow node runtime information
* Metadata
* workflow\_id - Unique ID of Workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - Workflow ID of this runtime
* tenant\_id - Tenant ID
* elapsed\_time - Elapsed time at this runtime
* status - Operational state
* version - Workflow version
* total\_tokens - Total token used at this runtime
* file\_list - List of files processed
* triggered\_from - Source that triggered this runtime
#### Message Trace Info
**For trace llm conversation**
| Message |
LangFuse Generation/Trace |
| message\_id |
id |
| user\_session\_id |
user\_id |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| Model token consumption |
usage |
| metadata |
metadata |
| error |
level |
| error |
status\_message |
| \["message", conversation\_mode] |
tags |
| conversation\_id |
session\_id |
| conversion\_id |
parent\_observation\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - Session ID for user
* conversation\_model - Conversation model
* message\_tokens - Message tokens
* answer\_tokens - Answer Tokens
* total\_tokens - Total Tokens from Message and Answer
* error - Error Message
* inputs - Input data
* outputs - Output data
* file\_list - List of files processed
* start\_time - Start time
* end\_time - End time
* message\_file\_data - Message of relevant file data
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - Sending user's ID
* from\_account\_id - Sending account's ID
* agent\_based - Whether agent based
* workflow\_run\_id - Workflow ID of this runtime
* from\_source - Message source
* message\_id - Message ID
#### Moderation Trace Information
**Used to track conversation moderation**
| Moderation |
LangFuse Generation/Trace |
| user\_id |
user\_id |
| moderation |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| metadata |
metadata |
| \[moderation] |
tags |
| message\_id |
parent\_observation\_id |
**Message Trace Info**
* message\_id - Message ID
* user\_id - user ID
* workflow\_app\_log\_id workflow\_app\_log\_id
* inputs - Input data for review
* message\_data - Message Data
* flagged - Whether it is flagged for attention
* action - Specific actions to implement
* preset\_response - Preset response
* start\_time - Start time of review
* end\_time - End time of review
* Metadata
* message\_id - Message ID
* action - Specific actions to implement
* preset\_response - Preset response
#### Suggested Question Trace Information
**Used to track suggested questions**
| Suggested Question |
LangFuse Generation/Trace |
| user\_id |
user\_id |
| suggested\_question |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| metadata |
metadata |
| \[suggested\_question] |
tags |
| message\_id |
parent\_observation\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input data
* outputs - Output data
* start\_time - Start time
* end\_time - End time
* total\_tokens - Total tokens
* status - Message Status
* error - Error Message
* from\_account\_id - Sending account ID
* agent\_based - Whether agent based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Message status
* Metadata
* message\_id - Message ID
* ls\_provider - Model Provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - Sending user's ID
* from\_account\_id - Sending Account ID
* workflow\_run\_id - Workflow ID of this runtime
* from\_source - Message source
#### Dataset Retrieval Trace Information
**Used to track knowledge base retrieval**
| Dataset Retrieval |
LangFuse Generation/Trace |
| user\_id |
user\_id |
| dataset\_retrieval |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| metadata |
metadata |
| \[dataset\_retrieval] |
tags |
| message\_id |
parent\_observation\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input Message
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model Provider
* ls\_model\_name - Model ID
* status - Model status
* from\_end\_user\_id - Sending user's ID
* from\_account\_id - Sending account's ID
* agent\_based - Whether agent based
* workflow\_run\_id - Workflow ID of this runtime
* from\_source - Message Source
#### Tool Trace Information
**Used to track tool invocation**
| Tool |
LangFuse Generation/Trace |
| user\_id |
user\_id |
| tool\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| metadata |
metadata |
| \["tool", tool\_name] |
tags |
| message\_id |
parent\_observation\_id |
**Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool Name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error Message, if exist
* inputs - Input of Message
* outputs - Output of Message
* tool\_config - Tool config
* time\_cost - Time cost
* tool\_parameters - Tool Parameters
* file\_url - URL of relevant files
* Metadata
* message\_id - Message ID
* tool\_name - Tool Name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool config
* time\_cost - Time. cost
* error - Error Message
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Created by role
* created\_user\_id - Created user ID
#### Generate Name Trace
**Used to track conversation title generation**
| Generate Name |
LangFuse Generation/Trace |
| user\_id |
user\_id |
| generate\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
input |
| outputs |
output |
| metadata |
metadata |
| \[generate\_name] |
tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated session name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
### Langfuse Prompt Management
The [Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) (community maintained) lets you use prompts that are [managed and versioned in Langfuse](https://langfuse.com/docs/prompt-management/get-started) in your Dify applications, enhancing your LLM application development workflow. Key features include:
* **Get Prompt**: Fetch specific prompts managed in Langfuse.
* **Search Prompts**: Search for prompts in Langfuse using various filters.
* **Update Prompt**: Create new versions of prompts in Langfuse and set tags/labels.
This integration streamlines the process of managing and versioning your prompts, contributing to more efficient development and iteration cycles. You can find the plugin and installation instructions [here](https://github.com/gao-ai-com/dify-plugin-langfuse).
# Integrate with LangSmith
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-langsmith
### What is LangSmith
LangSmith is a platform for building production-grade LLM applications. It is used for developing, collaborating, testing, deploying, and monitoring LLM applications.
For more details, please refer to [LangSmith](https://www.langchain.com/langsmith).
### How to Configure LangSmith
#### 1. Register/Login to [LangSmith](https://www.langchain.com/langsmith)
#### 2. Create a Project
Create a project in LangSmith. After logging in, click **New Project** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring.
Once created, you can view all created projects in the Projects section.
#### 3. Create Project Credentials
Find the project settings **Settings** in the left sidebar.
Click **Create API Key** to create project credentials.
Select **Personal Access Token** for subsequent API authentication.
Copy and save the created API key.
#### 4. Integrate LangSmith with Dify
Configure LangSmith in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key** and **project name** created in LangSmith into the configuration and save.
The configured project name needs to match the project set in LangSmith. If the project names do not match, LangSmith will automatically create a new project during data synchronization.
Once successfully saved, you can view the monitoring status on the current page.
### View Monitoring Data in LangSmith
Once configured, the debug or production data from applications within Dify can be monitored in LangSmith.
When you switch to LangSmith, you can view detailed operation logs of Dify applications in the dashboard.
Detailed LLM operation logs through LangSmith will help you optimize the performance of your Dify application.
### Monitoring Data List
#### **Workflow/Chatflow Trace Information**
**Used to track workflows and chatflows**
| Workflow |
LangSmith Chain |
| workflow\_app\_log\_id/workflow\_run\_id |
id |
| user\_session\_id |
- placed in metadata |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
extra |
| error |
error |
| \[workflow] |
tags |
| "conversation\_id/none for workflow" |
conversation\_id in metadata |
| conversion\_id |
parent\_run\_id |
**Workflow Trace Info**
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
* workflow\_run\_inputs - Input data for the current run
* workflow\_run\_outputs - Output data for the current run
* error - Errors encountered during the current run
* query - Query used during the run
* workflow\_app\_log\_id - Workflow application log ID
* message\_id - Associated message ID
* start\_time - Start time of the run
* end\_time - End time of the run
* workflow node executions - Information about workflow node executions
* Metadata
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
#### **Message Trace Information**
**Used to track LLM-related conversations**
| Chat |
LangSmith LLM |
| message\_id |
id |
| user\_session\_id |
- placed in metadata |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
extra |
| error |
error |
| \["message", conversation\_mode] |
tags |
| conversation\_id |
conversation\_id in metadata |
| conversion\_id |
parent\_run\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - User session ID
* conversation\_model - Conversation mode
* message\_tokens - Number of tokens in the message
* answer\_tokens - Number of tokens in the answer
* total\_tokens - Total number of tokens in the message and answer
* error - Error information
* inputs - Input data
* outputs - Output data
* file\_list - List of processed files
* start\_time - Start time
* end\_time - End time
* message\_file\_data - File data associated with the message
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Moderation Trace Information**
**Used to track conversation moderation**
| Moderation |
LangSmith Tool |
| user\_id |
- placed in metadata |
| “moderation" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
extra |
| \[moderation] |
tags |
| message\_id |
parent\_run\_id |
**Moderation Trace Info**
* message\_id - Message ID
* user\_id: User ID
* workflow\_app\_log\_id - Workflow application log ID
* inputs - Moderation input data
* message\_data - Message data
* flagged - Whether the content is flagged for attention
* action - Specific actions taken
* preset\_response - Preset response
* start\_time - Moderation start time
* end\_time - Moderation end time
* Metadata
* message\_id - Message ID
* action - Specific actions taken
* preset\_response - Preset response
#### **Suggested Question Trace Information**
**Used to track suggested questions**
| Suggested Question |
LangSmith LLM |
| user\_id |
- placed in metadata |
| suggested\_question |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
extra |
| \[suggested\_question] |
tags |
| message\_id |
parent\_run\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input content
* outputs - Output content
* start\_time - Start time
* end\_time - End time
* total\_tokens - Number of tokens
* status - Message status
* error - Error information
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Status message
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Dataset Retrieval Trace Information**
**Used to track knowledge base retrieval**
| Dataset Retrieval |
LangSmith Retriever |
| user\_id |
- placed in metadata |
| dataset\_retrieval |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
extra |
| \[dataset\_retrieval] |
tags |
| message\_id |
parent\_run\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input content
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Tool Trace Information**
**Used to track tool invocation**
| Tool |
LangSmith Tool |
| user\_id |
- placed in metadata |
| tool\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
extra |
| \["tool", tool\_name] |
tags |
| message\_id |
parent\_run\_id |
#### **Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error information, if any
* inputs - Inputs for the message
* outputs - Outputs of the message
* tool\_config - Tool configuration
* time\_cost - Time cost
* tool\_parameters - Tool parameters
* file\_url - URL of the associated file
* Metadata
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information, if any
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Role of the creator
* created\_user\_id - User ID of the creator
**Generate Name Trace Information**
**Used to track conversation title generation**
| Generate Name |
LangSmith Tool |
| user\_id |
- placed in metadata |
| generate\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
extra |
| \[generate\_name] |
tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated conversation name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
# Integrate with Opik
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-opik
### What is Opik
Opik is an open-source platform designed for evaluating, testing, and monitoring large language model (LLM) applications. Developed by Comet, it aims to facilitate more intuitive collaboration, testing, and monitoring of LLM-based applications.
For more details, please refer to [Opik](https://www.comet.com/site/products/opik/).
***
### How to Configure Opik
#### 1. Register/Login to [Opik](https://www.comet.com/signup?from=llm)
#### 2. Get your Opik API Key
Retrieve your Opik API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it:
#### 3. Integrate Opik with Dify
Configure Opik in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key** and **project name** created in Opik into the configuration and save.
Once successfully saved, you can view the monitoring status on the current page.
### View Monitoring Data in Opik
Once configured, you can debug or use the Dify application as usual. All usage history can be monitored in Opik.
When you switch to Opik, you can view detailed operation logs of Dify applications in the dashboard.
Detailed LLM operation logs through Opik will help you optimize the performance of your Dify application.
### Monitoring Data List
#### **Workflow/Chatflow Trace Information**
**Used to track workflows and chatflows**
| Workflow |
Opik Trace |
| workflow\_app\_log\_id/workflow\_run\_id |
id |
| user\_session\_id |
- placed in metadata |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| error |
error |
| \[workflow] |
tags |
| "conversation\_id/none for workflow" |
conversation\_id in metadata |
**Workflow Trace Info**
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
* workflow\_run\_inputs - Input data for the current run
* workflow\_run\_outputs - Output data for the current run
* error - Errors encountered during the current run
* query - Query used during the run
* workflow\_app\_log\_id - Workflow application log ID
* message\_id - Associated message ID
* start\_time - Start time of the run
* end\_time - End time of the run
* workflow node executions - Information about workflow node executions
* Metadata
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
#### **Message Trace Information**
**Used to track LLM-related conversations**
| Chat |
Opik LLM |
| message\_id |
id |
| user\_session\_id |
- placed in metadata |
| "llm" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| \["message", conversation\_mode] |
tags |
| conversation\_id |
conversation\_id in metadata |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - User session ID
* conversation\_model - Conversation mode
* message\_tokens - Number of tokens in the message
* answer\_tokens - Number of tokens in the answer
* total\_tokens - Total number of tokens in the message and answer
* error - Error information
* inputs - Input data
* outputs - Output data
* file\_list - List of processed files
* start\_time - Start time
* end\_time - End time
* message\_file\_data - File data associated with the message
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Moderation Trace Information**
**Used to track conversation moderation**
| Moderation |
Opik Tool |
| user\_id |
- placed in metadata |
| “moderation" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["moderation"] |
tags |
**Moderation Trace Info**
* message\_id - Message ID
* user\_id: User ID
* workflow\_app\_log\_id - Workflow application log ID
* inputs - Moderation input data
* message\_data - Message data
* flagged - Whether the content is flagged for attention
* action - Specific actions taken
* preset\_response - Preset response
* start\_time - Moderation start time
* end\_time - Moderation end time
* Metadata
* message\_id - Message ID
* action - Specific actions taken
* preset\_response - Preset response
#### **Suggested Question Trace Information**
**Used to track suggested questions**
| Suggested Question |
Opik LLM |
| user\_id |
- placed in metadata |
| "suggested\_question" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["suggested\_question"] |
tags |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input content
* outputs - Output content
* start\_time - Start time
* end\_time - End time
* total\_tokens - Number of tokens
* status - Message status
* error - Error information
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Status message
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Dataset Retrieval Trace Information**
**Used to track knowledge base retrieval**
| Dataset Retrieval |
Opik Retriever |
| user\_id |
- placed in metadata |
| "dataset\_retrieval" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["dataset\_retrieval"] |
tags |
| message\_id |
parent\_run\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input content
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Tool Trace Information**
**Used to track tool invocation**
| Tool |
Opik Tool |
| user\_id |
- placed in metadata |
| tool\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["tool", tool\_name] |
tags |
#### **Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error information, if any
* inputs - Inputs for the message
* outputs - Outputs of the message
* tool\_config - Tool configuration
* time\_cost - Time cost
* tool\_parameters - Tool parameters
* file\_url - URL of the associated file
* Metadata
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information, if any
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Role of the creator
* created\_user\_id - User ID of the creator
**Generate Name Trace Information**
**Used to track conversation title generation**
| Generate Name |
Opik Tool |
| user\_id |
- placed in metadata |
| "generate\_conversation\_name" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["generate\_name"] |
tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated conversation name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
# Integrate with Phoenix
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-phoenix
### What is Phoenix
[Arize Phoenix](https://arize.com/phoenix/) is the open-source, OpenTelemetry-based platform from [Arize AI](https://arize.com/?utm_source=dify-docs\&utm_medium=partner\&utm_campaign=partner-docs\&utm_content=integrate-phoenix) for observability, evaluation, prompt engineering, and experimentation with LLM workflows and agents.
Use Arize's hosted [Phoenix Cloud](#how-to-configure-phoenix-cloud), or self-host Phoenix on your own infrastructure (a single container is enough to start). Dify sends traces server-side, so a self-hosted endpoint must be reachable from the internet.
If you need the full-featured platform built for production teams, AI-native companies, and enterprises, set up [Arize AX](https://arize.com/products/ax/) through the [Arize integration](/en/cloud/use-dify/monitor/integrations/integrate-arize) instead.
Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality.
### How to Configure Phoenix
#### 1. Register/Login to [Phoenix](https://app.arize.com/auth/phoenix/signup)
#### 2. Get your Phoenix API Key
Retrieve your Phoenix API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it:
#### 3. Integrate Phoenix with Dify
Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key** and **project name** created in Phoenix into the configuration and save.
Once successfully saved, you can view the monitoring status on the current page.
### How to Configure Phoenix Cloud
#### 1. Register/Login to [Phoenix Cloud](https://app.arize.com/auth/phoenix/signup)
#### 2. Create your Phoenix Space
You can create your Phoenix Space from the user menu at the top-right. Click on **Create Space**, then provide a unique URL identifier for your space:
Once successfully saved, you can view the space status on the overview page.
#### 3. Create your Phoenix API Key
After launching your space, you can create your Phoenix API Key from the **Settings** option in the user menu at the bottom-left. Click on **System Key**, then provide a name for your Phoenix API Key:
#### 4. Integrate Phoenix Cloud with Dify
Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key** and **project name** along with **Space Hostname** created in Phoenix Cloud into the configuration and save.
Once successfully saved, you can view the monitoring status on the current page.
### Monitoring Data List
#### **Workflow/Chatflow Trace Information**
**Used to track workflows and chatflows**
| Workflow |
Phoenix Trace |
| workflow\_app\_log\_id/workflow\_run\_id |
id |
| user\_session\_id |
- placed in metadata |
| name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| error |
error |
| \[workflow] |
tags |
| "conversation\_id/none for workflow" |
conversation\_id in metadata |
**Workflow Trace Info**
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
* workflow\_run\_inputs - Input data for the current run
* workflow\_run\_outputs - Output data for the current run
* error - Errors encountered during the current run
* query - Query used during the run
* workflow\_app\_log\_id - Workflow application log ID
* message\_id - Associated message ID
* start\_time - Start time of the run
* end\_time - End time of the run
* workflow node executions - Information about workflow node executions
* Metadata
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
#### **Message Trace Information**
**Used to track LLM-related conversations**
| Chat |
Phoenix LLM |
| message\_id |
id |
| user\_session\_id |
- placed in metadata |
| "llm" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| Model token consumption |
usage\_metadata |
| metadata |
metadata |
| \["message", conversation\_mode] |
tags |
| conversation\_id |
conversation\_id in metadata |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - User session ID
* conversation\_model - Conversation mode
* message\_tokens - Number of tokens in the message
* answer\_tokens - Number of tokens in the answer
* total\_tokens - Total number of tokens in the message and answer
* error - Error information
* inputs - Input data
* outputs - Output data
* file\_list - List of processed files
* start\_time - Start time
* end\_time - End time
* message\_file\_data - File data associated with the message
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Moderation Trace Information**
**Used to track conversation moderation**
| Moderation |
Phoenix Tool |
| user\_id |
- placed in metadata |
| “moderation" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["moderation"] |
tags |
**Moderation Trace Info**
* message\_id - Message ID
* user\_id: User ID
* workflow\_app\_log\_id - Workflow application log ID
* inputs - Moderation input data
* message\_data - Message data
* flagged - Whether the content is flagged for attention
* action - Specific actions taken
* preset\_response - Preset response
* start\_time - Moderation start time
* end\_time - Moderation end time
* Metadata
* message\_id - Message ID
* action - Specific actions taken
* preset\_response - Preset response
#### **Suggested Question Trace Information**
**Used to track suggested questions**
| Suggested Question |
Phoenix LLM |
| user\_id |
- placed in metadata |
| "suggested\_question" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["suggested\_question"] |
tags |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input content
* outputs - Output content
* start\_time - Start time
* end\_time - End time
* total\_tokens - Number of tokens
* status - Message status
* error - Error information
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Status message
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Dataset Retrieval Trace Information**
**Used to track knowledge base retrieval**
| Dataset Retrieval |
Phoenix Retriever |
| user\_id |
- placed in metadata |
| "dataset\_retrieval" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["dataset\_retrieval"] |
tags |
| message\_id |
parent\_run\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input content
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Tool Trace Information**
**Used to track tool invocation**
| Tool |
Phoenix Tool |
| user\_id |
- placed in metadata |
| tool\_name |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["tool", tool\_name] |
tags |
#### **Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error information, if any
* inputs - Inputs for the message
* outputs - Outputs of the message
* tool\_config - Tool configuration
* time\_cost - Time cost
* tool\_parameters - Tool parameters
* file\_url - URL of the associated file
* Metadata
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information, if any
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Role of the creator
* created\_user\_id - User ID of the creator
**Generate Name Trace Information**
**Used to track conversation title generation**
| Generate Name |
Phoenix Tool |
| user\_id |
- placed in metadata |
| "generate\_conversation\_name" |
name |
| start\_time |
start\_time |
| end\_time |
end\_time |
| inputs |
inputs |
| outputs |
outputs |
| metadata |
metadata |
| \["generate\_name"] |
tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated conversation name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
# Integrate with W&B Weave
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/integrations/integrate-weave
Send traces from Dify applications to W&B Weave for LLM observability
### What is W\&B Weave
Weights & Biases (W\&B) Weave is a framework for tracking, experimenting with, evaluating, deploying, and improving LLM-based applications. Designed for flexibility and scalability, Weave supports every stage of your LLM application development workflow.
For more details, please refer to [Weave](https://docs.wandb.ai/weave).
### How to Configure Weave
#### 1. Register/Login
Register/Login to [W\&B Weave](https://wandb.ai/signup) and get your API key. Then, copy your API key from [here](https://wandb.ai/authorize).
#### 2. Integrate W\&B Weave with Dify
Configure Weave in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page.
After clicking configure, paste the **API Key** and **project name**, also specify the **W\&B entity**(optionally, default is your username) into the configuration and save.
Once successfully saved, you can view the monitoring status on the current page.
### View Monitoring Data in Weave
Once configured, the debug or production data from applications within Dify can be monitored in Weave.
When you switch to Weave, you can view detailed operation logs of Dify applications in the dashboard.
Detailed LLM operation logs through Weave will help you optimize the performance of your Dify application.
### Monitoring Data List
#### **Workflow/Chatflow Trace Information**
**Used to track workflows and chatflows**
| Workflow | Weave Trace |
| ---------------------------------------- | ---------------------------- |
| workflow\_app\_log\_id/workflow\_run\_id | id |
| user\_session\_id | placed in metadata |
| workflow\_\{id} | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| Model token consumption | usage\_metadata |
| metadata | extra |
| error | error |
| workflow | tags |
| "conversation\_id/none for workflow" | conversation\_id in metadata |
| conversion\_id | parent\_run\_id |
**Workflow Trace Info**
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
* workflow\_run\_inputs - Input data for the current run
* workflow\_run\_outputs - Output data for the current run
* error - Errors encountered during the current run
* query - Query used during the run
* workflow\_app\_log\_id - Workflow application log ID
* message\_id - Associated message ID
* start\_time - Start time of the run
* end\_time - End time of the run
* workflow node executions - Information about workflow node executions
* Metadata
* workflow\_id - Unique identifier of the workflow
* conversation\_id - Conversation ID
* workflow\_run\_id - ID of the current run
* tenant\_id - Tenant ID
* elapsed\_time - Time taken for the current run
* status - Run status
* version - Workflow version
* total\_tokens - Total tokens used in the current run
* file\_list - List of processed files
* triggered\_from - Source that triggered the current run
#### **Message Trace Information**
**Used to track LLM-related conversations**
| Chat | Weave Trace |
| ----------------------------- | ---------------------------- |
| message\_id | id |
| user\_session\_id | placed in metadata |
| "message\_\{id}" | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| Model token consumption | usage\_metadata |
| metadata | extra |
| error | error |
| "message", conversation\_mode | tags |
| conversation\_id | conversation\_id in metadata |
| conversion\_id | parent\_run\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* user\_session\_id - User session ID
* conversation\_model - Conversation mode
* message\_tokens - Number of tokens in the message
* answer\_tokens - Number of tokens in the answer
* total\_tokens - Total number of tokens in the message and answer
* error - Error information
* inputs - Input data
* outputs - Output data
* file\_list - List of processed files
* start\_time - Start time
* end\_time - End time
* message\_file\_data - File data associated with the message
* conversation\_mode - Conversation mode
* Metadata
* conversation\_id - Conversation ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Moderation Trace Information**
**Used to track conversation moderation**
| Moderation | Weave Trace |
| ------------ | ------------------ |
| user\_id | placed in metadata |
| “moderation" | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| metadata | extra |
| moderation | tags |
| message\_id | parent\_run\_id |
**Moderation Trace Info**
* message\_id - Message ID
* user\_id: User ID
* workflow\_app\_log\_id - Workflow application log ID
* inputs - Moderation input data
* message\_data - Message data
* flagged - Whether the content is flagged for attention
* action - Specific actions taken
* preset\_response - Preset response
* start\_time - Moderation start time
* end\_time - Moderation end time
* Metadata
* message\_id - Message ID
* action - Specific actions taken
* preset\_response - Preset response
#### **Suggested Question Trace Information**
**Used to track suggested questions**
| Suggested Question | Weave Trace |
| ------------------- | ------------------ |
| user\_id | placed in metadata |
| suggested\_question | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| metadata | extra |
| suggested\_question | tags |
| message\_id | parent\_run\_id |
**Message Trace Info**
* message\_id - Message ID
* message\_data - Message data
* inputs - Input content
* outputs - Output content
* start\_time - Start time
* end\_time - End time
* total\_tokens - Number of tokens
* status - Message status
* error - Error information
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* from\_source - Message source
* model\_provider - Model provider
* model\_id - Model ID
* suggested\_question - Suggested question
* level - Status level
* status\_message - Status message
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Dataset Retrieval Trace Information**
**Used to track knowledge base retrieval**
| Dataset Retrieval | Weave Trace |
| ------------------ | ------------------ |
| user\_id | placed in metadata |
| dataset\_retrieval | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| metadata | extra |
| dataset\_retrieval | tags |
| message\_id | parent\_run\_id |
**Dataset Retrieval Trace Info**
* message\_id - Message ID
* inputs - Input content
* documents - Document data
* start\_time - Start time
* end\_time - End time
* message\_data - Message data
* Metadata
* message\_id - Message ID
* ls\_provider - Model provider
* ls\_model\_name - Model ID
* status - Message status
* from\_end\_user\_id - ID of the sending user
* from\_account\_id - ID of the sending account
* agent\_based - Whether the message is agent-based
* workflow\_run\_id - Workflow run ID
* from\_source - Message source
#### **Tool Trace Information**
**Used to track tool invocation**
| Tool | Weave Trace |
| ------------------ | ------------------ |
| user\_id | placed in metadata |
| tool\_name | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| metadata | extra |
| "tool", tool\_name | tags |
| message\_id | parent\_run\_id |
#### **Tool Trace Info**
* message\_id - Message ID
* tool\_name - Tool name
* start\_time - Start time
* end\_time - End time
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* message\_data - Message data
* error - Error information, if any
* inputs - Inputs for the message
* outputs - Outputs of the message
* tool\_config - Tool configuration
* time\_cost - Time cost
* tool\_parameters - Tool parameters
* file\_url - URL of the associated file
* Metadata
* message\_id - Message ID
* tool\_name - Tool name
* tool\_inputs - Tool inputs
* tool\_outputs - Tool outputs
* tool\_config - Tool configuration
* time\_cost - Time cost
* error - Error information, if any
* tool\_parameters - Tool parameters
* message\_file\_id - Message file ID
* created\_by\_role - Role of the creator
* created\_user\_id - User ID of the creator
**Generate Name Trace Information**
**Used to track conversation title generation**
| Generate Name | Weave Trace |
| -------------- | ------------------ |
| user\_id | placed in metadata |
| generate\_name | name |
| start\_time | start\_time |
| end\_time | end\_time |
| inputs | inputs |
| outputs | outputs |
| metadata | extra |
| generate\_name | tags |
**Generate Name Trace Info**
* conversation\_id - Conversation ID
* inputs - Input data
* outputs - Generated conversation name
* start\_time - Start time
* end\_time - End time
* tenant\_id - Tenant ID
* Metadata
* conversation\_id - Conversation ID
* tenant\_id - Tenant ID
# Logs
Source: https://docs.dify.ai/en/cloud/use-dify/monitor/logs
Browse and inspect your app's conversation and run logs, understand log retention, and download archived workflow logs
In the **Logs** tab of any app, see how it is actually used: what people asked or submitted, how the app responded, and what feedback came back.
Chat-based apps (Chatbot, Chatflow, Agent) and Text Generator apps log conversations; Workflow apps log runs.
## What Gets Logged
Logs capture real usage from every channel: the web app, the API, and apps opened from the **WEB APPS** list on **Home**. For Workflow apps, runs started by [triggers](/en/cloud/use-dify/nodes/trigger/overview) are logged too.
End-user feedback (thumbs up/down and comments) is stored with the messages it refers to.
Test sessions from the app editor are excluded for Chatflow and Workflow apps (**Preview** and **Test Run**). For other app types they are listed, under the team member's account.
## Browse Logs
Each row is one conversation or one run. Most columns explain themselves, but a few deserve context:
* **Title** is generated from the conversation's first message.
* **End User or Account** shows a session ID for web app and API usage, or the team member's account for usage inside Dify.
* **User Rate** counts end users' likes and dislikes; **Op. Rate** (operator rate) counts your team's. Both aggregate across the whole conversation.
* **Trigger By** (Workflow apps) shows what started each run:
* **WebApp**: The published web app, or a call through the API
* **Webhook**: A webhook trigger receiving a request
* **Schedule**: A schedule trigger reaching its scheduled time
* **Integration**: An event from a connected integration
To find a conversation, search words from its messages or the end user's session ID. To find a workflow run, search its inputs or outputs, or paste the run ID.
## Inspect a Conversation
Click a row to open the full message thread. When you hover over an answer, you can:
* See its token spend and latency.
* Open the log behind it: the raw prompt, an Agent app's tool iterations, or a Chatflow message's node-by-node trace.
* Rate the answer as team feedback; a dislike can carry a comment explaining what went wrong. Team ratings fill the **Op. Rate** column, separate from end-user feedback.
* Add an annotation pairing the question with an improved reply. See [Annotation System](/en/cloud/use-dify/monitor/annotation-reply) for how annotated replies take effect.
To share a log entry with a teammate, copy its link in your browser's address bar.
## Inspect a Run
For Workflow apps, click a run to open its result, its inputs and outputs with status and token totals, and a node-by-node trace that pinpoints where a run failed or slowed down.
To reproduce an issue, click **Test With Params**: the workflow re-runs in the editor with this run's inputs.
![Test With Params]()
## Log Retention
Logs contain complete user conversations and may include sensitive information. Ensure your application complies with local data privacy regulations: publish a privacy policy and obtain user consent where required.
Deleting conversations or cleaning up old logs does not erase the files uploaded in them.
On the Sandbox plan, logs of every type are retained for 30 days. Older entries are permanently deleted—upgrading later doesn't recover them.
On Professional and Team, retention depends on the log type:
* **Conversation logs** (Chatbot, Chatflow, Agent, and Text Generator apps): retained for the duration of the active subscription.
* **Workflow run logs** (Workflow apps): recent runs stay on the **Logs** page; runs older than about three months move to monthly archives you can download as CSV files. See [Download Archived Logs](#download-archived-logs-professional-team) for details.
## Download Archived Logs Professional Team
Archived runs aren't lost: once a month, workflow run logs that have aged past about three months are packed into a monthly archive for the whole workspace, and every archived month is available for download.
Only the workspace owner and admins can download archives in **Settings** > **Archived logs**:
1. Click **Prepare download** for the month you need. Preparation runs in the background, so you can leave the page and come back.
2. When the button turns into **Download**, click it to save the file. A prepared download stays available for 24 hours; after that, prepare it again.
Each download is a ZIP containing CSV files that cover all workflow runs in the workspace for that month:
| File | Contents |
| :-------------------------------------------------- | :------------------------------------------------------------------------ |
| `workflow_runs.csv` | One row per run: status, inputs, outputs, timing, and token usage |
| `workflow_app_logs.csv` | Links each run to its app and the end user or account that started it |
| `workflow_node_executions.csv` | Per-node execution records for each run |
| `workflow_node_execution_offload.csv` | Oversized node inputs and outputs stored separately from the main records |
| `workflow_pauses.csv`, `workflow_pause_reasons.csv` | Pause records from runs that waited for human input |
| `workflow_trigger_logs.csv` | Trigger invocations that started runs |
To pull out a single app's history, filter by the `app_id` column, present in the run and app log CSVs. An app's ID is the long identifier in its URL in **Studio**.
# Agent
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/agent
Run an agent as a step in your workflow, reasoning and using tools to complete a task
The classic Agent node gives your LLM autonomous control over tools, enabling it to iteratively decide which tools to use and when to use them. Instead of pre-planning every step, the Agent reasons through problems dynamically, calling tools as needed to complete complex tasks.
## Agent Strategies
Agent strategies define how your Agent thinks and acts. Choose the approach that best matches your model's capabilities and task requirements.
Uses the LLM's native function calling capabilities to directly pass tool definitions through the tools parameter. The LLM decides when and how to call tools using its built-in mechanism.
Best for models like GPT-4, Claude 3.5, and other models with robust function calling support.
Uses structured prompts that guide the LLM through explicit reasoning steps. Follows a **Thought → Action → Observation** cycle for transparent decision-making.
Works well with models that may not have native function calling or when you need explicit reasoning traces.
Install additional strategies from **Marketplace → Agent Strategies** or contribute custom strategies to the [community repository](https://github.com/langgenius/dify-plugins).
## Configuration
### Model Selection
Choose an LLM that supports your selected agent strategy. More capable models handle complex reasoning better but cost more per iteration. Ensure your model supports function calling if using that strategy.
### Tool Configuration
Configure the tools your Agent can access. Each tool requires:
**Authorization** - API keys and credentials for external services configured in your workspace
**Description** - Clear explanation of what the tool does and when to use it (this guides the Agent's decision-making)
**Parameters** - Required and optional inputs the tool accepts with proper validation
### Instructions and Context
Define the Agent's role, goals, and context using natural language instructions. Use Jinja2 syntax to reference variables from upstream workflow nodes.
**Query** specifies the user input or task the Agent should work on. This can be dynamic content from previous workflow nodes.
### Execution Controls
**Max Iterations** sets a safety limit to prevent infinite loops. Configure based on task complexity - simple tasks need 3-5 iterations, while complex research might require 10-15.
**Memory** controls how many previous messages the Agent remembers using TokenBufferMemory. Larger memory windows provide more context but increase token costs. This enables conversational continuity where users can reference previous actions.
### Tool Parameter Auto-Generation
Tools can have parameters configured as **auto-generated** or **manual input**. Auto-generated parameters (`auto: false`) are automatically populated by the Agent, while manual input parameters require explicit values that become part of the tool's permanent configuration.
## Output Variables
Agent nodes provide comprehensive output including:
**Final Answer** - The Agent's ultimate response to the query
**Tool Outputs** - Results from each tool invocation during execution
**Reasoning Trace** - Step-by-step decision process (especially detailed with ReAct strategy) available in the JSON output
**Iteration Count** - Number of reasoning cycles used
**Success Status** - Whether the Agent completed the task successfully
**Agent Logs** - Structured log events with metadata for debugging and monitoring tool invocations
## Use Cases
**Research and Analysis** - Agents can autonomously search multiple sources, synthesize information, and provide comprehensive answers.
**Troubleshooting** - Diagnostic tasks where the Agent needs to gather information, test hypotheses, and adapt its approach based on findings.
**Multi-step Data Processing** - Complex workflows where the next action depends on intermediate results.
**Dynamic API Integration** - Scenarios where the sequence of API calls depends on responses and conditions that can't be predetermined.
## Best Practices
**Clear Tool Descriptions** help the Agent understand when and how to use each tool effectively.
**Appropriate Iteration Limits** prevent runaway costs while allowing sufficient flexibility for complex tasks.
**Detailed Instructions** provide context about the Agent's role, goals, and any constraints or preferences.
**Memory Management** balance context retention with token efficiency based on your use case requirements.
The new Agent node is in beta and available in Workflow apps only.
The new Agent node runs an [agent](/en/cloud/use-dify/build/new-agent/overview) as one step of a workflow. Unlike the classic node's model-with-tools setup, the agent arrives as a complete worker with its own capabilities and sandbox.
You pick the agent and tell it what to do; it works through the task on its own and hands the results back to the rest of the flow.
## Choose an Agent
When you add the node, pick who does the work:
You can invite any published agent: it arrives with its saved capabilities, and you set only its task here.
An invited agent is like a full-time employee: its capabilities are managed centrally in **Agents**. When you publish an update there, every workflow that uses the agent gets it.
* To edit its capabilities, click **Edit in Agents**.
* If you want changes for this step only, click **Make a copy**: the node switches to a one-time copy that no longer follows the original.
Create a one-time agent that lives on this node alone, and configure it right here, the same way you [build](/en/cloud/use-dify/build/new-agent/build) in **Agents**.
It's like a temp you bring in for one job. If it proves its worth, promote it to **Agents** to reuse it elsewhere.
![Save a One-Time Agent]()
You can always swap the agent later.
Two nodes that invite the same agent still work separately: each starts from the agent's saved setup in its own sandbox, and nothing from one node's run (files it wrote, tools it installed) carries into another.
To pass results between nodes, declare them as outputs and reference them downstream.
## Give It a Task
In **Agent task**, describe what you need at this step, the way you'd brief a colleague on one job. This is separate from the agent's own prompt and capabilities. Type `/` to pull in outputs from earlier nodes.
Say you've invited a support agent that already knows your product docs and writes in your support tone, and the workflow hands it inbound customer emails. The task covers only this step:
```text wrap theme={null}
Read the customer email in {{customer_email}} and draft a reply that answers every question in it. Keep it under 150 words.
```
Variables you pull in reach the agent as text and are truncated at 2,000 characters.
To hand over longer content in full, pass it as a file: the agent receives the whole file and reads it in its sandbox.
## Declare Its Outputs
By default, an Agent node returns a single output, `text`: the agent's reply to its task, as one block of text. When a later step needs something more specific, like a single value or a particular file, declare it as its own output.
Type `/` in the **Agent task**, choose **New output**, then name it and pick a type in place. Each declared output can be referenced by downstream nodes on its own.
A declared output sits right in the task text, so you can tell the agent exactly what to put in it. For example, in this task `{{vendor_name}}` and `{{quote_file}}` are declared outputs:
```text wrap theme={null}
Compare the three vendor quotes in {{vendor_quotes}} and write a recommendation. Put the winning vendor's name in {{vendor_name}} and its quote PDF in {{quote_file}}.
```
Each file the agent returns is capped at 50 MB.
# Answer
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/answer
Define response content in Chatflow applications
The Answer node defines what content gets delivered to users in Chatflow applications. Use it to format responses, combine text with variables, and stream multimodal content including text, images, and files.
The Answer node is only available for Chatflow applications. Workflow applications use the End node instead.
## Content Configuration
The Answer node provides a flexible text editor where you can craft responses using fixed text, variables from previous nodes, or combinations of both.
Reference variables from any previous workflow node using the `{{variable_name}}` syntax. The editor supports rich content formatting and variable insertion to create dynamic, contextual responses.
## Multimodal Responses
Answer nodes support rich content delivery including text, images, and files in a single response stream.
**Text Content** can include variable substitution, markdown formatting, and dynamic content based on workflow processing results.
**Image Content** displays images generated by tools, uploaded by users, or processed by workflow nodes. Images stream alongside text for rich user experiences.
**File Content** delivers documents, spreadsheets, or other files generated or processed during the workflow execution.
## Streaming Behavior
Answer nodes stream content progressively based on variable availability. The node outputs all content up to the first unresolved variable, then waits for that variable to resolve before continuing.
**Variable Order Matters** - The sequence of variables in your Answer node determines streaming behavior, not the execution order of upstream nodes.
For example, with nodes executing as `Node A -> Node B -> Answer`:
* If the Answer contains `{{A}}` then `{{B}}`, it streams A's content immediately when available, then waits for B
* If the Answer contains `{{B}}` then `{{A}}`, it waits for B to complete before streaming any content
This streaming behavior enables responsive user experiences while maintaining content coherence.
## Multiple Answer Nodes
You can place multiple Answer nodes throughout your Chatflow to deliver content at different stages of processing.
## Variable Integration
Answer nodes seamlessly integrate with outputs from all workflow node types. Common variable sources include:
**LLM Responses** - Display generated text, analysis results, or structured outputs from language models
**Knowledge Retrieval** - Show relevant information found in knowledge bases with automatic citation tracking
**Tool Results** - Present data from external APIs, calculations, or service integrations
**File Processing** - Display extracted text, analysis results, or processed document content
The variable system maintains type safety and automatically handles different content types for optimal display in the chat interface.
# Code
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/code
Execute custom Python or JavaScript for data processing
The Code node executes custom Python or JavaScript to handle complex data transformations, calculations, and logic within your workflow. Use it when preset nodes aren't sufficient for your specific processing needs.
## Configuration
Define **Input Variables** to access data from other nodes in your workflow, then reference these variables in your code. Your function must return a dictionary containing the **Output Variables** you've declared.
```python theme={null}
def main(input_variable: str) -> dict:
# Process the input
result = input_variable.upper()
return {
'output_variable': result
}
```
## Language Support
Choose between **Python** and **JavaScript** based on your needs and familiarity. Both languages run in secure sandboxes with access to common libraries for data processing.
Python includes standard libraries like `json`, `math`, `datetime`, and `re`. Ideal for data analysis, mathematical operations, and text processing.
```python theme={null}
def main(data: list) -> dict:
import json
import math
average = sum(data) / len(data)
return {'result': math.ceil(average)}
```
JavaScript provides standard built-in objects and methods. Good for JSON manipulation and string operations.
```javascript theme={null}
function main(data) {
const processed = data.map(item => item.toUpperCase());
return { result: processed };
}
```
## Error Handling and Retries
Configure automatic retry behavior for failed code executions and define fallback strategies when code encounters errors.
**Retry Settings** allow up to 10 automatic retries with configurable intervals (maximum 5000ms). Enable this for handling temporary processing issues.
**Error Handling** lets you define fallback paths when code execution fails, allowing your workflow to continue running even when the code encounters problems.
## Output Limits
Before an output passes to the next node, Dify checks that it isn't too large:
* **Strings**: up to 400,000 characters.
* **Numbers**: whole numbers up to 19 digits, and decimals up to 20 places.
* **Objects and arrays**: nested up to five levels deep.
An output that exceeds a limit fails the check, so trim or split large results before returning them.
## Security Considerations
Code runs in an isolated sandbox that blocks file system access, outbound network requests, and system commands. The sandbox keeps execution separated from the underlying infrastructure while still giving you the flexibility of writing custom code.
Because of this isolation, operations that reach outside the sandbox are blocked automatically. Avoid reading system files, opening network connections, or running shell commands; restructure your logic to work with the input variables and libraries available inside the sandbox instead.
## Dependencies Support
Code nodes support external dependencies for both Python and JavaScript:
```python theme={null}
# Python: Import numpy, pandas, requests, etc.
import numpy as np
import pandas as pd
def main(data: list) -> dict:
df = pd.DataFrame(data)
return {'mean': float(np.mean(df['values']))}
```
```javascript theme={null}
// JavaScript: Import lodash, moment, etc.
const _ = require('lodash');
function main(data) {
return { unique: _.uniq(data) };
}
```
A standard set of packages is pre-installed in the sandbox environment. Imports outside that set will fail at execution time.
# Document Extractor
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/doc-extractor
Extract text content from uploaded documents for AI processing
The Document Extractor node converts uploaded files into text that LLMs can process. Since language models can't directly read document formats like PDF or DOCX, this node serves as the essential bridge between file uploads and AI analysis.
## Supported File Types
The node handles most text-based document formats:
**Text Documents** - TXT, Markdown, HTML files with direct text content
**Office Documents** - DOCX files from Microsoft Word and compatible applications
**PDF Documents** - Text-based PDFs
**Office Files** - DOCX files parse directly, with tables converted to Markdown. DOC and ODT files are also supported.
**Spreadsheets** - Excel (.xls/.xlsx) and CSV files converted to Markdown tables
**Presentations** - PowerPoint (.ppt/.pptx) files
**Email Formats** - EML and MSG files for email content extraction
**Specialized Formats** - EPUB books, VTT subtitles, JSON/YAML data, and Properties files
Files containing primarily binary content like images, audio, or video require specialized processing tools or external services.
## Input and Output
### Input Configuration
Configure the node to accept either:
**Single File** input from a file variable (typically from the Start node)
**Multiple Files** as an array for batch document processing
### Output Structure
The node outputs extracted text content:
* Single file input produces a `string` containing the extracted text
* Multiple file input produces an `array[string]` with each file's content
The output variable is named `text` and contains the raw text content ready for downstream processing.
## Implementation Example
Here's a complete document Q\&A workflow using the Document Extractor:
### Workflow Setup
**File Upload Configuration** - Enable file input in your Start node to accept document uploads from users.
**Text Extraction** - Connect the Document Extractor to process uploaded files and extract their text content.
**AI Processing** - Use the extracted text in LLM prompts for analysis, summarization, or question answering.
## Processing Considerations
The Document Extractor uses specialized parsing libraries optimized for different file formats. It preserves text structure and formatting where possible, making extracted content more useful for LLM processing.
### File Format Processing
**Encoding Detection** - Uses chardet library to automatically detect file encoding with UTF-8 fallback for text-based files
**Table Conversion** - Excel and CSV data becomes Markdown tables for better LLM comprehension
**Document Structure** - DOCX files maintain paragraph and table ordering with proper table-to-Markdown conversion
**Multi-line Content** - VTT subtitle files merge consecutive utterances by the same speaker
For very large documents, consider the LLM's context limits and implement chunking strategies if needed. The extracted text maintains the original document's logical structure to preserve meaning and context.
# HTTP Request
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/http-request
Connect to external APIs and web services
The HTTP Request node connects your workflow to external APIs and web services. Use it to fetch data, send webhooks, upload files, or integrate with any service that accepts HTTP requests.
## HTTP Methods
The node supports all standard HTTP methods for different types of operations:
**GET** retrieves data from servers without modifying anything. Use for fetching user profiles, searching databases, or getting current status.
**HEAD** gets response headers without the full response body. Useful for checking if resources exist or getting metadata.
**POST** sends data to servers, typically for creating new resources. Use for form submissions, file uploads, or sending JSON payloads.
**PUT** creates or completely replaces resources. Use when you want to set the entire state of a resource.
**PATCH** makes partial updates to existing resources. Use when you only need to modify specific fields.
**DELETE** removes resources from servers. Use for deleting files, user accounts, or any resource that should be removed.
## Configuration
Configure every aspect of your HTTP request including URL, headers, query parameters, request body, and authentication. Variables from previous workflow nodes can be dynamically inserted anywhere in your request configuration.
### Variable Substitution
Reference workflow variables using double curly braces: `{{variable_name}}`. Dify supports deep object access, so you can extract nested values like `{{api_response.data.items[0].id}}` from previous HTTP responses.
Secret-type environment variable values are masked in workflow run logs and in this node's request log.
### Timeout Configuration
HTTP requests have configurable timeouts to prevent hanging:
* **Connect timeout**: Maximum time to establish connection
* **Read timeout**: Maximum time to read response data
* **Write timeout**: Maximum time to send request data
Timeouts are enforced to maintain workflow performance and prevent resource exhaustion.
### Authentication
The node supports multiple authentication types:
**No Auth** (`type: "no-auth"`) - No authentication headers added
**API Key** (`type: "api-key"`) with three subtypes:
* **Basic** (`type: "basic"`) - Adds Basic Auth header with base64 encoding
* **Bearer** (`type: "bearer"`) - Adds `Authorization: Bearer ` header
* **Custom** (`type: "custom"`) - Adds custom header with specified name and value
### Request Body
Choose the appropriate body type based on your API requirements:
* **JSON** for structured data
* **Form Data** for traditional web forms
* **Binary** for file uploads
* **Raw Text** for custom content types
## File Detection
The HTTP Request node automatically detects file responses using sophisticated logic:
1. **Content-Disposition analysis** - Checks for `attachment` disposition or filename parameters
2. **MIME type evaluation** - Analyzes content types to distinguish text from binary
3. **Content sampling** - For ambiguous types, samples first 1024 bytes to detect text patterns
Text-based responses (JSON, XML, HTML, etc.) are treated as regular data, while binary content becomes file variables.
## File Operations
The HTTP Request node handles file uploads and downloads seamlessly:
**File Uploads** use the binary request body option. Select file variables from previous nodes to send files to external services for document storage, media processing, or backup.
**File Downloads** are automatically handled when responses contain file content. Downloaded files become available as file variables for use in downstream nodes.
## Error Handling and Retries
Configure robust error handling for production workflows that depend on external services:
**Retry Settings** automatically retry failed requests up to 10 times with configurable intervals (maximum 5000ms). This handles temporary network issues or service unavailability.
**Error Handling** defines alternative workflow paths when HTTP requests fail, ensuring your workflow continues executing even when external APIs are unavailable.
## Response Processing
HTTP responses become structured variables in subsequent nodes with separate access to:
* **Response Body** - The main content returned by the API
* **Status Code** - HTTP status for conditional logic
* **Headers** - Response metadata as key-value pairs
* **Files** - Any file content returned by the API
* **Size Information** - Content size in bytes with readable formatting (KB/MB)
### SSL Verification
SSL certificate verification is configurable per node (`ssl_verify` parameter). This allows connections to internal services with self-signed certificates while maintaining security for external APIs.
# Human Input
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/human-input
Pause workflows to request human input
The Human Input node pauses workflows at key points to deliver a customizable request form. Recipients can use the form to review information, provide input, and choose from predefined decisions that determine how the workflow proceeds.
By embedding human judgement directly where it matters, you can *balance automated efficiency with human oversight*.
For a workflow design example, see [Example: Content Review Workflow](#example-content-review-workflow).
## Configuration
Configure the following to define how the node requests and processes human input:
* **Delivery method**: How the request form reaches recipients.
* **Form content**: What information recipients will see and what they can interact with.
* **User action**: What decisions recipients can make and how the workflow proceeds accordingly.
* **Timeout strategy**: How long to wait and what happens if no recipient responds.
### Delivery Method
Choose the channel through which the request is delivered. Currently available methods:
* **Web app**: Displays the request form to the web app end user. Not available in workflows started by a Trigger.
External clients can drive the web app form lifecycle through the Service API. See [API Integration Flow](/en/api-reference/guides/human-input-flow).
* **Email**: Sends a request link via email to specific workspace members, external email addresses, or every member of the workspace. Anyone with the link can respond, no Dify account required.
The request closes after the first response regardless of delivery method.
### Form Content
Customize the form recipients see and interact with:
* **Format and structure with Markdown**
Use headings, lists, bold text, links, and other Markdown elements to present information clearly.
* **Display dynamic data with variables**
Reference workflow variables to show dynamic content, such as AI-generated text for review or a file someone uploaded at an upstream Human Input node for approval.
In web app delivery, the form itself displays to end users. Any variables you reference render their values directly in the form, so **no Answer or Output node is needed before the Human Input node**.
Reasoning models emit their thinking process alongside the final answer. Referencing the `text` output variable shows both by default.
To show only the answer, toggle on **Enable Reasoning Tag Separation** for the corresponding LLM node.
* **Collect input with form fields**
Add fields into the request form to capture different types of input from recipients. Each field becomes a variable for downstream use.
For example, in a blog review workflow, you can pass recipient feedback to a downstream LLM node for content revision.
| Field Type | Description |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paragraph | Text input. Can start empty, or pre-filled with variables (e.g., LLM output to refine) or static text (examples or default values).
No maximum length, but very long inputs may exceed downstream LLM context windows. |
| Select | Single-choice selection from a list of options. Define options manually, or reference an `array[string]` variable to use its items as options. |
| Single File / File List | Single or multiple file uploads.
Per-file upload limits: 10 MB for images, 15 MB for documents and other files, 50 MB for audio, and 100 MB for video. A File List field accepts up to 10 files. |
Only Paragraph is optional; Select, Single File, and File List are mandatory. The form's action buttons stay disabled until all mandatory fields are filled.
After the recipient responds, the form content with all values filled in is available downstream as the `__rendered_content` variable. File field values render as plain-text placeholders: `[file]` for Single File and `[N files]` for File List.
### User Action
Define the decision buttons that recipients can click, each routing the workflow to a different execution path.
For example, a `Post` branch might lead to nodes that trigger content publishing, while a `Regenerate` branch might loop back to an LLM node to revise the content.
Each button has a display title and an action ID. When a button is clicked, its ID is exposed downstream as `__action_id` and its title (button text) as `__action_value`.
![Action Button Configuration]()
Use preset button styles to visually distinguish actions.
For example, use a prominent style for key actions like `Approve` and a subtler one for secondary options.
### Timeout Strategy
Configure how long the request stays open before it expires. The default is 3 days.
If no recipient responds before the timeout, the workflow follows the timeout branch from the node. Wire this branch to a fallback path, such as a notification or a retry loop.
If no timeout branch is connected, the workflow ends.
## Example: Content Review Workflow
This workflow drafts a blog post from the `topic` and `language` that a workflow initiator inputs, emails the draft to a reviewer, and finalizes the output based on the reviewer's choice.
It is designed around three things the reviewer should be able to do:
1. **See the AI-generated draft**: Reference the upstream LLM node's `text` variable in the form so the rendered form displays the draft directly.
2. **Edit the draft directly if needed**: Add a Paragraph field named `edits` in the form, pre-filled with the same `text` variable, so the reviewer sees the draft as starting content and can edit in place.
Because blog posts are long, the form's Markdown display (point 1) reads better than a Paragraph field on its own. For shorter content, the pre-filled Paragraph field alone can handle both reading and editing.
3. **Provide feedback for an AI revision**:
1. Add a Paragraph field named `feedback` in the form for the reviewer's feedback.
2. Connect two downstream LLM nodes in sequence:
1. A Regenerate node that takes the original draft `text` and the reviewer's `feedback` to produce a revised draft.
2. A Check Revision node that takes `feedback` and the revised draft to verify whether the revision addresses the feedback. The verified result is what flows downstream.
On the received request form, the reviewer fills the relevant Paragraph fields (or leaves them blank) based on their judgment, then clicks the matching action button. Each action wires to a different output:
* **Approve**: the original draft from the upstream LLM
* **Apply Edit**: the reviewer's edited content from the `edits` field
* **Regenerate**: the revised draft from the downstream LLM pipeline
**System**
```text wrap theme={null}
Write a marketing blog post around the given topic in the specified language.
```
**User**
```text theme={null}
Topic: {{#user_input.topic#}}
Language: {{#user_input.language#}}
```
**System**
```text wrap theme={null}
Regenerate the draft based on user feedback.
```
**User**
```text theme={null}
Draft: {{#generate_draft.text#}}
User Feedback: {{#human_input.feedback#}}
```
**System**
```text wrap theme={null}
Check whether the draft below addresses the user's feedback. Return the draft unchanged if it does; revise it to address the feedback if it doesn't.
```
**User**
```text theme={null}
User Feedback: {{#human_input.feedback#}}
Regenerated Draft: {{#regenerate.text#}}
```
# If-Else
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/ifelse
Add conditional logic and branching to workflows
The If-Else node adds decision-making logic to your workflows by routing execution down different paths based on conditions you define. It evaluates variables and determines which branch your workflow should follow.
## Branching Logic
The node supports multiple branching paths to handle complex decision trees:
**IF Path** executes when the primary condition evaluates to true.
**ELIF Paths** provide additional conditions to check in sequence when the IF condition is false. You can add multiple ELIF branches for complex logic.
**ELSE Path** serves as the fallback when no conditions match, ensuring your workflow always has a path to follow.
## Condition Types
Configure conditions to test variables using various comparison operators:
**Contains** / **Not contains** - Check if the value includes specific words or phrases
**Starts with** / **Ends with** - Test text beginnings or endings for pattern matching
**Is** / **Is not** - Exact value matching
**Is empty** / **Is not empty** - Check for blank, null, or missing values
**Greater than** / **Less than** - Numerical comparisons for numbers and dates
**Equals** / **Not equals** - Exact matching for any data type
## Complex Conditions
Combine multiple conditions using logical operators for sophisticated decision-making:
**AND Logic** requires all conditions to be true. Use this when you need multiple criteria to be met simultaneously.
**OR Logic** requires any condition to be true. Use this when you want to trigger the same action for different scenarios.
## Variable References
Reference any variable from previous workflow nodes in your conditions. Variables can come from user input, LLM responses, API calls, or any other workflow node output.
Use the variable selector to choose from available variables, or type variable names directly using the `{{variable_name}}` syntax.
# Iteration
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/iteration
Process arrays by applying workflows to each element
The Iteration node processes arrays by running the same workflow steps on each element sequentially or in parallel. Use it for batch processing tasks that would otherwise hit limits or be inefficient as single operations.
## How Iteration Works
The node takes an array input and creates a sub-workflow that runs once for each array element. During each iteration, the current item and its index are available as variables that internal nodes can reference.
**Core Components**:
* **Input Variables** - Array data from upstream nodes
* **Internal Workflow** - The processing steps to perform on each element
* **Output Variables** - Collected results from all iterations (also an array)
## Configuration
### Array Input
Connect an array variable from upstream nodes such as Parameter Extractor, Code nodes, Knowledge Retrieval, or HTTP Request responses.
### Built-in Variables
Each iteration provides access to:
* `items[object]` - The current array element being processed
* `index[number]` - The current iteration index (starting from 0)
### Processing Mode
**Sequential Processing** - Items processed one after another in order
**Streaming Support** - Results can be output progressively using Answer nodes
**Resource Management** - Lower memory usage, predictable execution order
**Best For** - When order matters or when using streaming output
**Concurrent Processing** - Up to 10 items processed simultaneously
**Improved Performance** - Faster execution for independent operations
**Batch Processing** - Handles large arrays efficiently
**Best For** - Independent operations where order doesn't matter
## Error Handling
Configure how to handle processing failures for individual array elements:
**Terminate** - Stop processing when any error occurs and return the error message
**Continue on Error** - Skip failed items and continue processing, outputting null for failed elements
**Remove Failed Results** - Skip failed items and return only successful results
Input-output correspondence examples:
* Input: `[1, 2, 3]`
* Output with Continue on Error: `[result-1, null, result-3]`
* Output with Remove Failed: `[result-1, result-3]`
## Long Article Generation Example
Generate lengthy content by processing chapter outlines individually:
**Workflow Steps**:
1. **Start Node** - User provides story title and outline
2. **LLM Node** - Generate detailed chapter breakdown
3. **Parameter Extractor** - Convert chapter list to structured array
4. **Iteration Node** - Process each chapter with internal LLM
5. **Answer Node** - Stream chapter content as it's generated
Parameter extraction effectiveness depends on model capabilities and instruction quality. Use stronger models and provide examples in instructions to improve results.
## Output Processing
Iteration nodes output arrays that often need conversion for final use:
### Convert Array to Text
```python theme={null}
def main(articleSections: list):
return {
"result": "\n".join(articleSections)
}
```
```jinja theme={null}
{{ articleSections | join("\n") }}
```
# Knowledge Retrieval
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/knowledge-retrieval
Retrieve relevant content from knowledge bases and use it as context for downstream nodes
Use the Knowledge Retrieval node to integrate existing knowledge bases into your workflows. The node searches specific knowledge for information relevant to queries and outputs results as contextual content for use in downstream nodes (e.g., LLMs).
Below is an example of using the Knowledge Retrieval node in a Chatflow:
1. The **User Input** node collects the user query.
2. The **Knowledge Retrieval** node searches the selected knowledge base(s) for content related to the user query and outputs the retrieval results.
3. The **LLM** node generates a response based on both the user query and the retrieved knowledge.
4. The **Answer** node returns the LLM's response to the user.
![Knowledge Retrieval Node Use Case]()
Before using a Knowledge Retrieval node, ensure that you have at least one available knowledge base. To learn about creating knowledge bases, see [Knowledge](/en/cloud/use-dify/knowledge/readme#create-knowledge).
Knowledge retrieval operations are subject to per-minute rate limits that vary by subscription plan. See [Knowledge Request Rate Limit](/en/cloud/use-dify/knowledge/knowledge-request-rate-limit) for the per-plan numbers.
## Configure the Node
To make the Knowledge Retrieval node work properly, you need to specify:
* *What* it should search for (the query)
* *Where* it should search (the knowledge base)
* *How* to process the retrieval results (the node-level retrieval settings)
You can also use document metadata to enable filter-based searches and further improve retrieval precision.
### Specify the Query
Provide the query content that the node should search for in the selected knowledge base(s).
* **Query Text**: Select a text variable. For example, use `userinput.query` to reference user input in Chatflows, or a custom text-type user input variable in Workflows.
* **Query Images**: Select an image variable, e.g., the image(s) uploaded by the user through a User Input node, to search by image. Each image must be 2 MB or smaller.
The **Query Images** option is available only when at least one multimodal knowledge base is added.
Such knowledge bases are marked with the **Vision** tag, indicating that they are using a multimodal embedding model.
### Select Knowledge to Search
Add one or more existing knowledge bases for the node to search for content relevant to the query.
When multiple knowledge bases are added, knowledge is first retrieved from all of them simultaneously, then combined and processed according to the [node-level retrieval settings](#configure-node-level-retrieval-settings).
Knowledge bases marked with the **Vision** tag support cross-modal retrieval: they return both text and images based on semantic relevance.
You can click the **Edit** icon next to any added knowledge base to modify its [settings](/en/cloud/use-dify/knowledge/manage-knowledge/introduction).
### Configure Node-Level Retrieval Settings
To fine-tune how the node processes retrieval results after they are fetched from the knowledge base(s), click **Retrieval Setting**.
Retrieval settings exist at two layers: the knowledge base level and the knowledge retrieval node level.
Think of them as two consecutive filters: the knowledge base settings determine the initial pool of results, and the node settings further rerank the results or narrow down the pool.
* **Rerank Settings**
* **Weighted Score**
The relative weight between semantic similarity and keyword matching during reranking. Higher semantic weight favors meaning relevance, while higher keyword weight favors exact matches.
Weighted Score is available only when all added knowledge bases are indexed with **High Quality** mode.
* **Rerank Model**
The rerank model to re-score and reorder all the results based on their relevance to the query.
If any multimodal knowledge bases are added, select a multimodal rerank model (marked with a **Vision** tag) as well. Otherwise, retrieved images will be excluded from reranking and the final output.
* **Top K**
The maximum number of top results to return after reranking.
When a rerank model is selected, this value will be automatically adjusted based on the model's maximum input capacity (how much text the model can process at once).
* **Score Threshold**
The minimum similarity score for returned results. Results scoring below this threshold are excluded. Use higher thresholds for stricter relevance or lower thresholds to include broader matches.
### Enable Metadata Filtering
By default, retrieval searches across the entire knowledge base. To restrict retrieval to specific documents, enable manual or automatic metadata filtering.
This improves retrieval precision, especially when your knowledge base is large or contains content for different contexts.
For creating and managing document metadata, see [Metadata](/en/cloud/use-dify/knowledge/metadata).
## Output
The Knowledge Retrieval node outputs the retrieval results as a variable named `result`, which is an array of retrieved document chunks containing their content, metadata, title, and other attributes.
When the retrieval results contain image attachments, the `result` variable also includes a field named `files` containing image details.
## Use with LLM Nodes
To use the retrieval results as context in an LLM node:
1. In **Context**, select the Knowledge Retrieval node's `result` variable.
2. In the system instruction, reference the `Context` variable.
3. Optional: If the LLM is vision-capable, enable **Vision** so it can process image attachments in the retrieval results.
You don't need to specify the retrieval results as the vision input. Once **Vision** is enabled, the LLM will automatically access any retrieved images.
In chatflows, citations are shown alongside responses that reference knowledge by default. You can turn this off by disabling **[Citation and Attributions](/en/cloud/use-dify/build/additional-features#citations-and-attributions)** in **Features** at the top right corner of the canvas.
# List Operator
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/list-operator
Filter, sort, and select elements from arrays
The List Operator node processes arrays by filtering, sorting, and selecting specific elements. Use it when you need to work with mixed file uploads, large datasets, or any array data that requires separation or organization before downstream processing.
Supported input data types include `array[string]`, `array[number]`, `array[file]`, and `array[boolean]`.
## The Array Processing Problem
Most workflow nodes expect single values, not arrays. When you have mixed content like `[image.png, document.pdf, audio.mp3]` in one variable, you need to separate this into focused streams that downstream nodes can process effectively.
The List Operator acts as an intelligent router, using filters to separate mixed arrays and prepare them for specialized processing.
## Operations
### Filtering
Extract specific items based on their attributes. For file arrays, filter by:
**Type** - Filter by content category: image, document, audio, video
**MIME Type** - Precise content type identification (image/jpeg, application/pdf, etc.)
**Extension** - File extensions (.pdf, .jpg, .mp3, .docx, etc.)
**Size** - File size constraints for processing limits
**Name** - Filename patterns or specific names
**Transfer Method** - Distinguish between local uploads and URL-based files
### Sorting
Organize filtered results by any attribute:
**Ascending (ASC)** - Smallest to largest values, A-Z alphabetical order
**Descending (DESC)** - Largest to smallest values, Z-A reverse order
### Selection
Choose specific elements from the processed array:
**Take First N** - Select the first 1-20 items after filtering and sorting
**First Record** - Return only the first matching element as a single value
**Last Record** - Return only the last matching element as a single value
## Output Variables
**result** - Complete filtered and sorted array for bulk processing
**first\_record** - Single element from the beginning, perfect for "primary" or "latest" item selection
**last\_record** - Single element from the end, useful for "most recent" or "final" selection
## Mixed File Processing Example
Handle workflows where users upload both documents and images:
**Implementation Steps**:
1. **Configure Mixed Uploads** - Enable file upload features to accept multiple file types
2. **Split by Type** - Use separate List Operator nodes with different filters:
* Filter for `type = "image"` → route to LLM with vision capabilities
* Filter for `type = "document"` → route to Document Extractor
3. **Process Appropriately** - Images get analyzed directly, documents get text extraction
4. **Combine Results** - Merge processed outputs into unified responses
This pattern automatically routes different file types to appropriate processors, creating seamless multi-modal user experiences.
# LLM
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/llm
Invoke language models for text generation and analysis
The LLM node invokes language models to process text, images, and documents. It sends prompts to your configured models and captures their responses, supporting structured outputs, context management, and multimodal inputs.
Configure at least one model provider in **Integrations** > **Model Provider** before using LLM nodes.
## Model Selection and Parameters
Choose from any model provider you've configured. Different models excel at different tasks - GPT-4 and Claude 3.5 handle complex reasoning well but cost more, while GPT-3.5 Turbo balances capability with affordability.
Model parameters control response generation. **Temperature** ranges from 0 (deterministic) to 1 (creative). **Top P** limits word choices by probability. **Frequency Penalty** reduces repetition. **Presence Penalty** encourages new topics. You can also use presets: **Precise**, **Balanced**, or **Creative**.
### Share a Model Configuration Across Nodes
When several LLM nodes should run on the same model, store the model selection in an environment variable instead of configuring each node separately. Editing the variable, such as pointing it at a different model, updates every node bound to it.
Open the **Environment Variables** panel, add a variable of the **LLM** type, and choose a model with its parameters.
Then, in each LLM node, switch the **Model** field to variable mode, and pick the variable. The variable carries the provider, model, and model parameters; prompts and other settings stay with each node.
## Prompt Configuration
Your interface adapts based on model type. Chat models use message roles (**System** for behavior, **User** for input, **Assistant** for examples), while completion models use simple text continuation.
Reference workflow variables in prompts using double curly braces: `{{variable_name}}`. Variables are replaced with actual values before reaching the model.
```text theme={null}
System: You are a technical documentation expert.
User: {{user_input}}
```
## Context Variables
Context variables inject external knowledge while preserving source attribution. This enables RAG applications where LLMs answer questions using your specific documents.
Connect a Knowledge Retrieval node's output to your LLM node's context input, then reference it:
```text theme={null}
Answer using only this context:
{{knowledge_retrieval.result}}
Question: {{user_question}}
```
When using context variables from knowledge retrieval, Dify automatically tracks citations so users see information sources.
## Structured Outputs
Force models to return specific data formats like JSON for programmatic use. Configure through three methods:
User-friendly interface for simple structures. Add fields with names and types, mark required fields, set descriptions. The editor generates JSON Schema automatically.
Write schemas directly for complex structures with nested objects, arrays, and validation rules.
```json theme={null}
{
"type": "object",
"properties": {
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "neutral"]
}
},
"required": ["sentiment"]
}
```
Describe needs in plain language and let AI generate the schema.
Models with native JSON support handle structured outputs reliably. For others, Dify includes the schema in prompts, but results may vary.
## Memory and File Processing
![LLM Memory]()
Enable Memory to maintain context across multiple LLM calls within a Chatflow conversation. When enabled, previous interactions will be included in subsequent prompts as formatted user - assistant outputs. You can customize what goes into the user prompts by editing the `USER` template. Memory is node-specific and doesn't persist between different conversations.
For **File Processing**, add file variables to prompts for multimodal models. GPT-4V handles images, Claude processes PDFs directly, while other models might need preprocessing.
### Vision Configuration
When processing images, you can control the detail level:
* **High detail** - Better accuracy for complex images but uses more tokens
* **Low detail** - Faster processing with fewer tokens for simple images
The default variable selector for vision is `userinput.files` which automatically picks up files from the User Input node.
## Jinja2 Template Support
LLM prompts support Jinja2 templating for advanced variable handling. When you use Jinja2 mode (`edition_type: "jinja2"`), you can:
```jinja theme={null}
{% for item in search_results %}
{{ loop.index }}. {{ item.title }}: {{ item.content }}
{% endfor %}
```
Jinja2 variables are processed separately from regular variable substitution, allowing for loops, conditionals, and complex data transformations within prompts.
## Streaming Output
LLM nodes support streaming output by default. Each text chunk is yielded as a `RunStreamChunkEvent`, enabling real-time response display. File outputs (images, documents) are processed and saved automatically during streaming.
## Separate Reasoning from Responses
Some reasoning models wrap their thinking in `...` tags inside their response. By default, those tags are included in the `text` output, so the reasoning flows downstream together with the answer.
Turn on the **Enable reasoning tag separation** toggle to split them: the `text` output keeps only the answer, and the thinking moves to a separate `reasoning_content` output variable. While the toggle is off, `reasoning_content` stays empty.
In API calls, this toggle appears as the `reasoning_format` parameter. When the toggle is on, `reasoning_format` is `separated`, and streaming API clients receive the reasoning as dedicated `reasoning_chunk` events, outside the answer stream. For event details, see [Send Chat Message](/en/api-reference/chat-messages/send-chat-message) and [Run Workflow](/en/api-reference/workflow-runs/run-workflow).
This setting affects only models that wrap their reasoning in `` tags.
## Error Handling
Configure retry behavior for failed LLM calls. Set maximum retry attempts, intervals between retries, and backoff multipliers. Define fallback strategies like default values, error routing, or alternative models when retries aren't sufficient.
# Loop
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/loop
Execute repetitive workflows with progressive refinement
The Loop node executes repetitive workflows where each cycle builds on the results of the previous one. Unlike iteration, which processes array elements independently, loops create progressive workflows that evolve with each repetition.
## Loop vs Iteration
Understanding when to use each repetition pattern:
**Sequential Processing** - Each cycle depends on previous results
**Progressive Refinement** - Outputs improve or evolve over iterations
**State Management** - Variables persist and accumulate across cycles
**Use Cases** - Content refinement, problem solving, quality assurance
**Independent Processing** - Each item processed separately
**Parallel Execution** - Items can be processed simultaneously
**Batch Operations** - Same operation applied to multiple data points
**Use Cases** - Data transformation, bulk processing, parallel analysis
## Configuration
### Loop Variables
Define variables that persist across loop iterations and remain accessible after the loop completes. These variables maintain state and enable progressive workflows.
### Termination Conditions
Configure when the loop should stop executing:
**Loop Termination Condition** - Expression that determines when to exit (e.g., `quality_score > 0.9`)
**Maximum Loop Count** - Safety limit to prevent infinite loops
**Exit Loop Node** - Immediate termination when this node is reached
The loop terminates when either the termination condition is met, the maximum count is reached, or an Exit Loop node executes. If no conditions are specified, the loop continues until the maximum count.
## Basic Loop Example
Generate random numbers until finding one less than 50:
**Workflow Steps**:
1. **Code node** generates random integers between 1-100
2. **If-Else node** checks if number is less than 50
3. **Template node** returns "done" for numbers \< 50 to trigger loop termination
4. Loop continues until termination condition is met
## Advanced Loop Example
Create a poem through iterative refinement, with each version building upon the previous one:
**Loop Variables**:
* `num` - Counter starting at 0, incrementing each iteration
* `verse` - Text variable holding the current poem version
**Workflow Logic**:
1. **If-Else node** checks if `num > 3` to determine when to exit
2. **LLM node** generates improved poem based on previous version
3. **Variable Assigner** updates both counter and poem content
4. **Exit Loop node** terminates after 4 refinement cycles
The LLM prompt references both the current verse and iteration context:
```text theme={null}
You are a European literary figure creating poetic verses.
Current verse: {{verse}}
Refine and improve this poem based on your previous work.
```
# Output
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/output
Return workflow results to the end user or API caller
Use the Output node to deliver specific variable values from your workflow to the end user or API caller. Add it where you need to surface results.
The Output node was previously named *End* and was required in every workflow.
It is now optional—workflows run successfully without one, but any workflow or branch without an Output node returns no data to the caller.
Output nodes are only available in Workflows. Chatflows use the [Answer](/en/cloud/use-dify/nodes/answer) node instead.
## Configure Output Variables
Each Output node requires at least one output variable. To add a variable, assign a name and select the source from any upstream node's output.
The variable name you assign becomes the key in API responses.
You can add multiple output variables to a single Output node and reorder them by dragging.
## Supported Variable Types
Output variables support the following types:
`string`, `number`, `integer`, `boolean`, `object`, `file`, `array[string]`, `array[number]`, `array[object]`, `array[boolean]`, `array[file]`
## Multiple Output Nodes
A workflow can contain more than one Output node. The Output node does not stop workflow execution—other parallel branches (if any) continue running after it completes.
All output variables from every executed Output node are combined into one final result. Each Output node adds its variables to the result as the workflow reaches it:
* On the **same branch**, variables are added in the order the Output nodes are placed.
* On **parallel branches**, whichever Output node executes first adds its variables first.
Always use unique variable names across all Output nodes in a workflow.
When two Output nodes use the same output variable name, the later one overwrites the earlier value.
## API Response Structure
When you call a workflow through the API, output variables appear in the `outputs` object of the response.
All outputs return in a single response once the workflow completes:
```json theme={null}
{
"workflow_run_id": "...",
"status": "succeeded",
"outputs": {
"result_text": "The processed output...",
"score": 95
}
}
```
Outputs arrive in the final `workflow_finished` event:
```json theme={null}
{
"event": "workflow_finished",
"data": {
"outputs": {
"result_text": "The processed output...",
"score": 95
}
}
}
```
Each output variable name maps directly to a key in the `outputs` object.
## For Workflow Tools
When you [publish a workflow as a tool](/en/cloud/use-dify/workspace/tools#workflow), the Output node defines the tool's return schema. Each output variable name becomes a key in the tool's result, accessible to the parent workflow that invokes the tool.
# Parameter Extractor
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/parameter-extractor
Convert natural language to structured data using LLM intelligence
The Parameter Extractor node converts unstructured text into structured data using LLM intelligence. It bridges the gap between natural language input and the structured parameters that tools, APIs, and other workflow nodes require.
## Configuration
### Input and Model Selection
Select the **Input Variable** containing the text you want to extract parameters from. This typically comes from user input, LLM responses, or other workflow nodes.
Choose a **Model** with strong structured output capabilities. The Parameter Extractor relies on the LLM's ability to understand context and generate structured JSON responses.
### Parameter Definition
Define the parameters you want to extract by specifying:
* **Parameter Name** - The key that will appear in the output JSON
* **Data Type** - String, number, boolean, array, or object
* **Description** - Helps the LLM understand what to extract
* **Required Status** - Whether the parameter must be present
You can manually define parameters or **quickly import from existing tools** to match the parameter requirements of downstream nodes.
### Extraction Instructions
Write clear instructions describing what information to extract and how to format it. Providing examples in your instructions improves extraction accuracy and consistency for complex parameters.
## Advanced Configuration
### Inference Mode
Choose between two extraction approaches based on your model's capabilities:
**Function Call/Tool Call** uses the model's structured output features for reliable parameter extraction with strong type compliance.
**Prompt-based** relies on pure prompting for models that may not support function calling or when prompt-based extraction performs better.
### Memory
Enable memory to include conversation history when extracting parameters. This helps the LLM understand context in interactive dialogues and improves extraction accuracy for conversational workflows.
## Output Variables
The node provides both extracted parameters and built-in status variables:
**Extracted Parameters** appear as individual variables matching your parameter definitions, ready for use in downstream nodes.
**Built-in Variables** include status information:
* `__is_success` - Extraction success status (1 for success, 0 for failure)
* `__reason` - Error description when extraction fails
# Question Classifier
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/question-classifier
Intelligently categorize user input to route workflow paths
The Question Classifier node intelligently categorizes user input to route conversations down different workflow paths. Instead of building complex conditional logic, you define classes and let the LLM determine which one fits best based on semantic understanding.
## Configuration
### Input and Model Setup
**Input Variable** - Select what to classify, typically `sys.query` for user questions, but can be any text variable from previous workflow nodes.
**Model Selection** - Choose an LLM for classification. Faster models work well for simple classes, while more powerful models handle nuanced distinctions better.
### Class Definition
Each class has two independent pieces of text:
* **Class description** (the editor body) is what the LLM reads when choosing a branch.
Write a precise, distinguishing description of what belongs in the class; boundary phrases like "anything related to..." or "excluding..." help when classes overlap. Exposed downstream as `class_name`.
* **Class title** (the small heading above the editor) is the label shown on the canvas.
Double-click the default **CLASS N** title to rename it. Exposed downstream as `class_label`.
The title and the description edit independently, so you can keep a short, scannable label on the canvas while giving the LLM a longer, more specific description.
Each class becomes a potential output path that you can connect to different downstream nodes like specialized knowledge bases, response templates, or processing workflows.
## Classification Example
Here's how the Question Classifier works in a customer service scenario:
**Classes Defined**:
* **After-sales service** - Warranty claims, returns, repairs, and post-purchase support
* **Product usage** - Setup instructions, troubleshooting, feature explanations
* **Other questions** - General inquiries not covered by specific classes
**Classification Results**:
* "How to set up contacts on iPhone 14?" → **Product usage**
* "What is the warranty period for my purchase?" → **After-sales service**
* "What's the weather like today?" → **Other questions**
Each classification result routes to different knowledge bases and response strategies, ensuring users receive relevant, specialized assistance.
## Advanced Configuration
### Instructions and Guidelines
Add detailed classification guidelines in the **Instructions** field to handle edge cases, ambiguous scenarios, or specific business rules. This helps the LLM understand nuanced distinctions between classes.
# Start Node
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/start
Choose how your workflow begins, on demand or automatically
When you create a new workflow, you choose a start node that decides whether the workflow waits for someone to run it or runs on its own.
## User Input
Use [User Input](/en/cloud/use-dify/nodes/user-input) when someone (or an API call) should kick off the workflow and supply information it needs. You define input fields for text, numbers, files, and other data, and downstream nodes reference those values.
Only User Input workflows can be published as web apps, MCP servers, backend service APIs, or reused as tools in other Dify apps.
Chatflows always start with User Input. Only Workflows can use triggers.
## Trigger
Use a [trigger](/en/cloud/use-dify/nodes/trigger/overview) when the workflow should run automatically, without anyone invoking it. Three types are available:
* **[Schedule Trigger](/en/cloud/use-dify/nodes/trigger/schedule-trigger)**: runs at specified times or intervals.
* **[Integration Trigger](/en/cloud/use-dify/nodes/trigger/plugin-trigger)**: runs when an event occurs in an external system, via a subscription through a trigger integration.
* **[Webhook Trigger](/en/cloud/use-dify/nodes/trigger/webhook-trigger)**: runs when the workflow receives an HTTP request from an external system.
## Switch Between Start Nodes
User Input and triggers are mutually exclusive on a canvas. To switch, right-click the current start node and select **Change Node**, or delete it and add a new one.
# Template
Source: https://docs.dify.ai/en/cloud/use-dify/nodes/template
Transform and format data using Jinja2 templating
The Template node transforms and formats data from multiple sources into structured text using Jinja2 templating. Use it to combine variables, format outputs, and prepare data for downstream nodes or end users.
## Jinja2 Templating
Template nodes use Jinja2 templating syntax to create dynamic content that adapts based on workflow data. This provides programming-like capabilities including loops, conditionals, and filters for sophisticated text generation.
### Variable Substitution
Reference workflow variables using double curly braces: `{{ variable_name }}`. You can access nested object properties and array elements using dot notation and bracket syntax.
```jinja theme={null}
{{ user.name }}
{{ items[0].title }}
{{ data.metrics.score }}
```
### Conditional Logic
Show different content based on data values using if-else statements:
```jinja theme={null}
{% if user.subscription == 'premium' %}
Welcome back, Premium Member! You have access to all features.
{% else %}
Consider upgrading to Premium for additional capabilities.
{% endif %}
```
### Loops and Iteration
Process arrays and objects with for loops to generate repetitive content:
```jinja theme={null}
{% for item in search_results %}
### Result {{ loop.index }}
**Score**: {{ item.score | round(2) }}
{{ item.content }}
---
{% endfor %}
```
## Data Formatting
### Filters
Jinja2 filters transform data during template rendering:
```jinja theme={null}
{{ name | upper }}
{{ price | round(2) }}
{{ content | replace('\n', '
') }}
{{ tags | join(', ') }}
{{ score | default('No score available') }}
```
### Error Handling
Handle missing or invalid data gracefully using default values and conditional checks:
```jinja theme={null}
{{ user.email | default('No email provided') }}
{{ metrics.accuracy | round(2) if metrics.accuracy else 'Not calculated' }}
```
## Interactive Forms
Templates can generate interactive HTML forms for structured data collection in Chatflows.
On submit, the form values are sent to the chat as the end user's next message. The format depends on the `
```
![Interactive Form Rendered in Chat Interface]()
### Supported Tags
| Tag
| Attributes | Notes |
| :------------- | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `