diff --git a/en/.gitbook/assets/Q&A-pair.png b/en/.gitbook/assets/Q&A-pair.png new file mode 100644 index 0000000..362d938 Binary files /dev/null and b/en/.gitbook/assets/Q&A-pair.png differ diff --git a/en/.gitbook/assets/api_based (1).png b/en/.gitbook/assets/api_based (1).png new file mode 100644 index 0000000..18f2357 Binary files /dev/null and b/en/.gitbook/assets/api_based (1).png differ diff --git a/en/.gitbook/assets/create-knowledge-2.png b/en/.gitbook/assets/create-knowledge-2.png new file mode 100644 index 0000000..95de792 Binary files /dev/null and b/en/.gitbook/assets/create-knowledge-2.png differ diff --git a/en/.gitbook/assets/create-knowledge.png b/en/.gitbook/assets/create-knowledge.png new file mode 100644 index 0000000..8de9508 Binary files /dev/null and b/en/.gitbook/assets/create-knowledge.png differ diff --git a/en/.gitbook/assets/custom-chunk-settings.png b/en/.gitbook/assets/custom-chunk-settings.png new file mode 100644 index 0000000..54dd62e Binary files /dev/null and b/en/.gitbook/assets/custom-chunk-settings.png differ diff --git a/en/.gitbook/assets/full-text-search.png b/en/.gitbook/assets/full-text-search.png new file mode 100644 index 0000000..f8ca634 Binary files /dev/null and b/en/.gitbook/assets/full-text-search.png differ diff --git a/en/.gitbook/assets/hybrid-search.png b/en/.gitbook/assets/hybrid-search.png new file mode 100644 index 0000000..aaeb875 Binary files /dev/null and b/en/.gitbook/assets/hybrid-search.png differ diff --git a/en/.gitbook/assets/image (109).png b/en/.gitbook/assets/image (109).png new file mode 100644 index 0000000..c981540 Binary files /dev/null and b/en/.gitbook/assets/image (109).png differ diff --git a/en/.gitbook/assets/image (110).png b/en/.gitbook/assets/image (110).png new file mode 100644 index 0000000..2004039 Binary files /dev/null and b/en/.gitbook/assets/image (110).png differ diff --git a/en/.gitbook/assets/image (116).png b/en/.gitbook/assets/image (116).png new file mode 100644 index 0000000..931081a Binary files /dev/null and b/en/.gitbook/assets/image (116).png differ diff --git a/en/.gitbook/assets/image (118).png b/en/.gitbook/assets/image (118).png new file mode 100644 index 0000000..fa26086 Binary files /dev/null and b/en/.gitbook/assets/image (118).png differ diff --git a/en/.gitbook/assets/image (122).png b/en/.gitbook/assets/image (122).png new file mode 100644 index 0000000..e6b588e Binary files /dev/null and b/en/.gitbook/assets/image (122).png differ diff --git a/en/.gitbook/assets/image (173).png b/en/.gitbook/assets/image (173).png new file mode 100644 index 0000000..87b772c Binary files /dev/null and b/en/.gitbook/assets/image (173).png differ diff --git a/en/.gitbook/assets/image (191).png b/en/.gitbook/assets/image (191).png new file mode 100644 index 0000000..575c375 Binary files /dev/null and b/en/.gitbook/assets/image (191).png differ diff --git a/en/.gitbook/assets/q2p-and-q2q.png b/en/.gitbook/assets/q2p-and-q2q.png new file mode 100644 index 0000000..b701715 Binary files /dev/null and b/en/.gitbook/assets/q2p-and-q2q.png differ diff --git a/en/.gitbook/assets/vector-search.png b/en/.gitbook/assets/vector-search.png new file mode 100644 index 0000000..f38b5a6 Binary files /dev/null and b/en/.gitbook/assets/vector-search.png differ diff --git a/en/.gitbook/assets/weather inquiry.png b/en/.gitbook/assets/weather inquiry.png new file mode 100644 index 0000000..6852b6b Binary files /dev/null and b/en/.gitbook/assets/weather inquiry.png differ diff --git a/en/.gitbook/assets/zeabur-project.png b/en/.gitbook/assets/zeabur-project.png deleted file mode 100644 index 4c6a52b..0000000 Binary files a/en/.gitbook/assets/zeabur-project.png and /dev/null differ diff --git a/en/.gitbook/assets/zeabur-region-select.png b/en/.gitbook/assets/zeabur-region-select.png deleted file mode 100644 index 2668649..0000000 Binary files a/en/.gitbook/assets/zeabur-region-select.png and /dev/null differ diff --git a/en/.gitbook/assets/zeabur-template-overview.jpeg b/en/.gitbook/assets/zeabur-template-overview.jpeg deleted file mode 100644 index c30cf06..0000000 Binary files a/en/.gitbook/assets/zeabur-template-overview.jpeg and /dev/null differ diff --git a/en/SUMMARY.md b/en/SUMMARY.md index ff7a949..27479bc 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -2,117 +2,126 @@ ## Getting Started -* [Welcome to Dify!](README.md) - * [Technical Spec](getting-started/readme/specifications-and-technical-features.md) - * [Model Providers](getting-started/readme/model-providers.md) -* [Using Dify Cloud](getting-started/cloud.md) -* [Install (Self hosted)](getting-started/install-self-hosted/README.md) - * [Docker Compose Deployment](getting-started/install-self-hosted/docker-compose.md) - * [Local Source Code Start](getting-started/install-self-hosted/local-source-code.md) - * [Start the frontend Docker container separately](getting-started/install-self-hosted/start-the-frontend-docker-container.md) - * [Environments](getting-started/install-self-hosted/environments.md) - * [FAQ](getting-started/install-self-hosted/install-faq.md) -* [What is LLMOps?](getting-started/what-is-llmops.md) +* [Welcome to Dify](README.md) + * [Features and Specifications](getting-started/readme/features-and-specifications.md) + * [List of Model Providers](getting-started/readme/model-providers.md) +* [Cloud Services](getting-started/cloud.md) +* [Community Edition](getting-started/install-self-hosted/README.md) + * [Deploy with Docker Compose](getting-started/install-self-hosted/docker-compose.md) + * [Start with Local Source Code](getting-started/install-self-hosted/local-source-code.md) + * [Start Frontend Docker Container Separately](getting-started/install-self-hosted/start-the-frontend-docker-container.md) + * [Environment Variables Explanation](getting-started/install-self-hosted/environments.md) -## User Guide +## Guides -* [Creating Dify Apps](user-guide/creating-dify-apps/README.md) - * [Quickstart](user-guide/creating-dify-apps/creating-an-application.md) - * [Overview](user-guide/creating-dify-apps/overview.md) - * [Setting Prompts](user-guide/creating-dify-apps/prompt-engineering/README.md) - * [Agent Assistant](user-guide/creating-dify-apps/prompt-engineering/agent-assistant.md) - * [Chat App](user-guide/creating-dify-apps/prompt-engineering/conversation-application.md) - * [Text Generator](user-guide/creating-dify-apps/prompt-engineering/text-generation-application.md) - * [FAQ](user-guide/creating-dify-apps/llms-use-faq.md) - * [Use Cases](user-guide/creating-dify-apps/use-cases/README.md) - * [Notion AI Assistant Based on Your Own Notes](user-guide/creating-dify-apps/use-cases/build-an-notion-ai-assistant.md) - * [AI ChatBot with Business Data](user-guide/creating-dify-apps/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md) - * [Midjourney Prompt Bot](user-guide/creating-dify-apps/use-cases/create-a-midjourney-prompt-bot-with-dify.md) -* [Launching Dify Apps](user-guide/launching-dify-apps/README.md) - * [Quickstart](user-guide/launching-dify-apps/launch-webapp.md) - * [Developing with APIs](user-guide/launching-dify-apps/developing-with-apis/README.md) - * [FAQ](user-guide/launching-dify-apps/developing-with-apis/api-use-faq.md) -* [Using Dify Apps](user-guide/using-dify-apps/README.md) - * [Text Generator](user-guide/using-dify-apps/text-generator.md) - * [Chat App](user-guide/using-dify-apps/conversation-application.md) - * [Further Chat App Settings](user-guide/using-dify-apps/chat.md) - -## Features - -* [Prompting Expert Mode](features/prompt-engineering/README.md) - * [Prompt Template](features/prompt-engineering/prompt-template.md) -* [Workflow](features/workflow/README.md) - * [Introduce](features/workflow/introduce.md) - * [Key Concept](features/workflow/key-concept.md) - * [Nodes](features/workflow/node/README.md) - * [Start](features/workflow/node/start.md) - * [End](features/workflow/node/end.md) - * [Answer](features/workflow/node/answer.md) - * [LLM](features/workflow/node/llm.md) - * [Knowledge Retrieval](features/workflow/node/knowledge-retrieval.md) - * [Question Classifier](features/workflow/node/question-classifier.md) - * [IF/ELSE](features/workflow/node/if-else.md) - * [Code](features/workflow/node/code.md) - * [Template](features/workflow/node/template.md) - * [Variable Assigner](features/workflow/node/variable-assigner.md) - * [HTTP Request](features/workflow/node/http-request.md) - * [Tools](features/workflow/node/tools.md) - * [Preview\&Run](features/workflow/preview-and-run/README.md) - * [Preview\&Run](features/workflow/preview-and-run/preview-and-run.md) - * [Step Test](features/workflow/preview-and-run/step-test.md) - * [Log](features/workflow/preview-and-run/log.md) - * [Checklist](features/workflow/preview-and-run/checklist.md) - * [History](features/workflow/preview-and-run/history.md) - * [Publish](features/workflow/publish.md) - * [Export/Import](features/workflow/export-import.md) -* [RAG (Retrieval Augmented Generation)](features/retrieval-augment/README.md) - * [Hybrid Search](features/retrieval-augment/hybrid-search.md) - * [Rerank](features/retrieval-augment/rerank.md) - * [Retrieval](features/retrieval-augment/retrieval.md) -* [Knowledge Import](features/datasets/README.md) - * [Sync from Notion](features/datasets/sync-from-notion.md) - * [Maintain Knowledge Via Api](features/datasets/maintain-dataset-via-api.md) -* [External Data Tool](features/external\_data\_tool.md) -* [Annotation Reply](features/annotation-reply.md) -* [Logs & Annotations](features/logs.md) -* [Plugins](features/ai-plugins/README.md) - * [Based on WebApp Template](features/ai-plugins/based-on-frontend-templates.md) -* [More Integration](features/more-integration.md) -* [Extension](features/extension/README.md) - * [API Based Extension](features/extension/api\_based\_extension/README.md) - * [External\_data\_tool](features/extension/api\_based\_extension/external\_data\_tool.md) - * [Moderation Extension](features/extension/api\_based\_extension/moderation-extension.md) - * [Code-based Extension](features/extension/code-based-extension.md) -* [Moderation](features/moderation\_tool.md) - -## workspace - -* [Discovery](workspace/app.md) -* [Billing](workspace/billing.md) - -## Tutorials - -* [Quick Tool Integration](tutorials/quick-tool-integration.md) -* [Advanced Tool Integration](tutorials/advanced-tool-integration.md) -* [Expose API Extension on public Internet using Cloudflare Workers](tutorials/cloudflare\_workers.md) -* [Connecting with Different Models](tutorials/model-configuration/README.md) - * [Hugging Face](tutorials/model-configuration/hugging-face.md) - * [Replicate](tutorials/model-configuration/replicate.md) - * [Xinference](tutorials/model-configuration/xinference.md) - * [OpenLLM](tutorials/model-configuration/openllm.md) - * [LocalAI](tutorials/model-configuration/localai.md) - * [Ollama](tutorials/model-configuration/ollama.md) -* [Vector Database Migrate Tool](tutorials/vector-database-migrate-tool.md) -* [Connecting with Different Tools](tutorials/tool-configuration/README.md) - * [Stable Diffusion](tutorials/tool-configuration/stable-diffusion.md) - * [SearXNG](tutorials/tool-configuration/searxng.md) +* [Model](guides/model-configuration/README.md) + * [Add New Provider](guides/model-configuration/new-provider.md) + * [Predefined Model Integration](guides/model-configuration/predefined-model.md) + * [Custom Model Integration](guides/model-configuration/customizable-model.md) + * [Integrate Open Source Models from Hugging Face](guides/model-configuration/hugging-face.md) + * [Integrate Open Source Models from Replicate](guides/model-configuration/replicate.md) + * [Integrate Local Models Deployed by Xinference](guides/model-configuration/xinference.md) + * [Integrate Local Models Deployed by OpenLLM](guides/model-configuration/openllm.md) + * [Integrate Local Models Deployed by LocalAI](guides/model-configuration/localai.md) + * [Integrate Local Models Deployed by Ollama](guides/model-configuration/ollama.md) + * [Load Balancing](guides/model-configuration/load-balancing.md) +* [Application Orchestration](guides/application-orchestrate/README.md) + * [Create Application](guides/application-orchestrate/creating-an-application.md) + * [Conversation Assistant](guides/application-orchestrate/conversation-application.md) + * [Agent](guides/application-orchestrate/agent.md) + * [Application Toolkits](guides/application-orchestrate/app-toolkits/README.md) + * [Moderation Tool](guides/application-orchestrate/app-toolkits/moderation-tool.md) +* [Workflow](guides/workflow/README.md) + * [Key Concepts](guides/workflow/key-concept.md) + * [Node Description](guides/workflow/node/README.md) + * [Start](guides/workflow/node/start.md) + * [End](guides/workflow/node/end.md) + * [Direct Reply](guides/workflow/node/answer.md) + * [LLM](guides/workflow/node/llm.md) + * [Knowledge Retrieval](guides/workflow/node/knowledge-retrieval.md) + * [Question Classifier](guides/workflow/node/question-classifier.md) + * [Conditional Branch IF/ELSE](guides/workflow/node/ifelse.md) + * [Code Execution](guides/workflow/node/code.md) + * [Template](guides/workflow/node/template.md) + * [Variable Aggregator](guides/workflow/node/variable-assigner.md) + * [Iteration](guides/workflow/node/iteration.md) + * [Parameter Extraction](guides/workflow/node/parameter-extractor.md) + * [HTTP Request](guides/workflow/node/http-request.md) + * [Tools](guides/workflow/node/tools.md) + * [Debug and Preview](guides/workflow/debug-and-preview/README.md) + * [Preview and Run](guides/workflow/debug-and-preview/yu-lan-yu-yun-hang.md) + * [Step Run](guides/workflow/debug-and-preview/step-run.md) + * [Conversation/Run Logs](guides/workflow/debug-and-preview/log.md) + * [Checklist](guides/workflow/debug-and-preview/checklist.md) + * [Run History](guides/workflow/debug-and-preview/history.md) + * [Application Publishing](guides/workflow/publish.md) +* [Knowledge Base](guides/knowledge-base/README.md) + * [Create Knowledge Base & Upload Documents](guides/knowledge-base/create-knowledge-and-upload-documents.md) + * [Knowledge Base and Document Maintenance](guides/knowledge-base/knowledge-and-documents-maintenance.md) + * [Integrate Knowledge Base within Application](guides/knowledge-base/integrate-knowledge-within-application.md) + * [Retrieval Test/Citation](guides/knowledge-base/retrieval-test-and-citation.md) + * [Sync Data from Notion](guides/knowledge-base/sync-from-notion.md) + * [Sync Data from Website](guides/knowledge-base/sync-from-website.md) + * [Maintain Knowledge Base via API](guides/knowledge-base/maintain-dataset-via-api.md) + * [External Data Tool](guides/knowledge-base/external-data-tool.md) + +* [Tools](guides/tools/README.md) + * [Quick Tool Integration](guides/tools/quick-tool-integration.md) + * [Advanced Tool Integration](guides/tools/advanced-tool-integration.md) + * [Tool Configuration](guides/tools/tool-configuration/README.md) + * [StableDiffusion](guides/tools/tool-configuration/stable-diffusion.md) + * [SearXNG](guides/tools/tool-configuration/searxng.md) +* [Publishing](guides/application-publishing/README.md) + * [Launch Your Webapp Quickly](guides/application-publishing/launch-your-webapp-quickly/README.md) + * [Web App Settings](guides/application-publishing/launch-your-webapp-quickly/web-app-settings.md) + * [Text Generator Application](guides/application-publishing/launch-your-webapp-quickly/text-generator.md) + * [Conversation Application](guides/application-publishing/launch-your-webapp-quickly/conversation-application.md) + * [Developing with APIs](guides/application-publishing/developing-with-apis.md) + * [Re-develop Based on Frontend Templates](guides/application-publishing/based-on-frontend-templates.md) +* [Annotation](guides/biao-zhu/README.md) + * [Logs and Annotation](guides/biao-zhu/logs.md) + * [Annotation Reply](guides/biao-zhu/annotation-reply.md) +* [Monitoring](guides/monitoring/README.md) + * [Data Analysis](guides/monitoring/analysis.md) + * [Integrate External Ops Tools](guides/monitoring/integrate-external-ops-tools/README.md) + * [Integrate LangSmith](guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md) + * [Integrate LangFuse](guides/monitoring/integrate-external-ops-tools/integrate-langfuse.md) +* [Extension](guides/extension/README.md) + * [API-Based Extension](guides/extension/api-based-extension/README.md) + * [External Data Tool](guides/extension/api-based-extension/external-data-tool.md) + * [Deploy API Tools with Cloudflare Workers](guides/extension/api-based-extension/cloudflare-workers.md) + * [Moderation](guides/extension/api-based-extension/moderation.md) + * [Code-Based Extension](guides/extension/code-based-extension/README.md) + * [External Data Tool](guides/extension/code-based-extension/external-data-tool.md) + * [Moderation](guides/extension/code-based-extension/moderation.md) +* [Collaboration](guides/workspace/README.md) + * [Discover](guides/workspace/app/README.md) + * [Invite and Manage Members](guides/workspace/invite-and-manage-members.md) ## Community -* [Contributing](community/contributing.md) -* [Support](community/support.md) +* [Seek Support](community/support.md) +* [Become a Contributor](community/contribution.md) -## User Agreement +## Learn More -* [Open-Source License](user-agreement/open-source.md) -* [Data Security](user-agreement/data-security.md) +* [Use Cases](learn-more/use-cases/README.md) + * [Build a Notion AI Assistant](learn-more/use-cases/build-an-notion-ai-assistant.md) + * [Create a MidJourney Prompt Bot with Dify](learn-more/use-cases/create-a-midjourney-prompt-bot-with-dify.md) + * [Create an AI Chatbot with Business Data in Minutes](learn-more/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md) +* [Extended Reading](learn-more/extended-reading/README.md) + * [What is LLMOps?](learn-more/extended-reading/what-is-llmops.md) + * [Retrieval-Augmented Generation (RAG)](learn-more/extended-reading/retrieval-augment/README.md) + * [Hybrid Search](learn-more/extended-reading/retrieval-augment/hybrid-search.md) + * [Re-ranking](learn-more/extended-reading/retrieval-augment/rerank.md) + * [Retrieval Modes](learn-more/extended-reading/retrieval-augment/retrieval.md) +* [FAQ](learn-more/faq/README.md) + * [Self-Host Related](learn-more/faq/self-host-faq.md) + * [LLM Configuration and Usage](learn-more/faq/use-llms-faq.md) + +## Policies + +* [Open Source License](policies/open-source.md) +* [User Agreement](policies/agreement/README.md) + * [Terms of Service](https://dify.ai/terms) + * [Privacy Policy](https://dify.ai/privacy) \ No newline at end of file diff --git a/en/community/contributing.md b/en/community/contribution.md similarity index 100% rename from en/community/contributing.md rename to en/community/contribution.md diff --git a/en/explore/images/creat-customize-app.jpg b/en/explore/images/creat-customize-app.jpg deleted file mode 100644 index de281f9..0000000 Binary files a/en/explore/images/creat-customize-app.jpg and /dev/null differ diff --git a/en/explore/images/explore-app.jpg b/en/explore/images/explore-app.jpg deleted file mode 100644 index dd6ecde..0000000 Binary files a/en/explore/images/explore-app.jpg and /dev/null differ diff --git a/en/explore/images/workspace.jpg b/en/explore/images/workspace.jpg deleted file mode 100644 index f39070d..0000000 Binary files a/en/explore/images/workspace.jpg and /dev/null differ diff --git a/en/features/ai-plugins/README.md b/en/features/ai-plugins/README.md deleted file mode 100644 index 9f5186a..0000000 --- a/en/features/ai-plugins/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Plugins - -{% hint style="info" %} -Plugins is an upcoming feature of Dify. You can incorporate plugins into your App orchestration and access AI applications with plugin capabilities through an API or WebApp. Dify is compatible with the ChatGPT Plugins standard and provides some native plugins. -{% endhint %} diff --git a/en/features/datasets/README.md b/en/features/datasets/README.md deleted file mode 100644 index c8de3c8..0000000 --- a/en/features/datasets/README.md +++ /dev/null @@ -1,134 +0,0 @@ -# Knowledge Import - -Most language models use outdated training data and have length limitations for the context of each request. For example, GPT-3.5 is trained on corpora from 2021 and has a limit of approximately 4k tokens per request. This means that developers who want their AI applications to be based on the latest and private context conversations must use techniques like embedding. - -Dify' knowledge feature allows developers (and even non-technical users) to easily manage knowledge and automatically integrate them into AI applications. All you need to do is prepare text content, such as: - -* Long text content (TXT, Markdown, DOCX, HTML, JSONL, or even PDF files) -* Structured data (CSV, Excel, etc.) - -Additionally, we are gradually supporting syncing data from various data sources to knowledge, including: - -* GitHub -* Databases -* Webpages -* ... - -{% hint style="info" %} -**Practice**: If your company wants to build an AI customer service assistant based on existing knowledge bases and product documentation, you can upload the documents to a knowledge base in Dify and create a conversational application. This might have taken you several weeks in the past and been difficult to maintain continuously. -{% endhint %} - -### Knowledge and Documents - -In Dify, knowledge bases are collections of documents. A knowledge base can be integrated as a whole into an application to be used as context. Documents can be uploaded by developers or operations staff, or synced from other data sources (typically corresponding to a file unit in the data source). - -**Steps to upload a document:** - -1. Upload your file, usually a long text file or a spreadsheet -2. Segment, clean, and preview -3. Dify submits it to the LLM provider for embedding as vector data and storage -4. Set metadata for the document -5. Ready to use in the application! - -#### How to write a good knowledge description - -When multiple knowledge bases are referenced in an application, AI uses the description of the knowledge and the user's question to determine which knowledge base to use to answer the user's question. Therefore, a well-written knowledge description can improve the accuracy of AI in selecting knowledge. - -The key to writing a good knowledge description is to clearly describe the content and characteristics of the knowledge. **It is recommended that the knowledge description begin with this: `Useful only when the question you want to answer is about the following: specific description`**. Here is an example of a real estate knowledge description: - -> Useful only when the question you want to answer is about the following: global real estate market data from 2010 to 2020. This data includes information such as the average housing price, property sales volume, and housing types for each city. In addition, this knowledge base also includes some economic indicators such as GDP and unemployment rate, as well as some social indicators such as population and education level. These indicators can help analyze the trends and influencing factors of the real estate market. With this data, we can understand the development trends of the global real estate market, analyze the changes in housing prices in various cities, and understand the impact of economic and social factors on the real estate market. - -### Create a knowledge - -1. Click on knowledge in the main navigation bar of Dify. On this page, you can see the existing knowledge bases. Click on "Create Knowledge" to enter the creation wizard. -2. If you have already prepared your files, you can start by uploading the files. -3. If you haven't prepared your documents yet, you can create an empty knowledge base first. - -### Uploading Documents By upload file - -1. Select the file you want to upload.We support batch uploads -2. Preview the full text -3. Perform segmentation and cleaning -4. Wait for Dify to process the data for you; this step usually consumes tokens in the LLM provider - -### Text Preprocessing and Cleaning - -Text Preprocessing and cleaning refers to Dify automatically segmenting and vectorizing your data documents so that user's questions (input) can match relevant paragraphs (Q to P), and generate results. - -When uploading a knowledge base, you need to select a **indexing mode** to specify how data is matched. This affects the accuracy of AI replies. - -In **High Quality mode**, OpenAI's embedding API is used for higher accuracy in user queries. - -In **Economic mode**, offline vector engines, keyword indexing etc. are used to reduce costs at the expense of lower accuracy. - -In **Segmenting in Question & Answer format**, instead of normal "Q to P" (question matches paragraphs), it uses "Q to Q" (question matches question) matching. After segmentation, Q\&A pairs are generated for each passage. When users ask questions, the system finds the most similar question and returns the corresponding passage as the answer. This is more precise because it directly matches the user's question and retrieves the information they need. - -> Questions have complete syntax while keywords lack semantics and context. So Q to Q improves clarity and handles similar high-frequency questions better. - -

In Segmenting in Question & Answer format, the text is summarized into multiple QA pairs

- -

The difference between Q to P and Q to Q indexing modes

- -### Modify Documents - -Modify Documents For technical reasons, if developers make the following changes to documents, Dify will create a new document for you, and the old document will be archived and deactivated: - -1. Adjust segmentation and cleaning settings -2. Re-upload the file - -Dify support customizing the segmented and cleaned text by adding, deleting, and editing paragraphs. You can dynamically adjust your segmentation to make your knowledge more accurate. Click **Document --> paragraph --> Edit** in the knowledge to modify paragraphs content and custom keywords. Click **Document --> paragraph --> Add segment --> Add a segment** to manually add new paragraph. Or click **Document --> paragraph --> Add segment --> Batch add** to batch add new paragraph. - -

Edit

- -

add

- -### Disabling and Archiving of Documents - -* **Disable, cancel disable**: The knowledge supports disabling documents or chunks that you temporarily do not want indexed. In the knowledge's document list, click the Disable button and the document will be disabled. You can also click the Disable button in the document details to disable the entire document or a segment. Disabled documents will not be indexed. To cancel the disable, click Enable on a disabled document. -* **Archive, Unarchive:** Some unused old document data can be archived if you don't want to delete it. After archiving, the data can only be viewed or deleted, not edited. In the document list of the knowledge, click the Archive button to archive the document. Documents can also be archived in the document details page. Archived documents will not be indexed. Archived documents can also be unarchived by clicking the Unarchive button. - -### Maintain Knowledge via API - -Head to [maintain-dataset-via-api.md](maintain-dataset-via-api.md "mention"). - -### Knowledge Settings - -Click **Settings** in the left navigation of the knowledge. You can change the following settings for the knowledge: - -* Knowledge **name** for identifying a knowledge base -* Knowledge **description** to allow AI to better use the knowledge appropriately. If the description is empty, Dify's automatic indexing strategy will be used. -* **Permissions** can be set to Only Me or All Team Members. Those without permissions cannot view and edit the knowledge. -* **Indexing mode**: In High Quality mode, OpenAI's embedding interface will be called to process and provide higher accuracy when users query. In Economic mode, offline vector engines, keyword indexing, etc. will be used to reduce accuracy without consuming tokens. - -Note: Upgrading the indexing mode from Economic to High Quality will incur additional token consumption. Downgrading from High Quality to Economic will not consume tokens. - -### Integrate into Applications - -Once the knowledge base is ready, it needs to be integrated into the application. When the AI application processes will automatically use the associated knowledge content as a reference context. - -1. Go to the application - Prompt Arrangement page -2. In the context options, select the knowledge you want to integrate -3. Save the settings to complete the integration - -### Q\&A - -**Q: What should I do if the PDF upload is garbled?** - -A: If your PDF parsing appears garbled under certain formatted contents, you could consider converting the PDF to Markdown format, which currently offers higher accuracy, or you could reduce the use of images, tables, and other formatted content in the PDF. We are researching ways to optimize the experience of using PDFs. - -**Q: How does the consumption mechanism of context work?** A: With a knowledge base added, each query will consume segmented content (currently embedding two chunks) + question + prompt + chat history combined. However, it will not exceed model limitations, such as 4096. - -**Q: Where does the embedded knowledge appear when asking questions?** A: It will be embedded as context before the question. - -**Q: Is there any priority between the added knowledge and OpenAI's answers?** A: The knowledge serves as context and is used together with questions for LLM to understand and answer; there is no priority relationship. - -**Q: Why can I hit in test but not in application?** A: You can troubleshoot issues by following these steps: - -1. Make sure you have added text on the prompt page and clicked on the save button in the top right corner. -2. Test whether it responds normally in the prompt debugging interface. -3. Try again in a new WebApp session window. -4. Optimize your data format and quality. For practice reference, visit [https://github.com/langgenius/dify/issues/90](https://github.com/langgenius/dify/issues/90) If none of these steps solve your problem, please join our community for help. - -**Q: Will APIs related to hit testing be opened up so that dify can access knowledge bases and implement dialogue generation using custom models?** A: We plan to open up Webhooks later on; however, there are no current plans for this feature. You can achieve your requirements by connecting to any vector database. - -**Q: How do I add multiple knowledge bases?** A: Due to short-term performance considerations, we currently only support one knowledge base. If you have multiple sets of data, you can upload them within the same knowledge base for use. diff --git a/en/features/datasets/sync-from-notion.md b/en/features/datasets/sync-from-notion.md deleted file mode 100644 index 3d2c4d2..0000000 --- a/en/features/datasets/sync-from-notion.md +++ /dev/null @@ -1,74 +0,0 @@ -# Sync from Notion - -Dify knowledge supports importing from Notion and setting up **Sync** so that data is automatically synced to Dify after updates in Notion. - -### Authorization verification - -1. When creating a knowledge base, select the data source, click **Sync from Notion--Go to connect**, and complete the authorization verification according to the prompt. -2. You can also: click **Settings--Data Sources--Add a Data Source**, click Notion Source **Connect** to complete authorization verification. - -

