Dify Getting Started Tutorial

Dify (Do It For You) is currently the most popular open-source LLM application development platform, designed specifically for building generative AI applications powered by large language models (LLMs).

Dify integrates AI workflow orchestration, RAG knowledge bases, Agent frameworks, model management, and observability into a single visual platform, allowing you to move quickly from prototype to production without building LLM infrastructure from scratch.

Dify simplifies the creation of AI applications by integrating RAG pipelines, AI workflows, observability tools, and model management.

If LangChain isParts factory for AI applications(flexible but requires a lot of handwritten code), then Dify isVisual IDE for AI Applications—all the components are there, just drag, connect, and run.

Comparison with Other Tools

The following is a comparison of Dify with LangChain and n8n across key dimensions.

Dify's intuitive visual orchestration studio makes it an ideal choice for startups and enterprises that need to quickly build functional AI applications.

LangChain is more suitable for complex enterprise-level applications that require custom integrations and deep developer involvement.

Who is using Dify?

From biomedicine to the automotive industry, Dify provides reliable solutions for a wide range of enterprises.

Volvo Cars uses Dify for rapid idea validation in AI frontier strategy navigation.

Users highly praise Dify for democratizing AI Agent development by combining powerful AI/ML capabilities into a no-code platform.

Core Concepts

Before you begin, let's understand the basic concepts of Dify:

Installation and Startup

Four installation methods, from instant start to high-availability cluster deployment.

Method 1: Dify Cloud (Fastest, 0-second onboarding)

Visitcloud.dify.ai, register an account and start using it immediately.

The free Sandbox plan includes 200 messages per month and 5 applications, with no environment configuration required.

Suitable for quick trials, personal projects, and prototyping.

Method 2: Docker Compose Self-hosting (Recommended for Production)

Suitable for users with technical background, giving full control over data and deployment environment.

System requirements

Installation steps

Step 1: Clone the repository

Clone the Dify repository to your local machine:

git clone https://github.com/langgenius/dify.git
cd dify

Step 2: Enter the docker directory and copy the environment configuration

cd docker
# 从模板复制环境配置文件
cp .env.example .env

Step 3 (Important): Configure SECRET_KEY

Since v1.14.1, Docker deployments no longer rely on a public default secret key. When SECRET_KEY is empty, the API automatically generates and persists a runtime key. It is recommended to explicitly set it in the .env file.

# 生成一个安全的随机密钥
openssl rand -base64 42

Edit the .env file, find SECRET_KEY, and set it to the random string generated above:

SECRET_KEY=your-very-long-random-secret-key-here

Step 4: Start the service

# 启动所有 Dify 服务（首次会拉取镜像，约需 3-10 分钟）
docker compose up -d

Step 5: Access and initialize

Open http://localhost/install in your browser and complete the admin account registration.

Step 6: Verify service status

# 查看所有容器状态，全部为 healthy 即表示运行正常
docker compose ps

If all containers (api, worker, web, db, redis, weaviate, nginx, etc.) are in healthy status, the services are running normally.

Stop and restart

# 停止所有服务（数据保留在 Docker volumes 中）
docker compose down

# 重新启动所有服务
docker compose up -d

Upgrade to a new version

# 进入 docker 目录
cd dify/docker

# 拉取最新代码
git pull origin main

# 拉取新镜像
docker compose pull

# 重新启动
docker compose up -d

Data is persisted in Docker volumes, and updates will not affect existing applications, knowledge bases, or conversation history. It is recommended to back up the PostgreSQL database before major version upgrades.

Method 3: One-click Deployment on AWS Marketplace

For startups and small businesses operating on AWS, Dify Premium on AWS Marketplace enables one-click deployment to your own AWS VPC, and supports custom Logo and branding.

Method 4: Kubernetes Deployment (High Availability)

For scenarios requiring high availability configuration, the community provides Helm Charts and YAML files to deploy Dify to a Kubernetes cluster.

# 添加 Dify Helm 仓库
helm repo add dify https://langgenius.github.io/dify-helm

# 使用自定义 values.yaml 安装
helm install dify dify/dify -f values.yaml

Configure Model Providers

After installation, the first step is to connect your AI model.

Operation Path

After logging into Dify, click the avatar in the upper-right corner, go to Settings, and select Model Provider.

For example, we can install the DeepSeek model provider, then configure the API key:

Mainstream Provider Configuration

