diff --git a/docs.json b/docs.json index ced4ba93..47a1b692 100644 --- a/docs.json +++ b/docs.json @@ -133,6 +133,7 @@ ] }, "en/guides/workflow/publish", + "en/guides/workflow/structured-outputs", "en/guides/workflow/bulletin" ] }, @@ -567,6 +568,7 @@ ] }, "zh-hans/guides/workflow/publish", + "zh-hans/guides/workflow/structured-outputs", "zh-hans/guides/workflow/bulletin" ] }, @@ -688,6 +690,7 @@ { "group": "代码扩展", "pages": [ + "zh-hans/guides/tools/extensions/code-based/README", "zh-hans/guides/tools/extensions/code-based/external-data-tool", "zh-hans/guides/tools/extensions/code-based/moderation" ] @@ -1059,6 +1062,7 @@ ] }, "ja-jp/guides/workflow/publish", + "ja-jp/guides/workflow/structured-outputs", "ja-jp/guides/workflow/bulletin" ] }, diff --git a/en/guides/management/app-management.mdx b/en/guides/management/app-management.mdx index 9f991624..5383ecee 100644 --- a/en/guides/management/app-management.mdx +++ b/en/guides/management/app-management.mdx @@ -22,7 +22,7 @@ Applications created in Dify support export in DSL format files, allowing you to ![](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/management/544c18d770e230db93d6756bba98d8a7.png) -The DSL file does not include authorization information already filled in [Tool](/en/guides/workflow/nodes/tools) nodes, such as API keys for third-party services. +The DSL file does not include authorization information already filled in [Tool](/en/guides/workflow/node/tools) nodes, such as API keys for third-party services. If the environment variables contain variables of the `Secret` type, a prompt will appear during file export asking whether to allow the export of this sensitive information. diff --git a/en/guides/workflow/bulletin.mdx b/en/guides/workflow/bulletin.mdx index 64850bdd..3956ee16 100644 --- a/en/guides/workflow/bulletin.mdx +++ b/en/guides/workflow/bulletin.mdx @@ -49,7 +49,7 @@ If you wish to add the “Image Upload” feature to a Chatflow application, ena If you have already created Workflow applications with the “Image Upload” feature enabled and activated the Vision feature in the LLM node, this change will not affect you immediately, but you will need to complete manual migration before the official deprecation. -If you wish to enable the “Image Upload” feature for a Workflow application, add a file variable in the [Start](/en/guides/workflow/nodes/start) node. Then, reference this file variable in subsequent nodes instead of using the `sys.files` variable. +If you wish to enable the “Image Upload” feature for a Workflow application, add a file variable in the [Start](/en/guides/workflow/node/start) node. Then, reference this file variable in subsequent node instead of using the `sys.files` variable. #### For Dify Community Edition or Self-hosted Enterprise Users: @@ -65,7 +65,7 @@ If you wish to add the “Image Upload” feature to a Chatflow application, ref Existing Workflow applications will not be affected, but please complete the manual migration before the official deprecation. -If you wish to enable the “Image Upload” feature for a Workflow application, add a file variable in the [Start](/en/guides/workflow/nodes/start) node. Then, reference this file variable in subsequent nodes instead of using the `sys.files` variable.\ +If you wish to enable the “Image Upload” feature for a Workflow application, add a file variable in the [Start](/en/guides/workflow/node/start) node. Then, reference this file variable in subsequent node instead of using the `sys.files` variable.\ ### FAQs: @@ -93,7 +93,7 @@ For Workflow applications: • Create a file-type variable in the “Start” node. -• Reference this file variable in subsequent nodes instead of using the LEGACY `sys.files` variable. +• Reference this file variable in subsequent node instead of using the LEGACY `sys.files` variable. #### 4. How to handle missing image upload icons in previously published Chatflow applications? diff --git a/en/guides/workflow/key-concepts.mdx b/en/guides/workflow/key-concepts.mdx index 9d0d3306..2cd7b6fa 100644 --- a/en/guides/workflow/key-concepts.mdx +++ b/en/guides/workflow/key-concepts.mdx @@ -3,17 +3,17 @@ title: Key Concepts --- -### Nodes +### node -**Nodes are the key components of a workflow**. By connecting nodes with different functionalities, you can execute a series of operations within the workflow. +**node are the key components of a workflow**. By connecting node with different functionalities, you can execute a series of operations within the workflow. -For core workflow nodes, please refer to [Block Description](/en/guides/workflow/nodes). +For core workflow node, please refer to [Block Description](/en/guides/workflow/node). *** ### Variables -**Variables are used to link the input and output of nodes within a workflow**, enabling complex processing logic throughout the process. Fore more details, please take refer to [Variables](/en/guides/workflow/variables). +**Variables are used to link the input and output of node within a workflow**, enabling complex processing logic throughout the process. Fore more details, please take refer to [Variables](/en/guides/workflow/variables). *** @@ -39,9 +39,9 @@ alt="" /> -**Differences in Available Nodes** +**Differences in Available Node** -1. The [End node](/en/guides/workflow/nodes/end) is an ending node for Workflow and can only be selected at the end of the process. -2. The [Answer node](/en/guides/workflow/nodes/answer) is specific to Chatflow, used for streaming text output, and can output at intermediate steps in the process. -3. Chatflow has built-in chat memory (Memory) for storing and passing multi-turn conversation history, which can be enabled in nodes like LLM and question classifiers. Workflow does not have Memory-related configurations and cannot enable them. -4. Built-in variables for Chatflow's [start node](/en/guides/workflow/nodes/start) include: `sys.query`, `sys.files`, `sys.conversation_id`, `sys.user_id`. Built-in [variables](/en/guides/workflow/variables) for Workflow's start node include: `sys.files`, `sys_id`. +1. The [End node](/en/guides/workflow/node/end) is an ending node for Workflow and can only be selected at the end of the process. +2. The [Answer node](/en/guides/workflow/node/answer) is specific to Chatflow, used for streaming text output, and can output at intermediate steps in the process. +3. Chatflow has built-in chat memory (Memory) for storing and passing multi-turn conversation history, which can be enabled in node like LLM and question classifiers. Workflow does not have Memory-related configurations and cannot enable them. +4. Built-in variables for Chatflow's [start node](/en/guides/workflow/node/start) include: `sys.query`, `sys.files`, `sys.conversation_id`, `sys.user_id`. Built-in [variables](/en/guides/workflow/variables) for Workflow's start node include: `sys.files`, `sys_id`. diff --git a/en/guides/workflow/node/llm.mdx b/en/guides/workflow/node/llm.mdx index 7c6278c1..dca136ac 100644 --- a/en/guides/workflow/node/llm.mdx +++ b/en/guides/workflow/node/llm.mdx @@ -133,19 +133,199 @@ If you do not understand what these parameters are, you can choose to load prese **Error Handling**: Provides diverse node error handling strategies that can throw error messages when the current node fails without interrupting the main process, or continue completing tasks through backup paths. For detailed information, please refer to the [Error Handling](/en/guides/workflow/error-handling). +**Structured Outputs**: Ensures LLM returns data in a usable, stable, and predictable format, helping users to control exactly how their LLM nodes return data. + + + +The **JSON Schema Editor** in LLM nodes lets you define how you want your data structured. You can use either the **Visual Editor** for a user-friendly experience or the **JSON Schema** for more precise control. + + +JSON Schema Editor supports structured outputs across all models: + +- Models with Native Support: Can directly use JSON Schema definitions. + +- Models without Native Support: Not all models handle structured outputs reliably. We will include your schema in the prompt, but response formatting may vary by model. + + +**Get Started** + +Access the editor through **LLM Node > Output Variables > Structured > Configure**. You can switch between visual and JSON Schema editing modes. + +![JSON Schema Editor](https://assets-docs.dify.ai/2025/04/646805384efa3cd85869d23a4d9735ad.png) + +***Visual Editor*** + +**When to Use** + +- For simple fields such as `name`, `email`, `age` without nested structures + +- If you prefer a drag-and-drop way over writing JSON + +- When you need to quickly iterate on your schema structure + +![Visual Editor](https://assets-docs.dify.ai/2025/04/a9d6a34a7903f81e4d57c7f1d8d0712b.png) + +**Add Fields** + +Click **Add Field** and set parameters below: + +- *(required)* Field Name + +- *(required)* Field Type: Choose from string, number, object, array, etc. + + > Note: Object and array type fields can contain child fields. + +- Description: Helps the LLM understand what the field means. + +- Required: Ensures the LLM always includes this field in its output. + +- Enum: Restricts possible values. For example, to allow only red, green, blue: + +```json +{ + "type": "string", + "enum": ["red", "green", "blue"] +} +``` + +**Manage Fields** + +- To Edit: Hover over a field and click the Edit icon. + +- To Delete: Hover over a field and click the Delete icon. + + > Note: Deleting an object or array removes all its child fields. + +**Import from JSON** + +1. Click **Import from JSON** and paste your example: + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. Click **Submit** to convert it into a schema. + +**Generate with AI** + +1. Click the AI Generate icon, select a model (like GPT-4o), and describe what you need: + + > “I need a JSON Schema for user profiles with username (string), age (number), and interests (array).” + +2. Click **Generate** to create a schema: + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["username", "age", "interests"] +} +``` + +***JSON Schema*** + +**When to Use** + +- For complex fields that need nesting, (e.g., `order_details`, `product_lists`) + +- When you want to import and modify existing JSON Schemas or API examples + +- When you need advanced schema features, such as `pattern` (regex matching) or `oneOf` (multiple type support) + +- When you want to fine-tune an AI-generated schema to fit your exact requirements + +![JSON Schema](https://assets-docs.dify.ai/2025/04/669af808dd9d0d8521a36e14db731cec.png) + +**Add Fields** + +1. Click **Import from JSON** and add your field structure: + +```json +{ + "name": "username", + "type": "string", + "description": "user's name", + "required": true +} +``` + +2. Click **Save**. Your schema will be validated automatically. + +**Manage Fields**: Edit field types, descriptions, default values, etc. in the JSON code box, and then click **Save**. + +**Import from JSON** + +1. Click **Import from JSON** and paste your example: + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. Click **Submit** to convert it into a schema. + +**Generate with AI** + +1. Click the AI Generate icon, select a model (like GPT-4o), and describe what you need: + + > “I need a JSON Schema for user profiles with username (string), age (number), and interests (array).” + +2. Click **Generate** to create a schema: + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["username", "age", "interests"] +} +``` + + + *** #### Use Cases * **Reading Knowledge Base Content** -To enable workflow applications to read [Knowledge Base](/en/guides/knowledge-base) content, such as building an intelligent customer service application, please follow these steps: +To enable workflow applications to read "[Knowledge Base](../../knowledge-base/)" content, such as building an intelligent customer service application, please follow these steps: 1. Add a knowledge base retrieval node upstream of the LLM node; 2. Fill in the **output variable** `result` of the knowledge retrieval node into the **context variable** of the LLM node; 3. Insert the **context variable** into the application prompt to give the LLM the ability to read text within the knowledge base. -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/988590f51629f43ac81770396456b372.png) +![上下文变量](../../../.gitbook/assets/image (135).png) The `result` variable output by the Knowledge Retrieval Node also includes segmented reference information. You can view the source of information through the **Citation and Attribution** feature. @@ -161,9 +341,9 @@ To enable workflow applications to read document contents, such as building a Ch * Add a document extractor node upstream of the LLM node, using the file variable as an input variable; * Fill in the **output variable** `text` of the document extractor node into the prompt of the LLM node. -For more information, please refer to [File Upload](/en/guides/workflow/file-upload). +For more information, please refer to [File Upload](../file-upload.md). -![input system prompts](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/373ac80deaf7ef9ed77019a94d31bed5.png) +![填写系统提示词](../../../.gitbook/assets/image (137).png) * **Error Handling** @@ -172,6 +352,46 @@ When processing information, LLM nodes may encounter errors such as input text e 1. Enable "Error Handling" in the LLM node 2. Select and configure an error handling strategy -![input system prompts](https://assets-docs.dify.ai/2024/12/f7109ce5e87c0e0a81248bb2672c7667.png) +![Error handling](https://assets-docs.dify.ai/2024/12/f7109ce5e87c0e0a81248bb2672c7667.png) -For more information about exception handling methods, please refer to the [Error Handling](/en/guides/workflow/error-handling). +For more information about exception handling methods, please refer to the [Error Handling](https://docs.dify.ai/guides/workflow/error-handling). + +* **Structured Outputs** + +**Scenario**: You are building a user feedback analysis workflow on Dify. The LLM node needs to read user reviews and return standardized ratings and comments in a consistent format for downstream nodes to process. + +**Solution**: In your workflow’s LLM node, you can use the JSON Schema Editor to define a structured format. This ensures the LLM generates results in a strict predefined format instead of unstructured text. + +1. Define your output structure in the JSON Schema Editor: + +```json +{ + "type": "object", + "properties": { + "rating": { + "type": "integer", + "description": "user's rating" + }, + "comment": { + "type": "string", + "description": "user's comments" + } + }, + "required": ["rating", "comment"] +} +``` + +2. Test it with a review in your Start node: + + > “This product is excellent!” + +3. The LLM node will return a clean, structured response: + +```json +{ + "structured_output": { + "comment": "This product is excellent!", + "rating": 5 + } +} +``` diff --git a/en/guides/workflow/structured-outputs.mdx b/en/guides/workflow/structured-outputs.mdx new file mode 100644 index 00000000..dd23eb58 --- /dev/null +++ b/en/guides/workflow/structured-outputs.mdx @@ -0,0 +1,58 @@ +--- +title: Structured Outputs +--- + +## Overview + +Dify’s structured outputs ensures LLMs return data in predictable JSON formats, making the output easier to process and integrate into applications. + +## Benefits + +- **Consistent Data Formatting**: All LLM-generated content follows predefined formats, eliminating data inconsistencies. + +- **Seamless Integration**: : Databases, APIs, or frontend applications can directly parse JSON Schema without additional data cleaning. + +- **Simplified Development**: Developers can skip writing complex validation code by letting JSON Schema handle output constraints. + +## Implementation Methods + +Dify offers two ways to create structured outputs: + +### Method 1: Tool Parameters + +Define your output structure directly in tool parameters. See **[Tool](https://docs.dify.ai/plugins/schema-definition/tool) > Data Structures > Return Variable Definitions**. + +### Method 2: JSON Schema Editor + +Use the built-in editor in LLM nodes. See **[LLM](https://docs.dify.ai/guides/workflow/node/llm) > Advanced Features > Structured Outputs** and **[LLM](https://docs.dify.ai/guides/workflow/node/llm) > Use Cases > Structured Outputs**. + +## Error Handling + +**What Can Go Wrong** + +When you are working with the JSON Schema Editor, you might run into a few common challenges: + +- **Limited Model Performance**: Smaller LLMs (like GPT-3.5 Turbo) sometimes have trouble following JSON Schema instructions correctly. + +- **Format Issues**: Some LLMs only understand basic JSON, not full JSON Schema. + +- **Error Messages**: You might see `Failed to parse structured output: output is not a valid json str` when the model fails to generate proper JSON. + +**How to Fix These Issues** + +1. **Choose the Right Model**. These models work best with JSON Schema: + - Gemini 2.0 Flash/Flash-Lite + - Gemini 1.5 Flash 8B (versions 0827/0924) + - Gemini-1.5 pro + - GPT-4o and GPT-4o-mini + - o1-mini/o3-mini series + +2. **Write Clear Instructions**. Make sure your prompts match what you are trying to do. For example, if you need mathematical formulas, don’t ask for legal analysis—this helps the AI understand exactly what you need. + +3. **Have a Backup Plan**. + + 1. Enable **Retry on Failure** with custom retry attempts and intervals. + + 2. Set up **Failure Branch** to handle any errors. + +See [Error Handling](https://docs.dify.ai/guides/workflow/error-handling) for more details. diff --git a/en/introduction.mdx b/en/introduction.mdx index 9f321e2c..a3e47961 100644 --- a/en/introduction.mdx +++ b/en/introduction.mdx @@ -1,6 +1,5 @@ --- title: Introduction -description: "Welcome to the home of your new documentation" --- Dify is an open-source platform for building AI applications. We combine Backend-as-a-Service and LLMOps to streamline the development of generative AI solutions, making it accessible to both developers and non-technical innovators. diff --git a/introduction.mdx b/introduction.mdx index fd06fcba..6b5ff457 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -1,6 +1,5 @@ --- title: Introduction -description: "Welcome to the home of your new documentation" --- + +LLMノードのJSONスキーマエディタを使用すると、LLM が返すデータ構造を定義し、出力の解析性、再利用性、制御性を保証できます。ビジュアル編集モードによる直感的な編集、コード編集モードによる詳細な調整により、様々な複雑度のニーズに対応できます。 + + +ノードレベルの機能であるJSONスキーマは、すべてのモデルの構造化出力の定義と制約に利用できます。 + +- 構造化出力をネイティブでサポートするモデル: JSONスキーマを使用して構造化変数を直接定義できます。 + +- 構造化出力をサポートしていないモデル: システムはJSONスキーマをプロンプトとして使用します。構造に基づいたコンテンツ生成をモデルに促せますが、出力の正しい解析は保証されません。 + + +**JSONスキーマエディタの開き方** + +LLMノードの出力変数をクリックし、構造化スイッチの設定を開くと、JSONスキーマエディタが表示されます。JSONスキーマエディタはビジュアル編集ウィンドウとコード編集ウィンドウを備え、シームレスに切り替えられます。 + +![JSON Schema Editor](https://assets-docs.dify.ai/2025/04/646805384efa3cd85869d23a4d9735ad.png) + +***ビジュアル編集*** + +**使用シーン** + +- ネスト構造を含まない、いくつかの単純なフィールドを定義する場合。 + +- JSONスキーマの構文に慣れていない場合、コードを書かずに、直感的なインターフェースでドラッグアンドドロップしてフィールドを追加できます。 + +- フィールド構造を素早く繰り返し変更したい場合。JSONコードを毎回変更する必要はありません。 + +![Visual Editor](https://assets-docs.dify.ai/2025/04/a9d6a34a7903f81e4d57c7f1d8d0712b.png) + +**フィールドの追加** + +構造化出力枠内でフィールドを追加ボタンをクリックし、フィールドのパラメータを設定します。 + +- *（必須）*フィールド名 + +- *（必須）*フィールドタイプ: string、number、object、arrayなどのフィールドタイプをサポートしています。 + + > オブジェクトまたは配列フィールドには、子フィールドを追加できます。 + +- 説明: LLMがフィールドの意味を理解し、出力精度を向上させます。 + +- 必須: オンにすると、LLMはこのフィールド値を必ず返します。 + +- 列挙型: フィールド値の選択範囲を制限するために使用します。モデルは、あらかじめ設定された列挙値のみを返します。たとえば、`red`、`green`、`blue` のみを許可する場合は、次のようになります。 + +```json +{ + "type": "string", + "enum": ["red", "green", "blue"] +} +``` + +> このルールでは、入力値は `red`、`green`、`blue` のいずれかでなければなりません。 + +**フィールドの編集・削除** + +- フィールドの編集：フィールドカードにマウスオーバーして、「編集」アイコンをクリックし、フィールドのタイプ、説明、デフォルト値などの項目を変更します。 + +- フィールドの削除：フィールドカードにマウスオーバーして、「削除」アイコンをクリックすると、フィールドがリストから削除されます。 + + > オブジェクトまたは配列フィールドを削除すると、そのすべての子フィールドも削除されます。 + +**JSONデータのインポート** + +1. 「JSONをインポート」ボタンをクリックし、表示されるダイアログボックスにJSONデータを貼り付けるか、アップロードします。例（JSONデータ）： + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. 「送信」ボタンをクリックすると、システムがJSONデータを自動的に解析し、JSONスキーマに変換します。 + +**AIでJSONスキーマを生成する** + +1. 「AI生成」アイコンをクリックし、モデル（GPT-4など）を選択します。入力ボックスにJSONスキーマの説明を入力します。例： + + > 「ユーザー名、年齢、および趣味を含むJSONスキーマが必要です。」 + +2. 「生成」をクリックすると、システムが自動的にJSONスキーマを生成します。 + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "username", + "age", + "interests" + ] +} +``` + +***コードエディタ*** + +**使用シーン** + +- 複雑なデータ構造で、ネストされたオブジェクトや配列をサポートする必要がある場合（例：注文詳細、商品一覧など）。 + +- 既存のJSONスキーマ（または API レスポンス例）を直接貼り付けて手動で調整したい場合。 + +- `pattern`（正規表現）や `oneOf`（複数タイプ）などの高度なスキーマ機能を使用したい場合。 + +- LLMで作成したスキーマを元に、フィールドのタイプや構造をビジネスニーズに合わせて変更したい場合。 + +![JSON Schema](https://assets-docs.dify.ai/2025/04/669af808dd9d0d8521a36e14db731cec.png) + +**フィールドの追加** + +1. コードエディタを開きます。 + +2. 「フィールドを追加」をクリックし、フィールドを入力します。例： + +```json +{ + "name": "username", + "type": "string", + "description": "user's name", + "required": true +} +``` + +3. 「保存」をクリックすると、システムがJSONスキーマを自動的に検証し、保存します。 + +**フィールドの編集・削除**：JSONコードボックスで、フィールドのタイプ、説明、デフォルト値などの項目を直接編集・削除し、「保存」をクリックします。 + +**JSONデータのインポート** + +1. 「JSONをインポート」ボタンをクリックし、表示されるダイアログボックスにJSONデータを貼り付けるか、アップロードします。例（JSONデータ）： + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. 「送信」ボタンをクリックすると、システムがJSONデータを自動的に解析し、JSONスキーマに変換します。 + +**AIでJSONスキーマを生成する** + +1. 「AI生成」アイコンをクリックし、モデル（GPT-4など）を選択します。入力ボックスにJSONスキーマの説明を入力します。例： + + > 「ユーザー名、年齢、および趣味を含むJSONスキーマが必要です。」 + +2. 「生成」をクリックすると、システムが自動的にJSONスキーマを生成します。 + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "username", + "age", + "interests" + ] +} +``` + + + *** -### ユースケース +### 活用事例 * **ナレッジベースの内容を検索する** -ワークフローアプリケーションが[「ナレッジベース」](/ja-jp/guides/knowledge-base/readme)の内容を検索できるようにしたい場合、例えばインテリジェントカスタマーサービスアプリケーションを構築する場合は、以下の手順を参考にしてください。 +ワークフローアプリケーションが[「ナレッジベース」](../../knowledge-base/)の内容を検索できるようにしたい場合、例えばインテリジェントカスタマーサービスアプリケーションを構築する場合は、以下の手順を参考にしてください。 1. LLMノードの上流に知識検索ノードを追加します； 2. 知識検索ノードの **出力変数** `result` をLLMノードの **コンテキスト変数** に入力します； 3. **コンテキスト変数** をアプリケーションのプロンプトに挿入し、LLMがナレッジベース内のテキスト内容を読み取れるようにします。 - - コンテキスト変数 - +![コンテキスト変数](../../../../en/.gitbook/assets/image (135).png) -[知識検索ノード](./knowledge-retrieval) の出力変数 `result` には引用情報も含まれており、[**引用と帰属**](/ja-jp/guides/knowledge-base/retrieval-test-and-citation) 機能を使用して情報の出所を確認できます。 +[知識検索ノード](knowledge-retrieval.md) の出力変数 `result` には引用情報も含まれており、[**引用と帰属**](../../knowledge-base/retrieval-test-and-citation.md#id-2-yin-yong-yu-gui-shu) 機能を使用して情報の出所を確認できます。 - + 通常のノードの変数もコンテキスト変数に入力可能ですが、例えば開始ノードの文字列型変数など、**引用と帰属** 機能は機能しません。 - + -* **文書ファイルの読み取り** +* **ドキュメントファイルの取り込み** -ChatPDF アプリケーションの構築など、ワークフロー アプリケーションにドキュメントのコンテンツを読み取る機能を提供する場合は、次を参照してください。 \ No newline at end of file +ワークフローアプリケーションでドキュメントの内容を取り込むことを可能にする場合、例えばChatPDFアプリケーションを開発する際には、以下の手順を踏んでください： + +* 「スタート」ノードへファイル変数を設定する； +* LLMノードの前段階にドキュメント抽出ノードを設置し、ファイル変数を入力として利用する； +* 抽出ノードからの**出力変数** `text` をLLMノードへの入力プロンプトとして設定する。 + +さらなる情報は、[ファイルアップロード](../file-upload.md)を参照してください。 + +![入力システムプロンプト](../../../.gitbook/assets/image (137).png) + +* **エラー処理** + +情報処理中に、LLMノードでは入力テキストがトークンの制限を超えたり、必要なパラメータが欠けているなどのエラーに遭遇することがあります。開発者は以下の手順に従い、エラー処理の枝を設定してノードエラーが発生した際の対処方針を構築することで、フローの中断を避けることができます： + +1. LLMノードで「エラー処理」を有効化する +2. エラー処理戦略を選択して設定する + +![エラー処理](https://assets-docs.dify.ai/2024/12/f7109ce5e87c0e0a81248bb2672c7667.png) + +エラー処理の詳細は、[エラー処理](https://docs.dify.ai/guides/workflow/error-handling)をご覧ください。 + +* **構造化出力** + +**シナリオ**: Difyワークフローを使用してユーザーフィードバック分析ワークフローを構築する際に、LLMノードはユーザー評価を読み取り、標準化された評価とコメントを返します。これにより、後続ノードがデータを正しく処理できるよう、データ形式の一貫性を保ちます。 + +**解決策**: ワークフローのLLMノードで、**JSONスキーマエディタ**を使用してLLM出力の構造化フォーマットを定義できます。これにより、LLM は自由形式のテキストではなく、定義済みのフォーマットに従って結果を出力します。 + +**操作手順**: + +1. **LLM**ノードの**JSONスキーマエディタ**で、以下のフィールドを追加します。これによりLLMは指定の構造でデータを出力します。 + +```json +{ + "type": "object", + "properties": { + "rating": { + "type": "integer", + "description": "ユーザー評価" + }, + "comment": { + "type": "string", + "description": "ユーザーコメント" + } + }, + "required": [ + "rating", + "comment" + ] +} +``` + +2. ワークフローの**開始**ノードで、ユーザー評価を入力します。例: + +> "この製品はとても素晴らしいです。使用体験も良好です！" + +3. **JSONスキーマエディタ**による処理後、LLMから出力される**構造化データ**は以下のようになります。 + +```json +{ + "structured_output": { + "comment": "この製品はとても素晴らしいです。使用体験も良好です！", + "rating": 5 + } +} +``` diff --git a/ja-jp/guides/workflow/structured-outputs.mdx b/ja-jp/guides/workflow/structured-outputs.mdx new file mode 100644 index 00000000..e2bff397 --- /dev/null +++ b/ja-jp/guides/workflow/structured-outputs.mdx @@ -0,0 +1,61 @@ +--- +title: JSON形式での出力 +--- + +DifyはLLMツールチェーンプラットフォームとして、JSON形式での出力機能をサポートしています。この機能により、LLMから返されるデータの形式が利用しやすく、安定し、予測可能になります。エラー処理やフォーマット変換の手間を削減できます。 + +## 利点 + +- **データ形式の整合性確保**: LLMがコンテンツを生成する場合でも、事前に設定された形式に準拠し、データの不整合を防ぎます。 + +- **後続処理の簡素化**: データベース、APIまたはフロントエンドは、追加のデータクレンジングなしでJSONスキーマを直接解析できます。 + +- **ローコード開発の効率化**: 開発者は複雑なデータ検証ロジックを手書きする必要がなく、JSONスキーマを使用して出力を制限できます。 + +## JSON形式での出力の実装方法 + +Difyの操作画面では、次の2つの方法でJSON形式での出力を実装できます。 + +- **方法1: ツール設定を直接行う** + +- **方法2: LLMノードのJSONスキーマエディタを使用する** + +### 方法1: ツール設定を直接行う + +**[Tool(ツール)](https://docs.dify.ai/ja-jp/plugins/schema-definition/tool) > データ構造 > 出力変数の定義**を参照してください。 + +### 方法2: LLMノードのJSONスキーマエディタを使用する + +**[LLM](https://docs.dify.ai/ja-jp/guides/workflow/node/llm) > 高級機能 > 構造化出力** と **[LLM](https://docs.dify.ai/ja/guides/workflow/node/llm) > 活用事例 > 構造化出力**を参照してください。 + +## 例外処理 + +**例外状況** + +JSONスキーマエディタを使用して構造化出力を行う際に、以下の制限や例外状況が発生する可能性があります。 + +- **モデルの能力制限**: 一部のLLM(特に70B以下のモデル、またはGPT-3.5Turbo相当のモデル)は、指示への追従性が低いため、JSONスキーマの解析に失敗する可能性があります。 + +- **形式の互換性**: 一部のLLMはJSONモードのみをサポートし、JSONスキーマをサポートしていないため、厳密なスキーマ解析に失敗する可能性があります。 + +- **エラーメッセージ**: `Failed to parse structured output: output is not a valid json str`というエラーが発生します。この種のエラーは、主にモデルがJSONの生成に失敗したことが原因です。 + +**推奨される対処方法** + +1. **JSONスキーマをサポートするモデルを優先的に使用する**: 推奨リストは以下のとおりです。 + - Gemini2.0Flash/Flash-Lite + - Gemini1.5Flash8B(0827/0924) + - Gemini-1.5pro + - GPT-4o + - GPT-4o-mini + - o1-mini/o3-miniシリーズ + +2. **システムプロンプトを適切に調整する**: 指示への追従性を高め、LLMの出力がスキーマ規範に準拠するように、システムプロンプトを調整してください。例えば、JSONスキーマが数式の構造化を目的としているのに、法律条文の解析を指示すると、モデルがタスクを正しく理解できず、出力の精度が低下する可能性があります。 + +3. **例外処理ポリシーを設定する**: 解析に失敗した場合、以下の対策を検討できます。 + + 1. **再試行設定**: ノード内で**再試行設定**を有効にし、最大再試行回数と再試行間隔を設定して、解析エラーの影響を軽減します。 + + 2. **エラー時の処理を設定する**: ノード内の**例外処理**で**エラー時の処理**を設定します。ノードで例外が発生すると、エラー時の処理が自動的に実行されます。 + +[エラー処理](https://docs.dify.ai/ja-jp/guides/workflow/error-handling)を参照してください。 diff --git a/zh-hans/getting-started/dify-for-education.mdx b/zh-hans/getting-started/dify-for-education.mdx index 66a533b2..67aa5835 100644 --- a/zh-hans/getting-started/dify-for-education.mdx +++ b/zh-hans/getting-started/dify-for-education.mdx @@ -98,11 +98,11 @@ Dify 教育版目前包含的权益为**一张 50% 折扣的 Dify 专业版优 ### 更新邮箱信息 -如果你的邮箱需要更改，目前只能由人工处理。请发送邮件至 `support@dify.ai` 寻求帮助。 +如果你的邮箱需要更改，目前只能由人工处理。请发送邮件至 [support@dify.ai](mailto:support@dify.ai) 寻求帮助。 ### 更新学校信息 -- **首次认证后修改学校信息**：如果你已完成教育认证，但需要更改学校信息，请发送邮件至 `` 寻求帮助。 +- **首次认证后修改学校信息**：如果你已完成教育认证，但需要更改学校信息，请发送邮件至 [support@dify.ai](mailto:support@dify.ai) 寻求帮助。 - **认证过期后修改学校信息**：当你的教育认证过期后，重新认证时可以填写新学校的信息。 diff --git a/zh-hans/getting-started/install-self-hosted/docker-compose.mdx b/zh-hans/getting-started/install-self-hosted/docker-compose.mdx index 1ffd1281..13aaa117 100644 --- a/zh-hans/getting-started/install-self-hosted/docker-compose.mdx +++ b/zh-hans/getting-started/install-self-hosted/docker-compose.mdx @@ -116,7 +116,7 @@ docker-web-1 langgenius/dify-web:0.6.13 "/bin/sh ./entrypoin… docker-worker-1 langgenius/dify-api:0.6.13 "/bin/bash /entrypoi…" worker About a minute ago Up About a minute 5001/tcp ``` -通过这些步骤，你应该可以成功在本地安装 Dify。 +通过这些步骤，你可以在本地成功安装 Dify。 ### 更新 Dify diff --git a/zh-hans/getting-started/install-self-hosted/environments.mdx b/zh-hans/getting-started/install-self-hosted/environments.mdx index 7a0146f0..ed90f002 100644 --- a/zh-hans/getting-started/install-self-hosted/environments.mdx +++ b/zh-hans/getting-started/install-self-hosted/environments.mdx @@ -1,607 +1,404 @@ --- -title: 环境变量说明 （待处理） +title: 环境变量说明 --- 本文档可能未及时更新，请优先参考最新的配置文件： - [docker-compose.yaml](https://github.com/langgenius/dify/blob/5f8d20b5b2bb51f19547467167b18d9c0f6ffbb8/docker/docker-compose.yaml) - - [.env.example](https://github.com/langgenius/dify/blob/5f8d20b5b2bb51f19547467167b18d9c0f6ffbb8/docker/.env.example) -### 公共变量 - -#### CONSOLE_API_URL - -控制台 API 后端 URL，用于拼接授权回调，传空则为同域。范例：`https://api.console.dify.ai`。 - -#### CONSOLE_WEB_URL - -控制台 web **前端** URL，用于拼接部分前端地址，以及 CORS 配置使用，传空则为同域。范例：`https://console.dify.ai` - -#### SERVICE_API_URL - -Service API URL，用于 **前端** 展示 Service API Base URL，传空则为同域。范例：`https://api.dify.ai` - -#### APP_API_URL - -WebApp API 后端 URL，用于声明 **前端** API 后端地址，传空则为同域。范例：`https://app.dify.ai` - -#### APP_WEB_URL - -WebApp URL，用于预览文件、**前端** 展示下载用的 URL，以及作为多模型输入接口，传空则为同域。范例：`https://udify.app/` - -#### FILES_URL - -文件预览或下载 URL 前缀，用于将文件预览或下载 URL 给前端展示或作为多模态模型输入； 为了防止他人伪造，图片预览 URL 是带有签名的，并且有 5 分钟过期时间。 - -*** - -### 服务端 - -#### MODE - -启动模式，仅使用 Docker 启动时可用，源码启动无效。 - -* api - - 启动 API Server。 -* worker - - 启动异步队列 worker。 - -#### DEBUG - -调试模式，默认 false，建议本地开发打开该配置，可防止 monkey patch 导致的一些问题出现。 - -#### FLASK_DEBUG - -Flask 调试模式，开启可在接口输出 trace 信息，方便调试。 - -#### SECRET_KEY - -一个用于安全地签名会话 cookie 并在数据库上加密敏感信息的密钥。初次启动需要设置该变量。可以运行 `openssl rand -base64 42` 生成一个强密钥。 - -#### DEPLOY_ENV - -部署环境。 - -* PRODUCTION（默认） - - 生产环境。 -* TESTING - - 测试环境，前端页面会有明显颜色标识，该环境为测试环境。 - -#### LOG_LEVEL - -日志输出等级，默认为 INFO。生产建议设置为 ERROR。 - -#### MIGRATION_ENABLED - -当设置为 true 时，会在容器启动时自动执行数据库迁移，仅使用 Docker 启动时可用，源码启动无效。源码启动需要在 api 目录手动执行 `flask db upgrade`。 - -#### CHECK_UPDATE_URL - -是否开启检查版本策略，若设置为 false，则不调用 `https://updates.dify.ai` 进行版本检查。由于目前国内无法直接访问基于 CloudFlare Worker 的版本接口，设置该变量为空，可以屏蔽该接口调用。 - -#### TEXT_GENERATION_TIMEOUT_MS - -默认 60000，单位为 ms，用于指定文本生成和工作流的超时时间，防止因某些进程运行超时而导致整体服务不可用。 - -#### CSP_WHITELIST - -内容安全策略（CSP）白名单，默认不开启。在此变量中填写被放行的域名列表后即视为开启，有助于减少潜在的 XSS 攻击。开启后，白名单将自动包含以下域名： - -```url -*.sentry.io http://localhost:* http://127.0.0.1:* https://analytics.google.com https://googletagmanager.com https://api.github.com -``` - -#### 容器启动相关配置 - -仅在使用 Docker 镜像或者 Docker-compose 启动时有效。 - -* DIFY_BIND_ADDRESS - - API 服务绑定地址，默认：0.0.0.0，即所有地址均可访问。 -* DIFY_PORT - - API 服务绑定端口号，默认 5001。 -* SERVER_WORKER_AMOUNT - - API 服务 Server worker 数量，即 gevent worker 数量，公式：`cpu 核心数 x 2 + 1` 可参考[文档](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) - -* SERVER_WORKER_CLASS - - 默认为 gevent，若为 windows，可以切换为 sync 或 solo。 -* GUNICORN_TIMEOUT - - 请求处理超时时间，默认 200，建议 360，以支持更长的 sse 连接时间。 -* CELERY_WORKER_CLASS - - 和 `SERVER_WORKER_CLASS` 类似，默认 gevent，若为 windows，可以切换为 sync 或 solo。 -* CELERY_WORKER_AMOUNT - - Celery worker 数量，默认为 1，按需设置。 -* HTTP_PROXY - - HTTP 代理地址，用于解决国内无法访问 OpenAI、HuggingFace 的问题。注意，若代理部署在宿主机 (例如 `http://127.0.0.1:7890`)，此处代理地址应当和接入本地模型时一样，使用 Docker 容器内部的宿主机地址（例如 `http://192.168.1.100:7890` 或 `http://172.17.0.1:7890`）。 -* HTTPS_PROXY - - HTTPS 代理地址，用于解决国内无法访问 OpenAI、HuggingFace 的问题。同上。 - -#### 数据库配置 - -数据库使用 PostgreSQL，请使用 public schema。 - -* DB_USERNAME：用户名 -* DB_PASSWORD：密码 -* DB_HOST：数据库 host -* DB_PORT：数据库端口号，默认 5432 -* DB_DATABASE：数据库 database -* SQLALCHEMY_POOL_SIZE：数据库连接池大小，默认 30 个连接数，可适当增加。 -* SQLALCHEMY_POOL_RECYCLE：数据库连接池回收时间，默认 3600 秒。 -* SQLALCHEMY_ECHO：是否打印 SQL，默认 false。 - -#### Redis 配置 - -该 Redis 配置用于缓存以及对话时的 pub/sub。 - -* REDIS_HOST：Redis host -* REDIS_PORT：Redis port，默认 6379 -* REDIS_DB：Redis Database，默认为 0，请和 Session Redis、Celery Broker 分开用不同 Database。 -* REDIS_USERNAME：Redis 用户名，默认为空 -* REDIS_PASSWORD：Redis 密码，默认为空，强烈建议设置密码。 -* REDIS_USE_SSL：是否使用 SSL 协议进行连接，默认 false -* REDIS_USE_SENTINEL：使用 Redis Sentinel 连接 Redis 服务器 -* REDIS_SENTINELS：哨兵节点，格式：`:,:,:` -* REDIS_SENTINEL_SERVICE_NAME：哨兵服务名，同 Master Name -* REDIS_SENTINEL_USERNAME：哨兵的用户名 -* REDIS_SENTINEL_PASSWORD：哨兵的密码 -* REDIS_SENTINEL_SOCKET_TIMEOUT：哨兵超时时间，默认值：0.1，单位：秒 - -#### Celery 配置 - -* CELERY_BROKER_URL - - 格式如下（直连模式）： - - ``` - redis://:@:/ - ``` - - 范例：`redis://:difyai123456@redis:6379/1` - - 哨兵模式： - - ``` - sentinel://:@:/ - ``` - - 范例：`sentinel://localhost:26379/1;sentinel://localhost:26380/1;sentinel://localhost:26381/1` - -* BROKER_USE_SSL - - 若设置为 true，则使用 SSL 协议进行连接，默认 false。 - -* CELERY_USE_SENTINEL - - 若设置为 true，则启用哨兵模式，默认 false。 - -* CELERY_SENTINEL_MASTER_NAME - - 哨兵的服务名，即 Master Name。 - -* CELERY_SENTINEL_SOCKET_TIMEOUT - - 哨兵连接超时时间，默认值：0.1，单位：秒。 - -#### CORS 配置 +本文档详细说明了 Dify 自托管安装时可配置的环境变量。这些配置项在 `.env` 文件中设置，您可以基于 `.env.example` 文件进行修改。 + +## 通用配置 + +这些变量影响 Dify 的基本功能和服务地址。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `CONSOLE_API_URL` | 控制台 API 的后端 URL，用于拼接授权回调地址。如果为空，则使用相同域名。 | 空 | +| `CONSOLE_WEB_URL` | 控制台 Web 的前端 URL，用于拼接前端地址和配置 CORS。如果为空，则使用相同域名。 | 空 | +| `SERVICE_API_URL` | 服务 API URL，用于在前端显示服务 API 基础 URL。如果为空，则使用相同域名。 | 空 | +| `APP_API_URL` | WebApp API 后端 URL，用于声明前端 API 的后端 URL。如果为空，则使用相同域名。 | 空 | +| `APP_WEB_URL` | WebApp URL，用于在前端显示 WebApp API 基础 URL。如果为空，则使用相同域名。 | 空 | +| `FILES_URL` | 文件预览或下载 URL 前缀，用于在前端显示文件预览或下载 URL，或作为多模型输入。URL 是签名的并具有过期时间。 | 空 | + +## 服务器配置 + +控制 Dify 服务器的基本行为。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `LOG_LEVEL` | 应用程序的日志级别。支持的值为 `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。 | `INFO` | +| `LOG_FILE` | 日志文件路径 | `/app/logs/server.log` | +| `LOG_FILE_MAX_SIZE` | 日志文件最大大小，单位为 MB | `20` | +| `LOG_FILE_BACKUP_COUNT` | 日志文件最大备份数量 | `5` | +| `LOG_DATEFORMAT` | 日志日期格式 | `%Y-%m-%d %H:%M:%S` | +| `LOG_TZ` | 日志时区 | `UTC` | +| `DEBUG` | 调试模式，默认为 false。建议在本地开发时打开此配置，以防止由猴子补丁引起的一些问题。 | `false` | +| `FLASK_DEBUG` | Flask 调试模式，开启后可以在接口处输出跟踪信息，方便调试。 | `false` | +| `SECRET_KEY` | 用于安全签署会话 cookie 和加密数据库上的敏感信息的密钥。可以使用 `openssl rand -base64 42` 生成强密钥。 | `sk-9f73s3ljTXVcMT3Blb3ljTqtsKiGHXVcMT3BlbkFJLK7U` | +| `INIT_PASSWORD` | 管理员用户初始化密码。如果不设置，创建初始管理员账户时将不会提示输入密码。密码长度不能超过 30 个字符。 | 空 | +| `DEPLOY_ENV` | 部署环境。支持的值为 `PRODUCTION`、`TESTING`。默认为 `PRODUCTION`。测试环境下，前端页面上将有明显的颜色标签，表明此环境是测试环境。 | `PRODUCTION` | +| `CHECK_UPDATE_URL` | 是否启用版本检查策略。如果设置为空，将调用 https://updates.dify.ai 进行版本检查。 | `https://updates.dify.ai` | +| `OPENAI_API_BASE` | 用于更改 OpenAI 基础地址，默认为 https://api.openai.com/v1。当在中国无法访问 OpenAI 时，可替换为国内镜像地址，或当本地模型提供 OpenAI 兼容 API 时，可以替换。 | `https://api.openai.com/v1` | +| `MIGRATION_ENABLED` | 启用后，将在应用程序启动前执行迁移，应用程序将在迁移完成后启动。 | `true` | +| `FILES_ACCESS_TIMEOUT` | 文件访问时间，指定文件被访问的时间间隔（秒）。默认值为 300 秒。 | `300` | +| `ACCESS_TOKEN_EXPIRE_MINUTES` | 访问令牌过期时间（分钟） | `60` | +| `REFRESH_TOKEN_EXPIRE_DAYS` | 刷新令牌过期时间（天） | `30` | +| `APP_MAX_ACTIVE_REQUESTS` | 应用程序的最大活动请求数，0 表示无限制，应为非负整数。 | `0` | +| `APP_MAX_EXECUTION_TIME` | 应用程序最大执行时间（秒） | `1200` | + +## 容器启动相关配置 + +这些配置仅在使用 Docker 镜像或 Docker Compose 启动时有效。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `DIFY_BIND_ADDRESS` | API 服务绑定地址，默认：0.0.0.0，即所有地址都可以访问。 | `0.0.0.0` | +| `DIFY_PORT` | API 服务绑定端口号，默认 5001。 | `5001` | +| `SERVER_WORKER_AMOUNT` | API 服务器工作进程数量，即工作线程数。公式：CPU 核心数 x 2 + 1（同步）或 1（Gevent） | `1` | +| `SERVER_WORKER_CLASS` | 默认为 gevent。如果使用 Windows，可以切换为 sync 或 solo。 | `gevent` | +| `SERVER_WORKER_CONNECTIONS` | 默认工作连接数，默认为 10。 | `10` | +| `CELERY_WORKER_CLASS` | 与 SERVER_WORKER_CLASS 类似。如果使用 Windows，可以切换为 sync 或 solo。 | 空 | +| `GUNICORN_TIMEOUT` | 请求处理超时时间。默认为 200，建议设为 360 以支持更长的 SSE 连接时间。 | `360` | +| `CELERY_WORKER_AMOUNT` | Celery 工作线程数。默认为 1，可根据需要设置。 | 空 | +| `CELERY_AUTO_SCALE` | 是否启用 Celery 工作线程自动缩放。自动缩放对于 CPU 密集型任务很有用，可以根据工作负载动态分配和释放。默认为 false（即禁用自动缩放）。 | `false` | +| `CELERY_MAX_WORKERS` | Celery 自动缩放的最大工作线程数。这是可选的，仅当启用自动缩放时使用。 | 空 | +| `CELERY_MIN_WORKERS` | Celery 自动缩放的最小工作线程数。这是可选的，仅当启用自动缩放时使用。 | 空 | +| `API_TOOL_DEFAULT_CONNECT_TIMEOUT` | API 工具默认连接超时时间 | `10` | +| `API_TOOL_DEFAULT_READ_TIMEOUT` | API 工具默认读取超时时间 | `60` | + +## 数据源配置 + +为不同的网站爬虫引擎配置。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `ENABLE_WEBSITE_JINAREADER` | 启用 Jina Reader 网站抓取 | `true` | +| `ENABLE_WEBSITE_FIRECRAWL` | 启用 Firecrawl 网站抓取 | `true` | +| `ENABLE_WEBSITE_WATERCRAWL` | 启用 Watercrawl 网站抓取 | `true` | + +## 数据库配置 + +Dify 使用 PostgreSQL 数据库。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `DB_USERNAME` | 数据库用户名 | `postgres` | +| `DB_PASSWORD` | 数据库密码 | `difyai123456` | +| `DB_HOST` | 数据库主机 | `db` | +| `DB_PORT` | 数据库端口 | `5432` | +| `DB_DATABASE` | 数据库名称 | `dify` | +| `SQLALCHEMY_POOL_SIZE` | 数据库连接池大小。默认为 30 个连接，可以适当增加。 | `30` | +| `SQLALCHEMY_POOL_RECYCLE` | 数据库连接池回收时间，默认为 3600 秒。 | `3600` | +| `SQLALCHEMY_ECHO` | 是否打印 SQL，默认为 false。 | `false` | +| `POSTGRES_MAX_CONNECTIONS` | 数据库最大连接数，默认为 100 | `100` | +| `POSTGRES_SHARED_BUFFERS` | PostgreSQL 共享缓冲区大小，默认为 128MB，建议值：可用内存的 25% | `128MB` | +| `POSTGRES_WORK_MEM` | 每个数据库工作进程的工作内存，默认为 4MB | `4MB` | +| `POSTGRES_MAINTENANCE_WORK_MEM` | 维护活动的保留内存，默认为 64MB | `64MB` | +| `POSTGRES_EFFECTIVE_CACHE_SIZE` | 规划器对有效缓存大小的假设，默认为 4096MB | `4096MB` | + +## Redis 配置 + +Redis 用于缓存和会话期间的发布/订阅。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `REDIS_HOST` | Redis 主机 | `redis` | +| `REDIS_PORT` | Redis 端口 | `6379` | +| `REDIS_USERNAME` | Redis 用户名 | 空 | +| `REDIS_PASSWORD` | Redis 密码 | `difyai123456` | +| `REDIS_USE_SSL` | 是否使用 SSL 连接 Redis | `false` | +| `REDIS_DB` | Redis 数据库编号 | `0` | +| `REDIS_USE_SENTINEL` | 是否使用 Redis Sentinel 模式 | `false` | +| `REDIS_SENTINELS` | Redis Sentinel 节点列表，格式：`:,:` | 空 | +| `REDIS_SENTINEL_SERVICE_NAME` | Redis Sentinel 服务名称 | 空 | +| `REDIS_SENTINEL_USERNAME` | Redis Sentinel 用户名 | 空 | +| `REDIS_SENTINEL_PASSWORD` | Redis Sentinel 密码 | 空 | +| `REDIS_SENTINEL_SOCKET_TIMEOUT` | Redis Sentinel 套接字超时 | `0.1` | +| `REDIS_USE_CLUSTERS` | 是否使用 Redis 集群 | `false` | +| `REDIS_CLUSTERS` | Redis 集群节点列表 | 空 | +| `REDIS_CLUSTERS_PASSWORD` | Redis 集群密码 | 空 | + +## Celery 配置 + +用于任务队列和异步处理。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `CELERY_BROKER_URL` | Celery 代理 URL，使用 Redis 作为代理 | `redis://:difyai123456@redis:6379/1` | +| `BROKER_USE_SSL` | 是否使用 SSL 连接代理 | `false` | +| `CELERY_USE_SENTINEL` | 是否使用 Redis Sentinel | `false` | +| `CELERY_SENTINEL_MASTER_NAME` | Celery Sentinel 主节点名称 | 空 | +| `CELERY_SENTINEL_SOCKET_TIMEOUT` | Celery Sentinel 套接字超时 | `0.1` | + +## CORS 配置 用于设置前端跨域访问策略。 -* CONSOLE_CORS_ALLOW_ORIGINS - - 控制台 CORS 跨域策略，默认为 `*`，即所有域名均可访问。 -* WEB_API_CORS_ALLOW_ORIGINS - - WebAPP CORS 跨域策略，默认为 `*`，即所有域名均可访问。 - -详细配置可参考：[跨域 / 身份相关指南](/zh-hans/learn-more/faq/install-faq#3-安装时后无法登录，登录成功，但后续接口均提示-401？) - -#### 文件存储配置 - -用于存储知识库上传的文件、团队 / 租户的加密密钥等等文件。 - -* STORAGE_TYPE - - 存储设施类型 - - * local（默认） - - 本地文件存储，若选择此项则需要设置下方 `STORAGE_LOCAL_PATH` 配置。 - * s3 - - S3 对象存储，若选择此项则需要设置下方 S3_ 开头的配置。 - * azure-blob - - Azure Blob 存储，若选择此项则需要设置下方 AZURE_BLOB_ 开头的配置。 - * huawei-obs - - Huawei OBS 存储，若选择此项则需要设置下方 HUAWEI_OBS_ 开头的配置。 - * volcengine-tos - - Volcengine TOS 存储，若选择此项则需要设置下方 VOLCENGINE_TOS_ 开头的配置。 -* STORAGE_LOCAL_PATH - - 默认为 storage，即存储在当前目录的 storage 目录下。若使用 Docker 或 Docker-compose 进行部署，请务必将两个容器中 `/app/api/storage` 目录挂载到同一个本机目录，否则可能会出现文件找不到的报错。 -* S3_ENDPOINT：S3 端点地址 -* S3_BUCKET_NAME：S3 桶名称 -* S3_ACCESS_KEY：S3 Access Key -* S3_SECRET_KEY：S3 Secret Key -* S3_REGION：S3 地域信息，如：us-east-1 -* AZURE_BLOB_ACCOUNT_NAME: your-account-name 如 'difyai' -* AZURE_BLOB_ACCOUNT_KEY: your-account-key 如 'difyai' -* AZURE_BLOB_CONTAINER_NAME: your-container-name 如 'difyai-container' -* AZURE_BLOB_ACCOUNT_URL: 'https://\.blob.core.windows.net' -* ALIYUN_OSS_BUCKET_NAME: your-bucket-name 如 'difyai' -* ALIYUN_OSS_ACCESS_KEY: your-access-key 如 'difyai' -* ALIYUN_OSS_SECRET_KEY: your-secret-key 如 'difyai' -* ALIYUN_OSS_ENDPOINT: https://oss-ap-southeast-1-internal.aliyuncs.com # 参考[文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints) -* ALIYUN_OSS_REGION: ap-southeast-1 # 参考[文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints) -* ALIYUN_OSS_AUTH_VERSION: v4 -* ALIYUN_OSS_PATH: your-path # 路径不要使用斜线 "/" 开头，阿里云 OSS 不支持。参考[文档](https://api.aliyun.com/troubleshoot?q=0016-00000005) -* HUAWEI_OBS_BUCKET_NAME: your-bucket-name 如 'difyai' -* HUAWEI_OBS_SECRET_KEY: your-secret-key 如 'difyai' -* HUAWEI_OBS_ACCESS_KEY: your-access-key 如 'difyai' -* HUAWEI_OBS_SERVER: your-server-url # 参考[文档](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0500.html)。 -* VOLCENGINE_TOS_BUCKET_NAME: your-bucket-name 如 'difyai'。 -* VOLCENGINE_TOS_SECRET_KEY: your-secret-key 如 'difyai'。 -* VOLCENGINE_TOS_ACCESS_KEY: your-access-key 如 'difyai'。 -* VOLCENGINE_TOS_REGION: your-region 如 'cn-guangzhou' # 参考[文档]( https://www.volcengine.com/docs/6349/107356)。 -* VOLCENGINE_TOS_ENDPOINT: your-endpoint 如 'tos-cn-guangzhou.volces.com' # 参考[文档](https://www.volcengine.com/docs/6349/107356)。 - -#### 向量数据库配置 - -* VECTOR_STORE - - **可使用的枚举类型包括：** - - * `weaviate` - * `qdrant` - * `milvus` - * `zilliz` 与 `milvus` 一致 - * `myscale` - * `pinecone` (暂未开放) - * `tidb_vector` - * `analyticdb` - * `couchbase` -* WEAVIATE_ENDPOINT - - Weaviate 端点地址，如：`http://weaviate:8080`。 -* WEAVIATE_API_KEY - - 连接 Weaviate 使用的 api-key 凭据。 -* WEAVIATE_BATCH_SIZE - - Weaviate 批量创建索引 Object 的数量，默认 100。可参考此[文档](https://weaviate.io/developers/weaviate/manage-data/import#how-to-set-batch-parameters)。 -* WEAVIATE_GRPC_ENABLED - - 是否使用 gRPC 方式与 Weaviate 进行交互，开启后性能会大大增加，本地可能无法使用，默认为 true。 -* QDRANT_URL - - Qdrant 端点地址，如：`https://your-qdrant-cluster-url.qdrant.tech/` -* QDRANT_API_KEY - - 连接 Qdrant 使用的 api-key 凭据。 -* PINECONE_API_KEY - - 连接 Pinecone 使用的 api-key 凭据。 -* PINECONE_ENVIRONMENT - - Pinecone 所在的额环境，如：`us-east4-gcp` -* MILVUS_URI - - Milvus 的 URI 配置。例如：`http://host.docker.internal:19530`。对于 [Zilliz Cloud](https://docs.zilliz.com.cn/docs/free-trials)，请将 URI 和 TOKEN 分别设置为 Public Endpoint 和 API Key。 -* MILVUS_TOKEN - - Milvus TOKEN 配置，默认为空。 -* MILVUS_USER - - Milvus 用户名配置，默认为空。 -* MILVUS_PASSWORD - - Milvus 密码配置，默认为空。 -* MYSCALE_HOST - - MyScale host 配置。 -* MYSCALE_PORT - - MyScale port 配置。 -* MYSCALE_USER - - MyScale 用户名配置，默认为 `default`。 -* MYSCALE_PASSWORD - - MyScale 密码配置，默认为空。 -* MYSCALE_DATABASE - - MyScale 数据库配置，默认为 `default`。 -* MYSCALE_FTS_PARAMS - - MyScale 全文搜索配置，如需多语言支持，请参考 [MyScale 文档](https://myscale.com/docs/en/text-search/#understanding-fts-index-parameters)，默认为空（仅支持英语）。 - -* TIDB_VECTOR_HOST - - TiDB Vector host 配置，如：`xxx.eu-central-1.xxx.tidbcloud.com` -* TIDB_VECTOR_PORT - - TiDB Vector 端口号配置，如：`4000` -* TIDB_VECTOR_USER - - TiDB Vector 用户配置，如：`xxxxxx.root` -* TIDB_VECTOR_PASSWORD - - TiDB Vector 密码配置 -* TIDB_VECTOR_DATABASE - - TiDB Vector 数据库配置，如：`dify` - -* ANALYTICDB_KEY_ID - - 用于阿里云 OpenAPI 认证的访问密钥 ID。请阅读 [Analyticdb 文档](https://help.aliyun.com/zh/analyticdb/analyticdb-for-postgresql/support/create-an-accesskey-pair) 来创建你的 AccessKey。 - -* ANALYTICDB_KEY_SECRET - - 用于阿里云 OpenAPI 认证的访问密钥秘密。 - -* ANALYTICDB_INSTANCE_ID - - 你的 AnalyticDB 实例的唯一标识符，例如 `gp-xxxxxx`。请阅读 [Analyticdb 文档](https://help.aliyun.com/zh/analyticdb/analyticdb-for-postgresql/getting-started/create-an-instance-1) 来创建你的实例。 - -* ANALYTICDB_REGION_ID - - AnalyticDB 实例所在区域的标识符，例如 `cn-hangzhou`。 - -* ANALYTICDB_ACCOUNT - - 用于连接 AnalyticDB 实例的账户名称。请阅读 [Analyticdb 文档](https://help.aliyun.com/zh/analyticdb/analyticdb-for-postgresql/getting-started/createa-a-privileged-account) 来创建账户。 - -* ANALYTICDB_PASSWORD - - 用于连接 AnalyticDB 实例的账户密码。 - -* ANALYTICDB_NAMESPACE - - 在 AnalyticDB 实例内要操作的命名空间 (schema)，例如 `dify`。如果此命名空间不存在，将自动创建。 - -* ANALYTICDB_NAMESPACE_PASSWORD - - 命名空间 (schema) 的密码。如果命名空间不存在，将使用此密码进行创建。 - -- COUCHBASE_CONNECTION_STRING - - Couchbase 集群的连接 string 字符串。 - -- COUCHBASE_USER - - 数据库用户名。 - -- COUCHBASE_PASSWORD - - 数据库密码。 - -- COUCHBASE_BUCKET_NAME - - Bucket 名称。 - -- COUCHBASE_SCOPE_NAME - - Scope 名称。 - -#### 知识库配置 - -* UPLOAD_FILE_SIZE_LIMIT - - 上传文件大小限制，默认 15M。 -* UPLOAD_FILE_BATCH_LIMIT - - 每次上传文件数上限，默认 5 个。 -* ETL_TYPE - - **可使用的枚举类型包括：** - - * dify - - Dify 自研文件 Extract 方案 - * Unstructured - - Unstructured.io 文件 Extract 方案 -* UNSTRUCTURED_API_URL - - Unstructured API 路径，当 ETL_TYPE 为 Unstructured 需要配置。 - - 如：`http://unstructured:8000/general/v0/general` - -#### 多模态模型配置 - -* MULTIMODAL_SEND_IMAGE_FORMAT - - 多模态模型输入时，发送图片的格式，默认为 `base64`，可选 `url`。 `url` 模式下，调用的延迟会比 `base64` 模式下低，一般建议使用兼容更好的 `base64` 模式。 若配置为 `url`，则需要将 `FILES_URL` 配置为外部可访问的地址，以便多模态模型可以访问到图片。 -* UPLOAD_IMAGE_FILE_SIZE_LIMIT - - 上传图片文件大小限制，默认 10M。 - -#### Sentry 配置 - -用于应用监控和错误日志跟踪。 - -* SENTRY_DSN - - Sentry DSN 地址，默认为空，为空时则所有监控信息均不上报 Sentry。 -* SENTRY_TRACES_SAMPLE_RATE - - Sentry events 的上报比例，若为 0.01，则为 1%。 -* SENTRY_PROFILES_SAMPLE_RATE - - Sentry profiles 的上报比例，若为 0.01，则为 1%。 - -#### Notion 集成配置 - -Notion 集成配置，变量可通过申请 Notion integration 获取：[https://www.notion.so/my-integrations](https://www.notion.so/my-integrations) - -* NOTION_CLIENT_ID -* NOTION_CLIENT_SECRET - -#### 邮件相关配置 - -* MAIL_TYPE - * resend - * MAIL_DEFAULT_SEND_FROM\ - 发件人的电子邮件名称，例如：no-reply [no-reply@dify.ai](mailto:no-reply@dify.ai)，非必需。 - * RESEND_API_KEY\ - 用于 Resend 邮件提供程序的 API 密钥，可以从 API 密钥获取。 - * smtp - * SMTP_SERVER\ - SMTP 服务器地址 - * SMTP_PORT\ - SMTP 服务器端口号 - * SMTP_USERNAME\ - SMTP 用户名 - * SMTP_PASSWORD\ - SMTP 密码 - * SMTP_USE_TLS\ - 是否使用 TLS，默认为 false - * MAIL_DEFAULT_SEND_FROM\ - 发件人的电子邮件名称，例如：no-reply [no-reply@dify.ai](mailto:no-reply@dify.ai)，非必需。 - -#### 模型供应商 & 工具 位置配置 - -用于指定应用中可以使用的模型供应商和工具。你可以自定义哪些工具和模型供应商可用，以及它们在应用界面中的顺序和包含 / 排除情况。 - -详见可用的 [工具](https://github.com/langgenius/dify/blob/main/api/core/tools/provider/_position.yaml) 和 [模型供应商](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/model_providers/_position.yaml)。 - -* POSITION_TOOL_PINS - - 将列出的工具固定在列表顶部，确保它们在界面中置顶出现。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_TOOL_PINS=bing,google` - -* POSITION_TOOL_INCLUDES - - 指定要在应用中包含的工具。只有此处列出的工具才可用。如果未设置，则除非在 POSITION_TOOL_EXCLUDES 中指定，否则所有工具都会包含在内。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_TOOL_INCLUDES=bing,google` - -* POSITION_TOOL_EXCLUDES - - 排除在应用中显示或使用的特定工具。此处列出的工具将从可用选项中省略，除非它们被固定。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_TOOL_EXCLUDES=yahoo,wolframalpha` - -* POSITION_PROVIDER_PINS - - 将列出的模型供应商固定在列表顶部，确保它们在界面中置顶出现。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_PROVIDER_PINS=openai,openllm` - -* POSITION_PROVIDER_INCLUDES - - 指定要在应用中包含的模型供应商。只有此处列出的供应商才可用。如果未设置，则除非在 POSITION_PROVIDER_EXCLUDES 中指定，否则所有供应商都会包含在内。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_PROVIDER_INCLUDES=cohere,upstage` - -* POSITION_PROVIDER_EXCLUDES - - 排除在应用中显示特定模型供应商。此处列出的供应商将从可用选项中移除，除非它们被置顶。（使用逗号分隔的值，**中间不留空格**。） - - 示例: `POSITION_PROVIDER_EXCLUDES=openrouter,ollama` - -#### 其他 - -* INVITE_EXPIRY_HOURS：成员邀请链接有效时间（小时），默认：72。 -* HTTP_REQUEST_NODE_MAX_TEXT_SIZE：workflow 工作流中 HTTP 请求节点的最大文本大小，默认 1MB。 -* HTTP_REQUEST_NODE_MAX_BINARY_SIZE：workflow 工作流中 HTTP 请求节点的最大二进制大小，默认 10MB。 - -*** - -### Web 前端 - -#### SENTRY_DSN - -Sentry DSN 地址，默认为空，为空时则所有监控信息均不上报 Sentry。 - -## 已废弃 - -#### CONSOLE_URL - -> ⚠️ 修改于 0.3.8，于 0.4.9 废弃，替代为：`CONSOLE_API_URL` 和 `CONSOLE_WEB_URL`。 - -控制台 URL，用于拼接授权回调、控制台前端地址，以及 CORS 配置使用，传空则为同域。范例：`https://console.dify.ai`。 - -#### API_URL - -> ⚠️ 修改于 0.3.8，于 0.4.9 废弃，替代为 `SERVICE_API_URL`。 - -API Url，用于给前端展示 Service API Base Url，传空则为同域。范例：`https://api.dify.ai` - -#### APP_URL - -> ⚠️ 修改于 0.3.8，于 0.4.9 废弃，替代为 `APP_API_URL` 和 `APP_WEB_URL`。 - -WebApp Url，用于显示文件预览或下载 URL 到前端作为多模型输入，传空则为同域。范例：`https://udify.app/` - -#### Session 配置 - -> ⚠️ 该配置从 0.3.24 版本起废弃。 - -仅 API 服务使用，用于验证接口身份。 - -* SESSION_TYPE： Session 组件类型 - * redis（默认） - - 选择此项，则需要设置下方 SESSION_REDIS_ 开头的环境变量。 - * sqlalchemy - - 选择此项，则使用当前数据库连接，并使用 sessions 表进行读写 session 记录。 -* SESSION_REDIS_HOST：Redis host -* SESSION_REDIS_PORT：Redis port，默认 6379 -* SESSION_REDIS_DB：Redis Database，默认为 0，请和 Redis、Celery Broker 分开用不同 Database。 -* SESSION_REDIS_USERNAME：Redis 用户名，默认为空 -* SESSION_REDIS_PASSWORD：Redis 密码，默认为空，强烈建议设置密码。 -* SESSION_REDIS_USE_SSL：是否使用 SSL 协议进行连接，默认 false - -#### Cookie 策略配置 - -> ⚠️ 该配置从 0.3.24 版本起废弃。 - -用于设置身份校验的 Session Cookie 浏览器策略。 - -* COOKIE_HTTPONLY - - Cookie HttpOnly 配置，默认为 true。 -* COOKIE_SAMESITE - - Cookie SameSite 配置，默认为 Lax。 -* COOKIE_SECURE - - Cookie Secure 配置，默认为 false。 - -### 文档分段长度配置 - -#### MAXIMUM_CHUNK_TOKEN_LENGTH - -文档分段长度配置，用于控制处理长文本时的分段大小。默认值：500。最大值：4000。 - -**较大分段** -- 可在单个分段内保留更多上下文，适合需要处理复杂或上下文相关任务的场景。 -- 分段数量减少，从而降低处理时间和存储需求。 - -**较小分段** -- 提供更高的粒度，适合精确提取或总结文本内容。 -- 减少超出模型 token 限制的风险，更适配限制严格的模型。 - -**配置建议** -- 较大分段：适合上下文依赖性强的任务，例如情感分析或长文档总结。 -- 较小分段：适合精细分析场景，例如关键词提取或段落级内容处理。 +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `WEB_API_CORS_ALLOW_ORIGINS` | Web API 跨域请求允许的来源 | `*` | +| `CONSOLE_CORS_ALLOW_ORIGINS` | 控制台 API 跨域请求允许的来源 | `*` | + +## 文件存储配置 + +Dify 支持多种文件存储方式。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `STORAGE_TYPE` | 存储用户文件的存储类型 | `opendal` | +| `OPENDAL_SCHEME` | OpenDAL 存储的方案名称 | `fs` | +| `OPENDAL_FS_ROOT` | OpenDAL 本地文件系统根目录 | `storage` | + +此外，Dify 还支持配置 S3、Azure Blob、Google Storage、阿里云 OSS、腾讯 COS、Oracle Storage、华为 OBS、火山引擎 TOS、百度 OBS 和 Supabase Storage 等多种云存储服务。 + +## 向量数据库配置 + +Dify 支持多种向量数据库。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `VECTOR_STORE` | 要使用的向量存储类型 | `weaviate` | + +支持的向量数据库包括：`weaviate`、`qdrant`、`milvus`、`myscale`、`relyt`、`pgvector`、`pgvecto-rs`、`chroma`、`opensearch`、`tidb_vector`、`oracle`、`tencent`、`elasticsearch`、`elasticsearch-ja`、`analyticdb`、`couchbase`、`vikingdb`、`oceanbase`、`opengauss`、`tablestore` 等。 + +每种向量数据库都有其特定的配置变量，例如： + +### Weaviate 配置 +``` +WEAVIATE_ENDPOINT=http://weaviate:8080 +WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih +``` + +### Qdrant 配置 +``` +QDRANT_URL=http://qdrant:6333 +QDRANT_API_KEY=difyai123456 +QDRANT_CLIENT_TIMEOUT=20 +QDRANT_GRPC_ENABLED=false +QDRANT_GRPC_PORT=6334 +``` + +## 知识库配置 + +控制文件上传和处理。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `UPLOAD_FILE_SIZE_LIMIT` | 上传文件大小限制，默认 15M | `15` | +| `UPLOAD_FILE_BATCH_LIMIT` | 一次可以上传的最大文件数，默认 5 | `5` | +| `ETL_TYPE` | ETL 类型，支持：`dify`、`Unstructured` | `dify` | +| `UNSTRUCTURED_API_URL` | Unstructured API 路径 | 空 | +| `UNSTRUCTURED_API_KEY` | Unstructured API 密钥 | 空 | +| `SCARF_NO_ANALYTICS` | 不进行数据分析 | `true` | + +## 模型配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `PROMPT_GENERATION_MAX_TOKENS` | 提示生成允许的最大令牌数 | `512` | +| `CODE_GENERATION_MAX_TOKENS` | 代码生成允许的最大令牌数 | `1024` | +| `PLUGIN_BASED_TOKEN_COUNTING_ENABLED` | 启用或禁用基于插件的令牌计数 | `false` | + +## 多模态配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `MULTIMODAL_SEND_FORMAT` | 多模态模型输入时发送图像/视频/音频/文档的格式，默认为 base64，可选 url | `base64` | +| `UPLOAD_IMAGE_FILE_SIZE_LIMIT` | 上传图像文件大小限制，默认 10M | `10` | +| `UPLOAD_VIDEO_FILE_SIZE_LIMIT` | 上传视频文件大小限制，默认 100M | `100` | +| `UPLOAD_AUDIO_FILE_SIZE_LIMIT` | 上传音频文件大小限制，默认 50M | `50` | + +## Sentry 配置 + +用于应用程序监控和错误日志跟踪。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `SENTRY_DSN` | Sentry DSN 地址 | 空 | +| `API_SENTRY_DSN` | API 服务 Sentry DSN 地址 | 空 | +| `API_SENTRY_TRACES_SAMPLE_RATE` | API 服务 Sentry 事件的报告比例 | `1.0` | +| `API_SENTRY_PROFILES_SAMPLE_RATE` | API 服务 Sentry 配置文件的报告比例 | `1.0` | +| `WEB_SENTRY_DSN` | Web 服务 Sentry DSN 地址 | 空 | + +## Notion 集成配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `NOTION_INTEGRATION_TYPE` | 配置为 "public" 或 "internal" | `public` | +| `NOTION_CLIENT_SECRET` | Notion OAuth 客户端密钥 | 空 | +| `NOTION_CLIENT_ID` | Notion OAuth 客户端 ID | 空 | +| `NOTION_INTERNAL_SECRET` | Notion 内部集成密钥 | 空 | + +## 邮件相关配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `MAIL_TYPE` | 邮件类型，支持：resend, smtp | `resend` | +| `MAIL_DEFAULT_SEND_FROM` | 默认发送邮件地址 | 空 | +| `RESEND_API_URL` | Resend 邮件提供商的 API-URL | `https://api.resend.com` | +| `RESEND_API_KEY` | Resend 邮件提供商的 API-Key | `your-resend-api-key` | +| `SMTP_SERVER` | SMTP 服务器地址 | 空 | +| `SMTP_PORT` | SMTP 端口 | `465` | +| `SMTP_USERNAME` | SMTP 用户名 | 空 | +| `SMTP_PASSWORD` | SMTP 密码 | 空 | +| `SMTP_USE_TLS` | 是否使用 TLS | `true` | +| `SMTP_OPPORTUNISTIC_TLS` | 是否使用投机式 TLS | `false` | + +## 其他配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `INDEXING_MAX_SEGMENTATION_TOKENS_LENGTH` | 索引的最大分段令牌长度 | `4000` | +| `INVITE_EXPIRY_HOURS` | 成员邀请链接有效时间（小时） | `72` | +| `RESET_PASSWORD_TOKEN_EXPIRY_MINUTES` | 重置密码令牌有效时间（分钟） | `5` | +| `CODE_EXECUTION_ENDPOINT` | 沙盒服务端点 | `http://sandbox:8194` | +| `CODE_EXECUTION_API_KEY` | 代码执行 API 密钥 | `dify-sandbox` | +| `CODE_MAX_NUMBER` | 代码最大数字 | `9223372036854775807` | +| `CODE_MIN_NUMBER` | 代码最小数字 | `-9223372036854775808` | +| `CODE_MAX_DEPTH` | 代码最大深度 | `5` | +| `CODE_MAX_PRECISION` | 代码最大精度 | `20` | +| `CODE_MAX_STRING_LENGTH` | 代码最大字符串长度 | `80000` | +| `CODE_MAX_STRING_ARRAY_LENGTH` | 代码最大字符串数组长度 | `30` | +| `CODE_MAX_OBJECT_ARRAY_LENGTH` | 代码最大对象数组长度 | `30` | +| `CODE_MAX_NUMBER_ARRAY_LENGTH` | 代码最大数字数组长度 | `1000` | +| `CODE_EXECUTION_CONNECT_TIMEOUT` | 代码执行连接超时时间 | `10` | +| `CODE_EXECUTION_READ_TIMEOUT` | 代码执行读取超时时间 | `60` | +| `CODE_EXECUTION_WRITE_TIMEOUT` | 代码执行写入超时时间 | `10` | +| `TEMPLATE_TRANSFORM_MAX_LENGTH` | 模板转换最大长度 | `80000` | + +## 工作流配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `WORKFLOW_MAX_EXECUTION_STEPS` | 工作流最大执行步骤数 | `500` | +| `WORKFLOW_MAX_EXECUTION_TIME` | 工作流最大执行时间（秒） | `1200` | +| `WORKFLOW_CALL_MAX_DEPTH` | 工作流调用最大深度 | `5` | +| `MAX_VARIABLE_SIZE` | 最大变量大小 | `204800` | +| `WORKFLOW_PARALLEL_DEPTH_LIMIT` | 工作流并行深度限制 | `3` | +| `WORKFLOW_FILE_UPLOAD_LIMIT` | 工作流文件上传限制 | `10` | +| `WORKFLOW_NODE_EXECUTION_STORAGE` | 工作流存储配置，选项：rdbms, hybrid | `rdbms` | +| `HTTP_REQUEST_NODE_MAX_BINARY_SIZE` | 工作流中 HTTP 请求节点的最大二进制大小 | `10485760` | +| `HTTP_REQUEST_NODE_MAX_TEXT_SIZE` | 工作流中 HTTP 请求节点的最大文本大小 | `1048576` | +| `HTTP_REQUEST_NODE_SSL_VERIFY` | 工作流中 HTTP 请求节点的 SSL 验证 | `True` | +| `SSRF_PROXY_HTTP_URL` | SSRF 代理服务器 HTTP URL | `http://ssrf_proxy:3128` | +| `SSRF_PROXY_HTTPS_URL` | SSRF 代理服务器 HTTPS URL | `http://ssrf_proxy:3128` | +| `LOOP_NODE_MAX_COUNT` | 工作流中最大循环次数 | `100` | +| `MAX_TOOLS_NUM` | 代理中可以使用的最大工具数量 | `10` | +| `MAX_PARALLEL_LIMIT` | 工作流中最大并行分支数 | `10` | +| `MAX_ITERATIONS_NUM` | 代理设置的最大迭代次数 | `5` | +| `MAX_SUBMIT_COUNT` | 并行节点执行的最大提交线程数 | `100` | +| `TOP_K_MAX_VALUE` | RAG 的最大 top-k 值 | `10` | + +## Web 服务环境变量 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `TEXT_GENERATION_TIMEOUT_MS` | 文本生成超时时间（毫秒） | `60000` | + +## Nginx 反向代理配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `NGINX_SERVER_NAME` | Nginx 服务器名称 | `_` | +| `NGINX_HTTPS_ENABLED` | 是否启用 HTTPS | `false` | +| `NGINX_PORT` | HTTP 端口 | `80` | +| `NGINX_SSL_PORT` | SSL 端口 | `443` | +| `NGINX_SSL_CERT_FILENAME` | SSL 证书文件名 | `dify.crt` | +| `NGINX_SSL_CERT_KEY_FILENAME` | SSL 证书密钥文件名 | `dify.key` | +| `NGINX_SSL_PROTOCOLS` | SSL 协议 | `TLSv1.1 TLSv1.2 TLSv1.3` | +| `NGINX_WORKER_PROCESSES` | Nginx 工作进程数 | `auto` | +| `NGINX_CLIENT_MAX_BODY_SIZE` | Nginx 客户端最大主体大小 | `15M` | +| `NGINX_KEEPALIVE_TIMEOUT` | Nginx keepalive 超时 | `65` | +| `NGINX_PROXY_READ_TIMEOUT` | Nginx 代理读取超时 | `3600s` | +| `NGINX_PROXY_SEND_TIMEOUT` | Nginx 代理发送超时 | `3600s` | +| `NGINX_ENABLE_CERTBOT_CHALLENGE` | 是否接受 /.well-known/acme-challenge/ 的请求 | `false` | +| `EXPOSE_NGINX_PORT` | 暴露的 Nginx 端口 | `80` | +| `EXPOSE_NGINX_SSL_PORT` | 暴露的 Nginx SSL 端口 | `443` | + +## Certbot 配置 + +用于自动管理 SSL 证书。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `CERTBOT_EMAIL` | 电子邮件地址（从 Let's Encrypt 获取证书所必需） | `your_email@example.com` | +| `CERTBOT_DOMAIN` | 域名 | `your_domain.com` | +| `CERTBOT_OPTIONS` | certbot 命令选项 | 空 | + +## 插件守护程序配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `DB_PLUGIN_DATABASE` | 插件数据库名称 | `dify_plugin` | +| `EXPOSE_PLUGIN_DAEMON_PORT` | 暴露的插件守护程序端口 | `5002` | +| `PLUGIN_DAEMON_PORT` | 插件守护程序端口 | `5002` | +| `PLUGIN_DAEMON_KEY` | 插件守护程序密钥 | `lYkiYYT6owG+71oLerGzA7GXCgOT++6ovaezWAjpCjf+Sjc3ZtU+qUEi` | +| `PLUGIN_DAEMON_URL` | 插件守护程序 URL | `http://plugin_daemon:5002` | +| `PLUGIN_MAX_PACKAGE_SIZE` | 插件最大包大小 | `52428800` | +| `PLUGIN_PPROF_ENABLED` | 是否启用插件性能分析 | `false` | +| `PLUGIN_DEBUGGING_HOST` | 插件调试主机 | `0.0.0.0` | +| `PLUGIN_DEBUGGING_PORT` | 插件调试端口 | `5003` | +| `EXPOSE_PLUGIN_DEBUGGING_HOST` | 暴露的插件调试主机 | `localhost` | +| `EXPOSE_PLUGIN_DEBUGGING_PORT` | 暴露的插件调试端口 | `5003` | +| `PLUGIN_DIFY_INNER_API_KEY` | 插件 Dify 内部 API 密钥 | `QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1` | +| `PLUGIN_DIFY_INNER_API_URL` | 插件 Dify 内部 API URL | `http://api:5001` | +| `ENDPOINT_URL_TEMPLATE` | 端点 URL 模板 | `http://localhost/e/{hook_id}` | +| `MARKETPLACE_ENABLED` | 是否启用市场 | `true` | +| `MARKETPLACE_API_URL` | 市场 API URL | `https://marketplace.dify.ai` | +| `FORCE_VERIFYING_SIGNATURE` | 是否强制验证签名 | `true` | +| `PLUGIN_PYTHON_ENV_INIT_TIMEOUT` | 插件 Python 环境初始化超时 | `120` | +| `PLUGIN_MAX_EXECUTION_TIMEOUT` | 插件最大执行超时 | `600` | +| `PIP_MIRROR_URL` | PIP 镜像 URL | 空 | + +## SSRF 代理配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `SSRF_HTTP_PORT` | SSRF HTTP 端口 | `3128` | +| `SSRF_COREDUMP_DIR` | SSRF 核心转储目录 | `/var/spool/squid` | +| `SSRF_REVERSE_PROXY_PORT` | SSRF 反向代理端口 | `8194` | +| `SSRF_SANDBOX_HOST` | SSRF 沙盒主机 | `sandbox` | +| `SSRF_DEFAULT_TIME_OUT` | SSRF 默认超时 | `5` | +| `SSRF_DEFAULT_CONNECT_TIME_OUT` | SSRF 默认连接超时 | `5` | +| `SSRF_DEFAULT_READ_TIME_OUT` | SSRF 默认读取超时 | `5` | +| `SSRF_DEFAULT_WRITE_TIME_OUT` | SSRF 默认写入超时 | `5` | + +## 模型提供商和工具位置配置 + +用于指定应用程序中可以使用的模型提供商和工具。 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `POSITION_TOOL_PINS` | 固定工具，用逗号分隔值，不要在项目之间加空格 | 空 | +| `POSITION_TOOL_INCLUDES` | 包含工具 | 空 | +| `POSITION_TOOL_EXCLUDES` | 排除工具 | 空 | +| `POSITION_PROVIDER_PINS` | 固定模型提供商 | 空 | +| `POSITION_PROVIDER_INCLUDES` | 包含模型提供商 | 空 | +| `POSITION_PROVIDER_EXCLUDES` | 排除模型提供商 | 空 | + +## OTLP 收集器配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `ENABLE_OTEL` | 是否启用 OTEL | `false` | +| `OTLP_BASE_ENDPOINT` | OTLP 基础端点 | `http://localhost:4318` | +| `OTLP_API_KEY` | OTLP API 密钥 | 空 | +| `OTEL_EXPORTER_TYPE` | OTEL 导出器类型 | `otlp` | +| `OTEL_SAMPLING_RATE` | OTEL 采样率 | `0.1` | +| `OTEL_BATCH_EXPORT_SCHEDULE_DELAY` | OTEL 批量导出调度延迟 | `5000` | +| `OTEL_MAX_QUEUE_SIZE` | OTEL 最大队列大小 | `2048` | +| `OTEL_MAX_EXPORT_BATCH_SIZE` | OTEL 最大导出批大小 | `512` | +| `OTEL_METRIC_EXPORT_INTERVAL` | OTEL 指标导出间隔 | `60000` | +| `OTEL_BATCH_EXPORT_TIMEOUT` | OTEL 批量导出超时 | `10000` | +| `OTEL_METRIC_EXPORT_TIMEOUT` | OTEL 指标导出超时 | `30000` | + +## 额外安全配置 + +| 变量名 | 描述 | 默认值 | +|-------|------|--------| +| `CSP_WHITELIST` | 内容安全策略白名单 | 空 | +| `ALLOW_EMBED` | 防止点击劫持 | `false` | diff --git a/zh-hans/getting-started/readme/features-and-specifications.mdx b/zh-hans/getting-started/readme/features-and-specifications.mdx index d0a2e0b9..3dc621db 100644 --- a/zh-hans/getting-started/readme/features-and-specifications.mdx +++ b/zh-hans/getting-started/readme/features-and-specifications.mdx @@ -23,7 +23,7 @@ description: 对于已经熟悉 LLM 应用技术栈的技术人士来说，这 开源协议 - 基于 Apache License 2.0 有限商业许可 + [基于 Apache License 2.0 有限商业许可](/zh-hans/policies/open-source) 官方研发团队 diff --git a/zh-hans/guides/application-orchestrate/agent.mdx b/zh-hans/guides/application-orchestrate/agent.mdx index cacb4abf..9916fe90 100644 --- a/zh-hans/guides/application-orchestrate/agent.mdx +++ b/zh-hans/guides/application-orchestrate/agent.mdx @@ -10,9 +10,7 @@ title: Agent 为了方便快速上手使用，你可以在“探索”中找到智能助手的应用模板，添加到自己的工作区，或者在此基础上进行自定义。在全新的 Dify 工作室中，你也可以从零编排一个专属于你自己的智能助手，帮助你完成财务报表分析、撰写报告、Logo 设计、旅程规划等任务。 -
-
- 探索-智能助手应用模板 -
-
- ReAct 模式 -
-
+![Function Calling 模式](https://assets-docs.dify.ai/2025/04/8e150e070d55e90028a55db2ec8055af.png) + +![ReAct 模式](https://assets-docs.dify.ai/2025/04/64a320f30d050736ee03c5ac25d8d0a8.png) ### 配置对话开场白 diff --git a/zh-hans/guides/application-orchestrate/app-toolkits/moderation-tool.mdx b/zh-hans/guides/application-orchestrate/app-toolkits/moderation-tool.mdx index aee99c2e..9f34d2c2 100644 --- a/zh-hans/guides/application-orchestrate/app-toolkits/moderation-tool.mdx +++ b/zh-hans/guides/application-orchestrate/app-toolkits/moderation-tool.mdx @@ -21,7 +21,7 @@ OpenAI 和大多数 LLM 公司提供的模型，都带有内容审查功能， ### 功能三： 敏感词审查 Moderation 扩展 -不同的企业内部往往有着不同的敏感词审查机制，企业在开发自己的 AI 应用如企业内部知识库 ChatBot，需要对员工输入的查询内容作敏感词审查。为此，开发者可以根据自己企业内部的敏感词审查机制写一个 API 扩展，具体可参考 [moderation.md](../../extension/api-based-extension/moderation.md "mention")，从而在 Dify 上调用，实现敏感词审查的高度自定义和隐私保护。 +不同的企业内部往往有着不同的敏感词审查机制，企业在开发自己的 AI 应用如企业内部知识库 ChatBot，需要对员工输入的查询内容作敏感词审查。为此，开发者可以根据自己企业内部的敏感词审查机制写一个 API 扩展，具体可参考 [敏感内容审查](/zh-hans/guides/tools/extensions/api-based/moderation)，从而在 Dify 上调用，实现敏感词审查的高度自定义和隐私保护。 ![Moderation Settings](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/application-orchestrate/app-toolkits/d8b6dff6fce6d70795b87aefc56eb02b.png) diff --git a/zh-hans/guides/application-orchestrate/chatbot-application.mdx b/zh-hans/guides/application-orchestrate/chatbot-application.mdx index eaabf0a3..d4726be9 100644 --- a/zh-hans/guides/application-orchestrate/chatbot-application.mdx +++ b/zh-hans/guides/application-orchestrate/chatbot-application.mdx @@ -45,10 +45,18 @@ title: 聊天助手 编辑开场白时，还可以添加数个开场问题： +描述文字 + #### 添加上下文 如果想要让 AI 的对话范围局限在[知识库](../knowledge-base/)内，例如企业内的客服话术规范，可以在“上下文”内引用知识库。 +![](https://assets-docs.dify.ai/2025/04/f99d63b2c6ab6c5bd20d036374cd803c.png) + #### 添加文件上传 部分多模态 LLM 已原生支持处理文件，例如 [Claude 3.5 Sonnet](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support) 或 [Gemini 1.5 Pro](https://ai.google.dev/api/files)。你可以在 LLM 的官方网站了解文件上传能力的支持情况。 @@ -76,3 +84,7 @@ title: 聊天助手 **如何在聊天助手内添加第三方工具？** 聊天助手类型应用不支持添加第三方工具，你可以在 [Agent 类型](/zh-hans/guides/application-orchestrate/agent)应用内添加第三方工具。 + +**如何在创建聊天助手应用时，使用元数据功能筛选知识库内文档？** + +如需了解如何使用元数据功能筛选文档，请参阅 [在应用内集成知识库](https://docs.dify.ai/zh-hans/guides/knowledge-base/integrate-knowledge-within-application) 中的“**使用元数据筛选知识 > 聊天助手**”章节。 diff --git a/zh-hans/guides/application-orchestrate/creating-an-application.mdx b/zh-hans/guides/application-orchestrate/creating-an-application.mdx index 4ae81be3..7cc35d50 100644 --- a/zh-hans/guides/application-orchestrate/creating-an-application.mdx +++ b/zh-hans/guides/application-orchestrate/creating-an-application.mdx @@ -10,21 +10,27 @@ title: 创建应用 ## 从模板创建应用 -初次使用 Dify 时，你可能对于应用创建比较陌生。为了帮助新手用户快速了解在 Dify 上能够构建哪些类型的应用，Dify 团队内的提示词工程师已经创建好了多场景、高质量的应用模板。 +初次使用 Dify 时，你可能对于应用创建比较陌生。为了帮助新手用户快速了解在 Dify 上能够构建哪些类型的应用，Dify 团队内的提示词工程师已经创建多场景、高质量的应用模板。 你可以从导航选择 「工作室 」，在应用列表内选择 「从模板创建」。 +![](https://assets-docs.dify.ai/2025/04/30b22b65fd5dc3843a264aaad28c3495.png) + +任意选择某个模板，并将其添加至工作区。 + #### 创建一个新应用 如果你需要在 Dify 上创建一个空白应用，你可以从导航选择 「工作室」 ，在应用列表内选择 「从空白创建 」。 +![](https://assets-docs.dify.ai/2025/04/dc7550d48fbd76528d7ea88588e207c8.png) + Dify 上可以创建 5 种不同的应用类型，分别是聊天助手、文本生成应用、Agent、Chatflow 和 Workflow。 创建应用时，你需要给应用起一个名字、选择合适的图标，或者上传喜爱的图片用作图标、使用一段清晰的文字描述此应用的用途，以便后续应用在团队内的使用。 + * **单文件** 仅允许应用使用者上传单个文件。 @@ -165,9 +173,7 @@ file variables 和 array[file] variables 支持以下文件类型与格式： 下面是一个示例配置： - - LLM节点中直接使用文件变量的配置界面 - +![](https://assets-docs.dify.ai/2025/04/ec247f5de4f59d4fb0c4ac25ce2fd96c.png) 需要注意的是，直接在 LLM 节点中使用文件变量时，我们需要确保文件变量仅包含图片文件，否则可能会导致错误。如果用户可能上传不同类型的文件，我们需要使用列表操作来进行过滤。 @@ -175,9 +181,7 @@ file variables 和 array[file] variables 支持以下文件类型与格式： 将文件变量放置到 answer 节点或者 end 节点中，当应用运行到该节点都时候将会在会话框中提供文件下载卡片。点击卡片即可下载文件。 - - 会话框中的文件下载卡片界面 - +![](https://assets-docs.dify.ai/2025/04/2ffc81675dee89d477cc461385501ddd.png) ### 进阶使用 diff --git a/zh-hans/guides/workflow/key-concept.mdx b/zh-hans/guides/workflow/key-concept.mdx index 49330a81..0a6790c5 100644 --- a/zh-hans/guides/workflow/key-concept.mdx +++ b/zh-hans/guides/workflow/key-concept.mdx @@ -6,7 +6,7 @@ title: 关键概念 **节点是工作流的关键构成**，通过连接不同功能的节点，执行工作流的一系列操作。 -工作流的核心节点请查看[节点 - 开始](./nodes/start)。 +工作流的核心节点请从[节点说明 - 开始节点](./nodes/start)起阅读。 *** @@ -16,18 +16,29 @@ title: 关键概念 *** -### Chatflow 和 Workflow +### Chatflow -**应用场景** +**适用场景：** -* **Chatflow**：面向对话类情景，包括客户服务、语义搜索、以及其他需要在构建响应时进行多步逻辑的对话式应用程序。 -* **Workflow**：面向自动化和批处理情景，适合高质量翻译、数据分析、内容生成、电子邮件自动化等应用程序。 +面向对话类情景，包括客户服务、语义搜索、以及其他需要在构建响应时进行多步逻辑的对话式应用程序。该类型应用的特点在于支持对生成的结果进行多轮对话交互，调整生成的结果。 -**使用入口** +常见的交互路径：给出指令 → 生成内容 → 就内容进行多次讨论 → 重新生成结果 → 结束 -**可用节点差异** +![Chatflow 入口](https://assets-docs.dify.ai/2024/12/224b6bcd750ff0b83e3a5dac5cf24d7d.png) -1. End 节点属于 Workflow 的结束节点，仅可在流程结束时选择。 -2. Answer 节点属于 Chatflow ，用于流式输出文本内容，并支持在流程中间步骤输出。 -3. Chatflow 内置聊天记忆（Memory），用于存储和传递多轮对话的历史消息，可在 LLM 、问题分类等节点内开启，Workflow 无 Memory 相关配置，无法开启。 -4. Chatflow 的开始节点内置变量包括：`sys.query`，`sys.files`，`sys.conversation_id`，`sys.user_id`。Workflow 的开始节点内置变量包括：`sys.files`，`sys.user_id` +### 工作流（Workflow） + +**适用场景：** + +面向自动化和批处理情景，适合高质量翻译、数据分析、内容生成、电子邮件自动化等应用程序。该类型应用无法对生成的结果进行多轮对话交互。 + +常见的交互路径：给出指令 → 生成内容 → 结束 + +![](https://assets-docs.dify.ai/2024/12/26a9fc809854fe51d946c148587fc1cf.png) + +**应用类型差异** + +1. [End 节点](node/end)属于 Workflow 的结束节点，仅可在流程结束时选择。 +2. [Answer 节点](node/answer)属于 Chatflow ，用于流式输出文本内容，并支持在流程中间步骤输出。 +3. Chatflow 内置聊天记忆（Memory），用于存储和传递多轮对话的历史消息，可在 [LLM](node/llm) 、[问题分类](node/question-classifier)等节点内开启，Workflow 无 Memory 相关配置，无法开启。 +4. Chatflow 的开始节点内置变量包括：`sys.query`，`sys.files`，`sys.conversation_id`，`sys.user_id`。Workflow 的开始节点内置变量包括：`sys.files`，`sys.user_id` ，详见[变量](/zh-hans/guides/workflow/variables)。 diff --git a/zh-hans/guides/workflow/node/agent.mdx b/zh-hans/guides/workflow/node/agent.mdx index 51fddb01..d2d751cc 100644 --- a/zh-hans/guides/workflow/node/agent.mdx +++ b/zh-hans/guides/workflow/node/agent.mdx @@ -12,7 +12,7 @@ Agent 节点是 Dify Chatflow/Workflow 中用于实现自主工具调用的组 在 Dify Chatflow/Workflow 编辑器中，从组件栏拖拽 Agent 节点至画布。 -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/node/17317ea064e250fc603c32232f0e93d2.png) +![](https://assets-docs.dify.ai/2025/04/7200e6f466a9da21fd8282afa392b348.png) ### 选择 Agent 策略 diff --git a/zh-hans/guides/workflow/node/answer.mdx b/zh-hans/guides/workflow/node/answer.mdx index fe80c088..403afb97 100644 --- a/zh-hans/guides/workflow/node/answer.mdx +++ b/zh-hans/guides/workflow/node/answer.mdx @@ -15,7 +15,16 @@ version: '简体中文' 2. 输出生成图片 3. 输出纯文本 +**示例1：** 输出纯文本 + +![](https://assets-docs.dify.ai/2025/04/42bb6bdef101bf79f959f4fc56a50ff3.png) + +**示例2：** 输出图片+LLM回复 + +![](https://assets-docs.dify.ai/2025/04/d2c901e821029756ebf95f4e099d833f.png) + +![](https://assets-docs.dify.ai/2025/04/5a70a5e568dded3975e54cfa84085c93.png) + 直接回复节点可以不作为最终的输出节点，作为流程过程节点时，可以在中间步骤流式输出结果。 - diff --git a/zh-hans/guides/workflow/node/end.mdx b/zh-hans/guides/workflow/node/end.mdx index 910a8a83..dc2b4841 100644 --- a/zh-hans/guides/workflow/node/end.mdx +++ b/zh-hans/guides/workflow/node/end.mdx @@ -10,8 +10,9 @@ title: 结束 结束节点需要声明一个或多个输出变量，声明时可以引用任意上游节点的输出变量。 -> **注意** -> Chatflow 内不支持结束节点 + +Chatflow 内不支持结束节点。 + *** diff --git a/zh-hans/guides/workflow/node/llm.mdx b/zh-hans/guides/workflow/node/llm.mdx index b2d78e57..964c85b5 100644 --- a/zh-hans/guides/workflow/node/llm.mdx +++ b/zh-hans/guides/workflow/node/llm.mdx @@ -46,9 +46,11 @@ LLM 节点是 Chatflow/Workflow 的核心节点。该节点能够利用大语言 3. **填写上下文（可选）**，上下文可以理解为向 LLM 提供的背景信息，常用于填写[知识检索](knowledge-retrieval)的输出变量。 4. **编写提示词**，LLM 节点提供了一个易用的提示词编排页面，选择聊天模型或补全模型，会显示不同的提示词编排结构。如果选择聊天模型（Chat model），你可以自定义系统提示词（SYSTEM）/用户（USER）/ 助手（ASSISTANT）三部分内容。 - - 编写提示词 - +描述文字 如果在编写系统提示词（SYSTEM）时没有好的思路，也可以使用提示生成器功能，借助 AI 能力快速生成适合实际业务场景的提示词。 @@ -72,13 +74,13 @@ LLM 节点是 Chatflow/Workflow 的核心节点。该节点能够利用大语言 上下文变量是一种特殊变量类型，用于向 LLM 提供背景信息，常用于在知识检索场景下使用。详细说明请参考[知识检索节点](knowledge-retrieval)。 -**图片文件变量** +**文件变量** -具备视觉能力的 LLM 可以通过变量读取应用使用者所上传的图片。开启 VISION 后，选择图片文件的输出变量完成设置。 +部分 LLMs（例如 [Claude 3.5 Sonnet](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support)）已支持直接处理并分析文件内容，因此系统提示词已允许输入文件变量。为了避免潜在异常，应用开发者在使用该文件变量前需前往 LLM 官网确认 LLM 支持何种文件类型。 - - 视觉上传功能 - +![](https://assets-docs.dify.ai/2024/11/05b3d4a78038bc7afbb157078e3b2b26.png) + +> 阅读[文件上传](https://docs.dify.ai/zh-hans/guides/workflow/file-upload)了解如何搭建具备文件上传功能的 Chatflow/Workflow 应用。 **会话历史** @@ -123,25 +125,246 @@ LLM 节点是 Chatflow/Workflow 的核心节点。该节点能够利用大语言 **Jinja-2 模板：** LLM 的提示词编辑器内支持 Jinja-2 模板语言，允许你借助 Jinja2 这一强大的 Python 模板语言，实现轻量级数据转换和逻辑处理，参考[官方文档](https://jinja.palletsprojects.com/en/3.1.x/templates/)。 +**错误重试**：针对节点发生的部分异常情况，通常情况下再次重试运行节点即可解决。开启错误重试功能后，节点将在发生错误的时候按照预设策略进行自动重试。你可以调整最大重试次数和每次重试间隔以设置重试策略。 + +- 最大重试次数为 10 次 +- 最大重试间隔时间为 5000 ms + +![高质量](https://assets-docs.dify.ai/2024/12/dfb43c1cbbf02cdd36f7d20973a5529b.png) + +**异常处理**：提供多样化的节点错误处理策略，能够在当前节点发生错误时抛出故障信息而不中断主流程；或通过备用路径继续完成任务。详细说明请参考[异常处理](https://docs.dify.ai/guides/workflow/error-handling)。 + +**结构化输出**：确保 LLM 返回的数据格式可用、稳定、可预测，减少错误处理和格式转换的工作。 + + + +LLM 节点中的 **JSON Schema 编辑器** 让你能够定义 LLM 返回的数据结构，确保输出可解析、可复用、可控。你可以使用**可视化编辑模式**直观编辑，或通过**代码编辑模式**精细调整，适配不同复杂度的需求。 + + +作为节点级能力，JSON Schema 适用于所有模型的结构化输出定义和约束。 + +- **原生支持结构化输出的模型**：可直接使用 JSON Schema 定义结构化变量。 + +- **不支持结构化输出的模型**：系统会将 JSON Schema 以提示词方式输入。你可以尝试引导模型按结构生成内容，但这并不保证一定可以正确解析输出。 + + +**JSON Schema 编辑器入口** + +点击 **LLM 节点 > 输出变量**，打开 **结构化开关 > 配置**，即可进入 **JSON Schema 编辑器** 界面。JSON Schema 编辑器分为可视化编辑窗口与代码编辑窗口，两者可无缝切换。 + +![JSON Schema Editor](https://assets-docs.dify.ai/2025/04/646805384efa3cd85869d23a4d9735ad.png) + +***可视化编辑*** + +**适用场景** + +- **你只需要定义几个简单的字段**，例如 `name`、`email`、`age` 等，并不涉及嵌套结构。 + +- **你不熟悉 JSON Schema 语法**，希望不写代码，而是用直观的界面拖拽、添加字段。 + +- **你希望快速迭代字段结构**，而不是每次修改都需要更新 JSON 代码。 + +![Visual Editor](https://assets-docs.dify.ai/2025/04/a9d6a34a7903f81e4d57c7f1d8d0712b.png) + +**添加字段** + +在 **结构化输出** 框中点击 **添加子字段** 按钮，并配置字段参数： + +- *（必填）* **字段名** + +- *（必填）* **字段类型**：支持 string、number、object、array 等字段类型等。 + + > 对象（object）或数组（array）字段可添加子字段。 + +- **描述**：帮助 LLM 理解字段含义，提高输出准确性。 + +- **必填**：开启后，LLM 将强制返回该字段值。 + +- **枚举值**：用于限制字段值的可选范围，使模型仅能从预设的枚举值中返回值。例如，若只允许 `red`、`green`、`blue`： + +```json +{ + "type": "string", + "enum": ["red", "green", "blue"] +} +``` + + > 该规则要求输入值只能是 `red`、`green` 或 `blue`。 + +**删改字段** + +- 编辑字段：鼠标悬停至字段卡片，点击 **编辑** 图标，修改字段类型、描述、默认值等参数。 + +- 删除字段：鼠标悬停至字段卡片，点击 **删除** 图标，字段将从列表中删除。 + + > 删除对象（object）或数组（array）字段时，其所有子字段也会被删除。 + +**导入现有 JSON 示例** + +1. 点击 **从 JSON 导入** 按钮，在弹出的对话框中粘贴或上传 JSON 示例，例如： + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. 点击 **提交** 按钮，系统会自动解析 JSON 示例，并转换为 JSON Schema 如下： + +![JSON Schema Editor](https://assets-docs.dify.ai/2025/04/646805384efa3cd85869d23a4d9735ad.png) + +**使用 AI 生成 JSON Schema** + +1. 点击 **AI 生成** 图标，选择模型（如 GPT-4o）。在输入框中描述你的 JSON Schema，例如： + + > “我需要一个包含用户名（string）、年龄（number）和兴趣爱好（array）的 JSON Schema。” + +2. 点击 **生成** ，系统将自动生成 JSON Schema 如下： + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "username", + "age", + "interests" + ] +} +``` + +***代码编辑*** + +**适用场景** + +- **你的数据结构复杂，需要支持嵌套对象或数组**，例如 `订单详情`、`产品列表` 等。 + +- **你已经有一个 JSON Schema（或者 API 响应示例）**，希望直接粘贴并手动调整。 + +- **你希望使用高级 Schema 特性**，如 `pattern`（正则表达式匹配）或 `oneOf`（多种类型支持）。 + +- 你使用 LLM 生成了初步 Schema，但**希望修改某些字段的类型或结构**，使其更符合业务需求。 + +![JSON Schema](https://assets-docs.dify.ai/2025/04/669af808dd9d0d8521a36e14db731cec.png) + +**添加字段** + +1. 进入 JSON Schema 代码编辑器。 + +2. 点击 **从 JSON 导入**， 输入字段。例如： + +```json +{ + "name": "username", + "type": "string", + "description": "user's name", + "required": true +} +``` + +3. 点击 **保存**，系统会自动校验 JSON Schema 并保存。 + +**删改字段**：在 JSON 代码框直接删改字段类型、描述、默认值等参数，并点击 **保存**。 + +**导入现有 JSON 示例** + +1. 点击 **从 JSON 导入** 按钮，在弹出的对话框中粘贴或上传 JSON 示例，例如： + +```json +{ + "comment": "This is great!", + "rating": 5 +} +``` + +2. 点击 **提交** 按钮，系统会自动解析 JSON 示例，并转换为 JSON Schema 如下： + +```json +{ + "type": "object", + "properties": { + "comment": { + "type": "string" + }, + "rating": { + "type": "number" + } + }, + "required": [ + "comment", + "rating" + ], + "additionalProperties": false +} +``` + +**使用 AI 生成 JSON Schema** + +1. 点击 **AI 生成** 图标，选择模型（如 GPT-4o）。在输入框中描述你的 JSON Schema，例如： + + > “我需要一个包含用户名（string）、年龄（number）和兴趣爱好（array）的 JSON Schema。” + +2. 点击 **生成** ，系统将自动生成 JSON Schema 如下： + +```json +{ + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "age": { + "type": "number" + }, + "interests": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "username", + "age", + "interests" + ] +} +``` + + *** ### 使用案例 * **读取知识库内容** -想要让工作流应用具备读取 ["知识库"](/zh-cn/user-guide/knowledge-base/) 内容的能力，例如搭建智能客服应用，请参考以下步骤： +想要让工作流应用具备读取 [“知识库”](../../knowledge-base/) 内容的能力，例如搭建智能客服应用，请参考以下步骤： 1. 在 LLM 节点上游添加知识库检索节点； 2. 将知识检索节点的 **输出变量** `result` 填写至 LLM 节点中的 **上下文变量** 内； 3. 将 **上下文变量** 插入至应用提示词内，赋予 LLM 读取知识库内的文本能力。 - - 上下文变量 - +![](https://assets-docs.dify.ai/2025/04/8ec79d64b90bd4c690ab5a9af8de1cc4.png) -[知识检索节点](knowledge-retrieval)输出的变量 `result` 还包含了分段引用信息，你可以通过 [**引用与归属**](/zh-hans/guides/knowledge-base/retrieval-test-and-citation) 功能查看信息来源。 +[知识检索节点](knowledge-retrieval.md)输出的变量 `result` 还包含了分段引用信息，你可以通过 [**引用与归属**](../../knowledge-base/retrieval-test-and-citation.md#id-2-yin-yong-yu-gui-shu) 功能查看信息来源。 -> 上游节点的普通变量同样可以填写至上下文变量内，例如开始节点的字符串类型变量，但 **引用与归属** 功能将会失效。 + +上游节点的普通变量同样可以填写至上下文变量内，例如开始节点的字符串类型变量，但 **引用与归属** 功能将会失效。 + * **读取文档文件** @@ -151,8 +374,62 @@ LLM 节点是 Chatflow/Workflow 的核心节点。该节点能够利用大语言 * 在 LLM 节点上游添加文档提取器节点，将文件变量作为输入变量； * 将文档提取器节点的 **输出变量** `text` 填写至 LLM 节点中的提示词内。 -如需了解更多，请参考[文件上传](/zh-hans/guides/workflow/file-upload)。 +如需了解更多，请参考[文件上传](../file-upload.md)。 - - 填写系统提示词 - +![](https://assets-docs.dify.ai/2025/04/c74cf0c58aaf1f35e515044deec2a88c.png) + +* **异常处理** + +LLM 节点处理信息时有可能会遇到输入文本超过 Token 限制，未填写关键参数等错误。应用开发者可以参考以下步骤配置异常分支，在节点出现异常时启用应对方案，而避免中断整个流程。 + +1. 在 LLM 节点启用 “异常处理” +2. 选择异常处理方案并进行配置 + +如需了解更多应对异常的处理办法，请参考[异常处理](https://docs.dify.ai/guides/workflow/error-handling)。 + +![Error handling](https://assets-docs.dify.ai/2024/12/48c666959a491aa87c2232c444794dc5.png) + +* **结构化输出** + +**场景**：你正在使用 Dify 构建一个用户反馈分析工作流。LLM 节点需要读取用户评价，并返回标准化的评分和评论内容，确保数据格式一致，便于后续节点处理。 + +**解决方案**：在工作流的 LLM 节点中，使用 **JSON Schema 编辑器** 定义结构化格式。这样能确保 LLM 生成的结果被限制在预设格式中，而非输出杂乱文本。 + +**操作步骤**： + +1. 在 **LLM** 节点的 **JSON Schema 编辑器** 中，添加以下字段，确保 LLM 按照规定的结构输出数据： + +```json +{ + "type": "object", + "properties": { + "rating": { + "type": "integer", + "description": "user's rating" + }, + "comment": { + "type": "string", + "description": "user's comments" + } + }, + "required": [ + "rating", + "comment" + ] +} +``` + +2. 在工作流的 **开始** 节点，输入一个用户评价，如： + +> "这个产品非常棒，使用体验很好！" + +3. 经过 **JSON Schema 编辑器** 的处理，AI 生成的 **结构化数据** 如下： + +```json +{ + "structured_output": { + "comment": "这个产品非常棒，使用体验很好！", + "rating": 5 + } +} +``` diff --git a/zh-hans/guides/workflow/node/parameter-extractor.mdx b/zh-hans/guides/workflow/node/parameter-extractor.mdx index 8fc95938..146264f2 100644 --- a/zh-hans/guides/workflow/node/parameter-extractor.mdx +++ b/zh-hans/guides/workflow/node/parameter-extractor.mdx @@ -8,7 +8,7 @@ title: 参数提取 Dify 工作流内提供了丰富的[工具](https://docs.dify.ai/v/zh-hans/guides/tools)选择，其中大多数工具的输入为结构化参数，参数提取器可以将用户的自然语言转换为工具可识别的参数，方便工具调用。 -工作流内的部分节点有特定的数据格式传入要求，如[迭代](/zh-hans/guides/workflow/nodes/iteration)节点的输入要求为数组格式，参数提取器可以方便的实现结构化参数的转换。 +工作流内的部分节点有特定的数据格式传入要求，如[迭代](/zh-hans/guides/workflow/node/iteration)节点的输入要求为数组格式，参数提取器可以方便的实现结构化参数的转换。 *** @@ -20,11 +20,11 @@ Dify 工作流内提供了丰富的[工具](https://docs.dify.ai/v/zh-hans/guide ![Arxiv 论文检索工具](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/node/9119e3f40d71ac845ad1e14f7401ee1f.png) -2. **将文本转换为结构化数据**，如长故事迭代生成应用中，作为[迭代节点](/zh-hans/guides/workflow/nodes/iteration)的前置步骤，将文本格式的章节内容转换为数组格式，方便迭代节点进行多轮生成处理。 +2. **将文本转换为结构化数据**，如长故事迭代生成应用中，作为[迭代节点](/zh-hans/guides/workflow/node/iteration)的前置步骤，将文本格式的章节内容转换为数组格式，方便迭代节点进行多轮生成处理。 ![长故事迭代生成应用流程图](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/node/342d37bfa31c1d9ab26cd8212be7ee7d.png) -3. **提取结构化数据并使用** [**HTTP 请求**](/zh-hans/guides/workflow/nodes/http-request) ，可请求任意可访问的 URL ，适用于获取外部检索结果、webhook、生成图片等情景。 +3. **提取结构化数据并使用** [**HTTP 请求**](/zh-hans/guides/workflow/node/http-request) ，可请求任意可访问的 URL ，适用于获取外部检索结果、webhook、生成图片等情景。 *** diff --git a/zh-hans/guides/workflow/node/start.mdx b/zh-hans/guides/workflow/node/start.mdx index 15ec90f6..9b87296a 100644 --- a/zh-hans/guides/workflow/node/start.mdx +++ b/zh-hans/guides/workflow/node/start.mdx @@ -1,6 +1,5 @@ --- title: 开始 -version: '简体中文' --- ## 定义 @@ -50,7 +49,7 @@ Workflow 类型应用提供以下系统变量： | `sys.workflow_id` | String | Workflow ID，用于记录当前 Workflow 应用内所包含的所有节点信息 | 面向具备开发能力的用户，可以通过此参数追踪并记录 Workflow 内的包含节点信息 | | `sys.workflow_run_id` | String | Workflow 应用运行 ID，用于记录 Workflow 应用中的运行情况 | 面向具备开发能力的用户，可以通过此参数追踪应用的历次运行情况 | -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/node/cb39be409f0037549d45f4b7d05aa9ce.png) +![](https://assets-docs.dify.ai/2025/04/cb39be409f0037549d45f4b7d05aa9ce.png) **Chatflow** @@ -67,4 +66,4 @@ Chatflow 类型应用提供以下系统变量： | `sys.workflow_id` | String | Workflow ID，用于记录当前 Workflow 应用内所包含的所有节点信息 | 面向具备开发能力的用户，可以通过此参数追踪并记录 Workflow 内的包含节点信息 | | `sys.workflow_run_id` | String | Workflow 应用运行 ID，用于记录 Workflow 应用中的运行情况 | 面向具备开发能力的用户，可以通过此参数追踪应用的历次运行情况 | -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/node/233efef6802ae700489f3ab3478bca6b.png) \ No newline at end of file +![](https://assets-docs.dify.ai/2025/04/233efef6802ae700489f3ab3478bca6b.png) diff --git a/zh-hans/guides/workflow/node/template.mdx b/zh-hans/guides/workflow/node/template.mdx index f96df6d7..c581c2be 100644 --- a/zh-hans/guides/workflow/node/template.mdx +++ b/zh-hans/guides/workflow/node/template.mdx @@ -9,11 +9,9 @@ version: '简体中文' ### 什么是 Jinja？ -> Jinja is a fast, expressive, extensible templating engine. +> [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) is a fast, expressive, extensible templating engine. > -> Jinja 是一个快速、表达力强、可扩展的模板引擎。 - -—— [https://jinja.palletsprojects.com/en/3.1.x/](https://jinja.palletsprojects.com/en/3.1.x/) +> [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) 是一个快速、表达力强、可扩展的模板引擎。 ### 场景 diff --git a/zh-hans/guides/workflow/node/variable-assigner.mdx b/zh-hans/guides/workflow/node/variable-assigner.mdx index a653d1cc..ca4c1bd1 100644 --- a/zh-hans/guides/workflow/node/variable-assigner.mdx +++ b/zh-hans/guides/workflow/node/variable-assigner.mdx @@ -7,7 +7,8 @@ version: '简体中文' 变量赋值节点用于向可写入变量进行变量赋值，已支持以下可写入变量： -* [会话变量](../variables#会话变量)。 +* [会话变量](../variables#会话变量) +* [循环变量](/zh-hans/guides/workflow/node/loop) 用法：通过变量赋值节点，你可以将工作流内的变量赋值到会话变量中用于临时存储，并可以在后续对话中持续引用。 @@ -160,8 +161,32 @@ def main(arg1: list) -> str: 以上图赋值逻辑为例：将上一个节点的文本输出项 `Language Recognition/text` 赋值到会话变量 `language` 内。 -**写入模式：** +### 指定变量的写入模式 -* 覆盖，将源变量的内容覆盖至目标会话变量 -* 追加，指定变量为 Array 类型时 -* 清空，清空目标会话变量中的内容 \ No newline at end of file +目标变量的数据类型将影响变量的写入模式。以下是不同变量间的写入模式： + +1. 目标变量的数据类型为 `String`。 + + * **覆盖**，将源变量直接覆盖至目标变量 + * **清空**，清空所选中变量中的内容 + * **设置**，手动指定一个值，无需设置源变量 + +2. 目标变量的数据类型为 `Number`。 + + * **覆盖**，将源变量直接覆盖至目标变量 + * **清空**，清空所选中变量中的内容 + * **设置**，手动指定一个值，无需设置源变量 + * **数字处理**，对目标变量进行`加减乘除`操作 + +3. 目标变量的数据类型为 `Object`。 + + * **覆盖**，将源变量的内容直接覆盖至目标变量 + * **清空**，清空所选中变量中的内容 + * **设置**，手动指定一个值，无需设置源变量 + +4. 目标变量的数据类型为 `Array`。 + + * **覆盖**，将源变量的内容直接覆盖至目标变量 + * **清空**，清空所选中变量中的内容 + * **追加**，在目标的数组变量中添加一个新的元素 + * **扩展**，在目标的数组变量中添加新的数组，即一次性添加多个元素 diff --git a/zh-hans/guides/workflow/structured-outputs.mdx b/zh-hans/guides/workflow/structured-outputs.mdx new file mode 100644 index 00000000..e72f4b48 --- /dev/null +++ b/zh-hans/guides/workflow/structured-outputs.mdx @@ -0,0 +1,63 @@ +--- +title: 结构化输出 +--- + +## 简介 + +作为 LLM 工具链平台，Dify 支持 JSON 结构化输出功能。结构化输出功能可以确保 LLM 返回的数据格式可用、稳定、可预测，减少错误处理和格式转换的工作。 + +## 价值 + +- **确保数据格式一致**：即使由 LLM 生成内容，也必须符合预设格式，避免数据混乱。 + +- **方便后续节点处理**：数据库、API 或前端可以直接解析 JSON Schema，而无需额外数据清洗。 + +- **提升低代码开发体验**：开发者无需手写复杂数据校验逻辑，直接使用 JSON Schema 约束输出。 + +## 如何实现结构化输出？ + +在 Dify 的操作界面中，可以通过以下两种方式实现结构化输出： + +- **方式一：直接定义工具参数** + +- **方式二：使用 LLM 节点中的 JSON Schema 编辑器** + +### 方式一：直接定义工具参数 + +请参阅 **[Tool](https://docs.dify.ai/zh-hans/plugins/schema-definition/tool) > 数据结构 > 返回变量定义**。 + +### 方式二：使用 LLM 节点中的 JSON Schema 编辑器 + +请参阅 **[LLM](https://docs.dify.ai/zh-hans/guides/workflow/node/llm) > 高级功能 > 结构化输出** 与 **[LLM](https://docs.dify.ai/zh-hans/guides/workflow/node/llm) > 使用案例 > 结构化输出**。 + +## 异常处理方案 + +**异常情况** + +在使用 JSON Schema 编辑器进行结构化输出时，可能会遇到以下限制和异常情况： + +- **模型能力限制**：部分 LLM（尤其是 70B 以下的模型或 GPT-3.5 Turbo 级别模型）在指令遵循性上较弱，可能导致 JSON Schema 解析失败。 + +- **格式兼容性**：部分 LLM 仅支持 **JSON mode** 而非 **JSON Schema**，导致严格的 Schema 解析失败。 + +- **错误信息**：出现错误 `Failed to parse structured output: output is not a valid json str`。此类错误主要源于模型生成 JSON 失败。 + +**推荐处理方案** + +1. **优先使用支持 JSON Schema 的模型**。推荐列表如下： + - Gemini 2.0 Flash/Flash-Lite + - Gemini 1.5 Flash 8B (0827/0924) + - Gemini-1.5 pro + - GPT-4o + - GPT-4o-mini + - o1-mini/o3-mini 系列 + +2. **适当调整系统提示词以增强指令遵循性，尽可能确保 LLM 输出符合 Schema 规范**。假如 JSON Schema 设计用于结构化数学公式的输入与输出，而系统提示词却要求模型进行法律条文解析，这种不匹配可能会导致模型无法正确理解任务，影响生成结果的准确性。 + +3. **配置异常处理策略**。你可以在解析失败时考虑采取以下措施： + + 1. **配置失败时重试**：在节点内开启 **失败时重试** 功能并配置最大重试次数与重试间隔，以减少解析错误的影响。 + + 2. **配置异常分支**：在节点内的 **异常处理** 中配置 **失败分支**。当节点发生异常时，将自动执行失败分支。 + +详情请参阅[异常处理](https://docs.dify.ai/zh-hans/guides/workflow/error-handling)。 diff --git a/zh-hans/guides/workflow/variables.mdx b/zh-hans/guides/workflow/variables.mdx index 6d3020b5..c563deb6 100644 --- a/zh-hans/guides/workflow/variables.mdx +++ b/zh-hans/guides/workflow/variables.mdx @@ -1,6 +1,6 @@ --- title: 变量 -version: '简体中文' +description: 最近编辑：Allen, Dify Technical Writer --- Workflow 和 Chatflow 类型应用由独立节点相构成。大部分节点设有输入和输出项，但每个节点的输入信息不一致，各个节点所输出的答复也不尽相同。 @@ -58,7 +58,7 @@ Workflow 类型应用提供以下系统变量： -![](/zh-cn/img/c405efa31fd5708542fdc3bd7c0cb708.png) +![](https://assets-docs.dify.ai/2025/04/c405efa31fd5708542fdc3bd7c0cb708.png) #### Chatflow @@ -131,7 +131,7 @@ Chatflow 类型应用提供以下系统变量： **环境变量用于保护工作流内所涉及的敏感信息**，例如运行工作流时所涉及的 API 密钥、数据库密码等。它们被存储在工作流程中，而不是代码中，以便在不同环境中共享。 -![](/zh-cn/img/d27ebecdc87e630212fb0ed866bf8e9e.png) +![](https://assets-docs.dify.ai/2025/04/c79ca2cbce49a61b1fb94d5bd7a53274.png) 支持以下三种数据类型： @@ -153,7 +153,7 @@ Chatflow 类型应用提供以下系统变量： 例如你可以将用户在首轮对话时输入的语言偏好存储至会话变量中，LLM 在回答时将参考会话变量中的信息，并在后续的对话中使用指定的语言回复用户。 -![](/zh-cn/img/338f93f401142fea4936a67a615eba32.png) +![](https://assets-docs.dify.ai/2025/04/338f93f401142fea4936a67a615eba32.png) **会话变量**支持以下六种数据类型： @@ -167,10 +167,10 @@ Chatflow 类型应用提供以下系统变量： **会话变量**具有以下特性： * 会话变量可在大部分节点内全局引用； -* 会话变量的写入需要使用[变量赋值](./nodes/variable-assigner)节点； +* 会话变量的写入需要使用[变量赋值](./node/variable-assigner)节点； * 会话变量为可读写变量； -关于如何将会话变量与变量赋值节点配合使用，请参考[变量赋值](./nodes/variable-assigner)节点说明。 +关于如何将会话变量与变量赋值节点配合使用，请参考[变量赋值](./node/variable-assigner)节点说明。 ### 注意事项