提示词工程概述
提示词工程是构建高质量AI应用的关键技能。在Dify中，良好的提示词设计可以显著提高应用的准确性和用户体验。
提示词的重要性
# 提示词的重要性
prompt_importance = {
"准确性": "好的提示词提高回答准确性",
"相关性": "确保回答与需求相关",
"格式": "控制输出格式和结构",
"行为": "定义AI的行为和角色"
}
提示词基础
1. 提示词结构
# 提示词基本结构
提示词结构:
系统提示词:
- 定义AI角色
- 设定行为规范
- 说明能力范围
用户提示词:
- 用户输入内容
- 具体问题或任务
上下文:
- 历史对话
- 知识库检索结果
- 外部数据
2. 提示词类型
# 提示词类型
提示词类型:
指令型:
- 明确的任务指令
- 示例: "请总结以下文档内容"
对话型:
- 自然对话形式
- 示例: "你是一个专业的客服，请回答用户问题"
示例型:
- 提供示例引导
- 示例: "以下是正确的格式示例：..."
角色型:
- 定义AI角色
- 示例: "你是一位经验丰富的Python开发专家"
提示词设计
1. 角色定义
# 角色定义示例
角色定义:
专业角色:
示例: "你是一位拥有10年经验的软件架构师"
作用: "让AI以专业身份回答问题"
性格设定:
示例: "你是一个友好、耐心的客服助手"
作用: "控制AI的交流风格"
能力范围:
示例: "你擅长Python、Java和Go语言开发"
作用: "限定AI的回答范围"
2. 任务描述
# 任务描述设计
任务描述:
明确性:
- 清晰描述任务目标
- 避免模糊表达
- 使用具体指令
完整性:
- 包含所有必要信息
- 说明输入输出格式
- 提供约束条件
示例:
好的: "请将以下JSON数据转换为Markdown表格格式"
差的: "处理这个数据"
3. 输出格式
# 输出格式控制
格式控制:
结构化输出:
- 使用JSON格式
- 使用Markdown格式
- 使用列表格式
格式示例:
示例: |
请按以下格式输出：
- 标题: [标题]
- 摘要: [摘要]
- 要点: [要点列表]
上下文管理
1. 上下文构建
# 上下文构建策略
上下文策略:
知识库上下文:
- 从知识库检索相关内容
- 按相关性排序
- 限制上下文长度
对话历史:
- 保留最近N轮对话
- 重要信息持久化
- 上下文压缩
外部数据:
- 集成外部API数据
- 实时数据更新
- 数据验证
2. 上下文优化
# 上下文优化方法
优化方法:
相关性过滤:
- 只包含相关内容
- 过滤无关信息
- 提高上下文质量
长度控制:
- 限制上下文长度
- 优先保留重要信息
- 使用摘要技术
结构优化:
- 清晰的上下文结构
- 使用分隔符
- 标注信息来源
变量使用
1. 变量引用
# 变量引用语法
变量引用:
基本变量: ""
对象属性: ""
数组元素: ""
条件变量: "默认值"
2. 变量示例
# 提示词中的变量使用
提示词示例: |
你是一位，擅长。
用户问题：
相关知识：
- <article class="post-container post-container--single" itemscope itemtype="http://schema.org/BlogPosting">
<header class="post-header">
<h1 class="post-title">Dify API使用指南</h1>
<div class="post-meta">
<img src="/images/calendar.png" width="20px"/>
<time datetime="2025-06-25 00:00:00 +0000" itemprop="datePublished" class="post-meta__date date">2025-06-25</time>
<span id="busuanzi_container_page_pv"> | 阅读：<span id="busuanzi_value_page_pv"></span>次</span>
</p>
</div>
</header>
<section class="post">
<h2 id="api概述">API概述</h2>
<p>Dify提供了完整的RESTful API接口，允许开发者通过编程方式集成Dify功能到自己的应用中。API支持对话、工作流、知识库等所有核心功能。</p>
<h3 id="api特点">API特点</h3>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># API特点
</span><span class="n">api_features</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"RESTful设计"</span><span class="p">:</span> <span class="s">"标准的REST API设计"</span><span class="p">,</span>
<span class="s">"完整功能"</span><span class="p">:</span> <span class="s">"覆盖所有平台功能"</span><span class="p">,</span>
<span class="s">"多语言SDK"</span><span class="p">:</span> <span class="s">"提供Python、JavaScript等SDK"</span><span class="p">,</span>
<span class="s">"文档完善"</span><span class="p">:</span> <span class="s">"详细的API文档和示例"</span><span class="p">,</span>
<span class="s">"认证安全"</span><span class="p">:</span> <span class="s">"支持API Key认证"</span>
<span class="p">}</span>
</code></pre></div></div>
<h2 id="api认证">API认证</h2>
<h3 id="1-api-key获取">1. API Key获取</h3>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># API Key获取</span>
<span class="na">获取方式</span><span class="pi">:</span>
<span class="na">1</span><span class="pi">:</span> <span class="s2">"</span><span class="s">登录Dify控制台"</span>
<span class="na">2</span><span class="pi">:</span> <span class="s2">"</span><span class="s">进入应用设置"</span>
<span class="na">3</span><span class="pi">:</span> <span class="s2">"</span><span class="s">找到API设置"</span>
<span class="na">4</span><span class="pi">:</span> <span class="s2">"</span><span class="s">生成API</span><span class="nv"> </span><span class="s">Key"</span>
<span class="na">5</span><span class="pi">:</span> <span class="s2">"</span><span class="s">保存API</span><span class="nv"> </span><span class="s">Key（只显示一次）"</span>
<span class="na">API Key类型</span><span class="pi">:</span>
<span class="na">应用API Key</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">绑定到特定应用</span>
<span class="pi">-</span> <span class="s">只能访问该应用</span>
<span class="pi">-</span> <span class="s">推荐使用</span>
<span class="na">全局API Key</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">可以访问所有应用</span>
<span class="pi">-</span> <span class="s">权限更高</span>
<span class="pi">-</span> <span class="s">谨慎使用</span>
</code></pre></div></div>
<h3 id="2-认证方式">2. 认证方式</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># API认证方式</span>
<span class="c"># 方式1：Header认证（推荐）</span>
curl <span class="nt">-X</span> POST <span class="s2">"https://api.dify.ai/v1/chat-messages"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer YOUR_API_KEY"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-d</span> <span class="s1">'{
"inputs": {},
"query": "Hello",
"response_mode": "blocking",
"conversation_id": "",
"user": "user-1234"
}'</span>
<span class="c"># 方式2：Query参数（不推荐，安全性较低）</span>
curl <span class="nt">-X</span> POST <span class="s2">"https://api.dify.ai/v1/chat-messages?authorization=YOUR_API_KEY"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-d</span> <span class="s1">'{...}'</span>
</code></pre></div></div>
<h2 id="对话api">对话API</h2>
<h3 id="1-发送消息">1. 发送消息</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 发送对话消息</span>
POST /v1/chat-messages
<span class="c"># 请求示例</span>
curl <span class="nt">-X</span> POST <span class="s2">"https://api.dify.ai/v1/chat-messages"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer YOUR_API_KEY"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-d</span> <span class="s1">'{
"inputs": {
"variable1": "value1"
},
"query": "用户的问题",
"response_mode": "blocking",
"conversation_id": "",
"user": "user-1234"
}'</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"event"</span>: <span class="s2">"message"</span>,
<span class="s2">"task_id"</span>: <span class="s2">"task-1234"</span>,
<span class="s2">"id"</span>: <span class="s2">"msg-1234"</span>,
<span class="s2">"message_id"</span>: <span class="s2">"msg-1234"</span>,
<span class="s2">"conversation_id"</span>: <span class="s2">"conv-1234"</span>,
<span class="s2">"answer"</span>: <span class="s2">"AI的回答内容"</span>,
<span class="s2">"created_at"</span>: 1234567890
<span class="o">}</span>
</code></pre></div></div>
<h3 id="2-流式响应">2. 流式响应</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 流式响应（SSE）</span>
POST /v1/chat-messages
<span class="c"># 请求参数</span>
<span class="o">{</span>
<span class="s2">"response_mode"</span>: <span class="s2">"streaming"</span>, <span class="c"># 设置为streaming</span>
<span class="s2">"query"</span>: <span class="s2">"用户问题"</span>,
<span class="s2">"conversation_id"</span>: <span class="s2">"conv-1234"</span>,
<span class="s2">"user"</span>: <span class="s2">"user-1234"</span>
<span class="o">}</span>
<span class="c"># 响应格式（SSE）</span>
event: message
data: <span class="o">{</span><span class="s2">"event"</span>: <span class="s2">"message"</span>, <span class="s2">"id"</span>: <span class="s2">"msg-1"</span>, <span class="s2">"answer"</span>: <span class="s2">"部分回答"</span><span class="o">}</span>
event: message_end
data: <span class="o">{</span><span class="s2">"event"</span>: <span class="s2">"message_end"</span>, <span class="s2">"id"</span>: <span class="s2">"msg-1"</span>, <span class="s2">"answer"</span>: <span class="s2">"完整回答"</span><span class="o">}</span>
</code></pre></div></div>
<h3 id="3-python-sdk示例">3. Python SDK示例</h3>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Python SDK使用示例
</span><span class="kn">from</span> <span class="nn">dify_client</span> <span class="kn">import</span> <span class="n">ChatClient</span>
<span class="c1"># 初始化客户端
</span><span class="n">client</span> <span class="o">=</span> <span class="n">ChatClient</span><span class="p">(</span>
<span class="n">api_key</span><span class="o">=</span><span class="s">"YOUR_API_KEY"</span><span class="p">,</span>
<span class="n">base_url</span><span class="o">=</span><span class="s">"https://api.dify.ai"</span>
<span class="p">)</span>
<span class="c1"># 发送消息（阻塞模式）
</span><span class="n">response</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">create_message</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="s">"用户问题"</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"blocking"</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">"user-1234"</span>
<span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">response</span><span class="p">.</span><span class="n">answer</span><span class="p">)</span>
<span class="c1"># 发送消息（流式模式）
</span><span class="k">for</span> <span class="n">chunk</span> <span class="ow">in</span> <span class="n">client</span><span class="p">.</span><span class="n">create_message_stream</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="s">"用户问题"</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"streaming"</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">"user-1234"</span>
<span class="p">):</span>
<span class="k">if</span> <span class="n">chunk</span><span class="p">.</span><span class="n">event</span> <span class="o">==</span> <span class="s">"message"</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">chunk</span><span class="p">.</span><span class="n">answer</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s">""</span><span class="p">,</span> <span class="n">flush</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</code></pre></div></div>
<h2 id="工作流api">工作流API</h2>
<h3 id="1-运行工作流">1. 运行工作流</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 运行工作流</span>
POST /v1/workflows/run
<span class="c"># 请求示例</span>
curl <span class="nt">-X</span> POST <span class="s2">"https://api.dify.ai/v1/workflows/run"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer YOUR_API_KEY"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-d</span> <span class="s1">'{
"inputs": {
"input_variable": "value"
},
"response_mode": "blocking",
"user": "user-1234"
}'</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"task_id"</span>: <span class="s2">"task-1234"</span>,
<span class="s2">"workflow_run_id"</span>: <span class="s2">"run-1234"</span>,
<span class="s2">"data"</span>: <span class="o">{</span>
<span class="s2">"output_variable"</span>: <span class="s2">"result_value"</span>
<span class="o">}</span>,
<span class="s2">"created_at"</span>: 1234567890
<span class="o">}</span>
</code></pre></div></div>
<h3 id="2-工作流状态查询">2. 工作流状态查询</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 查询工作流运行状态</span>
GET /v1/workflows/runs/<span class="o">{</span>workflow_run_id<span class="o">}</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"id"</span>: <span class="s2">"run-1234"</span>,
<span class="s2">"status"</span>: <span class="s2">"succeeded"</span>,
<span class="s2">"inputs"</span>: <span class="o">{</span>...<span class="o">}</span>,
<span class="s2">"outputs"</span>: <span class="o">{</span>...<span class="o">}</span>,
<span class="s2">"created_at"</span>: 1234567890,
<span class="s2">"finished_at"</span>: 1234567891
<span class="o">}</span>
</code></pre></div></div>
<h2 id="知识库api">知识库API</h2>
<h3 id="1-上传文档">1. 上传文档</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 上传文档到知识库</span>
POST /v1/datasets/<span class="o">{</span>dataset_id<span class="o">}</span>/documents
<span class="c"># 请求示例（multipart/form-data）</span>
curl <span class="nt">-X</span> POST <span class="s2">"https://api.dify.ai/v1/datasets/{dataset_id}/documents"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer YOUR_API_KEY"</span> <span class="se">\</span>
<span class="nt">-F</span> <span class="s2">"data=@document.pdf"</span> <span class="se">\</span>
<span class="nt">-F</span> <span class="s2">"indexing_technique=high_quality"</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"document"</span>: <span class="o">{</span>
<span class="s2">"id"</span>: <span class="s2">"doc-1234"</span>,
<span class="s2">"name"</span>: <span class="s2">"document.pdf"</span>,
<span class="s2">"data_source_type"</span>: <span class="s2">"upload_file"</span>,
<span class="s2">"indexing_status"</span>: <span class="s2">"parsing"</span>,
<span class="s2">"created_at"</span>: 1234567890
<span class="o">}</span>
<span class="o">}</span>
</code></pre></div></div>
<h3 id="2-查询文档状态">2. 查询文档状态</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 查询文档索引状态</span>
GET /v1/datasets/<span class="o">{</span>dataset_id<span class="o">}</span>/documents/<span class="o">{</span>document_id<span class="o">}</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"id"</span>: <span class="s2">"doc-1234"</span>,
<span class="s2">"name"</span>: <span class="s2">"document.pdf"</span>,
<span class="s2">"indexing_status"</span>: <span class="s2">"completed"</span>,
<span class="s2">"indexing_progress"</span>: 100,
<span class="s2">"created_at"</span>: 1234567890
<span class="o">}</span>
</code></pre></div></div>
<h3 id="3-删除文档">3. 删除文档</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 删除文档</span>
DELETE /v1/datasets/<span class="o">{</span>dataset_id<span class="o">}</span>/documents/<span class="o">{</span>document_id<span class="o">}</span>
<span class="c"># 响应</span>
<span class="o">{</span>
<span class="s2">"result"</span>: <span class="s2">"success"</span>
<span class="o">}</span>
</code></pre></div></div>
<h2 id="应用管理api">应用管理API</h2>
<h3 id="1-获取应用信息">1. 获取应用信息</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 获取应用信息</span>
GET /v1/apps/<span class="o">{</span>app_id<span class="o">}</span>
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"app"</span>: <span class="o">{</span>
<span class="s2">"id"</span>: <span class="s2">"app-1234"</span>,
<span class="s2">"name"</span>: <span class="s2">"我的应用"</span>,
<span class="s2">"mode"</span>: <span class="s2">"chat"</span>,
<span class="s2">"icon"</span>: <span class="s2">"icon-url"</span>,
<span class="s2">"icon_background"</span>: <span class="s2">"#FFFFFF"</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre></div></div>
<h3 id="2-获取对话历史">2. 获取对话历史</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 获取对话历史</span>
GET /v1/messages?conversation_id<span class="o">={</span>conversation_id<span class="o">}</span>&limit<span class="o">=</span>20
<span class="c"># 响应示例</span>
<span class="o">{</span>
<span class="s2">"data"</span>: <span class="o">[</span>
<span class="o">{</span>
<span class="s2">"id"</span>: <span class="s2">"msg-1"</span>,
<span class="s2">"conversation_id"</span>: <span class="s2">"conv-1234"</span>,
<span class="s2">"inputs"</span>: <span class="o">{}</span>,
<span class="s2">"query"</span>: <span class="s2">"用户问题"</span>,
<span class="s2">"answer"</span>: <span class="s2">"AI回答"</span>,
<span class="s2">"created_at"</span>: 1234567890
<span class="o">}</span>
<span class="o">]</span>,
<span class="s2">"has_more"</span>: <span class="nb">false</span>
<span class="o">}</span>
</code></pre></div></div>
<h2 id="sdk使用">SDK使用</h2>
<h3 id="1-python-sdk">1. Python SDK</h3>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 安装SDK
# pip install dify-client
</span>
<span class="kn">from</span> <span class="nn">dify_client</span> <span class="kn">import</span> <span class="n">ChatClient</span><span class="p">,</span> <span class="n">CompletionClient</span>
<span class="c1"># 对话客户端
</span><span class="n">chat_client</span> <span class="o">=</span> <span class="n">ChatClient</span><span class="p">(</span>
<span class="n">api_key</span><span class="o">=</span><span class="s">"YOUR_API_KEY"</span><span class="p">,</span>
<span class="n">base_url</span><span class="o">=</span><span class="s">"https://api.dify.ai"</span>
<span class="p">)</span>
<span class="c1"># 发送消息
</span><span class="n">response</span> <span class="o">=</span> <span class="n">chat_client</span><span class="p">.</span><span class="n">create_message</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="s">"Hello"</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"blocking"</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">"user-1234"</span>
<span class="p">)</span>
<span class="c1"># 完成客户端（文本补全）
</span><span class="n">completion_client</span> <span class="o">=</span> <span class="n">CompletionClient</span><span class="p">(</span>
<span class="n">api_key</span><span class="o">=</span><span class="s">"YOUR_API_KEY"</span><span class="p">,</span>
<span class="n">base_url</span><span class="o">=</span><span class="s">"https://api.dify.ai"</span>
<span class="p">)</span>
<span class="n">response</span> <span class="o">=</span> <span class="n">completion_client</span><span class="p">.</span><span class="n">create</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="s">"Complete this:"</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"blocking"</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">"user-1234"</span>
<span class="p">)</span>
</code></pre></div></div>
<h3 id="2-javascript-sdk">2. JavaScript SDK</h3>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 安装SDK</span>
<span class="c1">// npm install @difyai/dify-client</span>
<span class="k">import</span> <span class="p">{</span> <span class="nx">ChatClient</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@difyai/dify-client</span><span class="dl">'</span><span class="p">;</span>
<span class="c1">// 创建客户端</span>
<span class="kd">const</span> <span class="nx">client</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">ChatClient</span><span class="p">({</span>
<span class="na">apiKey</span><span class="p">:</span> <span class="dl">'</span><span class="s1">YOUR_API_KEY</span><span class="dl">'</span><span class="p">,</span>
<span class="na">baseUrl</span><span class="p">:</span> <span class="dl">'</span><span class="s1">https://api.dify.ai</span><span class="dl">'</span>
<span class="p">});</span>
<span class="c1">// 发送消息</span>
<span class="kd">const</span> <span class="nx">response</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">client</span><span class="p">.</span><span class="nx">createMessage</span><span class="p">({</span>
<span class="na">inputs</span><span class="p">:</span> <span class="p">{},</span>
<span class="na">query</span><span class="p">:</span> <span class="dl">'</span><span class="s1">Hello</span><span class="dl">'</span><span class="p">,</span>
<span class="na">responseMode</span><span class="p">:</span> <span class="dl">'</span><span class="s1">blocking</span><span class="dl">'</span><span class="p">,</span>
<span class="na">user</span><span class="p">:</span> <span class="dl">'</span><span class="s1">user-1234</span><span class="dl">'</span>
<span class="p">});</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">response</span><span class="p">.</span><span class="nx">answer</span><span class="p">);</span>
</code></pre></div></div>
<h2 id="错误处理">错误处理</h2>
<h3 id="1-错误码">1. 错误码</h3>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 常见错误码</span>
<span class="na">错误码</span><span class="pi">:</span>
<span class="na">400</span><span class="pi">:</span> <span class="s2">"</span><span class="s">请求参数错误"</span>
<span class="na">401</span><span class="pi">:</span> <span class="s2">"</span><span class="s">认证失败"</span>
<span class="na">403</span><span class="pi">:</span> <span class="s2">"</span><span class="s">权限不足"</span>
<span class="na">404</span><span class="pi">:</span> <span class="s2">"</span><span class="s">资源不存在"</span>
<span class="na">429</span><span class="pi">:</span> <span class="s2">"</span><span class="s">请求频率过高"</span>
<span class="na">500</span><span class="pi">:</span> <span class="s2">"</span><span class="s">服务器内部错误"</span>
</code></pre></div></div>
<h3 id="2-错误处理示例">2. 错误处理示例</h3>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Python错误处理
</span><span class="kn">from</span> <span class="nn">dify_client</span> <span class="kn">import</span> <span class="n">ChatClient</span>
<span class="kn">from</span> <span class="nn">dify_client.errors</span> <span class="kn">import</span> <span class="n">APIError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">ChatClient</span><span class="p">(</span><span class="n">api_key</span><span class="o">=</span><span class="s">"YOUR_API_KEY"</span><span class="p">)</span>
<span class="n">response</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">create_message</span><span class="p">(</span>
<span class="n">query</span><span class="o">=</span><span class="s">"Hello"</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"blocking"</span>
<span class="p">)</span>
<span class="k">except</span> <span class="n">APIError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="k">if</span> <span class="n">e</span><span class="p">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">401</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="s">"API Key无效"</span><span class="p">)</span>
<span class="k">elif</span> <span class="n">e</span><span class="p">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">429</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="s">"请求频率过高，请稍后重试"</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="sa">f</span><span class="s">"错误: </span><span class="si">{</span><span class="n">e</span><span class="p">.</span><span class="n">message</span><span class="si">}</span><span class="s">"</span><span class="p">)</span>
</code></pre></div></div>
<h2 id="最佳实践">最佳实践</h2>
<h3 id="1-api使用建议">1. API使用建议</h3>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># API使用建议</span>
<span class="na">使用建议</span><span class="pi">:</span>
<span class="na">认证安全</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">妥善保管API Key</span>
<span class="pi">-</span> <span class="s">不要在客户端暴露API Key</span>
<span class="pi">-</span> <span class="s">定期轮换API Key</span>
<span class="na">错误处理</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">实现完善的错误处理</span>
<span class="pi">-</span> <span class="s">处理网络异常</span>
<span class="pi">-</span> <span class="s">实现重试机制</span>
<span class="na">性能优化</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">使用流式响应提高体验</span>
<span class="pi">-</span> <span class="s">合理设置超时时间</span>
<span class="pi">-</span> <span class="s">使用连接池</span>
</code></pre></div></div>
<h3 id="2-集成示例">2. 集成示例</h3>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 完整集成示例
</span><span class="kn">from</span> <span class="nn">dify_client</span> <span class="kn">import</span> <span class="n">ChatClient</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="k">class</span> <span class="nc">DifyIntegration</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">api_key</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="s">"https://api.dify.ai"</span><span class="p">):</span>
<span class="bp">self</span><span class="p">.</span><span class="n">client</span> <span class="o">=</span> <span class="n">ChatClient</span><span class="p">(</span>
<span class="n">api_key</span><span class="o">=</span><span class="n">api_key</span><span class="p">,</span>
<span class="n">base_url</span><span class="o">=</span><span class="n">base_url</span>
<span class="p">)</span>
<span class="k">def</span> <span class="nf">chat</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">,</span> <span class="n">conversation_id</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="s">"""发送聊天消息"""</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">response</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">create_message</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="n">query</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"blocking"</span><span class="p">,</span>
<span class="n">conversation_id</span><span class="o">=</span><span class="n">conversation_id</span> <span class="ow">or</span> <span class="s">""</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="n">user_id</span> <span class="ow">or</span> <span class="sa">f</span><span class="s">"user-</span><span class="si">{</span><span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="p">.</span><span class="n">time</span><span class="p">())</span><span class="si">}</span><span class="s">"</span>
<span class="p">)</span>
<span class="k">return</span> <span class="p">{</span>
<span class="s">"success"</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
<span class="s">"answer"</span><span class="p">:</span> <span class="n">response</span><span class="p">.</span><span class="n">answer</span><span class="p">,</span>
<span class="s">"conversation_id"</span><span class="p">:</span> <span class="n">response</span><span class="p">.</span><span class="n">conversation_id</span>
<span class="p">}</span>
<span class="k">except</span> <span class="nb">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="k">return</span> <span class="p">{</span>
<span class="s">"success"</span><span class="p">:</span> <span class="bp">False</span><span class="p">,</span>
<span class="s">"error"</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
<span class="p">}</span>
<span class="k">def</span> <span class="nf">chat_stream</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">,</span> <span class="n">conversation_id</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="s">"""流式聊天"""</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">for</span> <span class="n">chunk</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">create_message_stream</span><span class="p">(</span>
<span class="n">inputs</span><span class="o">=</span><span class="p">{},</span>
<span class="n">query</span><span class="o">=</span><span class="n">query</span><span class="p">,</span>
<span class="n">response_mode</span><span class="o">=</span><span class="s">"streaming"</span><span class="p">,</span>
<span class="n">conversation_id</span><span class="o">=</span><span class="n">conversation_id</span> <span class="ow">or</span> <span class="s">""</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="n">user_id</span> <span class="ow">or</span> <span class="sa">f</span><span class="s">"user-</span><span class="si">{</span><span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="p">.</span><span class="n">time</span><span class="p">())</span><span class="si">}</span><span class="s">"</span>
<span class="p">):</span>
<span class="k">if</span> <span class="n">chunk</span><span class="p">.</span><span class="n">event</span> <span class="o">==</span> <span class="s">"message"</span><span class="p">:</span>
<span class="k">yield</span> <span class="n">chunk</span><span class="p">.</span><span class="n">answer</span>
<span class="k">except</span> <span class="nb">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="k">yield</span> <span class="sa">f</span><span class="s">"错误: </span><span class="si">{</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">)</span><span class="si">}</span><span class="s">"</span>
<span class="c1"># 使用示例
</span><span class="n">dify</span> <span class="o">=</span> <span class="n">DifyIntegration</span><span class="p">(</span><span class="n">api_key</span><span class="o">=</span><span class="s">"YOUR_API_KEY"</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">dify</span><span class="p">.</span><span class="n">chat</span><span class="p">(</span><span class="s">"Hello, Dify!"</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">result</span><span class="p">[</span><span class="s">"answer"</span><span class="p">])</span>
</code></pre></div></div>
<h2 id="总结">总结</h2>
<p>Dify API使用指南的关键要点：</p>
<ol>
<li><strong>API概述</strong>：RESTful API、完整功能、多语言SDK</li>
<li><strong>API认证</strong>：API Key获取、认证方式</li>
<li><strong>对话API</strong>：发送消息、流式响应、SDK示例</li>
<li><strong>工作流API</strong>：运行工作流、状态查询</li>
<li><strong>知识库API</strong>：上传文档、查询状态、删除文档</li>
<li><strong>应用管理API</strong>：获取应用信息、对话历史</li>
<li><strong>SDK使用</strong>：Python SDK、JavaScript SDK</li>
<li><strong>错误处理</strong>：错误码、错误处理示例</li>
<li><strong>最佳实践</strong>：使用建议、集成示例</li>
</ol>
<p>掌握API使用，可以将Dify功能集成到自己的应用中，实现灵活的AI能力集成。</p>
<p>转载请注明：<a href="http://zhouzhiyang.cn">周志洋的博客</a> » <a href="http://zhouzhiyang.cn/2025/06/Dify_API_Usage/">Dify API使用指南</a></p>
</section>
</article>
<section>
<div class="content-play">
<p><a href="javascript:void(0)" onclick="dashangToggle()" class="dashang" title="打赏，支持一下">打赏一个呗</a></p>
<div class="hide_box-play"></div>
<div class="shang_box-play">
<a class="shang_close-play" href="javascript:void(0)" onclick="dashangToggle()" title="关闭"><img src="/images/payimg/close.jpg" alt="取消" /></a>
<div class="shang_tit-play">
<p>感谢您的支持，我会继续努力的!</p>
</div>
<div class="shang_payimg">
<img src="/images/payimg/alipayimg.jpg" alt="扫码支持" title="扫一扫" />
</div>
<div class="shang_payimg">
<img src="/images/payimg/weipayimg.jpg" alt="扫码支持" title="扫一扫" />
</div>
<div class="pay_explain">扫码打赏，你说多少就多少</div>
<div class="shang_payselect">
<div class="pay_item checked" data-id="alipay">
<span class="pay_logo"><img src="/images/payimg/alipay.jpg" alt="支付宝" /></span>
</div>
<div class="pay_item" data-id="weipay">
<span class="pay_logo"><img src="/images/payimg/wechat.jpg" alt="微信" /></span>
</div>
</div>
<div class="shang_info-play">
<p>打开<span id="shang_pay_txt">支付宝</span>扫一扫，即可进行扫码打赏哦</p>
</div>
</div>
</div>
<script type="text/javascript">
function dashangToggle(){
$(".hide_box-play").fadeToggle();
$(".shang_box-play").fadeToggle();
}
</script>
<div style="text-align:center;margin:50px 0; font:normal 14px/24px 'MicroSoft YaHei';"></div>
<style type="text/css">
.content-play{width:80%;margin-top: 20px;margin-bottom: 10px;height:40px;}
.hide_box-play{z-index:999;filter:alpha(opacity=50);background:#666;opacity: 0.5;-moz-opacity: 0.5;left:0;top:0;height:99%;width:100%;position:fixed;display:none;}
.shang_box-play{width:540px;height:540px;padding:10px;background-color:#fff;border-radius:10px;position:fixed;z-index:1000;left:50%;top:50%;margin-left:-280px;margin-top:-280px;border:1px dotted #dedede;display:none;}
.shang_box-play img{border:none;border-width:0;}
.dashang{display:block;width:100px;margin:5px auto;height:25px;line-height:25px;padding:10px;background-color:#E74851;color:#fff;text-align:center;text-decoration:none;border-radius:10px;font-weight:bold;font-size:16px;transition: all 0.3s;}
.dashang:hover{opacity:0.8;padding:15px;font-size:18px;}
.shang_close-play{float:right;display:inline-block;
margin-right: 10px;margin-top: 20px;
}
.shang_logo{display:block;text-align:center;margin:20px auto;}
.shang_tit-play{width: 100%;height: 75px;text-align: center;line-height: 66px;color: #a3a3a3;font-size: 16px;background: url('/images/payimg/cy-reward-title-bg.jpg');font-family: 'Microsoft YaHei';margin-top: 7px;margin-right:2px;}
.shang_tit-play p{color:#a3a3a3;text-align:center;font-size:16px;}
.shang_payimg{width:140px;padding:10px;padding-left: 80px; /*border:6px solid #EA5F00;**/margin:0 auto;border-radius:3px;height:140px;display:inline-block;}
.shang_payimg img{display:inline-block;margin-right:10px;float:left;text-align:center;width:140px;height:140px; }
.pay_explain{text-align:center;margin:10px auto;font-size:12px;color:#545454;}
.shang_payselect{text-align:center;margin:0 auto;margin-top:40px;cursor:pointer;height:60px;width:500px;margin-left:110px;}
.shang_payselect .pay_item{display:inline-block;margin-right:140px;float:left;}
.shang_info-play{clear:both;}
.shang_info-play p,.shang_info-play a{color:#C3C3C3;text-align:center;font-size:12px;text-decoration:none;line-height:2em;}
</style>
<ul class="pager">
<li class="previous">
<a href="/2025/06/Dify_Application_Development/" data-toggle="tooltip" data-placement="top" title="Dify应用开发基础">上一篇： <span>Dify应用开发基础</span>
</a>
</li>
<li class="next">
<a href="/2025/06/Dify_Prompt_Engineering/" data-toggle="tooltip" data-placement="top" title="Dify提示词工程">下一篇： <span>Dify提示词工程</span>
</a>
</li>
</ul>
</section>
<section class="post-comments">
<div id="disqus_thread"></div>
<script>
var disqus_config = function () {
this.page.url = "http://zhouzhiyang.cn/2025/06/Dify_API_Usage/";
this.page.identifier = "/2025/06/Dify_API_Usage/";
};
var disqus_shortname = 'zhouzhiyang';
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = '//' + disqus_shortname + '.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>要查看<a href="http://disqus.com/?ref_noscript"> Disqus </a>评论，请启用 JavaScript</noscript>
</section>
请基于以上信息回答用户问题。
提示词优化技巧
1. 清晰度优化
# 清晰度优化
优化技巧:
使用明确指令:
- "请列出"而不是"可以列出"
- "必须包含"而不是"最好包含"
避免歧义:
- 使用具体术语
- 避免模糊表达
- 提供示例说明
结构化表达:
- 使用列表
- 使用标题
- 使用分隔符
2. 准确性优化
# 准确性优化
优化技巧:
提供约束:
- 明确回答范围
- 设置回答限制
- 指定信息来源
错误预防:
- 说明常见错误
- 提供正确示例
- 设置验证规则
质量控制:
- 要求引用来源
- 要求验证信息
- 要求说明不确定性
3. 效率优化
# 效率优化
优化技巧:
精简提示词:
- 去除冗余内容
- 合并相似指令
- 使用简洁表达
优先级明确:
- 重要信息前置
- 使用强调标记
- 分层组织信息
Token优化:
- 减少不必要的上下文
- 使用摘要代替全文
- 优化变量使用
常见场景提示词
1. 问答场景
# 问答场景提示词
提示词模板: |
你是一位专业的专家。
基于以下知识库内容回答用户问题：
用户问题：
要求：
1. 基于知识库内容回答，不要编造信息
2. 如果知识库中没有相关信息，请明确说明
3. 回答要准确、简洁、易懂
4. 如果问题涉及多个方面，请分点回答
2. 内容生成场景
# 内容生成场景提示词
提示词模板: |
你是一位专业的写作专家。
请根据以下要求生成内容：
- 主题：
- 长度：字
- 风格：
- 目标受众：
要求：
1. 内容要有逻辑性和可读性
2. 符合指定的风格和长度
3. 适合目标受众阅读
4. 使用Markdown格式输出
3. 代码生成场景
# 代码生成场景提示词
提示词模板: |
你是一位经验丰富的开发专家。
请根据以下要求生成代码：
- 编程语言：
- 功能需求：
- 代码风格：
要求：
1. 代码要符合最佳实践
2. 添加必要的注释
3. 处理异常情况
4. 代码要可运行和可测试
4. 数据分析场景
# 数据分析场景提示词
提示词模板: |
你是一位数据分析专家。
请分析以下数据：
分析要求：
1. 识别数据中的关键趋势
2. 发现异常值和模式
3. 提供数据洞察
4. 给出建议和结论
输出格式：
- 数据概览
- 关键发现
- 趋势分析
- 建议措施
提示词测试与优化
1. A/B测试
# A/B测试方法
测试方法:
版本对比:
- 创建多个提示词版本
- 使用相同测试用例
- 对比输出质量
评估指标:
- 准确性
- 相关性
- 完整性
- 用户满意度
迭代优化:
- 基于测试结果优化
- 持续改进提示词
- 记录最佳实践
2. 提示词优化流程
# 优化流程
优化流程:
1: "分析当前提示词问题"
2: "设计优化方案"
3: "创建新版本提示词"
4: "进行测试对比"
5: "评估优化效果"
6: "应用最佳版本"
7: "持续监控和改进"
最佳实践
1. 提示词设计原则
# 设计原则
设计原则:
明确性: "指令清晰明确"
完整性: "包含所有必要信息"
结构化: "使用结构化格式"
可测试: "易于测试和验证"
可维护: "易于理解和修改"
2. 常见错误避免
# 常见错误
错误类型:
过于模糊: "请处理这个"
信息不足: "生成内容"
格式混乱: "没有结构"
缺乏约束: "没有限制条件"
正确做法:
- 使用具体指令
- 提供完整信息
- 结构化表达
- 设置明确约束
总结
Dify提示词工程的关键要点：
- 提示词基础：提示词结构、提示词类型
- 提示词设计：角色定义、任务描述、输出格式
- 上下文管理：上下文构建、上下文优化
- 变量使用：变量引用、变量示例
- 优化技巧：清晰度、准确性、效率优化
- 常见场景：问答、内容生成、代码生成、数据分析
- 测试优化：A/B测试、优化流程
- 最佳实践：设计原则、错误避免
掌握提示词工程，可以显著提高AI应用的质量和用户体验。