Anthropic (Claude series):

Provider: Anthropic
API Key: sk-ant-xxxxxxxx（从 console.anthropic.com 获取）
推荐模型：claude-sonnet-4-6（综合性能最佳）

OpenAI：

Provider: OpenAI
API Key: sk-xxxxxxxx（从 platform.openai.com 获取）
推荐模型：gpt-4o（性价比高）

Google (Gemini series):

Provider: Google
API Key: xxxxxxxx（从 aistudio.google.com 获取）
推荐模型：gemini-2.0-flash（速度快，适合大量请求）

OpenRouter (one key to access 300+ models):

Provider: OpenRouter
API Key: sk-or-xxxxxxxx（从 openrouter.ai 获取）
Base URL: https://openrouter.ai/api/v1

Local model (Ollama):

Provider: Ollama
Base URL: http://host.docker.internal:11434  # Docker 内访问宿主机
（先在宿主机运行：ollama pull llama3.3）

Configure Embedding Model (Required for Knowledge Base)

Vectorization of the knowledge base requires an Embedding model. Below are recommended options:

Verify Model Availability

Go back to Settings, find the configured provider, click the Test button next to the model name. A green checkmark indicates successful configuration.

Detailed Explanation of Five Application Types

On the Dify homepage, click Create App. You will see five types, each corresponding to different usage scenarios.

Click to create a blank application, and you can see five types of applications:

1. Chatbot (Conversational Assistant)

A standard multi-turn conversation application with persistent session memory.

2. Text Generator

Single input to single output, no conversation history retained.

3. Agent

An AI that can proactively call tools, autonomously plan and execute multi-step tasks.

4. Chatflow (Conversation Flow)

Adds multi-turn conversation capabilities on top of Workflow, combining process orchestration and conversation context.

5. Workflow

A purely automated multi-step processing flow without a conversational interface, triggered via API or run manually.

Selection Guide

Quickly decide which application type to use based on your needs:

需要多轮对话？
├─ 是 → 需要复杂流程逻辑？
│        ├─ 是 → Chatflow
│        └─ 否 → Chatbot 或 Agent（需要工具调用时选 Agent）
└─ 否 → 单次输入输出？
          ├─ 是 → Text Generator
          └─ 需要多步骤自动化 → Workflow

Knowledge Base (RAG): Let AI Answer with Your Private Data

The Knowledge Base is one of Dify's most powerful features and the core of most enterprise applications.

Create a Knowledge Base

1. In the navigation bar, select Knowledge (Knowledge Base), and click Create Knowledge (Create Knowledge Base).
2. Name the knowledge base, e.g., 'Product Manual' or 'Internal Policy Documents'
3. Choose a creation method

Method 1: Upload files (most common)

Dify accepts files in PDF, Word (.docx), Markdown (.md), plain text (.txt), CSV, and HTML formats.

Markdown or plain text is recommended, as they are the most reliable to parse.

PDFs with complex layouts or scanned versions may require preprocessing; it is recommended to use OCR tools to extract the text before uploading.

Method 2: Knowledge Pipeline (Enterprise-level)

Knowledge Pipeline is a visual node-based orchestration system specifically designed for document ingestion and processing.

It addresses three major pain points of traditional RAG: scattered data sources, information loss during parsing (charts and formulas being discarded), and black-box processing (making it difficult to diagnose failure causes).

Method 3: External Knowledge Base API

Sync existing external knowledge bases via API without the need for data migration.

Document Chunking Strategy

After uploading, Dify automatically performs text chunking. Key parameters are explained below:

For Chinese content, it is recommended to set the chunk size to around 500 tokens. Too long makes retrieval less precise; too short loses context.

Index Modes

Retrieval Configuration

Go to the knowledge base, select Settings, and configure the retrieval parameters:

The similarity threshold is recommended to be set to 0.5-0.7.

If the similarity threshold is too high, no results will be returned; if too low, irrelevant content will be returned. It is recommended to start testing at 0.6 and fine-tune based on the results.

Test Retrieval Results

In the knowledge base, click Retrieval Testing, enter a test question, and directly view the returned Chunks to verify retrieval quality without actually starting a conversation.

Associate Knowledge Base with an Application

On the application editing page, select Context, click Add, choose the created knowledge base, and save.

Once linked, every conversation in the application will first retrieve from the knowledge base before answering.

