From b0a070ddd3e46a0b116fbdc2a74897703d85da2f Mon Sep 17 00:00:00 2001 From: xieke Date: Sat, 6 Jun 2026 06:30:43 +0800 Subject: [PATCH] =?UTF-8?q?feat(M5):=20API=E9=9B=86=E6=88=90=E6=96=87?= =?UTF-8?q?=E6=A1=A3=20-=20=E5=AF=B9=E8=AF=9D=E6=8E=A5=E5=8F=A3=E3=80=81?= =?UTF-8?q?=E7=9F=A5=E8=AF=86=E5=BA=93=E7=AE=A1=E7=90=86=E3=80=81Python/No?= =?UTF-8?q?de.js/=E4=BC=81=E5=BE=AE=E9=9B=86=E6=88=90=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-integration.md | 385 ++++++++++++++++++++++++++++++++++++++++ tasks.md | 2 +- 2 files changed, 386 insertions(+), 1 deletion(-) create mode 100644 docs/api-integration.md diff --git a/docs/api-integration.md b/docs/api-integration.md new file mode 100644 index 0000000..f87966d --- /dev/null +++ b/docs/api-integration.md @@ -0,0 +1,385 @@ +# Dify API 集成指南 + +> 西安云美电子科技有限公司 - 企业知识库 +> 版本：v1.0 | 创建时间：2026-06-06 + +--- + +## 1. 概述 + +Dify 提供完整的 RESTful API，支持将知识库对话能力集成到企业微信、钉钉、自建系统等渠道。本文档涵盖最常用的 API 接口及集成示例。 + +**Base URL**: `http:///v1` + +--- + +## 2. 认证方式 + +所有 API 请求需在 Header 中携带 API Key： + +``` +Authorization: Bearer app- +``` + +**获取 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 | ❌ | 上传文件列表 | + +**阻塞模式请求示例** + +```bash +curl -X POST 'http:///v1/chat-messages' \ + -H 'Authorization: Bearer app-' \ + -H 'Content-Type: application/json' \ + -d '{ + "query": "差旅报销标准是什么？", + "inputs": {}, + "response_mode": "blocking", + "user": "zhangsan" + }' +``` + +**阻塞模式响应** + +```json +{ + "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=&user= +``` + +**响应** + +```json +{ + "limit": 20, + "has_more": false, + "data": [ + { + "id": "xxx", + "query": "差旅报销标准", + "answer": "根据《差旅管理制度》...", + "created_at": 1717632000 + } + ] +} +``` + +### 3.3 获取对话列表 + +``` +GET /v1/conversations?user=&last_id=&limit=20&sort_by=-updated_at +``` + +### 3.4 重命名对话 + +``` +PATCH /v1/conversations//name +``` + +```json +{ + "name": "报销相关问题" +} +``` + +### 3.5 删除对话 + +``` +DELETE /v1/conversations/ +``` + +--- + +## 4. 知识库管理接口 + +### 4.1 创建知识库 + +``` +POST /v1/datasets +``` + +```json +{ + "name": "KB-RULE-制度流程", + "description": "公司各类管理制度和审批流程文档" +} +``` + +### 4.2 获取知识库列表 + +``` +GET /v1/datasets?page=1&page_size=20 +``` + +### 4.3 上传文档到知识库 + +**步骤一：创建上传任务** + +``` +POST /v1/datasets//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 | ❌ | 分段规则 | + +**分段规则示例** + +```json +{ + "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//documents//indexing-status +``` + +### 4.4 通过文本创建文档 + +``` +POST /v1/datasets//document/create-by-text +``` + +```json +{ + "name": "报销流程说明", + "text": "## 报销流程\n\n1. 填写报销单...\n2. 部门审批...\n3. 财务审核...", + "indexing_technique": "high_quality", + "process_rule": { + "mode": "automatic" + } +} +``` + +### 4.5 获取知识库文档列表 + +``` +GET /v1/datasets//documents?page=1&page_size=20 +``` + +### 4.6 删除文档 + +``` +DELETE /v1/datasets//documents/ +``` + +--- + +## 5. 集成示例 + +### 5.1 Python 集成示例 + +```python +import requests + +DIFY_BASE_URL = "http:///v1" +API_KEY = "app-" + +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 集成 + +```python +from flask import Flask, request, jsonify +import requests + +app = Flask(__name__) + +DIFY_API_KEY = "app-" +DIFY_BASE_URL = "http:///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 集成示例 + +```javascript +const axios = require('axios'); + +const DIFY_BASE_URL = 'http:///v1'; +const API_KEY = 'app-'; + +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 服务日志 | + +**建议的重试策略**： + +```python +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_ diff --git a/tasks.md b/tasks.md index 996735c..78f6938 100644 --- a/tasks.md +++ b/tasks.md @@ -42,7 +42,7 @@ ## M5: API 集成文档 -- [ ] M5.1.1 编写 `docs/api-integration.md`（Dify API 集成指南：对话、知识库管理接口） +- [x] M5.1.1 编写 `docs/api-integration.md`（Dify API 集成指南：对话、知识库管理接口） ---