Dify AI Ӧ�ÿ��Ŀ

Dify API 集成指南

西安云美电子科技有限公司 - 企业知识库版本：v1.0 | 创建时间：2026-06-06

1. 概述

Dify 提供完整的 RESTful API，支持将知识库对话能力集成到企业微信、钉钉、自建系统等渠道。本文档涵盖最常用的 API 接口及集成示例。

Base URL: http://<dify-host>/v1

2. 认证方式

所有 API 请求需在 Header 中携带 API Key：

Authorization: Bearer app-<your-api-key>

获取 API Key：Dify 控制台 → 应用 → API 访问 → 创建 API Key

3. 对话接口

3.1 发送对话消息

POST /v1/chat-messages

请求参数

参数	类型	必填	说明
query	string	✅	用户输入的问题
inputs	object	❌	额外输入参数
response_mode	string	✅	`blocking`（阻塞）或 `streaming`（流式）
conversation_id	string	❌	对话 ID，首次对话不传，后续传入上一次返回的 ID
user	string	✅	用户标识
files	array	❌	上传文件列表

阻塞模式请求示例

curl -X POST 'http://<dify-host>/v1/chat-messages' \
  -H 'Authorization: Bearer app-<api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "差旅报销标准是什么？",
    "inputs": {},
    "response_mode": "blocking",
    "user": "zhangsan"
  }'

阻塞模式响应

{
  "task_id": "xxx",
  "message_id": "xxx",
  "conversation_id": "xxx",
  "answer": "根据《差旅管理制度》第三章：\n\n1. 住宿标准：一线城市 500 元/晚...\n2. 交通标准：高铁二等座...",
  "created_at": 1717632000
}

流式模式响应（SSE）

data: {"event": "message", "message_id": "xxx", "conversation_id": "xxx", "answer": "根据", ...}
data: {"event": "message", "message_id": "xxx", "conversation_id": "xxx", "answer": "根据《", ...}
data: {"event": "message_end", ...}

3.2 获取对话历史

GET /v1/messages?conversation_id=<id>&user=<user>

响应

{
  "limit": 20,
  "has_more": false,
  "data": [
    {
      "id": "xxx",
      "query": "差旅报销标准",
      "answer": "根据《差旅管理制度》...",
      "created_at": 1717632000
    }
  ]
}

3.3 获取对话列表

GET /v1/conversations?user=<user>&last_id=<id>&limit=20&sort_by=-updated_at

3.4 重命名对话

PATCH /v1/conversations/<conversation_id>/name

{
  "name": "报销相关问题"
}

3.5 删除对话

DELETE /v1/conversations/<conversation_id>

4. 知识库管理接口

4.1 创建知识库

POST /v1/datasets

{
  "name": "KB-RULE-制度流程",
  "description": "公司各类管理制度和审批流程文档"
}

4.2 获取知识库列表

GET /v1/datasets?page=1&page_size=20

4.3 上传文档到知识库

步骤一：创建上传任务

POST /v1/datasets/<dataset_id>/document/create-by-file
Content-Type: multipart/form-data

参数	类型	必填	说明
file	file	✅	文档文件（PDF/Word/TXT/Markdown/Excel）
indexing_technique	string	✅	`high_quality`（高质量）或 `economy`（经济）
process_rule	object	❌	分段规则

分段规则示例

{
  "mode": "automatic",
  "rules": {
    "pre_processing_rules": [
      {"id": "remove_extra_spaces", "enabled": true},
      {"id": "remove_urls_emails", "enabled": false}
    ],
    "segmentation": {
      "max_segmentation_tokens_length": 500,
      "overlap_tokens_length": 50,
      "separator": ["\n", "\n\n", "。", "！", "？", "；"]
    }
  }
}

步骤二：查询上传进度

GET /v1/datasets/<dataset_id>/documents/<document_id>/indexing-status

4.4 通过文本创建文档

POST /v1/datasets/<dataset_id>/document/create-by-text

{
  "name": "报销流程说明",
  "text": "## 报销流程\n\n1. 填写报销单...\n2. 部门审批...\n3. 财务审核...",
  "indexing_technique": "high_quality",
  "process_rule": {
    "mode": "automatic"
  }
}

4.5 获取知识库文档列表

GET /v1/datasets/<dataset_id>/documents?page=1&page_size=20

4.6 删除文档

DELETE /v1/datasets/<dataset_id>/documents/<document_id>

5. 集成示例

5.1 Python 集成示例

import requests

DIFY_BASE_URL = "http://<dify-host>/v1"
API_KEY = "app-<your-api-key>"

def chat(query: str, user: str = "default", conversation_id: str = None):
    """发送对话消息"""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "query": query,
        "inputs": {},
        "response_mode": "blocking",
        "user": user,
    }
    if conversation_id:
        data["conversation_id"] = conversation_id

    resp = requests.post(
        f"{DIFY_BASE_URL}/chat-messages",
        headers=headers,
        json=data,
        timeout=30
    )
    result = resp.json()
    return {
        "answer": result.get("answer", ""),
        "conversation_id": result.get("conversation_id", ""),
        "message_id": result.get("message_id", ""),
    }

# 使用示例
result = chat("差旅报销标准是什么？", user="zhangsan")
print(result["answer"])

5.2 企业微信 Webhook 集成

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

DIFY_API_KEY = "app-<your-api-key>"
DIFY_BASE_URL = "http://<dify-host>/v1"

@app.route("/wecom/webhook", methods=["POST"])
def wecom_webhook():
    """企业微信消息回调"""
    data = request.json
    user_query = data.get("Content", "")
    user_id = data.get("FromUserName", "unknown")

    # 调用 Dify API
    resp = requests.post(
        f"{DIFY_BASE_URL}/chat-messages",
        headers={"Authorization": f"Bearer {DIFY_API_KEY}"},
        json={
            "query": user_query,
            "response_mode": "blocking",
            "user": user_id,
        },
        timeout=30
    )
    answer = resp.json().get("answer", "暂无回复")

    # 返回企业微信消息格式
    return jsonify({
        "msgtype": "text",
        "text": {"content": answer}
    })

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

5.3 Node.js 集成示例

const axios = require('axios');

const DIFY_BASE_URL = 'http://<dify-host>/v1';
const API_KEY = 'app-<your-api-key>';

async function chat(query, user = 'default') {
  const { data } = await axios.post(
    `${DIFY_BASE_URL}/chat-messages`,
    {
      query,
      inputs: {},
      response_mode: 'blocking',
      user,
    },
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      timeout: 30000,
    }
  );
  return {
    answer: data.answer,
    conversationId: data.conversation_id,
  };
}

// 使用示例
chat('差旅报销标准是什么？', 'zhangsan')
  .then(result => console.log(result.answer));

6. 错误处理

HTTP 状态码	说明	处理建议
400	请求参数错误	检查请求体格式
401	API Key 无效	检查 Authorization Header
403	无权限访问	检查 API Key 权限配置
429	请求频率超限	添加请求间隔/重试机制
500	服务端内部错误	查看 Dify 服务日志

建议的重试策略：

import time

def chat_with_retry(query, max_retries=3, retry_delay=2):
    for attempt in range(max_retries):
        try:
            return chat(query)
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(retry_delay * (attempt + 1))
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                time.sleep(retry_delay * (attempt + 1))
            else:
                raise

7. API 速率限制

计划类型	限制
自部署版	无官方限制，受服务器资源约束
建议配置	单用户 ≥ 60 次/分钟

最后更新: 2026-06-06

api-integration.md 8.1KB Cronologia Originale