Workflow: Visually Orchestrate Multi-step Tasks

Define multi-step AI processing logic by dragging nodes and connecting them.

Enter the Workflow Editor

Select Workflow when creating an application, or click Edit in an existing Workflow application to enter the canvas.

Main Node Types

The following are the most commonly used nodes in the Workflow editor and their functions:

Variable Passing Between Nodes

The output of each node can be referenced by subsequent nodes using the syntax {{node_name.output_variable_name}}.

The following is an example of variable passing in a typical RAG Q&A workflow:

Start 节点输出 user_query
  ↓
Knowledge Retrieval 节点：
  输入：{{Start.user_query}}
  输出：result（检索结果）
  ↓
LLM 节点：
  System Prompt：你是一个客服助理，根据以下资料回答问题
  User：用户问题：{{Start.user_query}}
        参考资料：{{Knowledge Retrieval.result}}
  ↓
End 节点：
  返回：{{LLM.text}}

Human Input Node (HITL)

The Human Input node is a major update that allows workflows to pause execution at key decision points.

This node generates a UI interface for human review and modification of variables (e.g., editing drafts or correcting data), and then determines the subsequent path based on custom buttons (such as "Approve", "Reject", or "Escalate").

This resolves the binary dilemma of previous workflows—"either fully automated or fully manual"—allowing high-risk scenarios (contract review, medical advice, financial decisions) to also benefit from automated AI.

Debugging the Workflow

Click Run (Run) in the top-right corner of the canvas, enter test parameters, and observe each node's input/output and latency.

Green (success) or red (failure) indicators appear next to nodes; click to view detailed execution logs.

Hands-on Scenario 1: Enterprise Internal Knowledge Q&A Bot

Use Dify to build a chatbot that can accurately answer questions about internal documents, with source citations in answers.

Business Background

The company has a large number of internal documents (HR policies, product manuals, technical Wiki). Employees often need to find information, but the documents are scattered and difficult to search.

Step 1: Prepare the Knowledge Base

1. Organize documents: export HR policies (PDF), product manuals (Word), and technical Wiki (Markdown) for use.
2. Under Knowledge, select Create Knowledge and name it "Company Internal Knowledge Base".
3. Upload files and select the high-quality indexing mode.
4. Wait for vectorization to complete (shown by progress bar).

Document quality optimization tips: remove irrelevant information, headers/footers, and special characters. Use clear headings and short paragraphs. If a document covers multiple different topics, consider splitting it into separate files.

Step 2: Create a Chatbot Application

1. Click Create App, select Chatbot, and name it "Internal Assistant".
2. Choose a model (Claude Sonnet 4.6 or GPT-4o recommended).
3. Write the System Prompt.

You are an internal company knowledge assistant, specifically helping employees find information in internal documents.

Code of conduct:
- Only answer based on the provided knowledge base content; do not fabricate information
- Cite the source document name when answering
- If the relevant information is not found in the knowledge base, directly say "I did not find the relevant information in the documents" and suggest contacting the corresponding department
- Use concise, professional language
- Do not discuss topics other than company confidential matters

1. In Context, click Add and select "Company Internal Knowledge Base".
2. Configure retrieval parameters: hybrid retrieval, similarity threshold 0.6, return Top 5 segments.

Step 3: Testing and Tuning

Test with real questions. Here are recommended test cases:

测试问题示例：
"年假怎么申请？" → 应该从 HR 政策文档返回正确步骤
"产品 A 的定价是多少？" → 应该从产品手册返回准确价格
"如何配置 VPN？" → 应该从技术 Wiki 返回步骤
"CEO 是谁？" → 如果文档中没有，应该诚实说不知道

Common tuning operations

Step 4: Publish and Integrate

Publish as a web app: On the app page, select Overview, click Embedded, copy the embed code, and paste it into an internal Wiki or intranet page.

Publish as API: On the app page, select API Reference, copy the API Key, and call the example:

# 调用聊天 API，向知识问答机器人发送问题
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "年假怎么申请？",
    "response_mode": "blocking",
    "user": "employee-001"
  }'

Hands-on Scenario 2: Automated Content Generation Pipeline

Use Workflow to generate marketing content for different channels in parallel.

Business Background

The marketing team needs to batch convert product update logs (technical language) into content for different channels: WeChat public account posts, technical blogs, and short video scripts.

Workflow Design

