mirror of
https://github.com/langgenius/dify-docs-archived.git
synced 2026-07-01 20:35:52 -04:00
docs: structured outputs (#634)
* docs: structured outputs * update: docs * update: structured outputs main doc * update: mandarin version of llm node * update: formats * update: llm node docs 3 languages * update: a few updates * update: v-ing * update: small errors * update: convert structured output format from Mintlify to GitBook * fix: convert mintlify format to gitbook format * Update llm.md * update: pic links * update: format * update: more info * update: doc guide --------- Co-authored-by: AllenWriter <allen@landaofudebijibendiannao.local> Co-authored-by: Hanqing Zhao <sherry9277@gmail.com>
This commit is contained in:
Jing Y.
@@ -69,6 +69,7 @@
|
||||
* [Checklist](guides/workflow/debug-and-preview/checklist.md)
|
||||
* [Run History](guides/workflow/debug-and-preview/history.md)
|
||||
* [Application Publishing](guides/workflow/publish.md)
|
||||
* [Structured Outputs](guides/workflow/structured-outputs.md)
|
||||
* [Bulletin: Image Upload Replaced by File Upload](guides/workflow/bulletin.md)
|
||||
* [Knowledge](guides/knowledge-base/README.md)
|
||||
* [Create Knowledge](guides/knowledge-base/create-knowledge-and-upload-documents.md)
|
||||
|
||||
@@ -131,6 +131,187 @@ 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](https://docs.dify.ai/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 returns data.
|
||||
|
||||
<details>
|
||||
<summary>JSON Schema Editor</summary>
|
||||
|
||||
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.
|
||||
|
||||
{% hint style="info" %}
|
||||
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 wll include your schema in the prompt, but response formatting may vary by model.
|
||||
{% endhint %}
|
||||
|
||||
**Get Started**
|
||||
|
||||
Access the editor through **LLM Node > Output Variables > Structured > Configure**. You can switch between visual and JSON Schema editing modes.
|
||||
|
||||
|
||||
|
||||
***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
|
||||
|
||||
|
||||
|
||||
**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:
|
||||
|
||||
```
|
||||
{
|
||||
"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:
|
||||
|
||||
```
|
||||
{
|
||||
"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:
|
||||
|
||||
```
|
||||
{
|
||||
"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
|
||||
|
||||
|
||||
|
||||
**Add Fields**
|
||||
|
||||
1. Click **Import from JSON** and add your field structure:
|
||||
|
||||
```
|
||||
{
|
||||
"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:
|
||||
|
||||
```
|
||||
{
|
||||
"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:
|
||||
|
||||
```
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"username": {
|
||||
"type": "string"
|
||||
},
|
||||
"age": {
|
||||
"type": "number"
|
||||
},
|
||||
"interests": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["username", "age", "interests"]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
***
|
||||
|
||||
#### Use Cases
|
||||
@@ -173,3 +354,43 @@ When processing information, LLM nodes may encounter errors such as input text e
|
||||
<figure><img src="https://assets-docs.dify.ai/2024/12/f7109ce5e87c0e0a81248bb2672c7667.png" alt=""><figcaption><p>input system prompts</p></figcaption></figure>
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
{
|
||||
"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:
|
||||
|
||||
```
|
||||
{
|
||||
"structured_output": {
|
||||
"comment": "This product is excellent!",
|
||||
"rating": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,54 @@
|
||||
## 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 **[How to Use JSON Schema Output in Dify?](https://docs.dify.ai/learn-more/extended-reading/how-to-use-json-schema-in-dify)**.
|
||||
|
||||
### 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.
|
||||
@@ -69,6 +69,7 @@
|
||||
* [チェックリスト](guides/workflow/debug-and-preview/checklist.md)
|
||||
* [実行履歴](guides/workflow/debug-and-preview/history.md)
|
||||
* [アプリケーション公開](guides/workflow/publish.md)
|
||||
* [JSON形式での出力](guides/workflow/structured-outputs.md)
|
||||
* [変更通知：画像アップロード機能がファイルアップロード機能に統合されました](guides/workflow/bulletin.md)
|
||||
* [ナレッジベース](guides/knowledge-base/README.md)
|
||||
* [ナレッジベース作成](guides/knowledge-base/create-knowledge-and-upload-documents/README.md)
|
||||
|
||||
@@ -130,6 +130,197 @@ Difyを初めて使用する場合は、LLMノードでモデルを選択する
|
||||
|
||||
**エラー処理**：異なるエラー対応戦略を提供し、現在のノードが失敗してもメインプロセスを止めずにエラー通知を行うか、バックアップ経路を使ってタスクを継続できるようにします。詳細は、[エラー処理](../error-handling/README.md)をご覧ください。
|
||||
|
||||
**構造化された出力**: LLM が返すデータ形式の可用性、安定性、予測可能性を高め、エラー処理や形式変換の手間を削減します。
|
||||
|
||||
<details>
|
||||
<summary>JSONスキーマエディタ</summary>
|
||||
|
||||
LLMノードのJSONスキーマエディタを使用すると、LLM が返すデータ構造を定義し、出力の解析性、再利用性、制御性を保証できます。ビジュアル編集モードによる直感的な編集、コード編集モードによる詳細な調整により、様々な複雑度のニーズに対応できます。
|
||||
|
||||
{% hint style="info" %}
|
||||
ノードレベルの機能であるJSONスキーマは、すべてのモデルの構造化出力の定義と制約に利用できます。
|
||||
|
||||
- 構造化出力をネイティブでサポートするモデル: JSONスキーマを使用して構造化変数を直接定義できます。
|
||||
|
||||
- 構造化出力をサポートしていないモデル: システムはJSONスキーマをプロンプトとして使用します。構造に基づいたコンテンツ生成をモデルに促せますが、出力の正しい解析は保証されません。
|
||||
{% endhint %}
|
||||
|
||||
**JSONスキーマエディタの開き方**
|
||||
|
||||
LLMノードの出力変数をクリックし、構造化スイッチの設定を開くと、JSONスキーマエディタが表示されます。JSONスキーマエディタはビジュアル編集ウィンドウとコード編集ウィンドウを備え、シームレスに切り替えられます。
|
||||
|
||||
|
||||
|
||||
***ビジュアル編集***
|
||||
|
||||
**使用シーン**
|
||||
|
||||
- ネスト構造を含まない、いくつかの単純なフィールドを定義する場合。
|
||||
|
||||
- JSONスキーマの構文に慣れていない場合、コードを書かずに、直感的なインターフェースでドラッグアンドドロップしてフィールドを追加できます。
|
||||
|
||||
- フィールド構造を素早く繰り返し変更したい場合。JSONコードを毎回変更する必要はありません。
|
||||
|
||||
|
||||
|
||||
**フィールドの追加**
|
||||
|
||||
構造化出力枠内でフィールドを追加ボタンをクリックし、フィールドのパラメータを設定します。
|
||||
|
||||
- *（必須）*フィールド名
|
||||
|
||||
- *（必須）*フィールドタイプ: string、number、object、arrayなどのフィールドタイプをサポートしています。
|
||||
|
||||
> オブジェクトまたは配列フィールドには、子フィールドを追加できます。
|
||||
|
||||
- 説明: LLMがフィールドの意味を理解し、出力精度を向上させます。
|
||||
|
||||
- 必須: オンにすると、LLMはこのフィールド値を必ず返します。
|
||||
|
||||
- 列挙型: フィールド値の選択範囲を制限するために使用します。モデルは、あらかじめ設定された列挙値のみを返します。たとえば、`red`、`green`、`blue` のみを許可する場合は、次のようになります。
|
||||
|
||||
```
|
||||
{
|
||||
"type": "string",
|
||||
"enum": ["red", "green", "blue"]
|
||||
}
|
||||
```
|
||||
|
||||
> このルールでは、入力値は `red`、`green`、`blue` のいずれかでなければなりません。
|
||||
|
||||
**フィールドの編集・削除**
|
||||
|
||||
- フィールドの編集：フィールドカードにマウスオーバーして、「編集」アイコンをクリックし、フィールドのタイプ、説明、デフォルト値などの項目を変更します。
|
||||
|
||||
- フィールドの削除：フィールドカードにマウスオーバーして、「削除」アイコンをクリックすると、フィールドがリストから削除されます。
|
||||
|
||||
> オブジェクトまたは配列フィールドを削除すると、そのすべての子フィールドも削除されます。
|
||||
|
||||
**JSONデータのインポート**
|
||||
|
||||
1. 「JSONをインポート」ボタンをクリックし、表示されるダイアログボックスにJSONデータを貼り付けるか、アップロードします。例（JSONデータ）：
|
||||
|
||||
```
|
||||
{
|
||||
"comment": "This is great!",
|
||||
"rating": 5
|
||||
}
|
||||
```
|
||||
|
||||
2. 「送信」ボタンをクリックすると、システムがJSONデータを自動的に解析し、JSONスキーマに変換します。
|
||||
|
||||
**AIでJSONスキーマを生成する**
|
||||
|
||||
1. 「AI生成」アイコンをクリックし、モデル（GPT-4など）を選択します。入力ボックスにJSONスキーマの説明を入力します。例：
|
||||
|
||||
> 「ユーザー名、年齢、および趣味を含むJSONスキーマが必要です。」
|
||||
|
||||
2. 「生成」をクリックすると、システムが自動的に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で作成したスキーマを元に、フィールドのタイプや構造をビジネスニーズに合わせて変更したい場合。
|
||||
|
||||
|
||||
|
||||
**フィールドの追加**
|
||||
|
||||
1. コードエディタを開きます。
|
||||
|
||||
2. 「フィールドを追加」をクリックし、フィールドを入力します。例：
|
||||
|
||||
```
|
||||
{
|
||||
"name": "username",
|
||||
"type": "string",
|
||||
"description": "user's name",
|
||||
"required": true
|
||||
}
|
||||
```
|
||||
|
||||
3. 「保存」をクリックすると、システムがJSONスキーマを自動的に検証し、保存します。
|
||||
|
||||
**フィールドの編集・削除**：JSONコードボックスで、フィールドのタイプ、説明、デフォルト値などの項目を直接編集・削除し、「保存」をクリックします。
|
||||
|
||||
**JSONデータのインポート**
|
||||
|
||||
1. 「JSONをインポート」ボタンをクリックし、表示されるダイアログボックスにJSONデータを貼り付けるか、アップロードします。例（JSONデータ）：
|
||||
|
||||
```
|
||||
{
|
||||
"comment": "This is great!",
|
||||
"rating": 5
|
||||
}
|
||||
```
|
||||
|
||||
2. 「送信」ボタンをクリックすると、システムがJSONデータを自動的に解析し、JSONスキーマに変換します。
|
||||
|
||||
**AIでJSONスキーマを生成する**
|
||||
|
||||
1. 「AI生成」アイコンをクリックし、モデル（GPT-4など）を選択します。入力ボックスにJSONスキーマの説明を入力します。例：
|
||||
|
||||
> 「ユーザー名、年齢、および趣味を含むJSONスキーマが必要です。」
|
||||
|
||||
2. 「生成」をクリックすると、システムが自動的にJSONスキーマを生成します。
|
||||
|
||||
```
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"username": {
|
||||
"type": "string"
|
||||
},
|
||||
"age": {
|
||||
"type": "number"
|
||||
},
|
||||
"interests": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"username",
|
||||
"age",
|
||||
"interests"
|
||||
]
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
***
|
||||
|
||||
### 活用事例
|
||||
@@ -171,4 +362,49 @@ Difyを初めて使用する場合は、LLMノードでモデルを選択する
|
||||
|
||||
<figure><img src="https://assets-docs.dify.ai/2024/12/f7109ce5e87c0e0a81248bb2672c7667.png" alt=""><figcaption><p>入力システムプロンプト</p></figcaption></figure>
|
||||
|
||||
エラー処理の詳細は、[エラー処理](https://docs.dify.ai/guides/workflow/error-handling)をご覧ください。
|
||||
エラー処理の詳細は、[エラー処理](https://docs.dify.ai/guides/workflow/error-handling)をご覧ください。
|
||||
|
||||
* **構造化出力**
|
||||
|
||||
**シナリオ**: Difyワークフローを使用してユーザーフィードバック分析ワークフローを構築する際に、LLMノードはユーザー評価を読み取り、標準化された評価とコメントを返します。これにより、後続ノードがデータを正しく処理できるよう、データ形式の一貫性を保ちます。
|
||||
|
||||
**解決策**: ワークフローのLLMノードで、**JSONスキーマエディタ**を使用してLLM出力の構造化フォーマットを定義できます。これにより、LLM は自由形式のテキストではなく、定義済みのフォーマットに従って結果を出力します。
|
||||
|
||||
**操作手順**:
|
||||
|
||||
1. **LLM**ノードの**JSONスキーマエディタ**で、以下のフィールドを追加します。これによりLLMは指定の構造でデータを出力します。
|
||||
|
||||
```
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"rating": {
|
||||
"type": "integer",
|
||||
"description": "ユーザー評価"
|
||||
},
|
||||
"comment": {
|
||||
"type": "string",
|
||||
"description": "ユーザーコメント"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"rating",
|
||||
"comment"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. ワークフローの**開始**ノードで、ユーザー評価を入力します。例:
|
||||
|
||||
> "この製品はとても素晴らしいです。使用体験も良好です！"
|
||||
|
||||
3. **JSONスキーマエディタ**による処理後、LLMから出力される**構造化データ**は以下のようになります。
|
||||
|
||||
```
|
||||
{
|
||||
"structured_output": { // LLMからの出力データ
|
||||
"comment": "この製品はとても素晴らしいです。使用体験も良好です！",
|
||||
"rating": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
## JSON形式での出力
|
||||
|
||||
DifyはLLMツールチェーンプラットフォームとして、JSON形式での出力機能をサポートしています。この機能により、LLMから返されるデータの形式が利用しやすく、安定し、予測可能になります。エラー処理やフォーマット変換の手間を削減できます。
|
||||
|
||||
## 利点
|
||||
|
||||
- **データ形式の整合性確保**: LLMがコンテンツを生成する場合でも、事前に設定された形式に準拠し、データの不整合を防ぎます。
|
||||
|
||||
- **後続処理の簡素化**: データベース、APIまたはフロントエンドは、追加のデータクレンジングなしでJSONスキーマを直接解析できます。
|
||||
|
||||
- **ローコード開発の効率化**: 開発者は複雑なデータ検証ロジックを手書きする必要がなく、JSONスキーマを使用して出力を制限できます。
|
||||
|
||||
## JSON形式での出力の実装方法
|
||||
|
||||
Difyの操作画面では、次の2つの方法でJSON形式での出力を実装できます。
|
||||
|
||||
- **方法1: ツール設定を直接行う**
|
||||
|
||||
- **方法2: LLMノードのJSONスキーマエディタを使用する**
|
||||
|
||||
### 方法1: ツール設定を直接行う
|
||||
|
||||
**[DifyでJSONスキーマ出力を使用する方法](https://docs.dify.ai/ja-jp/learn-more/extended-reading/how-to-use-json-schema-in-dify)**を参照してください。
|
||||
|
||||
### 方法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)を参照してください。
|
||||
@@ -69,6 +69,7 @@
|
||||
* [检查清单](guides/workflow/debug-and-preview/checklist.md)
|
||||
* [运行历史](guides/workflow/debug-and-preview/history.md)
|
||||
* [应用发布](guides/workflow/publish.md)
|
||||
* [结构化输出](guides/workflow/structured-outputs.md)
|
||||
* [变更公告：图片上传被替换为文件上传](guides/workflow/bulletin.md)
|
||||
* [知识库](guides/knowledge-base/README.md)
|
||||
* [创建知识库](guides/knowledge-base/create-knowledge-and-upload-documents/README.md)
|
||||
|
||||
@@ -125,6 +125,219 @@ LLM 节点是 Chatflow/Workflow 的核心节点。该节点能够利用大语言
|
||||
|
||||
**异常处理**：提供多样化的节点错误处理策略，能够在当前节点发生错误时抛出故障信息而不中断主流程；或通过备用路径继续完成任务。详细说明请参考[异常处理](https://docs.dify.ai/guides/workflow/error-handling)。
|
||||
|
||||
**结构化输出**：确保 LLM 返回的数据格式可用、稳定、可预测，减少错误处理和格式转换的工作。
|
||||
|
||||
<details>
|
||||
<summary>JSON Schema 编辑器</summary>
|
||||
|
||||
LLM 节点中的 **JSON Schema 编辑器** 让你能够定义 LLM 返回的数据结构，确保输出可解析、可复用、可控。你可以使用**可视化编辑模式**直观编辑，或通过**代码编辑模式**精细调整，适配不同复杂度的需求。
|
||||
|
||||
{% hint style="info" %}
|
||||
作为节点级能力，JSON Schema 适用于所有模型的结构化输出定义和约束。
|
||||
|
||||
- **原生支持结构化输出的模型**：可直接使用 JSON Schema 定义结构化变量。
|
||||
|
||||
- **不支持结构化输出的模型**：系统会将 JSON Schema 以提示词方式输入。你可以尝试引导模型按结构生成内容，但这并不保证一定可以正确解析输出。
|
||||
{% endhint %}
|
||||
|
||||
**JSON Schema 编辑器入口**
|
||||
|
||||
点击 **LLM 节点 > 输出变量**，打开 **结构化开关 > 配置**，即可进入 **JSON Schema 编辑器** 界面。JSON Schema 编辑器分为可视化编辑窗口与代码编辑窗口，两者可无缝切换。
|
||||
|
||||
|
||||
|
||||
***可视化编辑***
|
||||
|
||||
**适用场景**
|
||||
|
||||
- **你只需要定义几个简单的字段**，例如 `name`、`email`、`age` 等，并不涉及嵌套结构。
|
||||
|
||||
- **你不熟悉 JSON Schema 语法**，希望不写代码，而是用直观的界面拖拽、添加字段。
|
||||
|
||||
- **你希望快速迭代字段结构**，而不是每次修改都需要更新 JSON 代码。
|
||||
|
||||
|
||||
|
||||
**添加字段**
|
||||
|
||||
在 **结构化输出** 框中点击 **添加子字段** 按钮，并配置字段参数：
|
||||
|
||||
- *（必填）* **字段名**
|
||||
|
||||
- *（必填）* **字段类型**：支持 string、number、object、array 等字段类型等。
|
||||
|
||||
> 对象（object）或数组（array）字段可添加子字段。
|
||||
|
||||
- **描述**：帮助 LLM 理解字段含义，提高输出准确性。
|
||||
|
||||
- **必填**：开启后，LLM 将强制返回该字段值。
|
||||
|
||||
- **枚举值**：用于限制字段值的可选范围，使模型仅能从预设的枚举值中返回值。例如，若只允许 `red`、`green`、`blue`：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "string",
|
||||
"enum": ["red", "green", "blue"]
|
||||
}
|
||||
```
|
||||
|
||||
> 该规则要求输入值只能是 `red`、`green` 或 `blue`。
|
||||
|
||||
**删改字段**
|
||||
|
||||
- 编辑字段：鼠标悬停至字段卡片，点击 **编辑** 图标，修改字段类型、描述、默认值等参数。
|
||||
|
||||
- 删除字段：鼠标悬停至字段卡片，点击 **删除** 图标，字段将从列表中删除。
|
||||
|
||||
> 删除对象（object）或数组（array）字段时，其所有子字段也会被删除。
|
||||
|
||||
**导入现有 JSON 示例**
|
||||
|
||||
1. 点击 **从 JSON 导入** 按钮，在弹出的对话框中粘贴或上传 JSON 示例，例如：
|
||||
|
||||
```
|
||||
{
|
||||
"comment": "This is great!",
|
||||
"rating": 5
|
||||
}
|
||||
```
|
||||
|
||||
2. 点击 **提交** 按钮，系统会自动解析 JSON 示例，并转换为 JSON Schema 如下：
|
||||
|
||||
|
||||
|
||||
**使用 AI 生成 JSON Schema**
|
||||
|
||||
1. 点击 **AI 生成** 图标，选择模型（如 GPT-4o）。在输入框中描述你的 JSON Schema，例如：
|
||||
|
||||
> “我需要一个包含用户名（string）、年龄（number）和兴趣爱好（array）的 JSON Schema。”
|
||||
|
||||
2. 点击 **生成** ，系统将自动生成 JSON Schema 如下：
|
||||
|
||||
```
|
||||
{
|
||||
"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，但**希望修改某些字段的类型或结构**，使其更符合业务需求。
|
||||
|
||||
|
||||
|
||||
**添加字段**
|
||||
|
||||
1. 进入 JSON Schema 代码编辑器。
|
||||
|
||||
2. 点击 **从 JSON 导入**， 输入字段。例如：
|
||||
|
||||
```
|
||||
{
|
||||
"name": "username",
|
||||
"type": "string",
|
||||
"description": "user's name",
|
||||
"required": true
|
||||
}
|
||||
```
|
||||
|
||||
3. 点击 **保存**，系统会自动校验 JSON Schema 并保存。
|
||||
|
||||
**删改字段**：在 JSON 代码框直接删改字段类型、描述、默认值等参数，并点击 **保存**。
|
||||
|
||||
**导入现有 JSON 示例**
|
||||
|
||||
1. 点击 **从 JSON 导入** 按钮，在弹出的对话框中粘贴或上传 JSON 示例，例如：
|
||||
|
||||
```
|
||||
{
|
||||
"comment": "This is great!",
|
||||
"rating": 5
|
||||
}
|
||||
```
|
||||
|
||||
2. 点击 **提交** 按钮，系统会自动解析 JSON 示例，并转换为 JSON Schema 如下：
|
||||
|
||||
```
|
||||
{
|
||||
"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 如下：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"username": {
|
||||
"type": "string"
|
||||
},
|
||||
"age": {
|
||||
"type": "number"
|
||||
},
|
||||
"interests": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"username",
|
||||
"age",
|
||||
"interests"
|
||||
]
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
***
|
||||
|
||||
### 使用案例
|
||||
@@ -168,5 +381,47 @@ LLM 节点处理信息时有可能会遇到输入文本超过 Token 限制，未
|
||||
|
||||
|
||||
|
||||
* **结构化输出**
|
||||
|
||||
**场景**：你正在使用 Dify 构建一个用户反馈分析工作流。LLM 节点需要读取用户评价，并返回标准化的评分和评论内容，确保数据格式一致，便于后续节点处理。
|
||||
|
||||
**解决方案**：在工作流的 LLM 节点中，使用 **JSON Schema 编辑器** 定义结构化格式。这样能确保 LLM 生成的结果被限制在预设格式中，而非输出杂乱文本。
|
||||
|
||||
**操作步骤**：
|
||||
|
||||
1. 在 **LLM** 节点的 **JSON Schema 编辑器** 中，添加以下字段，确保 LLM 按照规定的结构输出数据：
|
||||
|
||||
```
|
||||
{
|
||||
"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 生成的 **结构化数据** 如下：
|
||||
|
||||
```
|
||||
{
|
||||
"structured_output": {
|
||||
"comment": "这个产品非常棒，使用体验很好！",
|
||||
"rating": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -54,8 +54,6 @@ Dify 工作流内提供了丰富的[工具](https://docs.dify.ai/v/zh-hans/guide
|
||||
|
||||
开启图片
|
||||
|
||||
|
||||
|
||||
**输出变量**
|
||||
|
||||
* 提取定义的变量
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
## 简介
|
||||
|
||||
作为 LLM 工具链平台，Dify 支持 JSON 结构化输出功能。结构化输出功能可以确保 LLM 返回的数据格式可用、稳定、可预测，减少错误处理和格式转换的工作。
|
||||
|
||||
## 价值
|
||||
|
||||
- **确保数据格式一致**：即使由 LLM 生成内容，也必须符合预设格式，避免数据混乱。
|
||||
|
||||
- **方便后续节点处理**：数据库、API 或前端可以直接解析 JSON Schema，而无需额外数据清洗。
|
||||
|
||||
- **提升低代码开发体验**：开发者无需手写复杂数据校验逻辑，直接使用 JSON Schema 约束输出。
|
||||
|
||||
## 如何实现结构化输出？
|
||||
|
||||
在 Dify 的操作界面中，可以通过以下两种方式实现结构化输出：
|
||||
|
||||
- **方式一：直接定义工具参数**
|
||||
|
||||
- **方式二：使用 LLM 节点中的 JSON Schema 编辑器**
|
||||
|
||||
### 方式一：直接定义工具参数
|
||||
|
||||
请参阅 **[如何使用 JSON Schema 让 LLM 输出遵循结构化格式的内容？](https://docs.dify.ai/zh-hans/learn-more/extended-reading/how-to-use-json-schema-in-dify)**。
|
||||
|
||||
### 方式二：使用 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)。
|
||||
Reference in New Issue
Block a user