Connect Notion

- -### Import Notion data - -After completing authorization verification, go to the knowledge creation page, click **Sync from Notion**, and select the required authorization page to import. - -### Segmentation and cleaning - -Next, select your **segmentation settings** and **indexing method**, **save and process**. Wait for Dify to process this data, usually this step requires token consumption in LLM providers. Dify not only supports importing ordinary page types but also summarizes and saves the page attributes under the database type. - -_**Note: Images and files are not currently supported for import. Table data will be converted to text.**_ - -### Sync Notion data - -If your Notion content has been modified, you can click Sync directly on the Dify knowledge document list page to sync the data with one click(Please note that each time you click, the current content will be synchronized). This step requires token consumption. - -

Sync Notion data

- -### (Community Edition) Notion Integration Configuration Guide - -Notion integration is divided into two ways: **internal integration** and **public integration** . It can be configured in Dify on demand. - -For the specific differences between the two integration methods, please refer to the [official doc of Notion](https://developers.notion.com/docs/authorization). - -#### 1. **Use internal integration** - -Create an integration in your [integration's settings](https://www.notion.so/my-integrations) page. By default, all integrations start with an internal integration; internal integrations will be associated with a workspace of your choice, so you need to be the workspace owner to create an integration. - -**Specific operation steps:** - -Click the " **New integration** " button, the type is Internal by default (cannot be modified), select the associated space, enter the name and upload the logo, and click "**Submit**" to create the integration successfully. - -
- -Once the integration is created, you can update its settings as needed under the **Capabilities** tab and click the "**Show**" button under **Secrets** and then copy the Secrets. - -
- -Copy it and back to the Dify source code , in the **.env** file configuration related environment variables, environment variables as follows: - -**NOTION\_INTEGRATION\_TYPE** = internal or **NOTION\_INTEGRATION\_TYPE** = public - -**NOTION\_INTERNAL\_SECRET**=you-internal-secret - -#### 2. **Use public integration** - -**You need to upgrade the internal integration to public integration** , navigate to the integrated Distribution page, and toggle the switch to expose the integration. - -To toggle the switch to public settings, you need to **fill in additional information in the Organization Information** form below, including your company name, website, and Retargeting URL, and click the "Submit" button. - -
- -After your integration has been successfully made public in your [integration’s settings page](https://www.notion.so/my-integrations), you will be able to access the integration’s secrets in the Secrets tab. - -
- -Back to the Dify source code , in the **.env** file configuration related environment variables , environment variables as follows: - -**NOTION\_INTEGRATION\_TYPE**=public - -**NOTION\_CLIENT\_SECRET**=you-client-secret - -**NOTION\_CLIENT\_ID**=you-client-id - -Once configured, you will be able to utilize Notion data import and sync functions in the knowledge section. diff --git a/en/features/extension/api_based_extension/external_data_tool.md b/en/features/extension/api_based_extension/external_data_tool.md deleted file mode 100644 index 1b2b09a..0000000 --- a/en/features/extension/api_based_extension/external_data_tool.md +++ /dev/null @@ -1,62 +0,0 @@ -# External\_data\_tool - -When creating AI applications, developers can use API extensions to incorporate additional data from external tools into prompts as supplementary information for LLMs. - -Please read [.](./ "mention") to complete the development and integration of basic API service capabilities. - -### Extension Point - -`app.external_data_tool.query`: Apply external data tools to query extension points. - -This extension point takes the application variable content passed in by the end user and the input content (fixed parameters for conversational applications) as parameters to the API. Developers need to implement the query logic for the corresponding tool and return the query results as a string type. - -#### Request Body - -```json -{ - "point": "app.external_data_tool.query", - "params": { - "app_id": string, - "tool_variable": string, - "inputs": { - "var_1": "value_1", - "var_2": "value_2", - ... - }, - "query": string | null - } -} -``` - -* Example - -```json -{ - "point": "app.external_data_tool.query", - "params": { - "app_id": "61248ab4-1125-45be-ae32-0ce91334d021", - "tool_variable": "weather_retrieve", - "inputs": { - "location": "London" - }, - "query": "How's the weather today?" - } -} -``` - -#### API Response - -```json -{ - "result": string -} -``` - -* Example - -```json -{ - "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain" -} -``` - diff --git a/en/features/extension/code-based-extension.md b/en/features/extension/code-based-extension.md deleted file mode 100644 index 7df83f4..0000000 --- a/en/features/extension/code-based-extension.md +++ /dev/null @@ -1,8 +0,0 @@ -# Code-based Extension - -For developers deploying Dify locally who wish to implement extension capabilities, there is no need to rewrite an API service. Instead, they can use Code-based Extension, which allows for the expansion or enhancement of the program's capabilities in the form of code (i.e., plugin capabilities) on top of Dify's existing features, without disrupting the original code logic of Dify. It follows certain interfaces or specifications to ensure compatibility and pluggability with the main program. Currently, Dify has opened up two types of Code-based Extensions, which are: - -* Add a new type of external data tool -* Expand sensitive content review policies - -On the basis of the above functions, you can follow the specifications of the code-level interface to achieve the purpose of horizontal expansion. diff --git a/en/features/external_data_tool.md b/en/features/external_data_tool.md deleted file mode 100644 index ecaf71d..0000000 --- a/en/features/external_data_tool.md +++ /dev/null @@ -1,30 +0,0 @@ -# External Data Tool - -Previously, [datasets](datasets/ "mention") allowed developers to directly upload long texts in various formats and structured data to build knowledge, enabling AI applications to converse based on the latest context uploaded by users. With this update, the external data tool empowers developers to use their own search capabilities or external data such as internal knowledge bases as the context for LLMs. This is achieved by extending APIs to fetch external data and embedding it into Prompts. Compared to uploading knowledge to the cloud, using external data tools offers significant advantages in ensuring the security of private data, customizing searches, and obtaining real-time data. - -## What does it do? - -When end-users make a request to the conversational system, the platform backend triggers the external data tool (i.e., calling its own API), which queries external information related to the user's question, such as employee profiles, real-time records, etc. The tool then returns through the API the portions relevant to the current request. The platform backend will assemble the returned results into text as context injected into the Prompt, in order to produce replies that are more personalized and meet user needs more accurately. - -## Quick Start - -1. Before using the external data tool, you need to prepare an API and an API Key for authentication. Head to [external\_data\_tool.md](extension/api\_based\_extension/external\_data\_tool.md "mention"). -2. Dify offers centralized API management; After adding API extension configurations in the settings interface, they can be directly utilized across various applications on Dify. - -

API-based Extension

- -3. Taking "Query Weather" as an example, enter the name, API endpoint, and API Key in the "Add New API-based Extension" dialog box. After saving, we can then call the API. - -

Weather Inquiry

- -4. On the prompt orchestration page, click the "+ Add" button to the right of "Tools," and in the "Add Tool" dialog that opens, fill in the name and variable name (the variable name will be referenced in the Prompt, so please use English), as well as select the API-based extension added in Step 2. - -

External_data_tool

- -5. In the prompt orchestration box, we can assemble the queried external data into the Prompt. For instance, if we want to query today's weather in London, we can add a variable named `location`, enter "London", and combine it with the external data tool's extension variable name `weather_data`. The debug output would be as follows: - -

Weather_search_tool

- -In the Prompt Log, we can also see the real-time data returned by the API: - -

Prompt Log

diff --git a/en/features/more-integration.md b/en/features/more-integration.md deleted file mode 100644 index d89ce30..0000000 --- a/en/features/more-integration.md +++ /dev/null @@ -1,3 +0,0 @@ -# More Integration - -TODO diff --git a/en/features/retrieval-augment/README.md b/en/features/retrieval-augment/README.md deleted file mode 100644 index 3afe490..0000000 --- a/en/features/retrieval-augment/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# RAG (Retrieval Augmented Generation) - -## The concept of the RAG - -The RAG architecture, with vector retrieval at its core, has become the leading technological framework for addressing two major challenges of large models: acquiring the latest external knowledge and mitigating issues of generating hallucinations. This architecture has been widely implemented in numerous practical application scenarios. - -Developers can utilize this technology to cost-effectively build AI-powered customer service bots, corporate knowledge bases, AI search engines, etc. These systems interact with various forms of organized knowledge through natural language input. A representative example of a RAG application is as follows: - -In the diagram below, when a user asks, "Who is the President of the United States?", the system doesn't directly relay the question to the large model for an answer. Instead, it first conducts a vector search in a knowledge base (like Wikipedia, as shown in the diagram) for the user's query. It finds relevant content through semantic similarity matching (for instance, "Biden is the current 46th President of the United States…"), and then provides the user's question along with the found knowledge to the large model. This enables the model to have sufficient and complete knowledge to answer the question, thereby yielding a more reliable response. - -

Basic Architecture of RAG

- -## Why is this necessary? - -We can liken a large model to a super-expert, knowledgeable in various human domains. However, this expert has its limitations; for example, it doesn't know your personal situation, as such information is private and not publicly available on the internet, and therefore, it hasn't had the opportunity to learn it beforehand. - -When you want to hire this super-expert as your family financial advisor, you need to allow them to review your investment records, household expenses, and other relevant data before they can respond to your inquiries. This enables them to provide professional advice tailored to your personal circumstances. - -**This is what the RAG system does: it helps the large model temporarily acquire external knowledge it doesn't possess, allowing it to search for answers before responding to a question.** - -Based on this example, it's evident that the most critical aspect of the RAG system is the retrieval of external knowledge. The expert's ability to provide professional financial advice depends on accurately finding the necessary information. If the expert retrieves information unrelated to financial investments, like a family weight loss plan, even the most capable expert would be ineffective. diff --git a/en/features/retrieval-augment/hybrid-search.md b/en/features/retrieval-augment/hybrid-search.md deleted file mode 100644 index e92d46a..0000000 --- a/en/features/retrieval-augment/hybrid-search.md +++ /dev/null @@ -1,80 +0,0 @@ -# Hybrid Search - -## Why is Hybrid Search Necessary? - -The mainstream method in the RAG retrieval phase is Vector Search, which is based on semantic relevance matching. The technical principle involves initially dividing documents from external knowledge bases into semantically complete paragraphs or sentences, and then converting them through a process known as embedding into a series of numerical expressions (multidimensional vectors) that computers can understand. The user's query undergoes a similar conversion. - -Computers can detect subtle semantic correlations between user queries and sentences. For example, the semantic relevance between "a cat chases a mouse" and "a kitten hunting a mouse" is higher than between "a cat chases a mouse" and "I like to eat ham." After identifying the text with the highest relevance, the RAG system provides it as context alongside the user's query to the large model, aiding in answering the question. - -Besides complex semantic text searches, Vector Search has other advantages: - -* Understanding of similar semantics (e.g., mouse/mousetrap/cheese, Google/Bing/search engine) -* Multilingual comprehension (e.g., matching Chinese input with English content) -* Multimodal understanding (supports matching text, images, audio, and video) -* Fault tolerance (handles spelling mistakes, vague descriptions) - -However, Vector Search might underperform in certain scenarios, like: - -* Searching names of people or objects (e.g., Elon Musk, iPhone 15) -* Searching acronyms or short phrases (e.g., RAG, RLHF) -* Searching IDs (e.g., `gpt-3.5-turbo`, `titan-xlarge-v1.01`) - -These limitations are precisely where traditional keyword search excels, being adept at: - -* Precise matching (e.g., product names, personal names, product numbers) -* Matching a small number of characters (vector search performs poorly with few characters, but users often input just a few keywords) -* Matching low-frequency vocabulary (which often carries more significant meanings, like in “Do you want to go for a coffee with me?”, words like “drink” and “coffee” carry more weight than “you”, “want”, “me”) - -In most text search scenarios, it's crucial to ensure that the most relevant results appear in the candidates. Vector and keyword searches each have their strengths in the search domain. Hybrid Search combines the advantages of both techniques while compensating for their respective shortcomings. - -In Hybrid Search, vector and keyword indices are pre-established in the database. Upon user query input, the system searches for the most relevant text in documents using both search methods. - -

Hybrid Search

- -"Hybrid Search" doesn't have a definitive definition; this article exemplifies it as a combination of Vector Search and Keyword Search. However, the term can also apply to other combinations of search algorithms. For instance, we could combine knowledge graph technology, used for retrieving entity relationships, with Vector Search. - -Different search systems each excel at uncovering various subtle connections within texts (paragraphs, sentences, words), including precise relationships, semantic relationships, thematic relationships, structural relationships, entity relationships, temporal relationships, and event relationships. It's safe to say that no single search mode is suitable for all scenarios. **Hybrid Search, by integrating multiple search systems, achieves a complementarity among various search technologies.** - -## Vector Search - -Definition: Vector Search involves generating query embeddings and then searching for text chunks that most closely match these embeddings in terms of vector representation. - -

Settings for Vector Search

- -**TopK:** This setting is used to filter text chunks that have the highest similarity to the user's query. The system also dynamically adjusts the number of chunks based on the context window size of the selected model. The default value for this setting is 3. - -**Score Threshold:** This setting is used to establish a similarity threshold for the selection of text chunks. It means that only text chunks exceeding the set score are recalled. By default, this setting is turned off, meaning that the system does not filter the similarity values of the recalled text chunks. When activated, the default value is set to 0.5. - -**Rerank Model:** After configuring the Rerank model's API key on the "Model Provider" page, you can enable the "Rerank Model" in the search settings. The system then performs a semantic re-ranking of the document results that have been recalled after semantic search, optimizing the order of these results. Once the Rerank model is set up, the TopK and Score threshold settings are only effective in the Rerank step. - -## Full-Text Search - -Definition: Full-Text Search involves indexing all the words in a document, enabling users to query any term and retrieve text chunks that contain these terms. - -

Settings for Full-Text Search

- -**TopK:** This setting is utilized to select text chunks that most closely match the user's query in terms of similarity. The system also dynamically adjusts the number of chunks based on the context window size of the chosen model. The default value for TopK is set at 3. - -**Rerank Model:** After configuring the API key for the Rerank model on the "Model Provider" page, you can activate the "Rerank Model" in the search settings. The system will then perform a semantic re-ranking of the document results retrieved through full-text search, optimizing the order of these results. Once the Rerank model is configured, the TopK and any Score threshold settings will only be effective during the Rerank step. - -## Hybrid Search - -Hybrid Search operates by concurrently executing Full-Text Search and Vector Search. It then applies a re-ranking step to choose the best results that match the user's query from both types of search results. To effectively use this feature, it is necessary to configure the Rerank Model API. - -

Settings for Hybrid Search

- -**TopK:** This setting is used for filtering text chunks that have the highest similarity to the user's query. The system will dynamically adjust the number of chunks based on the context window size of the model in use. The default value for TopK is set at 3. - -**Rerank Model:** After configuring the Rerank model's API key on the "Model Supplier" page, you can enable the "Rerank Model" in the search settings. The system will perform a semantic re-ranking of the document results retrieved through hybrid search, thereby optimizing the order of these results. Once the Rerank model is set up, the TopK and any Score threshold settings are only applicable during the Rerank step. - -## Setting the Search Mode When Creating a Knowledge - -To set the search mode when creating a knowledge base, navigate to the "Knowledge -> Create Knowledge" page. There, you can configure different search modes in the retrieval settings section. - -

Setting the Search Mode When Creating a Knowledge base

- -## Modifying the Search Mode in Prompt Engineering - -You can modify the search mode during application creation by navigating to the "Prompt Engineering -> Context -> Select Knowledge -> Settings" page. This allows for adjustments to different search modes within the prompt arrangement phase. - -

Modifying the Search Mode in Prompt Engineering

diff --git a/en/features/retrieval-augment/rerank.md b/en/features/retrieval-augment/rerank.md deleted file mode 100644 index cfaaeea..0000000 --- a/en/features/retrieval-augment/rerank.md +++ /dev/null @@ -1,41 +0,0 @@ -# Rerank - -## Why is Rerank Necessary? - -Hybrid Search combines the advantages of various search technologies to achieve better recall results. However, results from different search modes need to be merged and normalized (converting data into a uniform standard range or distribution for better comparison, analysis, and processing) before being collectively provided to the large model. This necessitates the introduction of a scoring system: Rerank Model. - -The Rerank Model works by reordering the list of candidate documents based on their semantic match with the user's question, thus improving the results of semantic sorting. It does this by calculating a relevance score between the user's question and each candidate document, returning a list of documents sorted by relevance from high to low. Common Rerank models include Cohere rerank, bge-reranker, and others. - -

Hybrid Search + Rerank

- -In most cases, there is an initial search before rerank because calculating the relevance score between a query and millions of documents is highly inefficient. **Therefore, rerank is typically placed at the end of the search process, making it very suitable for merging and sorting results from different search systems.** - -However, rerank is not only applicable to merging results from different search systems. Even in a single search mode, introducing a rerank step can effectively improve the recall of documents, such as adding semantic rerank after keyword search. - -In practice, apart from normalizing results from multiple queries, we usually limit the number of text chunks passed to the large model before providing the relevant text chunks (i.e., TopK, which can be set in the rerank model parameters). This is done because the input window of the large model has size limitations (generally 4K, 8K, 16K, 128K Token counts), and you need to select an appropriate segmentation strategy and TopK value based on the size limitation of the chosen model's input window. - -It should be noted that even if the model's context window is sufficiently large, too many recalled chunks may introduce content with lower relevance, thus degrading the quality of the answer. Therefore, the TopK parameter for rerank is not necessarily better when larger. - -Rerank is not a substitute for search technology but an auxiliary tool to enhance existing search systems. **Its greatest advantage is that it not only offers a simple and low-complexity method to improve search results but also allows users to integrate semantic relevance into existing search systems without the need for significant infrastructure modifications.** - -## How to Obtain the Cohere Rerank Model? - -Visit [https://cohere.com/rerank](https://cohere.com/rerank), register on the page, and apply for usage rights for the Rerank model to obtain the API key. - -## Setting the Rerank Model in Knowledge Search Mode - -Access the Rerank settings by navigating to “Knowledge -> Create Knowledge -> Retrieval Settings”. Besides setting Rerank during knowledge creation, you can also modify the Rerank configuration in the settings of an already created knowledge base, and change the Rerank configuration in the knowledge recall mode settings of application arrangement. - -

Setting the Rerank Model in Knowledge Search Mode

- -**TopK:** Used to set the number of relevant documents returned after Rerank. - -**Score Threshold:** Used to set the minimum score for relevant documents to be returned after Rerank. After setting the Rerank model, the TopK and Score threshold settings are only effective in the Rerank step. - -## Setting the Rerank Model in Multi-path retrieval - - Recall Mode Enable the Rerank model by setting it to Multi-path retrieval mode in the “Prompt Engineering -> Context -> Settings” page. - -Explanation of Multi-path retrieval Mode: 🔗 - -

Setting the Rerank Model in Multi-path retrieval

diff --git a/en/features/retrieval-augment/retrieval.md b/en/features/retrieval-augment/retrieval.md deleted file mode 100644 index 56d7238..0000000 --- a/en/features/retrieval-augment/retrieval.md +++ /dev/null @@ -1,33 +0,0 @@ -# Retrieval - -When users build knowledge base Q\&A AI applications, if multiple knowledge bases are associated within the application, Dify supports two retrieval modes: N-to-1 retrieval and Multi-path retrieval. - -

Retrieval Settings

- -## Retrieval **Settings** - -### **N-to-1 Retrieval** - -Based on user intent and knowledge description, the Agent independently determines and selects the most matching single knowledge base for querying relevant text. This mode is suitable for applications with distinct knowledge and a smaller number of knowledge bases. N-to-1 retrieval relies on the model's inference capability to choose the most relevant knowledge base based on user intent. When inferring the knowledge, the knowledge serves as a tool for the Agent, chosen through intent inference; the tool description is essentially the knowledge description. - -When users upload knowledge, the system automatically creates a summary description of each knowledge base. To achieve the best retrieval results in this mode, you can view the system-generated summary description under “Knowledge -> Settings -> Knowledge Description” and check if this content clearly summarizes the knowledge's content. - -Here is the technical flowchart for N-to-1 retrieval: - -

N-to-1 Retrieval

- -Therefore, this mode's recall effectiveness can be impacted when there are too many knowledge bases or when the knowledge descriptions lack sufficient distinction. This mode is more suitable for applications with fewer knowledge bases. - -Tip: OpenAI Function Call already supports multiple tool calls, and Dify plans to upgrade this mode to "N-to-M retrieval" in future versions. - -### Multi-path Retrieval - -Based on user intent, this mode matches all knowledge bases simultaneously, queries relevant text chunks from multiple knowledge bases, and after a re-ranking step, selects the best results matching the user's question from the multi-path query results. Configuring the Rerank model API is required. In Multi-path retrieval mode, the search engine retrieves text content related to the user's query from all knowledge bases associated with the application, merges the results from multi-path recall, and re-ranks the retrieved documents semantically using the Rerank model. - -In Multi-path retrieval mode, configuring the Rerank model is necessary. How to configure the Rerank model: 🔗 - -Here is the technical flowchart for Multi-path retrieval: - -

Multi-path retrieval

- -As Multi-path retrieval does not rely on the model's inferencing capability or knowledge descriptions, this mode can achieve higher quality recall results in multi-knowledge searches. Additionally, incorporating the Rerank step can effectively improve document recall. Therefore, when creating a knowledge base Q\&A application associated with multiple knowledge bases, we recommend configuring the retrieval mode as Multi-path retrieval. diff --git a/en/features/workflow/README.md b/en/features/workflow/README.md deleted file mode 100644 index 66277ea..0000000 --- a/en/features/workflow/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Workflow - diff --git a/en/features/workflow/key-concept.md b/en/features/workflow/key-concept.md deleted file mode 100644 index da328b3..0000000 --- a/en/features/workflow/key-concept.md +++ /dev/null @@ -1,49 +0,0 @@ -# Key Concept - -### Node - -Nodes are the key components of a workflow. By connecting nodes with different functionalities, a series of operations within the workflow are executed. Nodes are categorized by type: - -* Basic Nodes：Start, End, Answer, LLM, Knowledge Retrieval, Applications (coming soon) -* Question Understand：Quesition Classifier，Question Rewriting (coming soon), Sub-question Splitting (coming soon) -* Logic Processing：IF/ELSE, Merge (coming soon), Loop (coming soon) -* Transformation：Code, Template，Variable Assigner, Function Extraction (coming soon) -* Others：HTTP Request -* Tools：Built-in Tools, Custom Tools - -### Variables - -Variables are crucial for linking the input and output of nodes within a workflow, facilitating the implementation of complex processing logic throughout the process. - -* Workflows need to define input variables for initiating execution or conversation. -* Nodes require input variables for initiation; for instance, the input variable for a question classifier typically consists of the user's question. -* Variables referenced within a node can only be those from preceding process nodes to ensure coherence and avoid duplication. -* To prevent variable name duplication, node names must be unique. -* The output variables of a node are fixed by the system and are not subject to modification. - -### Differences between Chatflow and Workflow - -**Application Scenario Differences** - -* **Chatflow**: Targets conversational scenarios and represents an advanced orchestration mode for Chatbot application types. -* **Workflow**: Geared towards automation and batch processing scenarios. - -**Differences in Nodes** - -| **Node** | **Chatflow** | **Workflow** | -| ------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| Start | Utilizes system-built variables for user input and file uploads | Utilizes system-built variables for file uploads | -| End |

Not support End node

| Uses an End node to output structured text at the conclusion of execution, which is not designed for mid-process output. | -| Answer | The Answer node is used for streaming output or fixed text replies and can be utilized mid-process. | Not support Answer node | -| LLM | Memory is automatically enabled to store and pass on the history of multi-turn dialogues. |

Not support Memory configuration

| -| Question Classifier | Memory is automatically enabled to store and pass on the history of multi-turn dialogues. | Not Support Memory configuration | - -#### Application Entry Division - -* **Chatflow Entry**: - -
- -* **Workflow Entry**: - -
diff --git a/en/features/workflow/node/README.md b/en/features/workflow/node/README.md deleted file mode 100644 index 863ddfe..0000000 --- a/en/features/workflow/node/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Node - diff --git a/en/features/workflow/node/code.md b/en/features/workflow/node/code.md deleted file mode 100644 index 6904803..0000000 --- a/en/features/workflow/node/code.md +++ /dev/null @@ -1,74 +0,0 @@ -# Code - -## Navigation - -* [Introduction](code.md#introduction) -* [Use Cases](code.md#use-cases) -* [Local Deployment](code.md#local-deployment) -* [Security Policy](code.md#security-policy) - -## Introduction - -The code node supports the execution of Python / NodeJS code to perform data transformations within workflows. It simplifies your workflows, suitable for Arithmetic, JSON transform, text processing, and more scenarios. - -This node significantly enhances developers' flexibility, allowing them to embed custom Python or Javascript scripts in their workflows and manipulate variables in ways that preset nodes cannot achieve. Through configuration options, you can specify the required input and output variables and write the corresponding execution code: - -
- -## Configuration - -If you need to use variables from other nodes within the code node, you need to define the variable names in `input variables` and reference these variables, see [Variable Reference](../key\_concept.md#variable) for details. - -## Use Cases - -With the code node, you can perform the following common operations: - -### Structured Data Processing - -In workflows, it's often necessary to deal with unstructured data processing, such as parsing, extracting, and transforming JSON strings. A typical example is data processing in the HTTP node, where data might be nested within multiple layers of JSON objects, and we need to extract certain fields. The code node can help you accomplish these tasks. Here's a simple example that extracts the `data.name` field from a JSON string returned by an HTTP node: - -```python -def main(http_response: str) -> str: - import json - data = json.loads(http_response) - return { - # do not forget to declare 'result' in the output variables - 'result': data['data']['name'] - } -``` - -### Mathematical Calculations - -When complex mathematical calculations are needed in workflows, the code node can also be used. For example, to calculate a complex mathematical formula or perform some statistical analysis on the data. Here is a simple example that calculates the variance of a list: - -```python -def main(x: list) -> float: - return { - # do not forget to declare 'result' in the output variables - 'result': sum([(i - sum(x) / len(x)) ** 2 for i in x]) / len(x) - } -``` - -### Data Concatenation - -Sometimes, you may need to concatenate multiple data sources, such as multiple knowledge retrievals, data searches, API calls, etc. The code node can help you integrate these data sources. Here's a simple example that merges data from two knowledge bases: - -```python -def main(knowledge1: list, knowledge2: list) -> list: - return { - # do not forget to declare 'result' in the output variables - 'result': knowledge1 + knowledge2 - } -``` - -## Local Deployment - -If you are a user deploying locally, you need to start a sandbox service, which ensures that malicious code is not executed. Also, launching this service requires Docker, and you can find specific information about the Sandbox service [here](https://github.com/langgenius/dify/tree/main/docker/docker-compose.middleware.yaml). You can also directly start the service using docker-compose - -```bash -docker-compose -f docker-compose.middleware.yaml up -d -``` - -## Security Policy - -The execution environment is sandboxed for both Python and Javascript, meaning that certain functionalities that require extensive system resources or pose security risks are not available. This includes, but is not limited to, direct file system access, network calls, and operating system-level commands. diff --git a/en/features/workflow/node/http-request.md b/en/features/workflow/node/http-request.md deleted file mode 100644 index 8a779be..0000000 --- a/en/features/workflow/node/http-request.md +++ /dev/null @@ -1,7 +0,0 @@ -# HTTP Request - -HTTP Request node lets you craft and dispatch HTTP requests to specified endpoints, enabling a wide range of integrations and data exchanges with external services. The node supports all common HTTP request methods, and lets you fully customize over the URL, headers, query parameters, body content, and authorization details of the request. - -
- -A really handy feature with HTTP request is the ability to dynamically construct the request by inserting variables in different fields. For instance, in a customer support scenario, variables such as username or customer ID can be used to personalize automated responses sent via a POST request, or retrieve individual-specific information related to the customer.The HTTP request returns `body`, `status_code`, `headers`, and `files` as outputs. If the response includes files of [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics\_of\_HTTP/MIME\_types/Common\_types) types (currently limited to images), the node automatically saves these as `files` for downstream use. diff --git a/en/features/workflow/node/if-else.md b/en/features/workflow/node/if-else.md deleted file mode 100644 index 3c60c19..0000000 --- a/en/features/workflow/node/if-else.md +++ /dev/null @@ -1,5 +0,0 @@ -# IF/ELSE - -The IF/ELSE Node allows you to split a workflow into two branches based on if/else conditions. In this node, you can set one or more IF conditions. When the IF condition(s) are met, the workflow proceeds to the next step under the "IS TRUE" branch. If the IF condition(s) are not met, the workflow triggers the next step under the "IS FALSE" branch. - -
diff --git a/en/features/workflow/node/tools.md b/en/features/workflow/node/tools.md deleted file mode 100644 index 0363d21..0000000 --- a/en/features/workflow/node/tools.md +++ /dev/null @@ -1,12 +0,0 @@ -# Tools - -Within a workflow, Dify provides both built-in and customizable tools. Before utilizing these tools, you need to "authorize" them. If the built-in tools do not meet your requirements, you can create custom tools within "Dify—Tools". - -
- -Configuring a tool node generally involves two steps: - -1. **Authorizing the Tool/Creating Custom Tools** -2. **Configuring Tool Inputs and Parameters** - -For guidance on creating custom tools and configuring them, please refer to the [tool configuration instructions](https://docs.dify.ai/tutorials/quick-tool-integration). diff --git a/en/features/workflow/node/variable-assigner.md b/en/features/workflow/node/variable-assigner.md deleted file mode 100644 index c87f994..0000000 --- a/en/features/workflow/node/variable-assigner.md +++ /dev/null @@ -1,11 +0,0 @@ -# Variable Assigner - -The Variable Assigner node serves as a hub for collecting branch outputs within the workflow, ensuring that regardless of which branch is taken, the output can be referenced by a single variable. The output can subsequently be manipulated by nodes downstream. - -
- -Variable Assigner supports multiple types of output variables including `String`,`Number`, `Object`, and `Array`. Given the specified output type, you may add input variables from the dropdown list of variables to the node. The list of variables is derived from previous branch outputs and autofiltered based on the specified type. - -
- -Variable Assigner gives a single `output` variable of the specified type for downstream use. diff --git a/en/features/workflow/nodes/README.md b/en/features/workflow/nodes/README.md deleted file mode 100644 index 7ab6344..0000000 --- a/en/features/workflow/nodes/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Nodes - diff --git a/en/features/workflow/nodes/answer.md b/en/features/workflow/nodes/answer.md deleted file mode 100644 index ff31984..0000000 --- a/en/features/workflow/nodes/answer.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: Answer ---- - -# Answer - -Defining Reply Content in a Chatflow Process. In a text editor, you have the flexibility to determine the reply format. This includes crafting a fixed block of text, utilizing output variables from preceding steps as the reply content, or merging custom text with variables for the response. - -Answer node can be seamlessly integrated at any point to dynamically deliver content into the dialogue responses. This setup supports a live-editing configuration mode, allowing for both text and image content to be arranged together. The configurations include: - -1. Outputting the reply content from a Language Model (LLM) node. -2. Outputting generated images. -3. Outputting plain text. - -Example 1: Output plain text. - -
- -Example 2: Output image and LLM reply. - -
- -
diff --git a/en/features/workflow/nodes/code.md b/en/features/workflow/nodes/code.md deleted file mode 100644 index 319bbb9..0000000 --- a/en/features/workflow/nodes/code.md +++ /dev/null @@ -1,45 +0,0 @@ -# Code - -## Introduction - -The Code node lets you write Python / NodeJS code to perform data transformations not achievable via pre-defined nodes. It lends a lot of flexibility to your workflows and can be used to perform calculations, process JSON data, transform texts, and more. - -
- -## Including variables -If you need to use variables from other nodes within your code, you need to define the variable names in `input variables` and reference these variables, see [Variable Reference](../key_concept.md#variable) for details. - -You will need to define the type of the output variable for - -## Use Cases -With the code node, you can perform the following common operations: - -### Structured Data Processing -In workflows, it's often necessary to deal with unstructured data processing, such as parsing, extracting, and transforming JSON strings. A typical example is dealing with output from the [HTTP Request node](./http-request.md), where the data you need to extract might be nested under multiple layers within a JSON object. The code node can help you accomplish such tasks. Here's a simple example that extracts the `data.name` field from a JSON string returned by an HTTP node: - -```python -def main(http_response: str) -> str: - import json - data = json.loads(http_response) - return data['data']['name'] -``` - -### Mathematical Calculations -You can also write custom code to calculate a complex mathematical formula or perform some statistical analysis on certain data. Here is a simple example that calculates the variance of a list: - -```python -def main(x: list) -> float: - return sum([(i - sum(x) / len(x)) ** 2 for i in x]) / len(x) -``` - -### Data Transformations - -```python -def main(knowledge1: list, knowledge2: list) -> list: - return knowledge1 + knowledge2 -``` - -## Limitations -The execution environment is sandboxed for both Python and Javascript (If you are self-hosting Dify, a sandbox service would be started with Docker). - -This means that certain functionalities that require extensive system resources or pose security risks are not available. This includes, but is not limited to, direct file system access, network calls, and operating system-level commands. diff --git a/en/features/workflow/nodes/end.md b/en/features/workflow/nodes/end.md deleted file mode 100644 index f497d04..0000000 --- a/en/features/workflow/nodes/end.md +++ /dev/null @@ -1,13 +0,0 @@ -# End - -Defining the Final Output Content of a Workflow Process. Every workflow needs at least one "End" node to output the final result after full execution. - -The "End" node serves as the termination point of the process, beyond which no further nodes can be added. In workflow applications, execution results are only output when the process reaches the "End" node. If the process involves conditional branching, multiple "End" nodes must be defined. - -Single-Path Execution Example: - -
- -Multi-Path Execution Example: - -
diff --git a/en/features/workflow/nodes/http-request.md b/en/features/workflow/nodes/http-request.md deleted file mode 100644 index 2ed514d..0000000 --- a/en/features/workflow/nodes/http-request.md +++ /dev/null @@ -1,7 +0,0 @@ -# HTTP Request - -HTTP Request node lets you craft and dispatch HTTP requests to specified endpoints, enabling a wide range of integrations and data exchanges with external services. The node supports all common HTTP request methods, and lets you fully customize over the URL, headers, query parameters, body content, and authorization details of the request. - -
- -A really handy feature with HTTP request is the ability to dynamically construct the request by inserting variables in different fields. For instance, in a customer support scenario, variables such as username or customer ID can be used to personalize automated responses sent via a POST request, or retrieve individual-specific information related to the customer.The HTTP request returns `body`, `status_code`, `headers`, and `files` as outputs. If the response includes files of [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics\_of\_HTTP/MIME\_types/Common\_types) types (currently limited to images), the node automatically saves these as `files` for downstream use. diff --git a/en/features/workflow/nodes/if-else.md b/en/features/workflow/nodes/if-else.md deleted file mode 100644 index 3c60c19..0000000 --- a/en/features/workflow/nodes/if-else.md +++ /dev/null @@ -1,5 +0,0 @@ -# IF/ELSE - -The IF/ELSE Node allows you to split a workflow into two branches based on if/else conditions. In this node, you can set one or more IF conditions. When the IF condition(s) are met, the workflow proceeds to the next step under the "IS TRUE" branch. If the IF condition(s) are not met, the workflow triggers the next step under the "IS FALSE" branch. - -
diff --git a/en/features/workflow/nodes/knowledge-retrieval.md b/en/features/workflow/nodes/knowledge-retrieval.md deleted file mode 100644 index 9e4741b..0000000 --- a/en/features/workflow/nodes/knowledge-retrieval.md +++ /dev/null @@ -1,30 +0,0 @@ -# Knowledge Retrieval - -\ -The Knowledge Base Retrieval Node is designed to query text content related to user questions from the Dify Knowledge Base, which can then be used as context for subsequent answers by the Large Language Model (LLM). - -
- -Configuring the Knowledge Base Retrieval Node involves three main steps: - -1. **Selecting the Query Variable** -2. **Choosing the Knowledge Base for Query** -3. **Configuring the Retrieval Strategy** - -**Selecting the Query Variable** - -In knowledge base retrieval scenarios, the query variable typically represents the user's input question. In the "Start" node of conversational applications, the system pre-sets "sys.query" as the user input variable. This variable can be used to query the knowledge base for text segments most closely related to the user's question. - -**Choosing the Knowledge Base for Query** - -Within the knowledge base retrieval node, you can add an existing knowledge base from Dify. For instructions on creating a knowledge base within Dify, please refer to the knowledge base [help documentation](https://docs.dify.ai/v/zh-hans/guides/knowledge-base). - -**Configuring the Retrieval Strategy** - -It's possible to modify the indexing strategy and retrieval mode for an individual knowledge base within the node. For a detailed explanation of these settings, refer to the knowledge base [help documentation](https://docs.dify.ai/v/zh-hans/learn-more/extended-reading/retrieval-augment/hybrid-search). - -
- -Dify offers two recall strategies for different knowledge base retrieval scenarios: "N-choose-1 Recall" and "Multi-way Recall". In the N-choose-1 mode, knowledge base queries are executed through function calling, requiring the selection of a system reasoning model. In the multi-way recall mode, a Rerank model needs to be configured for result re-ranking. For a detailed explanation of these two recall strategies, refer to the retrieval mode explanation in the [help documentation](https://docs.dify.ai/v/zh-hans/learn-more/extended-reading/retrieval-augment/retrieval). - -
diff --git a/en/features/workflow/nodes/llm.md b/en/features/workflow/nodes/llm.md deleted file mode 100644 index b23ae6a..0000000 --- a/en/features/workflow/nodes/llm.md +++ /dev/null @@ -1,38 +0,0 @@ -# LLM - -Invoking a Large Language Model for Question Answering or Natural Language Processing. Within an LLM node, you can select an appropriate model, compose prompts, set the context referenced in the prompts, configure memory settings, and adjust the memory window size. - -
- -Configuring an LLM node primarily involves two steps: - -1. Selecting a model -2. Composing system prompts - -**Model Configuration** - -Before selecting a model suitable for your task, you must complete the model configuration in "System Settings—Model Provider". The specific configuration method can be referenced in the [model configuration instructions](https://docs.dify.ai/v/zh-hans/guides/model-configuration). After selecting a model, you can configure its parameters. - -
- -**Write Prompts** - -Within an LLM node, you can customize the model input prompts. If you choose a conversational model, you can customize the content of system prompts, user messages, and assistant messages. - -For instance, in a knowledge base Q\&A scenario, after linking the "Result" variable from the knowledge base retrieval node in "Context", inserting the "Context" special variable in the prompts will use the text retrieved from the knowledge base as the context background information for the model input. - -
- -In the prompt editor, you can bring up the variable insertion menu by typing "/" or "{" to insert special variable blocks or variables from preceding flow nodes into the prompts as context content. - -
- -If you opt for a completion model, the system provides preset prompt templates for conversational applications. You can customize the content of the prompts and insert special variable blocks like "Conversation History" and "Context" at appropriate positions by typing "/" or "{", enabling richer conversational functionalities. - -
- -**Memory Toggle Settings** In conversational applications (Chatflow), the LLM node defaults to enabling system memory settings. In multi-turn dialogues, the system stores historical dialogue messages and passes them into the model. In workflow applications (Workflow), system memory is turned off by default, and no memory setting options are provided. - -**Memory Window Settings** If the memory window setting is off, the system dynamically passes historical dialogue messages according to the model's context window. With the memory window setting on, you can configure the number of historical dialogue messages to pass based on your needs. - -**Dialogue Role Name Settings** Due to differences in model training phases, different models adhere to role name commands to varying degrees, such as Human/Assistant, Human/AI, 人类/助手, etc. To adapt to the prompt response effects of multiple models, the system allows setting dialogue role names, modifying the role prefix in conversation history. diff --git a/en/features/workflow/nodes/question-classifier.md b/en/features/workflow/nodes/question-classifier.md deleted file mode 100644 index d9de2e4..0000000 --- a/en/features/workflow/nodes/question-classifier.md +++ /dev/null @@ -1,17 +0,0 @@ -# Question Classifier - -Question Classifier node defines the categorization conditions for user queries, enabling the LLM to dictate the progression of the dialogue based on these categorizations. As illustrated in a typical customer service robot scenario, the question classifier can serve as a preliminary step to knowledge base retrieval, identifying user intent. Classifying user intent before retrieval can significantly enhance the recall efficiency of the knowledge base. - -
- -Configuring the Question Classifier Node involves three main components: - -1. **Selecting the Input Variable** -2. **Configuring the Inference Model** -3. **Writing the Classification Method** - -**Selecting the Input Variable** In conversational customer scenarios, you can use the user input variable from the "Start Node" (sys.query) as the input for the question classifier. In automated/batch processing scenarios, customer feedback or email content can be utilized as input variables. - -**Configuring the Inference Model** The question classifier relies on the natural language processing capabilities of the LLM to categorize text. You will need to configure an inference model for the classifier. Before configuring this model, you might need to complete the model setup in "System Settings - Model Provider". The specific configuration method can be found in the [model configuration instructions](https://docs.dify.ai/v/zh-hans/guides/model-configuration). After selecting a suitable model, you can configure its parameters. - -**Writing Classification Conditions** You can manually add multiple classifications by composing keywords or descriptive sentences that fit each classification. Based on the descriptions of these conditions, the question classifier can route the dialogue to the appropriate process path according to the semantics of the user's input. diff --git a/en/features/workflow/nodes/start.md b/en/features/workflow/nodes/start.md deleted file mode 100644 index b4c882e..0000000 --- a/en/features/workflow/nodes/start.md +++ /dev/null @@ -1,20 +0,0 @@ -# Start - -Defining initial parameters for a workflow process initiation allows for customization at the start node, where you input variables to kick-start the workflow. Every workflow necessitates a start node, acting as the entry point and foundation for the workflow's execution path. - -
- -Within the "Start" node, you can define input variables of four types: - -* **Text**: For short, simple text inputs like names, identifiers, or any other concise data. -* **Paragraph**: Supports longer text entries, suitable for descriptions, detailed queries, or any extensive textual data. -* **Dropdown Options**: Allows the selection from a predefined list of options, enabling users to choose from a set of predetermined values. -* **Number**: For numeric inputs, whether integers or decimals, to be used in calculations, quantities, identifiers, etc. - -
- -Once the configuration is completed, the workflow's execution will prompt for the values of the variables defined in the start node. This step ensures that the workflow has all the necessary information to proceed with its designated processes. - -
- -**Tip:** In Chatflow, the start node provides system-built variables: `sys.query` and `sys.files`. `sys.query` is utilized for user question input in conversational applications, enabling the system to process and respond to user queries. `sys.files` is used for file uploads within the conversation, such as uploading an image to understand its content. This requires the integration of image understanding models or tools designed for processing image inputs, allowing the workflow to interpret and act upon the uploaded files effectively. diff --git a/en/features/workflow/nodes/template.md b/en/features/workflow/nodes/template.md deleted file mode 100644 index 334629b..0000000 --- a/en/features/workflow/nodes/template.md +++ /dev/null @@ -1,29 +0,0 @@ -# Template - -Template lets you dynamically format and combine variables from previous nodes into a single text-based output using Jinja2, a powerful templating syntax for Python. It's useful for combining data from multiple sources into a specific structure required by subsequent nodes. The simple example below shows how to assemble an article by piecing together various previous outputs: - -
- -Beyond naive use cases, you can create more complex templates as per Jinja's [documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/) for a variety of tasks. Here's one template that structures retrieved chunks and their relevant metadata from a knowledge retrieval node into a formatted markdown: - -```Plain -{% raw %} -{% for item in chunks %} -### Chunk {{ loop.index }}. -### Similarity: {{ item.metadata.score | default('N/A') }} - -#### {{ item.title }} - -##### Content -{{ item.content | replace('\n', '\n\n') }} - ---- -{% endfor %} -{% endraw %} -``` - -
- -This template node can then be used within a Chatflow to return intermediate outputs to the end user, before a LLM response is initiated. - -> The `Answer` node in a Chatflow is non-terminal. It can be inserted anywhere to output responses at multiple points within the flow. diff --git a/en/features/workflow/nodes/variable-assigner.md b/en/features/workflow/nodes/variable-assigner.md deleted file mode 100644 index 0a026f3..0000000 --- a/en/features/workflow/nodes/variable-assigner.md +++ /dev/null @@ -1,16 +0,0 @@ -# Variable Assigner - -The Variable Assigner node serves as a hub for collecting branch outputs within the workflow, ensuring that regardless of which branch is taken, the output can be referenced by a single variable. The output can subsequently be manipulated by nodes downstream. - -In the example below, a branch is created to produce different LLM responses based on different user questions: A knowledge base is used in one branch, but not the other. The output variables from both branches are squashed by a Variable Assigner node into a single output based on the branch taken. This has a few benefits: - -1. Avoids having to create duplicate downstream logic for each branch -2. When modifying the name of an output variable, you don't need to locate everywhere it is referenced downstream and update the variable name. - -
- -Variable Assigner supports multiple types of output variables including `String`,`Number`, `Object`, and `Array`. Given the specified output type, you may add input variables from the dropdown list of variables to the node. The list of variables is derived from previous branch outputs and autofiltered based on the specified type. - -
- -Variable Assigner gives a single `output` variable of the specified type for downstream use. diff --git a/en/features/workflow/preview-and-run/README.md b/en/features/workflow/preview-and-run/README.md deleted file mode 100644 index 309e0c5..0000000 --- a/en/features/workflow/preview-and-run/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Preview\&Run - diff --git a/en/getting-started/install-self-hosted/README.md b/en/getting-started/install-self-hosted/README.md index 9a462d2..2140c32 100644 --- a/en/getting-started/install-self-hosted/README.md +++ b/en/getting-started/install-self-hosted/README.md @@ -1,10 +1,9 @@ # Install (Self hosted) -The Dify Self hosted Edition, which is the open-source on [GitHub](https://github.com/langgenius/dify), can be deployed in one of the following three ways: +The Dify Self hosted Edition, which is the open-source on [GitHub](https://github.com/langgenius/dify), can be deployed in one of the following two ways: 1. [Docker Compose Deployment](https://docs.dify.ai/getting-started/install-self-hosted/docker-compose) 2. [Local Source Code Start](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code) -3. [Deploy to Zeabur with One Click](https://docs.dify.ai/getting-started/install-self-hosted/zeabur) ### Contributing diff --git a/en/getting-started/install-self-hosted/environments.md b/en/getting-started/install-self-hosted/environments.md index 5a11aa5..baba0c6 100644 --- a/en/getting-started/install-self-hosted/environments.md +++ b/en/getting-started/install-self-hosted/environments.md @@ -209,7 +209,6 @@ Used to store uploaded data set files, team/tenant encryption keys, and other fi * `milvus` * `zilliz` (share the same configuration as `milvus`) * `pinecone` (not yet open) - * `tidb_vector` * WEAVIATE\_ENDPOINT Weaviate endpoint address, such as: `http://weaviate:8080`. @@ -252,22 +251,6 @@ Used to store uploaded data set files, team/tenant encryption keys, and other fi Whether Milvus uses SSL connection, default is false. -* TIDB\_VECTOR\_HOST - - TiDB Vector host configuration, such as: `xxx.eu-central-1.xxx.tidbcloud.com` -* TIDB\_VECTOR\_PORT - - TiDB Vector port configuration, such as: `4000` -* TIDB\_VECTOR\_USER - - TiDB Vector user configuration, such as: `xxxxxx.root` -* TIDB\_VECTOR\_PASSWORD - - TiDB Vector password configuration -* TIDB\_VECTOR\_DATABAS - - TiDB Vector database configuration - #### Knowledge Configuration * UPLOAD\_FILE\_SIZE\_LIMIT: diff --git a/en/getting-started/install-self-hosted/zeabur.md b/en/getting-started/install-self-hosted/zeabur.md deleted file mode 100644 index 0b21e2a..0000000 --- a/en/getting-started/install-self-hosted/zeabur.md +++ /dev/null @@ -1,30 +0,0 @@ -# Deploy Dify to Zeabur - -[Zeabur](https://zeabur.com) is a cloud platform that allows you to deploy Dify with one click. This guide will walk you through the process of deploying Dify to Zeabur. - -## Prerequisites - -Before you begin, you'll need the following: - -- A Zeabur account. If you don't have one, you can sign up for free at [Zeabur](https://zeabur.com/). -- Upgrade your Zeabur account to Developer Plan($5 per month). You can upgrade your account from the [Zeabur Pricing](https://zeabur.com/pricing) page. - -## Deploy Dify to Zeabur - -There is a one-click deploy template for Dify on Zeabur. To get started, just press the button below: - -[![Deploy to Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/1D4DOW) - -After clicking the button, you'll be navigated to the template page on Zeabur where you can see the details and instructions for deployment. - -
Zeabur Template Overview
- -Press on the Deploy button, you need to input a generated domain so that the domain can be binded to your Dify instance and inject to other services as environment variable. And then select your favourite region, press the deploy button, your Dify instance will be deployed in a few minutes. - -
Select Region
- -After the deployment is done, you can see a project page in Zeabur dashboard like the following picture, and the domain you inputed in the deploying process will be binded to the NGINX service automatically, you can access your Dify instance through that domain. - -
Zeabur Project Overview
- -You can also change the domain in the Networking tab in NGINX service page. You can refer to the [Zeabur Documentation](https://zeabur.com/docs/deploy/domain-binding) for more information. \ No newline at end of file diff --git a/en/getting-started/readme/specifications-and-technical-features.md b/en/getting-started/readme/features-and-specifications.md similarity index 100% rename from en/getting-started/readme/specifications-and-technical-features.md rename to en/getting-started/readme/features-and-specifications.md diff --git a/en/guides/application-orchestrate/README.md b/en/guides/application-orchestrate/README.md new file mode 100644 index 0000000..367eafa --- /dev/null +++ b/en/guides/application-orchestrate/README.md @@ -0,0 +1,26 @@ +# Application Orchestration + +In Dify, an "application" refers to a practical scenario application built on large language models like GPT. By creating an application, you can apply intelligent AI technology to specific needs. It encompasses both the engineering paradigm for developing AI applications and the specific deliverables. + +In short, an application provides developers with: + +* A user-friendly API that can be directly called by backend or frontend applications, authenticated via Token +* A ready-to-use, aesthetically pleasing, and hosted WebApp, which you can further develop using the WebApp template +* An easy-to-use interface that includes prompt engineering, context management, log analysis, and annotation + +You can choose **any one** or **all** of these to support your AI application development. + +### Application Types + +Dify offers four types of applications: + +* **Chat Assistant**: A conversational assistant built on LLM +* **Text Generation**: An assistant for text generation tasks such as writing stories, text classification, translation, etc. +* **Agent**: A conversational intelligent assistant capable of task decomposition, reasoning, and tool invocation +* **Workflow**: Defines more flexible LLM workflows based on process orchestration + +The differences between Text Generation and Chat Assistant are shown in the table below: + +
Text GenerationChat Assistant
WebApp InterfaceForm + ResultsChat-based
WebAPI Endpointcompletion-messageschat-messages
Interaction ModeOne question, one answerMulti-turn conversation
Streaming ResultsSupportedSupported
Context PreservationPer sessionContinuous
User Input FormSupportedSupported
Datasets and PluginsSupportedSupported
AI Opening RemarksNot supportedSupported
Example ScenariosTranslation, judgment, indexingChatting
+ +### \ No newline at end of file diff --git a/en/user-guide/creating-dify-apps/prompt-engineering/agent-assistant.md b/en/guides/application-orchestrate/agent.md similarity index 100% rename from en/user-guide/creating-dify-apps/prompt-engineering/agent-assistant.md rename to en/guides/application-orchestrate/agent.md diff --git a/en/guides/application-orchestrate/app-toolkits/README.md b/en/guides/application-orchestrate/app-toolkits/README.md new file mode 100644 index 0000000..3d8a690 --- /dev/null +++ b/en/guides/application-orchestrate/app-toolkits/README.md @@ -0,0 +1,49 @@ +# Application Toolbox + +In **Studio -- Application Orchestration**, click **Add Feature** to open the application toolbox. + +The application toolbox provides various additional features for Dify's [applications](../#application_type): + +
+ +### Conversation Opening + +In conversational applications, the AI will proactively say the first sentence or ask a question. You can edit the content of the opening, including the initial question. Using conversation openings can guide users to ask questions, explain the application background, and lower the barrier for initiating a conversation. + +

Conversation Opening

+ +### Next Step Question Suggestions + +Setting next step question suggestions allows the AI to generate 3 follow-up questions based on the previous conversation, guiding the next round of interaction. + +
+ +### Text-to-Speech + +When enabled, this feature converts the AI's responses into natural-sounding speech. + +
+ +### Speech-to-Text + +When enabled, you can record audio within the application and automatically convert the speech into text. + +
+ +### Citation and Attribution + +When this feature is enabled, the large language model will cite content from the knowledge base when responding to questions. You can view specific citation details below the response, including the original text segment, segment number, and match score. + +For more details, please see [Citation and Attribution](../../knowledge-base/retrieval_test_and_citation.md#id-2-yin-yong-yu-gui-shu). + +### Content Moderation + +During interactions with AI applications, we often have stringent requirements regarding content safety, user experience, and legal regulations. In such cases, we need the "Sensitive Content Moderation" feature to create a better interaction environment for end users. + +For more details, please see [Sensitive Content Moderation](moderation-tool.md). + +### Annotated Replies + +The annotated replies feature allows for customizable high-quality Q&A responses through manual editing and annotation. + +See [Annotated Replies](../../biao-zhu/annotation-reply.md). \ No newline at end of file diff --git a/en/features/moderation_tool.md b/en/guides/application-orchestrate/app-toolkits/moderation-tool.md similarity index 100% rename from en/features/moderation_tool.md rename to en/guides/application-orchestrate/app-toolkits/moderation-tool.md diff --git a/en/user-guide/creating-dify-apps/prompt-engineering/conversation-application.md b/en/guides/application-orchestrate/conversation-application.md similarity index 100% rename from en/user-guide/creating-dify-apps/prompt-engineering/conversation-application.md rename to en/guides/application-orchestrate/conversation-application.md diff --git a/en/user-guide/creating-dify-apps/creating-an-application.md b/en/guides/application-orchestrate/creating-an-application.md similarity index 100% rename from en/user-guide/creating-dify-apps/creating-an-application.md rename to en/guides/application-orchestrate/creating-an-application.md diff --git a/en/user-guide/creating-dify-apps/llms-use-faq.md b/en/guides/application-orchestrate/llms-use-faq.md similarity index 100% rename from en/user-guide/creating-dify-apps/llms-use-faq.md rename to en/guides/application-orchestrate/llms-use-faq.md diff --git a/en/user-guide/creating-dify-apps/overview.md b/en/guides/application-orchestrate/overview.md similarity index 100% rename from en/user-guide/creating-dify-apps/overview.md rename to en/guides/application-orchestrate/overview.md diff --git a/en/user-guide/creating-dify-apps/prompt-engineering/README.md b/en/guides/application-orchestrate/prompt-engineering/README.md similarity index 100% rename from en/user-guide/creating-dify-apps/prompt-engineering/README.md rename to en/guides/application-orchestrate/prompt-engineering/README.md diff --git a/en/features/prompt-engineering/README.md b/en/guides/application-orchestrate/prompt-engineering/prompt-engineering-expert-mode.md similarity index 100% rename from en/features/prompt-engineering/README.md rename to en/guides/application-orchestrate/prompt-engineering/prompt-engineering-expert-mode.md diff --git a/en/features/prompt-engineering/prompt-template.md b/en/guides/application-orchestrate/prompt-engineering/prompt-template.md similarity index 100% rename from en/features/prompt-engineering/prompt-template.md rename to en/guides/application-orchestrate/prompt-engineering/prompt-template.md diff --git a/en/user-guide/creating-dify-apps/prompt-engineering/text-generation-application.md b/en/guides/application-orchestrate/text-generation-application.md similarity index 100% rename from en/user-guide/creating-dify-apps/prompt-engineering/text-generation-application.md rename to en/guides/application-orchestrate/text-generation-application.md diff --git a/en/guides/application-publishing/README.md b/en/guides/application-publishing/README.md new file mode 100644 index 0000000..2445e52 --- /dev/null +++ b/en/guides/application-publishing/README.md @@ -0,0 +1,7 @@ +# Launching Dify Apps + +For more detailed information, please refer to the following sections: + +- [Launch Your Webapp Quickly](launch-your-webapp-quickly/) +- [Developing with APIs](developing-with-apis.md) +- [Based on Frontend Templates](based-on-frontend-templates.md) \ No newline at end of file diff --git a/en/features/ai-plugins/based-on-frontend-templates.md b/en/guides/application-publishing/based-on-frontend-templates.md similarity index 100% rename from en/features/ai-plugins/based-on-frontend-templates.md rename to en/guides/application-publishing/based-on-frontend-templates.md diff --git a/en/user-guide/launching-dify-apps/developing-with-apis/README.md b/en/guides/application-publishing/developing-with-apis.md similarity index 100% rename from en/user-guide/launching-dify-apps/developing-with-apis/README.md rename to en/guides/application-publishing/developing-with-apis.md diff --git a/en/user-guide/launching-dify-apps/launch-webapp.md b/en/guides/application-publishing/launch-your-webapp-quickly/README.md similarity index 100% rename from en/user-guide/launching-dify-apps/launch-webapp.md rename to en/guides/application-publishing/launch-your-webapp-quickly/README.md diff --git a/en/user-guide/using-dify-apps/conversation-application.md b/en/guides/application-publishing/launch-your-webapp-quickly/conversation-application.md similarity index 100% rename from en/user-guide/using-dify-apps/conversation-application.md rename to en/guides/application-publishing/launch-your-webapp-quickly/conversation-application.md diff --git a/en/user-guide/using-dify-apps/text-generator.md b/en/guides/application-publishing/launch-your-webapp-quickly/text-generator.md similarity index 100% rename from en/user-guide/using-dify-apps/text-generator.md rename to en/guides/application-publishing/launch-your-webapp-quickly/text-generator.md diff --git a/en/guides/application-publishing/launch-your-webapp-quickly/web-app-settings.md b/en/guides/application-publishing/launch-your-webapp-quickly/web-app-settings.md new file mode 100644 index 0000000..7e22843 --- /dev/null +++ b/en/guides/application-publishing/launch-your-webapp-quickly/web-app-settings.md @@ -0,0 +1,29 @@ +# Overview + +Web applications are designed for application users. When an application developer creates an application on Dify, a corresponding web application is generated. Users of the web application can use it without logging in. The web application is adapted for various device sizes: PC, tablet, and mobile. + +The content of the web application aligns with the configuration of the published application. When the application's configuration is modified and the "Publish" button is clicked on the prompt orchestration page, the web application's content will be updated according to the current configuration of the application. + +On the application overview page, you can enable or disable access to the web application and modify the web application's site information, including: + +* Icon +* Name +* Application description +* Interface language +* Copyright information +* Privacy policy link + +The functionality and performance of the web application depend on whether the developer has enabled these features during application orchestration, such as: + +* Conversation opening remarks +* Variables to be filled before the conversation +* Next step suggestions +* Speech-to-text +* References and attributions +* More similar answers (for text-based applications) +* ...... + +In the following sections, we will introduce the two types of web applications: + +* Text Generation +* Conversational \ No newline at end of file diff --git a/en/guides/biao-zhu/README.md b/en/guides/biao-zhu/README.md new file mode 100644 index 0000000..9384249 --- /dev/null +++ b/en/guides/biao-zhu/README.md @@ -0,0 +1,2 @@ +# Annotation + diff --git a/en/features/annotation-reply.md b/en/guides/biao-zhu/annotation-reply.md similarity index 100% rename from en/features/annotation-reply.md rename to en/guides/biao-zhu/annotation-reply.md diff --git a/en/features/logs.md b/en/guides/biao-zhu/logs.md similarity index 100% rename from en/features/logs.md rename to en/guides/biao-zhu/logs.md diff --git a/en/features/extension/README.md b/en/guides/extension/README.md similarity index 100% rename from en/features/extension/README.md rename to en/guides/extension/README.md diff --git a/en/features/extension/api_based_extension/README.md b/en/guides/extension/api-based-extension/README.md similarity index 100% rename from en/features/extension/api_based_extension/README.md rename to en/guides/extension/api-based-extension/README.md diff --git a/en/tutorials/cloudflare_workers.md b/en/guides/extension/api-based-extension/cloudflare-workers.md similarity index 100% rename from en/tutorials/cloudflare_workers.md rename to en/guides/extension/api-based-extension/cloudflare-workers.md diff --git a/en/guides/extension/api-based-extension/external-data-tool.md b/en/guides/extension/api-based-extension/external-data-tool.md new file mode 100644 index 0000000..9234f46 --- /dev/null +++ b/en/guides/extension/api-based-extension/external-data-tool.md @@ -0,0 +1,193 @@ +# External Data Tools + +External data tools are used to fetch additional data from external sources after the end user submits data, and then assemble this data into prompts as additional context information for the LLM. Dify provides a default tool for external API calls, see [api_based_extension](../api_based_extension/ "mention") for details. + +For developers deploying Dify locally, to meet more customized needs or to avoid developing an additional API Server, you can directly insert custom external data tool logic in the form of a plugin based on the Dify service. After extending custom tools, your custom tool options will be added to the dropdown list of tool types, and team members can use these custom tools to fetch external data. + +## Quick Start + +Here is an example of extending an external data tool for `Weather Search`, with the following steps: + +1. Initialize the directory +2. Add frontend form specifications +3. Add implementation class +4. Preview the frontend interface +5. Debug the extension + +### 1. **Initialize the Directory** + +To add a custom type `Weather Search`, you need to create the relevant directory and files under `api/core/external_data_tool`. + +```python +. +└── api + └── core + └── external_data_tool + └── weather_search + ├── __init__.py + ├── weather_search.py + └── schema.json +``` + +### 2. **Add Frontend Component Specifications** + +* `schema.json`, which defines the frontend component specifications, detailed in [.](./ "mention") + +```json +{ + "label": { + "en-US": "Weather Search", + "zh-Hans": "天气查询" + }, + "form_schema": [ + { + "type": "select", + "label": { + "en-US": "Temperature Unit", + "zh-Hans": "温度单位" + }, + "variable": "temperature_unit", + "required": true, + "options": [ + { + "label": { + "en-US": "Fahrenheit", + "zh-Hans": "华氏度" + }, + "value": "fahrenheit" + }, + { + "label": { + "en-US": "Centigrade", + "zh-Hans": "摄氏度" + }, + "value": "centigrade" + } + ], + "default": "centigrade", + "placeholder": "Please select temperature unit" + } + ] +} +``` + +### 3. Add Implementation Class + +`weather_search.py` code template, where you can implement the specific business logic. + +{% hint style="warning" %} +Note: The class variable `name` must be the custom type name, consistent with the directory and file name, and must be unique. +{% endhint %} + +```python +from typing import Optional + +from core.external_data_tool.base import ExternalDataTool + + +class WeatherSearch(ExternalDataTool): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "weather_search" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user save the config. + + Example: + .. code-block:: python + config = { + "temperature_unit": "centigrade" + } + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + + if not config.get('temperature_unit'): + raise ValueError('temperature unit is required') + + def query(self, inputs: dict, query: Optional[str] = None) -> str: + """ + Query the external data tool. + + :param inputs: user inputs + :param query: the query of chat app + :return: the tool query result + """ + city = inputs.get('city') + temperature_unit = self.config.get('temperature_unit') + + if temperature_unit == 'fahrenheit': + return f'Weather in {city} is 32°F' + else: + return f'Weather in {city} is 0°C' +``` + +### 4. **Preview the Frontend Interface** + +Follow the above steps and run the service to see the newly added custom type. + +

Add Tool

+ +### 5. **Debug the Extension** + +Now, you can select the custom `Weather Search` external data tool extension type in the Dify application orchestration interface for debugging. + +## Implementation Class Template + +```python +from typing import Optional + +from core.external_data_tool.base import ExternalDataTool + + +class WeatherSearch(ExternalDataTool): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "weather_search" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user save the config. + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + + # implement your own logic here + + def query(self, inputs: dict, query: Optional[str] = None) -> str: + """ + Query the external data tool. + + :param inputs: user inputs + :param query: the query of chat app + :return: the tool query result + """ + + # implement your own logic here + return "your own data." +``` + +### Detailed Introduction to Implementation Class Development + +### def validate_config + +`schema.json` form validation method, called when the user clicks "Publish" to save the configuration. + +* `config` form parameters + * `{{variable}}` custom form variables + +### def query + +User-defined data query implementation, the returned result will be replaced into the specified variable. + +* `inputs`: Variables passed by the end user +* `query`: Current conversation input content from the end user, a fixed parameter for conversational applications. \ No newline at end of file diff --git a/en/features/extension/api_based_extension/moderation-extension.md b/en/guides/extension/api-based-extension/moderation-extension.md similarity index 100% rename from en/features/extension/api_based_extension/moderation-extension.md rename to en/guides/extension/api-based-extension/moderation-extension.md diff --git a/en/guides/extension/api-based-extension/moderation.md b/en/guides/extension/api-based-extension/moderation.md new file mode 100644 index 0000000..46cd41d --- /dev/null +++ b/en/guides/extension/api-based-extension/moderation.md @@ -0,0 +1,137 @@ +# Sensitive Content Moderation + +This module is used to review the content input by end-users and the output content of the LLM within the application. It is divided into two types of extension points. + +### Extension Points + +* `app.moderation.input` - Extension point for reviewing end-user input content + * Used to review the variable content passed in by end-users and the input content of conversational applications. +* `app.moderation.output` - Extension point for reviewing LLM output content + * Used to review the content output by the LLM. + * When the LLM output is streamed, the content will be segmented into 100-character blocks for API requests to avoid delays in reviewing longer outputs. + +### app.moderation.input Extension Point + +#### Request Body + +``` +{ + "point": "app.moderation.input", // Extension point type, fixed as app.moderation.input here + "params": { + "app_id": string, // Application ID + "inputs": { // Variable values passed in by end-users, key is the variable name, value is the variable value + "var_1": "value_1", + "var_2": "value_2", + ... + }, + "query": string | null // Current dialogue input content from the end-user, fixed parameter for conversational applications. + } +} +``` + +* Example + * ``` + { + "point": "app.moderation.input", + "params": { + "app_id": "61248ab4-1125-45be-ae32-0ce91334d021", + "inputs": { + "var_1": "I will kill you.", + "var_2": "I will fuck you." + }, + "query": "Happy everydays." + } + } + ``` + +#### API Response + +``` +{ + "flagged": bool, // Whether it violates the moderation rules + "action": string, // Action to take, direct_output for directly outputting a preset response; overrided for overriding the input variable values + "preset_response": string, // Preset response (returned only when action=direct_output) + "inputs": { // Variable values passed in by end-users, key is the variable name, value is the variable value (returned only when action=overrided) + "var_1": "value_1", + "var_2": "value_2", + ... + }, + "query": string | null // Overridden current dialogue input content from the end-user, fixed parameter for conversational applications. (returned only when action=overrided) +} +``` + +* Example + * `action=direct_output` + * ``` + { + "flagged": true, + "action": "direct_output", + "preset_response": "Your content violates our usage policy." + } + ``` + * `action=overrided` + * ``` + { + "flagged": true, + "action": "overrided", + "inputs": { + "var_1": "I will *** you.", + "var_2": "I will *** you." + }, + "query": "Happy everydays." + } + ``` + +### app.moderation.output Extension Point + +#### Request Body + +``` +{ + "point": "app.moderation.output", // Extension point type, fixed as app.moderation.output here + "params": { + "app_id": string, // Application ID + "text": string // LLM response content. When the LLM output is streamed, this will be content segmented into 100-character blocks. + } +} +``` + +* Example + * ``` + { + "point": "app.moderation.output", + "params": { + "app_id": "61248ab4-1125-45be-ae32-0ce91334d021", + "text": "I will kill you." + } + } + ``` + +#### API Response + +``` +{ + "flagged": bool, // Whether it violates the moderation rules + "action": string, // Action to take, direct_output for directly outputting a preset response; overrided for overriding the input variable values + "preset_response": string, // Preset response (returned only when action=direct_output) + "text": string // Overridden LLM response content (returned only when action=overrided) +} +``` + +* Example + * `action=direct_output` + * ``` + { + "flagged": true, + "action": "direct_output", + "preset_response": "Your content violates our usage policy." + } + ``` + * `action=overrided` + * ``` + { + "flagged": true, + "action": "overrided", + "text": "I will *** you." + } + ``` \ No newline at end of file diff --git a/en/guides/extension/code-based-extension/README.md b/en/guides/extension/code-based-extension/README.md new file mode 100644 index 0000000..d4053b8 --- /dev/null +++ b/en/guides/extension/code-based-extension/README.md @@ -0,0 +1,98 @@ +# Code Based Extensions + +For developers deploying Dify locally, if you want to implement extension capabilities without rewriting an API service, you can use code extensions. This allows you to extend or enhance the functionality of the program in code form (i.e., plugin capability) without disrupting the original code logic of Dify. It follows certain interfaces or specifications to achieve compatibility and plug-and-play capability with the main program. Currently, Dify offers two types of code extensions: + +* Adding a new type of external data tool [external_data_tool.md](external_data_tool.md "mention") +* Extending sensitive content moderation strategies [moderation.md](moderation.md "mention") + +Based on the above functionalities, you can achieve horizontal expansion by following the code-level interface specifications. If you are willing to contribute your extensions to us, we warmly welcome you to submit a PR to Dify. + +## Frontend Component Specification Definition + +The frontend styles of code extensions are defined through `schema.json`: + +* label: Custom type name, supporting system language switching +* form_schema: List of form contents + * type: Component type + * select: Dropdown options + * text-input: Text + * paragraph: Paragraph + * label: Component name, supporting system language switching + * variable: Variable name + * required: Whether it is required + * default: Default value + * placeholder: Component hint content + * options: Exclusive property for the "select" component, defining the dropdown contents + * label: Dropdown name, supporting system language switching + * value: Dropdown option value + * max_length: Exclusive property for the "text-input" component, maximum length + +### Template Example + +```json +{ + "label": { + "en-US": "Cloud Service", + "zh-Hans": "云服务" + }, + "form_schema": [ + { + "type": "select", + "label": { + "en-US": "Cloud Provider", + "zh-Hans": "云厂商" + }, + "variable": "cloud_provider", + "required": true, + "options": [ + { + "label": { + "en-US": "AWS", + "zh-Hans": "亚马逊" + }, + "value": "AWS" + }, + { + "label": { + "en-US": "Google Cloud", + "zh-Hans": "谷歌云" + }, + "value": "GoogleCloud" + }, + { + "label": { + "en-US": "Azure Cloud", + "zh-Hans": "微软云" + }, + "value": "Azure" + } + ], + "default": "GoogleCloud", + "placeholder": "" + }, + { + "type": "text-input", + "label": { + "en-US": "API Endpoint", + "zh-Hans": "API Endpoint" + }, + "variable": "api_endpoint", + "required": true, + "max_length": 100, + "default": "", + "placeholder": "https://api.example.com" + }, + { + "type": "paragraph", + "label": { + "en-US": "API Key", + "zh-Hans": "API Key" + }, + "variable": "api_keys", + "required": true, + "default": "", + "placeholder": "Paste your API key here" + } + ] +} +``` \ No newline at end of file diff --git a/en/guides/extension/code-based-extension/external-data-tool.md b/en/guides/extension/code-based-extension/external-data-tool.md new file mode 100644 index 0000000..9234f46 --- /dev/null +++ b/en/guides/extension/code-based-extension/external-data-tool.md @@ -0,0 +1,193 @@ +# External Data Tools + +External data tools are used to fetch additional data from external sources after the end user submits data, and then assemble this data into prompts as additional context information for the LLM. Dify provides a default tool for external API calls, see [api_based_extension](../api_based_extension/ "mention") for details. + +For developers deploying Dify locally, to meet more customized needs or to avoid developing an additional API Server, you can directly insert custom external data tool logic in the form of a plugin based on the Dify service. After extending custom tools, your custom tool options will be added to the dropdown list of tool types, and team members can use these custom tools to fetch external data. + +## Quick Start + +Here is an example of extending an external data tool for `Weather Search`, with the following steps: + +1. Initialize the directory +2. Add frontend form specifications +3. Add implementation class +4. Preview the frontend interface +5. Debug the extension + +### 1. **Initialize the Directory** + +To add a custom type `Weather Search`, you need to create the relevant directory and files under `api/core/external_data_tool`. + +```python +. +└── api + └── core + └── external_data_tool + └── weather_search + ├── __init__.py + ├── weather_search.py + └── schema.json +``` + +### 2. **Add Frontend Component Specifications** + +* `schema.json`, which defines the frontend component specifications, detailed in [.](./ "mention") + +```json +{ + "label": { + "en-US": "Weather Search", + "zh-Hans": "天气查询" + }, + "form_schema": [ + { + "type": "select", + "label": { + "en-US": "Temperature Unit", + "zh-Hans": "温度单位" + }, + "variable": "temperature_unit", + "required": true, + "options": [ + { + "label": { + "en-US": "Fahrenheit", + "zh-Hans": "华氏度" + }, + "value": "fahrenheit" + }, + { + "label": { + "en-US": "Centigrade", + "zh-Hans": "摄氏度" + }, + "value": "centigrade" + } + ], + "default": "centigrade", + "placeholder": "Please select temperature unit" + } + ] +} +``` + +### 3. Add Implementation Class + +`weather_search.py` code template, where you can implement the specific business logic. + +{% hint style="warning" %} +Note: The class variable `name` must be the custom type name, consistent with the directory and file name, and must be unique. +{% endhint %} + +```python +from typing import Optional + +from core.external_data_tool.base import ExternalDataTool + + +class WeatherSearch(ExternalDataTool): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "weather_search" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user save the config. + + Example: + .. code-block:: python + config = { + "temperature_unit": "centigrade" + } + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + + if not config.get('temperature_unit'): + raise ValueError('temperature unit is required') + + def query(self, inputs: dict, query: Optional[str] = None) -> str: + """ + Query the external data tool. + + :param inputs: user inputs + :param query: the query of chat app + :return: the tool query result + """ + city = inputs.get('city') + temperature_unit = self.config.get('temperature_unit') + + if temperature_unit == 'fahrenheit': + return f'Weather in {city} is 32°F' + else: + return f'Weather in {city} is 0°C' +``` + +### 4. **Preview the Frontend Interface** + +Follow the above steps and run the service to see the newly added custom type. + +

Add Tool

+ +### 5. **Debug the Extension** + +Now, you can select the custom `Weather Search` external data tool extension type in the Dify application orchestration interface for debugging. + +## Implementation Class Template + +```python +from typing import Optional + +from core.external_data_tool.base import ExternalDataTool + + +class WeatherSearch(ExternalDataTool): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "weather_search" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user save the config. + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + + # implement your own logic here + + def query(self, inputs: dict, query: Optional[str] = None) -> str: + """ + Query the external data tool. + + :param inputs: user inputs + :param query: the query of chat app + :return: the tool query result + """ + + # implement your own logic here + return "your own data." +``` + +### Detailed Introduction to Implementation Class Development + +### def validate_config + +`schema.json` form validation method, called when the user clicks "Publish" to save the configuration. + +* `config` form parameters + * `{{variable}}` custom form variables + +### def query + +User-defined data query implementation, the returned result will be replaced into the specified variable. + +* `inputs`: Variables passed by the end user +* `query`: Current conversation input content from the end user, a fixed parameter for conversational applications. \ No newline at end of file diff --git a/en/guides/extension/code-based-extension/moderation.md b/en/guides/extension/code-based-extension/moderation.md new file mode 100644 index 0000000..1b4634e --- /dev/null +++ b/en/guides/extension/code-based-extension/moderation.md @@ -0,0 +1,314 @@ +# Sensitive Content Moderation + +In addition to the system's built-in content moderation types, Dify also supports user-defined content moderation rules. This method is suitable for developers customizing their own private deployments. For instance, in an enterprise internal customer service setup, it may be required that users, while querying or customer service agents while responding, not only avoid entering words related to violence, sex, and illegal activities but also avoid specific terms forbidden by the enterprise or violating internally established moderation logic. Developers can extend custom content moderation rules at the code level in a private deployment of Dify. + +## Quick Start + +Here is an example of extending a `Cloud Service` content moderation type, with the steps as follows: + +1. Initialize the directory +2. Add the frontend component definition file +3. Add the implementation class +4. Preview the frontend interface +5. Debug the extension + +### 1. Initialize the Directory + +To add a custom type `Cloud Service`, create the relevant directories and files under the `api/core/moderation` directory. + +```Plain +. +└── api + └── core + └── moderation + └── cloud_service + ├── __init__.py + ├── cloud_service.py + └── schema.json +``` + +### 2. Add Frontend Component Specifications + +* `schema.json`: This file defines the frontend component specifications. For details, see [.](./ "mention"). + +```json +{ + "label": { + "en-US": "Cloud Service", + "zh-Hans": "云服务" + }, + "form_schema": [ + { + "type": "select", + "label": { + "en-US": "Cloud Provider", + "zh-Hans": "云厂商" + }, + "variable": "cloud_provider", + "required": true, + "options": [ + { + "label": { + "en-US": "AWS", + "zh-Hans": "亚马逊" + }, + "value": "AWS" + }, + { + "label": { + "en-US": "Google Cloud", + "zh-Hans": "谷歌云" + }, + "value": "GoogleCloud" + }, + { + "label": { + "en-US": "Azure Cloud", + "zh-Hans": "微软云" + }, + "value": "Azure" + } + ], + "default": "GoogleCloud", + "placeholder": "" + }, + { + "type": "text-input", + "label": { + "en-US": "API Endpoint", + "zh-Hans": "API Endpoint" + }, + "variable": "api_endpoint", + "required": true, + "max_length": 100, + "default": "", + "placeholder": "https://api.example.com" + }, + { + "type": "paragraph", + "label": { + "en-US": "API Key", + "zh-Hans": "API Key" + }, + "variable": "api_keys", + "required": true, + "default": "", + "placeholder": "Paste your API key here" + } + ] +} +``` + +### 3. Add Implementation Class + +`cloud_service.py` code template where you can implement specific business logic. + +{% hint style="warning" %} +Note: The class variable name must be the same as the custom type name, matching the directory and file names, and must be unique. +{% endhint %} + +```python +from core.moderation.base import Moderation, ModerationAction, ModerationInputsResult, ModerationOutputsResult + +class CloudServiceModeration(Moderation): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "cloud_service" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user saves the config. + + Example: + .. code-block:: python + config = { + "cloud_provider": "GoogleCloud", + "api_endpoint": "https://api.example.com", + "api_keys": "123456", + "inputs_config": { + "enabled": True, + "preset_response": "Your content violates our usage policy. Please revise and try again." + }, + "outputs_config": { + "enabled": True, + "preset_response": "Your content violates our usage policy. Please revise and try again." + } + } + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + + cls._validate_inputs_and_outputs_config(config, True) + + if not config.get("cloud_provider"): + raise ValueError("cloud_provider is required") + + if not config.get("api_endpoint"): + raise ValueError("api_endpoint is required") + + if not config.get("api_keys"): + raise ValueError("api_keys is required") + + def moderation_for_inputs(self, inputs: dict, query: str = "") -> ModerationInputsResult: + """ + Moderation for inputs. + + :param inputs: user inputs + :param query: the query of chat app, there is empty if is completion app + :return: the moderation result + """ + flagged = False + preset_response = "" + + if self.config['inputs_config']['enabled']: + preset_response = self.config['inputs_config']['preset_response'] + + if query: + inputs['query__'] = query + flagged = self._is_violated(inputs) + + # return ModerationInputsResult(flagged=flagged, action=ModerationAction.OVERRIDED, inputs=inputs, query=query) + return ModerationInputsResult(flagged=flagged, action=ModerationAction.DIRECT_OUTPUT, preset_response=preset_response) + + def moderation_for_outputs(self, text: str) -> ModerationOutputsResult: + """ + Moderation for outputs. + + :param text: the text of LLM response + :return: the moderation result + """ + flagged = False + preset_response = "" + + if self.config['outputs_config']['enabled']: + preset_response = self.config['outputs_config']['preset_response'] + + flagged = self._is_violated({'text': text}) + + # return ModerationOutputsResult(flagged=flagged, action=ModerationAction.OVERRIDED, text=text) + return ModerationOutputsResult(flagged=flagged, action=ModerationAction.DIRECT_OUTPUT, preset_response=preset_response) + + def _is_violated(self, inputs: dict): + """ + The main logic of moderation. + + :param inputs: + :return: the moderation result + """ + return False +``` + +### 4. Preview Frontend Interface + +Following the above steps, run the service to see the newly added custom type. + +

Cloud Service

+ +### 5. Debug the Extension + +At this point, you can select the custom `Cloud Service` content moderation extension type for debugging in the Dify application orchestration interface. + +## Implementation Class Template + +```python +from core.moderation.base import Moderation, ModerationAction, ModerationInputsResult, ModerationOutputsResult + +class CloudServiceModeration(Moderation): + """ + The name of custom type must be unique, keep the same with directory and file name. + """ + name: str = "cloud_service" + + @classmethod + def validate_config(cls, tenant_id: str, config: dict) -> None: + """ + schema.json validation. It will be called when user saves the config. + + :param tenant_id: the id of workspace + :param config: the variables of form config + :return: + """ + cls._validate_inputs_and_outputs_config(config, True) + + # implement your own logic here + + def moderation_for_inputs(self, inputs: dict, query: str = "") -> ModerationInputsResult: + """ + Moderation for inputs. + + :param inputs: user inputs + :param query: the query of chat app, there is empty if is completion app + :return: the moderation result + """ + flagged = False + preset_response = "" + + # implement your own logic here + + # return ModerationInputsResult(flagged=flagged, action=ModerationAction.OVERRIDED, inputs=inputs, query=query) + return ModerationInputsResult(flagged=flagged, action=ModerationAction.DIRECT_OUTPUT, preset_response=preset_response) + + def moderation_for_outputs(self, text: str) -> ModerationOutputsResult: + """ + Moderation for outputs. + + :param text: the text of LLM response + :return: the moderation result + """ + flagged = False + preset_response = "" + + # implement your own logic here + + # return ModerationOutputsResult(flagged=flagged, action=ModerationAction.OVERRIDED, text=text) + return ModerationOutputsResult(flagged=flagged, action=ModerationAction.DIRECT_OUTPUT, preset_response=preset_response) +``` + +## Detailed Introduction to Implementation Class Development + +### def validate\_config + +The `schema.json` form validation method is called when the user clicks "Publish" to save the configuration. + +* `config` form parameters + * `{{variable}}` custom variable of the form + * `inputs_config` input moderation preset response + * `enabled` whether it is enabled + * `preset_response` input preset response + * `outputs_config` output moderation preset response + * `enabled` whether it is enabled + * `preset_response` output preset response + +### def moderation\_for\_inputs + +Input validation function + +* `inputs`: values passed by the end user +* `query`: the current input content of the end user in a conversation, a fixed parameter for conversational applications. +* `ModerationInputsResult` + * `flagged`: whether it violates the moderation rules + * `action`: action to be taken + * `direct_output`: directly output the preset response + * `overrided`: override the passed variable values + * `preset_response`: preset response (returned only when action=direct_output) + * `inputs`: values passed by the end user, with key as the variable name and value as the variable value (returned only when action=overrided) + * `query`: overridden current input content of the end user in a conversation, a fixed parameter for conversational applications (returned only when action=overrided) + +### def moderation\_for\_outputs + +Output validation function + +* `text`: content output by the model +* `moderation_for_outputs`: output validation function + * `text`: content of the LLM response. When the LLM output is streamed, this is the content in segments of 100 characters. + * `ModerationOutputsResult` + * `flagged`: whether it violates the moderation rules + * `action`: action to be taken + * `direct_output`: directly output the preset response + * `overrided`: override the passed variable values + * `preset_response`: preset response (returned only when action=direct_output) + * `text`: overridden content of the LLM response (returned only when action=overrided). \ No newline at end of file diff --git a/en/guides/knowledge-base/README.md b/en/guides/knowledge-base/README.md new file mode 100644 index 0000000..524593f --- /dev/null +++ b/en/guides/knowledge-base/README.md @@ -0,0 +1,30 @@ +### Literal Translation +# Knowledge Base + +The training data for large language models is generally based on publicly available data, and each training session requires a significant amount of computational power. This means that the knowledge of the models generally does not include private domain knowledge, and there is a certain delay in the public knowledge domain. To solve this problem, the current common solution is to use RAG (Retrieval-Augmented Generation) technology, which uses users' questions to match the most relevant external data, and after retrieving the relevant content, reorganize and insert the response back as the context of the model prompt. + +{% hint style="info" %} +To learn more, please check the extended reading on [Retrieval-Augmented Generation (RAG)](../../learn-more/extended-reading/retrieval-augment/) +{% endhint %} + + +Dify's knowledge base feature visualizes each step in the RAG pipeline, providing a simple and easy-to-use user interface to help application builders in managing personal or team knowledge bases, and quickly integrating them into AI applications. You only need to prepare text content, such as: + +* Long text content (TXT, Markdown, DOCX, HTML, JSONL, or even PDF files) +* Structured data (CSV, Excel, etc.) + +Additionally, we are gradually supporting synchronizing data from various data sources to datasets, including: + +* Web pages +* Notion +* Github +* Databases +* …… + +{% hint style="info" %} +**Scenario**: If your company wants to establish an AI customer service assistant based on the existing knowledge base and product documentation, you can upload the documents to the dataset in Dify and build a chatbot. In the past, this might have taken you weeks and been difficult to maintain continuously. +{% endhint %} + +### Knowledge Base and Documents + +In Dify, Knowledge is a collection of documents. A knowledge base can be integrated into an application as a retrieval context. Documents can be uploaded by developers or a member of operation team, or synchronized from other data sources (usually corresponding to one unit file in the data source). \ No newline at end of file diff --git a/en/guides/knowledge-base/create-knowledge-and-upload-documents.md b/en/guides/knowledge-base/create-knowledge-and-upload-documents.md new file mode 100644 index 0000000..04e2d0f --- /dev/null +++ b/en/guides/knowledge-base/create-knowledge-and-upload-documents.md @@ -0,0 +1,151 @@ +# Creating a Knowledge Base & Uploading Documents + +### 1 Creating a Knowledge Base + +Click on Knowledge in the main navigation bar of Dify. On this page, you can see your existing knowledge bases. Click **Create Knowledge** to enter the setup wizard: + +

Creating Knowledge

+ +* If you have already prepared the files, you can start by uploading them; +* If you have not prepared any documents yet, you can first create an empty dataset; + +

Creating Knowledge Base

+ +{% hint style="info" %} +If you choose to use an external data source when creating a dataset, the type of knowledge cannot be changed. This is to prevent difficulties in managing datasets caused by having multiple data sources in a single knowledge base. If you need to use multiple data sources, it is recommended to create multiple knowledge. +{% endhint %} + +*** + +### 2 Uploading Documents + +**Steps to upload documents into Knowledge:** + +1. Select the document you need to upload from your local files; +2. Segment and clean the document, and preview the effect; +3. Choose and configure Index Mode and Retreival Settings; +4. Wait for the chunks to be embedded; +5. Upload completed, now you can use it in your applications 🎉 + +**Limitations for uploading documents:** + +* The upload size limit for a single document is 15MB; +* The maximum number of files for a single batch upload is 20; +* Different [subscription plans](https://dify.ai/pricing) for the SaaS version limit **batch upload numbers, total document uploads, and vector storage**; + +### 3 Segmenting and Cleaning + +**Segmenting**: Large language models have a limited context window, usually requiring the entire text to be segmented and then recalling the most relevant segments to the user’s question, known as the segment TopK recall mode. Additionally, appropriate segment sizes help match the most relevant text content and reduce information noise when semantically matching user questions with text segments. + +**Cleaning**: To ensure the quality of text recall, it is usually necessary to clean the data before passing it into the model. For example, unwanted characters or blank lines in the output may affect the quality of the response. To help users solve this problem, Dify provides various cleaning methods to help clean the output before sending it to downstream applications. + +Segmentation and cleaning support two configuration strategies: + +* Automatic mode (to be phased out) +* Custom mode + +
+ +In custom mode, users can configure chunk settings and cleaning settings according to different document formats and scenario requirements. + +**Segmentation rules:** + +* Segmentation identifier, set an identifier such as "\n", and the system will segment the text when the identifier appears in the text; +* Maximum segment length, segment based on the maximum character limit of the text, forcibly segmenting when exceeding this length; +* Segment overlap length, set the number of overlapping characters between segments, it is recommended to set it to 10-25% of the segment length, which helps retain semantic relevance between segments and improves recall results during multi-segment recall. + +**Preprocessing rules:** + +* Replace continuous spaces, newlines, and tabs; +* Delete all URLs and email addresses; + +*** + +### 4 Optional ETL Configuration + +In production-level applications of RAG, to achieve better data recall, multi-source data needs to be preprocessed and cleaned, i.e., ETL (extract, transform, load). To enhance the preprocessing capabilities of unstructured/semi-structured data, Dify supports optional ETL solutions: **Dify ETL** and [**Unstructured ETL**](https://unstructured.io/). + +> Unstructured can efficiently extract and transform your data into clean data for subsequent steps. + +ETL solution choices in different versions of Dify: + +* The SaaS version defaults to using Unstructured ETL and cannot be changed; +* The community version defaults to using Dify ETL but can enable Unstructured ETL through [environment variables](../../getting-started/install-self-hosted/environments.md#zhi-shi-ku-pei-zhi); + + +Differences in supported file formats for parsing: + +| DIFY ETL | Unstructured ETL | +| ---------------------------------------------- | ------------------------------------------------------------------------ | +| txt, markdown, md, pdf, html, htm, xlsx, xls, docx, csv | txt, markdown, md, pdf, html, htm, xlsx, xls, docx, csv, eml, msg, pptx, ppt, xml, epub | + +{% hint style="info" %} +Different ETL solutions may have differences in file extraction effects. For more information on Unstructured ETL’s data processing methods, please refer to the [official documentation](https://docs.unstructured.io/open-source/core-functionality/partitioning). +{% endhint %} + +*** + +### 5 Indexing Methods + +You need to choose the **indexing method** for the text to specify the data matching method. The indexing strategy is often related to the retrieval method, and you need to choose the appropriate indexing method according to the scenario. + +**High-Quality Mode**: Calls OpenAI's embedding interface for processing, providing higher accuracy during user queries. + +**Economy Mode**: Uses keyword indexing, reducing accuracy but not requiring token costs. + +**Q\&A Mode (community version only)**: The Q\&A segment mode function differs from the ordinary "Q to P" (question to paragraph) matching mode mentioned above. It uses the "Q to Q" (question to question) matching mode. After the document is segmented, each segment generates a Q\&A matching pair through summarization. When a user asks a question, the system finds the most similar question and returns the corresponding segment as the answer. This method is more precise because it directly matches the user’s question, accurately obtaining the information the user truly needs. + +When uploading documents to the knowledge base, the system segments the text so that the user's questions (input) can match the relevant text segments (Q to P), and finally output the result. + +> Question text is natural language with complete grammatical structure, not just some keywords in a document retrieval task. Therefore, the Q to Q (question matching question) mode makes semantics and matching clearer and meets the needs of high-frequency and high-similarity question scenarios. + +

Texts summarized into multiple Q&A pairs in Q&A segment mode

+ +

Difference between Q to P and Q to Q indexing modes

+ +*** + +### 6 Retrieval Settings + +In high-quality indexing mode, Dify offers three retrieval options: + +* **Vector Search**, generating query embeddings and searching for the text chunk most similar to its vector representation. +* **Full-Text Search**, indexing all terms in the document, allowing users to search any term and retrieve relevant text chunk containing those terms. +* **Hybrid Search**, executing full-text search and vector searches simultaneously, re-rank to select the best match for the user's query. Configuration of the Rerank model APIis necessary. + +The specific configurations for the three retrieval methods are as follows: + +#### **Vector Search** + +Definition: By generating query embeddings to search the most similar text chunk to the query's vector representation. + + +

Vector Search Settings

+ +TopK: Used to filter the text chunk most similar to the user’s query. The system will dynamically adjust the number of chunks based on the context window size of the selected model. The default value is 3. + +Score threshold: Used to set the similarity threshold for filtering text fragments, i.e., only recall text fragments that exceed the set score. The system disables this setting by default, meaning no filtering is applied to the similarity values of the recalled text fragments. The default value is 0.5 when enabled. + +Rerank model: After configuring the API key for the Rerank model in the “Model Provider” page, you can + + enable the “Rerank model” in the retrieval settings. The system will semantically rerank the recalled document results after vector retrieval to optimize the ranking results. After setting the Rerank model, TopK and Score threshold settings only take effect in the Rerank step. + +#### **Full-Text Search** + +Definition: Indexing all terms in the document, allowing users to query any terms and return text fragments containing those terms. + +

Full-Text Search Settings

+ +TopK: Used to filter the text fragments most similar to the user’s query. The system will dynamically adjust the number of fragments based on the context window size of the selected model. The default value is 3. + +Rerank model: After configuring the API key for the Rerank model in the “Model Provider” page, you can enable the “Rerank model” in the retrieval settings. The system will semantically rerank the recalled document results after full-text retrieval to optimize the ranking results. After setting the Rerank model, TopK and Score threshold settings only take effect in the Rerank step. + +#### **Hybrid Search** + +Performs full-text and vector search simultaneously, with an additional reranking step to select the best match for the user’s query from the two types of query results, requiring Rerank model API configuration. + +

Hybrid Search Settings

+ +TopK: Used to filter the text fragments most similar to the user’s query. The system will dynamically adjust the number of fragments based on the context window size of the selected model. The default value is 3. + +Rerank model: After configuring the API key for the Rerank model in the “Model Provider” page, you can enable the “Rerank model” in the retrieval settings. The system will semantically rerank the recalled document results after hybrid retrieval to optimize the ranking results. After setting the Rerank model, TopK and Score threshold settings only take effect in the Rerank step. \ No newline at end of file diff --git a/en/guides/knowledge-base/external-data-tool.md b/en/guides/knowledge-base/external-data-tool.md new file mode 100644 index 0000000..8d38eda --- /dev/null +++ b/en/guides/knowledge-base/external-data-tool.md @@ -0,0 +1,34 @@ +# External Data Tool + +## Feature Introduction + +Previously, the [.](./ "mention") feature allowed developers to directly upload various formats of long texts and structured data to build datasets, enabling AI applications to engage in conversations based on the latest context provided by the user. + +With this update, the **External Data Tool** empowers developers to use their own search capabilities or internal knowledge bases as external data for the LLM's context. This is achieved by extending the API to retrieve and embed external data into prompts. Compared to uploading datasets to the cloud, using the **External Data Tool** offers significant advantages in ensuring private data security, customizing searches, and accessing real-time data. + +## Implementation Details + +When an end-user makes a request to the dialogue system, the platform's backend will trigger the external data tool (i.e., call its own API). It will query external information related to the user's question, such as employee profiles or real-time records, and return relevant parts via the API. The platform's backend will assemble the returned results into text and inject it into the prompt as context to provide more personalized and user-need-aligned responses. + +## Operating Instructions + +1. Before using the external data tool, you need to prepare an API and an API Key for authentication. Please read [external\_data\_tool.md](../extension/api\_based\_extension/external\_data\_tool.md "mention") +2. Dify provides centralized API management. After adding the API extension configuration in the settings interface, it can be used directly in various applications on Dify. + +

API-based Extension

+ +3. For example, to "query the weather," enter the name, API endpoint, and API Key in the "Add API-based Extension" dialog box. After saving, we can call the API. + +

Weather Inquiry

+ +4. On the prompt orchestration page, click the "+ Add" button next to "Tools." In the opened "Add Tool" dialog box, fill in the name and variable name (the variable name will be referenced in the prompt, please fill in English), and select the API-based extension added in step 2. + +

External_data_tool

+ +5. In this way, we can assemble the queried external data into the prompt. For example, to query today's weather in London, you can add the `location` variable, input "London," combine it with the external data tool's extension variable name `weather_data`, and the debug output will be as follows: + +

Weather_search_tool

+ +In the dialogue logs, we can also see the real-time data returned by the API: + +

Prompt Log

\ No newline at end of file diff --git a/en/guides/knowledge-base/integrate-knowledge-within-application.md b/en/guides/knowledge-base/integrate-knowledge-within-application.md new file mode 100644 index 0000000..6f58b9c --- /dev/null +++ b/en/guides/knowledge-base/integrate-knowledge-within-application.md @@ -0,0 +1,104 @@ +# Integrating Knowledge Base within the Application + +### 1. Creating a Knowledge Base Application + +A knowledge base can be used as external knowledge to provide precise answers to user questions through a large language model. You can associate an existing knowledge base with any application type in Dify. + +Taking a chat assistant as an example, the process is as follows: + +1. Go to **Studio -- Create Application -- Create Chat Assistant** +2. Enter **Context Settings**, click **Add**, and select the already created knowledge base +3. In **Context Settings -- Parameter Settings**, configure the **Recall Strategy** +4. Enable **Citation and Attribution** in **Add Features** +5. In **Debug and Preview**, input user questions related to the knowledge base for debugging +6. After debugging, **Save and Publish** as an AI knowledge base Q&A application + +

Associating a knowledge base within the application

+ +*** + +### 2. Recall Modes + +Enter **Context -- Parameter Settings -- Recall Settings** to choose the recall mode for the knowledge base. + +**N-Choose-1 Recall**: Based on user intent and knowledge base description, the LLM autonomously selects the most relevant single knowledge base to query for related text. + +**Multi-Path Recall**: Matches all knowledge bases simultaneously based on user intent, querying related text fragments from multiple knowledge bases. After a re-ranking step, the best result matching the user question is selected from the multi-path query results. Requires configuration of the Rerank model API. + +
+ +**How to Choose a Recall Mode** + +N-Choose-1 Recall is driven by Function Call/ReAct, where each associated knowledge base acts as a tool function. The LLM autonomously selects the most relevant knowledge base to query based on the semantic match between the user question and the knowledge base description. + +The effectiveness of the N-Choose-1 mode is influenced by three main factors: + +* **The reasoning capability of the system model:** Some models have unstable adherence to Function Call/ReAct instructions. +* **Clarity of the knowledge base description:** The description content affects the LLM's reasoning about the user question and the related knowledge base. +* **Number of knowledge bases:** Too many knowledge bases can affect the LLM's reasoning accuracy and may exceed the context window length of the reasoning model. + +**Recommended Configuration for N-Choose-1 Mode:** Choose a system reasoning model with better performance, associate as few knowledge bases as possible, and provide precise knowledge base descriptions. + +When users upload a knowledge base, the system reasoning model automatically generates a summary description for the knowledge base. To achieve the best recall effect in this mode, you can check the system-generated summary description in "Knowledge Base -> Settings -> Knowledge Base Description" to ensure it clearly summarizes the content of the knowledge base. + +Below is the technical flowchart for the N-Choose-1 Recall mode: + +
+ +{% hint style="info" %} +N-Choose-1 Recall relies on the reasoning capability of the model and has many usage restrictions. The recall strategy for this mode is planned to be adjusted in Q3 2024. +{% endhint %} + +#### Multi-Path Recall Mode (Recommended) + +In Multi-Path Recall mode, the retriever searches for text content related to the user question across all knowledge bases associated with the application. The results of the multi-path recall are merged, and a subsequent re-ranking (Rerank) step reorders the retrieved documents semantically. + +Below is the technical flowchart for the Multi-Path Recall mode: + +
+ +{% hint style="info" %} +Multi-Path Recall mode requires the configuration of a Rerank model. +{% endhint %} + +The Multi-Path Recall mode does not depend on the reasoning capability of the model or the knowledge base description. This mode can achieve higher quality recall effects when retrieving from multiple knowledge bases. Therefore, it is **recommended to set the recall mode to Multi-Path Recall**. + +*** + +### 3. Re-Ranking (Rerank) + +The re-ranking model improves the results of semantic sorting by reordering the candidate document list based on the semantic match between the user question and the documents. It calculates the relevance score between the user question and each candidate document and returns a list of documents sorted by relevance from high to low. + +

Hybrid Retrieval + Re-Ranking

+ +{% hint style="info" %} +For more information about Rerank, please refer to the extended reading [Re-Ranking](integrate\_knowledge\_within\_application.md#zhong-pai-xu-rerank). +{% endhint %} + +#### How to Configure the Rerank Model? + +Dify currently supports the Cohere Rerank model. Enter the "Model Provider -> Cohere" page and fill in the Rerank model's API key: + +

Configuring the Cohere Rerank model in the model provider

+ +How to obtain the Cohere Rerank model? + +Log in to [https://cohere.com/rerank](https://cohere.com/rerank), register on the page, apply for the usage qualification of the Rerank model, and obtain the API key. + +{% hint style="info" %} +Besides supporting the Cohere Rerank API, you can also use local inference frameworks like Ollama and Xinference to deploy local Rerank models such as bge-reranker. +{% endhint %} + +#### Setting the Rerank Model + +Go to the "Dataset -> Create Dataset -> Retrieval Settings" page and add the Rerank settings. In addition to setting Rerank when creating a dataset, you can also change the Rerank configuration in the settings of an already created dataset. Change the Rerank configuration in the recall mode settings of the application orchestration dataset. + +

Setting the Rerank model in the dataset retrieval mode

+ +**TopK**: Used to set the number of relevant documents returned after Rerank. + +**Score Threshold**: Used to set the minimum score of relevant documents returned after Rerank. After setting the Rerank model, the TopK and Score Threshold settings only take effect in the Rerank step. + +When setting the recall mode to Multi-Path Recall in the "Prompt Orchestration -> Context -> Settings" page, you need to enable the Rerank model. + +

Setting the Rerank model in the dataset multi-path recall mode

\ No newline at end of file diff --git a/en/guides/knowledge-base/knowledge-and-documents-maintenance.md b/en/guides/knowledge-base/knowledge-and-documents-maintenance.md new file mode 100644 index 0000000..7f4a402 --- /dev/null +++ b/en/guides/knowledge-base/knowledge-and-documents-maintenance.md @@ -0,0 +1,111 @@ +# Knowledge Base and Document Maintenance + +### 1. Viewing Text Segments + +Each document uploaded to the knowledge base is stored in the form of text segments (Chunks). You can view the specific text content of each segment in the segment list. + +

Viewing uploaded document segments

+ +*** + +### 2. Checking Segment Quality + +The quality of document segmentation significantly affects the Q&A performance of the knowledge base application. It is recommended to manually check the segment quality before associating the knowledge base with the application. + +Although automated segmentation methods based on character length, identifiers, or NLP semantic segmentation can significantly reduce the workload of large-scale text segmentation, the quality of segmentation is related to the text structure of different document formats and the semantic context. Manual checking and correction can effectively compensate for the shortcomings of machine segmentation in semantic recognition. + +When checking segment quality, pay attention to the following situations: + +* **Overly short text segments**, leading to semantic loss; + +

Overly short text segments

+ +* **Overly long text segments**, leading to semantic noise affecting matching accuracy; + +

Overly long text segments

+ +* **Obvious semantic truncation**, which occurs when using maximum segment length limits, leading to forced semantic truncation and missing content during recall; + +

Obvious semantic truncation

+ +*** + +### 3. Adding Text Segments + +In the segment list, click "Add Segment" to add one or multiple custom segments to the document. + +
+ +When adding segments in bulk, you need to first download the CSV format segment upload template, edit all the segment content in Excel according to the template format, save the CSV file, and then upload it. + +

Bulk adding custom segments

+ +*** + +### 4. Editing Text Segments + +In the segment list, you can directly edit the content of the added segments, including the text content and keywords of the segments. + +

Editing document segments

+ +*** + +### 5. Metadata Management + +In addition to marking metadata information from different source documents, such as the title, URL, keywords, and description of web data, metadata will be used in the segment recall process of the knowledge base as structured fields for recall filtering or displaying citation sources. + +{% hint style="info" %} +The metadata filtering and citation source functions are not yet supported in the current version. +{% endhint %} + +

Metadata management

+ +*** + +### 6. Adding Documents + +In "Knowledge Base > Document List," click "Add File" to upload new documents or [Notion pages](sync-from-notion.md) to the created knowledge base. + +A knowledge base (Knowledge) is a collection of documents (Documents). Documents can be uploaded by developers or operators, or synchronized from other data sources (usually corresponding to a file unit in the data source). + +

Uploading new documents to the knowledge base

+ +*** + +### 7. Document Disable and Archive + +**Disable**: The dataset supports disabling documents or segments that are temporarily not to be indexed. In the dataset document list, click the disable button to disable the document. You can also disable an entire document or a specific segment in the document details. Disabled documents will not be indexed. Click enable on the disabled documents to cancel the disable status. + +**Archive**: Old document data that is no longer in use can be archived if you do not want to delete it. Archived data can only be viewed or deleted, not edited. In the dataset document list, click the archive button to archive the document. You can also archive documents in the document details. Archived documents will not be indexed. Archived documents can also be unarchived. + +*** + +### 8. Knowledge Base Settings + +Click **Settings** in the left navigation of the knowledge base to change the following settings: + +

Knowledge base settings

+ +**Knowledge Base Name**: Define a name to identify a knowledge base. + +**Knowledge Base Description**: Used to describe the information represented by the documents in the knowledge base. + +{% hint style="info" %} +When the recall mode of the knowledge base is N-Choose-1, the knowledge base is provided as a tool for LLM reasoning calls. The reasoning is based on the description of the knowledge base. If the description is empty, Dify's automatic indexing strategy will be used. +{% endhint %} + +**Visibility Permissions**: You can choose "Only Me" or "All Team Members." People without permissions will not be able to view and edit the dataset. + +**Index Mode**: [Reference Document](create\_knowledge\_and\_upload\_documents.md#index-mode) + +**Embedding Model**: Modify the embedding model of the knowledge base. Changing the embedding model will re-embed all documents in the knowledge base, and the original embeddings will be deleted. + +**Retrieval Settings**: [Reference Document](create\_knowledge\_and\_upload\_documents.md#retrieval-settings) + +*** + +### 9. Knowledge Base API Management + +Dify Knowledge Base provides a complete set of standard APIs. Developers can use API calls to perform daily management and maintenance operations such as adding, deleting, modifying, and querying documents and segments in the knowledge base. Please refer to the [Knowledge Base API Documentation](maintain-dataset-via-api.md). + +

Knowledge base API management

\ No newline at end of file diff --git a/en/features/datasets/maintain-dataset-via-api.md b/en/guides/knowledge-base/maintain-dataset-via-api.md similarity index 54% rename from en/features/datasets/maintain-dataset-via-api.md rename to en/guides/knowledge-base/maintain-dataset-via-api.md index b291b6f..5c9436b 100644 --- a/en/features/datasets/maintain-dataset-via-api.md +++ b/en/guides/knowledge-base/maintain-dataset-via-api.md @@ -1,25 +1,26 @@ -# Maintain Knowledge via API +# Maintaining Datasets via API -> Authentication, invocation method and application Service API remain consistent. The difference is that a knowledge API token can operate on all knowledge bases. +> Authentication and invocation methods are consistent with the application Service API. The difference is that a single dataset API token can operate on all datasets. -### Benefits of Using the Knowledge API -* Sync your data systems to Dify knowledge to create powerful workflows. -* Provide knowledge list and document list APIs as well as detail query interfaces, to facilitate building your own data management page. -* Support both plain text and file uploads/updates documents, as well as batch additions and modifications, to simplify your sync process. -* Reduce manual document handling and syncing time, improving visibility of Dify's software and services. +### Advantages of Using Dataset API -### How to use +* Synchronize your data system with Dify datasets to create powerful workflows. +* Provide dataset list, document list, and detail queries to facilitate building your own data management page. +* Support both plain text and file uploads and updates for documents, and support batch addition and modification at the segment level to streamline your synchronization process. +* Reduce the time spent on manual document processing and synchronization, enhancing your visibility into Dify's software and services. -Please go to the knowledge page, you can switch tap to the API page in the navigation on the left side. On this page, you can view the API documentation provided by Dify and manage credentials for accessing the Knowledge API. +### How to Use + +Navigate to the dataset page, and you can switch to the **API** page from the left navigation. On this page, you can view the dataset API documentation provided by Dify and manage the credentials for accessing the dataset API in **API Keys**.

Knowledge API Document

-## **Create Empty Knowledge** +### API Call Examples -**`POST /datasets`** +#### **Create an Empty Dataset** {% hint style="warning" %} -Used only to create an empty dataset +Only used to create an empty dataset {% endhint %} ``` @@ -27,24 +28,21 @@ curl --location --request POST 'https://api.dify.ai/v1/datasets' \ --header 'Authorization: Bearer {api_key}' \ --header 'Content-Type: application/json' \ --data-raw '{"name": "name"}' - ``` -#### **List of Knowledge** - +#### **Dataset List** ``` curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \ --header 'Authorization: Bearer {api_key}' - ``` -#### **Create A Document From Text** +#### **Create Document by Text** ``` -curl --location --request POST '/document/create_by_text>' \\ ---header 'Authorization: Bearer {api_key}' \\ ---header 'Content-Type: application/json' \\ +curl --location --request POST 'https://api.dify.ai/v1/datasets//document/create_by_text' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ --data-raw '{ "name": "Dify", "text": "Dify means Do it for you...", @@ -66,10 +64,9 @@ curl --location --request POST '

Recall Testing

+ +Clicking the icon in the upper right corner of the source text input box allows you to change the retrieval method and specific parameters of the current knowledge base. **Changes will only take effect during the recall testing process.** After completing the recall test and confirming changes to the retrieval parameters of the knowledge base, you need to make changes in [Knowledge Base Settings > Retrieval Settings](retrieval\_test\_and\_citation.md#zhi-shi-ku-she-zhi). + +

Recall Testing - Retrieval Settings

+ +**Suggested Steps for Recall Testing:** + +1. Design and organize test cases/test question sets covering common user questions. +2. Choose an appropriate retrieval strategy: vector search/full-text search/hybrid search. For the pros and cons of different retrieval methods, please refer to the extended reading [Retrieval-Augmented Generation (RAG)](../../learn-more/extended-reading/retrieval-augment/). +3. Debug the number of recall segments (TopK) and the recall score threshold (Score). Choose appropriate parameter combinations based on the application scenario, including the quality of the documents themselves. + +**How to Configure TopK Value and Recall Threshold (Score)** + +* **TopK represents the maximum number of recall segments when sorted in descending order of similarity scores.** A smaller TopK value will recall fewer segments, which may result in incomplete recall of relevant texts; a larger TopK value will recall more segments, which may result in recalling segments with lower semantic relevance, reducing the quality of LLM responses. +* **The recall threshold (Score) represents the minimum similarity score allowed for recall segments.** A smaller recall score will recall more segments, which may result in recalling less relevant segments; a larger recall score threshold will recall fewer segments, and if too large, may result in missing relevant segments. + +*** + +### 2. Citation and Attribution + +When testing the knowledge base effect within the application, you can go to **Workspace -- Add Function -- Citation Attribution** to enable the citation attribution feature. + +

Enable Citation and Attribution Feature

+ +After enabling the feature, when the large language model responds to a question by citing content from the knowledge base, you can view specific citation paragraph information below the response content, including **original segment text, segment number, matching degree**, etc. Clicking **Jump to Knowledge Base** above the cited segment allows quick access to the segment list in the knowledge base, facilitating developers in debugging and editing. + +

View Citation Information in Response Content

\ No newline at end of file diff --git a/en/guides/knowledge-base/sync-from-notion.md b/en/guides/knowledge-base/sync-from-notion.md new file mode 100644 index 0000000..243e0c4 --- /dev/null +++ b/en/guides/knowledge-base/sync-from-notion.md @@ -0,0 +1,70 @@ +# Importing Data from Notion + +Dify datasets support importing from Notion and setting up **synchronization** so that data updates in Notion are automatically synced to Dify. + +### 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. + +

Binding Notion

+ +### Importing 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. + +### Segmentation and Cleaning + +Next, choose your **segmentation settings** and **indexing method**, then **Save and Process**. Wait for Dify to process this data for you, which typically requires token consumption in the LLM provider. Dify supports importing not only standard page types but also aggregates and saves page properties under the database type. + +_**Please note: Images and files are not currently supported for import, and tabular data will be converted to text display.**_ + +### Synchronizing Notion Data + +If your Notion content is modified, you can directly click **Sync** in the Dify dataset **Document List Page** to perform a one-click data synchronization. This step requires token consumption. + +

Sync Notion Content

+ +### Integration Configuration Method for Community Edition Notion + +Notion integration can be done in two ways: **internal integration** and **public integration**. You can configure them as needed in Dify. For specific differences between the two integration methods, please refer to [Notion Official Documentation](https://developers.notion.com/docs/authorization). + +### 1. **Using Internal Integration** + +First, create an integration in the integration settings page [Create Integration](https://www.notion.so/my-integrations). By default, all integrations start as internal integrations; internal integrations will be associated with the workspace you choose, so you need to be the workspace owner to create an integration. + +Specific steps: + +Click the **New integration** button. The type is **Internal** by default (cannot be modified). Select the associated space, enter the integration name, upload a logo, and click **Submit** to create the integration successfully. + +
+ +After creating the integration, you can update its settings as needed under the Capabilities tab and click the **Show** button under Secrets to copy the secrets. + +
+ +After copying, go back to the Dify source code, and configure the relevant environment variables in the **.env** file. The environment variables are as follows: + +**NOTION\_INTEGRATION\_TYPE**=internal or **NOTION\_INTEGRATION\_TYPE**=public + +**NOTION\_INTERNAL\_SECRET**=your-internal-secret + +### 2. **Using Public Integration** + +**You need to upgrade the internal integration to a public integration.** Navigate to the Distribution page of the integration, and toggle the switch to make the integration public. When switching to the public setting, you need to fill in additional information in the Organization Information form below, including your company name, website, and redirect URL, then click the **Submit** button. + +
+ +After successfully making the integration public on the integration settings page, you will be able to access the integration key in the Keys tab: + +
+ +Go back to the Dify source code, and configure the relevant environment variables in the **.env** file. The environment variables are as follows: + +**NOTION\_INTEGRATION\_TYPE**=public + +**NOTION\_CLIENT\_SECRET**=your-client-secret + +**NOTION\_CLIENT\_ID**=your-client-id + +After configuration, you can operate the Notion data import and synchronization functions in the dataset. \ No newline at end of file diff --git a/en/guides/knowledge-base/sync-from-website.md b/en/guides/knowledge-base/sync-from-website.md new file mode 100644 index 0000000..b476a61 --- /dev/null +++ b/en/guides/knowledge-base/sync-from-website.md @@ -0,0 +1 @@ +# Under Maintenance diff --git a/en/tutorials/model-configuration/README.md b/en/guides/model-configuration/README.md similarity index 100% rename from en/tutorials/model-configuration/README.md rename to en/guides/model-configuration/README.md diff --git a/en/guides/model-configuration/customizable-model.md b/en/guides/model-configuration/customizable-model.md new file mode 100644 index 0000000..77eb923 --- /dev/null +++ b/en/guides/model-configuration/customizable-model.md @@ -0,0 +1,304 @@ +# Custom Model Integration + +### Introduction + +After completing vendor integration, the next step is to integrate models under the vendor. To help understand the entire integration process, we will use `Xinference` as an example to gradually complete a full vendor integration. + +It is important to note that for custom models, each model integration requires a complete vendor credential. + +Unlike predefined models, custom vendor integration will always have the following two parameters, which do not need to be defined in the vendor YAML file. + +
+ +In the previous section, we have learned that vendors do not need to implement `validate_provider_credential`. The Runtime will automatically call the corresponding model layer's `validate_credentials` based on the model type and model name selected by the user for validation. + +#### Writing Vendor YAML + +First, we need to determine what types of models the vendor supports. + +Currently supported model types are as follows: + +* `llm` Text Generation Model +* `text_embedding` Text Embedding Model +* `rerank` Rerank Model +* `speech2text` Speech to Text +* `tts` Text to Speech +* `moderation` Moderation + +`Xinference` supports `LLM`, `Text Embedding`, and `Rerank`, so we will start writing `xinference.yaml`. + +```yaml +provider: xinference # Specify vendor identifier +label: # Vendor display name, can be set in en_US (English) and zh_Hans (Simplified Chinese). If zh_Hans is not set, en_US will be used by default. + en_US: Xorbits Inference +icon_small: # Small icon, refer to other vendors' icons, stored in the _assets directory under the corresponding vendor implementation directory. Language strategy is the same as label. + en_US: icon_s_en.svg +icon_large: # Large icon + en_US: icon_l_en.svg +help: # Help + title: + en_US: How to deploy Xinference + zh_Hans: 如何部署 Xinference + url: + en_US: https://github.com/xorbitsai/inference +supported_model_types: # Supported model types. Xinference supports LLM/Text Embedding/Rerank +- llm +- text-embedding +- rerank +configurate_methods: # Since Xinference is a locally deployed vendor and does not have predefined models, you need to deploy the required models according to Xinference's documentation. Therefore, only custom models are supported here. +- customizable-model +provider_credential_schema: + credential_form_schemas: +``` + +Next, we need to consider what credentials are required to define a model in Xinference. + +* It supports three different types of models, so we need `model_type` to specify the type of the model. It has three types, so we write it as follows: + +```yaml +provider_credential_schema: + credential_form_schemas: + - variable: model_type + type: select + label: + en_US: Model type + zh_Hans: 模型类型 + required: true + options: + - value: text-generation + label: + en_US: Language Model + zh_Hans: 语言模型 + - value: embeddings + label: + en_US: Text Embedding + - value: reranking + label: + en_US: Rerank +``` + +* Each model has its own name `model_name`, so we need to define it here. + +```yaml + - variable: model_name + type: text-input + label: + en_US: Model name + zh_Hans: 模型名称 + required: true + placeholder: + zh_Hans: 填写模型名称 + en_US: Input model name +``` + +* Provide the address for the local deployment of Xinference. + +```yaml + - variable: server_url + label: + zh_Hans: 服务器URL + en_US: Server url + type: text-input + required: true + placeholder: + zh_Hans: 在此输入Xinference的服务器地址，如 https://example.com/xxx + en_US: Enter the url of your Xinference, for example https://example.com/xxx +``` + +* Each model has a unique `model_uid`, so we need to define it here. + +```yaml + - variable: model_uid + label: + zh_Hans: 模型 UID + en_US: Model uid + type: text-input + required: true + placeholder: + zh_Hans: 在此输入您的 Model UID + en_US: Enter the model uid +``` + +Now, we have completed the basic definition of the vendor. + +#### Writing Model Code + +Next, we will take the `llm` type as an example and write `xinference.llm.llm.py`. + +In `llm.py`, create a Xinference LLM class, which we will name `XinferenceAILargeLanguageModel` (arbitrary name), inheriting from the `__base.large_language_model.LargeLanguageModel` base class. Implement the following methods: + +* LLM Invocation + + Implement the core method for LLM invocation, which can support both streaming and synchronous returns. + + ```python + def _invoke(self, model: str, credentials: dict, + prompt_messages: list[PromptMessage], model_parameters: dict, + tools: Optional[list[PromptMessageTool]] = None, stop: Optional[List[str]] = None, + stream: bool = True, user: Optional[str] = None) \ + -> Union[LLMResult, Generator]: + """ + Invoke large language model + + :param model: model name + :param credentials: model credentials + :param prompt_messages: prompt messages + :param model_parameters: model parameters + :param tools: tools for tool calling + :param stop: stop words + :param stream: is stream response + :param user: unique user id + :return: full response or stream response chunk generator result + """ + ``` + + When implementing, note that you need to use two functions to return data, one for handling synchronous returns and one for streaming returns. This is because Python identifies functions containing the `yield` keyword as generator functions, and the return data type is fixed as `Generator`. Therefore, synchronous and streaming returns need to be implemented separately, as shown below (note that the example uses simplified parameters; the actual implementation should follow the parameter list above): + + ```python + def _invoke(self, stream: bool, **kwargs) \ + -> Union[LLMResult, Generator]: + if stream: + return self._handle_stream_response(**kwargs) + return self._handle_sync_response(**kwargs) + + def _handle_stream_response(self, **kwargs) -> Generator: + for chunk in response: + yield chunk + def _handle_sync_response(self, **kwargs) -> LLMResult: + return LLMResult(**response) + ``` + +* Precompute Input Tokens + + If the model does not provide a precompute tokens interface, it can directly return 0. + + ```python + def get_num_tokens(self, model: str, credentials: dict, prompt_messages: list[PromptMessage], + tools: Optional[list[PromptMessageTool]] = None) -> int: + """ + Get number of tokens for given prompt messages + + :param model: model name + :param credentials: model credentials + :param prompt_messages: prompt messages + :param tools: tools for tool calling + :return: + """ + ``` + + Sometimes, you may not want to directly return 0, so you can use `self._get_num_tokens_by_gpt2(text: str)` to get precomputed tokens. This method is located in the `AIModel` base class and uses GPT2's Tokenizer for calculation. However, it can only be used as an alternative method and is not completely accurate. + +* Model Credential Validation + + Similar to vendor credential validation, this is for validating individual model credentials. + + ```python + def validate_credentials(self, model: str, credentials: dict) -> None: + """ + Validate model credentials + + :param model: model name + :param credentials: model credentials + :return: + """ + ``` + +* Model Parameter Schema + + Unlike custom types, since a model's supported parameters are not defined in the YAML file, we need to dynamically generate the model parameter schema. + + For example, Xinference supports the `max_tokens`, `temperature`, and `top_p` parameters. + + However, some vendors support different parameters depending on the model. For instance, the vendor `OpenLLM` supports `top_k`, but not all models provided by this vendor support `top_k`. Here, we illustrate that Model A supports `top_k`, while Model B does not. Therefore, we need to dynamically generate the model parameter schema, as shown below: + + ```python + def get_customizable_model_schema(self, model: str, credentials: dict) -> AIModelEntity | None: + """ + Used to define customizable model schema + """ + rules = [ + ParameterRule( + name='temperature', type=ParameterType.FLOAT, + use_template='temperature', + label=I18nObject( + zh_Hans='温度', en_US='Temperature' + ) + ), + ParameterRule( + name='top_p', type=ParameterType.FLOAT, + use_template='top_p', + label=I18nObject( + zh_Hans='Top P', en_US='Top P' + ) + ), + ParameterRule( + name='max_tokens', type=ParameterType.INT, + use_template='max_tokens', + min=1, + default=512, + label=I18nObject( + zh_Hans='最大生成长度', en_US='Max Tokens' + ) + ) + ] + + # if model is A, add top_k to rules + if model == 'A': + rules.append( + ParameterRule( + name='top_k', type=ParameterType.INT, + use_template='top_k', + min=1, + default=50, + label=I18nObject( + zh_Hans='Top K', en_US='Top K' + ) + ) + ) + + """ + some NOT IMPORTANT code here + """ + + entity = AIModelEntity( + model=model, + label=I18nObject( + en_US=model + ), + fetch_from=FetchFrom.CUSTOMIZABLE_MODEL, + model_type=model_type, + model_properties={ + ModelPropertyKey.MODE: ModelType.LLM, + }, + parameter_rules=rules + ) + + return entity + ``` + +* Invocation Error Mapping Table + + When a model invocation error occurs, it needs to be mapped to the Runtime-specified `InvokeError` type to facilitate Dify's different subsequent processing for different errors. + + Runtime Errors: + + * `InvokeConnectionError` Invocation connection error + * `InvokeServerUnavailableError` Invocation server unavailable + * `InvokeRateLimitError` Invocation rate limit reached + * `InvokeAuthorizationError` Invocation authorization failed + * `InvokeBadRequestError` Invocation parameter error + + ```python + @property + def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]: + """ + Map model invoke error to unified error + The key is the error type thrown to the caller + The value is the error type thrown by the model, + which needs to be converted into a unified error type for the caller. + + :return: Invoke error mapping + """ + ``` + +For an explanation of interface methods, see: [Interfaces](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/interfaces.md). For specific implementations, refer to: [llm.py](https://github.com/langgenius/dify-runtime/blob/main/lib/model_providers/anthropic/llm/llm.py). \ No newline at end of file diff --git a/en/tutorials/model-configuration/hugging-face.md b/en/guides/model-configuration/hugging-face.md similarity index 100% rename from en/tutorials/model-configuration/hugging-face.md rename to en/guides/model-configuration/hugging-face.md diff --git a/en/guides/model-configuration/load-balancing.md b/en/guides/model-configuration/load-balancing.md new file mode 100644 index 0000000..b791b23 --- /dev/null +++ b/en/guides/model-configuration/load-balancing.md @@ -0,0 +1,35 @@ +# Load Balancing + +Model rate limits are restrictions imposed by model providers on the number of times a user or customer can access API services within a specified period. These limits help prevent abuse or misuse of the API, ensure fair access for all users, and control the overall load on the infrastructure. + +In enterprise-level large-scale model API calls, high concurrent requests can exceed rate limits and affect user access. Load balancing can distribute API requests across multiple endpoints to ensure all users receive the fastest response and the highest model call throughput, thereby ensuring stable business operations. + +You can enable this feature in **Model Provider -- Model List -- Configure Model Load Balancing** and add multiple credentials (API keys) for the same model. + +

Model Load Balancing

+ +{% hint style="info" %} +Model load balancing is a paid feature. You can enable this feature by [subscribing to SaaS paid services](../../getting-started/cloud.md#subscription-plans) or purchasing the enterprise edition. +{% endhint %} + +The default API Key in the configuration is the credential added when the model provider was initially configured. You need to click **Add Configuration** to add different API keys for the same model to properly use the load balancing feature. + +

Configure Load Balancing

+ +**You need to add at least one additional model credential** to save and enable load balancing. + +You can also **temporarily disable** or **delete** configured credentials. + +
+ +After configuration, all models with load balancing enabled will be displayed in the model list. + +

Enable Load Balancing

+ +{% hint style="info" %} +By default, load balancing uses the Round-robin strategy. If a rate limit is triggered, a 1-minute cooldown period will be applied. +{% endhint %} + +You can also configure load balancing from **Add Model**, and the configuration process is the same as described above. + +

Configure Load Balancing from Add Model

\ No newline at end of file diff --git a/en/tutorials/model-configuration/localai.md b/en/guides/model-configuration/localai.md similarity index 100% rename from en/tutorials/model-configuration/localai.md rename to en/guides/model-configuration/localai.md diff --git a/en/guides/model-configuration/new-provider.md b/en/guides/model-configuration/new-provider.md new file mode 100644 index 0000000..2c832ef --- /dev/null +++ b/en/guides/model-configuration/new-provider.md @@ -0,0 +1,192 @@ +# Adding a New Provider + +### Provider Configuration Methods + +Providers support three configuration models: + +**Predefined Model** + +This indicates that users only need to configure unified provider credentials to use the predefined models under the provider. + +**Customizable Model** + +Users need to add credentials configuration for each model. For example, Xinference supports both LLM and Text Embedding, but each model has a unique **model_uid**. If you want to connect both, you need to configure a **model_uid** for each model. + +**Fetch from Remote** + +Similar to the `predefined-model` configuration method, users only need to configure unified provider credentials, and the models are fetched from the provider using the credential information. + +For instance, with OpenAI, we can fine-tune multiple models based on gpt-turbo-3.5, all under the same **api_key**. When configured as `fetch-from-remote`, developers only need to configure a unified **api_key** to allow Dify Runtime to fetch all the developer's fine-tuned models and connect to Dify. + +These three configuration methods **can coexist**, meaning a provider can support `predefined-model` + `customizable-model` or `predefined-model` + `fetch-from-remote`, etc. This allows using predefined models and models fetched from remote with unified provider credentials, and additional custom models can be used if added. + +### Configuration Instructions + +**Terminology** + +* `module`: A `module` is a Python Package, or more colloquially, a folder containing an `__init__.py` file and other `.py` files. + +**Steps** + +Adding a new provider mainly involves several steps. Here is a brief outline to give you an overall understanding. Detailed steps will be introduced below. + +* Create a provider YAML file and write it according to the [Provider Schema](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/schema.md). +* Create provider code and implement a `class`. +* Create corresponding model type `modules` under the provider `module`, such as `llm` or `text_embedding`. +* Create same-named code files under the corresponding model `module`, such as `llm.py`, and implement a `class`. +* If there are predefined models, create same-named YAML files under the model `module`, such as `claude-2.1.yaml`, and write them according to the [AI Model Entity](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/schema.md). +* Write test code to ensure functionality is available. + +#### Let's Get Started + +To add a new provider, first determine the provider's English identifier, such as `anthropic`, and create a `module` named after it in `model_providers`. + +Under this `module`, we need to prepare the provider's YAML configuration first. + +**Preparing Provider YAML** + +Taking `Anthropic` as an example, preset the basic information of the provider, supported model types, configuration methods, and credential rules. + +```YAML +provider: anthropic # Provider identifier +label: # Provider display name, can be set in en_US English and zh_Hans Chinese. If zh_Hans is not set, en_US will be used by default. + en_US: Anthropic +icon_small: # Small icon of the provider, stored in the _assets directory under the corresponding provider implementation directory, same language strategy as label + en_US: icon_s_en.png +icon_large: # Large icon of the provider, stored in the _assets directory under the corresponding provider implementation directory, same language strategy as label + en_US: icon_l_en.png +supported_model_types: # Supported model types, Anthropic only supports LLM +- llm +configurate_methods: # Supported configuration methods, Anthropic only supports predefined models +- predefined-model +provider_credential_schema: # Provider credential rules, since Anthropic only supports predefined models, unified provider credential rules need to be defined + credential_form_schemas: # Credential form item list + - variable: anthropic_api_key # Credential parameter variable name + label: # Display name + en_US: API Key + type: secret-input # Form type, secret-input here represents an encrypted information input box, only displaying masked information when editing. + required: true # Whether it is required + placeholder: # PlaceHolder information + zh_Hans: 在此输入您的 API Key + en_US: Enter your API Key + - variable: anthropic_api_url + label: + en_US: API URL + type: text-input # Form type, text-input here represents a text input box + required: false + placeholder: + zh_Hans: 在此输入您的 API URL + en_US: Enter your API URL +``` + +If the connected provider offers customizable models, such as `OpenAI` which provides fine-tuned models, we need to add [`model_credential_schema`](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/schema.md). Taking `OpenAI` as an example: + +```yaml +model_credential_schema: + model: # Fine-tuned model name + label: + en_US: Model Name + zh_Hans: 模型名称 + placeholder: + en_US: Enter your model name + zh_Hans: 输入模型名称 + credential_form_schemas: + - variable: openai_api_key + label: + en_US: API Key + type: secret-input + required: true + placeholder: + zh_Hans: 在此输入您的 API Key + en_US: Enter your API Key + - variable: openai_organization + label: + zh_Hans: 组织 ID + en_US: Organization + type: text-input + required: false + placeholder: + zh_Hans: 在此输入您的组织 ID + en_US: Enter your Organization ID + - variable: openai_api_base + label: + zh_Hans: API Base + en_US: API Base + type: text-input + required: false + placeholder: + zh_Hans: 在此输入您的 API Base + en_US: Enter your API Base +``` + +You can also refer to the [YAML configuration information](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/schema.md) in the directories of other providers under the `model_providers` directory. + +**Implement Provider Code** + +We need to create a Python file with the same name under `model_providers`, such as `anthropic.py`, and implement a `class` that inherits from the `__base.provider.Provider` base class, such as `AnthropicProvider`. + +**Custom Model Providers** + +For providers like Xinference that offer custom models, this step can be skipped. Just create an empty `XinferenceProvider` class and implement an empty `validate_provider_credentials` method. This method will not actually be used and is only to avoid abstract class instantiation errors. + +```python +class XinferenceProvider(Provider): + def validate_provider_credentials(self, credentials: dict) -> None: + pass +``` + +**Predefined Model Providers** + +Providers need to inherit from the `__base.model_provider.ModelProvider` base class and implement the `validate_provider_credentials` method to validate the provider's unified credentials. You can refer to [AnthropicProvider](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/model_providers/anthropic/anthropic.py). + +```python +def validate_provider_credentials(self, credentials: dict) -> None: + """ + Validate provider credentials + You can choose any validate_credentials method of model type or implement validate method by yourself, + such as: get model list api + + if validate failed, raise exception + + :param credentials: provider credentials, credentials form defined in `provider_credential_schema`. + """ +``` + +You can also reserve the `validate_provider_credentials` implementation first and directly reuse it after implementing the model credential validation method. + +**Adding Models** + +[**Adding Predefined Models**](https://docs.dify.ai/v/zh-hans/guides/model-configuration/predefined-model)**👈🏻** + +For predefined models, we can connect them by simply defining a YAML file and implementing the calling code. + +[**Adding Custom Models**](https://docs.dify.ai/v/zh-hans/guides/model-configuration/customizable-model) **👈🏻** + +For custom models, we only need to implement the calling code to connect them, but the parameters they handle may be more complex. + +*** + +#### Testing + +To ensure the availability of the connected provider/model, each method written needs to have corresponding integration test code written in the `tests` directory. + +Taking `Anthropic` as an example. + +Before writing test code, you need to add the credential environment variables required for testing the provider in `.env.example`, such as: `ANTHROPIC_API_KEY`. + +Before executing, copy `.env.example` to `.env` and then execute. + +**Writing Test Code** + +Create a `module` with the same name as the provider under the `tests` directory: `anthropic`, and continue to create `test_provider.py` and corresponding model type test py files in this module, as shown below: + +```shell +. +├── __init__.py +├── anthropic +│   ├── __init__.py +│   ├── test_llm.py # LLM Test +│   └── test_provider.py # Provider Test +``` + +Write test code for various situations of the implemented code above, and after passing the tests, submit the code. diff --git a/en/tutorials/model-configuration/ollama.md b/en/guides/model-configuration/ollama.md similarity index 100% rename from en/tutorials/model-configuration/ollama.md rename to en/guides/model-configuration/ollama.md diff --git a/en/tutorials/model-configuration/openllm.md b/en/guides/model-configuration/openllm.md similarity index 100% rename from en/tutorials/model-configuration/openllm.md rename to en/guides/model-configuration/openllm.md diff --git a/en/guides/model-configuration/predefined-model.md b/en/guides/model-configuration/predefined-model.md new file mode 100644 index 0000000..456da3a --- /dev/null +++ b/en/guides/model-configuration/predefined-model.md @@ -0,0 +1,197 @@ +# Predefined Model Integration + +After completing the supplier integration, the next step is to integrate the models under the supplier. + +First, we need to determine the type of model to be integrated and create the corresponding model type `module` in the directory of the respective supplier. + +The currently supported model types are as follows: + +* `llm` Text Generation Model +* `text_embedding` Text Embedding Model +* `rerank` Rerank Model +* `speech2text` Speech to Text +* `tts` Text to Speech +* `moderation` Moderation + +Taking `Anthropic` as an example, `Anthropic` only supports LLM, so we create a `module` named `llm` in `model_providers.anthropic`. + +For predefined models, we first need to create a YAML file named after the model under the `llm` `module`, such as: `claude-2.1.yaml`. + +#### Preparing the Model YAML + +```yaml +model: claude-2.1 # Model identifier +# Model display name, can be set in en_US English and zh_Hans Chinese. If zh_Hans is not set, it will default to en_US. +# You can also not set a label, in which case the model identifier will be used. +label: + en_US: claude-2.1 +model_type: llm # Model type, claude-2.1 is an LLM +features: # Supported features, agent-thought supports Agent reasoning, vision supports image understanding +- agent-thought +model_properties: # Model properties + mode: chat # LLM mode, complete for text completion model, chat for dialogue model + context_size: 200000 # Maximum context size supported +parameter_rules: # Model invocation parameter rules, only LLM needs to provide +- name: temperature # Invocation parameter variable name + # There are 5 preset variable content configuration templates: temperature/top_p/max_tokens/presence_penalty/frequency_penalty + # You can set the template variable name directly in use_template, and it will use the default configuration in entities.defaults.PARAMETER_RULE_TEMPLATE + # If additional configuration parameters are set, they will override the default configuration + use_template: temperature +- name: top_p + use_template: top_p +- name: top_k + label: # Invocation parameter display name + zh_Hans: 取样数量 + en_US: Top k + type: int # Parameter type, supports float/int/string/boolean + help: # Help information, describes the parameter's function + zh_Hans: 仅从每个后续标记的前 K 个选项中采样。 + en_US: Only sample from the top K options for each subsequent token. + required: false # Whether it is required, can be omitted +- name: max_tokens_to_sample + use_template: max_tokens + default: 4096 # Default parameter value + min: 1 # Minimum parameter value, only applicable to float/int + max: 4096 # Maximum parameter value, only applicable to float/int +pricing: # Pricing information + input: '8.00' # Input unit price, i.e., Prompt unit price + output: '24.00' # Output unit price, i.e., return content unit price + unit: '0.000001' # Price unit, the above price is per 100K + currency: USD # Price currency +``` + +It is recommended to prepare all model configurations before starting the implementation of the model code. + +Similarly, you can refer to the YAML configuration information in the directories of other suppliers under the `model_providers` directory. The complete YAML rules can be found in: Schema[^1]. + +#### Implementing Model Invocation Code + +Next, create a Python file with the same name `llm.py` under the `llm` `module` to write the implementation code. + +Create an Anthropic LLM class in `llm.py`, which we will name `AnthropicLargeLanguageModel` (name can be arbitrary), inheriting from the `__base.large_language_model.LargeLanguageModel` base class, and implement the following methods: + +* LLM Invocation + + Implement the core method for LLM invocation, supporting both streaming and synchronous responses. + + ```python + def _invoke(self, model: str, credentials: dict, + prompt_messages: list[PromptMessage], model_parameters: dict, + tools: Optional[list[PromptMessageTool]] = None, stop: Optional[List[str]] = None, + stream: bool = True, user: Optional[str] = None) \ + -> Union[LLMResult, Generator]: + """ + Invoke large language model + + :param model: model name + :param credentials: model credentials + :param prompt_messages: prompt messages + :param model_parameters: model parameters + :param tools: tools for tool calling + :param stop: stop words + :param stream: is stream response + :param user: unique user id + :return: full response or stream response chunk generator result + """ + ``` + + When implementing, note to use two functions to return data, one for handling synchronous responses and one for streaming responses. Since Python recognizes functions containing the `yield` keyword as generator functions, returning a fixed data type of `Generator`, synchronous and streaming responses need to be implemented separately, like this (note the example below uses simplified parameters, actual implementation should follow the parameter list above): + + ```python + def _invoke(self, stream: bool, **kwargs) \ + -> Union[LLMResult, Generator]: + if stream: + return self._handle_stream_response(**kwargs) + return self._handle_sync_response(**kwargs) + + def _handle_stream_response(self, **kwargs) -> Generator: + for chunk in response: + yield chunk + def _handle_sync_response(self, **kwargs) -> LLMResult: + return LLMResult(**response) + ``` +* Precompute Input Tokens + + If the model does not provide a precompute tokens interface, return 0 directly. + + ```python + def get_num_tokens(self, model: str, credentials: dict, prompt_messages: list[PromptMessage], + tools: Optional[list[PromptMessageTool]] = None) -> int: + """ + Get number of tokens for given prompt messages + + :param model: model name + :param credentials: model credentials + :param prompt_messages: prompt messages + :param tools: tools for tool calling + :return: + """ + ``` +* Model Credentials Validation + + Similar to supplier credentials validation, this validates the credentials for a single model. + + ```python + def validate_credentials(self, model: str, credentials: dict) -> None: + """ + Validate model credentials + + :param model: model name + :param credentials: model credentials + :return: + """ + ``` +* Invocation Error Mapping Table + + When a model invocation error occurs, it needs to be mapped to the `InvokeError` type specified by Runtime, facilitating Dify to handle different errors differently. + + Runtime Errors: + + * `InvokeConnectionError` Invocation connection error + * `InvokeServerUnavailableError` Invocation service unavailable + * `InvokeRateLimitError` Invocation rate limit reached + * `InvokeAuthorizationError` Invocation authorization failed + * `InvokeBadRequestError` Invocation parameter error + + ```python + @property + def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]: + """ + Map model invoke error to unified error + The key is the error type thrown to the caller + The value is the error type thrown by the model, + which needs to be converted into a unified error type for the caller. + + :return: Invoke error mapping + """ + ``` + +For interface method descriptions, see: [Interfaces](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/docs/zh_Hans/interfaces.md), and for specific implementation, refer to: [llm.py](https://github.com/langgenius/dify-runtime/blob/main/lib/model_providers/anthropic/llm/llm.py). + +[^1]: #### Provider + + * `provider` (string) Supplier identifier, e.g., `openai` + * `label` (object) Supplier display name, i18n, can be set in `en_US` English and `zh_Hans` Chinese + * `zh_Hans` (string) [optional] Chinese label name, if `zh_Hans` is not set, it will default to `en_US`. + * `en_US` (string) English label name + * `description` (object) [optional] Supplier description, i18n + * `zh_Hans` (string) [optional] Chinese description + * `en_US` (string) English description + * `icon_small` (string) [optional] Supplier small icon, stored in the `_assets` directory under the respective supplier implementation directory, follows the same language strategy as `label` + * `zh_Hans` (string) [optional] Chinese icon + * `en_US` (string) English icon + * `icon_large` (string) [optional] Supplier large icon, stored in the `_assets` directory under the respective supplier implementation directory, follows the same language strategy as `label` + * `zh_Hans` (string) [optional] Chinese icon + * `en_US` (string) English icon + * `background` (string) [optional] Background color value, e.g., #FFFFFF, if empty, the default color value will be displayed on the front end. + * `help` (object) [optional] Help information + * `title` (object) Help title, i18n + * `zh_Hans` (string) [optional] Chinese title + * `en_US` (string) English title + * `url` (object) Help link, i18n + * `zh_Hans` (string) [optional] Chinese link + * `en_US` (string) English link + * `supported_model_types` (array[ModelType]) Supported model types + * `configurate_methods` (array[ConfigurateMethod]) Configuration methods + * `provider_credential_schema` (ProviderCredentialSchema) Supplier credential schema + * `model_credential_schema` (ModelCredentialSchema) Model credential schema \ No newline at end of file diff --git a/en/tutorials/model-configuration/replicate.md b/en/guides/model-configuration/replicate.md similarity index 100% rename from en/tutorials/model-configuration/replicate.md rename to en/guides/model-configuration/replicate.md diff --git a/en/tutorials/model-configuration/xinference.md b/en/guides/model-configuration/xinference.md similarity index 100% rename from en/tutorials/model-configuration/xinference.md rename to en/guides/model-configuration/xinference.md diff --git a/en/guides/monitoring/README.md b/en/guides/monitoring/README.md new file mode 100644 index 0000000..fbc79e9 --- /dev/null +++ b/en/guides/monitoring/README.md @@ -0,0 +1,2 @@ +# Monitoring + diff --git a/en/guides/monitoring/analysis.md b/en/guides/monitoring/analysis.md new file mode 100644 index 0000000..7689744 --- /dev/null +++ b/en/guides/monitoring/analysis.md @@ -0,0 +1,31 @@ +# Data Analysis + +The **Overview -- Data Analysis** section displays metrics such as usage, active users, and LLM (Language Learning Model) invocation costs. This allows you to continuously improve the effectiveness, engagement, and cost-efficiency of your application operations. We will gradually provide more useful visualization capabilities, so please let us know what you need. + +

Overview—Data Analysis

+ +*** + +**Total Messages** + +Reflects the total number of interactions AI has each day, with each user question answered counted as one message. Prompt orchestration and debugging sessions are not included. + +**Active Users** + +The number of unique users who have had effective interactions with the AI, defined as having more than one question-and-answer exchange. Prompt orchestration and debugging sessions are not included. + +**Average Session Interactions** + +Reflects the number of continuous interactions per session user. For example, if a user has a 10-round Q&A with the AI, it is counted as 10. This metric reflects user engagement. It is available only for conversational applications. + +**Token Output Speed** + +The number of tokens output per second, indirectly reflecting the model's generation rate and the application's usage frequency. + +**User Satisfaction Rate** + +The number of likes per 1,000 messages, reflecting the proportion of users who are very satisfied with the answers. + +**Token Usage** + +Reflects the daily token expenditure for language model requests by the application, useful for cost control. \ No newline at end of file diff --git a/en/guides/monitoring/integrate-external-ops-tools/README.md b/en/guides/monitoring/integrate-external-ops-tools/README.md new file mode 100644 index 0000000..f9bae28 --- /dev/null +++ b/en/guides/monitoring/integrate-external-ops-tools/README.md @@ -0,0 +1,3 @@ +# Integrating External Ops Tools + +🚧 Under Maintenance \ No newline at end of file diff --git a/en/guides/monitoring/integrate-external-ops-tools/integrate-langfuse.md b/en/guides/monitoring/integrate-external-ops-tools/integrate-langfuse.md new file mode 100644 index 0000000..9d58841 --- /dev/null +++ b/en/guides/monitoring/integrate-external-ops-tools/integrate-langfuse.md @@ -0,0 +1,3 @@ +# Integrating LangFuse + +Under maintenance... diff --git a/en/guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md b/en/guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md new file mode 100644 index 0000000..233082d --- /dev/null +++ b/en/guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md @@ -0,0 +1,3 @@ +# Integrating LangSmith + +Under maintenance... diff --git a/en/guides/tools/README.md b/en/guides/tools/README.md new file mode 100644 index 0000000..cf344d7 --- /dev/null +++ b/en/guides/tools/README.md @@ -0,0 +1,67 @@ +# Tools + +### Tool Definition + +Tools can extend the capabilities of LLMs (Language Learning Models), such as performing web searches, scientific calculations, or generating images, thereby enhancing the LLM's ability to connect with the external world. Dify provides two types of tools: **First-party Tools** and **Custom Tools**. + +You can directly use the first-party built-in tools provided by the Dify ecosystem, or easily import custom API tools (currently supporting OpenAPI / Swagger and OpenAI Plugin specifications). + +#### Functions of Tools: + +1. Tools allow users to create more powerful AI applications on Dify. For example, you can arrange suitable tools for an intelligent assistant application (Agent) that can complete complex tasks through task reasoning, step-by-step breakdown, and tool invocation. +2. They facilitate connecting your application with other systems or services and interacting with the external environment, such as code execution or access to proprietary information sources. + +### How to Configure First-party Tools + +

First-party Tools List

+ +Dify currently supports: + +
ToolDescription
Google SearchTool for performing Google SERP searches and extracting snippets and web pages. The input should be a search query.
WikipediaTool for performing Wikipedia searches and extracting snippets and web pages.
DALL-E DrawingTool for generating high-quality images through natural language input.
Web ScrapingTool for scraping web data.
WolframAlphaA powerful computational knowledge engine that provides standardized answers based on questions and has strong mathematical computation capabilities.
Chart GenerationTool for generating visual charts, allowing you to create bar charts, line charts, pie charts, and other types of charts.
Current TimeTool for querying the current time.
Yahoo FinanceTool for obtaining and organizing the latest financial information, such as news and stock quotes.
Stable DiffusionA tool for generating images that can be deployed locally using stable-diffusion-webui.
VectorizerTool for quickly and easily converting PNG and JPG images to SVG vector graphics.
YouTubeTool for retrieving statistics of YouTube channel videos.
+ +{% hint style="info" %} +We welcome you to contribute your developed tools to Dify. For detailed methods on how to contribute, please refer to the [Dify Development Contribution Documentation](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md). Your support is invaluable to us. +{% endhint %} + +#### First-party Tool Authorization + +If you need to use the first-party built-in tools provided by the Dify ecosystem, you need to configure the corresponding credentials before using them. + +

Configure First-party Tool Credentials

+ +Once the credentials are successfully verified, the tool will display an "Authorized" status. After configuring the credentials, all members in the workspace can use this tool when arranging applications. + +

First-party Tool Authorized

+ +### How to Create Custom Tools + +You can import custom API tools in the "Tools - Custom Tools" section, currently supporting OpenAPI / Swagger and ChatGPT Plugin specifications. You can directly paste the OpenAPI schema content or import it from a URL. For the OpenAPI / Swagger specification, you can refer to the [official documentation](https://swagger.io/specification/). + +Currently, tools support two authentication methods: No Authentication and API Key. + +

Create Custom Tools

+ +After importing the schema content, the system will automatically parse the parameters in the file, and you can preview the specific parameters, methods, and paths of the tool. You can also test the tool parameters here. + +

Custom Tool Parameter Testing

+ +Once the custom tool is created, all members in the workspace can use this tool when arranging applications in the "Studio." + +

Custom Tool Added

+ +#### Cloudflare Workers + +You can also use [dify-tools-worker](https://github.com/crazywoola/dify-tools-worker) to quickly deploy custom tools. This tool provides: + +* Routes that can be imported into Dify `https://difytoolsworker.yourname.workers.dev/doc`, offering an OpenAPI-compatible interface documentation. +* API implementation code that can be directly deployed to Cloudflare Workers. + +### How to Use Tools in Applications + +Currently, you can use the configured tools when creating **intelligent assistant applications** in the "Studio." + +

Add Tools When Creating Intelligent Assistant Applications

+ +For example, after adding tools in a financial analysis application, the intelligent assistant will autonomously invoke tools when needed to query financial report data, analyze the data, and complete the conversation with the user. + +

Intelligent Assistant Using Tools to Answer Questions During Conversation

\ No newline at end of file diff --git a/en/tutorials/advanced-tool-integration.md b/en/guides/tools/advanced-tool-integration.md similarity index 100% rename from en/tutorials/advanced-tool-integration.md rename to en/guides/tools/advanced-tool-integration.md diff --git a/en/tutorials/quick-tool-integration.md b/en/guides/tools/quick-tool-integration.md similarity index 100% rename from en/tutorials/quick-tool-integration.md rename to en/guides/tools/quick-tool-integration.md diff --git a/en/tutorials/tool-configuration/README.md b/en/guides/tools/tool-configuration/README.md similarity index 100% rename from en/tutorials/tool-configuration/README.md rename to en/guides/tools/tool-configuration/README.md diff --git a/en/tutorials/tool-configuration/searxng.md b/en/guides/tools/tool-configuration/searxng.md similarity index 100% rename from en/tutorials/tool-configuration/searxng.md rename to en/guides/tools/tool-configuration/searxng.md diff --git a/en/tutorials/tool-configuration/stable-diffusion.md b/en/guides/tools/tool-configuration/stable-diffusion.md similarity index 100% rename from en/tutorials/tool-configuration/stable-diffusion.md rename to en/guides/tools/tool-configuration/stable-diffusion.md diff --git a/en/guides/workflow/README.md b/en/guides/workflow/README.md new file mode 100644 index 0000000..61ab675 --- /dev/null +++ b/en/guides/workflow/README.md @@ -0,0 +1,45 @@ +# Workflow + +### Basic Introduction + +Workflows reduce system complexity by breaking down complex tasks into smaller steps (nodes), reducing reliance on prompt engineering and model inference capabilities, and enhancing the performance of LLM applications for complex tasks. This also improves the system's interpretability, stability, and fault tolerance. + +Dify workflows are divided into two types: + +* **Chatflow**: Designed for conversational scenarios, including customer service, semantic search, and other conversational applications that require multi-step logic in response construction. +* **Workflow**: Geared towards automation and batch processing scenarios, suitable for high-quality translation, data analysis, content generation, email automation, and more. + +
+ +To address the complexity of user intent recognition in natural language input, Chatflow provides question understanding nodes. Compared to Workflow, it adds support for Chatbot features such as conversation history (Memory), annotated replies, and Answer nodes. + +To handle complex business logic in automation and batch processing scenarios, Workflow offers a variety of logic nodes, such as code nodes, IF/ELSE nodes, template transformation, iteration nodes, and more. Additionally, it provides capabilities for timed and event-triggered actions, facilitating the construction of automated processes. + +### Common Use Cases + +* Customer Service + +By integrating LLM into your customer service system, you can automate responses to common questions, reducing the workload of your support team. LLM can understand the context and intent of customer queries and generate helpful and accurate answers in real-time. + +* Content Generation + +Whether you need to create blog posts, product descriptions, or marketing materials, LLM can assist by generating high-quality content. Simply provide an outline or topic, and LLM will use its extensive knowledge base to produce engaging, informative, and well-structured content. + +* Task Automation + +LLM can be integrated with various task management systems like Trello, Slack, and Lark to automate project and task management. Using natural language processing, LLM can understand and interpret user input, create tasks, update statuses, and assign priorities without manual intervention. + +* Data Analysis and Reporting + +LLM can analyze large datasets and generate reports or summaries. By providing relevant information to LLM, it can identify trends, patterns, and insights, transforming raw data into actionable intelligence. This is particularly valuable for businesses looking to make data-driven decisions. + +* Email Automation + +LLM can be used to draft emails, social media updates, and other forms of communication. By providing a brief outline or key points, LLM can generate well-structured, coherent, and contextually relevant messages. This saves significant time and ensures your responses are clear and professional. + +### How to Get Started + +* Start by building a workflow from scratch or use system templates to help you get started. +* Get familiar with basic operations, including creating nodes on the canvas, connecting and configuring nodes, debugging workflows, and viewing run history. +* Save and publish a workflow. +* Run the published application or call the workflow through an API. \ No newline at end of file diff --git a/en/guides/workflow/debug-and-preview/README.md b/en/guides/workflow/debug-and-preview/README.md new file mode 100644 index 0000000..120b4e3 --- /dev/null +++ b/en/guides/workflow/debug-and-preview/README.md @@ -0,0 +1 @@ +# Debug and Preview \ No newline at end of file diff --git a/en/features/workflow/preview-and-run/checklist.md b/en/guides/workflow/debug-and-preview/checklist.md similarity index 100% rename from en/features/workflow/preview-and-run/checklist.md rename to en/guides/workflow/debug-and-preview/checklist.md diff --git a/en/features/workflow/preview-and-run/history.md b/en/guides/workflow/debug-and-preview/history.md similarity index 100% rename from en/features/workflow/preview-and-run/history.md rename to en/guides/workflow/debug-and-preview/history.md diff --git a/en/features/workflow/preview-and-run/log.md b/en/guides/workflow/debug-and-preview/log.md similarity index 100% rename from en/features/workflow/preview-and-run/log.md rename to en/guides/workflow/debug-and-preview/log.md diff --git a/en/features/workflow/preview-and-run/step-test.md b/en/guides/workflow/debug-and-preview/step-run.md similarity index 100% rename from en/features/workflow/preview-and-run/step-test.md rename to en/guides/workflow/debug-and-preview/step-run.md diff --git a/en/features/workflow/preview-and-run/preview-and-run.md b/en/guides/workflow/debug-and-preview/yu-lan-yu-yun-hang.md similarity index 100% rename from en/features/workflow/preview-and-run/preview-and-run.md rename to en/guides/workflow/debug-and-preview/yu-lan-yu-yun-hang.md diff --git a/en/features/workflow/export-import.md b/en/guides/workflow/export-import.md similarity index 100% rename from en/features/workflow/export-import.md rename to en/guides/workflow/export-import.md diff --git a/en/features/workflow/introduce.md b/en/guides/workflow/introduce.md similarity index 100% rename from en/features/workflow/introduce.md rename to en/guides/workflow/introduce.md diff --git a/en/guides/workflow/key-concept.md b/en/guides/workflow/key-concept.md new file mode 100644 index 0000000..b8d3121 --- /dev/null +++ b/en/guides/workflow/key-concept.md @@ -0,0 +1,41 @@ +# Key Concepts + +### 1. Nodes + +**Nodes are the key components of a workflow**. By connecting nodes with different functionalities, you can execute a series of operations within the workflow. + +For core workflow nodes, please refer to [Node Description](node/). + +*** + +### 2. Variables + +**Variables are used to link the input and output of nodes within a workflow**, enabling complex processing logic throughout the process. + +* A workflow needs to define execution start variables, such as defining an input variable `sys.query` for a chatbot. +* Nodes generally need to define input variables, such as defining the input variable for a question classifier as `sys.query`. +* When referencing variables, only upstream node variables in the process can be referenced. +* To avoid variable name conflicts, node names must be unique. +* The output variables of nodes are generally system-fixed variables and cannot be edited. + +*** + +### 3. Chatflow and Workflow + +**Application Scenarios** + +* **Chatflow**: Designed for conversational scenarios, including customer service, semantic search, and other conversational applications that require multi-step logic in response construction. +* **Workflow**: Geared towards automation and batch processing scenarios, suitable for high-quality translation, data analysis, content generation, email automation, and more. + +**Usage Entry Points** + +

Chatflow Entry

+ +

Workflow Entry

+ +**Differences in Available Nodes** + +1. The End node is an ending node for Workflow and can only be selected at the end of the process. +2. The Answer node is specific to Chatflow, used for streaming text output, and can output at intermediate steps in the process. +3. Chatflow has built-in chat memory (Memory) for storing and passing multi-turn conversation history, which can be enabled in nodes like LLM and question classifiers. Workflow does not have Memory-related configurations and cannot enable them. +4. Built-in variables for Chatflow's start node include: `sys.query`, `sys.files`, `sys.conversation_id`, `sys.user_id`. Built-in variables for Workflow's start node include: `sys.files`, `sys_id`. \ No newline at end of file diff --git a/en/guides/workflow/node/README.md b/en/guides/workflow/node/README.md new file mode 100644 index 0000000..bebe997 --- /dev/null +++ b/en/guides/workflow/node/README.md @@ -0,0 +1,83 @@ +# Node Description + +**Nodes are the key components of a workflow**, enabling the execution of a series of operations by connecting nodes with different functionalities. + +### Core Nodes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StartDefines the initial parameters for starting a workflow process.
EndDefines the final output content for ending a workflow process.
AnswerDefines the response content in a Chatflow process.
Large Language Model (LLM)Calls a large language model to answer questions or process natural language.
Knowledge RetrievalRetrieves text content related to user questions from a knowledge base, which can serve as context for downstream LLM nodes.
Question ClassifierBy defining classification descriptions, the LLM can select the matching classification based on user input.
IF/ELSEAllows you to split the workflow into two branches based on if/else conditions.
Code ExecutionRuns Python/NodeJS code to execute custom logic such as data transformation within the workflow.
Template TransformationEnables flexible data transformation and text processing using Jinja2, a Python templating language.
Variable AggregatorAggregates variables from multiple branches into one variable for unified configuration of downstream nodes.
Parameter ExtractorUses LLM to infer and extract structured parameters from natural language for subsequent tool calls or HTTP requests.
IterationExecutes multiple steps on list objects until all results are output.
HTTP RequestAllows sending server requests via the HTTP protocol, suitable for retrieving external results, webhooks, generating images, and other scenarios.
ToolsEnables calling built-in Dify tools, custom tools, sub-workflows, and more within the workflow.
\ No newline at end of file diff --git a/en/features/workflow/node/answer.md b/en/guides/workflow/node/answer.md similarity index 100% rename from en/features/workflow/node/answer.md rename to en/guides/workflow/node/answer.md diff --git a/en/guides/workflow/node/code.md b/en/guides/workflow/node/code.md new file mode 100644 index 0000000..8222e94 --- /dev/null +++ b/en/guides/workflow/node/code.md @@ -0,0 +1,66 @@ +# Code Execution + +## Table of Contents +- [Introduction](#introduction) +- [Usage Scenarios](#usage-scenarios) +- [Local Deployment](#local-deployment) +- [Security Policies](#security-policies) + +## Introduction + +The code node supports running Python/NodeJS code to perform data transformations within a workflow. It can simplify your workflow and is suitable for scenarios such as arithmetic operations, JSON transformations, text processing, and more. + +This node significantly enhances the flexibility for developers, allowing them to embed custom Python or JavaScript scripts within the workflow and manipulate variables in ways that preset nodes cannot achieve. Through configuration options, you can specify the required input and output variables and write the corresponding execution code: + +
+ +## Configuration +If you need to use variables from other nodes in the code node, you must define the variable names in the `input variables` and reference these variables. You can refer to [Variable References](../key_concept.md#variables). + +## Usage Scenarios +Using the code node, you can perform the following common operations: + +### Structured Data Processing +In workflows, you often have to deal with unstructured data processing, such as parsing, extracting, and transforming JSON strings. A typical example is data processing from an HTTP node. In common API return structures, data may be nested within multiple layers of JSON objects, and you need to extract certain fields. The code node can help you perform these operations. Here is a simple example that extracts the `data.name` field from a JSON string returned by an HTTP node: + +```python +def main(http_response: str) -> str: + import json + data = json.loads(http_response) + return { + # Note to declare 'result' in the output variables + 'result': data['data']['name'] + } +``` + +### Mathematical Calculations +When you need to perform complex mathematical calculations in a workflow, you can also use the code node. For example, calculating a complex mathematical formula or performing some statistical analysis on data. Here is a simple example that calculates the variance of an array: + +```python +def main(x: list) -> float: + return { + # Note to declare 'result' in the output variables + 'result': sum([(i - sum(x) / len(x)) ** 2 for i in x]) / len(x) + } +``` + +### Data Concatenation +Sometimes, you may need to concatenate multiple data sources, such as multiple knowledge retrievals, data searches, API calls, etc. The code node can help you integrate these data sources together. Here is a simple example that merges data from two knowledge bases: + +```python +def main(knowledge1: list, knowledge2: list) -> list: + return { + # Note to declare 'result' in the output variables + 'result': knowledge1 + knowledge2 + } +``` + +## Local Deployment +If you are a local deployment user, you need to start a sandbox service to ensure that malicious code is not executed. This service requires the use of Docker. You can find specific information about the sandbox service [here](https://github.com/langgenius/dify/tree/main/docker/docker-compose.middleware.yaml). You can also start the service directly via `docker-compose`: + +```bash +docker-compose -f docker-compose.middleware.yaml up -d +``` + +## Limitations +Both Python and JavaScript execution environments are strictly isolated (sandboxed) to ensure security. This means that developers cannot use functions that consume large amounts of system resources or may pose security risks, such as direct file system access, making network requests, or executing operating system-level commands. These limitations ensure the safe execution of the code while avoiding excessive consumption of system resources. \ No newline at end of file diff --git a/en/features/workflow/node/end.md b/en/guides/workflow/node/end.md similarity index 100% rename from en/features/workflow/node/end.md rename to en/guides/workflow/node/end.md diff --git a/en/guides/workflow/node/http-request.md b/en/guides/workflow/node/http-request.md new file mode 100644 index 0000000..120dd66 --- /dev/null +++ b/en/guides/workflow/node/http-request.md @@ -0,0 +1,28 @@ +# HTTP Request + +### 1 Definition + +Allows sending server requests via the HTTP protocol, suitable for scenarios such as retrieving external data, webhooks, generating images, and downloading files. It enables you to send customized HTTP requests to specified web addresses, achieving interconnectivity with various external services. + +This node supports common HTTP request methods: + +* **GET**: Used to request the server to send a specific resource. +* **POST**: Used to submit data to the server, typically for submitting forms or uploading files. +* **HEAD**: Similar to GET requests, but the server only returns the response headers without the resource body. +* **PATCH**: Used to apply partial modifications to a resource. +* **PUT**: Used to upload resources to the server, typically for updating an existing resource or creating a new one. +* **DELETE**: Used to request the server to delete a specified resource. + +You can configure various aspects of the HTTP request, including URL, request headers, query parameters, request body content, and authentication information. + +

HTTP Request Configuration

+ +*** + +### 2 Scenarios + +One practical feature of this node is the ability to dynamically insert variables into different parts of the request based on the scenario. For example, when handling customer feedback requests, you can embed variables such as username or customer ID, feedback content, etc., into the request to customize automated reply messages or fetch specific customer information and send related resources to a designated server. + +

Customer Feedback Classification

+ +The return values of an HTTP request include the response body, status code, response headers, and files. Notably, if the response contains a file (currently only image types are supported), this node can automatically save the file for use in subsequent steps of the workflow. This design not only improves processing efficiency but also makes handling responses with files straightforward and direct. \ No newline at end of file diff --git a/en/guides/workflow/node/ifelse.md b/en/guides/workflow/node/ifelse.md new file mode 100644 index 0000000..fd46acb --- /dev/null +++ b/en/guides/workflow/node/ifelse.md @@ -0,0 +1,40 @@ +# IF/ELSE + +### Definition + +Allows you to split the workflow into two branches based on if/else conditions. + +A conditional branching node has three parts: + +* IF Condition: Select a variable, set the condition, and specify the value that satisfies the condition. +* IF condition evaluates to `True`, execute the IF path. +* IF condition evaluates to `False`, execute the ELSE path. + +**Condition Types** + +* Contains +* Not contains +* Starts with +* Ends with +* Is +* Is not +* Is empty +* Is not empty + +*** + +### Scenario + +
+ +Taking the above **Text Summary Workflow** as an example: + +* IF Condition: Select the `summarystyle` variable from the start node, with the condition **Contains** `technical`. +* IF condition evaluates to `True`, execute the IF path, querying technical-related knowledge through the Knowledge Retrieval node and then responding via the LLM node (upper part of the diagram). +* IF condition evaluates to `False`, i.e., the `summarystyle` variable input **does not contain** `technical`, execute the ELSE path, responding via the LLM2 node (lower part of the diagram). + +**Multiple Condition Judgments** + +For complex condition judgments, you can set multiple condition judgments and configure **AND** or **OR** between conditions to take the **intersection** or **union** of the conditions, respectively. + +

Multiple Condition Judgments

\ No newline at end of file diff --git a/en/guides/workflow/node/iteration.md b/en/guides/workflow/node/iteration.md new file mode 100644 index 0000000..6459617 --- /dev/null +++ b/en/guides/workflow/node/iteration.md @@ -0,0 +1,157 @@ +# Iteration + +### Definition + +Execute multiple steps on an array until all results are output. + +The iteration step performs the same steps on each item in a list. To use iteration, ensure that the input value is formatted as a list object. The iteration node allows AI workflows to handle more complex processing logic. It is a user-friendly version of the loop node, making some compromises in customization to allow non-technical users to quickly get started. + +*** + +### Scenarios + +#### **Example 1: Long Article Iteration Generator** + +

Long Story Generator

+ +1. Enter the story title and outline in the **Start Node**. +2. Use a **Code Node** to extract the complete content from user input. +3. Use a **Parameter Extraction Node** to convert the complete content into an array format. +4. Use an **Iteration Node** to wrap an **LLM Node** and generate content for each chapter through multiple iterations. +5. Add a **Direct Reply Node** inside the iteration node to achieve streaming output after each iteration. + +**Detailed Configuration Steps** + +1. Configure the story title (title) and outline (outline) in the **Start Node**. + +

Start Node Configuration

+ +2. Use a **Jinja-2 Template Node** to convert the story title and outline into complete text. + +

Template Node

+ +3. Use a **Parameter Extraction Node** to convert the story text into an array (Array) structure. The parameter to extract is `sections`, and the parameter type is `Array[Object]`. + +

Parameter Extraction

+ +{% hint style="info" %} +The effectiveness of parameter extraction is influenced by the model's inference capability and the instructions given. Using a model with stronger inference capabilities and adding examples in the **instructions** can improve the parameter extraction results. +{% endhint %} + +4. Use the array-formatted story outline as the input for the iteration node and process it within the iteration node using an **LLM Node**. + +

Configure Iteration Node

+ +Configure the input variables `GenerateOverallOutline/output` and `Iteration/item` in the LLM Node. + +

Configure LLM Node

+ +{% hint style="info" %} +Built-in variables for iteration: `items[object]` and `index[number]`. + +`items[object]` represents the input item for each iteration; + +`index[number]` represents the current iteration round; +{% endhint %} + +5. Configure a **Direct Reply Node** inside the iteration node to achieve streaming output after each iteration. + +

Configure Answer Node

+ +6. Complete debugging and preview. + +

Generate by Iterating Through Story Chapters

+ +#### **Example 2: Long Article Iteration Generator (Another Arrangement)** + +
+ +* Enter the story title and outline in the **Start Node**. +* Use an **LLM Node** to generate subheadings and corresponding content for the article. +* Use a **Code Node** to convert the complete content into an array format. +* Use an **Iteration Node** to wrap an **LLM Node** and generate content for each chapter through multiple iterations. +* Use a **Template Conversion** Node to convert the string array output from the iteration node back to a string. +* Finally, add a **Direct Reply Node** to directly output the converted string. + +### What is Array Content + +A list is a specific data type where elements are separated by commas and enclosed in `[` and `]`. For example: + +**Numeric:** + +``` +[0,1,2,3,4,5] +``` + +**String:** + +``` +["Monday", "Tuesday", "Wednesday", "Thursday"] +``` + +**JSON Object:** + +``` +[ + { + "name": "Alice", + "age": 30, + "email": "alice@example.com" + }, + { + "name": "Bob", + "age": 25, + "email": "bob@example.com" + }, + { + "name": "Charlie", + "age": 35, + "email": "charlie@example.com" + } +] +``` + +*** + +### Nodes Supporting Array Return + +* Code Node +* Parameter Extraction +* Knowledge Base Retrieval +* Iteration +* Tools +* HTTP Request + +### How to Obtain Array-Formatted Content + +**Return Using the CODE Node** + +

CODE Node Outputting Array

+ +**Return Using the Parameter Extraction Node** + +

Parameter Extraction Node Outputting Array

+ +### How to Convert an Array to Text + +The output variable of the iteration node is in array format and cannot be directly output. You can use a simple step to convert the array back to text. + +**Convert Using a Code Node** + +

Code Node Conversion

+ +```python +def main(articleSections: list): + data = articleSections + return { + "result": "\n".join(data) + } +``` + +**Convert Using a Template Node** + +

Template Node Conversion

+ +```django +{{ articleSections | join("\n") }} +``` \ No newline at end of file diff --git a/en/features/workflow/node/knowledge-retrieval.md b/en/guides/workflow/node/knowledge-retrieval.md similarity index 100% rename from en/features/workflow/node/knowledge-retrieval.md rename to en/guides/workflow/node/knowledge-retrieval.md diff --git a/en/features/workflow/node/llm.md b/en/guides/workflow/node/llm.md similarity index 100% rename from en/features/workflow/node/llm.md rename to en/guides/workflow/node/llm.md diff --git a/en/guides/workflow/node/parameter-extractor.md b/en/guides/workflow/node/parameter-extractor.md new file mode 100644 index 0000000..14d8a0a --- /dev/null +++ b/en/guides/workflow/node/parameter-extractor.md @@ -0,0 +1,60 @@ +# Parameter Extraction + +### 1 Definition + +Utilize LLM to infer and extract structured parameters from natural language for subsequent tool invocation or HTTP requests. + +Dify workflows provide a rich selection of [tools](../../gong-ju.md), most of which require structured parameters as input. The parameter extractor can convert user natural language into parameters recognizable by these tools, facilitating tool invocation. + +Some nodes within the workflow require specific data formats as inputs, such as the [iteration](iteration.md#ding-yi) node, which requires an array format. The parameter extractor can conveniently achieve [structured parameter conversion](iteration.md#shi-li-1-chang-wen-zhang-die-dai-sheng-cheng-qi). + +*** + +### 2 Scenarios + +1. **Extracting key parameters required by tools from natural language**, such as building a simple conversational Arxiv paper retrieval application. + +In this example: The Arxiv paper retrieval tool requires **paper author** or **paper ID** as input parameters. The parameter extractor extracts the paper ID **2405.10739** from the query "What is the content of this paper: 2405.10739" and uses it as the tool parameter for precise querying. + +

Arxiv Paper Retrieval Tool

+ +2. **Converting text to structured data**, such as in the long story iteration generation application, where it serves as a pre-step for the [iteration node](iteration.md), converting chapter content in text format to an array format, facilitating multi-round generation processing by the iteration node. + +
+ +3. **Extracting structured data and using the [HTTP Request](http\_request.md)**, which can request any accessible URL, suitable for obtaining external retrieval results, webhooks, generating images, and other scenarios. + +*** + +### 3 How to Configure + +
+ +**Configuration Steps** + +1. Select the input variable, usually the variable input for parameter extraction. +2. Choose the model, as the parameter extractor relies on the LLM's inference and structured generation capabilities. +3. Define the parameters to extract, which can be manually added or **quickly imported from existing tools**. +4. Write instructions, where providing examples can help the LLM improve the effectiveness and stability of extracting complex parameters. + +**Advanced Settings** + +**Inference Mode** + +Some models support two inference modes, achieving parameter extraction through function/tool calls or pure prompt methods, with differences in instruction compliance. For instance, some models may perform better in prompt inference if function calling is less effective. + +* Function Call/Tool Call +* Prompt + +**Memory** + +When memory is enabled, each input to the question classifier will include the chat history in the conversation to help the LLM understand the context and improve question comprehension during interactive dialogues. + +**Output Variables** + +* Extracted defined variables +* Node built-in variables + +`__is_success Number` Extraction success status, with a value of 1 for success and 0 for failure. + +`__reason String` Extraction error reason \ No newline at end of file diff --git a/en/features/workflow/node/question-classifier.md b/en/guides/workflow/node/question-classifier.md similarity index 100% rename from en/features/workflow/node/question-classifier.md rename to en/guides/workflow/node/question-classifier.md diff --git a/en/features/workflow/node/start.md b/en/guides/workflow/node/start.md similarity index 100% rename from en/features/workflow/node/start.md rename to en/guides/workflow/node/start.md diff --git a/en/features/workflow/node/template.md b/en/guides/workflow/node/template.md similarity index 100% rename from en/features/workflow/node/template.md rename to en/guides/workflow/node/template.md diff --git a/en/guides/workflow/node/tools.md b/en/guides/workflow/node/tools.md new file mode 100644 index 0000000..8ebe05f --- /dev/null +++ b/en/guides/workflow/node/tools.md @@ -0,0 +1,26 @@ +# Tools + +### Definition + +The workflow provides a rich selection of tools, categorized into three types: + +* **Built-in Tools**: Tools provided by Dify. +* **Custom Tools**: Tools imported or configured via the OpenAPI/Swagger standard format. +* **Workflows**: Workflows that have been published as tools. + +Before using built-in tools, you may need to **authorize** the tools. + +If built-in tools do not meet your needs, you can create custom tools in the **Dify menu navigation -- Tools** section. + +You can also orchestrate a more complex workflow and publish it as a tool. + +

Tool Selection

+ +

Configuring Google Search Tool to Retrieve External Knowledge

+ +Configuring a tool node generally involves two steps: + +1. Authorizing the tool/creating a custom tool/publishing a workflow as a tool. +2. Configuring the tool's input and parameters. + +For more information on how to create custom tools and configure them, please refer to the [Tool Configuration Guide](https://docs.dify.ai/v/zh-hans/guides/tools). \ No newline at end of file diff --git a/en/guides/workflow/node/variable-assigner.md b/en/guides/workflow/node/variable-assigner.md new file mode 100644 index 0000000..a732b13 --- /dev/null +++ b/en/guides/workflow/node/variable-assigner.md @@ -0,0 +1,39 @@ +# Variable Aggregation + +### 1 Definition + +Aggregate variables from multiple branches into a single variable to achieve unified configuration for downstream nodes. + +The variable aggregation node (formerly the variable assignment node) is a key node in the workflow. It is responsible for integrating the output results from different branches, ensuring that regardless of which branch is executed, its results can be referenced and accessed through a unified variable. This is particularly useful in multi-branch scenarios, as it maps variables with the same function from different branches into a single output variable, avoiding the need for repeated definitions in downstream nodes. + +*** + +### 2 Scenarios + +Through variable aggregation, you can aggregate multiple outputs, such as from issue classification or conditional branching, into a single output for use and manipulation by downstream nodes, simplifying data flow management. + +**Multi-Branch Aggregation after Issue Classification** + +Without variable aggregation, the branches of Classification 1 and Classification 2, after different knowledge base retrievals, would require repeated definitions for downstream LLM and direct response nodes. + +

Issue Classification (without Variable Aggregation)

+ +By adding variable aggregation, the outputs of the two knowledge retrieval nodes can be aggregated into a single variable. + +

Multi-Branch Aggregation after Issue Classification

+ +**Multi-Branch Aggregation after IF/ELSE Conditional Branching** + +

Multi-Branch Aggregation after Conditional Branching

+ +### 3 Format Requirements + +The variable aggregator supports aggregating various data types, including strings (`String`), numbers (`Number`), objects (`Object`), and arrays (`Array`). + +**The variable aggregator can only aggregate variables of the same data type**. If the first variable added to the variable aggregation node is of the `String` data type, subsequent connections will automatically filter and allow only `String` type variables to be added. + +**Aggregation Grouping** + +Starting from version v0.6.10, aggregation grouping is supported. + +When aggregation grouping is enabled, the variable aggregator can aggregate multiple groups of variables, with each group requiring the same data type for aggregation. \ No newline at end of file diff --git a/en/features/workflow/publish.md b/en/guides/workflow/publish.md similarity index 100% rename from en/features/workflow/publish.md rename to en/guides/workflow/publish.md diff --git a/en/guides/workspace/README.md b/en/guides/workspace/README.md new file mode 100644 index 0000000..c71fbf2 --- /dev/null +++ b/en/guides/workspace/README.md @@ -0,0 +1,20 @@ +# Collaboration + +Dify is a multi-user platform where workspaces are the basic units of team collaboration. Members of a workspace can create and edit applications and knowledge bases, and can also directly use public applications created by other team members in the [Discover](app/) area. + +### Login Methods + +It is important to note that the login methods supported by Dify's cloud service and community edition differ, as shown in the table below. + +| | Cloud Service | Community Edition | +| -------------- | ------------- | ----------------- | +| Email Login | Not Supported | Supported | +| GitHub Login | Supported | Not Supported | +| Google Login | Supported | Not Supported | +| SSO Login | Planned | Planned | + +### Creating an Account + +If you are using the cloud service, a workspace will be automatically created for you upon your first login, and you will become the administrator. + +In the community edition, you will be prompted to set an administrator email and password during installation. The community edition does not support the creation of multiple workspaces. \ No newline at end of file diff --git a/en/guides/workspace/app/README.md b/en/guides/workspace/app/README.md new file mode 100644 index 0000000..c6e96bf --- /dev/null +++ b/en/guides/workspace/app/README.md @@ -0,0 +1,21 @@ +# Discover + +## Template Applications + +In the **Discover** section, several commonly used template applications are provided. These applications cover areas such as human resources, assistants, translation, programming, and writing. + +
+ +To use a template application, click the "Add to Workspace" button on the template. You can then use the application in the workspace on the left side. + +
+ +To modify a template and create a new application, click the "Customize" button on the template. + +## Workspace + +The workspace serves as the navigation for applications. Click on an application within the workspace to use it directly. + +
+ +Applications in the workspace include your own applications as well as those added to the workspace by other team members. \ No newline at end of file diff --git a/en/workspace/billing.md b/en/guides/workspace/billing.md similarity index 100% rename from en/workspace/billing.md rename to en/guides/workspace/billing.md diff --git a/en/workspace/app.md b/en/guides/workspace/explore.md similarity index 100% rename from en/workspace/app.md rename to en/guides/workspace/explore.md diff --git a/en/guides/workspace/invite-and-manage-members.md b/en/guides/workspace/invite-and-manage-members.md new file mode 100644 index 0000000..0b71493 --- /dev/null +++ b/en/guides/workspace/invite-and-manage-members.md @@ -0,0 +1,13 @@ +# Inviting and Managing Members + +Members of a workspace can be invited and managed by the owner and administrators. After logging in, go to the settings under the user avatar dropdown in Dify, and open the member management interface from the left side of that screen. + +### Inviting Members + +Provide the email of the invitee. The system will immediately grant the invitee access to the workspace, and the invitee will also receive an email notification. + +The system will automatically create a Dify account for the new member. + +### Removing Members + +Once a member is removed from the team, they will no longer have access to the current workspace. However, this will not affect their access to other workspaces they have already joined. \ No newline at end of file diff --git a/en/learn-more/extended-reading/README.md b/en/learn-more/extended-reading/README.md new file mode 100644 index 0000000..392d04b --- /dev/null +++ b/en/learn-more/extended-reading/README.md @@ -0,0 +1 @@ +# Under Maintenance diff --git a/en/learn-more/extended-reading/retrieval-augment/README.md b/en/learn-more/extended-reading/retrieval-augment/README.md new file mode 100644 index 0000000..392d04b --- /dev/null +++ b/en/learn-more/extended-reading/retrieval-augment/README.md @@ -0,0 +1 @@ +# Under Maintenance diff --git a/en/learn-more/extended-reading/retrieval-augment/hybrid-search.md b/en/learn-more/extended-reading/retrieval-augment/hybrid-search.md new file mode 100644 index 0000000..e69de29 diff --git a/en/learn-more/extended-reading/retrieval-augment/rerank.md b/en/learn-more/extended-reading/retrieval-augment/rerank.md new file mode 100644 index 0000000..e69de29 diff --git a/en/learn-more/extended-reading/retrieval-augment/retrieval.md b/en/learn-more/extended-reading/retrieval-augment/retrieval.md new file mode 100644 index 0000000..e69de29 diff --git a/en/getting-started/what-is-llmops.md b/en/learn-more/extended-reading/what-is-llmops.md similarity index 99% rename from en/getting-started/what-is-llmops.md rename to en/learn-more/extended-reading/what-is-llmops.md index 890d7cc..d72fd67 100644 --- a/en/getting-started/what-is-llmops.md +++ b/en/learn-more/extended-reading/what-is-llmops.md @@ -24,7 +24,7 @@ Before using an LLMOps platform like Dify, the process of developing application 5. Model Fine-tuning: Independently manage the fine-tuning data preparation and training process, which can lead to inefficiencies and require more code. 6. System and Operations: Technical personnel involvement or cost required for developing a management backend, increasing development and maintenance costs, and lacking support for collaboration and non-technical users. -With the introduction of an LLMOps platform like Dify, the process of developing applications based on LLMs becomes more efficient, scalable, and secure. Here are the advantages of developing LLM applications using platforms like Dify: +With the introduction of an LLMOps platform like Dify, the process of developing applications based on LLMs becomes more efficient, scalable, and secure. Here are the advantages of developing LLM applications using Dify: 1. Data Preparation: The platform provides data collection and preprocessing tools, simplifying data cleaning and annotation tasks, and minimizing or even eliminating coding work. 2. Prompt Engineering: WYSIWYG Prompt editing and debugging, allowing real-time optimization and adjustments based on user input data. diff --git a/en/learn-more/faq/README.md b/en/learn-more/faq/README.md new file mode 100644 index 0000000..e69de29 diff --git a/en/tutorials/vector-database-migrate-tool.md b/en/learn-more/faq/self-host-faq.md similarity index 93% rename from en/tutorials/vector-database-migrate-tool.md rename to en/learn-more/faq/self-host-faq.md index dfeeedc..c39393f 100644 --- a/en/tutorials/vector-database-migrate-tool.md +++ b/en/learn-more/faq/self-host-faq.md @@ -1,4 +1,6 @@ -# Vector Database Migrate Tool +# Under Maintenance + +## 1 Vector Database Migrate Tool When you want to switch to another vector database, you can deactivate or delete the original vector database after switching. diff --git a/en/learn-more/faq/use-llms-faq.md b/en/learn-more/faq/use-llms-faq.md new file mode 100644 index 0000000..e69de29 diff --git a/en/user-guide/creating-dify-apps/use-cases/README.md b/en/learn-more/use-cases/README.md similarity index 100% rename from en/user-guide/creating-dify-apps/use-cases/README.md rename to en/learn-more/use-cases/README.md diff --git a/en/user-guide/creating-dify-apps/use-cases/build-an-notion-ai-assistant.md b/en/learn-more/use-cases/build-an-notion-ai-assistant.md similarity index 100% rename from en/user-guide/creating-dify-apps/use-cases/build-an-notion-ai-assistant.md rename to en/learn-more/use-cases/build-an-notion-ai-assistant.md diff --git a/en/user-guide/creating-dify-apps/use-cases/create-a-midjourney-prompt-bot-with-dify.md b/en/learn-more/use-cases/create-a-midjourney-prompt-bot-with-dify.md similarity index 100% rename from en/user-guide/creating-dify-apps/use-cases/create-a-midjourney-prompt-bot-with-dify.md rename to en/learn-more/use-cases/create-a-midjourney-prompt-bot-with-dify.md diff --git a/en/user-guide/creating-dify-apps/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md b/en/learn-more/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md similarity index 100% rename from en/user-guide/creating-dify-apps/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md rename to en/learn-more/use-cases/create-an-ai-chatbot-with-business-data-in-minutes.md diff --git a/en/policies/agreement/README.md b/en/policies/agreement/README.md new file mode 100644 index 0000000..ae9160b --- /dev/null +++ b/en/policies/agreement/README.md @@ -0,0 +1,9 @@ +## Data Security + +We highly value your data security and are in the process of obtaining SOC2 and ISO27001 certifications. + +Dify.AI's cloud services are hosted on AWS in the U.S. region. Only a very limited number of authorized personnel, after approval, can access user data. Additionally, our code is open-source on GitHub, so if you have security concerns about the cloud service, you can use the self-deployed version. + +In the self-deployed version of Dify, there is only one instance where the Dify server is called, which is for checking the current version update API. This action must be triggered by an administrator in the backend. There are no other technologies that use remote servers, so you can use it securely. + +If you still have concerns, you can protect your data by setting up firewalls and other security measures. \ No newline at end of file diff --git a/en/user-agreement/open-source.md b/en/policies/open-source.md similarity index 100% rename from en/user-agreement/open-source.md rename to en/policies/open-source.md diff --git a/en/user-agreement/data-security.md b/en/user-agreement/data-security.md deleted file mode 100644 index 61284cd..0000000 --- a/en/user-agreement/data-security.md +++ /dev/null @@ -1,13 +0,0 @@ -# Data Security - -Thank you for your interest in the Dify product. Dify takes your data security very seriously. Please refer to our [\[Privacy Policy\]](https://dify.ai/privacy). - -What can be disclosed is that Dify's cloud service is located on US Azure, and only a very small number of authorized personnel can access user data after approval. In addition, our code is open source on GitHub. If you have concerns about the security of cloud services, you can use the self-deployed version. - -As our product is still in its early stages, there may be some areas where we are not yet perfect, but we do plan to obtain SOC2 and ISO27001 certifications. - -If you have any questions regarding commercialization, please contact business@dify.ai. - -In the self-deployed version of Dify, there is only one instance where the Dify server is called - to check for updates via the API functionality. This must be triggered by an administrator in the backend. There are no other remote server technologies used, so you can use it safely. - -If you still have concerns, you can protect your data through measures such as setting up firewalls. diff --git a/en/user-guide/creating-dify-apps/README.md b/en/user-guide/creating-dify-apps/README.md deleted file mode 100644 index e0dd2b2..0000000 --- a/en/user-guide/creating-dify-apps/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Creating Dify Apps - diff --git a/en/user-guide/launching-dify-apps/README.md b/en/user-guide/launching-dify-apps/README.md deleted file mode 100644 index d424c7f..0000000 --- a/en/user-guide/launching-dify-apps/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Launching Dify Apps - diff --git a/en/user-guide/launching-dify-apps/developing-with-apis/api-use-faq.md b/en/user-guide/launching-dify-apps/developing-with-apis/api-use-faq.md deleted file mode 100644 index 1709e5d..0000000 --- a/en/user-guide/launching-dify-apps/developing-with-apis/api-use-faq.md +++ /dev/null @@ -1,11 +0,0 @@ -# API-use-FAQ - -## 1. What is a Bearer Token? - -Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources: - -``` -Authorization: Bearer -``` - -The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL). diff --git a/en/user-guide/using-dify-apps/README.md b/en/user-guide/using-dify-apps/README.md deleted file mode 100644 index 115bf4c..0000000 --- a/en/user-guide/using-dify-apps/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Using Dify Apps - diff --git a/en/user-guide/using-dify-apps/chat.md b/en/user-guide/using-dify-apps/chat.md deleted file mode 100644 index 34f4826..0000000 --- a/en/user-guide/using-dify-apps/chat.md +++ /dev/null @@ -1,57 +0,0 @@ -# Further Chat App Settings - -Chat in explore is a conversational application used to explore the boundaries of Dify's capabilities. - -When we talk to large natural language models, we often encounter situations where the answers are outdated or invalid. This is due to the old training data of the large model and the lack of networking capabilities. Based on the large model, Chat uses agents to capabilities and some tools endow the large model with the ability of online real-time query. - -
- -Chat supports the use of plugins and knowledge. - -### Use plugins - -LLM(Large language model)cannot be networked and invoke external tools. But this cannot meet the actual usage scenarios, such as: - -* When we want to know the weather today, we need to be connected to the Internet. -* When we want to summarize the content of a web page, we need to use an external tool: read the content of the web page. - -The above problem can be solved by using the agent mode: when the LLM cannot answer the user's question, it will try to use the existing plugins to answer the question. - -{% hint style="info" %} -In Dify, we use different proxy strategies for different models. The proxy strategy used by OpenAI's model is **GPT function call**. Another model used is **ReACT**. The current test experience is that the effect of **GPT function call** is better. To know more, you can read the link below: - -* [Function calling and other API updates](https://openai.com/blog/function-calling-and-other-api-updates) -* [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) -{% endhint %} - -Currently we support the following plugins: - -* Google Search. The plugin searches Google for answers. -* Web Reader. The plugin reads the content of linked web pages. -* Wikipedia. The plugin searches Wikipedia for answers. - -We can choose the plugins needed for this conversation before the conversation starts. - -
- -If you use the Google search plugin, you need to configure the SerpAPI key. - -
- -Configured entry: - -
- -### Use knowledge - -Chat supports knowledge. After selecting the knowledge, the questions asked by the user are related to the content of the data set, and the model will find the answer from the data set. - -We can select the knowledge needed for this conversation before the conversation starts. - -
- -### The process of thinking - -The thinking process refers to the process of the model using plugins and knowledge. We can see the thought process in each answer. - -
diff --git a/zh_CN/guides/extension/code_based_extension/README.md b/zh_CN/guides/extension/code_based_extension/README.md index 6259308..d4053b8 100644 --- a/zh_CN/guides/extension/code_based_extension/README.md +++ b/zh_CN/guides/extension/code_based_extension/README.md @@ -1,33 +1,33 @@ -# 代码扩展 +# Code Based Extensions -对于本地部署 Dify 的开发者，如果想实现扩展能力，无需重新写一个 API 服务，可以使用代码扩展，即在 Dify 功能的基础上，以代码形式扩展或增强程序的能力（即插件能力），而不破坏 Dify 原有代码逻辑。它遵循一定的接口或规范，以实现与主程序的兼容和可插拔性。 目前，Dify 开放了两种代码扩展，分别为： +For developers deploying Dify locally, if you want to implement extension capabilities without rewriting an API service, you can use code extensions. This allows you to extend or enhance the functionality of the program in code form (i.e., plugin capability) without disrupting the original code logic of Dify. It follows certain interfaces or specifications to achieve compatibility and plug-and-play capability with the main program. Currently, Dify offers two types of code extensions: -* 新增一种新的外部数据工具类型 [external\_data\_tool.md](external\_data\_tool.md "mention") -* 扩展敏感内容审查策略 [moderation.md](moderation.md "mention") +* Adding a new type of external data tool [external_data_tool.md](external_data_tool.md "mention") +* Extending sensitive content moderation strategies [moderation.md](moderation.md "mention") -可在上述功能的基础上，遵循代码层 interface 的规范，来实现横向扩展的目的。如果你愿意将扩展功能贡献给我们的话，非常欢迎给 Dify 提交 PR。 +Based on the above functionalities, you can achieve horizontal expansion by following the code-level interface specifications. If you are willing to contribute your extensions to us, we warmly welcome you to submit a PR to Dify. -## 前端组件规范定义 +## Frontend Component Specification Definition -代码扩展的前端样式通过 `schema.json` 定义： +The frontend styles of code extensions are defined through `schema.json`: -* label：自定义类型名称，支持系统语言切换 -* form\_schema：表单内容列表 - * type：组件类型 - * select：下拉选项 - * text-input：文本 - * paragraph：段落 - * label：组件名称，支持系统语言切换 - * variable：变量名称 - * required：是否必填 - * default：默认值 - * placeholder：组件提示内容 - * options：组件「select」专有属性，定义下拉内容 - * label：下拉名称，支持系统语言切换 - * value：下拉选项值 - * max\_length：组件「text-input」专有属性，最大长度 +* label: Custom type name, supporting system language switching +* form_schema: List of form contents + * type: Component type + * select: Dropdown options + * text-input: Text + * paragraph: Paragraph + * label: Component name, supporting system language switching + * variable: Variable name + * required: Whether it is required + * default: Default value + * placeholder: Component hint content + * options: Exclusive property for the "select" component, defining the dropdown contents + * label: Dropdown name, supporting system language switching + * value: Dropdown option value + * max_length: Exclusive property for the "text-input" component, maximum length -### 模版样例 +### Template Example ```json { @@ -95,4 +95,4 @@ } ] } -``` +``` \ No newline at end of file diff --git a/zh_CN/guides/workflow/node/tools.md b/zh_CN/guides/workflow/node/tools.md index 5e9ec19..64962bb 100644 --- a/zh_CN/guides/workflow/node/tools.md +++ b/zh_CN/guides/workflow/node/tools.md @@ -24,6 +24,3 @@ 2. 配置工具输入和参数 如何创建自定义工具和配置工具请参考[工具配置说明](https://docs.dify.ai/v/zh-hans/guides/tools)。 - - -