Start（输入：更新日志文本）
  ↓ 并行分支
  ├─→ LLM-1：生成微信推文（轻松活泼，500字，含表情符号）
  ├─→ LLM-2：生成技术博客（专业详细，1500字，含代码示例）
  └─→ LLM-3：生成短视频脚本（口语化，300字，分镜头格式）
  ↓ 合并
End（输出：三份内容）

Concrete Build Steps

Step 1: Create a Workflow app and name it "Content Generation Pipeline".

Step 2: Configure the Start node and add input variables:

Step 3: Add three LLM nodes (parallel).

Connect all three LLM nodes to the Start node, and Dify will execute them in parallel automatically.

LLM-1 (WeChat post) Prompt example:

你是一位擅长社交媒体写作的内容创作者。

请将以下 {{product_name}} v{{version}} 的更新日志改写成微信公众号推文：
- 字数：400-600字
- 语气：轻松活泼，贴近用户
- 结构：开头吸引眼球，中间介绍亮点，结尾引导互动
- 适当使用 emoji
- 不要使用技术术语，用用户能理解的语言

更新日志原文：
{{Start.update_content}}

LLM-2 (technical blog) and LLM-3 (short video script) are configured similarly; just adjust the Prompt and model.

Step 4: Add an End node and configure output variables:

wechat_post：引用 {{LLM-1.text}}
tech_blog：引用 {{LLM-2.text}}
video_script：引用 {{LLM-3.text}}

Step 5: Integrate into internal tools via API.

Hands-on Scenario 3: Customer Support Agent (with Human-in-the-Loop)

Build an intelligent customer service ticket processing system: AI automatically handles standard issues, and complex issues are routed to human agents with pre-analysis.

Business Background

An e-commerce platform receives 500+ customer service tickets per day on average; most are standard questions (logistics inquiries, return policies), but about 20% require manual handling (complex complaints, large refunds).

Workflow Design

Start（接收用户工单：问题类型 + 内容 + 订单号）
  ↓
LLM-分类：判断问题类型（standard / complex）
  ↓
IF/ELSE：问题类型是否为 standard？
  ├─ standard →
  │    Knowledge Retrieval（从客服知识库检索）
  │      ↓
  │    LLM-回复：生成标准回答
  │      ↓
  │    End（直接回复用户）
  │
  └─ complex →
       LLM-预分析：生成问题摘要和建议处理方案
         ↓
       Human Input（人工审核，可编辑 AI 建议，选择"批准"/"修改"/"升级"）
         ↓
       End（发送经过人工确认的回复）

Key Node Configuration

Classification LLM node (outputs structured JSON):

Human Input node configuration:

Expected Outcomes

External Publishing: API, Web Embedding, and MCP Server

Publishing Dify applications to external systems supports three methods: API calls, web embedding, and MCP servers.

Publish as API

Every Dify application automatically has a REST API. Go to the application page and select API Access to obtain it.

Chat application API call example:

# 调用聊天 API（流式返回模式）
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "你好",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-001"
  }'

Workflow application API call example:

# 调用 Workflow API（阻塞模式）
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  -H 'Authorization: Bearer {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {"your_variable": "your_value"},
    "response_mode": "blocking",
    "user": "user-001"
  }'

The API Key format starts with app-. Make sure to pass it in the request header as Authorization: Bearer, not as a query parameter. Each API Key corresponds to only one specific application, and keys for different applications are not interchangeable.

Web page embedding

On the application page, select Overview, click Embedded, and three embedding methods are provided:

Method 1: iframe embedding

Method 2: Bubble button (floating in the bottom-right corner of the web page)

Method 3: Full-screen web page, accessed independently, share the link directly: https://udify.app/chat/xxxxxxxx.

Publish as MCP server

Dify supports publishing built workflows or Agents as standard MCP servers, supporting pre-authorization and no-authentication modes.

This means: the knowledge base Q&A application you build in Dify can directly become a tool node for AI programming tools such as Claude Code, Cursor, omp, etc., seamlessly integrated into the development workflow.

Operation path: In the application, select Publish and click MCP Server.

Observability: monitoring and continuous optimization

Continuously monitor and optimize AI application performance through logs, annotations, statistics, and external platform integration.

View application logs

In the application page, select Logs to view the complete input/output of each conversation, token usage (input and output counted separately), response time, model, and parameter information.

Annotate conversations

