Dify is an open-source LLM app development platform. Its intuitive interface combines AI workflow, RAG pipeline, agent capabilities, model management, observability features (including [Opik](https://www.comet.com/docs/opik/integrations/dify), [Langfuse](https://docs.langfuse.com), and [Arize Phoenix](https://docs.arize.com/phoenix)) and more, letting you quickly go from prototype to production. Here's a list of the core features:
## Quick start
> Before installing Dify, make sure your machine meets the following minimum system requirements:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
The easiest way to start the Dify server is through [Docker Compose](docker/docker-compose.yaml). Before running Dify with the following commands, make sure that [Docker](https://docs.docker.com/get-docker/) and Docker Compose v2.24.0 or later are installed on your machine:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
After running, you can access the Dify dashboard in your browser at [http://localhost/install](http://localhost/install) and start the initialization process.
### Seeking help
Please refer to our [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs) if you encounter problems setting up Dify. Reach out to [the community and us](#community--contact) if you are still having issues.
> If you'd like to contribute to Dify or do additional development, refer to our [guide to deploying from source code](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## Key features
**1. Workflow**:
Build and test powerful AI workflows on a visual canvas, leveraging all the following features and beyond.
**2. Comprehensive model support**:
Seamless integration with hundreds of proprietary / open-source LLMs from dozens of inference providers and self-hosted solutions, covering GPT, Mistral, Llama3, and any OpenAI API-compatible models. A full list of supported model providers can be found [here](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
Intuitive interface for crafting prompts, comparing model performance, and adding additional features such as text-to-speech to a chat-based app.
**4. RAG Pipeline**:
Extensive RAG capabilities that cover everything from document ingestion to retrieval, with out-of-box support for text extraction from PDFs, PPTs, and other common document formats.
**5. Agent**: Autonomous agents with a sandbox of their own: they run commands, install software, and handle files to get open-ended tasks done. Describe the agent you want and it builds itself. Give it skills, connect tools from [Dify Marketplace](https://marketplace.dify.ai/?category=tool), MCP servers, or your own APIs, and put it to work as a chat app or as a step in any workflow.
**6. LLMOps**:
Monitor and analyze application logs and performance over time. You could continuously improve prompts, datasets, and models based on production data and annotations.
**7. Backend-as-a-Service**:
All of Dify's offerings come with corresponding APIs, so you could effortlessly integrate Dify into your own business logic.
## Using Dify
- **Cloud **
We host [Dify Cloud](https://cloud.dify.ai) so you can try Dify without managing a server. See the [pricing page](https://dify.ai/pricing) for current plans and usage allowances. If you run into issues, [contact our Cloud support team](mailto:cloud@dify.ai?subject=%5BGitHub%5DDify%20Cloud%20Support).
- **Self-hosting Dify Community Edition **
Quickly get Dify running in your environment with this [starter guide](#quick-start).
Use our [documentation](https://docs.dify.ai) for further references and more in-depth instructions.
- **[Dify Enterprise](https://dify.ai/dify-enterprise) **
For organizations requiring self-hosting, SSO, RBAC Security and Enterprise Support SLAs, please fill out [this form](https://share-na2.hsforms.com/14-09ff5HS92Sh4m3f4yrcw40s9fk) to speak to a solution representative.
## Staying ahead
Star Dify on GitHub and be instantly notified of new releases.
## Advanced Setup
For custom configuration, observability, and deployment options, see [Advanced Setup](docs/ADVANCED_SETUP.md).
## Contributing
Dify welcomes contributions of all kinds:
- **Code**: Read the [Contribution Guide](CONTRIBUTING.md), then browse [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideas and feedback**: Start or join a [GitHub Discussion](https://github.com/langgenius/dify/discussions).
- **Translations**: Follow the [internationalization guide](web/i18n/README.md) to add or update a locale.
- **Community**: Share the apps you build, help other users, and spread the word about Dify.
### Contributors
## Community & contact
Choose the channel that best fits your question:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Get help, share feedback, and propose ideas.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Report reproducible bugs and track engineering work. Read the [Contribution Guide](CONTRIBUTING.md) before opening one.
- [Discord](https://discord.gg/FngNHpbcY7): Chat in real time, share your apps, and connect with other Dify users.
- [X](https://x.com/dify_ai): Follow Dify for release news and project updates.
## Star History
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Security disclosure
Report vulnerabilities privately through GitHub Security Advisories, following our [security policy](SECURITY.md). Do not disclose them in public issues, discussions, or pull requests.
## License
This repository is licensed under the [Dify Open Source License](LICENSE), based on Apache 2.0 with additional conditions.
---
### Dify Agent Docs Index (`dify-agent/docs/index.md`)
# Dify Agent
[Runtime modules](dify-agent/index.md) compose native Pydantic AI capabilities
and toolsets. [Getting started](dify-agent/get-started/index.md) covers the HTTP
protocol; [operations](dify-agent/guide/index.md) covers deployment.
---
### Ar SA README (`docs/ar-SA/README.md`)
مشروع Dify هو منصة تطوير تطبيقات الذكاء الصناعي مفتوحة المصدر. تجمع واجهته البديهية بين سير العمل الذكي بالذكاء الاصطناعي وخط أنابيب RAG وقدرات الوكيل وإدارة النماذج وميزات الملاحظة وأكثر من ذلك، مما يتيح لك الانتقال بسرعة من المرحلة التجريبية إلى الإنتاج. إليك قائمة بالميزات الأساسية:
**1. سير العمل**: قم ببناء واختبار سير عمل الذكاء الاصطناعي القوي على قماش بصري، مستفيدًا من جميع الميزات التالية وأكثر.
**2. الدعم الشامل للنماذج**: تكامل سلس مع مئات من LLMs الخاصة / مفتوحة المصدر من عشرات من موفري التحليل والحلول المستضافة ذاتيًا، مما يغطي GPT و Mistral و Llama3 وأي نماذج متوافقة مع واجهة OpenAI API. يمكن العثور على قائمة كاملة بمزودي النموذج المدعومين [هنا](https://docs.dify.ai/getting-started/readme/model-providers).
**3. بيئة التطوير للأوامر**: واجهة بيئة التطوير المبتكرة لصياغة الأمر ومقارنة أداء النموذج، وإضافة ميزات إضافية مثل تحويل النص إلى كلام إلى تطبيق قائم على الدردشة.
**4. خط أنابيب RAG**: قدرات RAG الواسعة التي تغطي كل شيء من استيعاب الوثائق إلى الاسترجاع، مع الدعم الفوري لاستخراج النص من ملفات PDF و PPT وتنسيقات الوثائق الشائعة الأخرى.
**5. قدرات الوكيل**: يمكنك تعريف الوكلاء بناءً على أمر وظيفة LLM أو ReAct، وإضافة أدوات مدمجة أو مخصصة للوكيل. توفر Dify أكثر من 50 أداة مدمجة لوكلاء الذكاء الاصطناعي، مثل البحث في Google و DALL·E وStable Diffusion و WolframAlpha.
**6. الـ LLMOps**: راقب وتحلل سجلات التطبيق والأداء على مر الزمن. يمكنك تحسين الأوامر والبيانات والنماذج باستمرار استنادًا إلى البيانات الإنتاجية والتعليقات.
**7.الواجهة الخلفية (Backend) كخدمة**: تأتي جميع عروض Dify مع APIs مطابقة، حتى يمكنك دمج Dify بسهولة في منطق أعمالك الخاص.
## استخدام Dify
- **سحابة **
جرّب [Dify Cloud](https://cloud.dify.ai) دون إدارة خادم. راجع [صفحة الأسعار](https://dify.ai/pricing) للاطلاع على الخطط وحصص الاستخدام الحالية.
- **استضافة ذاتية لنسخة المجتمع Dify**
ابدأ سريعًا في تشغيل Dify في بيئتك باستخدام \[دليل البدء السريع\](#البدء السريع).
استخدم [توثيقنا](https://docs.dify.ai) للمزيد من المراجع والتعليمات الأعمق.
- **مشروع Dify للشركات / المؤسسات**
نحن نوفر ميزات إضافية مركزة على الشركات. [جدول اجتماع معنا](https://cal.com/guchenhe/30min) أو [أرسل لنا بريدًا إلكترونيًا](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) لمناقشة احتياجات الشركات.
## البقاء قدمًا
قم بإضافة نجمة إلى Dify على GitHub وتلق تنبيهًا فوريًا بالإصدارات الجديدة.
## البداية السريعة
> قبل تثبيت Dify، تأكد من أن جهازك يلبي الحد الأدنى من متطلبات النظام التالية:
>
> - معالج >= 2 نواة
> - ذاكرة وصول عشوائي (RAM) >= 4 جيجابايت
أسهل طريقة لبدء تشغيل خادم Dify هي تشغيل ملف [docker-compose.yml](../../docker/docker-compose.yaml) الخاص بنا. قبل تشغيل أمر التثبيت، تأكد من تثبيت [Docker](https://docs.docker.com/get-docker/) و [Docker Compose](https://docs.docker.com/compose/install/) على جهازك:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
بعد التشغيل، يمكنك الوصول إلى لوحة تحكم Dify في متصفحك على [http://localhost/install](http://localhost/install) وبدء عملية التهيئة.
> إذا كنت ترغب في المساهمة في Dify أو القيام بتطوير إضافي، فانظر إلى [دليلنا للنشر من الشفرة (code) المصدرية](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## الخطوات التالية
لخيارات التكوين المخصص والمراقبة والنشر، راجع [الإعداد المتقدم](ADVANCED_SETUP.md).
## المساهمة
يرحب Dify بالمساهمات بجميع أشكالها:
- **الشفرة البرمجية**: اقرأ [دليل المساهمة](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md)، ثم تصفح [المشكلات المناسبة للمساهمين الجدد](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **الأفكار والملاحظات**: ابدأ أو انضم إلى [مناقشة على GitHub](https://github.com/langgenius/dify/discussions).
- **الترجمات**: اتبع [دليل التدويل](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) لإضافة لغة أو تحديثها.
- **المجتمع**: شارك التطبيقات التي تبنيها، وساعد المستخدمين الآخرين، وساهم في نشر Dify.
### المساهمون
## المجتمع والاتصال
اختر القناة الأنسب لسؤالك:
- [مناقشات GitHub](https://github.com/langgenius/dify/discussions): للحصول على المساعدة ومشاركة الملاحظات واقتراح الأفكار.
- [مشكلات GitHub](https://github.com/langgenius/dify/issues): للإبلاغ عن الأخطاء القابلة لإعادة الإنتاج ومتابعة العمل الهندسي. اقرأ [دليل المساهمة](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) قبل فتح مشكلة.
- [Discord](https://discord.gg/FngNHpbcY7): للدردشة الفورية ومشاركة تطبيقاتك والتواصل مع مستخدمي Dify الآخرين.
- [X](https://x.com/dify_ai): لمتابعة أخبار الإصدارات وتحديثات المشروع.
## تاريخ النجمة
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## الكشف عن الأمان
أبلغ عن الثغرات بشكل خاص عبر GitHub Security Advisories وفقًا [لسياسة الأمان](../../SECURITY.md). لا تفصح عنها في المشكلات أو المناقشات أو طلبات السحب العامة.
## الرخصة
هذا المستودع متاح تحت [رخصة البرنامج الحر Dify](../../LICENSE)، والتي تعتبر بشكل أساسي Apache 2.0 مع بعض القيود الإضافية.
---
### Bn BD README (`docs/bn-BD/README.md`)
ডিফাই একটি ওপেন-সোর্স LLM অ্যাপ ডেভেলপমেন্ট প্ল্যাটফর্ম। এটি ইন্টুইটিভ ইন্টারফেস, এজেন্টিক AI ওয়ার্কফ্লো, RAG পাইপলাইন, এজেন্ট ক্যাপাবিলিটি, মডেল ম্যানেজমেন্ট, মনিটরিং সুবিধা এবং আরও অনেক কিছু একত্রিত করে, যা দ্রুত প্রোটোটাইপ থেকে প্রোডাকশন পর্যন্ত নিয়ে যেতে সহায়তা করে।
## কুইক স্টার্ট
> ডিফাই ইনস্টল করার আগে, নিশ্চিত করুন যে আপনার মেশিন নিম্নলিখিত ন্যূনতম কনফিগারেশনের প্রয়োজনীয়তা পূরন করে :
>
> - সিপিউ >= 2 কোর
> - র্যাম >= 4 জিবি
ডিফাই সার্ভার চালু করার সবচেয়ে সহজ উপায় [docker compose](../../docker/docker-compose.yaml) মাধ্যমে। নিম্নলিখিত কমান্ডগুলো ব্যবহার করে ডিফাই চালানোর আগে, নিশ্চিত করুন যে আপনার মেশিনে [Docker](https://docs.docker.com/get-docker/) এবং [Docker Compose](https://docs.docker.com/compose/install/) ইনস্টল করা আছে :
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
চালানোর পর, আপনি আপনার ব্রাউজারে [http://localhost/install](http://localhost/install)-এ ডিফাই ড্যাশবোর্ডে অ্যাক্সেস করতে পারেন এবং ইনিশিয়ালাইজেশন প্রক্রিয়া শুরু করতে পারেন।
### সাহায্যের খোঁজে
ডিফাই সেট আপ করতে সমস্যা হলে দয়া করে আমাদের [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs) দেখুন। যদি তবুও সমস্যা থেকে থাকে, তাহলে [কমিউনিটি এবং আমাদের](#কমিউনিটি-এবং-যোগাযোগ) সাথে যোগাযোগ করুন।
> যদি আপনি ডিফাইতে অবদান রাখতে বা অতিরিক্ত উন্নয়ন করতে চান, আমাদের [সোর্স কোড থেকে ডিপ্লয়মেন্টের গাইড](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code) দেখুন।
## প্রধান ফিচারসমূহ
**১. ওয়ার্কফ্লো**:
ভিজ্যুয়াল ক্যানভাসে AI ওয়ার্কফ্লো তৈরি এবং পরীক্ষা করুন, নিম্নলিখিত সব ফিচার এবং তার বাইরেও আরও অনেক কিছু ব্যবহার করে।
**২. মডেল সাপোর্ট**:
GPT, Mistral, Llama3, এবং যেকোনো OpenAI API-সামঞ্জস্যপূর্ণ মডেলসহ, কয়েক ডজন ইনফারেন্স প্রদানকারী এবং সেল্ফ-হোস্টেড সমাধান থেকে শুরু করে প্রোপ্রাইটরি/ওপেন-সোর্স LLM-এর সাথে সহজে ইন্টিগ্রেশন। সমর্থিত মডেল প্রদানকারীদের একটি সম্পূর্ণ তালিকা পাওয়া যাবে [এখানে](https://docs.dify.ai/getting-started/readme/model-providers)।
**3. প্রম্পট IDE**:
প্রম্পট তৈরি, মডেলের পারফরম্যান্স তুলনা এবং চ্যাট-বেজড অ্যাপে টেক্সট-টু-স্পিচের মতো বৈশিষ্ট্য যুক্ত করার জন্য ইন্টুইটিভ ইন্টারফেস।
**4. RAG পাইপলাইন**:
ডকুমেন্ট ইনজেশন থেকে শুরু করে রিট্রিভ পর্যন্ত সবকিছুই বিস্তৃত RAG ক্যাপাবিলিটির আওতাভুক্ত। PDF, PPT এবং অন্যান্য সাধারণ ডকুমেন্ট ফর্ম্যাট থেকে টেক্সট এক্সট্রাকশনের জন্য আউট-অফ-বক্স সাপোর্ট।
**5. এজেন্ট ক্যাপাবিলিটি**:
LLM ফাংশন কলিং বা ReAct উপর ভিত্তি করে এজেন্ট ডিফাইন করতে পারেন এবং এজেন্টের জন্য পূর্ব-নির্মিত বা কাস্টম টুলস যুক্ত করতে পারেন। Dify AI এজেন্টদের জন্য 50+ বিল্ট-ইন টুলস সরবরাহ করে, যেমন Google Search, DALL·E, Stable Diffusion এবং WolframAlpha।
**6. এলএলএম-অপ্স**:
সময়ের সাথে সাথে অ্যাপ্লিকেশন লগ এবং পারফরম্যান্স মনিটর এবং বিশ্লেষণ করুন। প্রডাকশন ডেটা এবং annotation এর উপর ভিত্তি করে প্রম্পট, ডেটাসেট এবং মডেলগুলিকে ক্রমাগত উন্নত করতে পারেন।
**7. ব্যাকএন্ড-অ্যাজ-এ-সার্ভিস**:
ডিফাই-এর সমস্ত অফার সংশ্লিষ্ট API-সহ আছে, যাতে আপনি অনায়াসে ডিফাইকে আপনার নিজস্ব বিজনেস লজিকে ইন্টেগ্রেট করতে পারেন।
## ডিফাই-এর ব্যবহার
- **ক্লাউড **
সার্ভার পরিচালনা ছাড়াই [Dify Cloud](https://cloud.dify.ai)-এ Dify ব্যবহার করে দেখুন। বর্তমান প্ল্যান ও ব্যবহারের সীমা জানতে [মূল্যতালিকা](https://dify.ai/pricing) দেখুন।
- **সেল্ফহোস্টিং ডিফাই কমিউনিটি সংস্করণ**
সেল্ফহোস্ট করতে এই [স্টার্টার গাইড](#কুইক-স্টার্ট) ব্যবহার করে দ্রুত আপনার এনভায়রনমেন্টে ডিফাই চালান।
আরো ইন-ডেপথ রেফারেন্সের জন্য [ডকুমেন্টেশন](https://docs.dify.ai) দেখেন।
- **এন্টারপ্রাইজ / প্রতিষ্ঠানের জন্য Dify**
আমরা এন্টারপ্রাইজ/প্রতিষ্ঠান-কেন্দ্রিক সেবা প্রদান করে থাকি । [এই চ্যাটবটের মাধ্যমে আপনার প্রশ্নগুলি আমাদের জন্য লগ করুন।](https://udify.app/chat/22L1zSxg6yW1cWQg) অথবা [আমাদের ইমেল পাঠান](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) আপনার চাহিদা সম্পর্কে আলোচনা করার জন্য।
## এগিয়ে থাকুন
GitHub-এ ডিফাইকে স্টার দিয়ে রাখুন এবং নতুন রিলিজের খবর তাৎক্ষণিকভাবে পান।
## Advanced Setup
কাস্টম কনফিগারেশন, পর্যবেক্ষণ এবং ডেপ্লয়মেন্ট বিকল্পের জন্য, [উন্নত সেটআপ](ADVANCED_SETUP.md) দেখুন।
## অবদান
Dify সব ধরনের অবদানকে স্বাগত জানায়:
- **কোড**: [অবদান নির্দেশিকা](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) পড়ুন, তারপর [নতুন অবদানকারীদের উপযোগী সমস্যাগুলো](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) দেখুন।
- **ধারণা ও প্রতিক্রিয়া**: একটি [GitHub আলোচনা](https://github.com/langgenius/dify/discussions) শুরু করুন বা বিদ্যমান আলোচনায় যোগ দিন।
- **অনুবাদ**: কোনো লোকেল যোগ বা হালনাগাদ করতে [আন্তর্জাতিকীকরণ নির্দেশিকা](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) অনুসরণ করুন।
- **কমিউনিটি**: আপনার তৈরি অ্যাপ শেয়ার করুন, অন্য ব্যবহারকারীদের সাহায্য করুন এবং Dify সম্পর্কে সবাইকে জানান।
### অবদানকারীরা
## কমিউনিটি এবং যোগাযোগ
আপনার প্রশ্নের জন্য সবচেয়ে উপযুক্ত মাধ্যমটি বেছে নিন:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): সাহায্য নিন, প্রতিক্রিয়া জানান এবং ধারণা প্রস্তাব করুন।
- [GitHub Issues](https://github.com/langgenius/dify/issues): পুনরুৎপাদনযোগ্য বাগ রিপোর্ট করুন এবং ইঞ্জিনিয়ারিং কাজ অনুসরণ করুন। নতুন ইস্যু খোলার আগে [অবদান নির্দেশিকা](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) পড়ুন।
- [Discord](https://discord.gg/FngNHpbcY7): সরাসরি আলোচনা করুন, আপনার অ্যাপ শেয়ার করুন এবং অন্যান্য Dify ব্যবহারকারীর সঙ্গে যুক্ত হন।
- [X](https://x.com/dify_ai): রিলিজের খবর এবং প্রকল্পের হালনাগাদ পেতে Dify অনুসরণ করুন।
## স্টার হিস্ট্রি
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## নিরাপত্তা বিষয়ক
আমাদের [নিরাপত্তা নীতি](../../SECURITY.md) অনুসারে GitHub Security Advisories-এর মাধ্যমে গোপনে নিরাপত্তা দুর্বলতা জানান। প্রকাশ্য issue, আলোচনা বা pull request-এ তা প্রকাশ করবেন না।
## লাইসেন্স
এই রিপোজিটরিটি [ডিফাই ওপেন সোর্স লাইসেন্স](../../LICENSE) এর অধিনে , যা মূলত অ্যাপাচি ২.০, তবে কিছু অতিরিক্ত বিধিনিষেধ রয়েছে।
---
### Cross Env App Migration README (`docs/cross-env-app-migration/README.md`)
# Cross-Environment Data Migration
This guide explains how to move workflow apps, chatflow apps, and their custom tool dependencies from one Dify environment to another.
The recommended best-practice path is:
1. Run the export wizard in the source environment.
2. Import the generated migration package in the target environment.
Use scripted export only when you need repeatable automation.
## What Gets Migrated
The migration package can contain:
- Workflow apps and advanced-chat apps.
- Custom API tool providers.
- Workflow tool providers.
- MCP tool providers when secrets are explicitly included.
- Dependency metadata for MCP tools, built-in tools, and plugin tools that must already exist or be configured in the target environment.
Only single source workspace exports are supported. The source and target workspace names do not need to match.
## Recommended Flow: Wizard Export + Import
Run the wizard from the source environment:
```bash
cd api
source .venv/bin/activate
uv run flask app-migration-wizard
```
The wizard asks you to select the source workspace, choose workflow/chatflow apps, discover referenced tools, set import behavior, and write the final migration package JSON.
Then copy the generated JSON package to the target environment and import it:
```bash
cd api
source .venv/bin/activate
uv run flask import-app-migration \
--input migration-data-20260528-120000.json \
--target-tenant "production Workspace"
```
This wizard + import combination is the recommended migration workflow because the wizard shows the available apps and tools, discovers app dependencies, summarizes the package before writing it, and uses the same export service as scripted export.
## Wizard Command
```bash
cd api
source .venv/bin/activate
uv run flask app-migration-wizard
```
The wizard has no CLI options. Its interactive inputs are:
- `Source tenant`: the source workspace to export from. Select one tenant by number.
- `App selection`: apps to export. Supported app types are `workflow` and `advanced-chat`. Enter `all`, one number, or comma-separated numbers.
- `Automatically export tools referenced by selected apps?`: recommended `yes`. This scans selected app graphs and automatically includes referenced custom API tools, workflow tools, and MCP tool references.
- `Export additional tools manually?`: optional. Use this when you need to migrate tools that are not referenced by the selected apps.
- `Include secrets in output JSON?`: default `no`. When `no`, workflow/app DSL secrets are omitted or masked, API tool credentials are omitted, and MCP providers are exported as dependency metadata only. When `yes`, treat the output JSON as sensitive.
- `Create or reuse app API tokens during import?`: default `no`. When `yes`, import creates an app API token for imported apps that have none, or reuses an existing token.
- `Import ID strategy`: `preserve-id` or `generate-new-id`. Default is `preserve-id`.
- `Import conflict strategy`: `fail`, `skip`, or `update`. Wizard default is `update`.
- `Output path`: output migration package path. The default is `migration-data-YYYYMMDD-HHMMSS.json`.
- `Overwrite existing output`: shown only if the selected output file already exists.
- `Write migration package?`: final confirmation after the wizard prints the summary.
## Import Command
```bash
cd api
source .venv/bin/activate
uv run flask import-app-migration --input migration-package.json --target-tenant "target Workspace"
```
Options:
- `--input`: required. Path to the migration package JSON generated by the wizard or scripted export.
- `--target-tenant`: optional only when package metadata already contains a target tenant. Target workspace name or workspace UUID. This overrides package metadata and is recommended for reusable packages.
- `--operator-email`: optional. Email of the target-tenant account used as the import operator. If omitted, import uses the earliest owner account in the target tenant.
- `--id-strategy`: optional override for the package import option. Allowed values:
- `preserve-id`: keep source app/tool IDs when supported. This is the recommended default for preserving workflow references across environments.
- `generate-new-id`: let the target environment generate new IDs and rewrite references through the migration ID mapping.
- `--conflict-strategy`: optional override for the package import option. Allowed values:
- `fail`: stop at the first existing target resource conflict. Previously committed resources are not rolled back.
- `skip`: keep the existing target resource and skip importing that resource.
- `update`: update the existing target resource in place.
- `--create-app-api-token-on-import`: optional override. Create or reuse app API tokens during import.
- `--no-create-app-api-token-on-import`: optional override. Do not create app API tokens during import.
Import prints a report that includes the resolved target tenant, operator, created/updated/skipped resources, unresolved dependencies, app API token counts, and ID mappings used to rewrite references.
## Optional Flow: Scripted Export
Scripted export is supported for automation. The recommended scripted path is:
1. Generate an export config template.
2. Edit the template.
3. Run scripted export.
4. Import the generated package.
Generate the template:
```bash
cd api
source .venv/bin/activate
uv run flask app-migration-template --output export-config.json
```
Edit `export-config.json`, then run:
```bash
cd api
source .venv/bin/activate
uv run flask export-app-migration \
--input export-config.json \
--output migration-package.json
```
Import it:
```bash
cd api
source .venv/bin/activate
uv run flask import-app-migration \
--input migration-package.json \
--target-tenant "production Workspace"
```
### Template Command
```bash
cd api
source .venv/bin/activate
uv run flask app-migration-template [--output export-config.json] [--overwrite]
```
Options:
- `--output`: optional. Path to write the scripted export config JSON template. If omitted, the template is printed to stdout.
- `--overwrite`: optional. Allows replacing an existing output file. Without this option, the command fails if `--output` already exists.
### Scripted Export Command
```bash
cd api
source .venv/bin/activate
uv run flask export-app-migration --input export-config.json --output migration-package.json
```
Options:
- `--input`: required. Path to the export config JSON.
- `--output`: required. Path to write the migration package JSON.
- `--overwrite`: optional. Allows replacing an existing output package. Without this option, the command fails if `--output` already exists.
### Export Config Fields
The generated template uses this shape:
```json
{
"source_tenant": {
"mode": "single",
"id": "",
"name": "admin's Workspace"
},
"apps": {
"modes": ["workflow", "advanced-chat"],
"ids": [],
"all": true
},
"include_referenced_tools": true,
"additional_tools": {
"api_tools": [],
"workflow_tools": [],
"mcp_tools": []
},
"include_secrets": false,
"import_options": {
"create_app_api_token_on_import": false,
"id_strategy": "preserve-id",
"conflict_strategy": "fail"
}
}
```
Fields:
- `source_tenant.mode`: must be `single`.
- `source_tenant.id`: optional source workspace UUID. Use this when workspace names are duplicated or when you want strict source selection.
- `source_tenant.name`: required source workspace name. When `source_tenant.id` is set, the ID and name must match.
- `apps.modes`: optional list of app modes for validation. Supported values are `workflow` and `advanced-chat`.
- `apps.ids`: app IDs to export when `apps.all` is `false`.
- `apps.all`: when `true`, export all supported apps in the selected source workspace. When `false`, export only `apps.ids`.
- `include_referenced_tools`: recommended `true`. Automatically discovers tools referenced by selected workflow/chatflow apps.
- `additional_tools.api_tools`: optional custom API tool provider names to export in addition to referenced tools.
- `additional_tools.workflow_tools`: optional workflow tool provider IDs to export in addition to referenced tools.
- `additional_tools.mcp_tools`: optional MCP provider IDs or server identifiers to export in addition to referenced tools.
- `include_secrets`: default `false`. When `false`, credentials are omitted and MCP providers are recorded as dependency metadata. When `true`, custom API credentials, workflow DSL secrets, and full MCP connection data can be written to the package.
- `import_options.create_app_api_token_on_import`: default `false`. Package-level default for import token creation.
- `import_options.id_strategy`: package-level default ID strategy. Allowed values are `preserve-id` and `generate-new-id`.
- `import_options.conflict_strategy`: package-level default conflict strategy. Allowed values are `fail`, `skip`, and `update`.
## Referenced Tools
Use automatic referenced-tool discovery whenever possible.
When enabled, Dify scans selected workflow/chatflow graphs and agent tool configs, then de-duplicates discovered custom API tools, workflow tools, and MCP tool references before export. This reduces the chance of importing an app whose workflow references missing providers.
Built-in and plugin tools are not serialized into the package. The migration report records them as dependency metadata; make sure the target environment has the required built-in or plugin tools installed and configured.
MCP providers are also dependency-only unless `include_secrets` is enabled. If MCP secrets are not exported, configure the corresponding MCP provider manually in the target workspace before running migrated workflows.
## Secret Handling
The safe default is `include_secrets: false`.
Only enable secret export when you have a controlled transfer path for the JSON package. With secrets enabled, the package may include API tool credentials, workflow/app DSL secret values, MCP server URLs, MCP headers, authentication data, and cached MCP tool lists.
## FAQ
### What happens when `include_secrets` is `false`?
This is the recommended default, but it means the migration package is intentionally incomplete for sensitive runtime configuration.
Important behavior:
- MCP tools are not exported as full tool providers. They are recorded as dependency metadata only.
- Custom API tool credentials are not exported. The provider schema can be exported, but credentials must be configured again in the target workspace.
- Workflow/app DSL secrets are omitted or masked. Any app variables, credentials, or secret-backed settings must be reviewed in the target workspace after import.
- Built-in and plugin tools are never serialized as custom migration data. They are recorded as dependencies only.
How to handle it:
- Before importing, install or enable the required built-in/plugin tools in the target environment.
- For MCP tools, manually create or configure the corresponding MCP provider in the target workspace before running migrated workflows.
- For custom API tools, open the imported provider in the target workspace and re-enter credentials.
- After import, review each migrated workflow/chatflow before production use. Pay special attention to tool nodes, agent tool configs, environment variables, app variables, and credential-backed settings.
- Use the import report. Items marked `dependency-only`, `skipped`, or `unresolved` usually need manual follow-up.
If you need the package to carry full MCP provider configuration or credentials, rerun export with `include_secrets` set to `true` and transfer the generated JSON as sensitive data.
### What should I consider when `include_secrets` is `true`?
The package can include sensitive runtime configuration such as API tool credentials, workflow/app DSL secret values, MCP server URLs, headers, authentication data, and MCP tool lists.
How to handle it:
- Store and transfer the JSON package as a secret.
- Delete the package after import if your security policy requires it.
- Prefer using this only for controlled one-time migrations where manual target-side credential setup is harder than securing the package.
### Should I use `preserve-id` or `generate-new-id`?
The ID strategy controls whether imported resources keep source IDs or receive new IDs in the target environment. It applies to workflow apps and custom tool resources where the target service supports explicit IDs.
Use `preserve-id` by default. It is recommended for cross-environment app migration because imported apps and tools try to keep their source IDs, which makes workflow references easier to preserve.
Use `preserve-id` when:
- You are migrating between environments that are meant to mirror each other, such as staging to production.
- You want workflow tool references and provider references to remain as stable as possible.
- The target environment does not already contain unrelated resources with the same IDs.
Watch out for:
- If the target already has a resource with the same ID, `conflict_strategy=fail` stops the import, `skip` keeps the target resource, and `update` updates it in place.
- If the same ID was reused for a different resource in the target environment, review carefully before using `update`.
Use `generate-new-id` when the target environment should keep its own local IDs.
Use `generate-new-id` when:
- The target environment already has resources that may conflict with source IDs.
- You are importing a package as a copy rather than trying to mirror environments.
- You want to avoid preserving source database IDs in the target environment.
Watch out for:
- Import records source-to-target ID mappings. Always review the import report's ID mappings.
- Workflow DSL provider references are rewritten using the generated ID mapping where possible.
- Dependencies that are metadata-only, such as MCP providers exported with `include_secrets=false`, still require manual target-side configuration.
- Built-in/plugin tools are not remapped as migrated custom resources; the target environment must provide them separately.
---
### De DE README (`docs/de-DE/README.md`)
Dify ist eine Open-Source-Plattform zur Entwicklung von LLM-Anwendungen. Ihre intuitive Benutzeroberfläche vereint agentenbasierte KI-Workflows, RAG-Pipelines, Agentenfunktionen, Modellverwaltung, Überwachungsfunktionen und mehr, sodass Sie schnell von einem Prototyp in die Produktion übergehen können.
## Schnellstart
> Bevor Sie Dify installieren, stellen Sie sicher, dass Ihr System die folgenden Mindestanforderungen erfüllt:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
Der einfachste Weg, den Dify-Server zu starten, ist über [docker compose](../../docker/docker-compose.yaml). Stellen Sie vor dem Ausführen von Dify mit den folgenden Befehlen sicher, dass [Docker](https://docs.docker.com/get-docker/) und [Docker Compose](https://docs.docker.com/compose/install/) auf Ihrem System installiert sind:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
Nachdem Sie den Server gestartet haben, können Sie über Ihren Browser auf das Dify Dashboard unter [http://localhost/install](http://localhost/install) zugreifen und den Initialisierungsprozess starten.
### Hilfe suchen
Bitte beachten Sie unsere [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs), wenn Sie Probleme bei der Einrichtung von Dify haben. Wenden Sie sich an [die Community und uns](#gemeinschaft--kontakt), falls weiterhin Schwierigkeiten auftreten.
> Wenn Sie zu Dify beitragen oder zusätzliche Entwicklungen durchführen möchten, lesen Sie bitte unseren [Leitfaden zur Bereitstellung aus dem Quellcode](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code).
## Wesentliche Merkmale
**1. Workflow**:
Erstellen und testen Sie leistungsstarke KI-Workflows auf einer visuellen Oberfläche, wobei Sie alle der folgenden Funktionen und darüber hinaus nutzen können.
**2. Umfassende Modellunterstützung**:
Nahtlose Integration mit Hunderten von proprietären und Open-Source-LLMs von Dutzenden Inferenzanbietern und selbstgehosteten Lösungen, die GPT, Mistral, Llama3 und alle mit der OpenAI API kompatiblen Modelle abdecken. Eine vollständige Liste der unterstützten Modellanbieter finden Sie [hier](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
Intuitive Benutzeroberfläche zum Erstellen von Prompts, zum Vergleichen der Modellleistung und zum Hinzufügen zusätzlicher Funktionen wie Text-to-Speech in einer chatbasierten Anwendung.
**4. RAG Pipeline**:
Umfassende RAG-Funktionalitäten, die alles von der Dokumenteneinlesung bis zur -abfrage abdecken, mit sofort einsatzbereiter Unterstützung für die Textextraktion aus PDFs, PPTs und anderen gängigen Dokumentformaten.
**5. Fähigkeiten des Agenten**:
Sie können Agenten basierend auf LLM Function Calling oder ReAct definieren und vorgefertigte oder benutzerdefinierte Tools für den Agenten hinzufügen. Dify stellt über 50 integrierte Tools für KI-Agenten bereit, wie zum Beispiel Google Search, DALL·E, Stable Diffusion und WolframAlpha.
**6. LLMOps**:
Überwachen und analysieren Sie Anwendungsprotokolle und die Leistung im Laufe der Zeit. Sie können kontinuierlich Prompts, Datensätze und Modelle basierend auf Produktionsdaten und Annotationen verbessern.
**7. Backend-as-a-Service**:
Alle Dify-Angebote kommen mit entsprechenden APIs, sodass Sie Dify mühelos in Ihre eigene Geschäftslogik integrieren können.
## Dify verwenden
- **Cloud **
Mit [Dify Cloud](https://cloud.dify.ai) können Sie Dify ohne eigenen Server ausprobieren. Aktuelle Tarife und Nutzungskontingente finden Sie auf der [Preisseite](https://dify.ai/pricing).
- **Selbstgehostete Dify Community Edition**
Starten Sie Dify schnell in Ihrer Umgebung mit diesem [Schnellstart-Leitfaden](#schnellstart). Nutzen Sie unsere [Dokumentation](https://docs.dify.ai) für weiterführende Informationen und detaillierte Anweisungen.
- **Dify für Unternehmen / Organisationen**
Wir bieten zusätzliche, unternehmensspezifische Funktionen. [Über diesen Chatbot können Sie uns Ihre Fragen mitteilen](https://udify.app/chat/22L1zSxg6yW1cWQg) oder [senden Sie uns eine E-Mail](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry), um Ihre unternehmerischen Bedürfnisse zu besprechen.
## Immer einen Schritt voraus
Star Dify auf GitHub und lassen Sie sich sofort über neue Releases benachrichtigen.
## Erweiterte Einstellungen
Optionen für benutzerdefinierte Konfiguration, Observability und Bereitstellung finden Sie unter [Erweiterte Einstellungen](ADVANCED_SETUP.md).
## Mitwirken
Dify freut sich über Beiträge jeder Art:
- **Code**: Lesen Sie den [Contribution Guide](./CONTRIBUTING.md) und stöbern Sie anschließend in den [Good First Issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideen und Feedback**: Starten Sie eine [GitHub-Diskussion](https://github.com/langgenius/dify/discussions) oder beteiligen Sie sich an einer bestehenden.
- **Übersetzungen**: Folgen Sie dem [Internationalisierungsleitfaden](https://github.com/langgenius/dify/blob/main/web/i18n/README.md), um eine Sprache hinzuzufügen oder zu aktualisieren.
- **Community**: Teilen Sie Ihre Apps, helfen Sie anderen Nutzern und machen Sie Dify bekannter.
### Mitwirkende
## Gemeinschaft & Kontakt
Wählen Sie den Kanal, der am besten zu Ihrem Anliegen passt:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Hilfe erhalten, Feedback teilen und Ideen vorschlagen.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Reproduzierbare Fehler melden und technische Arbeiten verfolgen. Lesen Sie vor dem Erstellen eines Issues den [Contribution Guide](./CONTRIBUTING.md).
- [Discord](https://discord.gg/FngNHpbcY7): In Echtzeit chatten, Apps teilen und sich mit anderen Dify-Nutzern austauschen.
- [X](https://x.com/dify_ai): Neuigkeiten zu Releases und Projekt-Updates verfolgen.
## Star-Geschichte
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Offenlegung der Sicherheit
Melden Sie Sicherheitslücken gemäß unserer [Sicherheitsrichtlinie](../../SECURITY.md) vertraulich über GitHub Security Advisories. Veröffentlichen Sie sie nicht in öffentlichen Issues, Diskussionen oder Pull Requests.
## Lizenz
Dieses Repository steht unter der [Dify Open Source License](../../LICENSE), die im Wesentlichen Apache 2.0 mit einigen zusätzlichen Einschränkungen ist.
---
### Es ES README (`docs/es-ES/README.md`)
Dify es una plataforma de desarrollo de aplicaciones de LLM de código abierto. Su interfaz intuitiva combina flujo de trabajo de IA, pipeline RAG, capacidades de agente, gestión de modelos, características de observabilidad y más, lo que le permite pasar rápidamente de un prototipo a producción. Aquí hay una lista de las características principales:
**1. Flujo de trabajo**:
Construye y prueba potentes flujos de trabajo de IA en un lienzo visual, aprovechando todas las siguientes características y más.
**2. Soporte de modelos completo**:
Integración perfecta con cientos de LLMs propietarios / de código abierto de docenas de proveedores de inferencia y soluciones auto-alojadas, que cubren GPT, Mistral, Llama3 y cualquier modelo compatible con la API de OpenAI. Se puede encontrar una lista completa de proveedores de modelos admitidos [aquí](https://docs.dify.ai/getting-started/readme/model-providers).
**3. IDE de prompt**:
Interfaz intuitiva para crear prompts, comparar el rendimiento del modelo y agregar características adicionales como texto a voz a una aplicación basada en chat.
**4. Pipeline RAG**:
Amplias capacidades de RAG que cubren todo, desde la ingestión de documentos hasta la recuperación, con soporte listo para usar para la extracción de texto de PDF, PPT y otros formatos de documento comunes.
**5. Capacidades de agente**:
Puedes definir agentes basados en LLM Function Calling o ReAct, y agregar herramientas preconstruidas o personalizadas para el agente. Dify proporciona más de 50 herramientas integradas para agentes de IA, como Búsqueda de Google, DALL·E, Difusión Estable y WolframAlpha.
**6. LLMOps**:
Supervisa y analiza registros de aplicaciones y rendimiento a lo largo del tiempo. Podrías mejorar continuamente prompts, conjuntos de datos y modelos basados en datos de producción y anotaciones.
**7. Backend como servicio**:
Todas las ofertas de Dify vienen con APIs correspondientes, por lo que podrías integrar Dify sin esfuerzo en tu propia lógica empresarial.
## Usando Dify
- **Nube **
Prueba [Dify Cloud](https://cloud.dify.ai) sin administrar un servidor. Consulta los planes y límites de uso actuales en la [página de precios](https://dify.ai/pricing).
- **Auto-alojamiento de Dify Community Edition**
Pon rápidamente Dify en funcionamiento en tu entorno con esta [guía de inicio rápido](#inicio-rápido).
Usa nuestra [documentación](https://docs.dify.ai) para más referencias e instrucciones más detalladas.
- **Dify para Empresas / Organizaciones**
Proporcionamos características adicionales centradas en la empresa. [Envíanos un correo electrónico](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) para discutir las necesidades empresariales.
## Manteniéndote al tanto
Dale estrella a Dify en GitHub y serás notificado instantáneamente de las nuevas versiones.
## Inicio Rápido
> Antes de instalar Dify, asegúrate de que tu máquina cumpla con los siguientes requisitos mínimos del sistema:
>
> - CPU >= 2 núcleos
> - RAM >= 4GB
La forma más fácil de iniciar el servidor de Dify es ejecutar nuestro archivo [docker-compose.yml](../../docker/docker-compose.yaml). Antes de ejecutar el comando de instalación, asegúrate de que [Docker](https://docs.docker.com/get-docker/) y [Docker Compose](https://docs.docker.com/compose/install/) estén instalados en tu máquina:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
Después de ejecutarlo, puedes acceder al panel de control de Dify en tu navegador en [http://localhost/install](http://localhost/install) y comenzar el proceso de inicialización.
> Si deseas contribuir a Dify o realizar desarrollo adicional, consulta nuestra [guía para implementar desde el código fuente](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## Próximos pasos
Para opciones de configuración personalizada, observabilidad y despliegue, consulta la [Configuración avanzada](ADVANCED_SETUP.md).
## Contribuir
Dify acepta contribuciones de todo tipo:
- **Código**: Lee la [Guía de contribución](./CONTRIBUTING.md) y consulta las [incidencias para principiantes](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideas y comentarios**: Inicia o únete a una [discusión en GitHub](https://github.com/langgenius/dify/discussions).
- **Traducciones**: Sigue la [guía de internacionalización](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) para añadir o actualizar un idioma.
- **Comunidad**: Comparte las aplicaciones que crees, ayuda a otros usuarios y da a conocer Dify.
### Contribuidores
## Comunidad y contacto
Elige el canal que mejor se adapte a tu consulta:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Obtén ayuda, comparte comentarios y propón ideas.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Informa de errores reproducibles y sigue el trabajo de ingeniería. Lee la [Guía de contribución](./CONTRIBUTING.md) antes de abrir una incidencia.
- [Discord](https://discord.gg/FngNHpbcY7): Chatea en tiempo real, comparte tus aplicaciones y conecta con otros usuarios de Dify.
- [X](https://x.com/dify_ai): Sigue las noticias de versiones y las actualizaciones del proyecto.
## Historial de Estrellas
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Divulgación de Seguridad
Informa de las vulnerabilidades en privado mediante GitHub Security Advisories, siguiendo nuestra [política de seguridad](../../SECURITY.md). No las divulgues en issues, debates ni pull requests públicos.
## Licencia
Este repositorio está disponible bajo la [Licencia de Código Abierto de Dify](../../LICENSE), que es esencialmente Apache 2.0 con algunas restricciones adicionales.
---
### Fr FR README (`docs/fr-FR/README.md`)
Dify est une plateforme de développement d'applications LLM open source. Sa interface intuitive combine un flux de travail d'IA, un pipeline RAG, des capacités d'agent, une gestion de modèles, des fonctionnalités d'observabilité, et plus encore, vous permettant de passer rapidement du prototype à la production. Voici une liste des fonctionnalités principales:
**1. Flux de travail** :
Construisez et testez des flux de travail d'IA puissants sur un canevas visuel, en utilisant toutes les fonctionnalités suivantes et plus encore.
**2. Prise en charge complète des modèles** :
Intégration transparente avec des centaines de LLM propriétaires / open source offerts par dizaines de fournisseurs d'inférence et de solutions auto-hébergées, couvrant GPT, Mistral, Llama3, et tous les modèles compatibles avec l'API OpenAI. Une liste complète des fournisseurs de modèles pris en charge se trouve [ici](https://docs.dify.ai/getting-started/readme/model-providers).
**3. IDE de prompt** :
Interface intuitive pour créer des prompts, comparer les performances des modèles et ajouter des fonctionnalités supplémentaires telles que la synthèse vocale à une application basée sur des chats.
**4. Pipeline RAG** :
Des capacités RAG étendues qui couvrent tout, de l'ingestion de documents à la récupération, avec un support prêt à l'emploi pour l'extraction de texte à partir de PDF, PPT et autres formats de document courants.
**5. Capacités d'agent** :
Vous pouvez définir des agents basés sur l'appel de fonctions LLM ou ReAct, et ajouter des outils pré-construits ou personnalisés pour l'agent. Dify fournit plus de 50 outils intégrés pour les agents d'IA, tels que la recherche Google, DALL·E, Stable Diffusion et WolframAlpha.
**6. LLMOps** :
Surveillez et analysez les journaux d'application et les performances au fil du temps. Vous pouvez continuellement améliorer les prompts, les ensembles de données et les modèles en fonction des données de production et des annotations.
**7. Backend-as-a-Service** :
Toutes les offres de Dify sont accompagnées d'API correspondantes, vous permettant d'intégrer facilement Dify dans votre propre logique métier.
## Utiliser Dify
- **Cloud **
Essayez [Dify Cloud](https://cloud.dify.ai) sans gérer de serveur. Consultez la [page des tarifs](https://dify.ai/pricing) pour les offres et quotas actuels.
- **Auto-hébergement Dify Community Edition**
Lancez rapidement Dify dans votre environnement avec ce [guide de démarrage](#démarrage-rapide).
Utilisez notre [documentation](https://docs.dify.ai) pour plus de références et des instructions plus détaillées.
- **Dify pour les entreprises / organisations**
Nous proposons des fonctionnalités supplémentaires adaptées aux entreprises. [Envoyez-nous un e-mail](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) pour discuter des besoins de l'entreprise.
## Rester en avance
Mettez une étoile à Dify sur GitHub et soyez instantanément informé des nouvelles versions.
## Démarrage rapide
> Avant d'installer Dify, assurez-vous que votre machine répond aux exigences système minimales suivantes:
>
> - CPU >= 2 cœurs
> - RAM >= 4 Go
La manière la plus simple de démarrer le serveur Dify est d'exécuter notre fichier [docker-compose.yml](../../docker/docker-compose.yaml). Avant d'exécuter la commande d'installation, assurez-vous que [Docker](https://docs.docker.com/get-docker/) et [Docker Compose](https://docs.docker.com/compose/install/) sont installés sur votre machine:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
Après l'exécution, vous pouvez accéder au tableau de bord Dify dans votre navigateur à [http://localhost/install](http://localhost/install) et commencer le processus d'initialisation.
> Si vous souhaitez contribuer à Dify ou effectuer un développement supplémentaire, consultez notre [guide de déploiement à partir du code source](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## Prochaines étapes
Pour les options de configuration personnalisée, d’observabilité et de déploiement, consultez la page [Configuration avancée](ADVANCED_SETUP.md).
## Contribuer
Dify accueille les contributions de toutes sortes :
- **Code** : consultez le [guide de contribution](./CONTRIBUTING.md), puis parcourez les [issues accessibles aux nouveaux contributeurs](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Idées et retours** : lancez ou rejoignez une [discussion GitHub](https://github.com/langgenius/dify/discussions).
- **Traductions** : suivez le [guide d’internationalisation](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) pour ajouter ou mettre à jour une langue.
- **Communauté** : partagez les applications que vous créez, aidez les autres utilisateurs et faites connaître Dify.
### Contributeurs
## Communauté et contact
Choisissez le canal le plus adapté à votre demande :
- [GitHub Discussions](https://github.com/langgenius/dify/discussions) : obtenez de l’aide, partagez vos retours et proposez des idées.
- [GitHub Issues](https://github.com/langgenius/dify/issues) : signalez des bogues reproductibles et suivez les travaux d’ingénierie. Consultez le [guide de contribution](./CONTRIBUTING.md) avant d’ouvrir une issue.
- [Discord](https://discord.gg/FngNHpbcY7) : échangez en temps réel, partagez vos applications et rencontrez d’autres utilisateurs de Dify.
- [X](https://x.com/dify_ai) : suivez les nouvelles versions et les actualités du projet.
## Historique des étoiles
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Divulgation de sécurité
Signalez les vulnérabilités en privé via GitHub Security Advisories, conformément à notre [politique de sécurité](../../SECURITY.md). Ne les divulguez pas dans les issues, discussions ou pull requests publiques.
## Licence
Ce référentiel est disponible sous la [Licence open source Dify](../../LICENSE), qui est essentiellement l'Apache 2.0 avec quelques restrictions supplémentaires.
---
### Hi IN README (`docs/hi-IN/README.md`)
Dify एक मुक्त-स्रोत प्लेटफ़ॉर्म है जो LLM अनुप्रयोगों (एप्लिकेशनों) के विकास के लिए बनाया गया है। इसका सहज इंटरफ़ेस एजेंटिक एआई वर्कफ़्लो, RAG पाइपलाइनों, एजेंट क्षमताओं, मॉडल प्रबंधन, ऑब्ज़र्वेबिलिटी (निगरानी) सुविधाओं और अन्य को एक साथ जोड़ता है — जिससे आप प्रोटोटाइप से उत्पादन (प्रोडक्शन) तक जल्दी पहुँच सकते हैं।
## त्वरित प्रारंभ
> Dify स्थापित करने से पहले, सुनिश्चित करें कि आपकी मशीन निम्नलिखित न्यूनतम सिस्टम आवश्यकताओं को पूरा करती है:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
Dify सर्वर शुरू करने का सबसे आसान तरीका [Docker Compose](../../docker/docker-compose.yaml) के माध्यम से है। नीचे दिए गए कमांड्स से Dify चलाने से पहले, सुनिश्चित करें कि आपकी मशीन पर [Docker] (https://docs.docker.com/get-docker/) और [Docker Compose] (https://docs.docker.com/compose/install/) इंस्टॉल हैं।:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
रन करने के बाद, आप अपने ब्राउज़र में [http://localhost/install](http://localhost/install) पर Dify डैशबोर्ड एक्सेस कर सकते हैं और प्रारंभिक सेटअप प्रक्रिया शुरू कर सकते हैं।
### सहायता प्राप्त करना
यदि आपको Dify सेटअप करते समय कोई समस्या आती है, तो कृपया हमारे [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs) को देखें। यदि फिर भी समस्या बनी रहती है, तो [the community and us](#समुदाय-और-संपर्क-community--contact) से संपर्क करें।
> यदि आप Dify में योगदान देना चाहते हैं या अतिरिक्त विकास करना चाहते हैं, तो हमारे [guide to deploying from source code](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code) को देखें।
## मुख्य विशेषताएँ
**1. वर्कफ़्लो**:\
एक दृश्य कैनवास पर शक्तिशाली एआई वर्कफ़्लो बनाएं और परीक्षण करें, नीचे दी गई सभी सुविधाओं और उससे भी आगे का उपयोग करते हुए।
**2. व्यापक मॉडल समर्थन**:\
कई इन्फ़रेंस प्रदाताओं और स्व-होस्टेड समाधानों से सैकड़ों स्वामित्व / मुक्त-स्रोत LLMs के साथ सहज एकीकरण, जिसमें GPT, Mistral, Llama3, और कोई भी OpenAI API-संगत मॉडल शामिल हैं। समर्थित मॉडल प्रदाताओं की पूरी सूची [here](https://docs.dify.ai/getting-started/readme/model-providers) पर पाई जा सकती है।
**3. प्रॉम्प्ट IDE**:\
प्रॉम्प्ट बनाने, मॉडल प्रदर्शन की तुलना करने, और चैट-आधारित ऐप में टेक्स्ट-टू-स्पीच जैसी अतिरिक्त सुविधाएँ जोड़ने के लिए सहज इंटरफ़ेस।
**4. RAG पाइपलाइन**:\
विस्तृत RAG क्षमताएँ जो दस्तावेज़ इनजेशन से लेकर रिट्रीवल तक सब कुछ कवर करती हैं, और PDFs, PPTs, तथा अन्य सामान्य दस्तावेज़ प्रारूपों से टेक्स्ट निकालने के लिए आउट-ऑफ़-द-बॉक्स समर्थन प्रदान करती हैं।
**5. एजेंट क्षमताएँ**:\
आप LLM फ़ंक्शन कॉलिंग या ReAct के आधार पर एजेंट परिभाषित कर सकते हैं, और एजेंट के लिए पूर्व-निर्मित या कस्टम टूल जोड़ सकते हैं। Dify एआई एजेंटों के लिए 50+ अंतर्निर्मित टूल प्रदान करता है, जैसे Google Search, DALL·E, Stable Diffusion और WolframAlpha।
**6. LLMOps**:\
समय के साथ एप्लिकेशन लॉग्स और प्रदर्शन की निगरानी और विश्लेषण करें। आप उत्पादन डेटा और एनोटेशनों के आधार पर प्रॉम्प्ट्स, डेटासेट्स और मॉडल्स को निरंतर सुधार सकते हैं।
**7. Backend-as-a-Service**:\
Dify की सभी सेवाएँ संबंधित APIs के साथ आती हैं, जिससे आप Dify को आसानी से अपने व्यावसायिक लॉजिक में एकीकृत कर सकते हैं।
## Dify का उपयोग करना
- **Cloud **\
सर्वर का प्रबंधन किए बिना [Dify Cloud](https://cloud.dify.ai) पर Dify आज़माएँ। मौजूदा योजनाओं और उपयोग सीमाओं के लिए [मूल्य निर्धारण पृष्ठ](https://dify.ai/pricing) देखें।
- **Dify कम्युनिटी संस्करण की स्व-होस्टिंग **\
अपने वातावरण में Dify को जल्दी चलाएँ इस [starter guide](#त्वरित-प्रारंभ) की मदद से।\
आगे के संदर्भों और विस्तृत निर्देशों के लिए हमारी [documentation](https://docs.dify.ai) देखें।
- **उद्यमों / संगठनों के लिए Dify **\
हम अतिरिक्त एंटरप्राइज़-केंद्रित सुविधाएँ प्रदान करते हैं।\
[इस चैटबॉट के माध्यम से हमें अपने प्रश्न भेजें](https://udify.app/chat/22L1zSxg6yW1cWQg) या [हमें ईमेल भेजें](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) ताकि हम एंटरप्राइज़ आवश्यकताओं पर चर्चा कर सकें।
## आगे बने रहें
GitHub पर Dify को स्टार करें और नए रिलीज़ की सूचना तुरंत प्राप्त करें।
## उन्नत सेटअप
कस्टम कॉन्फ़िगरेशन, ऑब्ज़र्वेबिलिटी और डिप्लॉयमेंट विकल्पों के लिए, [उन्नत सेटअप](ADVANCED_SETUP.md) देखें।
## योगदान (Contributing)
Dify सभी प्रकार के योगदानों का स्वागत करता है:
- **कोड**: [Contribution Guide](./CONTRIBUTING.md) पढ़ें, फिर [नए योगदानकर्ताओं के लिए उपयुक्त issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) देखें।
- **विचार और प्रतिक्रिया**: [GitHub Discussion](https://github.com/langgenius/dify/discussions) शुरू करें या किसी मौजूदा चर्चा में शामिल हों।
- **अनुवाद**: किसी locale को जोड़ने या अपडेट करने के लिए [internationalization guide](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) का पालन करें।
- **समुदाय**: अपने बनाए हुए ऐप साझा करें, अन्य उपयोगकर्ताओं की मदद करें और Dify के बारे में लोगों को बताएं।
### योगदानकर्ता
## समुदाय और संपर्क (Community & contact)
अपने प्रश्न के लिए सबसे उपयुक्त माध्यम चुनें:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): सहायता प्राप्त करें, प्रतिक्रिया साझा करें और विचार सुझाएँ।
- [GitHub Issues](https://github.com/langgenius/dify/issues): दोहराए जा सकने वाले bugs की रिपोर्ट करें और engineering work को ट्रैक करें। Issue खोलने से पहले [Contribution Guide](./CONTRIBUTING.md) पढ़ें।
- [Discord](https://discord.gg/FngNHpbcY7): रीयल टाइम में बातचीत करें, अपने ऐप साझा करें और अन्य Dify उपयोगकर्ताओं से जुड़ें।
- [X](https://x.com/dify_ai): रिलीज़ समाचार और प्रोजेक्ट अपडेट के लिए Dify को फ़ॉलो करें।
## स्टार इतिहास (Star history)
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## सुरक्षा प्रकटीकरण (Security disclosure)
हमारी [सुरक्षा नीति](../../SECURITY.md) के अनुसार GitHub Security Advisories के ज़रिए निजी तौर पर सुरक्षा खामियों की रिपोर्ट करें। उन्हें सार्वजनिक issues, चर्चाओं या pull requests में उजागर न करें।
## लाइसेंस (License)
यह रिपॉज़िटरी [Dify Open Source License](../../LICENSE) के अंतर्गत लाइसेंस प्राप्त है, जो Apache 2.0 पर आधारित है और इसमें अतिरिक्त शर्तें शामिल हैं।
---
### Id ID README (`docs/id-ID/README.md`)
Dify adalah platform pengembangan aplikasi *Large Language Model* (LLM) sumber terbuka (*open-source*). Antarmukanya yang intuitif menggabungkan *AI workflow*, *pipeline RAG*, kapabilitas agen otonom, manajemen model, fitur observabilitas (termasuk [Opik](https://www.comet.com/docs/opik/integrations/dify), [Langfuse](https://docs.langfuse.com), dan [Arize Phoenix](https://docs.arize.com/phoenix)), dan masih banyak lagi—memungkinkan Anda beralih dari tahap purwarupa (*prototype*) ke produksi dengan cepat.
Berikut daftar fitur utamanya:
## Mulai Cepat (Quick start)
> Sebelum menginstal Dify, pastikan sistem komputer atau server Anda memenuhi spesifikasi minimum berikut:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
Cara termudah untuk menjalankan server Dify adalah menggunakan [Docker Compose](../../docker/docker-compose.yaml). Sebelum menjalankan perintah berikut, pastikan [Docker](https://docs.docker.com/get-docker/) dan Docker Compose versi v2.24.0 atau yang lebih baru telah terpasang:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
Setelah berjalan, Anda dapat mengakses dashboard Dify melalui peramban web di [http://localhost/install](http://localhost/install) untuk memulai proses inisialisasi awal.
### Bantuan & FAQ
Silakan merujuk ke [FAQ kami](https://docs.dify.ai/getting-started/install-self-hosted/faqs) jika menemui kendala saat pemasangan Dify. Hubungi [komunitas kami](#komunitas--kontak) jika Anda membutuhkan bantuan lebih lanjut.
> Jika ingin berkontribusi pada pengembangan kode Dify, pelajari [panduan instalasi dari source code](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code).
## Fitur Utama
**1. Workflow Visual**:
Rancang dan uji alur kerja AI yang kuat di atas kanvas visual, memanfaatkan seluruh integrasi fitur secara menyeluruh.
**2. Dukungan Model Komprehensif**:
Integrasi mulus dengan ratusan model LLM komersial maupun open-source dari puluhan penyedia inferensi dan solusi *self-hosted*, meliputi GPT, Mistral, Llama 3, serta semua model yang kompatibel dengan OpenAI API. Daftar lengkap penyedia model dapat dilihat [di sini](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
Antarmuka intuitif untuk meracik *prompt*, membandingkan performa berbagai model secara berdampingan, dan menambahkan fitur interaktif seperti *text-to-speech* ke dalam aplikasi obrolan.
**4. Pipeline RAG (Retrieval-Augmented Generation)**:
Kemampuan RAG lengkap mulai dari ingest dokumen hingga pencarian semantik, dilengkapi dukungan bawaan untuk ekstraksi teks dari PDF, dokumen presentasi PPT, dan berbagai format berkas populer lainnya.
**5. Autonomous Agent**:
Agen mandiri yang beroperasi dalam lingkungan *sandbox* terisolasi: mereka mampu menjalankan perintah, memasang pustaka perangkat lunak, dan memproses dokumen untuk menyelesaikan tugas yang dinamis. Deskripsikan agen yang Anda butuhkan, dan ia akan menyusun dirinya sendiri. Hubungkan alat dari [Dify Marketplace](https://marketplace.dify.ai/?category=tool), server MCP, atau API kustom Anda, lalu terapkan sebagai aplikasi obrolan cerdas atau sebagai langkah otomatis dalam workflow.
**6. LLMOps**:
Pantau dan analisis log riwayat aplikasi serta metrik performanya secara berkala. Anda dapat terus menyempurnakan prompt, dataset, dan model berdasarkan data penggunaan produksi nyata serta anotasi kualitas.
**7. Backend-as-a-Service (BaaS)**:
Seluruh kapabilitas Dify disertai API yang lengkap dan terdokumentasi rapi, memudahkan integrasi fungsionalitas AI ke dalam logika aplikasi backend Anda yang sudah ada.
## Pilihan Penerapan Dify
- **Dify Cloud **
Coba [Dify Cloud](https://cloud.dify.ai) tanpa mengelola server. Lihat paket dan kuota penggunaan terkini di [halaman harga](https://dify.ai/pricing). Jika ada kendala, [hubungi tim dukungan Cloud kami](mailto:cloud@dify.ai?subject=%5BGitHub%5DDify%20Cloud%20Support).
- **Self-hosting Dify Community Edition **
Jalankan Dify langsung di infrastruktur server mandiri Anda dengan [panduan mulai cepat](#mulai-cepat-quick-start).
Lihat [dokumentasi resmi kami](https://docs.dify.ai) untuk referensi konfigurasi mendalam.
- **[Dify Enterprise](https://dify.ai/dify-enterprise) **
Bagi korporasi atau instansi yang memerlukan dukungan *self-hosting enterprise*, integrasi SSO, keamanan berbasis peran (RBAC), dan SLA dukungan resmi, silakan isi [formulir ini](https://share-na2.hsforms.com/14-09ff5HS92Sh4m3f4yrcw40s9fk) untuk berdiskusi dengan tim representatif kami.
## Tetap Terhubung & Update Terbaru
Berikan bintang (*star*) pada repositori Dify di GitHub untuk mendapatkan pemberitahuan pembaruan versi terbaru:
## Konfigurasi Tingkat Lanjut
Untuk konfigurasi kustom, observabilitas mendalam, dan opsi deployment tingkat lanjut, lihat [Advanced Setup](../../docs/ADVANCED_SETUP.md).
## Berkontribusi
Dify menyambut segala bentuk kontribusi dari komunitas:
- **Kode**: Pelajari [Panduan Kontribusi](../../CONTRIBUTING.md), lalu telusuri daftar [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ide & Masukan**: Mulai diskusi di [GitHub Discussions](https://github.com/langgenius/dify/discussions).
- **Terjemahan (i18n)**: Ikuti [panduan internasionalisasi](../../web/i18n/README.md) untuk memperbarui atau menambahkan bahasa baru.
- **Komunitas**: Bagikan aplikasi yang Anda bangun, bantu sesama pengembang, dan sebarkan informasi tentang Dify.
### Kontributor
## Komunitas & Kontak
Pilih saluran komunikasi resmi yang paling relevan:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Diskusi umum, masukan fitur, dan tanya jawab.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Laporan bug yang dapat direproduksi dan pelacakan fitur teknis. Baca [Panduan Kontribusi](../../CONTRIBUTING.md) sebelum membuka issue baru.
- [Discord](https://discord.gg/FngNHpbcY7): Diskusi interaktif langsung, bertukar proyek aplikasi AI, dan berjejaring dengan pengguna Dify di seluruh dunia.
- [X (Twitter)](https://x.com/dify_ai): Berita rilis fitur dan pengumuman resmi.
## Riwayat Bintang (Star History)
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Kebijakan Pelaporan Kerentanan Keamanan
Laporkan kerentanan secara privat melalui GitHub Security Advisories sesuai [kebijakan keamanan](../../SECURITY.md). Jangan mengungkapkannya dalam issue, diskusi, atau pull request publik.
## Lisensi
Repositori ini dilisensikan di bawah [Dify Open Source License](../../LICENSE), berbasiskan Apache 2.0 dengan beberapa ketentuan tambahan.
---
### It IT README (`docs/it-IT/README.md`)
Dify è una piattaforma open-source per lo sviluppo di applicazioni LLM. La sua interfaccia intuitiva combina flussi di lavoro AI basati su agenti, pipeline RAG, funzionalità di agenti, gestione dei modelli, funzionalità di monitoraggio e altro ancora, permettendovi di passare rapidamente da un prototipo alla produzione.
## Avvio Rapido
> Prima di installare Dify, assicuratevi che il vostro sistema soddisfi i seguenti requisiti minimi:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
Il modo più semplice per avviare il server Dify è tramite [docker compose](../../docker/docker-compose.yaml). Prima di eseguire Dify con i seguenti comandi, assicuratevi che [Docker](https://docs.docker.com/get-docker/) e [Docker Compose](https://docs.docker.com/compose/install/) siano installati sul vostro sistema:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
Dopo aver avviato il server, potete accedere al dashboard di Dify tramite il vostro browser all'indirizzo [http://localhost/install](http://localhost/install) e avviare il processo di inizializzazione.
### Richiedere Aiuto
Consultate le nostre [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs) se riscontrate problemi durante la configurazione di Dify. Contattateci [tramite la community](#community-e-contatti) se continuano a verificarsi difficoltà.
> Se desiderate contribuire a Dify o effettuare ulteriori sviluppi, consultate la nostra [guida al deployment dal codice sorgente](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code).
## Caratteristiche Principali
**1. Workflow**:
Create e testate potenti flussi di lavoro AI su un'interfaccia visuale, utilizzando tutte le funzionalità seguenti e oltre.
**2. Supporto Completo dei Modelli**:
Integrazione perfetta con centinaia di LLM proprietari e open-source di decine di provider di inferenza e soluzioni self-hosted, che coprono GPT, Mistral, Llama3 e tutti i modelli compatibili con l'API OpenAI. L'elenco completo dei provider di modelli supportati è disponibile [qui](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
Interfaccia intuitiva per creare prompt, confrontare le prestazioni dei modelli e aggiungere funzionalità aggiuntive come text-to-speech in un'applicazione basata su chat.
**4. Pipeline RAG**:
Funzionalità RAG complete che coprono tutto, dall'acquisizione dei documenti alla loro interrogazione, con supporto pronto all'uso per l'estrazione di testo da PDF, PPT e altri formati di documenti comuni.
**5. Capacità degli Agenti**:
Potete definire agenti basati su LLM Function Calling o ReAct e aggiungere strumenti predefiniti o personalizzati per l'agente. Dify fornisce oltre 50 strumenti integrati per gli agenti AI, come Google Search, DALL·E, Stable Diffusion e WolframAlpha.
**6. LLMOps**:
Monitorate e analizzate i log delle applicazioni e le prestazioni nel tempo. Potete migliorare continuamente prompt, dataset e modelli basandovi sui dati di produzione e sulle annotazioni.
**7. Backend-as-a-Service**:
Tutte le offerte di Dify sono dotate di API corrispondenti, permettendovi di integrare facilmente Dify nella vostra logica di business.
## Utilizzo di Dify
- **Cloud **
Prova [Dify Cloud](https://cloud.dify.ai) senza gestire un server. Consulta la [pagina dei prezzi](https://dify.ai/pricing) per i piani e i limiti di utilizzo attuali.
- **Dify Community Edition Self-Hosted **
Avviate rapidamente Dify nel vostro ambiente con questa [guida di avvio rapido](#avvio-rapido). Utilizzate la nostra [documentazione](https://docs.dify.ai) per ulteriori informazioni e istruzioni dettagliate.
- **Dify per Aziende / Organizzazioni **
Offriamo funzionalità aggiuntive specifiche per le aziende. Potete [scriverci via email](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) per discutere le vostre esigenze aziendali.
## Resta Sempre Aggiornato
Mettete una stella a Dify su GitHub e ricevete notifiche immediate sui nuovi rilasci.
## Configurazioni Avanzate
Per le opzioni di configurazione personalizzata, osservabilità e distribuzione, consulta le [Configurazioni avanzate](ADVANCED_SETUP.md).
## Contribuire
Dify accoglie contributi di ogni tipo:
- **Codice**: leggi la [Guida ai contributi](../../CONTRIBUTING.md), quindi consulta le [issue adatte ai nuovi contributori](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Idee e feedback**: avvia o partecipa a una [discussione su GitHub](https://github.com/langgenius/dify/discussions).
- **Traduzioni**: segui la [guida all’internazionalizzazione](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) per aggiungere o aggiornare una lingua.
- **Community**: condividi le app che crei, aiuta gli altri utenti e fai conoscere Dify.
### Collaboratori
## Community e contatti
Scegli il canale più adatto alla tua richiesta:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): ricevi assistenza, condividi feedback e proponi idee.
- [GitHub Issues](https://github.com/langgenius/dify/issues): segnala bug riproducibili e segui il lavoro di sviluppo. Leggi la [Guida ai contributi](../../CONTRIBUTING.md) prima di aprire una issue.
- [Discord](https://discord.gg/FngNHpbcY7): chatta in tempo reale, condividi le tue app e incontra altri utenti Dify.
- [X](https://x.com/dify_ai): segui le notizie sulle release e gli aggiornamenti del progetto.
## Storia delle Stelle
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Divulgazione sulla Sicurezza
Segnala le vulnerabilità in privato tramite GitHub Security Advisories, seguendo la nostra [politica di sicurezza](../../SECURITY.md). Non divulgarle in issue, discussioni o pull request pubbliche.
## Licenza
Questo repository è disponibile sotto la [Dify Open Source License](../../LICENSE), che è essenzialmente Apache 2.0 con alcune restrizioni aggiuntive.
---
### Ja JP README (`docs/ja-JP/README.md`)
Dify는 오픈 소스 LLM 앱 개발 플랫폼입니다. 직관적인 인터페이스를 통해 AI 워크플로우, RAG 파이프라인, 에이전트 기능, 모델 관리, 관찰 기능 등을 결합하여 프로토타입에서 프로덕션까지 빠르게 전환할 수 있습니다. 주요 기능 목록은 다음과 같습니다:
**1. 워크플로우**:
다음 기능들을 비롯한 다양한 기능을 활용하여 시각적 캔버스에서 강력한 AI 워크플로우를 구축하고 테스트하세요.
**2. 포괄적인 모델 지원:**:
수십 개의 추론 제공업체와 자체 호스팅 솔루션에서 제공하는 수백 개의 독점 및 오픈 소스 LLM과 원활하게 통합되며, GPT, Mistral, Llama3 및 모든 OpenAI API 호환 모델을 포함합니다. 지원되는 모델 제공업체의 전체 목록은 [여기](https://docs.dify.ai/getting-started/readme/model-providers)에서 확인할 수 있습니다.
**3. 통합 개발환경**:
프롬프트를 작성하고, 모델 성능을 비교하며, 텍스트-음성 변환과 같은 추가 기능을 채팅 기반 앱에 추가할 수 있는 직관적인 인터페이스를 제공합니다.
**4. RAG 파이프라인**:
문서 수집부터 검색까지 모든 것을 다루며, PDF, PPT 및 기타 일반적인 문서 형식에서 텍스트 추출을 위한 기본 지원이 포함되어 있는 광범위한 RAG 기능을 제공합니다.
**5. 에이전트 기능**:
LLM 함수 호출 또는 ReAct를 기반으로 에이전트를 정의하고 에이전트에 대해 사전 구축된 도구나 사용자 정의 도구를 추가할 수 있습니다. Dify는 Google Search, DALL·E, Stable Diffusion, WolframAlpha 등 AI 에이전트를 위한 50개 이상의 내장 도구를 제공합니다.
**6. LLMOps**:
시간 경과에 따른 애플리케이션 로그와 성능을 모니터링하고 분석합니다. 생산 데이터와 주석을 기반으로 프롬프트, 데이터세트, 모델을 지속적으로 개선할 수 있습니다.
**7. Backend-as-a-Service**:
Dify의 모든 제품에는 해당 API가 함께 제공되므로 Dify를 자신의 비즈니스 로직에 쉽게 통합할 수 있습니다.
## Dify 사용하기
- **클라우드 **
[Dify Cloud](https://cloud.dify.ai)를 통해 서버를 관리하지 않고 Dify를 사용할 수 있습니다. 최신 요금제와 사용 한도는 [요금 안내](https://dify.ai/pricing)를 확인하세요.
- **셀프-호스팅 Dify 커뮤니티 에디션**
환경에서 Dify를 빠르게 실행하려면 이 [스타터 가이드를](#빠른-시작) 참조하세요.
추가 참조 및 더 심층적인 지침은 [문서](https://docs.dify.ai)를 사용하세요.
- **기업 / 조직을 위한 Dify**
우리는 추가적인 기업 중심 기능을 제공합니다. 잡거나 [이메일 보내기](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry)를 통해 기업 요구 사항을 논의하십시오.
## 앞서가기
GitHub에서 Dify에 별표를 찍어 새로운 릴리스를 즉시 알림 받으세요.
## 빠른 시작
> Dify를 설치하기 전에 컴퓨터가 다음과 같은 최소 시스템 요구 사항을 충족하는지 확인하세요 :
>
> - CPU >= 2 Core
> - RAM >= 4GB
Dify 서버를 시작하는 가장 쉬운 방법은 [docker-compose.yml](../../docker/docker-compose.yaml) 파일을 실행하는 것입니다. 설치 명령을 실행하기 전에 [Docker](https://docs.docker.com/get-docker/) 및 [Docker Compose](https://docs.docker.com/compose/install/)가 머신에 설치되어 있는지 확인하세요.
```bash
cd docker
cp .env.example .env
docker compose up -d
```
실행 후 브라우저의 [http://localhost/install](http://localhost/install) 에서 Dify 대시보드에 액세스하고 초기화 프로세스를 시작할 수 있습니다.
> Dify에 기여하거나 추가 개발을 하고 싶다면 소스 코드에서 [배포에 대한 가이드](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)를 참조하세요.
## 다음 단계
사용자 지정 구성, 관측 가능성 및 배포 옵션은 [고급 설정](ADVANCED_SETUP.md)을 참조하세요.
## 기여
Dify는 모든 형태의 기여를 환영합니다.
- **코드**: [기여 가이드](./CONTRIBUTING.md)를 읽고 [good first issue](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)를 살펴보세요.
- **아이디어 및 피드백**: [GitHub 토론](https://github.com/langgenius/dify/discussions)을 시작하거나 기존 토론에 참여하세요.
- **번역**: 언어를 추가하거나 업데이트하려면 [국제화 가이드](https://github.com/langgenius/dify/blob/main/web/i18n/README.md)를 따르세요.
- **커뮤니티**: 만든 앱을 공유하고, 다른 사용자를 돕고, Dify를 널리 알려주세요.
### 기여자
## 커뮤니티 & 연락처
문의 내용에 가장 적합한 채널을 선택하세요.
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): 도움을 받고, 피드백을 공유하고, 아이디어를 제안하세요.
- [GitHub Issues](https://github.com/langgenius/dify/issues): 재현 가능한 버그를 보고하고 개발 작업을 추적하세요. 이슈를 열기 전에 [기여 가이드](./CONTRIBUTING.md)를 읽어주세요.
- [Discord](https://discord.gg/FngNHpbcY7): 실시간으로 대화하고, 앱을 공유하고, 다른 Dify 사용자와 교류하세요.
- [X](https://x.com/dify_ai): 릴리스 소식과 프로젝트 업데이트를 확인하세요.
## Star 히스토리
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## 보안 공개
[보안 정책](../../SECURITY.md)에 따라 GitHub Security Advisories를 통해 취약점을 비공개로 보고하세요. 공개 이슈, 토론 또는 PR에 공개하지 마세요.
## 라이선스
이 저장소는 기본적으로 몇 가지 추가 제한 사항이 있는 Apache 2.0인 [Dify 오픈 소스 라이선스](../../LICENSE)에 따라 사용할 수 있습니다.
---
### Pt BR README (`docs/pt-BR/README.md`)
Dify é uma plataforma de desenvolvimento de aplicativos LLM de código aberto. Sua interface intuitiva combina workflow de IA, pipeline RAG, capacidades de agente, gerenciamento de modelos, recursos de observabilidade e muito mais, permitindo que você vá rapidamente do protótipo à produção. Aqui está uma lista das principais funcionalidades:
**1. Workflow**:
Construa e teste workflows poderosos de IA em uma interface visual, aproveitando todos os recursos a seguir e muito mais.
**2. Suporte abrangente a modelos**:
Integração perfeita com centenas de LLMs proprietários e de código aberto de diversas provedoras e soluções auto-hospedadas, abrangendo GPT, Mistral, Llama3 e qualquer modelo compatível com a API da OpenAI. A lista completa de provedores suportados pode ser encontrada [aqui](https://docs.dify.ai/getting-started/readme/model-providers).
**3. IDE de Prompt**:
Interface intuitiva para criação de prompts, comparação de desempenho de modelos e adição de recursos como conversão de texto para fala em um aplicativo baseado em chat.
**4. Pipeline RAG**:
Extensas capacidades de RAG que cobrem desde a ingestão de documentos até a recuperação, com suporte nativo para extração de texto de PDFs, PPTs e outros formatos de documentos comuns.
**5. Capacidades de agente**:
Você pode definir agentes com base em LLM Function Calling ou ReAct e adicionar ferramentas pré-construídas ou personalizadas para o agente. O Dify oferece mais de 50 ferramentas integradas para agentes de IA, como Google Search, DALL·E, Stable Diffusion e WolframAlpha.
**6. LLMOps**:
Monitore e analise os registros e o desempenho do aplicativo ao longo do tempo. É possível melhorar continuamente prompts, conjuntos de dados e modelos com base nos dados de produção e anotações.
**7. Backend como Serviço**:
Todas os recursos do Dify vêm com APIs correspondentes, permitindo que você integre o Dify sem esforço na lógica de negócios da sua empresa.
## Usando o Dify
- **Nuvem **
Experimente o [Dify Cloud](https://cloud.dify.ai) sem gerenciar um servidor. Consulte os planos e limites de uso atuais na [página de preços](https://dify.ai/pricing).
- **Auto-hospedagem do Dify Community Edition**
Configure rapidamente o Dify no seu ambiente com este [guia inicial](#início-rápido).
Use nossa [documentação](https://docs.dify.ai) para referências adicionais e instruções mais detalhadas.
- **Dify para empresas/organizações**
Oferecemos recursos adicionais voltados para empresas. Você pode [falar conosco por e-mail](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) para discutir necessidades empresariais.
## Mantendo-se atualizado
Dê uma estrela no Dify no GitHub e seja notificado imediatamente sobre novos lançamentos.
## Início rápido
> Antes de instalar o Dify, certifique-se de que sua máquina atenda aos seguintes requisitos mínimos de sistema:
>
> - CPU >= 2 Núcleos
> - RAM >= 4 GiB
A maneira mais fácil de iniciar o servidor Dify é executar nosso arquivo [docker-compose.yml](../../docker/docker-compose.yaml). Antes de rodar o comando de instalação, certifique-se de que o [Docker](https://docs.docker.com/get-docker/) e o [Docker Compose](https://docs.docker.com/compose/install/) estão instalados na sua máquina:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
Após a execução, você pode acessar o painel do Dify no navegador em [http://localhost/install](http://localhost/install) e iniciar o processo de inicialização.
> Se você deseja contribuir com o Dify ou fazer desenvolvimento adicional, consulte nosso [guia para implantar a partir do código fonte](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code).
## Próximos passos
Para opções de configuração personalizada, observabilidade e implantação, consulte a [Configuração avançada](ADVANCED_SETUP.md).
## Contribuindo
O Dify aceita contribuições de todos os tipos:
- **Código**: leia o [Guia de Contribuição](./CONTRIBUTING.md) e consulte as [issues para iniciantes](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideias e feedback**: inicie ou participe de uma [discussão no GitHub](https://github.com/langgenius/dify/discussions).
- **Traduções**: siga o [guia de internacionalização](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) para adicionar ou atualizar um idioma.
- **Comunidade**: compartilhe os aplicativos que você criar, ajude outros usuários e divulgue o Dify.
### Contribuidores
## Comunidade e contato
Escolha o canal mais adequado para a sua dúvida:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): obtenha ajuda, compartilhe feedback e proponha ideias.
- [GitHub Issues](https://github.com/langgenius/dify/issues): relate bugs reproduzíveis e acompanhe o trabalho de engenharia. Leia o [Guia de Contribuição](./CONTRIBUTING.md) antes de abrir uma issue.
- [Discord](https://discord.gg/FngNHpbcY7): converse em tempo real, compartilhe seus aplicativos e conecte-se com outros usuários do Dify.
- [X](https://x.com/dify_ai): acompanhe notícias de versões e atualizações do projeto.
## Histórico de estrelas
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Divulgação de segurança
Relate vulnerabilidades em particular pelo GitHub Security Advisories, seguindo nossa [política de segurança](../../SECURITY.md). Não as divulgue em issues, discussões ou pull requests públicos.
## Licença
Este repositório está disponível sob a [Licença de Código Aberto Dify](../../LICENSE), que é essencialmente Apache 2.0 com algumas restrições adicionais.
---
### Sl SI README (`docs/sl-SI/README.md`)
Dify je odprtokodna platforma za razvoj aplikacij LLM. Njegov intuitivni vmesnik združuje agentski potek dela z umetno inteligenco, cevovod RAG, zmogljivosti agentov, upravljanje modelov, funkcije opazovanja in več, kar vam omogoča hiter prehod od prototipa do proizvodnje.
## Hitri začetek
> Preden namestite Dify, se prepričajte, da vaša naprava izpolnjuje naslednje minimalne sistemske zahteve:
>
> - CPU >= 2 Core
> - RAM >= 4 GiB
Najlažji način za zagon strežnika Dify je prek docker compose . Preden zaženete Dify z naslednjimi ukazi, se prepričajte, da sta Docker in Docker Compose nameščena na vašem računalniku:
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
Po zagonu lahko dostopate do nadzorne plošče Dify v brskalniku na [http://localhost/install](http://localhost/install) in začnete postopek inicializacije.
### Iskanje pomoči
Prosimo, glejte naša pogosta vprašanja [FAQ](https://docs.dify.ai/getting-started/install-self-hosted/faqs) če naletite na težave pri nastavitvi Dify. Če imate še vedno težave, se obrnite na [skupnost ali nas](#skupnost-in-stik).
> Če želite prispevati k Difyju ali narediti dodaten razvoj, glejte naš vodnik za [uvajanje iz izvorne kode](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## Ključne značilnosti
**1. Potek dela**:
Zgradite in preizkusite zmogljive poteke dela AI na vizualnem platnu, pri čemer izkoristite vse naslednje funkcije in več.
**2. Celovita podpora za modele**:
Brezhibna integracija s stotinami lastniških/odprtokodnih LLM-jev ducatov ponudnikov sklepanja in samostojnih rešitev, ki pokrivajo GPT, Mistral, Llama3 in vse modele, združljive z API-jem OpenAI. Celoten seznam podprtih ponudnikov modelov najdete [tukaj](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
intuitivni vmesnik za ustvarjanje pozivov, primerjavo zmogljivosti modela in dodajanje dodatnih funkcij, kot je pretvorba besedila v govor, aplikaciji, ki temelji na klepetu.
**4. RAG Pipeline**:
E Obsežne zmogljivosti RAG, ki pokrivajo vse od vnosa dokumenta do priklica, s podporo za ekstrakcijo besedila iz datotek PDF, PPT in drugih običajnih formatov dokumentov.
**5. Agent capabilities**:
definirate lahko agente, ki temeljijo na klicanju funkcij LLM ali ReAct, in dodate vnaprej izdelana orodja ali orodja po meri za agenta. Dify ponuja več kot 50 vgrajenih orodij za agente AI, kot so Google Search, DALL·E, Stable Diffusion in WolframAlpha.
**6. LLMOps**:
Spremljajte in analizirajte dnevnike aplikacij in učinkovitost skozi čas. Pozive, nabore podatkov in modele lahko nenehno izboljšujete na podlagi proizvodnih podatkov in opomb.
**7. Backend-as-a-Service**:
AVse ponudbe Difyja so opremljene z ustreznimi API-ji, tako da lahko Dify brez težav integrirate v svojo poslovno logiko.
## Uporaba Dify
- **Cloud **
Preizkusite [Dify Cloud](https://cloud.dify.ai) brez upravljanja strežnika. Trenutne pakete in omejitve uporabe najdete na [strani s cenami](https://dify.ai/pricing).
- **Self-hosting Dify Community Edition**
Hitro zaženite Dify v svojem okolju s tem [začetnim vodnikom](#hitri-začetek) . Za dodatne reference in podrobnejša navodila uporabite našo [dokumentacijo](https://docs.dify.ai) .
- **Dify za podjetja/organizacije**
Ponujamo dodatne funkcije, osredotočene na podjetja. Zabeležite svoja vprašanja prek tega klepetalnega robota ali nam pošljite e-pošto, da se pogovorimo o potrebah podjetja.
## Staying ahead
Star Dify on GitHub and be instantly notified of new releases.
## Napredne nastavitve
Za možnosti konfiguracije po meri, opazovanja in namestitve glejte [Napredne nastavitve](ADVANCED_SETUP.md).
## Prispevanje
Dify pozdravlja vse vrste prispevkov:
- **Koda**: preberite [vodnik za prispevke](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md), nato pa preglejte [naloge za nove sodelavce](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideje in povratne informacije**: začnite ali se pridružite [razpravi na GitHubu](https://github.com/langgenius/dify/discussions).
- **Prevodi**: sledite [vodniku za internacionalizacijo](https://github.com/langgenius/dify/blob/main/web/i18n/README.md), da dodate ali posodobite jezik.
- **Skupnost**: delite ustvarjene aplikacije, pomagajte drugim uporabnikom in razširite glas o Difyju.
### Sodelavci
## Skupnost in stik
Izberite kanal, ki najbolj ustreza vašemu vprašanju:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): poiščite pomoč, delite povratne informacije in predlagajte ideje.
- [GitHub Issues](https://github.com/langgenius/dify/issues): prijavite ponovljive napake in spremljajte razvojno delo. Pred odprtjem težave preberite [vodnik za prispevke](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md).
- [Discord](https://discord.gg/FngNHpbcY7): klepetajte v živo, delite svoje aplikacije in se povežite z drugimi uporabniki Difyja.
- [X](https://x.com/dify_ai): spremljajte novice o izdajah in posodobitve projekta.
## Star history
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Varnostno razkritje
Ranljivosti prijavite zasebno prek GitHub Security Advisories v skladu z našo [varnostno politiko](../../SECURITY.md). Ne razkrivajte jih v javnih prijavah težav, razpravah ali zahtevkih za združitev.
## Licenca
To skladišče je na voljo pod [odprtokodno licenco Dify](../../LICENSE) , ki je v bistvu Apache 2.0 z nekaj dodatnimi omejitvami.
---
### Tlh README (`docs/tlh/README.md`)
Dify is an open-source LLM app development platform. Its intuitive interface combines AI workflow, RAG pipeline, agent capabilities, model management, observability features (including [Opik](https://www.comet.com/docs/opik/integrations/dify), [Langfuse](https://docs.langfuse.com), and [Arize Phoenix](https://docs.arize.com/phoenix)) and more, letting you quickly go from prototype to production. Here's a list of the core features:
**1. Workflow**:
Build and test powerful AI workflows on a visual canvas, leveraging all the following features and beyond.
**2. Comprehensive model support**:
Seamless integration with hundreds of proprietary / open-source LLMs from dozens of inference providers and self-hosted solutions, covering GPT, Mistral, Llama3, and any OpenAI API-compatible models. A full list of supported model providers can be found [here](https://docs.dify.ai/getting-started/readme/model-providers).
**3. Prompt IDE**:
Intuitive interface for crafting prompts, comparing model performance, and adding additional features such as text-to-speech to a chat-based app.
**4. RAG Pipeline**:
Extensive RAG capabilities that cover everything from document ingestion to retrieval, with out-of-box support for text extraction from PDFs, PPTs, and other common document formats.
**5. Agent capabilities**:
You can define agents based on LLM Function Calling or ReAct, and add pre-built or custom tools for the agent. Dify provides 50+ built-in tools for AI agents, such as Google Search, DALL·E, Stable Diffusion and WolframAlpha.
**6. LLMOps**:
Monitor and analyze application logs and performance over time. You could continuously improve prompts, datasets, and models based on production data and annotations.
**7. Backend-as-a-Service**:
All of Dify's offerings come with corresponding APIs, so you could effortlessly integrate Dify into your own business logic.
## Using Dify
- **Cloud **
We host [Dify Cloud](https://cloud.dify.ai) so you can try Dify without managing a server. See the [pricing page](https://dify.ai/pricing) for current plans and usage allowances.
- **Self-hosting Dify Community Edition**
Quickly get Dify running in your environment with this [starter guide](#quick-start).
Use our [documentation](https://docs.dify.ai) for further references and more in-depth instructions.
- **Dify for Enterprise / Organizations**
We provide additional enterprise-centric features. [Send us an email](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) to discuss enterprise needs.
## Staying ahead
Star Dify on GitHub and be instantly notified of new releases.
## Quick Start
> Before installing Dify, make sure your machine meets the following minimum system requirements:
>
> - CPU >= 2 Core
> - RAM >= 4GB
The easiest way to start the Dify server is to run our [docker-compose.yml](../../docker/docker-compose.yaml) file. Before running the installation command, make sure that [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed on your machine:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
After running, you can access the Dify dashboard in your browser at [http://localhost/install](http://localhost/install) and start the initialization process.
> If you'd like to contribute to Dify or do additional development, refer to our [guide to deploying from source code](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## Next steps
For custom configuration, observability, and deployment options, see [Advanced Setup](ADVANCED_SETUP.md).
## Contributing
Dify welcomes contributions of all kinds:
- **Code**: Read the [Contribution Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md), then browse [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ideas and feedback**: Start or join a [GitHub Discussion](https://github.com/langgenius/dify/discussions).
- **Translations**: Follow the [internationalization guide](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) to add or update a locale.
- **Community**: Share the apps you build, help other users, and spread the word about Dify.
### Contributors
## Community & Contact
Choose the channel that best fits your question:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Get help, share feedback, and propose ideas.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Report reproducible bugs and track engineering work. Read the [Contribution Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) before opening one.
- [Discord](https://discord.gg/FngNHpbcY7): Chat in real time, share your apps, and connect with other Dify users.
- [X](https://x.com/dify_ai): Follow Dify for release news and project updates.
## Star History
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Security Disclosure
Report vulnerabilities privately through GitHub Security Advisories, following our [security policy](../../SECURITY.md). Do not disclose them in public issues, discussions, or pull requests.
## License
This repository is available under the [Dify Open Source License](../../LICENSE), which is essentially Apache 2.0 with a few additional restrictions.
---
### Tr TR README (`docs/tr-TR/README.md`)
Dify, açık kaynaklı bir LLM uygulama geliştirme platformudur. Sezgisel arayüzü, AI iş akışı, RAG pipeline'ı, ajan yetenekleri, model yönetimi, gözlemlenebilirlik özellikleri ve daha fazlasını birleştirerek, prototipten üretime hızlıca geçmenizi sağlar. İşte temel özelliklerin bir listesi:
**1. Workflow**:
Görsel bir arayüz üzerinde güçlü AI iş akışları oluşturun ve test edin, aşağıdaki tüm özellikleri ve daha fazlasını kullanarak.
**2. Kapsamlı model desteği**:
Çok sayıda çıkarım sağlayıcısı ve kendi kendine barındırılan çözümlerden yüzlerce özel / açık kaynaklı LLM ile sorunsuz entegrasyon sağlar. GPT, Mistral, Llama3 ve OpenAI API uyumlu tüm modelleri kapsar. Desteklenen model sağlayıcılarının tam listesine [buradan](https://docs.dify.ai/getting-started/readme/model-providers) ulaşabilirsiniz.
**3. Prompt IDE**:
Komut istemlerini oluşturmak, model performansını karşılaştırmak ve sohbet tabanlı uygulamalara metin-konuşma gibi ek özellikler eklemek için kullanıcı dostu bir arayüz.
**4. RAG Pipeline**:
Belge alımından bilgi çekmeye kadar geniş kapsamlı RAG yetenekleri. PDF'ler, PPT'ler ve diğer yaygın belge formatlarından metin çıkarma için hazır destek sunar.
**5. Ajan yetenekleri**:
LLM Fonksiyon Çağırma veya ReAct'a dayalı ajanlar tanımlayabilir ve bu ajanlara önceden hazırlanmış veya özel araçlar ekleyebilirsiniz. Dify, AI ajanları için Google Arama, DALL·E, Stable Diffusion ve WolframAlpha gibi 50'den fazla yerleşik araç sağlar.
**6. LLMOps**:
Uygulama loglarını ve performans metriklerini zaman içinde izleme ve analiz etme imkanı. Üretim ortamından elde edilen verilere ve kullanıcı geri bildirimlerine dayanarak, prompt'ları, veri setlerini ve modelleri sürekli olarak optimize edebilirsiniz. Bu sayede, AI uygulamanızın performansını ve doğruluğunu sürekli olarak artırabilirsiniz.
**7. Hizmet Olarak Backend**:
Dify'ın tüm özellikleri ilgili API'lerle birlikte gelir, böylece Dify'ı kendi iş mantığınıza kolayca entegre edebilirsiniz.
## Dify'ı Kullanma
- **Cloud **
Sunucu yönetmeden [Dify Cloud](https://cloud.dify.ai) ile Dify’ı deneyebilirsiniz. Güncel planlar ve kullanım kotaları için [fiyatlandırma sayfasına](https://dify.ai/pricing) bakın.
- **Dify Topluluk Sürümünü Kendi Sunucunuzda Barındırma**
Bu [başlangıç kılavuzu](#hızlı-başlangıç) ile Dify'ı kendi ortamınızda hızlıca çalıştırın.
Daha fazla referans ve detaylı talimatlar için [dokümantasyonumuzu](https://docs.dify.ai) kullanın.
- **Kurumlar / organizasyonlar için Dify**
Ek kurumsal odaklı özellikler sunuyoruz. Kurumsal ihtiyaçları görüşmek için [bize bir e-posta gönderin](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry).
## Güncel Kalma
GitHub'da Dify'a yıldız verin ve yeni sürümlerden anında haberdar olun.
## Hızlı başlangıç
> Dify'ı kurmadan önce, makinenizin aşağıdaki minimum sistem gereksinimlerini karşıladığından emin olun:
>
> - CPU >= 2 Çekirdek
> - RAM >= 4GB
Dify sunucusunu başlatmanın en kolay yolu, [docker-compose.yml](../../docker/docker-compose.yaml) dosyamızı çalıştırmaktır. Kurulum komutunu çalıştırmadan önce, makinenizde [Docker](https://docs.docker.com/get-docker/) ve [Docker Compose](https://docs.docker.com/compose/install/)'un kurulu olduğundan emin olun:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
Çalıştırdıktan sonra, tarayıcınızda [http://localhost/install](http://localhost/install) adresinden Dify kontrol paneline erişebilir ve başlangıç ayarları sürecini başlatabilirsiniz.
> Eğer Dify'a katkıda bulunmak veya ek geliştirmeler yapmak isterseniz, [kaynak koddan dağıtım kılavuzumuza](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code) başvurun.
## Sonraki adımlar
Özel yapılandırma, gözlemlenebilirlik ve dağıtım seçenekleri için [Gelişmiş Kurulum](ADVANCED_SETUP.md) belgesine bakın.
## Katkıda Bulunma
Dify her türlü katkıyı memnuniyetle karşılar:
- **Kod**: [Katkı Kılavuzu'nu](./CONTRIBUTING.md) okuyun, ardından [yeni katkıda bulunanlara uygun sorunlara](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) göz atın.
- **Fikirler ve geri bildirim**: Bir [GitHub tartışması](https://github.com/langgenius/dify/discussions) başlatın veya mevcut bir tartışmaya katılın.
- **Çeviriler**: Bir dil eklemek veya güncellemek için [uluslararasılaştırma kılavuzunu](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) izleyin.
- **Topluluk**: Oluşturduğunuz uygulamaları paylaşın, diğer kullanıcılara yardımcı olun ve Dify'ı duyurun.
### Katkıda bulunanlar
## Topluluk ve iletişim
Sorunuza en uygun kanalı seçin:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Yardım alın, geri bildirim paylaşın ve fikir önerin.
- [GitHub Issues](https://github.com/langgenius/dify/issues): Tekrarlanabilir hataları bildirin ve mühendislik çalışmalarını takip edin. Bir sorun açmadan önce [Katkı Kılavuzu'nu](./CONTRIBUTING.md) okuyun.
- [Discord](https://discord.gg/FngNHpbcY7): Gerçek zamanlı sohbet edin, uygulamalarınızı paylaşın ve diğer Dify kullanıcılarıyla bağlantı kurun.
- [X](https://x.com/dify_ai): Sürüm haberleri ve proje güncellemeleri için Dify'ı takip edin.
## Star history
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Güvenlik açıklaması
Güvenlik açıklarını [güvenlik politikamıza](../../SECURITY.md) göre GitHub Security Advisories üzerinden özel olarak bildirin. Herkese açık issue, tartışma veya pull request içinde paylaşmayın.
## Lisans
Bu depo, temel olarak Apache 2.0 lisansı ve birkaç ek kısıtlama içeren [Dify Açık Kaynak Lisansı](../../LICENSE) altında kullanıma sunulmuştur.
---
### Vi VN README (`docs/vi-VN/README.md`)
Dify là một nền tảng phát triển ứng dụng LLM mã nguồn mở. Giao diện trực quan kết hợp quy trình làm việc AI, mô hình RAG, khả năng tác nhân, quản lý mô hình, tính năng quan sát và hơn thế nữa, cho phép bạn nhanh chóng chuyển từ nguyên mẫu sang sản phẩm. Đây là danh sách các tính năng cốt lõi:
**1. Quy trình làm việc**:
Xây dựng và kiểm tra các quy trình làm việc AI mạnh mẽ trên một canvas trực quan, tận dụng tất cả các tính năng sau đây và hơn thế nữa.
**2. Hỗ trợ mô hình toàn diện**:
Tích hợp liền mạch với hàng trăm mô hình LLM độc quyền / mã nguồn mở từ hàng chục nhà cung cấp suy luận và giải pháp tự lưu trữ, bao gồm GPT, Mistral, Llama3, và bất kỳ mô hình tương thích API OpenAI nào. Danh sách đầy đủ các nhà cung cấp mô hình được hỗ trợ có thể được tìm thấy [tại đây](https://docs.dify.ai/getting-started/readme/model-providers).
**3. IDE Prompt**:
Giao diện trực quan để tạo prompt, so sánh hiệu suất mô hình và thêm các tính năng bổ sung như chuyển văn bản thành giọng nói cho một ứng dụng dựa trên trò chuyện.
**4. Mô hình RAG**:
Khả năng RAG mở rộng bao gồm mọi thứ từ nhập tài liệu đến truy xuất, với hỗ trợ sẵn có cho việc trích xuất văn bản từ PDF, PPT và các định dạng tài liệu phổ biến khác.
**5. Khả năng tác nhân**:
Bạn có thể định nghĩa các tác nhân dựa trên LLM Function Calling hoặc ReAct, và thêm các công cụ được xây dựng sẵn hoặc tùy chỉnh cho tác nhân. Dify cung cấp hơn 50 công cụ tích hợp sẵn cho các tác nhân AI, như Google Search, DALL·E, Stable Diffusion và WolframAlpha.
**6. LLMOps**:
Giám sát và phân tích nhật ký và hiệu suất ứng dụng theo thời gian. Bạn có thể liên tục cải thiện prompt, bộ dữ liệu và mô hình dựa trên dữ liệu sản xuất và chú thích.
**7. Backend-as-a-Service**:
Tất cả các dịch vụ của Dify đều đi kèm với các API tương ứng, vì vậy bạn có thể dễ dàng tích hợp Dify vào logic kinh doanh của riêng mình.
## Sử dụng Dify
- **Cloud **
Dùng thử [Dify Cloud](https://cloud.dify.ai) mà không cần quản lý máy chủ. Xem các gói và hạn mức sử dụng hiện tại tại [trang giá](https://dify.ai/pricing).
- **Tự triển khai Dify Community Edition**
Nhanh chóng chạy Dify trong môi trường của bạn với [hướng dẫn bắt đầu](#bắt-đầu-nhanh) này.
Sử dụng [tài liệu](https://docs.dify.ai) của chúng tôi để tham khảo thêm và nhận hướng dẫn chi tiết hơn.
- **Dify cho doanh nghiệp / tổ chức**
Chúng tôi cung cấp các tính năng bổ sung tập trung vào doanh nghiệp. [Gửi email cho chúng tôi](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) để thảo luận về nhu cầu doanh nghiệp.
## Luôn cập nhật
Yêu thích Dify trên GitHub và được thông báo ngay lập tức về các bản phát hành mới.
## Bắt đầu nhanh
> Trước khi cài đặt Dify, hãy đảm bảo máy của bạn đáp ứng các yêu cầu hệ thống tối thiểu sau:
>
> - CPU >= 2 Core
> - RAM >= 4GB
Cách dễ nhất để khởi động máy chủ Dify là chạy tệp [docker-compose.yml](../../docker/docker-compose.yaml) của chúng tôi. Trước khi chạy lệnh cài đặt, hãy đảm bảo rằng [Docker](https://docs.docker.com/get-docker/) và [Docker Compose](https://docs.docker.com/compose/install/) đã được cài đặt trên máy của bạn:
```bash
cd docker
cp .env.example .env
docker compose up -d
```
Sau khi chạy, bạn có thể truy cập bảng điều khiển Dify trong trình duyệt của bạn tại [http://localhost/install](http://localhost/install) và bắt đầu quá trình khởi tạo.
> Nếu bạn muốn đóng góp cho Dify hoặc phát triển thêm, hãy tham khảo [hướng dẫn triển khai từ mã nguồn](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code) của chúng tôi
## Các bước tiếp theo
Để biết các tùy chọn cấu hình tùy chỉnh, khả năng quan sát và triển khai, hãy xem [Thiết lập nâng cao](ADVANCED_SETUP.md).
## Đóng góp
Dify chào đón mọi hình thức đóng góp:
- **Mã nguồn**: đọc [Hướng dẫn đóng góp](./CONTRIBUTING.md), sau đó xem các [issue phù hợp cho người mới](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
- **Ý tưởng và phản hồi**: bắt đầu hoặc tham gia một [thảo luận trên GitHub](https://github.com/langgenius/dify/discussions).
- **Bản dịch**: làm theo [hướng dẫn quốc tế hóa](https://github.com/langgenius/dify/blob/main/web/i18n/README.md) để thêm hoặc cập nhật một ngôn ngữ.
- **Cộng đồng**: chia sẻ ứng dụng bạn xây dựng, hỗ trợ người dùng khác và giới thiệu Dify đến nhiều người hơn.
### Người đóng góp
## Cộng đồng và liên hệ
Chọn kênh phù hợp nhất với câu hỏi của bạn:
- [GitHub Discussions](https://github.com/langgenius/dify/discussions): nhận trợ giúp, chia sẻ phản hồi và đề xuất ý tưởng.
- [GitHub Issues](https://github.com/langgenius/dify/issues): báo cáo lỗi có thể tái hiện và theo dõi công việc kỹ thuật. Đọc [Hướng dẫn đóng góp](./CONTRIBUTING.md) trước khi mở issue.
- [Discord](https://discord.gg/FngNHpbcY7): trò chuyện theo thời gian thực, chia sẻ ứng dụng và kết nối với những người dùng Dify khác.
- [X](https://x.com/dify_ai): theo dõi tin tức phát hành và cập nhật dự án.
## Lịch sử Yêu thích
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## Tiết lộ bảo mật
Báo cáo lỗ hổng riêng tư qua GitHub Security Advisories theo [chính sách bảo mật](../../SECURITY.md). Không công bố trong issue, thảo luận hoặc pull request công khai.
## Giấy phép
Kho lưu trữ này có sẵn theo [Giấy phép Mã nguồn Mở Dify](../../LICENSE), về cơ bản là Apache 2.0 với một vài hạn chế bổ sung.
---
### Zh CN README (`docs/zh-CN/README.md`)
Dify 是一個開源的 LLM 應用程式開發平台。其直觀的界面結合了智能代理工作流程、RAG 管道、代理功能、模型管理、可觀察性功能等，讓您能夠快速從原型進展到生產環境。
## 快速開始
> 安裝 Dify 之前，請確保您的機器符合以下最低系統要求：
>
> - CPU >= 2 核心
> - 記憶體 >= 4 GiB
啟動 Dify 伺服器最簡單的方式是透過 [docker compose](../../docker/docker-compose.yaml)。在使用以下命令運行 Dify 之前，請確保您的機器已安裝 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/)：
```bash
cd dify
cd docker
cp .env.example .env
docker compose up -d
```
運行後，您可以在瀏覽器中通過 [http://localhost/install](http://localhost/install) 訪問 Dify 儀表板並開始初始化過程。
### 尋求幫助
如果您在設置 Dify 時遇到問題，請參考我們的 [常見問題](https://docs.dify.ai/getting-started/install-self-hosted/faqs)。如果仍有疑問，請聯絡 [社區和我們](#社群與聯絡方式)。
> 如果您想為 Dify 做出貢獻或進行額外開發，請參考我們的 [從原始碼部署指南](https://docs.dify.ai/getting-started/install-self-hosted/local-source-code)
## 核心功能
**1. 工作流程**：
在視覺化畫布上建立和測試強大的 AI 工作流程，利用以下所有功能及更多。
**2. 全面的模型支援**：
無縫整合來自數十個推理提供商和自託管解決方案的數百個專有/開源 LLM，涵蓋 GPT、Mistral、Llama3 和任何與 OpenAI API 兼容的模型。您可以在[此處](https://docs.dify.ai/getting-started/readme/model-providers)找到支援的模型提供商完整列表。
**3. 提示詞 IDE**：
直觀的界面，用於編寫提示詞、比較模型性能，以及為聊天型應用程式添加文字轉語音等額外功能。
**4. RAG 管道**：
廣泛的 RAG 功能，涵蓋從文件擷取到檢索的全部流程，內建支援從 PDF、PPT 和其他常見文件格式提取文本。
**5. 代理功能**：
您可以基於 LLM 函數調用或 ReAct 定義代理，並為代理添加預構建或自定義工具。Dify 為 AI 代理提供 50 多種內建工具，如 Google 搜尋、DALL·E、Stable Diffusion 和 WolframAlpha。
**6. LLMOps**：
監控並分析應用程式日誌和長期效能。您可以根據生產數據和標註持續改進提示詞、數據集和模型。
**7. 後端即服務**：
Dify 的所有功能都提供相應的 API，因此您可以輕鬆地將 Dify 整合到您自己的業務邏輯中。
## 使用 Dify
- **雲端服務 **
我們提供 [Dify Cloud](https://cloud.dify.ai)，無需管理伺服器即可體驗 Dify。最新方案與用量額度請參閱[定價頁面](https://dify.ai/pricing)。
- **自託管 Dify 社區版**
使用這份[快速指南](#%E5%BF%AB%E9%80%9F%E9%96%8B%E5%A7%8B)在您的環境中快速運行 Dify。
使用我們的[文檔](https://docs.dify.ai)獲取更多參考和深入指導。
- **企業/組織版 Dify**
我們提供額外的企業中心功能。[通過這個聊天機器人記錄您的問題](https://udify.app/chat/22L1zSxg6yW1cWQg)或[發送電子郵件給我們](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry)討論企業需求。
## 保持領先
在 GitHub 上為 Dify 加星，即時獲取新版本通知。
## 進階設定
如需自訂設定、可觀測性和部署選項，請參閱[進階設定](ADVANCED_SETUP.md)。
## 貢獻
Dify 歡迎各種形式的貢獻：
- **程式碼**：閱讀[貢獻指南](./CONTRIBUTING.md)，再瀏覽[適合新手的議題](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)。
- **想法與意見**：發起或加入 [GitHub Discussions](https://github.com/langgenius/dify/discussions)。
- **翻譯**：依照[國際化指南](https://github.com/langgenius/dify/blob/main/web/i18n/README.md)新增或更新語言。
- **社群**：分享您建立的應用程式、協助其他使用者，並向更多人介紹 Dify。
### 貢獻者
## 社群與聯絡方式
請選擇最符合您問題的管道：
- [GitHub Discussions](https://github.com/langgenius/dify/discussions)：取得協助、分享意見並提出想法。
- [GitHub Issues](https://github.com/langgenius/dify/issues)：回報可重現的錯誤並追蹤工程工作。建立議題前，請先閱讀[貢獻指南](./CONTRIBUTING.md)。
- [Discord](https://discord.gg/FngNHpbcY7)：即時交流、分享您的應用程式，並與其他 Dify 使用者互動。
- [X](https://x.com/dify_ai)：追蹤版本消息與專案更新。
## 星星歷史
[](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-light-mode-only) [](https://star-history.dera.page/langgenius/dify?type=date&legend=top-left#gh-dark-mode-only)
## 安全揭露
請依照[安全政策](../../SECURITY.md)，透過 GitHub Security Advisories 私下回報漏洞，不要在公開議題、討論或 PR 中揭露。
## 授權條款
本代碼庫採用 [Dify 開源授權](../../LICENSE)，這基本上是 Apache 2.0 授權加上一些額外限制條款。
---
### Dify Agent Docs Dify Agent Index (`dify-agent/docs/dify-agent/index.md`)
# Dify Agent runtime
Dify Agent hosts native Pydantic AI runs behind FastAPI. Implementations remain
under `src/dify_agent`; there is no separate agent composition framework.
Each module declares Pydantic `Config`, `State`, and exactly one native
`Capability` or `Toolset`. The server registry maps a name to a module. Names
identify configuration, state and instances; aliases can use the same module
with independent state. New instances are created for every run.
`ctx.deps.layers[name]` contains JSON `config` and `state`. Config is read-only
within a run and comes from the current request. State belongs to its module;
validated models are copies, so mutations require explicit
`entry["state"] = state.model_dump(mode="json")` writeback. Stateful tools that
read and modify across awaits execute sequentially.
`deps.services` borrows lifespan clients and server settings. `deps.resources`
holds only operation leases, shell sessions and temporary credentials. The
capability that acquires a resource releases it in `wrap_run` using `finally`,
including failures and cancellation. The API owns durable Binding/Workspace
retirement and saves snapshots in the owning session.
Registered production names are `agent_soul_prompt`, `workflow_node_job_prompt`,
`workflow_user_prompt`, `agent_app_user_prompt`, `execution_context`, `runtime`,
`shell`, `config`, `history`, `llm`, `tools`, `core_tools`, `knowledge`, `output`,
plus `prompt` and `user_prompt` convenience names. HTTP input cannot supply an
import path. Cross-module references live in Config, for example
`execution_context`, `runtime`, and `shell`; the loader validates their targets
before I/O. Instruction ordering is unspecified. Native capability ordering
preserves Runtime → Shell → Config resource scopes.
An enabled Local runtime requires a nonblank deployment auth token matching
shellctl. When shellctl path isolation is enabled, Landlock setup errors abort
the job before its user script executes. Deployment settings may explicitly
disable path isolation. See the [operations guide](guide/index.md) for setup.
Model, output type, current user content and initial history use explicit runner
assembly and native Agent arguments. Knowledge eager results stay in the user
role through a native model-request hook. Tool dispatch, instructions and
capability hooks use native Pydantic AI interfaces.
See [run lifecycle](concepts/run-lifecycle/index.md),
[resources](concepts/runtime-resources/index.md), and the
[operations guide](guide/index.md).
---
### Dify Agent Docs Dify Agent Examples Index (`dify-agent/docs/dify-agent/examples/index.md`)
# Dify Agent examples
These examples live under `examples/dify_agent/dify_agent_examples`. They use
registered modules and depend on the Agent server, Redis, Dify API, and plugin
daemon settings described in the operations guide.
## Run a Dify plugin-daemon backed model
```snippet {path="/examples/dify_agent/dify_agent_examples/run_pydantic_ai_agent.py"}
```
## Poll run events
```snippet {path="/examples/dify_agent/dify_agent_examples/run_server_consumer.py"}
```
## Use the synchronous client
```snippet {path="/examples/dify_agent/dify_agent_examples/run_server_sync_client.py"}
```
## Stream run events with SSE
```snippet {path="/examples/dify_agent/dify_agent_examples/run_server_sse_consumer.py"}
```
---
### Dify Agent Docs Dify Agent Get Started Index (`dify-agent/docs/dify-agent/get-started/index.md`)
# Get started
Create a run with `POST /runs`; poll `/runs/{run_id}` or consume its event stream.
The composition schema version is 2. Each entry contains a registered `name` and
current JSON `config`. Module identity comes from the server registry; there are
no graph type/dependency fields or generic per-module exit policy.
```json
{
"composition": {
"schema_version": 2,
"layers": [
{"name": "execution_context", "config": {"tenant_id": "tenant", "agent_mode": "agent_app", "invoke_from": "service-api"}},
{"name": "prompt", "config": {"prefix": "Be helpful", "user": "Hello"}},
{"name": "history", "config": {}},
{"name": "llm", "config": {"execution_context": "execution_context", "plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}
]
}
}
```
Resume by including the previous terminal `session_snapshot` and submitting the
current composition. `llm` is required, `history` and `output` are optional.
Resource cleanup always happens at exit. Cancellation is a separate operation;
its terminal event is published only after the owner run has cleaned up.
---
### Dify Agent Docs Dify Agent Guide Index (`dify-agent/docs/dify-agent/guide/index.md`)
# Operating the Dify Agent Run Server
This guide describes how to run the MVP Dify Agent API server. The server is
implemented in `dify-agent/src/dify_agent/server/app.py` and uses Redis for run
records and per-run event streams. Optional E2B usage collection is triggered by
the API's existing Celery Beat schedule through a separate one-shot endpoint.
It adds no operation logging, polling loop, leader election or accounting context
to business runtime execution.
## Default local startup
Start Redis, then run one FastAPI/uvicorn process:
```bash
uv run --project dify-agent uvicorn dify_agent.server.app:app --reload
```
By default, the FastAPI lifespan creates:
- one Redis-backed run store used by HTTP routes
- shared plugin-daemon and Dify API inner `httpx.AsyncClient` instances
- one deployment-selected, stateless runtime backend profile when configured
- one process-local scheduler that starts background `asyncio` run tasks
This means local development needs one uvicorn process plus Redis, and
plugin-backed runs also need a reachable Dify plugin daemon. Run execution still
happens outside request handlers, so client disconnects do not cancel the agent
run.
## Configuration
`ServerSettings` loads environment variables with the `DIFY_AGENT_` prefix. It
also reads `.env` and `dify-agent/.env` when present.
OpenShell-specific settings are listed in the
[OpenShell configuration reference](openshell.md#configuration).
Independent E2B execution accounting, activation and rollout checks are described
in [E2B runtime metering](runtime-metering.md).
| Environment variable | Default | Description |
| --- | --- | --- |
| `DIFY_AGENT_REDIS_URL` | `redis://localhost:6379/0` | Redis connection URL. |
| `DIFY_AGENT_REDIS_PREFIX` | `dify-agent` | Prefix for Redis record and event keys. |
| `DIFY_AGENT_SHUTDOWN_GRACE_SECONDS` | `30` | Seconds to wait for active local runs during graceful shutdown before cancellation. |
| `DIFY_AGENT_RUN_RETENTION_SECONDS` | `7200` | Seconds to retain Redis run records and per-run event streams after their last write; defaults to 2 hours. |
| `DIFY_AGENT_RUN_EVENT_STREAM_MAX_LENGTH` | `5000` | Approximate target maximum for replayable events retained in each per-run Redis Stream. |
| `DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED` | `true` | Set `false` to publish each text delta without coalescing. |
| `DIFY_AGENT_STREAM_TEXT_DELTA_FLUSH_INTERVAL_MS` | `100` | Soft debounce interval for compatible text deltas. Already-ready source events may continue to merge after this interval; a waiting source triggers the timed flush. Must be greater than zero; use `DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED=false` to disable coalescing. |
| `DIFY_AGENT_STREAM_TEXT_DELTA_MAX_CHARS` | `4096` | Character threshold that flushes a buffered text-delta event immediately. |
| `DIFY_AGENT_RUN_TIMEOUT_SECONDS` | `3600` | Wall-clock deadline in seconds for the Pydantic AI `agent.run(...)` model/tool loop. Deadline failures use `agent_run_limit_exceeded`. Its default intentionally matches `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS`, but the settings are independently configurable. |
| `DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS` | `210` | Shell command deadline for running the sandbox `dify-agent file upload --no-download-link` conversion. Keep it above the CLI's 180-second upload deadline. |
| `DIFY_AGENT_API_TOKEN` | empty | Optional Bearer token required by private run, Execution Binding, Home Snapshot, and Binding file control-plane routes. Must match Dify API `AGENT_BACKEND_API_TOKEN`. |
| `DIFY_AGENT_PLUGIN_DAEMON_URL` | `http://localhost:5002` | Base URL for the Dify plugin daemon. |
| `DIFY_AGENT_PLUGIN_DAEMON_API_KEY` | empty | API key sent to the Dify plugin daemon. |
| `DIFY_AGENT_INNER_API_URL` | `http://localhost:5001` | Dify API service root used when dify-agent calls `/inner/api/...` endpoints. |
| `DIFY_AGENT_INNER_API_KEY` | empty | API key sent to Dify API inner plugin endpoints. Set this to Dify API `INNER_API_KEY_FOR_PLUGIN` (Docker: `PLUGIN_DIFY_INNER_API_KEY`). |
| `DIFY_AGENT_RUNTIME_BACKEND` | `local` | Selects one coherent `local`, `enterprise`, `e2b`, or `openshell` Home Snapshot + Execution Binding backend profile. |
| `DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT` | empty | Local shellctl data-plane URL. With the default Local selection, leaving it empty disables `dify.runtime` and resource endpoints. |
| `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN` | empty | Required nonblank bearer token when the Local endpoint is configured; must match shellctl's `SHELLCTL_AUTH_TOKEN`. |
| `DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT` | `/home/dify` | Root directory, on the Local shellctl filesystem, for per-Binding materialized Homes. |
| `DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT` | `/workspace` | Root directory, on the Local shellctl filesystem, for mutable Workspaces. |
| `DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT` | `/home/dify/.snapshots` | Root directory, on the Local shellctl filesystem, for immutable Home Snapshots. |
| `DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_ENDPOINT` | empty | Enterprise Gateway endpoint required by configuration. Default-Home Bindings are supported; immutable Home Snapshot operations remain unsupported. |
| `DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_AUTH_TOKEN` | empty | Optional `X-Inner-Api-Key` sent to the Enterprise Gateway. |
| `DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_TIMEOUT` | `30` | Enterprise control-plane timeout in seconds. |
| `DIFY_AGENT_ENTERPRISE_SANDBOX_PROXY_TIMEOUT` | `60` | Enterprise shellctl-proxy timeout in seconds. |
| `DIFY_AGENT_E2B_API_KEY` | empty | E2B API key; required for E2B. |
| `DIFY_AGENT_E2B_TEMPLATE` | `difys-default-team/dify-agent-local-sandbox` | Prepared E2B template containing shellctl and the deployment-default Home environment. |
| `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS` | `3600` | Maximum continuous active time for the RuntimeLease spanning one complete Agent run. Its default intentionally matches `DIFY_AGENT_RUN_TIMEOUT_SECONDS`, but the settings are independently configurable. Binding resources pause on timeout; this setting does not own the run terminal state and is not a retention TTL. |
| `DIFY_AGENT_E2B_SHELLCTL_PORT` | `5004` | shellctl port exposed by the E2B template. |
| `DIFY_AGENT_SHELL_REDACT_PATTERNS` | empty | JSON array of additional regex patterns redacted from Shell output. |
| `DIFY_AGENT_STUB_API_BASE_URL` | empty | HTTP(S) Agent Stub API base URL reachable from the Sandbox. It may be the service root or `/agent-stub`. Enables `DIFY_AGENT_STUB_*` env injection for user `shell.run` jobs. |
| `DIFY_AGENT_SANDBOX_FILES_BASE_URL` | empty | Dify API base URL reachable from the Sandbox for signed `/files/*` upload/download bytes, including Config file and skill pulls. Required when Agent Stub file operations are enabled. May include an ingress path prefix, but not a query or fragment. |
| `DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` | `50` | Agent service-owned maximum Agent Stub upload size in MiB. The file-request handler factory converts it to bytes and sends it to Dify API as the required `max_size` used to sign a size-limited upload URL. |
| `DIFY_AGENT_SERVER_SECRET_KEY` | empty | Security-sensitive server-wide root secret used to derive the JWE encryption key for Agent Stub bearer tokens; required when `DIFY_AGENT_STUB_API_BASE_URL` is set. The supplied default config uses a development value; set a unique unpadded base64url 32-byte secret in production. |
| `DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT` | `10` | Shared outbound HTTP connect timeout in seconds. |
| `DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT` | `600` | Shared outbound HTTP read timeout in seconds. |
| `DIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUT` | `30` | Shared outbound HTTP write timeout in seconds. |
| `DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT` | `10` | Shared outbound connection-pool wait timeout in seconds. |
| `DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS` | `100` | Maximum total shared outbound HTTP connections. |
| `DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS` | `20` | Maximum idle shared outbound HTTP connections. |
| `DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY` | `30` | Idle keep-alive expiry in seconds. |
| `DIFY_AGENT_TRAJECTORY_ENABLED` | `false` | Opt-in switch for the separate Agent trajectory export pipeline. |
| `DIFY_AGENT_APPLICATION_TRACING_ENABLED` | `false` | Collect API-authorized application spans into the Dify inner API tracing inbox. Requires the server inner API URL and key. |
| `DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT` | empty | Full HTTP(S) OTLP traces endpoint required when trajectory export is enabled. |
| `DIFY_AGENT_TRAJECTORY_OTLP_HEADERS` | `{}` | JSON object of request headers sent with Agent OTLP trace exports. |
| `DIFY_AGENT_TRAJECTORY_SERVICE_NAME` | `dify-agent-trajectory` | Resource service name attached to Agent trajectory spans. |
| `DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT` | `false` | Include message and tool content in Agent trajectory spans. |
| `DIFY_AGENT_TRAJECTORY_TRACE_CONTEXT_MODE` | `isolated` | `isolated` starts independent platform/Agent traces; `shared` preserves cross-instance parent context. Requires process restart to change. |
| `DIFY_AGENT_TRAJECTORY_MAX_QUEUE_SIZE` | `2048` | Maximum number of spans queued for Agent trace export; must be positive. |
| `DIFY_AGENT_TRAJECTORY_MAX_EXPORT_BATCH_SIZE` | `512` | Maximum spans per export batch; must be positive and no greater than the queue size. |
| `DIFY_AGENT_TRAJECTORY_SCHEDULE_DELAY_MS` | `5000` | Delay between scheduled Agent span exports, in milliseconds; must be positive. |
| `DIFY_AGENT_TRAJECTORY_EXPORT_TIMEOUT_MS` | `5000` | Batch processor export timeout setting, in milliseconds; must be positive. Does not change the OTLP HTTP exporter request timeout. |
Platform observability uses the process-level Logfire instance and standard
`OTEL_*` / `LOGFIRE_*` configuration. Agent observability uses a separate local
Logfire instance and is disabled by default. Set `DIFY_AGENT_TRAJECTORY_ENABLED=true`
and a full `DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT` to opt in;
`DIFY_AGENT_TRAJECTORY_OTLP_HEADERS` is a JSON object of request headers. Agent
traces do not inherit platform endpoints, credentials, sampling, or console
export. Message/tool content requires the separate
`DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT` opt-in. Platform FastAPI parameter/error
payloads, HTTPX bodies/headers and Redis statements are not captured by these
instrumentations. The Agent instance is created at service startup and shut down
after active runs finish. These are deployment-level settings, not yet
per-tenant authorization or routing; a shared backend does not provide storage
isolation.
With `DIFY_AGENT_TRAJECTORY_TRACE_CONTEXT_MODE=isolated` (the default), Agent
run spans start independent traces instead of inheriting platform request
parents. Platform HTTPX/Redis instrumentation also detaches local Agent
parents while preserving platform-only and incoming distributed trace
relationships. In `shared` mode both pipelines retain cross-instance parent
context and the Agent sampler respects the parent sampling decision. Use
`shared` only when both pipelines export to the same queryable backend space;
otherwise missing-root spans can recur. Service names do not select the mode.
The two SDK instances, exporters, enable switch, and content opt-in remain
separate. The mode is fixed at process initialization and requires a restart
to change. No extra shared root span is added; incomplete traces may still
appear temporarily while a run or export is in progress.
Application tracing is a third, independent pipeline. When enabled, a run's
API-issued `execution_context.tracing` supplies its durable run/invocation IDs,
OpenTelemetry parent, session and content/sampling policy. Its spans are sent as
JSON to `POST /inner/api/agent/tracing/batches`, authenticated with the server's
`DIFY_AGENT_INNER_API_KEY` in `X-Inner-Api-Key`. Provider credentials and routing
remain in the Dify API. Application spans do not inherit platform or deployment
trajectory destinations, and one Agent is never instrumented by both application
and deployment pipelines. Binary content is excluded.
The actual model-call span also carries the Dify gateway's billed amount as
`dify.llm.total_price` (a decimal string) and `dify.llm.currency` when a usage
payload is returned. `gen_ai.response.time_to_first_token` is measured in seconds
(`dify.llm.time_to_first_token_unit=s`): gateway-provided TTFT takes precedence;
otherwise it measures request issue to the first content/tool-call chunk.
`dify.llm.time_to_first_token_source` distinguishes those two sources. Missing
accounting is left absent. The current Graphon LLM gateway does not expose cache
token counters, so the Agent adapter does not manufacture them.
Each batch has a stable `batch_id`. Retries reuse the same payload, and a 2xx
response is accepted only with `{result: "success", batch_id, accepted_spans}`
matching that batch. An invocation emits an empty `final: true` batch after its
ended spans are flushed and acknowledged, before its normal terminal event when
delivery completes within five seconds. Failure or cancellation still flushes.
Collection failures do not fail the Agent run; outstanding delivery can finish
in the background after the terminal-event deadline. A full in-memory queue or
unacknowledged data suppresses completion instead of claiming a complete trace.
The queue is bounded (2048 spans, batches of at most 128), with up to 128 unacknowledged
batches retained until invocation finalization. Batches are split below 1 MiB
of UTF-8 JSON. A single oversized span is dropped and marks its invocation
incomplete rather than silently truncating content or sending a success marker.
This is not a durable local
spool: process loss can leave an incomplete trace in the API. Shutdown drains the
collector after active runs finish.
If setup fails or cancellation arrives before Pydantic AI starts its Agent span,
the collector emits one failed `invoke_agent` span with the measured setup
interval, then finalizes normally. It records `dify.agent.execution_state` as
`initialization_failed` or `cancelled`. Runs that already started their native
Agent span keep that span without an extra wrapper. Sampling-off invocations
remain span-free; successful but unexplained empty collections are not converted
to synthetic success.
Example `.env`:
```
/* Detailed source-code truncated for AI context efficiency. */
```
The two Sandbox-facing base URLs have different owners. Agent Stub control
requests use `DIFY_AGENT_STUB_API_BASE_URL`; signed file bytes use
`DIFY_AGENT_SANDBOX_FILES_BASE_URL`. `DIFY_AGENT_INNER_API_URL` remains a
trusted service-to-service URL and is never returned to the Sandbox.
Config file and skill pulls use the same split: Agent Stub authorizes the
Config target and returns a short-lived URL, then the Sandbox fetches the bytes
directly from the Dify API `/files/*` data plane.
Removing Agent Stub gRPC is a breaking transport migration: replace every
`grpc://` Agent Stub URL with HTTP(S), remove
`DIFY_AGENT_STUB_GRPC_BIND_ADDRESS`, and deploy without a gRPC fallback.
For a remote Sandbox, expose only `/agent-stub/*` from Agent Backend and the
existing `/files/*` Dify API data plane. The `/files/*` ingress must preserve
the complete signed query string and set its request-body limit above the
configured file-size limit to leave room for multipart framing and headers; the
two limits need not be numerically equal. Use response streaming and timeouts
suitable for large downloads. Do not expose Agent Backend `/runs`, Workspace,
or Binding management routes through the Sandbox ingress.
Browser presentation URLs are independent. Configure Dify API `FILES_URL` to a
browser-reachable public origin, or leave it empty so responses use same-origin
relative `/files/...` URIs. Never set `FILES_URL` to a Docker-only service name
such as `http://api:5001`.
`DIFY_AGENT_SHELLCTL_ENTRYPOINT` and `DIFY_AGENT_SHELLCTL_AUTH_TOKEN` remain
accepted only as legacy aliases for the two Local settings. New deployments
must use `DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT` and
`DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`. There is no compatibility setting for
the removed shell-provider selector.
Local shellctl deployments must start with `shellctl serve --require-auth-token`
and set `SHELLCTL_AUTH_TOKEN` to the same secret as the Agent Backend. Compose's
`local_sandbox` command enables this check; missing, empty, or whitespace-only
tokens fail before service initialization. E2B and Enterprise retain their
existing token requirements, and an unset Local endpoint still disables runtime.
For Compose, set `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN` in a shared interpolation
source: the invoking shell, `docker/.env`, or a Compose `--env-file`. This supplies
the same secret to Agent Backend and shellctl. Setting it only in a service env
file is insufficient: Compose's explicit `environment` values override that
file, including with an empty interpolated value. The legacy token alias remains
accepted. Deploy this change with a rebuilt runtime image containing
`--require-auth-token`; the previously published `1.17.1` image does not support
the new flag.
When shellctl path isolation is enabled, any Landlock setup error aborts the job
with exit code `125` before its user script executes. Deployments may explicitly
set `SHELLCTL_ENABLE_PATH_ISOLATION=false` to disable shellctl path isolation.
The backend selection is deployment-private. Shell-enabled run requests use an
Execution Context, `dify.runtime`, and `dify.shell` graph. Runtime config carries
only the opaque `backend_binding_ref` resolved by Dify API. See
[Runtime resources](../concepts/runtime-resources/index.md) for the ownership
and lifecycle contract.
Run records and event streams use the same retention. Status writes refresh the
record TTL, and event writes refresh both the stream TTL and the corresponding
record TTL so active runs that keep producing events remain observable. Text
deltas for the same response part and provider metadata are coalesced within a
soft debounce/size window before being published. The debounce timer flushes
when reading the next source event would block; already-ready events may keep
merging until the character threshold or a non-compatible event is reached.
Every Redis Stream write also applies the configured approximate maximum length. A reconnect cursor older than the
retained window resumes from the oldest remaining event, so callers must treat
the terminal snapshot and application-owned history as authoritative rather
than relying on the Agent event stream as long-term history.
## Validate the E2B Compose deployment
The E2B overlay requires a prepared template that starts shellctl on port 5004.
The default is `difys-default-team/dify-agent-local-sandbox`. It also requires
an E2B API key in `DIFY_AGENT_E2B_API_KEY`; the Compose interpolation accepts
`E2B_API_KEY` and `E2B_API_TOKEN` only as deployment-level fallbacks.
From the repository root, keep the normal `docker/.env` unchanged and export the
secret for this shell:
```bash
export DIFY_AGENT_E2B_API_KEY="${DIFY_AGENT_E2B_API_KEY:-${E2B_API_KEY:-${E2B_API_TOKEN:-}}}"
test -n "$DIFY_AGENT_E2B_API_KEY"
export DIFY_AGENT_E2B_TEMPLATE=difys-default-team/dify-agent-local-sandbox
docker compose \
--env-file docker/.env \
-f docker/docker-compose.yaml \
-f docker/docker-compose.e2b.yaml \
up -d --build
```
The overlay builds `dify-api:e2b-local` and
`dify-agent-backend:e2b-local` from the current checkout. It disables the
normal Local sandbox service, switches Dify Agent to E2B, and mounts PostgreSQL
on the separate `dify_e2b_postgres_data` Compose volume. That database is empty
when the volume is first created and is isolated from the normal stack; later
starts reuse it until an operator explicitly removes the volume.
Verify the merged deployment and the branch-built Dify Agent API:
```bash
docker compose \
--env-file docker/.env \
-f docker/docker-compose.yaml \
-f docker/docker-compose.e2b.yaml \
ps
agent_backend_port="$(
docker compose \
--env-file docker/.env \
-f docker/docker-compose.yaml \
-f docker/docker-compose.e2b.yaml \
port agent_backend 5050 | awk -F: 'NR == 1 { print $NF }'
)"
test -n "$agent_backend_port"
curl --fail --silent --show-error \
--connect-timeout 2 --max-time 5 \
--retry 12 --retry-delay 1 --retry-connrefused --retry-max-time 60 \
"http://127.0.0.1:${agent_backend_port}/openapi.json" \
>/dev/null
docker compose \
--env-file docker/.env \
-f docker/docker-compose.yaml \
-f docker/docker-compose.e2b.yaml \
logs --tail=100 agent_backend api worker
```
Stop the validation stack without deleting its isolated database volume:
```bash
docker compose \
--env-file docker/.env \
-f docker/docker-compose.yaml \
-f docker/docker-compose.e2b.yaml \
down
```
`DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS` controls continuous active E2B time.
The physical resource behind a Binding pauses when that timeout fires, preserving
the current Workspace. The setting is not a resource-age TTL, does not delete
paused resources or immutable snapshots, and does not authoritatively finalize
the Agent run. If the paused Sandbox is first observed by a Shell tool, that
provider failure is returned to Pydantic AI as a tool error observation.
The run and E2B defaults both equal 3600 seconds, but independent clocks and
asynchronous E2B pause propagation make their ordering nondeterministic. A Shell
provider `RuntimeError` observed first becomes a tool observation. In contrast,
run-deadline cancellation propagates through the Shell boundary; only the Dify
Agent run deadline owns the terminal `agent_run_limit_exceeded` failure.
The E2B backend uses SDK 2.55.1 or later with three control-plane retries.
The SDK retries `502` only for replayable operations, including when the response
has `Retry-After`; a gateway can return `502` after a resource was already created.
Sandbox and snapshot creation therefore surface `502` without replaying the
request. The SDK still retries `503`, `429` with `Retry-After`, and safely
replayable network failures. Backend adapters invoke each SDK operation once;
exhausted retries and timeouts do not start a second SDK request budget.
Resource creation and snapshot creation are also not replayed after an ambiguous
post-write network failure. See the [SDK replay policy](https://github.com/e2b-dev/E2B/pull/1924).
This policy covers E2B lifecycle API calls. Shell commands and normal file
operations use the separate shellctl client, and usage collection uses its own
HTTP client. Neither inherits the E2B SDK retry or connection-pool settings.
The backend explicitly requests `mode="full"` for timeout pauses, explicit
pauses, and Home Snapshots, preserving both filesystem and memory state. Binding
acquisition uses `on_resume="restore"`; `connect` does not accept a snapshot
mode. These settings preserve the existing full-memory restore intent while
replacing the deprecated `keep_memory` option. They do not override platform
fallbacks: E2B may save only the filesystem if a timeout pause is continuously
refused because a previous snapshot is still being finalized. See the
[E2B persistence contract](https://docs.e2b.dev/sandbox/persistence).
## OpenShell backend
See the [OpenShell Runtime Backend guide](openshell.md) for its configuration
reference, runtime image build instructions, gateway and shared-volume setup,
and deployment validation.
## Run runtime-backend integration contracts
Run the disposable Local contract from the `dify-agent` directory. The script
starts one local-sandbox container on an unused port and removes that exact
container on exit. It intentionally has no image fallback: provide a Local
Sandbox image built from the same commit as the code under test so an older
shellctl implementation cannot make the lifecycle contract pass incorrectly:
```bash
cd dify-agent
DIFY_AGENT_TEST_LOCAL_SANDBOX_IMAGE= \
tests/integration/dify_agent/runtime_backend/run_local_integration.sh
```
To use an already managed Local shellctl endpoint instead:
```bash
cd dify-agent
DIFY_AGENT_TEST_LOCAL_SHELLCTL_ENDPOINT=http://127.0.0.1:5004 \
DIFY_AGENT_TEST_LOCAL_SHELLCTL_AUTH_TOKEN=replace-with-shellctl-token \
pdm run pytest --import-mode=importlib \
tests/integration/dify_agent/runtime_backend/test_working_environment.py \
-k local -q -rs
```
Run the real E2B contract with an explicit test credential and template:
```bash
cd dify-agent
DIFY_AGENT_TEST_E2B_API_KEY="$E2B_API_TOKEN" \
DIFY_AGENT_TEST_E2B_TEMPLATE=difys-default-team/dify-agent-local-sandbox \
pdm run pytest --import-mode=importlib \
tests/integration/dify_agent/runtime_backend/test_working_environment.py \
-k e2b -q -rs
```
For OpenShell, see [Run the OpenShell integration contract](openshell.md#run-the-openshell-integration-contract).
The Local auth token is optional when shellctl has authentication disabled.
The E2B contract uses the one-hour `E2B_MAX_ACTIVE_TIMEOUT_SECONDS` RuntimeLease
limit. This is continuous active test time, not a post-test retention TTL. All
contracts create unique resources and perform explicit cleanup in `finally`
blocks.
## Scheduling and shutdown semantics
`POST /runs` persists a `running` run record and starts an `asyncio` task in the
same process. There is no Redis job stream, consumer group, pending reclaim, or
automatic retry layer. Request-shaped runtime failures such as bad composition,
prompt, output, or snapshot inputs are reported later as failed runs rather than
rejected synchronously once the request DTO itself is accepted.
Each run explicitly limits Pydantic AI to 500 model-request steps. Tool calls do
not have a separate count limit, but every model request used to continue the
tool loop consumes one of those steps.
`DIFY_AGENT_RUN_TIMEOUT_SECONDS` additionally applies a wall-clock deadline around
native Pydantic AI's `agent.run(...)`. This includes capability entry, RuntimeLease
acquisition, dynamic tool preparation, the model/tool loop, and the event handler.
Request validation and agent assembly happen before this deadline. Expiry cancels
the native run; capability scopes unwind and release resources before the runner
generates the session snapshot and finalizes the run as failed with
`error_type: "agent_run_limit_exceeded"`. History persistence, snapshot generation,
and terminal finalization occur after native execution.
During FastAPI shutdown the scheduler rejects new runs, waits up to
`DIFY_AGENT_SHUTDOWN_GRACE_SECONDS` for active tasks, then cancels remaining tasks
and attempts to finalize them as failed. Success and failure use an atomic Redis
transition. Cancellation first atomically records a private intent; after the
owner exits the runner, a second atomic transition appends `run_cancelled`,
updates the run record, and deletes the intent. The first accepted success,
failure, or cancellation intent wins. A hard process crash can still leave
active runs, including runs with accepted cancellation intent, stuck as
`running`; there is no in-service recovery or worker handoff.
Horizontal scaling is possible by running multiple API processes against the same
Redis prefix, but each process executes only the runs it accepted. Redis provides
shared status/event visibility, not load balancing or queued-job recovery. The
cancel endpoint can atomically accept a running run on any process. The process
that owns the runner observes the private cancellation-intent stream, cancels
and cleans up its local task, and only then emits `run_cancelled`. The HTTP
response confirms that cancellation intent is durable; `GET /runs/{run_id}` may
still report `running` until cleanup finishes. Retrying an accepted or completed
cancellation is idempotent.
Atomic terminal finalization currently assumes the configured Redis URL targets
one Redis deployment that can execute all run-coordination keys in a Lua script.
The record and event key names are unchanged, and cancellation adds a private
cancel-intent key. These keys do not contain a shared Redis Cluster hash tag, so
Redis Cluster is not supported for this transition. During
a rolling upgrade, older processes can still use the former split event/status
writes; treat the single-terminal invariant as active only after those processes
have exited. Deploy atomic terminal finalization everywhere first, then ensure
every process that can own a runner has the cancellation observer before relying
on route-independent cancellation. Operators should then alert on more than one
terminal event per run and on disagreement between the run record status and
terminal event type.
## Run inputs and session snapshots
Submit a `RunComposition` with registered module names and JSON Config. The
`llm` model module is required and references an `execution_context` module.
Prompt modules contribute instructions and `config.user` input:
```json
{
"composition": {
"schema_version": 2,
"layers": [
{"name": "prompt", "config": {"prefix": "You are concise.", "user": "Summarize the current state."}},
{"name": "execution_context", "config": {"tenant_id": "tenant-id", "agent_mode": "agent_app", "invoke_from": "web-app"}},
{"name": "llm", "config": {"plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}
]
}
}
```
`config.user` can be a string or a list of strings. Empty or whitespace-only
effective prompts and module configuration are validated by the runner before
resource acquisition or model I/O. HTTP create-run parses the wire shape, persists
the run and schedules execution; configuration errors produce `run_failed`.
Agent App callers can use the `agent_app_user_prompt` module to send text and images
in the same model turn. Each image must provide exactly one transport: an
HTTP(S) `url` or unprefixed Base64 data in `base64_data`. The image is passed as
structured multimodal content; it is not interpolated into `config.text`.
```json
{
"name": "agent_app_user_prompt",
"config": {
"text": "Describe this image.",
"files": [
{
"delivery": "multimodal",
"type": "image",
"filename": "earth.png",
"mime_type": "image/png",
"format": "png",
"url": "https://files.example.com/earth.png",
"base64_data": null,
"detail": "high"
}
]
}
}
```
All attachments use `config.files`. The `delivery` field selects how an attachment
is presented, independently of its file `type` (`image`, `document`, `audio`,
`video`, or `custom`):
- `delivery: "multimodal"` currently supports `type: "image"` only. Dify API
chooses URL or Base64 transport according to `MULTIMODAL_SEND_FORMAT`.
- `delivery: "download"` preserves the original file `type`, including `image`
when the selected model has no Vision feature. It contains either
`transfer_method: "remote_url"` with `url`, or a `local_file`, `tool_file`, or
`datasource_file` transfer method with a canonical `reference`.
The module appends sandbox file-download instructions for download attachments
and adds multimodal attachments as structured model content. Callers keep
`config.text` as the original user text. Omitting `config.files` is equivalent
to an empty list.
The optional history module uses the reserved name `history`. It persists captured
messages, including failure and cancellation history, with current instructions
removed. Snapshots have `schema_version: 2` and a `layers` JSON dict containing only
State. Submit current Config on each turn along with the previous snapshot. Modules
can be added or removed between turns; retained state is matched by name.
Known v1 snapshots are converted once at read time without restoring legacy
instances or lifecycle. Native resource scopes always release leases and clear
tracked shell jobs at run exit. Success always contains the resulting snapshot;
failure and cancellation contain one when validated run data was available and
cleanup produced a snapshot. Callers retain the previous snapshot when none is
returned. Product Workspace retirement remains owned by the API.
## Observing runs
Use the HTTP status endpoint for coarse state and the event endpoints for detailed
progress:
- `POST /runs` creates a running run and schedules it locally.
- `GET /runs/{run_id}` returns `running`, `succeeded`, `failed`, or `cancelled`.
Failed records can also expose a stable machine-readable `error_type` alongside
the diagnostic `error` text.
- `POST /runs/{run_id}/cancel` atomically accepts cancellation on any API process
and returns immediately. `CancelRunResponse.status == "cancelled"` acknowledges
a durably accepted cancellation intent, not completed runner cleanup. Callers
that require cleanup-complete state or its session snapshot must await the
public `run_cancelled` event or use `cancel_run_and_wait`. The endpoint returns
`409` only when a success/failure terminal already won.
- `GET /runs/{run_id}/events` polls the Redis Stream event log with `after` and
`next_cursor` cursors.
- `GET /runs/{run_id}/events/sse` replays and streams events over SSE. The SSE
`id` is the event Redis Stream ID. `after` query cursors take precedence over
`Last-Event-ID` headers. The server closes the SSE response normally after
delivering a terminal event. Clients must stop reconnecting after consuming
that event. Both cursor forms remain exclusive resume cursors, so the server
does not resend a terminal event that the supplied cursor already excludes.
Both event endpoints replay with nonblocking `XREAD`, which supports exclusive
resume cursors on Redis 6.0, including 6.0.14. `0-0` starts at the earliest
retained event. Polling returns at most `limit` events; an empty page preserves
the supplied `after` as `next_cursor`. SSE switches to blocking reads after
replay is exhausted. Both endpoints return `404` when the run record is missing.
This read-command compatibility does not define the platform's full Redis
support matrix; the Redis deployment constraints above still apply.
Successful runs emit `run_started`, zero or more `pydantic_ai_event`, and
`run_succeeded`. Failed runs end with `run_failed`, and accepted cancellations
end with `run_cancelled`. Each run can append at most one of these terminal
events. Event envelopes retain `id`, `run_id`, `type`, `data`, and `created_at`;
`data` is typed per event type,
including Pydantic AI's `AgentStreamEvent` payload for `pydantic_ai_event` and a
terminal event may contain a `SessionSnapshot` for resumption.
`run_succeeded` always contains it; `run_failed` and `run_cancelled` contain it
when the runner produced State after native capability cleanup. A successful run
contains JSON-safe `output`, which may be null.
Failed event payloads contain the diagnostic `error`, optional source-specific
`reason`, optional stable `error_type`, and optional `session_snapshot`.
Cancelled payloads likewise may contain `session_snapshot`. Pydantic AI request/step budget
exhaustion enforced by Dify Agent is reported as
`error_type: "agent_run_limit_exceeded"`; consumers should branch on that value
rather than parsing the error text. The Dify Agent-owned wall-clock run deadline
uses the same error type; provider and connection timeouts do not. The matching
failed run record and terminal event are committed atomically with the same error
type. For independently deployed Agent backend and API services, deploy consumers
that accept the optional field before producers begin emitting it because the
public protocol models reject unknown fields.
## Examples
The repository includes simple consumers that print observed output/events:
- `dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py`
creates a run and polls events.
- `dify-agent/examples/dify_agent/dify_agent_examples/run_server_sse_consumer.py`
consumes raw SSE frames for an existing run id.
The create-run examples submit Dify plugin model modules, so they require Redis,
the Agent server, Dify API gateway settings, and a configured model provider in Dify.
---
### Dify Agent Docs Dify Agent Concepts Run Lifecycle Index (`dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md`)
# Agent run lifecycle
The server validates current Config, restored State and module references before
external operations. It creates fresh native Capability/Toolset instances and
runs Pydantic AI with a per-run Deps object. Current prompts and instructions are
built from that run's config.
Native `wrap_run` scopes acquire operation resources and clean them in `finally`.
Runtime acquires a lease; Shell bootstraps once and removes tracked jobs on exit;
Config pulls mentioned assets on successful first initialization. Initialization
flags are written only after successful setup, so failures can retry. The API's
workflow terminal events own Workspace retirement and physical resource collection.
The runner saves captured conversation history in its outer `finally`, strips
transient instructions and marks unexecuted trailing tool calls interrupted.
If no messages were captured, restored history remains intact. Compaction rewrites
are included. A terminal state snapshot is built after capability cleanup for
success, failure and cancellation.
Snapshot v2 stores only JSON state:
```json
{"schema_version": 2, "layers": {"history": {"messages": []}}}
```
Configurations, clients, lease handles, tokens, models and lifecycle enums are
excluded. State is keyed by name, so instruction order does not constrain resume;
known optional modules can be added or removed. The API resubmits current Config
and retains session ownership through `AgentWorkspaceBinding.session_snapshot`.
All snapshot readers use `SessionSnapshot` validation. Its `migrate_snapshot`
validator dispatches v1 (including unversioned legacy lists) to the data-only
`migrate_snapshot_v1_to_v2` helper. V2 is validated directly; unknown explicit
versions are rejected. Reading converts data in memory without updating stored
JSON; the API saves the terminal v2 snapshot through its existing session owner.
Known legacy names map to their meaningful State and removed AskHuman slots are
discarded. Their unanswered tool calls are marked interrupted so native history
repair closes them before the first new user turn. All runs use the native runner.
Unknown legacy names and malformed state are rejected.
---
### Dify Agent Docs Dify Agent Concepts Runtime Resources Index (`dify-agent/docs/dify-agent/concepts/runtime-resources/index.md`)
# Runtime resources
Dify separates persistent product resources from request-time execution:
- a **Home Snapshot** is immutable Agent-owned Home content;
- a **Workspace** is mutable working data owned by a product scope such as a
conversation, Build Draft, or Workflow run;
- an **Execution Binding** is one materialized Agent participant, including its
private Home and resumable session, attached to a Workspace;
- a **RuntimeLease** is operation-scoped access to the physical Binding.
`AgentWorkspaceBinding.id` is the participant, materialized Home, and persisted
module session identity. `agent_id` identifies the source Agent. The same
Agent can therefore have multiple active Bindings in one Workspace:
each has an independent Home and session, while all may share Workspace files.
Home and Workspace are logically independent. A backend may still couple their
physical representation. For example, current E2B maps one Binding and its
Workspace to one E2B resource, while Local can attach multiple materialized
Homes to one shared Workspace.
## Runtime modules
Agent requests do not expose separate Home, Workspace, or Sandbox layers. Dify
API resolves the Binding selected by the product flow and sends its opaque
backend ref to the `runtime` module:
```mermaid
flowchart LR
EC["dify.execution_context request identity"]
RT["dify.runtime opaque backend_binding_ref"]
SH["dify.shell commands and jobs"]
EC --> SH
RT --> SH
```
`runtime.Capability` calls the selected `ExecutionBindingBackend.acquire()` when
its native `wrap_run` scope opens and `release()` when the operation ends. It exposes
the resulting `RuntimeLease` only while that context is active. The module does
not create, retire, or destroy persistent resources, and it stores no backend
SDK object in an module session snapshot.
The Shell module consumes `RuntimeLease.commands` and `RuntimeLease.layout`. It
tracks only request-local shell job ids and offsets.
Closing a run clears that job state; it does not retire the Binding.
## State ownership
Dify API is the lifecycle ledger. It stores three resource records:
| Record | Meaning | Backend field |
| --- | --- | --- |
| `agent_home_snapshots` | One immutable Home version owned by an Agent. | `snapshot_ref` |
| `agent_workspaces` | One mutable Workspace owned by a product scope. | `backend_workspace_ref` |
| `agent_workspace_bindings` | One materialized participant, private Home, and resumable session attached to a Workspace. | `backend_binding_ref` |
Backend refs are opaque strings interpreted only by the selected backend
adapter. Dify API stores the latest module session snapshot on the Binding, but
it does not serialize `RuntimeLease`, SDK clients, credentials, or temporary
access tokens.
Dify Agent does not connect to the Dify product database and has no persistent
resource registry. Its private control-plane endpoints create or destroy
backend resources from requests made by Dify API. Redis run records and event
streams are observability state, not the Home/Workspace/Binding ledger.
When `DIFY_AGENT_API_TOKEN` is configured, every private control-plane request must carry the matching Dify API `AGENT_BACKEND_API_TOKEN` as a Bearer token.
## Creation and execution flow
Agent creation does not create a Home Snapshot. A config with no logical Home
Snapshot asks the selected backend to materialize its deployment-default Home
when the Binding is created. This default Home is mutable and private to the
Binding; it does not produce an `agent_home_snapshots` row or an implicit
snapshot ref.
Build Draft Apply uses `POST /home-snapshots/from-binding`: Dify Agent acquires
the exact source Binding, snapshots its materialized Home through the
backend-native operation, releases the lease, and returns a new opaque snapshot
ref. Dify API then stores a new immutable `agent_home_snapshots` row and records
its logical id on the resulting config version. There is no replay or fallback
when the source Binding is unavailable.
Before an Agent request, Dify API loads the specific product context. If it has
no associated Binding, Dify API materializes one and saves the Binding id in the
same database transaction. Otherwise it resolves only that Binding and validates
its owner and config/Home generation. Missing, retired, or mismatched Bindings
fail fast; Dify API does not search by Agent, Workspace, candidate count, or
recency, and it does not create a replacement implicitly.
`POST /execution-bindings` accepts either an exact `home_snapshot_ref` or
`null`. An exact ref must be materialized without fallback; `null` selects the
backend's deployment-default Home. It returns opaque Binding and Workspace
refs. Every create request represents a new participant, even when the Agent,
Snapshot, config generation, and Workspace match another Binding. The request
composition contains:
```json
{
"name": "runtime",
"config": {"backend_binding_ref": "opaque-backend-binding-ref"}
}
```
Each Agent request acquires that ref for the duration of the run and releases it
afterward. Local release closes the operation's shellctl connection. E2B release
also pauses the underlying E2B resource with memory preserved. A later request
or Binding file operation acquires a new lease for the same Binding ref. If a
backend confirms the resource is gone, acquisition fails; it does not create an
empty replacement Workspace.
## Retirement and collection
Retirement is a database transition from `ACTIVE` to `RETIRED`. It prevents new
product use without performing network I/O inside the caller's transaction.
Product lifecycle paths commit this transition synchronously. After the
transaction commits, one Celery task asks Dify Agent to destroy the physical
resources. A successful collector deletes the corresponding ledger row. If a
collector raises, the task logs the tenant, resource type, and resource ID and
continues with the other independent resources in the batch. After all resources
have been attempted, any failure makes the Celery task fail and prevents Agent
aggregate deletion. Failed RETIRED rows remain available for a later retry. A
failure to publish the Celery task is also propagated to the product caller. No
automatic retry or reconciliation is performed.
The unified `collect_agent_resources` task is registered on normal Celery
workers and explicitly uses the existing `retention` queue. Standard workers
already consume that queue, so no dedicated Agent resource worker or new queue
is required. At a Workflow terminal event, the graph layer synchronously retires
and commits the run's Workspaces before enqueueing collection. When a Workflow
change may orphan Workflow-only Agents, the main product transaction commits
first; a fresh session then rechecks effective ownership and retires only Agents
that remain unowned. An effective reference is a binding in a normal App's
current draft or current published Workflow. This ownership check applies only
to implicit retirement of Workflow-only Agents. Explicit deletion of a roster
Agent or Agent App proceeds even while Workflows reference it.
Retiring a final Binding also retires its Workspace. Workspace collection
destroys the physical Workspace through one Binding and then collects remaining
materialized Homes. Home Snapshots are retired when their owning Agent is
retired. `RETIRED` is the sole physical-deletion condition for a Home Snapshot;
Draft and Config Snapshot references are historical pointers and do not keep it
alive. After every external resource in a deletion batch succeeds, Dify API
hard-deletes the archived Agent together with its Drafts, Config Snapshots,
Config Revisions, debug-conversation mappings, and resource ledgers in one
database transaction. Workflow Agent bindings belong to
their Workflows and remain unchanged, so they may hold a dangling Agent ID after
explicit deletion. Dify Agent itself remains stateless.
A `RETIRED` Workspace without a `RETIRED` Binding cannot identify a backend
participant through which to destroy the Workspace. That state is a lifecycle
invariant violation and fails collection instead of being logged as success.
There is currently no age-based TTL, periodic GC, or global orphan reconciler.
Backend destroy operations are idempotent where supported. Dify API does not
perform cross-system compensation after a backend create returns success. Any
later API failure, including Python, flush, or commit failure, may leave a
physical orphan for a future global reconciler.
Backends still clean up partial resources when a create operation fails before
returning success. For example, E2B kills a Sandbox when its initialization
fails, and Local removes paths created by an incomplete operation. This
backend-local cleanup does not cross the database commit boundary.
## Binding file boundary
Dify API's public file APIs accept a product locator, not a Binding id or
backend ref: a Conversation, a debug Build Draft, or a Workflow Node Execution.
Dify API authorizes that object and resolves its associated active Binding. It
does not select the latest Binding or fall back to another product context.
The resolved request reaches Dify Agent through its private
`POST /execution-bindings/files/list`, `POST /execution-bindings/files/read`,
and `POST /execution-bindings/files/download` endpoints. Each operation receives a
`backend_binding_ref`, acquires a fresh RuntimeLease, performs the file action,
and releases the lease.
`BindingFileService` resolves relative paths from `workspace_dir`, `~` and
`~/...` from `home_dir`, and leaves absolute paths in the Binding filesystem
namespace. It does not enforce Workspace containment or reject `..`; the
selected backend's isolation policy remains authoritative. List and preview
run bounded inspection scripts through `RuntimeLease.commands`. Download runs
`dify-agent file upload --no-download-link` inside the Binding so bytes stream
directly from the runtime to Dify's existing ToolFile endpoint. Dify Agent
returns only the canonical ToolFile reference and releases the lease before
Dify API signs a browser URL.
The default Binding-download deadline chain leaves each caller time to receive
and normalize the lower layer's result: the sandbox CLI upload is 180 seconds,
`DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS` is 210 seconds,
Dify API's `AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS` is 240 seconds,
and `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS` is 3600 seconds.
`RuntimeLayout.home_dir` and `RuntimeLayout.workspace_dir` are canonical paths
inside the backend execution namespace. They are not host paths, product ids,
or request configuration. Shell commands start in `workspace_dir`, and `HOME`
is forced to `home_dir`. The standard temp variables `TMPDIR`, `TMP`, and `TEMP`
also point directly to `workspace_dir`, so the Workspace is both the command
`cwd` and temp space. On Local, sibling materialized Homes may exist in the same
shellctl namespace, while path isolation restricts the active lease to its own
Home plus the shared Workspace.
## Backend support
| Backend | Home Snapshot operations | Binding operations | Physical relationship |
| --- | --- | --- | --- |
| Local | Supported | Supported, including default empty Homes and attaching multiple Bindings to one Workspace | Snapshot directory, per-Binding materialized Home, and Workspace directory are separate. |
| E2B | Supported | Supported with template-backed default Homes, without shared-Workspace attachment | Binding and Workspace refs map to the same E2B resource; checkpoints use E2B snapshots. |
| Enterprise | Not implemented | Default-Home Binding creation, acquire, and coupled destroy are supported | Binding and Workspace refs map to one Gateway sandbox. Explicit Home Snapshot materialization fails fast. |
| OpenShell | Supported via directory copies on an operator-provided shared volume | Supported with image-backed default Homes, without shared-Workspace attachment | Binding and Workspace refs map to the same OpenShell sandbox, addressed by its stable name; snapshots live under `home-snapshots//` on the shared volume. Production deployments must use one workspace and one dedicated volume per tenant. |
Local creates a new Home for every Binding id. Destroying one Binding without
the Workspace leaves sibling Homes and the shared Workspace intact. Current E2B
rejects `existing_workspace_ref` with `shared_workspace_unsupported`, because
its Binding and Workspace are one Sandbox. It also rejects binding-only destroy.
OpenShell shares the E2B shape: one sandbox per Binding, no
`existing_workspace_ref`, no binding-only destroy. Neither path creates a
fallback Workspace or switches backends.
`DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS` limits continuous active time for an E2B
resource to one hour. The limit covers the complete Agent run held by one
RuntimeLease rather than an individual tool call. Its 3600-second default is
intentionally the same as `DIFY_AGENT_RUN_TIMEOUT_SECONDS`, but the two settings
remain independently configurable. Runtime resources pause on timeout, but this
resource setting does not own the Agent run terminal state. It is not a retention
TTL and does not delete paused resources or immutable snapshots.
See the [Shell module](../../user-manual/shell-layer/index.md) for request
composition, the [Operations Guide](../../guide/index.md) for Local and E2B
validation, and the [OpenShell guide](../../guide/openshell.md) for OpenShell
configuration and validation.
---
### Dify Agent Docs Dify Agent User Manual Execution Context Layer Index (`dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md`)
# Execution context module
`dify_agent.layers.execution_context.layer` declares Config, empty State and
Capability. Config carries tenant/user/app/invoke identity and correlation IDs.
Other modules refer to its registered name in their Config. Server-only daemon
settings and clients are borrowed from Deps.services. Knowledge retrieval
requires its complete caller identity before any external request.
The optional `tracing` field is an API-issued `ApplicationTracingContext`:
```json
{
"version": 1,
"run_id": "429cab49-8663-42b4-a701-ac1038ee4fa7",
"invocation_id": "95bdeed9-4652-4708-8322-b866f159ad62",
"trace_id": "81b617d638eb419ba2b209c14984d908",
"parent_span_id": "716db0b6c736b395",
"session_id": "conversation-id",
"capture_content": false,
"sampled": true
}
```
`run_id` identifies the API's persisted application trace. `invocation_id`
identifies this particular Agent execution; multiple nodes or attempts can
belong to one application trace. Both are UUIDs. The trace and parent span IDs
are nonzero, lowercase OpenTelemetry hex IDs (32 and 16 characters). The parent
is the API-owned message or Agent-node invocation, and is restored as the actual
OpenTelemetry parent rather than attached only as metadata. Tenant/app identity
continues to come from the containing execution context.
Application collection requires `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`
on the Agent server. The API owns sampling and content policy per invocation;
no third-party destination or credential is accepted in a run request. When an
application context is selected it replaces deployment trajectory instrumentation
for that invocation, including when `sampled` is false. Without an application
context, the existing deployment trajectory behavior is unchanged.
---
### Dify Agent Docs Dify Agent User Manual History Layer Index (`dify-agent/docs/dify-agent/user-manual/history-layer/index.md`)
# History module
`dify_agent.layers.history` declares Config, State and Capability. Config is
empty. State contains `messages`, encoded as JSON using Pydantic AI message
schemas. The runner explicitly loads initial message_history and writes the
captured history on every terminal outcome, preserving compaction and partial
responses. Current instructions are removed and unmatched trailing calls are
marked interrupted on failure or cancellation. The reserved name is `history`.
---
### Dify Agent Docs Dify Agent User Manual Plugin Llm Layer Index (`dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md`)
# Model module
`dify_agent.layers.dify_plugin.llm_layer` declares Config, State and Capability.
The reserved `llm` name selects model assembly. Public Config contains plugin,
provider, model, model settings, context window and an `execution_context` name.
The runtime builds a model through the Dify API metered gateway with borrowed
lifespan HTTP services. Credentials stay API-owned; no model/client is persisted.
---
### Dify Agent Docs Dify Agent User Manual Plugin Tool Layer Index (`dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md`)
# Plugin tool module
`dify_agent.layers.dify_plugin.tools_layer` declares Config, State and native
Toolset. The `tools` registry name accepts API-prepared declarations, parameters,
runtime values and model-facing schema, plus `execution_context` and optional
`shell` Config references. Hidden/default parameter merging, loose schemas and
observation mapping preserve the API-prepared contract. Sandbox paths use the
referenced live shell session to upload files; file mappings resolve signed URLs
through the borrowed Dify API client. Config and credentials are never snapshotted.
Each prepared tool includes `plugin_unique_identifier` (version and checksum)
alongside `plugin_id`. The daemon receives it as `X-Plugin-Unique-Identifier`
and executes that exact plugin package, even if the installed version changes
during the run. Tool clients are shared only within the same complete identifier.
Older configurations can omit the identifier and retain plugin-ID dispatch.
---
### Dify Agent Docs Dify Agent User Manual Prompt Layer Index (`dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md`)
# Prompt module
`dify_agent.layers.prompt` declares Config, State and native Toolset. Config
accepts `prefix`, `suffix` and `user` string fragments or lists. Prefix/suffix
become dynamic instructions; `user` contributes current user content. State is
empty. Instruction order is unspecified. Product names `agent_soul_prompt`,
`workflow_node_job_prompt`, and `workflow_user_prompt` map to this module.
---
### Dify Agent Docs Dify Agent User Manual Shell Layer Index (`dify-agent/docs/dify-agent/user-manual/shell-layer/index.md`)
# Shell module
`dify_agent.layers.shell.layer` declares Config, State and Capability. Config
contains CLI tools, environment values, secret names, redaction patterns and
`runtime` / optional `execution_context` references. Native ordering ensures an
active lease exists before shell bootstrap and config eager pulls.
The Capability exposes shell_run, shell_wait, shell_input and shell_interrupt
through a native sequential Toolset. JSON State holds initialized, job_ids and
job_offsets; live tokens remain in the run-scoped ShellSession. Bootstrap marks
initialized only on success. Exit cleanup removes tracked jobs and clears IDs,
offsets and credentials before Runtime releases the lease, including cancellation.
The API owns Workspace/Binding retirement. HOME is reusable system space; cwd
and TMPDIR/TMP/TEMP refer to the active Workspace.
---
### Dify Agent Docs Dify Agent User Manual Structured Output Layer Index (`dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md`)
# Structured output module
`dify_agent.layers.output.output_layer` declares Config, empty State and
Capability. The reserved `output` name accepts a top-level object JSON Schema,
optional description and strictness. The runner resolves native output_type
before running the agent. A fresh dynamic type exposes the schema and performs
JSON Schema validation in Pydantic AI's retry pipeline. The model-facing tool
name is final_output. Local `#/$defs/` references are supported; remote or
recursive references are rejected before I/O. Resume resubmits current Config.
---
### ADVANCED SETUP (`docs/ADVANCED_SETUP.md`)
# Advanced Setup
## Custom configurations
If you need to customize the configuration, edit `docker/.env`. The essential startup defaults live in [`docker/.env.example`](../docker/.env.example), and optional advanced variables are split under `docker/envs/` by theme. After making any changes, re-run `docker compose up -d` from the `docker` directory. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
## Metrics Monitoring with Grafana
Import the dashboard to Grafana, using Dify's PostgreSQL database as data source, to monitor metrics in granularity of apps, tenants, messages, and more.
- [Grafana Dashboard by @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Deployment with Kubernetes
If you'd like to configure a highly available setup, there are community-contributed [Helm Charts](https://helm.sh/) and YAML files which allow Dify to be deployed on Kubernetes.
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Using Terraform for Deployment
Deploy Dify to Cloud Platform with a single click using [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Using AWS CDK for Deployment
Deploy Dify to AWS with [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Using Alibaba Cloud Computing Nest
Quickly deploy Dify to Alibaba cloud with [Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Using Alibaba Cloud Data Management
One-Click deploy Dify to Alibaba Cloud with [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Deploy to AKS with Azure Devops Pipeline
One-Click deploy Dify to AKS with [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Using Sealos for Deployment
Deploy Dify with one click using the [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Ar SA ADVANCED SETUP (`docs/ar-SA/ADVANCED_SETUP.md`)
# الإعداد المتقدم
اضبط الإعدادات المحلية في `docker/.env`. يحتوي [`.env.example`](../../docker/.env.example) على القيم اللازمة للنشر الافتراضي فقط، وتوجد الإعدادات الاختيارية والخاصة بالخدمات في [`docker/envs/`](../../docker/envs/). انسخ القوالب المطلوبة دون اللاحقة `.example`. تكون الأولوية لقيم `.env`. بعد التعديل، شغّل `docker compose up -d` من `docker/`. راجع [دليل Docker](../../docker/README.md).
## مراقبة المقاييس باستخدام Grafana
استيراد لوحة التحكم إلى Grafana، باستخدام قاعدة بيانات PostgreSQL الخاصة بـ Dify كمصدر للبيانات، لمراقبة المقاييس بدقة للتطبيقات والمستأجرين والرسائل وغير ذلك.
- [لوحة تحكم Grafana بواسطة @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## النشر باستخدام Kubernetes
يوجد مجتمع خاص بـ [Helm Charts](https://helm.sh/) وملفات YAML التي تسمح بتنفيذ Dify على Kubernetes للنظام من الإيجابيات العلوية.
- [رسم بياني Helm من قبل @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [رسم بياني Helm من قبل @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [رسم بياني Helm من قبل @magicsong](https://github.com/magicsong/ai-charts)
- [ملف YAML من قبل @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [ملف YAML من قبل @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 جديد! ملفات YAML (تدعم Dify v1.6.0) بواسطة @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### استخدام Terraform للتوزيع
انشر Dify إلى منصة السحابة بنقرة واحدة باستخدام [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform بواسطة @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform بواسطة @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### استخدام AWS CDK للنشر
انشر Dify على AWS باستخدام [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK بواسطة @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK بواسطة @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### استخدام Alibaba Cloud للنشر
[بسرعة نشر Dify إلى سحابة علي بابا مع عش الحوسبة السحابية علي بابا](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### استخدام Alibaba Cloud Data Management للنشر
انشر Dify على علي بابا كلاود بنقرة واحدة باستخدام [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### استخدام Azure Devops Pipeline للنشر على AKS
انشر Dify على AKS بنقرة واحدة باستخدام [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### استخدام Sealos للنشر
انشر Dify بنقرة واحدة باستخدام [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Bn BD ADVANCED SETUP (`docs/bn-BD/ADVANCED_SETUP.md`)
# উন্নত সেটআপ
স্থানীয় সেটিংস `docker/.env`-এ পরিবর্তন করুন। [`.env.example`](../../docker/.env.example)-এ ডিফল্ট ডেপ্লয়মেন্টের প্রয়োজনীয় মান থাকে; ঐচ্ছিক ও পরিষেবা-নির্দিষ্ট সেটিংস [`docker/envs/`](../../docker/envs/)-এ রয়েছে। প্রয়োজনীয় টেমপ্লেটের `.example` প্রত্যয় বাদ দিয়ে কপি করুন। `.env`-এর মান অগ্রাধিকার পায়। পরিবর্তনের পরে `docker/` থেকে `docker compose up -d` চালান। [Docker নির্দেশিকা](../../docker/README.md) দেখুন।
## Grafana দিয়ে মেট্রিক্স মনিটরিং
Dify-এর PostgreSQL ডাটাবেসকে ডেটা সোর্স হিসাবে ব্যবহার করে, অ্যাপ, টেন্যান্ট, মেসেজ ইত্যাদির গ্র্যানুলারিটিতে মেট্রিক্স মনিটর করার জন্য Grafana-তে ড্যাশবোর্ড ইম্পোর্ট করুন।
- [@bowenliang123 কর্তৃক Grafana ড্যাশবোর্ড](https://github.com/bowenliang123/dify-grafana-dashboard)
## Kubernetes এর সাথে ডেপ্লয়মেন্ট
যদি আপনি একটি হাইলি এভেইলেবল সেটআপ কনফিগার করতে চান, তাহলে কমিউনিটি [Helm Charts](https://helm.sh/) এবং YAML ফাইল রয়েছে যা Dify কে Kubernetes-এ ডিপ্লয় করার প্রক্রিয়া বর্ণনা করে।
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 নতুন! YAML ফাইলসমূহ (Dify v1.6.0 সমর্থিত) তৈরি করেছেন @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### টেরাফর্ম ব্যবহার করে ডিপ্লয়
[terraform](https://www.terraform.io/) ব্যবহার করে এক ক্লিকেই ক্লাউড প্ল্যাটফর্মে Dify ডিপ্লয় করুন।
#### অ্যাজুর গ্লোবাল
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### গুগল ক্লাউড
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### AWS CDK ব্যবহার করে ডিপ্লয়
[CDK](https://aws.amazon.com/cdk/) দিয়ে AWS-এ Dify ডিপ্লয় করুন
#### AWS
- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud ব্যবহার করে ডিপ্লয়
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management ব্যবহার করে ডিপ্লয়
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### AKS-এ ডিপ্লয় করার জন্য Azure Devops Pipeline ব্যবহার
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) ব্যবহার করে Dify কে AKS-এ এক ক্লিকে ডিপ্লয় করুন
### Sealos ব্যবহার করে ডিপ্লয়
[Sealos App Store](https://sealos.io/products/app-store/dify/) ব্যবহার করে Dify-কে এক ক্লিকে ডিপ্লয় করুন
---
### De DE ADVANCED SETUP (`docs/de-DE/ADVANCED_SETUP.md`)
# Erweiterte Einstellungen
Konfigurieren Sie Ihre Installation in `docker/.env`. [`.env.example`](../../docker/.env.example) enthält die nötigen Startwerte für die Standardbereitstellung; optionale und dienstspezifische Einstellungen liegen unter [`docker/envs/`](../../docker/envs/). Kopieren Sie benötigte Vorlagen ohne die Endung `.example`. Werte aus `.env` haben Vorrang. Führen Sie nach Änderungen `docker compose up -d` in `docker/` aus. Siehe [Docker-Anleitung](../../docker/README.md).
## Metriküberwachung mit Grafana
Importieren Sie das Dashboard in Grafana, wobei Sie die PostgreSQL-Datenbank von Dify als Datenquelle verwenden, um Metriken in der Granularität von Apps, Mandanten, Nachrichten und mehr zu überwachen.
- [Grafana-Dashboard von @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Bereitstellung mit Kubernetes
Falls Sie eine hochverfügbare Konfiguration einrichten möchten, gibt es von der Community bereitgestellte [Helm Charts](https://helm.sh/) und YAML-Dateien, die es ermöglichen, Dify auf Kubernetes bereitzustellen.
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Terraform für die Bereitstellung verwenden
Stellen Sie Dify mit nur einem Klick mithilfe von [terraform](https://www.terraform.io/) auf einer Cloud-Plattform bereit.
#### Azure Global
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Verwendung von AWS CDK für die Bereitstellung
Bereitstellung von Dify auf AWS mit [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Ein-Klick-Bereitstellung von Dify in der Alibaba Cloud mit [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Verwendung von Azure Devops Pipeline für AKS-Bereitstellung
Stellen Sie Dify mit einem Klick in AKS bereit, indem Sie [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) verwenden
### Bereitstellung mit Sealos
Stellen Sie Dify mit einem Klick über den [Sealos App Store](https://sealos.io/products/app-store/dify/) bereit
---
### De DE CONTRIBUTING (`docs/de-DE/CONTRIBUTING.md`)
# MITWIRKEN
Sie möchten also zu Dify beitragen - das ist großartig, wir können es kaum erwarten zu sehen, was Sie entwickeln. Als Startup mit begrenztem Personal und Finanzierung haben wir große Ambitionen, den intuitivsten Workflow für die Entwicklung und Verwaltung von LLM-Anwendungen zu gestalten. Jede Hilfe aus der Community zählt wirklich.
Wir müssen wendig sein und schnell liefern, aber wir möchten auch sicherstellen, dass Mitwirkende wie Sie eine möglichst reibungslose Erfahrung beim Beitragen haben. Wir haben diesen Leitfaden zusammengestellt, damit Sie sich schnell mit der Codebasis und unserer Arbeitsweise mit Mitwirkenden vertraut machen können.
Dieser Leitfaden ist, wie Dify selbst, in ständiger Entwicklung. Wir sind dankbar für Ihr Verständnis, falls er manchmal hinter dem eigentlichen Projekt zurückbleibt, und begrüßen jedes Feedback zur Verbesserung.
Bitte nehmen Sie sich einen Moment Zeit, um unsere [Lizenz- und Mitwirkungsvereinbarung](../../LICENSE) zu lesen. Die Community hält sich außerdem an den [Verhaltenskodex](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
## Bevor Sie loslegen
Suchen Sie nach einer Aufgabe? Durchstöbern Sie unsere [Einsteiger-Issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) und wählen Sie eines zum Einstieg!
Haben Sie eine neue Modell-Runtime oder ein Tool hinzuzufügen? Öffnen Sie einen PR in unserem [Plugin-Repository](https://github.com/langgenius/dify-plugins).
Möchten Sie eine bestehende Modell-Runtime oder ein Tool aktualisieren oder Bugs beheben? Besuchen Sie unser [offizielles Plugin-Repository](https://github.com/langgenius/dify-official-plugins)!
Vergessen Sie nicht, in der PR-Beschreibung ein bestehendes Issue zu verlinken oder ein neues zu erstellen.
### Fehlermeldungen
Melden Sie Sicherheitslücken gemäß der [Sicherheitsrichtlinie](../../SECURITY.md) vertraulich, statt ein öffentliches Issue zu erstellen.
> [!WICHTIG]
> Bitte stellen Sie sicher, dass Sie folgende Informationen bei der Einreichung eines Fehlerberichts angeben:
- Ein klarer und beschreibender Titel
- Eine detaillierte Beschreibung des Fehlers, einschließlich Fehlermeldungen
- Schritte zur Reproduktion des Fehlers
- Erwartetes Verhalten
- **Logs** bei Backend-Problemen (sehr wichtig, zu finden in docker-compose logs)
- Screenshots oder Videos, falls zutreffend
Unsere Priorisierung:
| Fehlertyp | Priorität |
| ------------------------------------------------------------ | --------------- |
| Fehler in Kernfunktionen (Cloud-Service, Login nicht möglich, Anwendungen funktionieren nicht) | Kritisch |
| Nicht-kritische Fehler, Leistungsverbesserungen | Mittlere Priorität |
| Kleinere Korrekturen (Tippfehler, verwirrende aber funktionierende UI) | Niedrige Priorität |
### Feature-Anfragen
> [!HINWEIS]
> Bitte stellen Sie sicher, dass Sie folgende Informationen bei der Einreichung einer Feature-Anfrage angeben:
- Ein klarer und beschreibender Titel
- Eine detaillierte Beschreibung des Features
- Ein Anwendungsfall für das Feature
- Zusätzlicher Kontext oder Screenshots zur Feature-Anfrage
Unsere Priorisierung:
| Feature-Typ | Priorität |
| ------------------------------------------------------------ | --------------- |
| Hochprioritäre Features (durch Teammitglied gekennzeichnet) | Hohe Priorität |
| Beliebte Feature-Anfragen aus unserem [Community-Feedback-Board](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Mittlere Priorität |
| Nicht-Kernfunktionen und kleinere Verbesserungen | Niedrige Priorität |
| Wertvoll, aber nicht dringend | Zukunfts-Feature |
## Einreichen Ihres PRs
### Pull-Request-Prozess
1. Repository forken
1. Vor dem Erstellen eines PRs bitte ein Issue zur Diskussion der Änderungen erstellen
1. Einen neuen Branch für Ihre Änderungen erstellen
1. Tests ergänzen oder aktualisieren, wenn die Änderung beobachtbares Verhalten beeinflusst oder ein relevantes Regressionsrisiko birgt.
1. Sicherstellen, dass Ihr Code die bestehenden Tests besteht
1. Issue in der PR-Beschreibung verlinken (`fixes #`)
1. Auf den Merge warten!
### Projekt einrichten
#### Frontend
Für die Einrichtung des Frontend-Service folgen Sie bitte unserer ausführlichen [Anleitung](../../web/README.md) in der Datei `web/README.md`.
#### Backend
Für die Einrichtung des Backend-Service folgen Sie bitte unseren detaillierten [Anweisungen](../../api/README.md) in der Datei `api/README.md`.
## Hilfe bekommen
Wenn Sie beim Mitwirken Fragen haben oder nicht weiterkommen, stellen Sie Ihre Fragen einfach im entsprechenden GitHub Issue oder besuchen Sie unseren [Discord](https://discord.gg/8Tpq4AcN9c) für einen schnellen Austausch.
---
### Es ES ADVANCED SETUP (`docs/es-ES/ADVANCED_SETUP.md`)
# Configuración avanzada
Configura la instalación en `docker/.env`. [`.env.example`](../../docker/.env.example) contiene los valores necesarios para el despliegue predeterminado; las opciones avanzadas y específicas de cada servicio están en [`docker/envs/`](../../docker/envs/). Copia las plantillas necesarias sin el sufijo `.example`. Los valores de `.env` tienen prioridad. Tras los cambios, ejecuta `docker compose up -d` desde `docker/`. Consulta la [guía de Docker](../../docker/README.md).
## Monitorización de Métricas con Grafana
Importe el panel a Grafana, utilizando la base de datos PostgreSQL de Dify como fuente de datos, para monitorizar métricas en granularidad de aplicaciones, inquilinos, mensajes y más.
- [Panel de Grafana por @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Implementación con Kubernetes
Si desea configurar una configuración de alta disponibilidad, la comunidad proporciona [Gráficos Helm](https://helm.sh/) y archivos YAML, a través de los cuales puede desplegar Dify en Kubernetes.
- [Gráfico Helm por @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Gráfico Helm por @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Gráfico Helm por @magicsong](https://github.com/magicsong/ai-charts)
- [Ficheros YAML por @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [Ficheros YAML por @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 ¡NUEVO! Archivos YAML (compatible con Dify v1.6.0) por @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Uso de Terraform para el despliegue
Despliega Dify en una plataforma en la nube con un solo clic utilizando [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform por @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform por @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Usando AWS CDK para el Despliegue
Despliegue Dify en AWS usando [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK por @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK por @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Despliega Dify en Alibaba Cloud con un solo clic con [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Uso de Azure Devops Pipeline para implementar en AKS
Implementa Dify en AKS con un clic usando [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Implementación con Sealos
Despliega Dify con un solo clic desde [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Es ES CONTRIBUTING (`docs/es-ES/CONTRIBUTING.md`)
# CONTRIBUIR
Así que estás buscando contribuir a Dify - eso es fantástico, estamos ansiosos por ver lo que haces. Como una startup con personal y financiación limitados, tenemos grandes ambiciones de diseñar el flujo de trabajo más intuitivo para construir y gestionar aplicaciones LLM. Cualquier ayuda de la comunidad cuenta, realmente.
Necesitamos ser ágiles y enviar rápidamente dado donde estamos, pero también queremos asegurarnos de que colaboradores como tú obtengan una experiencia lo más fluida posible al contribuir. Hemos elaborado esta guía de contribución con ese propósito, con el objetivo de familiarizarte con la base de código y cómo trabajamos con los colaboradores, para que puedas pasar rápidamente a la parte divertida.
Esta guía, como Dify mismo, es un trabajo en constante progreso. Agradecemos mucho tu comprensión si a veces se queda atrás del proyecto real, y damos la bienvenida a cualquier comentario para que podamos mejorar.
En términos de licencia, por favor tómate un minuto para leer nuestro breve [Acuerdo de Licencia y Colaborador](../../LICENSE). La comunidad también se adhiere al [código de conducta](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
## Antes de empezar
¿Buscas algo en lo que trabajar? Explora nuestros [buenos primeros issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) y elige uno para comenzar.
¿Tienes un nuevo modelo o herramienta genial para añadir? Abre un PR en nuestro [repositorio de plugins](https://github.com/langgenius/dify-plugins) y muéstranos lo que has construido.
¿Necesitas actualizar un modelo existente, herramienta o corregir algunos errores? Dirígete a nuestro [repositorio oficial de plugins](https://github.com/langgenius/dify-official-plugins) y haz tu magia.
¡Únete a la diversión, contribuye y construyamos algo increíble juntos! 💡✨
No olvides vincular un issue existente o abrir uno nuevo en la descripción del PR.
### Informes de errores
Informa de las vulnerabilidades en privado según la [política de seguridad](../../SECURITY.md), sin abrir un issue público.
> [!IMPORTANT]
> Por favor, asegúrate de incluir la siguiente información al enviar un informe de error:
- Un título claro y descriptivo
- Una descripción detallada del error, incluyendo cualquier mensaje de error
- Pasos para reproducir el error
- Comportamiento esperado
- **Logs**, si están disponibles, para problemas del backend, esto es realmente importante, puedes encontrarlos en los logs de docker-compose
- Capturas de pantalla o videos, si es aplicable
Cómo priorizamos:
| Tipo de Issue | Prioridad |
| ------------------------------------------------------------ | --------------- |
| Errores en funciones principales (servicio en la nube, no poder iniciar sesión, aplicaciones que no funcionan) | Crítica |
| Errores no críticos, mejoras de rendimiento | Prioridad Media |
| Correcciones menores (errores tipográficos, UI confusa pero funcional) | Prioridad Baja |
### Solicitudes de funcionalidades
> [!NOTE]
> Por favor, asegúrate de incluir la siguiente información al enviar una solicitud de funcionalidad:
- Un título claro y descriptivo
- Una descripción detallada de la funcionalidad
- Un caso de uso para la funcionalidad
- Cualquier otro contexto o capturas de pantalla sobre la solicitud de funcionalidad
Cómo priorizamos:
| Tipo de Funcionalidad | Prioridad |
| ------------------------------------------------------------ | --------------- |
| Funcionalidades de alta prioridad etiquetadas por un miembro del equipo | Prioridad Alta |
| Solicitudes populares de funcionalidades de nuestro [tablero de comentarios de la comunidad](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Prioridad Media |
| Funcionalidades no principales y mejoras menores | Prioridad Baja |
| Valiosas pero no inmediatas | Futura-Funcionalidad |
## Enviando tu PR
### Proceso de Pull Request
1. Haz un fork del repositorio
1. Antes de redactar un PR, por favor crea un issue para discutir los cambios que quieres hacer
1. Crea una nueva rama para tus cambios
1. Añade o actualiza pruebas cuando el cambio afecte al comportamiento observable o implique un riesgo significativo de regresión.
1. Asegúrate de que tu código pasa las pruebas existentes
1. Por favor vincula el issue en la descripción del PR, `fixes #`
1. ¡Fusiona tu código!
### Configuración del proyecto
#### Frontend
Para configurar el servicio frontend, por favor consulta nuestra [guía completa](../../web/README.md) en el archivo `web/README.md`. Este documento proporciona instrucciones detalladas para ayudarte a configurar el entorno frontend correctamente.
#### Backend
Para configurar el servicio backend, por favor consulta nuestras [instrucciones detalladas](../../api/README.md) en el archivo `api/README.md`. Este documento contiene una guía paso a paso para ayudarte a poner en marcha el backend sin problemas.
## Obteniendo Ayuda
Si alguna vez te quedas atascado o tienes una pregunta urgente mientras contribuyes, simplemente envíanos tus consultas a través del issue relacionado de GitHub, o únete a nuestro [Discord](https://discord.gg/8Tpq4AcN9c) para una charla rápida.
---
### Fr FR ADVANCED SETUP (`docs/fr-FR/ADVANCED_SETUP.md`)
# Configuration avancée
Configurez votre installation dans `docker/.env`. [`.env.example`](../../docker/.env.example) contient les paramètres nécessaires au déploiement par défaut ; les options avancées et propres aux services sont dans [`docker/envs/`](../../docker/envs/). Copiez les modèles nécessaires sans le suffixe `.example`. Les valeurs de `.env` sont prioritaires. Après modification, exécutez `docker compose up -d` depuis `docker/`. Consultez le [guide Docker](../../docker/README.md).
## Surveillance des Métriques avec Grafana
Importez le tableau de bord dans Grafana, en utilisant la base de données PostgreSQL de Dify comme source de données, pour surveiller les métriques avec une granularité d'applications, de locataires, de messages et plus.
- [Tableau de bord Grafana par @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Déploiement avec Kubernetes
Si vous souhaitez configurer une configuration haute disponibilité, la communauté fournit des [Helm Charts](https://helm.sh/) et des fichiers YAML, à travers lesquels vous pouvez déployer Dify sur Kubernetes.
- [Helm Chart par @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart par @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart par @magicsong](https://github.com/magicsong/ai-charts)
- [Fichier YAML par @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [Fichier YAML par @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NOUVEAU ! Fichiers YAML (compatible avec Dify v1.6.0) par @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Utilisation de Terraform pour le déploiement
Déployez Dify sur une plateforme cloud en un clic en utilisant [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform par @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform par @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Utilisation d'AWS CDK pour le déploiement
Déployez Dify sur AWS en utilisant [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK par @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK par @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Déployez Dify en un clic sur Alibaba Cloud avec [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Utilisation d'Azure Devops Pipeline pour déployer sur AKS
Déployez Dify sur AKS en un clic en utilisant [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Déploiement avec Sealos
Déployez Dify en un clic depuis le [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Fr FR CONTRIBUTING (`docs/fr-FR/CONTRIBUTING.md`)
# CONTRIBUER
Vous cherchez donc à contribuer à Dify - c'est fantastique, nous avons hâte de voir ce que vous allez faire. En tant que startup avec un personnel et un financement limités, nous avons de grandes ambitions pour concevoir le flux de travail le plus intuitif pour construire et gérer des applications LLM. Toute aide de la communauté compte, vraiment.
Nous devons être agiles et livrer rapidement compte tenu de notre position, mais nous voulons aussi nous assurer que des contributeurs comme vous obtiennent une expérience aussi fluide que possible lors de leur contribution. Nous avons élaboré ce guide de contribution dans ce but, visant à vous familiariser avec la base de code et comment nous travaillons avec les contributeurs, afin que vous puissiez rapidement passer à la partie amusante.
Ce guide, comme Dify lui-même, est un travail en constante évolution. Nous apprécions grandement votre compréhension si parfois il est en retard par rapport au projet réel, et nous accueillons tout commentaire pour nous aider à nous améliorer.
En termes de licence, veuillez prendre une minute pour lire notre bref [Accord de Licence et de Contributeur](../../LICENSE). La communauté adhère également au [code de conduite](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
## Avant de vous lancer
Vous cherchez quelque chose à réaliser ? Parcourez nos [problèmes pour débutants](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) et choisissez-en un pour commencer !
Vous avez un nouveau modèle ou un nouvel outil à ajouter ? Ouvrez une PR dans notre [dépôt de plugins](https://github.com/langgenius/dify-plugins) et montrez-nous ce que vous avez créé.
Vous devez mettre à jour un modèle existant, un outil ou corriger des bugs ? Rendez-vous sur notre [dépôt officiel de plugins](https://github.com/langgenius/dify-official-plugins) et faites votre magie !
Rejoignez l'aventure, contribuez, et construisons ensemble quelque chose d'extraordinaire ! 💡✨
N'oubliez pas de lier un problème existant ou d'ouvrir un nouveau problème dans la description de votre PR.
### Rapports de bugs
Signalez les vulnérabilités en privé selon la [politique de sécurité](../../SECURITY.md), sans ouvrir d’issue publique.
> [!IMPORTANT]
> Veuillez vous assurer d'inclure les informations suivantes lors de la soumission d'un rapport de bug :
- Un titre clair et descriptif
- Une description détaillée du bug, y compris tous les messages d'erreur
- Les étapes pour reproduire le bug
- Comportement attendu
- **Logs**, si disponibles, pour les problèmes de backend, c'est vraiment important, vous pouvez les trouver dans les logs de docker-compose
- Captures d'écran ou vidéos, si applicable
Comment nous priorisons :
| Type de Problème | Priorité |
| ------------------------------------------------------------ | --------------- |
| Bugs dans les fonctions principales (service cloud, impossibilité de se connecter, applications qui ne fonctionnent pas) | Critique |
| Bugs non critiques, améliorations de performance | Priorité Moyenne |
| Corrections mineures (fautes de frappe, UI confuse mais fonctionnelle) | Priorité Basse |
### Demandes de fonctionnalités
> [!NOTE]
> Veuillez vous assurer d'inclure les informations suivantes lors de la soumission d'une demande de fonctionnalité :
- Un titre clair et descriptif
- Une description détaillée de la fonctionnalité
- Un cas d'utilisation pour la fonctionnalité
- Tout autre contexte ou captures d'écran concernant la demande de fonctionnalité
Comment nous priorisons :
| Type de Fonctionnalité | Priorité |
| ------------------------------------------------------------ | --------------- |
| Fonctionnalités hautement prioritaires étiquetées par un membre de l'équipe | Priorité Haute |
| Demandes populaires de fonctionnalités de notre [tableau de feedback communautaire](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Priorité Moyenne |
| Fonctionnalités non essentielles et améliorations mineures | Priorité Basse |
| Précieuses mais non immédiates | Fonctionnalité Future |
## Soumettre votre PR
### Processus de Pull Request
1. Forkez le dépôt
1. Avant de rédiger une PR, veuillez créer un problème pour discuter des changements que vous souhaitez apporter
1. Créez une nouvelle branche pour vos changements
1. Ajoutez ou mettez à jour les tests si le changement affecte un comportement observable ou présente un risque significatif de régression.
1. Assurez-vous que votre code passe les tests existants
1. Veuillez lier le problème dans la description de la PR, `fixes #`
1. Faites fusionner votre code !
### Configuration du projet
#### Frontend
Pour configurer le service frontend, veuillez consulter notre [guide complet](../../web/README.md) dans le fichier `web/README.md`. Ce document fournit des instructions détaillées pour vous aider à configurer correctement l'environnement frontend.
#### Backend
Pour configurer le service backend, veuillez consulter nos [instructions détaillées](../../api/README.md) dans le fichier `api/README.md`. Ce document contient un guide étape par étape pour vous aider à faire fonctionner le backend sans problème.
## Obtenir de l'aide
Si jamais vous êtes bloqué ou avez une question urgente en contribuant, envoyez-nous simplement vos questions via le problème GitHub concerné, ou rejoignez notre [Discord](https://discord.gg/8Tpq4AcN9c) pour une discussion rapide.
---
### Hi IN ADVANCED SETUP (`docs/hi-IN/ADVANCED_SETUP.md`)
# उन्नत सेटअप
## कस्टम कॉन्फ़िगरेशन
स्थानीय सेटिंग्स `docker/.env` में बदलें। [`.env.example`](../../docker/.env.example) में डिफ़ॉल्ट परिनियोजन के लिए आवश्यक मान हैं; वैकल्पिक और सेवा-विशिष्ट सेटिंग्स [`docker/envs/`](../../docker/envs/) में हैं। ज़रूरी टेम्पलेट को `.example` प्रत्यय हटाकर कॉपी करें। `.env` के मान प्राथमिकता लेते हैं। बदलाव के बाद `docker/` से `docker compose up -d` चलाएँ। [Docker गाइड](../../docker/README.md) देखें।
## Grafana के साथ मेट्रिक्स मॉनिटरिंग
Grafana में Dify के PostgreSQL डेटाबेस को डेटा स्रोत के रूप में उपयोग करते हुए डैशबोर्ड आयात करें, ताकि आप ऐप्स, टेनेंट्स, संदेशों आदि के स्तर पर मेट्रिक्स की निगरानी कर सकें।
- [Grafana Dashboard by @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Kubernetes के साथ डिप्लॉयमेंट
यदि आप उच्च उपलब्धता (high-availability) सेटअप कॉन्फ़िगर करना चाहते हैं, तो समुदाय द्वारा योगदान किए गए [Helm Charts](https://helm.sh/) और YAML फ़ाइलें उपलब्ध हैं जो Dify को Kubernetes पर डिप्लॉय करने की अनुमति देती हैं।
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### डिप्लॉयमेंट के लिए Terraform का उपयोग
[terraform](https://www.terraform.io/) का उपयोग करके एक क्लिक में Dify को क्लाउड प्लेटफ़ॉर्म पर डिप्लॉय करें।
#### Azure Global
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### डिप्लॉयमेंट के लिए AWS CDK का उपयोग
[CDK](https://aws.amazon.com/cdk/) का उपयोग करके Dify को AWS पर डिप्लॉय करें।
#### AWS
- [AWS CDK by @KevinZhao (EKS आधारित)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS आधारित)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud Computing Nest का उपयोग
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88) के साथ Dify को Alibaba Cloud पर तेज़ी से डिप्लॉय करें।
### Alibaba Cloud Data Management का उपयोग
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/) के साथ एक क्लिक में Dify को Alibaba Cloud पर डिप्लॉय करें।
### Azure Devops Pipeline के साथ AKS पर डिप्लॉय करें
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) के साथ एक क्लिक में Dify को AKS पर डिप्लॉय करें।
### Sealos के साथ डिप्लॉय करें
[Sealos App Store](https://sealos.io/products/app-store/dify/) के साथ एक क्लिक में Dify को डिप्लॉय करें।
---
### Hi IN CONTRIBUTING (`docs/hi-IN/CONTRIBUTING.md`)
# योगदान (CONTRIBUTING)
तो आप Dify में योगदान देना चाहते हैं — यह शानदार है, हम उत्सुक हैं यह देखने के लिए कि आप क्या बनाते हैं। सीमित टीम और फंडिंग वाले एक स्टार्टअप के रूप में, हमारा बड़ा लक्ष्य LLM एप्लिकेशनों के निर्माण और प्रबंधन के लिए सबसे सहज वर्कफ़्लो डिज़ाइन करना है। समुदाय से मिलने वाली कोई भी मदद वास्तव में मायने रखती है।
हमारे वर्तमान चरण को देखते हुए हमें तेज़ी से काम करना और डिलीवर करना होता है, लेकिन हम यह भी सुनिश्चित करना चाहते हैं कि आपके जैसे योगदानकर्ताओं के लिए योगदान देने का अनुभव यथासंभव सरल और सुगम हो।\
इसी उद्देश्य से हमने यह योगदान गाइड तैयार किया है, ताकि आप कोडबेस से परिचित हो सकें और जान सकें कि हम योगदानकर्ताओं के साथ कैसे काम करते हैं — ताकि आप जल्दी से मज़ेदार हिस्से पर पहुँच सकें।
यह गाइड, Dify की तरह ही, एक निरंतर विकसित होता दस्तावेज़ है। यदि यह कभी-कभी वास्तविक प्रोजेक्ट से पीछे रह जाए तो हम आपके समझ के लिए आभारी हैं, और सुधार के लिए किसी भी सुझाव का स्वागत करते हैं।
लाइसेंसिंग के संदर्भ में, कृपया एक मिनट निकालकर हमारा छोटा [License and Contributor Agreement](../../LICENSE) पढ़ें।\
समुदाय [code of conduct](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md) का भी पालन करता है।
## शुरू करने से पहले
कुछ योगदान करने की तलाश में हैं? हमारे [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) ब्राउज़ करें और किसी एक को चुनकर शुरुआत करें!
कोई नया मॉडल रनटाइम या टूल जोड़ना चाहते हैं? हमारे [plugin repo](https://github.com/langgenius/dify-plugins) में एक PR खोलें और हमें दिखाएँ कि आपने क्या बनाया है।
किसी मौजूदा मॉडल रनटाइम या टूल को अपडेट करना है, या कुछ बग्स को ठीक करना है? हमारे [official plugin repo](https://github.com/langgenius/dify-official-plugins) पर जाएँ और अपना जादू दिखाएँ!
मज़े में शामिल हों, योगदान दें, और चलिए मिलकर कुछ शानदार बनाते हैं! 💡✨
PR के विवरण में मौजूदा issue को लिंक करना या नया issue खोलना न भूलें।
### बग रिपोर्ट (Bug reports)
सुरक्षा खामियों की रिपोर्ट सार्वजनिक issue में करने के बजाय [सुरक्षा नीति](../../SECURITY.md) के अनुसार निजी तौर पर करें।
> [!IMPORTANT]\
> कृपया बग रिपोर्ट सबमिट करते समय निम्नलिखित जानकारी अवश्य शामिल करें:
- एक स्पष्ट और वर्णनात्मक शीर्षक
- बग का विस्तृत विवरण, जिसमें कोई भी त्रुटि संदेश (error messages) शामिल हो
- बग को पुन: उत्पन्न करने के चरण
- अपेक्षित व्यवहार
- **लॉग्स**, यदि उपलब्ध हों — बैकएंड समस्याओं के लिए यह बहुत महत्वपूर्ण है, आप इन्हें docker-compose logs में पा सकते हैं
- स्क्रीनशॉट या वीडियो (यदि लागू हो)
हम प्राथमिकता कैसे तय करते हैं:
| समस्या प्रकार (Issue Type) | प्राथमिकता (Priority) |
| ------------------------------------------------------------ | --------------- |
| मुख्य कार्यों में बग (क्लाउड सेवा, लॉगिन न होना, एप्लिकेशन न चलना) | गंभीर (Critical) |
| गैर-गंभीर बग, प्रदर्शन सुधार | मध्यम प्राथमिकता (Medium Priority) |
| छोटे सुधार (टाइपो, भ्रमित करने वाला लेकिन काम करने वाला UI) | निम्न प्राथमिकता (Low Priority) |
### फ़ीचर अनुरोध (Feature requests)
> [!NOTE]\
> कृपया फ़ीचर अनुरोध सबमिट करते समय निम्नलिखित जानकारी अवश्य शामिल करें:
- एक स्पष्ट और वर्णनात्मक शीर्षक
- फ़ीचर का विस्तृत विवरण
- फ़ीचर के उपयोग का मामला (use case)
- फ़ीचर अनुरोध से संबंधित कोई अन्य संदर्भ या स्क्रीनशॉट
हम प्राथमिकता कैसे तय करते हैं:
| फ़ीचर प्रकार (Feature Type) | प्राथमिकता (Priority) |
| ------------------------------------------------------------ | --------------- |
| किसी टीम सदस्य द्वारा उच्च प्राथमिकता (High-Priority) के रूप में चिह्नित फ़ीचर | उच्च प्राथमिकता (High Priority) |
| हमारे [community feedback board](https://github.com/langgenius/dify/discussions/categories/feedbacks) से लोकप्रिय फ़ीचर अनुरोध | मध्यम प्राथमिकता (Medium Priority) |
| गैर-मुख्य फ़ीचर्स और छोटे सुधार | निम्न प्राथमिकता (Low Priority) |
| मूल्यवान लेकिन तात्कालिक नहीं | भविष्य का फ़ीचर (Future-Feature) |
## अपना PR सबमिट करना (Submitting your PR)
### पुल रिक्वेस्ट प्रक्रिया (Pull Request Process)
1. रिपॉज़िटरी को Fork करें
1. PR ड्राफ्ट करने से पहले, कृपया अपने बदलावों पर चर्चा करने के लिए एक issue बनाएँ
1. अपने परिवर्तनों के लिए एक नई शाखा (branch) बनाएँ
1. बदलाव से प्रत्यक्ष व्यवहार प्रभावित हो या रिग्रेशन का महत्वपूर्ण जोखिम हो, तो टेस्ट जोड़ें या अपडेट करें।
1. सुनिश्चित करें कि आपका कोड मौजूदा टेस्ट पास करता है
1. PR विवरण में issue लिंक करें, जैसे: `fixes #`
1. मर्ज हो जाएँ! 🎉
### प्रोजेक्ट सेटअप करें (Setup the project)
#### फ्रंटएंड (Frontend)
फ्रंटएंड सेवा सेटअप करने के लिए, कृपया हमारी विस्तृत [guide](../../web/README.md) देखें जो `web/README.md` फ़ाइल में उपलब्ध है।\
यह दस्तावेज़ आपको फ्रंटएंड वातावरण को सही ढंग से सेटअप करने के लिए विस्तृत निर्देश प्रदान करता है।
#### बैकएंड (Backend)
बैकएंड सेवा सेटअप करने के लिए, कृपया हमारी विस्तृत [instructions](../../api/README.md) देखें जो `api/README.md` फ़ाइल में दी गई हैं।\
यह दस्तावेज़ चरण-दर-चरण मार्गदर्शन प्रदान करता है जिससे आप बैकएंड को सुचारू रूप से चला सकें।
## सहायता प्राप्त करना (Getting Help)
यदि योगदान करते समय आप कहीं अटक जाएँ या कोई महत्वपूर्ण प्रश्न हो, तो संबंधित GitHub issue के माध्यम से हमें अपने प्रश्न भेजें, या त्वरित बातचीत के लिए हमारे [Discord](https://discord.gg/8Tpq4AcN9c) पर जुड़ें।
---
### It IT ADVANCED SETUP (`docs/it-IT/ADVANCED_SETUP.md`)
# Configurazioni Avanzate
Configura l’installazione in `docker/.env`. [`.env.example`](../../docker/.env.example) contiene i valori necessari per il deployment predefinito; le opzioni avanzate e specifiche dei servizi sono in [`docker/envs/`](../../docker/envs/). Copia i modelli necessari senza il suffisso `.example`. I valori di `.env` hanno la precedenza. Dopo le modifiche, esegui `docker compose up -d` da `docker/`. Consulta la [guida Docker](../../docker/README.md).
## Monitoraggio delle Metriche con Grafana
Importate la dashboard in Grafana, utilizzando il database PostgreSQL di Dify come origine dati, per monitorare le metriche a livello di app, tenant, messaggi e altro ancora.
- [Dashboard Grafana di @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Distribuzione con Kubernetes
Se desiderate configurare un'installazione ad alta disponibilità, ci sono [Helm Charts](https://helm.sh/) e file YAML forniti dalla community che consentono di distribuire Dify su Kubernetes.
- [Helm Chart di @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart di @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart di @magicsong](https://github.com/magicsong/ai-charts)
- [File YAML di @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [File YAML di @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NUOVO! File YAML (Supporta Dify v1.6.0) di @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Utilizzo di Terraform per la Distribuzione
Distribuite Dify con un solo clic su una piattaforma cloud utilizzando [terraform](https://www.terraform.io/).
#### Azure Global
- [Azure Terraform di @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform di @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Utilizzo di AWS CDK per la Distribuzione
Distribuzione di Dify su AWS con [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK di @KevinZhao (basato su EKS)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK di @tmokmss (basato su ECS)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Distribuzione con un clic di Dify su Alibaba Cloud con [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Utilizzo di Azure DevOps Pipeline per la Distribuzione su AKS
Distribuite Dify con un clic in AKS utilizzando [Azure DevOps Pipeline Helm Chart di @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Distribuzione con Sealos
Distribuite Dify con un clic tramite [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Ja JP ADVANCED SETUP (`docs/ja-JP/ADVANCED_SETUP.md`)
# 高度なセットアップ
ローカル設定は `docker/.env` に記入します。[`.env.example`](../../docker/.env.example) には標準デプロイに必要な設定のみが含まれ、オプションやサービス固有の設定は [`docker/envs/`](../../docker/envs/) にあります。必要なテンプレートを `.example` 接尾辞なしでコピーしてください。`.env` の値が優先されます。変更後は `docker/` で `docker compose up -d` を実行します。詳細は [Docker ガイド](../../docker/README.md)を参照してください。
## Grafanaを使用したメトリクス監視
Grafanaにダッシュボードをインポートし、DifyのPostgreSQLデータベースをデータソースとして使用して、アプリ、テナント、メッセージなどの粒度でメトリクスを監視します。
- [@bowenliang123によるGrafanaダッシュボード](https://github.com/bowenliang123/dify-grafana-dashboard)
## Kubernetesでのデプロイ
高可用性設定を設定する必要がある場合、コミュニティは[Helm Charts](https://helm.sh/)とYAMLファイルにより、DifyをKubernetesにデプロイすることができます。
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 新着！YAML ファイル（Dify v1.6.0 対応）by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Terraformを使用したデプロイ
[terraform](https://www.terraform.io/) を使用して、ワンクリックでDifyをクラウドプラットフォームにデプロイします
#### Azure Global
- [@nikawangによるAzure Terraform](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [@sotazumによるGoogle Cloud Terraform](https://github.com/DeNA/dify-google-cloud-terraform)
### AWS CDK を使用したデプロイ
[CDK](https://aws.amazon.com/cdk/) を使用して、DifyをAWSにデプロイします
#### AWS
- [@KevinZhaoによるAWS CDK (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [@tmokmssによるAWS CDK (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/) を利用して、DifyをAlibaba Cloudへワンクリックでデプロイできます
### AKSへのデプロイにAzure Devops Pipelineを使用
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)を使用してDifyをAKSにワンクリックでデプロイ
### Sealosを使用したデプロイ
[Sealos App Store](https://sealos.io/products/app-store/dify/)を使用してDifyをワンクリックでデプロイできます
---
### Ja JP CONTRIBUTING (`docs/ja-JP/CONTRIBUTING.md`)
# 貢献ガイド
Difyに貢献しようとお考えですか？素晴らしいですね。私たちは、あなたがどのような貢献をしてくださるのか、とても楽しみにしています。スタートアップとして限られた人員と資金の中で、LLMアプリケーションの構築と管理のための最も直感的なワークフローを設計するという大きな目標を持っています。コミュニティからのあらゆる支援が、本当に重要な意味を持ちます。
私たちは迅速に開発を進める必要がありますが、同時に貢献者の皆様にとってスムーズな経験を提供したいと考えています。このガイドは、コードベースと私たちの貢献者との協働方法を理解していただき、すぐに楽しい開発に取り掛かれるようにすることを目的としています。
このガイドは、Dify自体と同様に、常に進化し続けています。実際のプロジェクトの進行状況と多少のずれが生じる場合もございますが、ご理解いただけますと幸いです。改善のためのフィードバックも歓迎いたします。
ライセンスについては、[ライセンスと貢献者同意書](../../LICENSE)をご一読ください。また、コミュニティは[行動規範](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md)に従っています。
## 始める前に
取り組むべき課題をお探しですか？[初心者向けの課題](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)から選んで始めてみましょう！
新しいモデルランタイムやツールを追加したいですか？[プラグインリポジトリ](https://github.com/langgenius/dify-plugins)でPRを作成し、あなたの成果を見せてください。
既存のモデルランタイムやツールの更新、バグ修正をしたいですか？[公式プラグインリポジトリ](https://github.com/langgenius/dify-official-plugins)で作業を進めてください。
参加して、貢献して、一緒に素晴らしいものを作りましょう！💡✨
PRの説明には、既存のイシューへのリンクを含めるか、新しいイシューを作成することを忘れないでください。
### バグ報告
脆弱性は公開イシューを作成せず、[セキュリティポリシー](../../SECURITY.md)に従って非公開で報告してください。
> [!IMPORTANT]
> バグ報告時には、以下の情報を必ず含めてください：
- 明確で分かりやすいタイトル
- エラーメッセージを含む詳細なバグの説明
- バグの再現手順
- 期待される動作
- バックエンドの問題の場合は**ログ**（docker-composeのログで確認可能）が非常に重要です
- 該当する場合はスクリーンショットや動画
優先順位の付け方：
| 問題の種類 | 優先度 |
| ------------------------------------------------------------ | --------- |
| コア機能のバグ（クラウドサービス、ログイン不可、アプリケーション不具合） | 最重要 |
| 重要度の低いバグ、パフォーマンス改善 | 中程度 |
| 軽微な修正（タイプミス、分かりにくいが動作するUI） | 低 |
### 機能リクエスト
> [!NOTE]
> 機能リクエスト時には、以下の情報を必ず含めてください：
- 明確で分かりやすいタイトル
- 機能の詳細な説明
- 使用事例
- その他の文脈や画面のスクリーンショット
優先順位の付け方：
| 機能の種類 | 優先度 |
| ------------------------------------------------------------ | --------- |
| チームメンバーによって高優先度とラベル付けされた機能 | 高 |
| [コミュニティフィードボード](https://github.com/langgenius/dify/discussions/categories/feedbacks)での人気の機能リクエスト | 中程度 |
| 非コア機能と軽微な改善 | 低 |
| 価値はあるが緊急性の低いもの | 将来対応 |
## PRの提出
### プルリクエストのプロセス
1. リポジトリをフォークする
1. PRを作成する前に、変更内容についてイシューで議論する
1. 変更用の新しいブランチを作成する
1. 観察可能な動作に影響する変更や、無視できないリグレッションのリスクがある変更には、テストを追加または更新する。
1. 既存のテストをパスすることを確認する
1. PRの説明文にイシューをリンクする（`fixes #`）
1. マージ完了！
### プロジェクトのセットアップ
#### フロントエンド
フロントエンドサービスのセットアップについては、`web/README.md`の[ガイド](../../web/README.md)を参照してください。このドキュメントには、フロントエンド環境を適切にセットアップするための詳細な手順が記載されています。
#### バックエンド
バックエンドサービスのセットアップについては、`api/README.md`の[手順](../../api/README.md)を参照してください。このドキュメントには、バックエンドを正しく動作させるためのステップバイステップのガイドが含まれています。
## サポートを受ける
貢献中に行き詰まったり、緊急の質問がある場合は、関連するGitHubイシューで質問するか、[Discord](https://discord.gg/8Tpq4AcN9c)で気軽にチャットしてください。
---
### Ko KR ADVANCED SETUP (`docs/ko-KR/ADVANCED_SETUP.md`)
# 고급 설정
로컬 설정은 `docker/.env`에서 변경하세요. [`.env.example`](../../docker/.env.example)에는 기본 배포에 필요한 설정만 있으며, 선택 사항과 서비스별 설정은 [`docker/envs/`](../../docker/envs/)에 있습니다. 필요한 템플릿을 `.example` 접미사 없이 복사하세요. `.env`의 값이 우선합니다. 변경 후 `docker/`에서 `docker compose up -d`를 실행하세요. 자세한 내용은 [Docker 가이드](../../docker/README.md)를 참고하세요.
## Grafana를 사용한 메트릭 모니터링
Dify의 PostgreSQL 데이터베이스를 데이터 소스로 사용하여 앱, 테넌트, 메시지 등에 대한 세분화된 메트릭을 모니터링하기 위해 대시보드를 Grafana로 가져옵니다.
- [@bowenliang123의 Grafana 대시보드](https://github.com/bowenliang123/dify-grafana-dashboard)
## Kubernetes를 통한 배포
Dify를 Kubernetes에 배포하고 프리미엄 스케일링 설정을 구성했다는 커뮤니티가 제공하는 [Helm Charts](https://helm.sh/)와 YAML 파일이 존재합니다.
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Terraform을 사용한 배포
[terraform](https://www.terraform.io/)을 사용하여 단 한 번의 클릭으로 Dify를 클라우드 플랫폼에 배포하십시오
#### Azure Global
- [nikawang의 Azure Terraform](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [sotazum의 Google Cloud Terraform](https://github.com/DeNA/dify-google-cloud-terraform)
### AWS CDK를 사용한 배포
[CDK](https://aws.amazon.com/cdk/)를 사용하여 AWS에 Dify 배포
#### AWS
- [KevinZhao의 AWS CDK (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [tmokmss의 AWS CDK (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)를 통해 원클릭으로 Dify를 Alibaba Cloud에 배포할 수 있습니다
### AKS에 배포하기 위해 Azure Devops Pipeline 사용
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)을 사용하여 Dify를 AKS에 원클릭으로 배포
### Sealos를 사용한 배포
[Sealos App Store](https://sealos.io/products/app-store/dify/)를 사용하여 Dify를 원클릭으로 배포할 수 있습니다
---
### Ko KR CONTRIBUTING (`docs/ko-KR/CONTRIBUTING.md`)
# 기여하기
Dify에 기여하려고 하시는군요 - 정말 멋집니다, 당신이 무엇을 할지 기대가 됩니다. 인력과 자금이 제한된 스타트업으로서, 우리는 LLM 애플리케이션을 구축하고 관리하기 위한 가장 직관적인 워크플로우를 설계하고자 하는 큰 야망을 가지고 있습니다. 커뮤니티의 모든 도움은 정말 중요합니다.
우리는 현재 상황에서 민첩하게 빠르게 배포해야 하지만, 동시에 당신과 같은 기여자들이 기여하는 과정에서 최대한 원활한 경험을 얻을 수 있도록 하고 싶습니다. 우리는 이러한 목적으로 이 기여 가이드를 작성했으며, 여러분이 코드베이스와 우리가 기여자들과 어떻게 협업하는지에 대해 친숙해질 수 있도록 돕고, 빠르게 재미있는 부분으로 넘어갈 수 있도록 하고자 합니다.
이 가이드는 Dify 자체와 마찬가지로 끊임없이 진행 중인 작업입니다. 때로는 실제 프로젝트보다 뒤처질 수 있다는 점을 이해해 주시면 감사하겠으며, 개선을 위한 피드백은 언제든지 환영합니다.
라이센스 측면에서, 간략한 [라이센스 및 기여자 동의서](../../LICENSE)를 읽어보는 시간을 가져주세요. 커뮤니티는 또한 [행동 강령](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md)을 준수합니다.
## 시작하기 전에
처리할 작업을 찾고 계신가요? [초보자를 위한 이슈](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)를 살펴보고 시작할 것을 선택하세요!
추가할 새로운 모델 런타임이나 도구가 있나요? 우리의 [플러그인 저장소](https://github.com/langgenius/dify-plugins)에 PR을 열고 당신이 만든 것을 보여주세요.
기존 모델 런타임, 도구를 업데이트하거나 버그를 수정해야 하나요? 우리의 [공식 플러그인 저장소](https://github.com/langgenius/dify-official-plugins)로 가서 당신의 마법을 펼치세요!
함께 즐기고, 기여하고, 멋진 것을 함께 만들어 봅시다! 💡✨
PR 설명에 기존 이슈를 연결하거나 새 이슈를 여는 것을 잊지 마세요.
### 버그 보고
보안 취약점은 공개 이슈를 만들지 말고 [보안 정책](../../SECURITY.md)에 따라 비공개로 보고하세요.
> [!IMPORTANT]
> 버그 보고서를 제출할 때 다음 정보를 포함해 주세요:
- 명확하고 설명적인 제목
- 오류 메시지를 포함한 버그에 대한 상세한 설명
- 버그를 재현하는 단계
- 예상되는 동작
- 가능한 경우 **로그**, 백엔드 이슈의 경우 매우 중요합니다. docker-compose 로그에서 찾을 수 있습니다
- 해당되는 경우 스크린샷 또는 비디오
우선순위 결정 방법:
| 이슈 유형 | 우선순위 |
| ------------------------------------------------------------ | --------------- |
| 핵심 기능의 버그(클라우드 서비스, 로그인 불가, 애플리케이션 작동 불능) | 중대 |
| 비중요 버그, 성능 향상 | 중간 우선순위 |
| 사소한 수정(오타, 혼란스럽지만 작동하는 UI) | 낮은 우선순위 |
### 기능 요청
> [!NOTE]
> 기능 요청을 제출할 때 다음 정보를 포함해 주세요:
- 명확하고 설명적인 제목
- 기능에 대한 상세한 설명
- 해당 기능의 사용 사례
- 기능 요청에 관한 기타 컨텍스트 또는 스크린샷
우선순위 결정 방법:
| 기능 유형 | 우선순위 |
| ------------------------------------------------------------ | --------------- |
| 팀 구성원에 의해 레이블이 지정된 고우선순위 기능 | 높은 우선순위 |
| 우리의 [커뮤니티 피드백 보드](https://github.com/langgenius/dify/discussions/categories/feedbacks)에서 인기 있는 기능 요청 | 중간 우선순위 |
| 비핵심 기능 및 사소한 개선 | 낮은 우선순위 |
| 가치 있지만 즉시 필요하지 않은 기능 | 미래 기능 |
## PR 제출하기
### Pull Request 프로세스
1. 저장소를 포크하세요
1. PR을 작성하기 전에, 변경하고자 하는 내용에 대해 논의하기 위한 이슈를 생성해 주세요
1. 변경 사항을 위한 새 브랜치를 만드세요
1. 변경이 관찰 가능한 동작에 영향을 주거나 유의미한 회귀 위험이 있으면 테스트를 추가하거나 갱신하세요.
1. 코드가 기존 테스트를 통과하는지 확인하세요
1. PR 설명에 이슈를 연결해 주세요, `fixes #<이슈_번호>`
1. 병합 완료!
### 프로젝트 설정하기
#### 프론트엔드
프론트엔드 서비스를 설정하려면, `web/README.md` 파일에 있는 우리의 [종합 가이드](../../web/README.md)를 참조하세요. 이 문서는 프론트엔드 환경을 적절히 설정하는 데 도움이 되는 자세한 지침을 제공합니다.
#### 백엔드
백엔드 서비스를 설정하려면, `api/README.md` 파일에 있는 우리의 [상세 지침](../../api/README.md)을 참조하세요. 이 문서는 백엔드를 원활하게 실행하는 데 도움이 되는 단계별 가이드를 포함하고 있습니다.
## 도움 받기
기여하는 동안 막히거나 긴급한 질문이 있으면, 관련 GitHub 이슈를 통해 질문을 보내거나, 빠른 대화를 위해 우리의 [Discord](https://discord.gg/8Tpq4AcN9c)에 참여하세요.
---
### Pt BR ADVANCED SETUP (`docs/pt-BR/ADVANCED_SETUP.md`)
# Configuração avançada
Configure a instalação em `docker/.env`. [`.env.example`](../../docker/.env.example) contém os valores necessários para a implantação padrão; opções avançadas e específicas dos serviços ficam em [`docker/envs/`](../../docker/envs/). Copie os modelos necessários sem o sufixo `.example`. Os valores de `.env` têm prioridade. Após alterações, execute `docker compose up -d` em `docker/`. Consulte o [guia do Docker](../../docker/README.md).
## Monitoramento de Métricas com Grafana
Importe o dashboard para o Grafana, usando o banco de dados PostgreSQL do Dify como fonte de dados, para monitorar métricas na granularidade de aplicativos, inquilinos, mensagens e muito mais.
- [Dashboard do Grafana por @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Implantação com Kubernetes
Se deseja configurar uma instalação de alta disponibilidade, há [Helm Charts](https://helm.sh/) e arquivos YAML contribuídos pela comunidade que permitem a implantação do Dify no Kubernetes.
- [Helm Chart de @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart de @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart de @magicsong](https://github.com/magicsong/ai-charts)
- [Arquivo YAML por @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [Arquivo YAML por @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NOVO! Arquivos YAML (Compatível com Dify v1.6.0) por @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Usando o Terraform para Implantação
Implante o Dify na Plataforma Cloud com um único clique usando [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform por @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform por @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Usando AWS CDK para Implantação
Implante o Dify na AWS usando [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK por @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK por @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Implante o Dify na Alibaba Cloud com um clique usando o [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Usando Azure Devops Pipeline para Implantar no AKS
Implante o Dify no AKS com um clique usando [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Implantação com Sealos
Implante o Dify com um clique usando a [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Pt BR CONTRIBUTING (`docs/pt-BR/CONTRIBUTING.md`)
# CONTRIBUINDO
Então você está procurando contribuir para o Dify - isso é incrível, mal podemos esperar para ver o que você vai fazer. Como uma startup com equipe e financiamento limitados, temos grandes ambições de projetar o fluxo de trabalho mais intuitivo para construir e gerenciar aplicações LLM. Qualquer ajuda da comunidade conta, verdadeiramente.
Precisamos ser ágeis e entregar rapidamente considerando onde estamos, mas também queremos garantir que colaboradores como você tenham uma experiência o mais tranquila possível ao contribuir. Montamos este guia de contribuição com esse propósito, visando familiarizá-lo com a base de código e como trabalhamos com os colaboradores, para que você possa rapidamente passar para a parte divertida.
Este guia, como o próprio Dify, é um trabalho em constante evolução. Agradecemos muito a sua compreensão se às vezes ele ficar atrasado em relação ao projeto real, e damos as boas-vindas a qualquer feedback para que possamos melhorar.
Em termos de licenciamento, por favor, dedique um minuto para ler nosso breve [Acordo de Licença e Contribuidor](../../LICENSE). A comunidade também adere ao [código de conduta](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
## Antes de começar
Procurando algo para resolver? Navegue por nossos [problemas para iniciantes](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) e escolha um para começar!
Tem um novo modelo ou ferramenta para adicionar? Abra um PR em nosso [repositório de plugins](https://github.com/langgenius/dify-plugins) e mostre-nos o que você construiu.
Precisa atualizar um modelo existente, ferramenta ou corrigir alguns bugs? Vá para nosso [repositório oficial de plugins](https://github.com/langgenius/dify-official-plugins) e faça sua mágica!
Junte-se à diversão, contribua e vamos construir algo incrível juntos! 💡✨
Não se esqueça de vincular um problema existente ou abrir um novo problema na descrição do PR.
### Relatórios de bugs
Relate vulnerabilidades em particular, seguindo a [política de segurança](../../SECURITY.md), sem abrir uma issue pública.
> [!IMPORTANT]
> Por favor, certifique-se de incluir as seguintes informações ao enviar um relatório de bug:
- Um título claro e descritivo
- Uma descrição detalhada do bug, incluindo quaisquer mensagens de erro
- Passos para reproduzir o bug
- Comportamento esperado
- **Logs**, se disponíveis, para problemas de backend, isso é realmente importante, você pode encontrá-los nos logs do docker-compose
- Capturas de tela ou vídeos, se aplicável
Como priorizamos:
| Tipo de Problema | Prioridade |
| ------------------------------------------------------------ | --------------- |
| Bugs em funções centrais (serviço em nuvem, não conseguir fazer login, aplicações não funcionando) | Crítica |
| Bugs não críticos, melhorias de desempenho | Prioridade Média |
| Correções menores (erros de digitação, interface confusa mas funcional) | Prioridade Baixa |
### Solicitações de recursos
> [!NOTE]
> Por favor, certifique-se de incluir as seguintes informações ao enviar uma solicitação de recurso:
- Um título claro e descritivo
- Uma descrição detalhada do recurso
- Um caso de uso para o recurso
- Qualquer outro contexto ou capturas de tela sobre a solicitação de recurso
Como priorizamos:
| Tipo de Recurso | Prioridade |
| ------------------------------------------------------------ | --------------- |
| Recursos de alta prioridade conforme rotulado por um membro da equipe | Prioridade Alta |
| Solicitações populares de recursos do nosso [quadro de feedback da comunidade](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Prioridade Média |
| Recursos não essenciais e melhorias menores | Prioridade Baixa |
| Valiosos mas não imediatos | Recurso Futuro |
## Enviando seu PR
### Processo de Pull Request
1. Faça um fork do repositório
1. Antes de elaborar um PR, por favor crie um problema para discutir as mudanças que você quer fazer
1. Crie um novo branch para suas alterações
1. Adicione ou atualize testes quando a alteração afetar o comportamento observável ou apresentar risco significativo de regressão.
1. Certifique-se de que seu código passa nos testes existentes
1. Por favor, vincule o problema na descrição do PR, `fixes #`
1. Faça o merge do seu código!
### Configurando o projeto
#### Frontend
Para configurar o serviço frontend, por favor consulte nosso [guia abrangente](../../web/README.md) no arquivo `web/README.md`. Este documento fornece instruções detalhadas para ajudá-lo a configurar o ambiente frontend adequadamente.
#### Backend
Para configurar o serviço backend, por favor consulte nossas [instruções detalhadas](../../api/README.md) no arquivo `api/README.md`. Este documento contém um guia passo a passo para ajudá-lo a colocar o backend em funcionamento sem problemas.
## Obtendo Ajuda
Se você ficar preso ou tiver uma dúvida urgente enquanto contribui, simplesmente envie suas perguntas através do problema relacionado no GitHub, ou entre no nosso [Discord](https://discord.gg/8Tpq4AcN9c) para uma conversa rápida.
---
### Sl SI ADVANCED SETUP (`docs/sl-SI/ADVANCED_SETUP.md`)
# Napredne nastavitve
Lokalne nastavitve uredite v `docker/.env`. [`.env.example`](../../docker/.env.example) vsebuje nujne vrednosti za privzeto namestitev; izbirne nastavitve in nastavitve posameznih storitev so v [`docker/envs/`](../../docker/envs/). Potrebne predloge kopirajte brez končnice `.example`. Vrednosti v `.env` imajo prednost. Po spremembah v `docker/` zaženite `docker compose up -d`. Glejte [vodnik za Docker](../../docker/README.md).
## Spremljanje metrik z Grafana
Uvoz nadzorne plošče v Grafana, z uporabo Difyjeve PostgreSQL baze podatkov kot vir podatkov, za spremljanje metrike glede na podrobnost aplikacij, najemnikov, sporočil in drugega.
- [Nadzorna plošča Grafana avtorja @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Namestitev s Kubernetes
Če želite konfigurirati visoko razpoložljivo nastavitev, so na voljo Helm Charts in datoteke YAML, ki jih prispeva skupnost, ki omogočajo uvedbo Difyja v Kubernetes.
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Uporaba Terraform za uvajanje
namestite Dify v Cloud Platform z enim klikom z uporabo [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Uporaba AWS CDK za uvajanje
Uvedite Dify v AWS z uporabo [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Z enim klikom namestite Dify na Alibaba Cloud z [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Uporaba Azure Devops Pipeline za uvajanje v AKS
Z enim klikom namestite Dify v AKS z uporabo [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Namestitev s Sealos
Z enim klikom namestite Dify prek [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Tlh ADVANCED SETUP (`docs/tlh/ADVANCED_SETUP.md`)
# Advanced Setup
Set local configuration in `docker/.env`. [`.env.example`](../../docker/.env.example) contains essential startup defaults; optional and service-specific settings live under [`docker/envs/`](../../docker/envs/). Copy the templates you need without the `.example` suffix. Values in `.env` take precedence. After changes, run `docker compose up -d` from `docker/`. See the [Docker deployment guide](../../docker/README.md).
## Kubernetes
If you'd like to configure a highly-available setup, there are community-contributed [Helm Charts](https://helm.sh/) and YAML files which allow Dify to be deployed on Kubernetes.
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Terraform atorlugu pilersitsineq
wa'logh nIqHom neH ghun deployment toy'wI' [terraform](https://www.terraform.io/) lo'laH.
#### Azure Global
- [Azure Terraform mung @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform qachlot @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### AWS CDK atorlugh pilersitsineq
wa'logh nIqHom neH ghun deployment toy'wI' [CDK](https://aws.amazon.com/cdk/) lo'laH.
#### AWS
- [AWS CDK qachlot @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK qachlot @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### AKS 'e' Deploy je Azure Devops Pipeline lo'laH
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) lo'laH Dify AKS 'e' wa'DIch click 'e' Deploy
### Sealos lo'laH Deploy
[Sealos App Store](https://sealos.io/products/app-store/dify/) lo'laH Dify wa'DIch click 'e' Deploy
---
### Tr TR ADVANCED SETUP (`docs/tr-TR/ADVANCED_SETUP.md`)
# Gelişmiş Kurulum
Yerel ayarları `docker/.env` içinde düzenleyin. [`.env.example`](../../docker/.env.example) varsayılan dağıtım için gereken başlangıç değerlerini içerir; isteğe bağlı ve hizmete özel ayarlar [`docker/envs/`](../../docker/envs/) altındadır. Gereken şablonları `.example` son eki olmadan kopyalayın. `.env` değerleri önceliklidir. Değişikliklerden sonra `docker/` dizininde `docker compose up -d` çalıştırın. [Docker kılavuzuna](../../docker/README.md) bakın.
## Grafana ile Metrik İzleme
Uygulamalar, kiracılar, mesajlar ve daha fazlasının granularitesinde metrikleri izlemek için Dify'nin PostgreSQL veritabanını veri kaynağı olarak kullanarak panoyu Grafana'ya aktarın.
- [@bowenliang123 tarafından Grafana Panosu](https://github.com/bowenliang123/dify-grafana-dashboard)
## Kubernetes ile Dağıtım
Yüksek kullanılabilirliğe sahip bir kurulum yapılandırmak isterseniz, Dify'ın Kubernetes üzerine dağıtılmasına olanak tanıyan topluluk katkılı [Helm Charts](https://helm.sh/) ve YAML dosyaları mevcuttur.
- [@LeoQuote tarafından Helm Chart](https://github.com/douban/charts/tree/master/charts/dify)
- [@BorisPolonsky tarafından Helm Chart](https://github.com/BorisPolonsky/dify-helm)
- [@Winson-030 tarafından YAML dosyası](https://github.com/Winson-030/dify-kubernetes)
- [@wyy-holding tarafından YAML dosyası](https://github.com/wyy-holding/dify-k8s)
- [🚀 YENİ! YAML dosyaları (Dify v1.6.0 destekli) @Zhoneym tarafından](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Dağıtım için Terraform Kullanımı
Dify'ı bulut platformuna tek tıklamayla dağıtın [terraform](https://www.terraform.io/) kullanarak
#### Azure Global
- [Azure Terraform tarafından @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform tarafından @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### AWS CDK ile Dağıtım
[CDK](https://aws.amazon.com/cdk/) kullanarak Dify'ı AWS'ye dağıtın
#### AWS
- [AWS CDK tarafından @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK tarafından @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
[Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/) kullanarak Dify'ı tek tıkla Alibaba Cloud'a dağıtın
### AKS'ye Dağıtım için Azure Devops Pipeline Kullanımı
[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) kullanarak Dify'ı tek tıkla AKS'ye dağıtın
### Sealos ile Dağıtım
[Sealos App Store](https://sealos.io/products/app-store/dify/) kullanarak Dify'ı tek tıkla dağıtın
---
### Tr TR CONTRIBUTING (`docs/tr-TR/CONTRIBUTING.md`)
# KATKIDA BULUNMAK
Demek Dify'a katkıda bulunmak istiyorsunuz - bu harika, ne yapacağınızı görmek için sabırsızlanıyoruz. Sınırlı personel ve finansmana sahip bir startup olarak, LLM uygulamaları oluşturmak ve yönetmek için en sezgisel iş akışını tasarlama konusunda büyük hedeflerimiz var. Topluluktan gelen her türlü yardım gerçekten önemli.
Bulunduğumuz noktada çevik olmamız ve hızlı hareket etmemiz gerekiyor, ancak sizin gibi katkıda bulunanların mümkün olduğunca sorunsuz bir deneyim yaşamasını da sağlamak istiyoruz. Bu katkı rehberini bu amaçla hazırladık; sizi kod tabanıyla ve katkıda bulunanlarla nasıl çalıştığımızla tanıştırmayı, böylece hızlıca eğlenceli kısma geçebilmenizi hedefliyoruz.
Bu rehber, Dify'ın kendisi gibi, sürekli gelişen bir çalışmadır. Bazen gerçek projenin gerisinde kalırsa anlayışınız için çok minnettarız ve gelişmemize yardımcı olacak her türlü geri bildirimi memnuniyetle karşılıyoruz.
Lisanslama konusunda, lütfen kısa [Lisans ve Katkıda Bulunan Anlaşmamızı](../../LICENSE) okumak için bir dakikanızı ayırın. Topluluk ayrıca [davranış kurallarına](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md) da uyar.
## Başlamadan Önce
Üzerinde çalışacak bir şey mi arıyorsunuz? [İlk katkıda bulunanlar için iyi sorunlarımıza](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) göz atın ve başlamak için birini seçin!
Eklenecek harika bir yeni model runtime'ı veya aracınız mı var? [Eklenti depomuzda](https://github.com/langgenius/dify-plugins) bir PR açın ve ne yaptığınızı bize gösterin.
Mevcut bir model runtime'ını, aracı güncellemek veya bazı hataları düzeltmek mi istiyorsunuz? [Resmi eklenti depomuza](https://github.com/langgenius/dify-official-plugins) gidin ve sihrinizi gösterin!
Eğlenceye katılın, katkıda bulunun ve birlikte harika bir şeyler inşa edelim! 💡✨
PR açıklamasında mevcut bir sorunu bağlamayı veya yeni bir sorun açmayı unutmayın.
### Hata Raporları
Güvenlik açıklarını herkese açık issue oluşturmadan [güvenlik politikasına](../../SECURITY.md) göre özel olarak bildirin.
> [!IMPORTANT]
> Lütfen bir hata raporu gönderirken aşağıdaki bilgileri dahil ettiğinizden emin olun:
- Net ve açıklayıcı bir başlık
- Hata mesajları dahil hatanın ayrıntılı bir açıklaması
- Hatayı tekrarlamak için adımlar
- Beklenen davranış
- Mümkünse **Loglar**, backend sorunları için, bu gerçekten önemlidir, bunları docker-compose loglarında bulabilirsiniz
- Uygunsa ekran görüntüleri veya videolar
Nasıl önceliklendiriyoruz:
| Sorun Türü | Öncelik |
| ------------------------------------------------------------ | --------------- |
| Temel işlevlerdeki hatalar (bulut hizmeti, giriş yapamama, çalışmayan uygulamalar) | Kritik |
| Kritik olmayan hatalar, performans artışları | Orta Öncelik |
| Küçük düzeltmeler (yazım hataları, kafa karıştırıcı ama çalışan UI) | Düşük Öncelik |
### Özellik İstekleri
> [!NOTE]
> Lütfen bir özellik isteği gönderirken aşağıdaki bilgileri dahil ettiğinizden emin olun:
- Net ve açıklayıcı bir başlık
- Özelliğin ayrıntılı bir açıklaması
- Özellik için bir kullanım durumu
- Özellik isteği hakkında diğer bağlamlar veya ekran görüntüleri
Nasıl önceliklendiriyoruz:
| Özellik Türü | Öncelik |
| ------------------------------------------------------------ | --------------- |
| Bir ekip üyesi tarafından etiketlenen Yüksek Öncelikli Özellikler | Yüksek Öncelik |
| [Topluluk geri bildirim panosundan](https://github.com/langgenius/dify/discussions/categories/feedbacks) popüler özellik istekleri | Orta Öncelik |
| Temel olmayan özellikler ve küçük geliştirmeler | Düşük Öncelik |
| Değerli ama acil olmayan | Gelecek-Özellik |
## PR'nizi Göndermek
### Pull Request Süreci
1. Depoyu fork edin
1. Bir PR taslağı oluşturmadan önce, yapmak istediğiniz değişiklikleri tartışmak için lütfen bir sorun oluşturun
1. Değişiklikleriniz için yeni bir dal oluşturun
1. Değişiklik gözlemlenebilir davranışı etkiliyorsa veya önemli bir regresyon riski taşıyorsa test ekleyin ya da güncelleyin.
1. Kodunuzun mevcut testleri geçtiğinden emin olun
1. Lütfen PR açıklamasında sorunu bağlayın, `fixes #`
1. Kodunuzu birleştirin!
### Projeyi Kurma
#### Frontend
Frontend hizmetini kurmak için, lütfen `web/README.md` dosyasındaki kapsamlı [rehberimize](../../web/README.md) bakın. Bu belge, frontend ortamını düzgün bir şekilde kurmanıza yardımcı olacak ayrıntılı talimatlar sağlar.
#### Backend
Backend hizmetini kurmak için, lütfen `api/README.md` dosyasındaki detaylı [talimatlarımıza](../../api/README.md) bakın. Bu belge, backend'i sorunsuz bir şekilde çalıştırmanıza yardımcı olacak adım adım bir kılavuz içerir.
## Yardım Almak
Katkıda bulunurken takılırsanız veya yanıcı bir sorunuz olursa, sorularınızı ilgili GitHub sorunu aracılığıyla bize gönderin veya hızlı bir sohbet için [Discord'umuza](https://discord.gg/8Tpq4AcN9c) katılın.
---
### Vi VN ADVANCED SETUP (`docs/vi-VN/ADVANCED_SETUP.md`)
# Thiết lập nâng cao
Cấu hình cục bộ nằm trong `docker/.env`. [`.env.example`](../../docker/.env.example) chỉ chứa các giá trị cần cho triển khai mặc định; cấu hình tùy chọn và riêng cho từng dịch vụ nằm trong [`docker/envs/`](../../docker/envs/). Sao chép mẫu cần dùng và bỏ hậu tố `.example`. Giá trị trong `.env` được ưu tiên. Sau khi thay đổi, chạy `docker compose up -d` từ `docker/`. Xem [hướng dẫn Docker](../../docker/README.md).
## Giám sát Số liệu với Grafana
Nhập bảng điều khiển vào Grafana, sử dụng cơ sở dữ liệu PostgreSQL của Dify làm nguồn dữ liệu, để giám sát số liệu theo mức độ chi tiết của ứng dụng, người thuê, tin nhắn và hơn thế nữa.
- [Bảng điều khiển Grafana của @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
## Triển khai với Kubernetes
Nếu bạn muốn cấu hình một cài đặt có độ sẵn sàng cao, có các [Helm Charts](https://helm.sh/) và tệp YAML do cộng đồng đóng góp cho phép Dify được triển khai trên Kubernetes.
- [Helm Chart bởi @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart bởi @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Tệp YAML bởi @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [Tệp YAML bởi @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 MỚI! Tệp YAML (Hỗ trợ Dify v1.6.0) bởi @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### Sử dụng Terraform để Triển khai
Triển khai Dify lên nền tảng đám mây với một cú nhấp chuột bằng cách sử dụng [terraform](https://www.terraform.io/)
#### Azure Global
- [Azure Terraform bởi @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform bởi @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### Sử dụng AWS CDK để Triển khai
Triển khai Dify trên AWS bằng [CDK](https://aws.amazon.com/cdk/)
#### AWS
- [AWS CDK bởi @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK bởi @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### Alibaba Cloud
[Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### Alibaba Cloud Data Management
Triển khai Dify lên Alibaba Cloud chỉ với một cú nhấp chuột bằng [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
### Sử dụng Azure Devops Pipeline để Triển khai lên AKS
Triển khai Dify lên AKS chỉ với một cú nhấp chuột bằng [Azure Devops Pipeline Helm Chart bởi @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
### Triển khai với Sealos
Triển khai Dify chỉ với một cú nhấp chuột từ [Sealos App Store](https://sealos.io/products/app-store/dify/)
---
### Vi VN CONTRIBUTING (`docs/vi-VN/CONTRIBUTING.md`)
# ĐÓNG GÓP
Bạn đang muốn đóng góp cho Dify - thật tuyệt vời, chúng tôi rất mong được thấy những gì bạn sẽ làm. Là một startup với nguồn nhân lực và tài chính hạn chế, chúng tôi có tham vọng lớn trong việc thiết kế quy trình trực quan nhất để xây dựng và quản lý các ứng dụng LLM. Mọi sự giúp đỡ từ cộng đồng đều rất có ý nghĩa.
Chúng tôi cần phải nhanh nhẹn và triển khai nhanh chóng, nhưng cũng muốn đảm bảo những người đóng góp như bạn có trải nghiệm đóng góp thuận lợi nhất có thể. Chúng tôi đã tạo hướng dẫn đóng góp này nhằm giúp bạn làm quen với codebase và cách chúng tôi làm việc với người đóng góp, để bạn có thể nhanh chóng bắt đầu phần thú vị.
Hướng dẫn này, giống như Dify, đang được phát triển liên tục. Chúng tôi rất cảm kích sự thông cảm của bạn nếu đôi khi nó chưa theo kịp dự án thực tế, và hoan nghênh mọi phản hồi để cải thiện.
Về giấy phép, vui lòng dành chút thời gian đọc [Thỏa thuận Cấp phép và Người đóng góp](../../LICENSE) ngắn gọn của chúng tôi. Cộng đồng cũng tuân theo [quy tắc ứng xử](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
## Trước khi bắt đầu
Đang tìm việc để thực hiện? Hãy xem qua [các issue dành cho người mới](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) và chọn một để bắt đầu!
Bạn có một model runtime hoặc công cụ mới thú vị để thêm vào? Mở PR trong [repo plugin](https://github.com/langgenius/dify-plugins) của chúng tôi và cho chúng tôi thấy những gì bạn đã xây dựng.
Cần cập nhật model runtime, công cụ hiện có hoặc sửa lỗi? Ghé thăm [repo plugin chính thức](https://github.com/langgenius/dify-official-plugins) và thực hiện phép màu của bạn!
Hãy tham gia, đóng góp và cùng nhau xây dựng điều tuyệt vời! 💡✨
Đừng quên liên kết đến issue hiện có hoặc mở issue mới trong mô tả PR.
### Báo cáo lỗi
Báo cáo lỗ hổng riêng tư theo [chính sách bảo mật](../../SECURITY.md), không tạo issue công khai.
> [!QUAN TRỌNG]\
> Vui lòng đảm bảo cung cấp các thông tin sau khi gửi báo cáo lỗi:
- Tiêu đề rõ ràng và mô tả
- Mô tả chi tiết về lỗi, bao gồm các thông báo lỗi
- Các bước để tái hiện lỗi
- Hành vi mong đợi
- **Log**, nếu có, cho các vấn đề backend, điều này rất quan trọng, bạn có thể tìm thấy chúng trong docker-compose logs
- Ảnh chụp màn hình hoặc video, nếu có thể
Cách chúng tôi ưu tiên:
| Loại vấn đề | Mức độ ưu tiên |
| ----------- | -------------- |
| Lỗi trong các chức năng cốt lõi (dịch vụ đám mây, không thể đăng nhập, ứng dụng không hoạt động) | Quan trọng |
| Lỗi không nghiêm trọng, cải thiện hiệu suất | Ưu tiên trung bình |
| Sửa lỗi nhỏ (lỗi chính tả, UI gây nhầm lẫn nhưng vẫn hoạt động) | Ưu tiên thấp |
### Yêu cầu tính năng
> [!LƯU Ý]
> Vui lòng đảm bảo cung cấp các thông tin sau khi gửi yêu cầu tính năng:
- Tiêu đề rõ ràng và mô tả
- Mô tả chi tiết về tính năng
- Trường hợp sử dụng cho tính năng
- Bất kỳ ngữ cảnh hoặc ảnh chụp màn hình nào về yêu cầu tính năng
Cách chúng tôi ưu tiên:
| Loại tính năng | Mức độ ưu tiên |
| -------------- | -------------- |
| Tính năng ưu tiên cao được gắn nhãn bởi thành viên nhóm | Ưu tiên cao |
| Yêu cầu tính năng phổ biến từ [bảng phản hồi cộng đồng](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Ưu tiên trung bình |
| Tính năng không cốt lõi và cải tiến nhỏ | Ưu tiên thấp |
| Có giá trị nhưng không cấp bách | Tính năng tương lai |
## Gửi PR của bạn
### Quy trình tạo Pull Request
1. Fork repository
1. Trước khi soạn PR, vui lòng tạo issue để thảo luận về các thay đổi bạn muốn thực hiện
1. Tạo nhánh mới cho các thay đổi của bạn
1. Thêm hoặc cập nhật kiểm thử khi thay đổi ảnh hưởng đến hành vi có thể quan sát được hoặc có nguy cơ hồi quy đáng kể.
1. Đảm bảo code của bạn vượt qua các test hiện có
1. Vui lòng liên kết issue trong mô tả PR, `fixes #`
1. Được merge!
### Thiết lập dự án
#### Frontend
Để thiết lập dịch vụ frontend, vui lòng tham khảo [hướng dẫn](../../web/README.md) chi tiết của chúng tôi trong file `web/README.md`. Tài liệu này cung cấp hướng dẫn chi tiết để giúp bạn thiết lập môi trường frontend một cách đúng đắn.
#### Backend
Để thiết lập dịch vụ backend, vui lòng tham khảo [hướng dẫn](../../api/README.md) chi tiết của chúng tôi trong file `api/README.md`. Tài liệu này chứa hướng dẫn từng bước để giúp bạn khởi chạy backend một cách suôn sẻ.
## Nhận trợ giúp
Nếu bạn bị mắc kẹt hoặc có câu hỏi cấp bách trong quá trình đóng góp, chỉ cần gửi câu hỏi của bạn thông qua issue GitHub liên quan, hoặc tham gia [Discord](https://discord.gg/8Tpq4AcN9c) của chúng tôi để trò chuyện nhanh.
---
### Zh CN ADVANCED SETUP (`docs/zh-CN/ADVANCED_SETUP.md`)
# 高级设置
## 自定义配置
在 `docker/.env` 中设置本地配置。[`.env.example`](../../docker/.env.example) 只包含默认部署所需的启动配置，可选和服务专用配置位于 [`docker/envs/`](../../docker/envs/)。需要时，将对应模板复制为不带 `.example` 后缀的文件；`.env` 中的值优先。修改后，在 `docker/` 目录运行 `docker compose up -d`。详见 [Docker 部署指南](../../docker/README.md)。
## 使用 Grafana 进行指标监控
将仪表板导入 Grafana，使用 Dify 的 PostgreSQL 数据库作为数据源，以监控应用、租户、消息等粒度的指标。
- [由 @bowenliang123 提供的 Grafana 仪表板](https://github.com/bowenliang123/dify-grafana-dashboard)
## 使用 Helm Chart 或 Kubernetes 资源清单（YAML）部署
使用 [Helm Chart](https://helm.sh/) 版本或者 Kubernetes 资源清单（YAML），可以在 Kubernetes 上部署 Dify。
- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
- [YAML 文件 by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML 文件 (支持 Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### 使用 Terraform 部署
使用 [terraform](https://www.terraform.io/) 一键将 Dify 部署到云平台
#### Azure Global
- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
### 使用 AWS CDK 部署
使用 [CDK](https://aws.amazon.com/cdk/) 将 Dify 部署到 AWS
#### AWS
- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### 使用 阿里云计算巢 部署
使用 [阿里云计算巢](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88) 将 Dify 一键部署到 阿里云
### 使用 阿里云数据管理DMS 部署
使用 [阿里云数据管理DMS](https://help.aliyun.com/zh/dms/dify-in-invitational-preview) 将 Dify 一键部署到 阿里云
### 使用 Azure Devops Pipeline 部署到AKS
使用[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) 将 Dify 一键部署到 AKS
### 使用 Sealos 部署
通过 [Sealos App Store](https://sealos.io/products/app-store/dify/) 一键部署 Dify
---
### Zh CN CONTRIBUTING (`docs/zh-CN/CONTRIBUTING.md`)
# 贡献指南
非常感谢你考虑为 Dify 做出贡献！作为一家资源有限的创业公司，我们希望打造最直观的 LLM 应用开发和管理工作流程。社区的每一份贡献对我们来说都弥足珍贵。
我们需要保持敏捷和快速迭代，同时也希望确保贡献者能获得尽可能流畅的参与体验。这份贡献指南旨在帮助你熟悉代码库和我们的工作方式，让你可以尽快进入有趣的开发环节。
本指南和 Dify 一样在不断完善中。如果有任何滞后于项目实际情况的地方，恳请谅解，我们也欢迎任何改进建议。
关于许可证，请花一分钟阅读我们简短的[许可和贡献者协议](../../LICENSE)。同时也请遵循社区[行为准则](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md)。
## 开始之前
想寻找可以着手的任务？浏览我们的[新手友好议题](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)并选择一个开始！
有酷炫的新模型运行时或工具要添加？在我们的[插件仓库](https://github.com/langgenius/dify-plugins)开启 PR，展示你的作品。
需要更新现有模型运行时、工具或修复 bug？前往我们的[官方插件仓库](https://github.com/langgenius/dify-official-plugins)大展身手！
加入我们，一起贡献，共同打造精彩项目！💡✨
请记得在 PR 描述中关联现有 issue 或创建新的 issue。
### Bug 报告
安全漏洞请按[安全政策](../../SECURITY.md)私下报告，不要创建公开 issue。
> [!IMPORTANT]
> 提交 bug 报告时请务必包含以下信息：
- 清晰描述性的标题
- 详细的 bug 描述，包括任何错误信息
- 复现步骤
- 预期行为
- **日志**，如果是后端问题，这点很重要，可以在 docker-compose 日志中找到
- 截图或视频（如果适用）
优先级划分：
| 问题类型 | 优先级 |
| -------------------------------------------------- | ---------- |
| 核心功能 bug（云服务、登录失败、应用无法使用） | 紧急 |
| 非关键 bug、性能优化 | 中等优先级 |
| 小修复（拼写错误、界面混乱但可用） | 低优先级 |
### 功能请求
> [!NOTE]
> 提交功能请求时请务必包含以下信息：
- 清晰描述性的标题
- 详细的功能描述
- 功能使用场景
- 其他相关上下文或截图
优先级划分：
| 功能类型 | 优先级 |
| -------------------------------------------------- | ---------- |
| 被团队成员标记为高优先级的功能 | 高优先级 |
| 来自[社区反馈板](https://github.com/langgenius/dify/discussions/categories/feedbacks)的热门功能请求 | 中等优先级 |
| 非核心功能和小改进 | 低优先级 |
| 有价值但非紧急的功能 | 未来特性 |
## 提交 PR
### PR 提交流程
1. Fork 本仓库
1. 在提交 PR 之前，请先创建 issue 讨论你想要做的修改
1. 为你的修改创建一个新的分支
1. 当修改影响可观察行为或存在明显回归风险时，添加或更新测试。
1. 确保你的代码能通过现有的测试
1. 请在 PR 描述中关联相关 issue，格式为 `fixes #`
1. 等待合并！
### 项目设置
#### 前端
关于前端服务的设置，请参考 `web/README.md` 文件中的[详细指南](../../web/README.md)。该文档提供了帮助你正确配置前端环境的详细说明。
#### 后端
关于后端服务的设置，请参考 `api/README.md` 文件中的[详细说明](../../api/README.md)。该文档包含了帮助你顺利运行后端的步骤说明。
## 获取帮助
如果你在贡献过程中遇到困难或有紧急问题，可以通过相关 GitHub issue 向我们提问，或加入我们的 [Discord](https://discord.gg/8Tpq4AcN9c) 进行快速交流。
---
### Zh TW ADVANCED SETUP (`docs/zh-TW/ADVANCED_SETUP.md`)
# 進階設定
在 `docker/.env` 中設定本機配置。[`.env.example`](../../docker/.env.example) 僅包含預設部署所需的啟動設定，可選與服務專用設定位於 [`docker/envs/`](../../docker/envs/)。需要時，將對應範本複製為不含 `.example` 後綴的檔案；`.env` 中的值優先。修改後，在 `docker/` 目錄執行 `docker compose up -d`。詳見 [Docker 部署指南](../../docker/README.md)。
## 使用 Grafana 進行指標監控
將儀表板匯入 Grafana，使用 Dify 的 PostgreSQL 資料庫作為資料來源，以監控應用程式、租戶、訊息等顆粒度的指標。
- [由 @bowenliang123 提供的 Grafana 儀表板](https://github.com/bowenliang123/dify-grafana-dashboard)
## 使用 Kubernetes 部署
如果您想配置高可用性設置，社區貢獻的 [Helm Charts](https://helm.sh/) 和 Kubernetes 資源清單（YAML）允許在 Kubernetes 上部署 Dify。
- [由 @LeoQuote 提供的 Helm Chart](https://github.com/douban/charts/tree/master/charts/dify)
- [由 @BorisPolonsky 提供的 Helm Chart](https://github.com/BorisPolonsky/dify-helm)
- [由 @Winson-030 提供的 YAML 文件](https://github.com/Winson-030/dify-kubernetes)
- [由 @wyy-holding 提供的 YAML 文件](https://github.com/wyy-holding/dify-k8s)
- [🚀 NEW! YAML 檔案（支援 Dify v1.6.0）by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
### 使用 Terraform 進行部署
使用 [terraform](https://www.terraform.io/) 一鍵部署 Dify 到雲端平台
#### Azure 全球
- [由 @nikawang 提供的 Azure Terraform](https://github.com/nikawang/dify-azure-terraform)
#### Google Cloud
- [由 @sotazum 提供的 Google Cloud Terraform](https://github.com/DeNA/dify-google-cloud-terraform)
### 使用 AWS CDK 進行部署
使用 [CDK](https://aws.amazon.com/cdk/) 部署 Dify 到 AWS
#### AWS
- [由 @KevinZhao 提供的 AWS CDK (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
- [由 @tmokmss 提供的 AWS CDK (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
### 使用 阿里云计算巢進行部署
[阿里云](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
### 使用 阿里雲數據管理DMS 進行部署
透過 [阿里雲數據管理DMS](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)，一鍵將 Dify 部署至阿里雲
### 使用 Azure Devops Pipeline 部署到AKS
使用[Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS) 將 Dify 一鍵部署到 AKS
### 使用 Sealos 部署
透過 [Sealos App Store](https://sealos.io/products/app-store/dify/) 一鍵部署 Dify
---
### Zh TW CONTRIBUTING (`docs/zh-TW/CONTRIBUTING.md`)
# 參與貢獻
我們很高興你想要為 Dify 做出貢獻！作為一個資源有限的新創團隊，我們期望打造最直觀的 LLM 應用開發與管理工作流程。社群中的每一份貢獻對我們來說都非常重要。
作為一個快速發展的專案，我們需要保持敏捷並快速迭代，同時也希望能為貢獻者提供順暢的參與體驗。我們準備了這份貢獻指南，幫助你了解程式碼庫和我們與貢獻者合作的方式，讓你能夠盡快投入有趣的開發工作。
這份指南與 Dify 一樣，都在持續完善中。如果指南內容有落後於實際專案的情況，還請見諒，也歡迎提供改進建議。
關於授權部分，請花點時間閱讀我們簡短的[授權和貢獻者協議](../../LICENSE)。社群也需遵守[行為準則](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md)。
## 開始之前
想找點事做？瀏覽我們的[新手友善議題](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)並挑選一個開始！
有酷炫的模型執行時期或工具要新增？在我們的[外掛倉庫](https://github.com/langgenius/dify-plugins)開啟 PR 展示你的作品。
需要更新現有的模型執行時期、工具或修復錯誤？前往我們的[官方外掛倉庫](https://github.com/langgenius/dify-official-plugins)開始你的魔法之旅！
加入我們，一起貢獻並打造令人驚艷的作品吧！💡✨
別忘了在 PR 描述中連結現有議題或開啟新議題。
### 錯誤回報
安全漏洞請依照[安全政策](../../SECURITY.md)私下回報，不要建立公開議題。
> [!IMPORTANT]\
> 提交錯誤回報時，請務必包含以下資訊：
- 清晰明確的標題
- 詳細的錯誤描述，包含任何錯誤訊息
- 重現錯誤的步驟
- 預期行為
- **日誌**，如果有的話。對後端問題來說這點很重要，你可以在 docker-compose logs 中找到
- 截圖或影片（如適用）
優先順序評估：
| 議題類型 | 優先級 |
| -------- | ------ |
| 核心功能錯誤（雲端服務、無法登入、應用程式無法運作） | 緊急 |
| 非緊急錯誤、效能優化 | 中等 |
| 次要修正（拼字錯誤、介面混淆但可運作） | 低 |
### 功能請求
> [!NOTE]\
> 提交功能請求時，請務必包含以下資訊：
- 清晰明確的標題
- 詳細的功能描述
- 功能的使用情境
- 其他相關背景說明或截圖
優先順序評估：
| 功能類型 | 優先級 |
| -------- | ------ |
| 團隊成員標記為高優先級的功能 | 高 |
| 來自[社群回饋板](https://github.com/langgenius/dify/discussions/categories/feedbacks)的熱門功能請求 | 中 |
| 非核心功能和小幅改進 | 低 |
| 有價值但非急迫的功能 | 未來功能 |
## 提交 PR
### PR 流程
1. Fork 專案
1. 在開始撰寫 PR 前，請先建立議題討論你想做的更改
1. 為你的更改建立新分支
1. 當更改影響可觀察行為或存在明顯回歸風險時，新增或更新測試。
1. 確保你的程式碼通過現有測試
1. 請在 PR 描述中連結相關議題，使用 `fixes #`
1. 等待合併！
### 專案設定
#### 前端
關於前端服務的設定，請參考 `web/README.md` 中的完整[指南](../../web/README.md)。此文件提供詳細說明，幫助你正確設定前端環境。
#### 後端
關於後端服務的設定，請參考 `api/README.md` 中的詳細[說明](../../api/README.md)。此文件包含逐步指引，幫助你順利啟動後端服務。
## 尋求協助
如果你在貢獻過程中遇到困難或有急切的問題，可以透過相關的 GitHub 議題詢問，或加入我們的 [Discord](https://discord.gg/8Tpq4AcN9c) 進行即時交流。
---
### Web Docs Bundle Size (`web/docs/bundle-size.md`)
# Bundle analysis in pull requests
The main CI calls **Web Bundle Analysis** when its Web style checks are required,
for both pull requests and merge queue entries. It builds the event's exact base
commit and the tested merge commit from `github.sha` in parallel. Both run the
complete `build:vinext` pipeline, including the unused translations check.
No SSR, reference-analysis, or standalone stage is skipped.
This replaces the separate Vinext build in Web Style. Static checks run alongside
the analysis workflow, and the existing **Web Style** required check succeeds only
when both complete successfully. Main CI owns change detection and duplicate-run
skipping. Target-branch updates alone do not rerun PRs.
The official Rolldown `bundleAnalyzerPlugin` is added only to the client environment
through a temporary Vite config wrapper. Each revision keeps its own application
config and lockfile. The plugin is already bundled with the repository's Vite+
runtime through `vite/rolldown/experimental`; no separate analyzer dependency is
installed. The experimental schema is validated and unsupported data fails the
job instead of appearing as savings.
## Reading the report
The full comparison always appears in the Actions summary. Same-repository PRs
receive an updated comment only when the absolute gzip change reaches at least
5 KiB for all client JS, 1 KiB for client CSS, or 2 KiB for any entry present in
both revisions. Increases and decreases both qualify. Raw sizes, package
attribution, and added/removed entry boundaries do not independently trigger a
comment. If a later run falls below every threshold, the existing report comment
is removed to avoid leaving stale results.
Merge queue runs receive the summary and artifacts without
a PR comment. Fork PRs receive the summary and artifacts without a
privileged build or comment token. Reports are informational: growth does not fail
the check; build, analysis, and reporting errors do.
- **All client JS:** actual bytes and per-file gzip of the chunks listed in the
official analyzer. Includes dynamically imported chunks.
- **Client CSS:** emitted CSS under `dist/client/_next/static`, excluding copied
public assets.
- **Entry static dependencies:** recursively follows static chunk edges, with
shared chunks counted once within an entry. Application source paths identify
entries independently of output hashes. Dynamic entries are measured when
loaded; these are not full-page first-load measurements. Entries overlap and
cannot be summed. The comment shows the 20 largest absolute gzip changes.
Added/removed entry boundaries appear separately and are not treated as size
changes from zero.
- **Package attribution:** groups module sizes from the official analyzer by npm
package. This is attribution, not compressed output size; the comment shows the
15 largest absolute changes.
This measures Vinext/Rolldown output, not Next.js/Turbopack production output or
browser network timings. Compiler versions are recorded in both snapshots.
Both revisions upload the official JSON and Markdown reports, build logs, and
size snapshots for 14 days. The summary links to these artifacts; no local viewer
is required. We do not rely on Vite DevTools' incomplete static Session Compare.
See the [Rolldown analyzer documentation].
## Local collection
The `instrument` command renames `vite.config.ts` and writes a temporary wrapper.
Use it only in a disposable checkout, as CI does:
```sh
node web/scripts/bundle-analysis.ts instrument web
pnpm --dir web run build:vinext
node web/scripts/bundle-analysis.ts collect web "$(git rev-parse HEAD)" /tmp/current.json
node web/scripts/bundle-analysis.ts compare /tmp/base.json /tmp/current.json /tmp/report.md
```
## Next.js / Turbopack analysis
The Web `analyze` script uses Next.js's built-in Turbopack analyzer:
```sh
pnpm --dir web analyze --output
```
Save `web/.next/diagnostics/analyze` before changing code, then collect another
report with the same compiler version and environment. Omit `--output` to open
the interactive analyzer and inspect route-specific client/server import chains.
These reports are separate from the Vinext snapshots above.
If analysis panics inside `next-api/src/nft.rs`, move
`web/.next/cache/turbopack` outside `.next` and retry before changing production
configuration. A stale filesystem cache caused this failure locally with
Next.js 16.3.6; rebuilding the cache let the unchanged configuration complete.
Check import chains before adding configuration. Next.js already optimizes
imports from libraries such as `ahooks` and Heroicons. `serverExternalPackages`
affects server bundling; it does not remove dependencies from browser bundles.
A lazy component can still have eager dependencies if shared utilities import
its SDK statically. Console analytics keeps its initialization state and event
helpers lightweight, loading Amplitude and session replay only after analytics
is enabled and consent is granted. Keep SDK imports in shared helpers type-only
and use the initialized client for events. When changing this boundary, verify
revocation and unmount during loading, concurrent initialization, and failure
recovery as well as entry static dependencies and total emitted bytes.
[Rolldown analyzer documentation]: https://rolldown.rs/builtin-plugins/bundle-analyzer
---
### Web Docs Hotkeys (`web/docs/hotkeys.md`)
# Keyboard Commands
Use TanStack Hotkeys for application commands. Keep registration, business actions, and
availability with the feature owner; keep text editing, widget navigation, and dismissal with
their existing editor or Dify UI primitive. Do not add a generic shortcut wrapper.
The official [React guide] owns library options and [defaults], including input filtering,
keyboard layouts, composition matching, and repeats. This document adds Dify's integration
contracts. Check the installed declarations when an API differs from the latest documentation.
## Registration and availability
For commands belonging to mounted popup content, pass the actual owner's ref:
```tsx
const PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
const popupRef = useRef(null)
useHotkey(PUBLISH_HOTKEY, publish, {
target: popupRef,
enabled: canPublish,
requireReset: true,
})
```
Attach the ref to the Popup. Import the hook and type from `@tanstack/react-hotkeys` and
`useRef` from React. Call the button's action, including its validation and permission checks.
- Use `enabled` when an unavailable command should release the key entirely. A disabled
registration does not consume the event. If the browser action must remain suppressed,
keep the registration enabled and guard the business action inside its callback instead.
- Use default input filtering unless the feature requires otherwise. Form submission may need
`ignoreInputs: false`; canvas commands use `true` to preserve editing. See [defaults].
- Use `requireReset: true` for one-shot commands with default consumption; allow continuous
actions such as zoom to repeat. Conditional event owners follow the rules below.
- Pass a ref, not `ref.current`. An empty ref skips registration; a bare null target falls back
to document. Ref mutation does not re-render the owner: put the hook in mounted content or
use the actual Form's `onKeyDown` when it mounts later. Lexical root replacement can use its
root subscription with element state; disable registration while that element is null.
- For form commands, call `event.currentTarget.requestSubmit()` to share native submission and
validation. React events from nested portals follow React ancestry; check DOM containment
when those portals must be excluded. The Skills file tree intentionally includes its menus.
## Bindings and display
| Boundary | Contract |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| One command / a group | `useHotkey` / `useHotkeys`; preserve feature command IDs. |
| Chord-only strings / objects | `HotkeyChord` / `RawHotkeyChord`; use `satisfies` for constants. |
| Both chord forms | `RegisterableHotkeyChord`; `Hotkey` / `RegisterableHotkey` also admit sequences. |
| Existing React handler | `matchesKeyboardEvent(event.nativeEvent, chord)` matches one chord only. |
| Keycaps | Share the binding with registration; use `formatForDisplay(..., { parts: true })` and Dify UI `Kbd` / `KbdGroup`. |
Use `DisplayHotkeyChord` for chord-only display boundaries. Sequence formatting returns groups
of keycaps; do not widen a chord renderer without implementing that UI. Follow [formatting] for
logical/physical keys, validation, and labels. Preserve the initial platform through hydration,
as navigation search does. `aria-keyshortcuts` uses `Meta+K` or `Control+K`, not glyphs or `Mod`.
Local constants are the default. Use native [app hotkeys] when a product needs app-wide discovery
or remapping: declarations contain no callbacks; business callbacks stay with their feature.
Recording, sequences, and modifier hints are optional capabilities, not migration requirements.
## Event ownership and scopes
A DOM target limits event origin; a [scope] controls whether TanStack registrations are active.
Neither replaces editor handling or Dify UI dismissal. Use a scoped provider above its hook
consumers, with a unique name for independently mounted surfaces. Same-scope matches may all
run; `conflictBehavior: 'replace'` is not a restoring stack, and metadata is not activation.
Use `exclusive` when a modal feature must suspend background application commands. Activate it
with the interactive content, not a permanently mounted Root. Content may retain exclusivity
through its closing transition; hidden retained content needs explicit `enabled` handling.
Preserve commands needed inside the modal: GotoAnything consumes repeated `Mod+K` inside its
scope while the global opener is suspended. Scope precedence and exceptions belong to [scope].
Use normal library consumption unless the owner must decide whether to claim an event:
- An element's native listener can precede child React handlers. When children must go first,
handle React bubbling, or use document bubble plus owner containment as Workflow does.
`capture: true` is for an intentional requirement to precede descendants, not a general fix.
- The manager does not skip `defaultPrevented`. Conditional owners set `preventDefault: false`
and `stopPropagation: false`, check scope and `defaultPrevented`, then consume accepted events.
Consume repeats before returning on `event.repeat`; leave `requireReset` unset in this mode
so its callback latch cannot bypass that consumption. `stopPropagation()` does not stop
another callback on the same manager target.
- Keep IME protection for custom submission and logical Enter/Escape, including existing
composition-end handling. Library composition filtering does not cover those named keys.
- A container delegating child events retains its real semantics. Explain a necessary lint
exception instead of adding a fake button role or tab stop.
[Character shortcuts], including Shift plus a character, must be disableable, remappable to
include a non-character key, or limited to focus within their owning component. Input filtering
or an active page-wide scope alone is insufficient.
## Workflow boundaries
| Owner | Responsibility |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canvas | `WorkflowCanvas` supplies the ReactFlow root ref. `useWorkflowHotkeys` runs after child React handlers and accepts only events within that subtree. |
| Graph actions | Existing graph hooks own permissions, mutations, history, and persistence. Keyboard commands invoke them. |
| Editors and nodes | ReactFlow, local handlers, Lexical, CodeMirror, and forms own navigation, undo, suggestions, and submission. |
| Portalled menus | Match displayed commands and act on the actual node, edge, or selection. |
| Run and history | Header features own page commands; header focus is unnecessary. |
| Comments | Focused draft/thread dismissal runs after suggestions. Active pointer-following placement owns Escape without taking focus. |
The outer Workflow container includes unrelated panels; use the canvas root for graph scope.
Restore canvas focus after deleting its focused object or applying graph undo/redo. Use Popup
`finalFocus` when a menu action deletes its return target. Hold-to-dim combines held-key state
with canvas focus and clears on focus loss; held-key state alone does not establish ownership.
## Verification
Follow [Web testing]. Use the real matcher/manager to verify affected scope, availability,
mount/reopen behavior, child priority, IME flags, and repeats. Check native editing, focus, and
selection in a browser, and both platform modifiers for binding or hint changes. State the
limits of simulated IME and mocked business actions.
[Character shortcuts]: https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html
[React guide]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/hotkeys
[Web testing]: test.md
[app hotkeys]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/app-hotkeys
[defaults]: https://tanstack.com/hotkeys/latest/docs/guides/sensible-defaults
[formatting]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/formatting-display
[scope]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/hotkeys-provider-and-scopes
---
### Web Docs Landmarks (`web/docs/landmarks.md`)
# Page Landmarks
Web owns landmark composition across route layouts and feature components. Use the
[W3C landmark guide] for role semantics and the Dify UI [naming contract] for accessible
names. This guide records how those contracts apply to Web pages.
## Page Ownership
- Place perceivable page content in meaningful landmark regions and check coverage after
composing the layout and its children.
- Trace the parent layouts before adding a page-level landmark. Inspect the composed
page, including parallel route slots and portals, rather than judging a component alone.
- [MainNavLayout] provides the console's `main` and skip-navigation target. Descendant
pages and editors must not create another `main`. Hiding the main navigation does not
remove this wrapper. A route outside this layout must establish its own main-content
boundary in its owning layout or page.
- Keep the skip link and its target under the same layout owner. Preserve the target ID
and focus behavior when changing wrappers; a landmark role alone does not move focus.
- Keep page and section headings meaningful inside these boundaries. A heading does not
create a landmark or automatically name its surrounding section.
## Choose Roles by Content
- Use `nav` for a meaningful group of navigation links. A grid of resource cards is not
automatically navigation merely because its cards can open detail pages.
- A visual sidebar is not automatically complementary content. File controls, editors,
and builder or version panels are parts of the current task. Use ordinary containers
or named sections according to their navigation value. Follow APG's recommendation
to keep genuine complementary landmarks at the top level.
- Reserve named `section` regions for content useful to reach directly. Avoid turning
every wrapper, card, or modal body into a landmark. Prefer an existing visible heading
as the naming source, following the [naming contract].
- Give repeated landmarks distinct names by purpose unless their content and purpose
are identical. Keep names localized and avoid repeating the role in the name.
- Page-level `header` and `footer` can expose `banner` and `contentinfo`. Their implicit
roles depend on ancestors; local panel headers and footers do not necessarily expose
those landmarks. Check the composed context before adding explicit roles.
## Verify the Composed Page
- Check the main-content boundary, landmark hierarchy, names, and heading relationships
in the relevant loaded, empty, collapsed, and open-overlay states. Exclude hidden
skeletons from the exposed landmark inventory. Check that label references still
resolve when conditional content changes.
- When changing a semantic element, inspect affected unit tests and E2E locators,
including CSS selectors such as `closest('main')`. Locate the intended feature or
control instead of relying on an extra page landmark or positional selection among
duplicate landmarks.
- Follow [Web testing policy] for regression coverage. At composition boundaries, keep
the components that own landmark semantics real; a mocked sidebar cannot prove the
real sidebar's role. Distinguish DOM assertions and Cucumber dry-runs from actual
browser or assistive-technology verification.
[MainNavLayout]: ../app/components/main-nav/layout.tsx
[W3C landmark guide]: https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions
[Web testing policy]: test.md
[naming contract]: ../../packages/dify-ui/docs/accessible-names-and-descriptions.md
---
### Web Docs Lint (`web/docs/lint.md`)
# Static Check Guide
See the [repository tooling guide] for linting, formatting, static checks, and custom rule maintenance.
[repository tooling guide]: ../../packages/tooling/README.md
---
### Web Docs Test (`web/docs/test.md`)
# Frontend Testing Guide
This document is the single source of truth for automated frontend tests under `web/`. Tests should protect product behavior and make refactoring safer. They are not a file-by-file completion exercise. Dify UI owns its package-specific test boundary in the [Dify UI testing contract].
## Testing Mindset
Write or update a test when a change affects a stable, observable contract:
- User interactions and resulting UI state.
- Navigation, URL state, persistence, permissions, or data flow.
- Loading, success, error, and empty states that users can actually reach.
- Accessibility semantics, keyboard behavior, focus management, or disabled state.
- Business logic or a reusable utility with meaningful input/output behavior.
- A bug fix whose regression can be reproduced through a public boundary.
Do not add tests merely for file/prop coverage, render-without-crashing checks, React implementation choices, or inputs excluded by TypeScript and the product contract.
Decide whether a regression needs lasting automated coverage before choosing its boundary or runtime. Check existing tests first. For visual-only changes, default to reviewing the real UI at representative widths and states; record the result without adding a permanent test. Automate a stable visual requirement or meaningful regression risk, not every design adjustment. Do not move a low-value test to another runner or a screenshot suite merely to keep coverage.
### Coverage
Coverage is a diagnostic signal, not a quality target. This guide defines no required percentage and reviewers should not request tests solely to increase coverage. Use a report to find suspicious gaps, then decide whether each gap represents a product risk worth protecting.
The unit coverage report includes authored JavaScript and TypeScript throughout `web/`, including runtime entry points, scripts, plugins, and files that no test imports. It excludes test infrastructure, stories, declarations, generated sources, tool configuration, build output, and vendored static code. TypeScript modules containing only erased types have no executable statements and are not meaningful zero-coverage findings. Local coverage runs also produce an HTML report at `coverage/index.html`.
Run the full `unit` project before using coverage to identify untested modules. A focused run measures only the selected tests. CI collects Browser Mode coverage separately and combines it with unit coverage under the same Codecov `web` flag. Zero unit coverage does not imply that Browser Mode or E2E never exercises the file; E2E does not contribute to the coverage report. Anonymous VM scripts and subprocesses can also execute code without attributing coverage to its source file. Check existing tests and separate product modules from development tooling when prioritizing the findings.
## Choose the Right Boundary
Use the smallest boundary that includes the behavior owner and proves the product contract without coupling the test to implementation:
- Test pure transformations and business rules as unit tests.
- Test hooks directly only when the hook itself exposes a reusable public contract. Otherwise, exercise the hook through its owning component or feature.
- Use React Testing Library for component and feature behavior visible through the DOM or external side effects.
- Use integration tests for behavior that crosses meaningful module boundaries.
- Use the `browser` project when it adds meaningful browser evidence under [Browser Mode Admission].
- Follow the [Dify UI testing contract] for the Storybook and Vitest boundary of Dify UI primitives.
Test the behavior owner. Barrel exports, pass-through wrappers, and purely presentational children do not need separate tests when the owning feature already proves their contract. Do not repeat generic behavior already owned by Base UI, React Aria, or the browser; test Dify's integration, overrides, and known regressions.
### Browser Mode Admission
Web defaults to the `unit` project in `happy-dom`. This is a project tradeoff, not a Vitest restriction: [Vitest component testing] recommends Browser Mode, and [Vitest visual regression testing] supports visual contracts.
A new browser test must establish all three:
- **Value:** name the user-visible failure or stable visual requirement worth protecting. Layout, focus, portals, observers, and “happy-dom cannot do this” alone are not justification; neither are primitive or native defaults such as focus returning to the trigger that opened an overlay or Space activating a button.
- **Additional evidence:** identify what existing owner tests miss and what real rendering or browser interaction adds. Do not repeat a state matrix just because a browser fixture exists; a viewport, theme, key, or variant row needs its own failure mode, otherwise keep the hardest row.
- **Faithful boundary:** exercise the production owner and assert the claimed result. A copied layout cannot prove page integration; cursor or hover styling cannot prove that clicking performs an action.
Use the smallest scenario that supplies that evidence. Native selection, focus restoration to CSS-hidden controls, hit testing, scrolling, and animation completion can justify browser coverage. Ordinary event handling and DOM state usually belong in `unit`. Synthetic events can test handler responses but do not prove native gesture generation, capture, or event ordering; use the [Vitest Interactivity API] when those are the contract.
Do not add permanent tests solely to freeze decorative spacing, radii, or artwork dimensions from a one-off visual adjustment. Geometry and computed styles are appropriate when they prove the chosen contract, such as readable content, unobstructed controls, or visible keyboard focus. Visual baselines need an explicit stable requirement and controlled rendering environment.
Each `*.browser.spec.{ts,tsx}` must make its regression and additional evidence clear from its scenario and assertions; add a short explanation only when needed. Do not use forced interaction, fixed sleeps, private DOM assertions, or real network requests.
Browser input is real and nothing waits between keys. Split a `userEvent.keyboard` sequence wherever a later key depends on state an earlier key produces, such as an opened menu or moved focus, and await that state with `expect.element` before continuing.
Browser Mode remains a focused component or feature test and currently proves Chromium only. Use the end-to-end suite for a running application, authentication, real routing, backend APIs, persistence, or complete journeys.
## Assert Behavior, Not Implementation
- Drive state transitions through props, user interaction, URL changes, or public APIs.
- Assert rendered UI, ARIA state, navigation, persistence, network-boundary calls, or another observable result.
- For a reset-or-persistence regression in a hidden surface, exercise the public transition: open, modify, close and wait for the surface to disappear, then reopen. Assert the intended behavior without coupling the test to hook placement, component names, keys, or private mount structure.
- Do not inspect React state, refs, hook call order, effect dependencies, or private DOM structure.
- Test referential identity only when identity is itself a documented public contract.
- One test should describe one behavior. It may contain multiple assertions when they jointly prove that behavior.
- Test only input states supported by the type and product contract. Do not manufacture `null`, `undefined`, or extreme values without a reachable scenario.
- Do not assert CSS class names or mechanically translate them into computed-style assertions. Assert the required outcome; use visual review for incidental styling.
- Use DOM or data snapshots only when serialized output is itself an intentionally public, stable contract. Visual baselines follow Browser Mode Admission.
## Queries, Interaction, and Accessibility
Prefer selectors in this order:
1. `getByRole` with an accessible name.
1. `getByLabelText` for labeled form controls.
1. `getByText`, `getByPlaceholderText`, or other user-visible queries when appropriate.
1. `getByTestId` only for boundaries with no useful DOM semantics, such as canvas output, editor shims, or mocked non-visual integrations.
When repeated content creates ambiguity, narrow to a semantic container, then query within it with `within` in React Testing Library or locator chaining in Browser Mode.
If an interactive control cannot be found semantically, first check whether the production markup needs a real button, link, label, landmark, or accessible name.
- In React Testing Library tests, use a `userEvent.setup()` instance inside the test. Use `fireEvent` only when the low-level event itself is the contract.
- In Browser Mode, interact through awaited locators. Use `.element()` only for DOM APIs that locators do not expose; it does not wait, so await the element with `expect.element` first.
- Semantic queries and automated checks do not constitute complete accessibility conformance.
- Exact copy assertions are valid when the copy or translation key is the contract; otherwise prefer a semantic query or resilient match.
- In React Testing Library, use `queryBy*` for synchronous absence, `findBy*` for asynchronous appearance, and `waitForElementToBeRemoved` or `waitFor` for asynchronous disappearance. In Browser Mode, use `expect.element` for eventual assertions.
## Mock at Real Boundaries
Keep the production code that owns or transforms the asserted behavior real. Mock only dependencies outside the target contract, where isolation improves the signal:
- Service and network boundaries.
- Next.js navigation or browser APIs not provided by the test environment.
- External SDKs and expensive providers.
- Independently tested child boundaries that do not own or transform the asserted behavior and whose setup would otherwise dominate the owner test.
Mocks must preserve the public contract needed by the test. Do not mock interactive Dify UI primitives or feature-owned wrappers around them. Keep their semantic roles, state attributes, portals, focus behavior, and `render(props, state)` contract real; mock only service or external-data boundaries needed to reach the scenario.
- Never make real network requests.
- Reset shared mock state before each test that mutates it.
- Create a fresh TanStack Query client for tests that exercise query behavior.
- Prefer typed builders with valid defaults for complex data. Add overrides only for fields relevant to the scenario.
- Keep local mocks local. Move a mock helper to `web/__mocks__/` only when multiple suites genuinely share it.
## Async, Time, and Isolation
- Await user interactions, promises, `findBy*`, and `waitFor`.
- Wait for observable state changes. Do not use fixed sleeps or broad retries to hide incorrect timing.
- Use fake timers only when timer behavior is part of the contract. Restore real timers after the test.
- Control time, randomness, network responses, and shared stores so tests are deterministic.
- `web/vitest.setup.ts` already runs Testing Library cleanup and resets Zustand stores after each test.
- Vitest 5 clears mock call history before each test. This does not reset mock implementations or external state; set those up explicitly for each case. Do not use `afterEach` to prepare the next test.
## Dify Test Setup
- Following [Vite+ testing configuration], tests under `web/` use two explicit projects in `web/vite.config.ts`. Supported commands and CI select one project explicitly: `unit` runs in `happy-dom` and loads `web/vitest.setup.ts`, while `browser` runs matching `{app,features}/**/*.browser.spec.{ts,tsx}` files in Playwright Chromium and loads `web/vitest.browser.setup.ts`. Bare `vp test` runs both registered projects.
- Browser string locators use Vitest 5's exact, case-sensitive matching. Use a regular expression or a per-locator `{ exact: false }` only when partial matching protects the intended behavior. Node tests use `@testing-library/jest-dom/vitest`; a regular-expression check against rendered text can use `expect(element.textContent).toMatch(pattern)` when the Vitest 5 browser matcher types conflict with jest-dom's `toHaveTextContent` overload.
- Tests in one browser file share a page. `web/vitest.browser.setup.ts` resets the viewport and pointer before each test; set the viewport a test depends on inside that test.
- Browser failures keep screenshots and Playwright traces under `web/.vitest-browser/`. CI uploads that directory only when failure artifacts exist; Browser Mode does not own coverage or report merging.
- New component and feature specs should generally use a sibling `__tests__/` directory. Existing colocated utility and hook specs may follow their owning module's convention. Cross-feature integration specs belong in `web/__tests__/`.
- The shared `react-i18next` mock is loaded globally. Use `createReactI18nextMock` from `web/test/i18n-mock` only when a test needs custom translations.
- For `nuqs` behavior, use the helpers in `web/test/nuqs-testing.tsx` and assert URL updates. Mock `nuqs` only when URL synchronization is explicitly outside the test contract.
- Do not add another test runner, DOM environment, or network interception library without a demonstrated project-level need.
## Workflow
Use the behavior owner and nearby tests to identify a realistic regression and the assertion that would catch it. For a behavior change or bug fix, establish the failing case first when practical. Remove redundant tests and assertions as readily as adding missing coverage.
Run the focused spec and the affected suite when it adds coverage beyond that spec, plus the required [static checks]. Once these pass, broaden or repeat verification only for new changes, failures, or unresolved concerns. Diagnose CI-only failures from the failing job and reproduce them locally when possible; reruns do not replace diagnosis or reporting.
## Commands
Run from `web/`:
```bash
# happy-dom; omit the path to run the full unit project
vp test run --project unit path/to/spec-or-directory
# Browser Mode; omit the path to run the full browser project
vp test run --project browser path/to/spec.browser.spec.tsx
# Watch mode; select browser instead for Browser Mode
vp test watch --project unit path/to/spec
# Diagnostic coverage report for the unit project; not an acceptance target
vp test run --project unit --coverage path/to/spec-or-directory
```
Always pass `--project unit` or `--project browser`. Bare `vp test` runs both registered projects and is not the standard Web test command.
## References
- [Vitest documentation]
- [Vitest test projects]
- [Why Browser Mode]
- [Vitest Browser Mode documentation]
- [Vitest Browser Mode locators]
- [Vitest Browser Mode traces]
- [Storybook Vitest addon]
- [Testing Library guiding principles]
- [React Testing Library documentation]
- [Testing Library query guidance]
- [Testing Library user-event guidance]
- [Testing Library user-event convenience APIs]
[Browser Mode Admission]: #browser-mode-admission
[Dify UI testing contract]: ../../packages/dify-ui/docs/testing.md
[React Testing Library documentation]: https://testing-library.com/docs/react-testing-library/intro
[Storybook Vitest addon]: https://storybook.js.org/docs/writing-tests/integrations/vitest-addon
[Testing Library guiding principles]: https://testing-library.com/docs/guiding-principles
[Testing Library query guidance]: https://testing-library.com/docs/queries/about
[Testing Library user-event convenience APIs]: https://testing-library.com/docs/user-event/convenience
[Testing Library user-event guidance]: https://testing-library.com/docs/user-event/intro
[Vite+ testing configuration]: https://viteplus.dev/guide/test
[Vitest Browser Mode documentation]: https://vitest.dev/guide/browser
[Vitest Browser Mode locators]: https://vitest.dev/api/browser/locators
[Vitest Browser Mode traces]: https://vitest.dev/guide/browser/trace-view
[Vitest Interactivity API]: https://vitest.dev/api/browser/interactivity
[Vitest component testing]: https://vitest.dev/guide/browser/component-testing
[Vitest documentation]: https://vitest.dev/guide
[Vitest test projects]: https://vitest.dev/guide/projects
[Vitest visual regression testing]: https://vitest.dev/guide/browser/visual-regression-testing
[Why Browser Mode]: https://vitest.dev/guide/browser/why
[static checks]: lint.md
---
### Web Docs Toasts (`web/docs/toasts.md`)
# Toasts
A toast reports a result the user cannot see where they acted. It is the last choice for feedback, not the default completion signal of a mutation.
## Choose the Feedback Owner
Before adding a toast, check in order:
1. If the result is already visible where the user acted, add nothing.
1. If the feedback can live at the trigger, such as a button state, an inline message, or a field error, put it there.
1. Otherwise a toast is appropriate.
Show at most one toast for one user action. When an action succeeds with a warning, show the warning and not a separate success message.
## Choose the Type
The type says whether the thing the user asked for happened.
| Type | Meaning | Example |
| --------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `success` | It happened as asked, and the result is not on screen. | An export finished; reindexing started. |
| `warning` | It happened, but incompletely or with a side effect the user should know about. | An import completed with warnings. |
| `error` | It did not happen. | A request failed. |
| `info` | Something the user did not trigger happened, and it needs no response from the user. | A collaborator restored a version of the shared workflow. |
A toast is not the place to explain why an action is unavailable. When a precondition is not met, such as missing permission, a response still in progress, or a feature that is not available, prevent the action at the control instead: disable it, keep it focusable, and give the reason in a tooltip or inline text next to it.
## Success
Do not show a success toast when:
- A switch, select, segmented control, checkbox, toggle, or rating control shows the new value itself. After a failed request the control must show the server value again.
- A button copies content. Show the copied state on the button. For an icon button use [CopyFeedback], which changes the icon, the tooltip, and the accessible name.
- The created, changed, or removed item is visible on the current surface, whether the action ran inline, from a menu, or through a dialog that closed.
- The action navigates to the item it just created, or the page reloads right after.
A success toast is appropriate when the result is not on screen: a background job started, an import, export, or download finished, a save left the page looking the same, or the action left the page that showed its subject, such as deleting an item from its detail page. The message must name what happened. Do not use generic messages such as “Action succeeded” or “Modified successfully” in new code.
## Errors
- When a request fails and the server returns an error message, the request layer shows that message unless the request is `silent`; see `afterResponseErrorCode` in [request layer]. Do not add a second toast for the same failure in `catch` or `onError`.
- To present a request error differently, make the request `silent` (`{ context: { silent: true } }` for generated clients) and show the error inline. A `silent` request with no other error presentation fails without any feedback.
- Failures that never reach the request layer, such as a rejected clipboard write or a client-side exception, still need their own feedback.
- Client-side validation belongs at the field through the [form contract], never in a toast.
## Existing Code
Many existing calls predate these rules and are migrated in batches. Do not copy them into new code, and do not remove an error toast without confirming the request layer covers that failure.
[CopyFeedback]: ../app/components/base/copy-feedback/index.tsx
[form contract]: ../../packages/dify-ui/docs/forms.md
[request layer]: ../service/fetch.ts
---
### Web Docs Truncated Text Disclosure (`web/docs/truncated-text-disclosure.md`)
# Truncated Text Disclosure
Treat native `title` as an opt-in, supplemental product behavior. Do not treat it as a mechanical companion to `truncate`, `text-overflow`, or `line-clamp-*`.
Browser-rendered title tooltips are exempt from the author-controlled hover and focus behavior in [WCAG 1.4.13], but that exception is not an accessibility endorsement. [MDN] documents unreliable access for touch, keyboard, and assistive-technology users. The classifications below decide whether to add `title`; they do not establish WCAG conformance for the surrounding interaction.
Missing `title` is not by itself an accessibility defect. Native title tooltips must not:
- be the only way to access essential information;
- replace a visible label, accessible name, or accessible description;
- compete with an existing hover, focus, pointer, expand, copy, or detail interaction.
For automated `title` additions, trace the displayed value, final DOM element, and existing disclosure owner. Apply `SKIP`, `COVERED`, `AUTO`, and `REVIEW` in that order; add `title` only for `AUTO` candidates.
These classifications limit automatic `title` additions. For a requested disclosure fix, continue with the appropriate feature-owned interaction. `REVIEW` calls for resolving the disclosure design; it does not require stopping an already authorized fix or asking for approval of routine implementation choices.
## AUTO
Automatically add `title` only when every condition below is satisfied:
- The target is a native, non-editable, pointer-reachable text container whose own hit area receives the pointer, or a documented component that forwards `title` unchanged to that final DOM element.
- The final element intentionally implements single-line truncation. A truncation-related class alone is not sufficient evidence.
- The full content is a bounded, non-sensitive, single-line plain string.
- The truncated portion is supplemental; users do not need it to understand, distinguish, or complete the current task.
- “Bounded” means fixed text, an enum, or a value with an explicit owner-level maximum length.
- The exact already-evaluated display value can be reused without repeating a function call, getter, conversion, mutation, async operation, or other potentially effectful expression.
- The final rendered element does not already receive an equivalent title through its props, wrapper, child component, or covering interaction target.
- No Tooltip, Popover, expandable content, “show more” action, detail view, copy/reveal action, or other full-content owner exists. A PreviewCard counts only under the `COVERED` rule below.
- The native tooltip will not compete with another hover, focus, pointer, or keyboard interaction.
## COVERED
Classify as `COVERED` and make no change when the full content is already available through the current content, an accessible interaction, or a linked destination. An overlay is not automatically a disclosure owner:
- a Tooltip only when it duplicates non-essential full text already available from its trigger's readable text or accessible name;
- a [PreviewCard] whose trigger is a real destination link and whose destination contains the equivalent full content; the preview popup itself is only a visual enhancement, not the disclosure owner;
- a Popover that exposes the full content through pointer, keyboard, touch, and assistive technology;
- expandable or “show more” content;
- a detail view opened from the current surface;
- a copy or reveal action;
- a parent or covering interaction target that already provides the equivalent title.
## SKIP
Classify as `SKIP` and make no change when any condition below applies:
- The value contains or may contain a secret, token, API key, password, credential, or other sensitive data.
- The value is unbounded user content, multiline content, a comment, prompt, generated output, log body, or another potentially large string.
- The visible content is JSX, `ReactNode`, structured content, or would require a stringification helper.
- Producing the title would repeat or relocate evaluation of a function call, getter, conversion, mutation, async operation, or other potentially effectful expression.
- The element is an input, textarea, editable surface, `pointer-events-none`, covered by another element, or not the actual pointer target.
- An existing `title`, including `title=""`, would need to be overwritten or removed.
## REVIEW
Classify a proposed automatic `title` addition as `REVIEW` and explain the unresolved disclosure requirement when:
- the correct disclosure owner is ambiguous or product-specific;
- users need the full value to understand, distinguish, or complete the task, but no cross-input disclosure owner exists;
- the value bound or sensitivity cannot be proven;
- the final DOM element or pointer owner cannot be traced;
- the component is interactive;
- Tooltip or PreviewCard content would be the only path to the full content, or a PreviewCard trigger is not a destination link;
- a Popover or other disclosure cannot be reached across pointer, keyboard, touch, and assistive technology;
- the content uses `line-clamp-*` without an existing full-content path;
- actual truncation or the intended product behavior cannot be established from the owner contract.
Before adding `title` to a custom component, inspect its implementation and trace the prop to the final DOM element. A `value`, `label`, or similar prop may already provide the native title; do not add a duplicate at the call site.
Do not introduce:
- a repository-wide missing-title lint error;
- a mass autofix or migration;
- a `ReactNode`-to-string helper;
- suppressions for candidates outside the allowlist.
Test the feature-owned disclosure behavior through its public interface. Assert native `title` only when it is an explicitly accepted product contract. Do not use `getByTitle` or `toHaveAttribute('title', ...)` merely to prove a migration, and do not use title-based selectors to test unrelated interactions.
[MDN]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title#accessibility_concerns
[PreviewCard]: ../../packages/dify-ui/docs/overlays.md#primitive-semantics
[WCAG 1.4.13]: https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html
---
### Web Docs Webapp Document Gate (`web/docs/webapp-document-gate.md`)
# WebApp document availability gate
The optional Proxy gate checks default `/chat/:code`, `/chatbot/:code`, `/workflow/:code`, `/completion/:code`, and `/agent/:code` addresses before Next starts rendering. It does not replace Gateway checks on subsequent API requests. Environment/Enterprise address routing is unchanged.
Configure both server-only variables:
- `WEBAPP_ACCESS_PREFLIGHT_URL`: the fixed internal Gateway `/api/webapp/access-mode` endpoint. Do not point it at Core or a public redirecting origin.
- `WEBAPP_ACCESS_PREFLIGHT_PROXY_SECRET`: a random shared ingress secret. Do not use a `NEXT_PUBLIC_` variable, commit its value, include it in logs, or expose it in a response.
Every ingress location that forwards documents to Web must **overwrite**, not append or preserve, `X-Dify-Webapp-Client-Ip` with its validated visitor address and `X-Dify-Webapp-Proxy-Secret` with this secret. The ingress must itself have an explicit trusted-proxy policy; an arbitrary inbound XFF/CF header is not evidence of visitor identity. Web should not have an unprotected public port.
Web verifies the proof with a constant-time comparison and validates a single IP, then creates a fresh Gateway request with only `Accept` and a one-address `X-Forwarded-For`. Gateway must trust the Web peer's network and resolve the forwarded address using its existing trusted-hop policy. Original XFF, Forwarded, CF headers, Authorization, Cookie, and ingress proof are not forwarded. The URL is configuration-owned; request queries cannot select another upstream or supply an IP.
An unset URL leaves self-hosted routing unchanged. Once configured, missing/invalid attestation, timeout, redirects, invalid payloads, and dependency failures produce a non-cacheable 503. They are not application-not-found responses. Only the canonical Gateway/Core `404 app_not_found` produces the existing generic unavailable page, with a 404 status fixed before rendering and `Cache-Control: no-store`. The allow path retains existing rendering and authentication behavior.
The internal `/webapp-unavailable` destination has no application lookup, uses no caller-supplied query state, and is always a 404. Proxy clears its internal IP header on every request, including direct visits. Only a verified denial can populate that header. Locale resources are provided for server rendering; the existing error-page UI remains the owner of language selection, appearance, and navigation.
Validation must include real Next HTTP requests, not only an assertion on `NextResponse.status`: verify document status, absence of redirect, non-cacheability, matching missing/denied body, and unchanged allowed rendering. API availability and the edge trust configuration must be deployed before enabling these variables. Do not enable them globally in an environment whose Gateway does not route `/api`.
---
### Packages Dify Ui Docs Accessible Names And Descriptions (`packages/dify-ui/docs/accessible-names-and-descriptions.md`)
# Accessible Names and Descriptions
This cross-component contract is owned by Dify UI. It applies to Dify UI primitives and to
consumers composing those primitives. It depends only on Dify UI component contracts and upstream
web standards; application packages may add localization, testing, and product-specific rules
without redefining this contract.
[Base UI accessibility] owns the primitive mechanics it implements, such as roles, relationships,
keyboard interaction, and focus management. Dify UI and its consumers still own the final element,
label content, composition, and product meaning. Use this guide to choose those naming and
description sources. Open a component guide only when the decision reaches that component.
Use [ARIA in HTML][html-naming] for authoring conformance and the [name and description computation
specification][accname] to understand the current computation model. APG and MDN provide authoring
guidance; Base UI documents the behavior and usage guidance of the primitives Dify wraps. The Dify
conventions below choose among valid options without making a prohibited naming relationship valid.
## Start Here
An accessible name is the flat string that identifies a named element to assistive technology; not
every role permits one. An accessible description adds optional help, instructions, or consequences.
State such as checked, expanded, or disabled remains separate from the name, and changing status
remains with the feature's status or live-region owner.
For each changed element:
1. Inspect the final rendered element, role, text, and props forwarded by its primitive.
1. Prefer meaningful visible text or a native label relationship.
1. Use `aria-labelledby` when suitable visible text exists elsewhere in the DOM.
1. Use `aria-label` only when the role permits naming and no visible text can provide the name.
1. Add `aria-describedby` only for useful supplemental text; do not repeat the name.
1. Verify the computed name and description in every changed responsive and interaction state.
These choices follow the [W3C APG naming techniques][apg] and [MDN `aria-label` guidance]. Nearby
text is not a label relationship by proximity alone.
## Common Decisions
| Surface | Contract |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text button or link | Let meaningful child text name the action; do not repeat it in `aria-label`. Follow [Button] when a focused loading button changes its label. |
| Form control | Follow [Forms]. Use its label primitive or an associated native `label`, preserving label activation. |
| Icon-only command | Follow [IconButton]. Its component-specific contract requires one accessible-name source and a decorative glyph. |
| Dialog or named region | Reuse the visible title through the primitive title API or `aria-labelledby`; use `aria-label` only when no suitable visible title exists. |
| Related form-control group | Follow [Forms]. Use `Fieldset` with `FieldsetLegend` and preserve each control's own label. Other composite widgets follow their owning primitive. |
| Table or figure | Prefer `caption` or `figcaption` when appropriate. See the [APG caption guidance][captions] for name and description differences. |
| Image | Supply meaningful `alt`, or `alt=""` for a decorative image. |
| Plain `div` or `span` | Keep readable content; do not add `aria-label` or `aria-labelledby` to the default `generic` role. |
Naming permission comes from semantics, not the presence of an `aria-*` prop. Other roles also
prohibit naming. Do not invent a role merely to permit a label. A plain span may contain text
referenced by another element's `aria-labelledby`; that relationship names the referencing element,
not the span. Check [ARIA in HTML][html-naming] for restrictions on the final element.
## Names, Descriptions, and State
A description is optional when the name is sufficient. For a file action, the name might identify
the operation and file, while the description explains retention or recovery. Avoid repeating the
same sentence in both. See the [name and description computation specification][accname].
A name or description attribute is not a general announcement mechanism. Keep progress and
asynchronous updates with their existing feature owner. Follow [Button] for the narrower case of a
focused loading button whose visible label changes, and [Forms] for field error relationships.
## Overrides and References
Authoring preference differs from computation priority. An `aria-labelledby` value with at least
one valid ID reference is evaluated first. If its computed text is non-empty, it takes precedence
over `aria-label` and normal native or content naming. If its result is empty, name computation
continues to lower-priority sources; do not rely on that fallback to excuse a broken reference. A
non-empty `aria-label` also overrides normal native or content naming; these sources are not
concatenated. See the [computation steps][computation].
- With `aria-labelledby`, reference the intended text directly. Multiple IDs are read in attribute
order; do not build chains of elements that each use `aria-labelledby`.
- Overriding a button or link's content-derived name can suppress meaningful descendant content in
its accessible representation. Preserve the necessary visible wording in the resulting name.
- Inspect IDs generated by primitives before overriding them. Keep IDs unique across repeated rows
and simultaneous dialogs, and ensure referenced nodes exist in relevant open, closed, and
responsive states. Preserve existing description IDs when adding another relationship.
- Do not use `title`, `placeholder`, or Tooltip content as the only naming source. Native `title`
does not replace an intentional name or description relationship.
## Write Useful Names
Keep the visible label's wording in the accessible name, preferably at the beginning. Add target
context when identical visible actions would otherwise be ambiguous. Matching visible words also
lets speech-input users invoke what they see. See [WCAG Label in Name][label-in-name].
Use concise action or purpose wording. Avoid appending role words already announced by assistive
technology or duplicating state exposed by the control. Consumers own localization and pass the
complete localized text through public props or children; Dify UI primitives do not import
application i18n.
The following fragment assumes localized strings and owner-scoped unique IDs. It combines the
visible action with the file it affects:
```tsx
<>
{fileName}
```
## Associate Descriptions
Use `aria-describedby` to associate concise help or consequences with a named control. The
referenced content becomes a plain string: headings, lists, and interactive links do not retain
their structure in the description. Keep rich instructions reachable as normal content or through
the [Overlay] contract. `aria-details` may supplement structured content where supported; it does
not replace that reachable content. See [MDN `aria-describedby` guidance][describedby].
In Dify fields, compose `FieldDescription` and `FieldError` with the appropriate label and control.
These primitives own their relationships, including invalid-state feedback. Do not overwrite them
with a second label or a competing error association:
```tsx
{fileNameLabel}{formatHint}{requiredMessage}
```
Use `DialogTitle` and, when useful, `DialogDescription` for a short dialog summary. Do not turn a
whole form or rich dialog body into one description. Tooltip content is not the trigger's
accessible-name source: icon-only triggers still need their own name, while persistent visible
trigger text should continue to name the control.
Prefer descriptions associated with DOM text. When considering `aria-description`, verify target
browser and assistive-technology behavior. The [AccName 1.2 working draft] gives
`aria-describedby` precedence over `aria-description`, followed by applicable native description
sources and unused `title` fallback. It specifies using only the first applicable source, even when
that source computes to an empty description. Do not stack mechanisms to force repeated output.
## Hidden Text and Safe Removal
- `sr-only` hides text visually while retaining it for assistive technology. It can contribute to
a content-derived name or serve as a referenced label or description. A standalone span does not
name a sibling control, and `sr-only` is not an automatic replacement for `aria-label`.
- `hidden`, `display: none`, `visibility: hidden`, and `aria-hidden="true"` normally exclude content
during name calculation. Explicitly referenced hidden nodes can still contribute; inspect the
reference and its subtree instead of assuming all hidden text is ignored. See the [computation
steps][computation] and [description reference][describedby].
- Before removing a label, inspect the resulting name and description in collapsed navigation,
responsive icon-only layouts, loading, and disabled states. CSS truncation alone does not remove
underlying text. Preserve primitive relationships and necessary status information. Add hidden
text only when information would otherwise be missing.
- Verify observable names, descriptions, and keyboard behavior at the changed boundary. Follow the
test policy owned by that package or consumer. Dify UI changes follow [Package testing]; complex
overrides may also require inspecting the rendered accessibility tree and relevant screen-reader
behavior.
[APG]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions#namingtechniques
[AccName 1.2 working draft]: https://www.w3.org/TR/accname-1.2#mapping_additional_nd_description
[Base UI accessibility]: https://base-ui.com/react/overview/accessibility
[Button]: ../src/button/README.md
[Forms]: forms.md
[IconButton]: ../src/icon-button/README.md
[MDN `aria-label` guidance]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label
[Overlay]: overlays.md
[Package testing]: testing.md
[accname]: https://www.w3.org/TR/accname-1.2#name_and_description
[captions]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions
[computation]: https://www.w3.org/TR/accname-1.2#computation-steps
[describedby]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby
[html-naming]: https://www.w3.org/TR/html-aria#requirements-for-use-of-aria-attributes-to-name-elements
[label-in-name]: https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html
---
### Packages Dify Ui Docs Authoring (`packages/dify-ui/docs/authoring.md`)
# Public API Authoring
Each `src//index.tsx` is an explicit public API boundary. Keep implementation details
module-local and publish the complete surface through separate `export { ... }` and
`export type { ... }` manifests at the bottom of the file. Do not mix scattered inline exports
with the manifest or use wildcard exports.
## Base UI imports
Import a Base UI part once per module and read its types from that binding's namespace, such as
`BaseRadio.Root.Props`. Use `import type` only when the module has no runtime use of the part. Do
not keep a value import and a type import of the same module side by side.
Add a public utility subpath only when an application consumer needs it. Inside the package,
use an existing utility entrypoint; otherwise import directly from `@base-ui/utils`.
## React imports
Use React namespace imports throughout this package, including stories and tests. Use
`import * as React from 'react'` when calling React runtime APIs, and
`import type * as React from 'react'` when referencing only React types. A runtime namespace
import also covers React types; do not add separate named type imports. JSX alone does not
require an explicit React import.
Use namespace imports for `react-dom`, `react-dom/client`, and `react-dom/server` as well.
Write grouping fragments as `` and remove unnecessary fragment wrappers.
## Component writing style
Define named components with function declarations or function expressions. Arrow functions
remain appropriate for event handlers, render props, and Storybook render callbacks. Name function
expressions when JavaScript cannot infer their name. Use `event` or `error` instead of `e`.
## Subpaths and names
Every public primitive needs a matching `package.json#exports` subpath. Import relatively between
package components; consumers import only through public subpaths.
Keep package-private helpers in `src/internal/`; top-level runtime utility modules in `src/` are
public utility subpaths. Components share code through the owning component's entrypoint or an
explicit internal module, not another component's implementation files.
Use the primitive name without a `Root` suffix for the canonical boundary and matching props type:
`Select` and `SelectProps`, `Drawer` and `DrawerProps`.
Every runtime component must have an accurate, importable props type with the matching name. Use a
direct alias for an unchanged Base UI part. Define Dify-authored composite props at the Dify UI
boundary instead of copying upstream shapes.
Use a discriminated union when one prop changes the valid shape of related props, such as
controlled versus uncontrolled state or single versus multiple selection.
## Generic contracts
Preserve generic relationships end to end, including picker `Value` and `Multiple`, form values,
radio and slider values, and overlay payloads or handles. Do not erase caller-owned types with
`any` or a hard-coded `string`. Use `unknown` only as the safe default for independently consumed
anatomy whose value JSX cannot infer from its parent.
Do not add a root-only generic when separately rendered anatomy can produce values outside the
root's inferred type. Preserve the upstream contract until the whole component family can enforce
one value type. `Tabs` intentionally follows Base UI's non-generic root because its current tab
value type is `any | null`; do not advertise a type relationship the complete anatomy cannot
enforce.
Preserve upstream anatomy when its parts own distinct semantics, interaction, or positioning.
Create a Dify-authored convenience component only when the package adds a shared contract; do not
hide primitive parts merely to shorten a consumer call site.
## Keep the public surface small
A type is not public merely because Base UI names it or an implementation once exported it. In
addition to matching component props, export a type only when it pairs with a public factory or a
real consumer must name it independently.
State, controlled-state helpers, context values, render helpers, styling helpers, and upstream
passthrough aliases are private by default. Public props already provide contextual typing for
inline render and event callbacks. Expose styling helpers only when consumers need to reuse
appearance independently.
Event details and reasons are the exception. A component that aliases or wraps a Base UI part
re-exports that part's `*EventDetails` and `*EventReason` types under its own name. A composite
that only uses a part internally does not. `State` and enum namespaces stay private.
Preserve upstream `className` and `style` callbacks. Resolve `className` with the owning Base UI
part's state before merging default classes with `cn()`, including through composite wrappers.
Forward `style` unchanged unless the wrapper needs to merge styles; then resolve its callback first.
Do not add state callbacks to native DOM props or unrelated custom APIs. See [Styling].
## Evidence
Use local public-subpath type tests to protect generic inference, required relationships, and
intentional errors. Read current official Base UI documentation and installed type declarations
before changing an upstream-derived contract.
[Styling]: ./styling.md
---
### Packages Dify Ui Docs Forms (`packages/dify-ui/docs/forms.md`)
# Forms
Dify UI form primitives compose Base UI's native form semantics, field accessibility, and Dify
styling. They are not a form state-management or schema framework. See the [Base UI forms
handbook] for the upstream model.
## Submit boundary
Every group of controls that saves or submits together needs a real `