In the logs, click a specific conversation, then click the like or dislike button next to the answer to add an ideal answer as an annotation.

Uses of annotation data include: building fine-tuning datasets from annotations, identifying coverage gaps in the knowledge base, and discovering frequently occurring error types.

Application data statistics

In the application page, select Overview and click Analytics to view:

Integrate external observability platforms

Dify supports observability platforms such as Opik, Langfuse, and Arize Phoenix.

Taking Langfuse as an example: In Settings, select Monitoring, choose Langfuse, enter the Public Key and Secret Key, then save. Afterward, the call chain of all applications will be automatically synced to Langfuse, where you can view complete span tracing and token cost details.

Continuous optimization loop

It is recommended to establish the following continuous optimization process:

部署上线
  ↓
收集对话日志（1-2 周）
  ↓
分析差评对话：哪些问题回答得不好？
  ↓
改进知识库（补充文档、调整分块）或优化 Prompt
  ↓
A/B 测试：对比改进前后的效果
  ↓
再次部署

Pricing and plans.

Understand the cost structures of Dify Cloud and self-hosting, and choose the option that best suits you.

Dify Cloud Plan

Self-hosting costs.

The self-hosted Community Edition is completely free with no usage restrictions.

You only need to pay for server hosting (a VPS costs about $5-50/month) and the API call fees for AI models.

Cost estimate (self-hosted, 10,000 conversations/month):

Compared to Dify Cloud Professional ($59/month, plus model API fees), self-hosting is usually more economical for heavy usage.

Tips for reducing costs

Common issues and troubleshooting

Covers troubleshooting methods for four major categories of common issues: startup, knowledge base retrieval, API calls, and workflows.

Startup issue

Issue: Services unhealthy after docker compose up -d

Problem: Accessing http://localhost shows 502 Bad Gateway

Knowledge base retrieval issues

Question: Relevant content cannot be found in the knowledge base.

Troubleshooting steps:

1. In the knowledge base, click Retrieval Testing, test specific questions, and confirm whether they can be retrieved.
2. If nothing is retrieved: lower the similarity threshold (from 0.6 to 0.3), and test whether there are any results.
3. If there is still no result: confirm that the Embedding model configuration is correct, and whether the knowledge base index has been completed.
4. If there are results but the content is incorrect: check the document chunking strategy, and consider manually splitting large files.

Problem: RAG returns irrelevant content.

Check the retrieved Chunk content. If the Chunk is irrelevant, reduce the chunk size and raise the score threshold. If no Chunk is returned, the threshold may be set too high; temporarily lower it to 0.3 and test again. Also confirm that the knowledge base has been linked in the application's orchestration panel.

API call issues

Problem: API returns 401 Unauthorized

Verify API Key format — Dify application API Keys start with app-. Ensure it is passed in the request header as Authorization: Bearer, not as a query parameter. Also confirm that this API Key belongs to the correct application — Keys are application-level, and Keys for different applications are not interchangeable.

Question: Streaming response truncated midway.

This is usually a timeout issue. Check the reverse proxy's timeout settings—Nginx defaults to 60 seconds, which may not be enough for complex workflows.

# nginx.conf 中增加超时配置，确保长时间运行的工作流不被中断
proxy_read_timeout 300s;
proxy_connect_timeout 300s;
proxy_send_timeout 300s;

Workflow issues.

Problem: A node in the workflow reported an error.

Troubleshooting steps:

1. Open the debug panel to view the input/output of the node that reported the error.
2. Click the red marker next to the node to view detailed error information.
3. Common cause: incorrect variable reference path (check the spelling of {{node name.variable name}})

Resources

Recommended learning paths and related resources to help you go from beginner to mastery.

Recommended learning path

注册 Dify Cloud，用 Sandbox 体验
    ↓
配置自己的模型提供商（Anthropic 或 OpenAI）
    ↓
创建第一个知识库，上传 5-10 个文档，测试检索效果
    ↓
创建 Chatbot 应用，关联知识库，完成场景实战一
    ↓
学习 Workflow，完成场景实战二（内容生成流水线）
    ↓
探索 Human Input 节点，完成场景实战三（客服 Agent）
    ↓
用 Docker Compose 搭建本地/服务器自托管版本
    ↓
通过 API 将 Dify 应用集成到现有系统
    ↓
探索 MCP Server 发布，接入 AI 编程工具生态

Official resources