yunmei/dify-app
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

merge: feature/dev → main (v1.0 企业知识库完整交付)

Browse Source
This commit is contained in:
yunmei
2026-06-06 07:43:43 +08:00
parent 1b15db8be4 6fd474b679
commit 783dc0ae5f
21 changed files with 2477 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-integration.md
+385
View File
@@ -0,0 +1,385 @@
# 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 | ❌ | 上传文件列表 |
**阻塞模式请求示例**
```bash
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"
}'
```
**阻塞模式响应**
```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=<id>&user=<user>
```
**响应**
```json
{
"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
```
```json
{
"name": "报销相关问题"
}
```
### 3.5 删除对话
```
DELETE /v1/conversations/<conversation_id>
```
---
## 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/<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 | ❌ | 分段规则 |
**分段规则示例**
```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/<dataset_id>/documents/<document_id>/indexing-status
```
### 4.4 通过文本创建文档
```
POST /v1/datasets/<dataset_id>/document/create-by-text
```
```json
{
"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 集成示例
```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 集成
```python
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 集成示例
```javascript
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 服务日志 |
**建议的重试策略**：
```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_
docs/deployment-guide.md
+293
View File
@@ -0,0 +1,293 @@
# 完整部署指南
> 西安云美电子科技有限公司 - 企业知识库
> 版本：v1.0 | 创建时间：2026-06-06
---
## 部署架构概览
```
┌─────────────────────┐
│ 用户 (浏览器) │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Nginx (反向代理) │ :80 / :443
│ SSL 终止 / 负载均衡 │
└──────────┬──────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌──────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
│ Dify Web │ │ Dify API │ │ SSRF Proxy │
│ (React SPA) │ │ (Flask) │ │ (Squid) │
│ :3000 │ │ :5001 │ │ :3128 │
└─────────────┘ └─────┬─────┘ └─────────────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌──▼────┐ ┌─────▼──────┐
│ PostgreSQL │ │ Redis │ │ Qdrant │
│ :5432 │ │ :6379 │ │ :6333 │
└─────────────┘ └───────┘ └────────────┘
```
---
## 第一步：服务器准备
### 1.1 系统要求
- Ubuntu 22.04 LTS（推荐）
- 最低 4 核 CPU / 8 GB RAM / 50 GB SSD
- 推荐 8 核 CPU / 16 GB RAM / 100 GB SSD
### 1.2 安装 Docker
```bash
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装 Docker
curl -fsSL https://get.docker.com | sh
# 安装 Docker Compose（如未自带）
sudo apt install docker-compose-plugin -y
# 验证安装
docker --version
docker compose version
# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
# 重新登录生效
```
---
## 第二步：部署 Dify
### 2.1 克隆项目
```bash
git clone http://git.xayunmei.com/yunmei/dify-app.git
cd dify-app
git checkout feature/dev
```
### 2.2 配置环境变量
```bash
cd docker
# 复制模板
cp .env.example .env
# 生成 SECRET_KEY
SECRET_KEY=$(openssl rand -hex 32)
echo "生成的 SECRET_KEY: $SECRET_KEY"
# 编辑 .env，填入实际值
nano .env
```
**必须修改的配置项**：
| 变量 | 说明 | 操作 |
|------|------|------|
| `SECRET_KEY` | 安全密钥 | 使用上面生成的值 |
| `POSTGRES_PASSWORD` | 数据库密码 | 设置强密码 |
| `REDIS_PASSWORD` | Redis 密码 | 设置强密码 |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | 从 DeepSeek 平台获取 |
### 2.3 启动服务
```bash
# 拉取镜像
docker compose pull
# 启动所有服务
docker compose up -d
# 查看状态
docker compose ps
# 等待所有服务健康（约 30-60 秒）
docker compose ps --format "table {{.Name}}\t{{.Status}}"
```
### 2.4 验证部署
```bash
# 检查 API 服务
curl http://localhost:5001/health
# 检查 Web 服务
curl -I http://localhost:80
```
---
## 第三步：初始化 Dify
### 3.1 创建管理员账号
1. 浏览器访问 `http://<服务器IP>:80`
2. 首次访问进入设置向导
3. 填写邮箱和密码，创建管理员账号
4. 设置管理员姓名
### 3.2 配置模型提供者
1. 进入 Dify 控制台
2. 导航到 **设置 → 模型提供者**
3. 添加 **DeepSeek**：
- API Base: `https://api.deepseek.com`
- API Key: 填入实际的 DeepSeek API Key
4. 验证连接成功
### 3.3 创建知识库
按 `docs/knowledge-base-structure.md` 中的结构创建知识库：
| 知识库名称 | 说明 |
|-----------|------|
| KB-COMP-公司概况 | 公司简介、组织架构 |
| KB-PROD-产品技术 | 产品手册、技术规范 |
| KB-QUAL-质量管理 | 质量体系、检测标准 |
| KB-RULE-制度流程 | 管理制度、审批流程 |
| KB-TRAIN-培训学习 | 培训材料 |
| KB-PROJ-项目档案 | 项目文档 |
| KB-FAQ-常见问题 | FAQ |
**每个知识库的分段配置**：
- 分段模式：自动
- 最大分段长度：500 tokens
- 重叠长度：50 tokens
### 3.4 上传文档
1. 准备各部门的知识库文档（PDF/Word/Markdown）
2. 按分类上传到对应知识库
3. 等待索引完成
4. 测试检索效果
---
## 第四步：配置对话应用
### 4.1 创建聊天应用
1. Dify 控制台 → **创建应用 → 聊天助手**
2. 应用名称：**云美知识助手**
3. 导入 DSL 配置（可选）：
- 应用设置 → 右上角 → **导入 DSL**
- 上传 `dsl/app-config.yaml`
4. 或手动配置（参考 `dsl/app-config.yaml` 中的参数）
### 4.2 配置提示词
复制 `prompts/system-prompt.md` 中的系统提示词到应用配置。
### 4.3 关联知识库
在应用的「知识库」设置中，关联已创建的所有知识库。
### 4.4 配置推荐问题
复制 `prompts/system-prompt.md` 中的推荐问题到应用配置。
### 4.5 测试应用
使用 Dify 内置的调试界面进行测试：
```
测试问题1：公司的组织架构是怎样的？
测试问题2：差旅报销的标准和流程是什么？
测试问题3：质量管理体系审核周期是多久？
```
对照 `tests/test-cases.md` 执行完整测试。
---
## 第五步：发布与接入
### 5.1 发布应用
1. 点击应用右上角 **发布**
2. 选择 **运行环境**（生产环境）
3. 确认发布
### 5.2 获取 API Key
1. 应用 → **访问 API**
2. 创建 API Key
3. 保存 Key（只显示一次）
### 5.3 接入企业微信（可选）
参考 `docs/api-integration.md` 中的企业微信集成示例。
### 5.4 配置 Nginx SSL（生产环境必做）
```bash
# 将 SSL 证书放入 nginx/ssl/ 目录
mkdir -p nginx/ssl
# 编辑 Nginx 配置，启用 HTTPS
# 修改 .env 中的 NGINX_SSL_PORT
```
---
## 日常运维
### 备份
```bash
# 数据库备份（建议设置 cron 每日执行）
docker compose exec db pg_dump -U postgres dify > /backup/dify_$(date +%Y%m%d).sql
# 向量库备份
docker compose exec qdrant curl -X POST http://localhost:6333/snapshots
```
### 更新
```bash
cd docker
docker compose pull
docker compose up -d
```
### 监控
```bash
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f --tail=100 api
docker compose logs -f --tail=100 worker
# 查看资源占用
docker stats --no-stream
```
---
## 故障排查速查
| 现象 | 排查命令 | 常见原因 |
|------|---------|---------|
| 页面打不开 | `docker compose ps` | 服务未启动 |
| 模型不回复 | `docker compose logs api` | API Key 无效/过期 |
| 知识库不检索 | `docker compose logs worker` | Worker 异常/索引未完成 |
| 数据库连接失败 | `docker compose logs db` | 密码不一致 |
| 磁盘空间不足 | `df -h` | 日志/数据膨胀 |
---
_最后更新: 2026-06-06_
docs/knowledge-base-structure.md
+210
View File
@@ -0,0 +1,210 @@
# 企业知识库结构设计
> 西安云美电子科技有限公司 - 企业知识库
> 文档版本：v1.0
> 创建时间：2026-06-06
---
## 1. 知识库总体架构
云美电子科技企业知识库采用 **分层分类** 结构，覆盖公司运营全链路：
```
企业知识库
├── 📁 公司概况
│ ├── 公司简介
│ ├── 组织架构
│ ├── 发展历程
│ └── 联系方式
│
├── 📁 产品技术
│ ├── 产品手册（按产品线分类）
│ ├── 技术规范
│ ├── 技术方案
│ ├── 研发文档
│ └── 常见技术问题 FAQ
│
├── 📁 质量管理
│ ├── 质量管理体系（QMS）
│ ├── 检测标准
│ ├── 计量规程
│ ├── 不合格品处理流程
│ └── 质量案例库
│
├── 📁 制度流程
│ ├── 行政管理制度
│ ├── 财务管理制度
│ ├── 人力资源制度
│ ├── 采购管理制度
│ └── 项目管理流程
│
├── 📁 培训学习
│ ├── 新员工入职培训
│ ├── 岗位技能培训
│ ├── 安全培训
│ └── 外部培训资料
│
├── 📁 项目档案
│ ├── 项目立项文档
│ ├── 项目验收报告
│ ├── 客户资料
│ └── 合同模板
│
└── 📁 常见问题 FAQ
├── 通用 FAQ
├── IT 支持 FAQ
├── 行政 FAQ
└── 产品售后 FAQ
```
## 2. 分类详细说明
### 2.1 公司概况
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 公司简介 | 公司介绍、业务范围、核心优势 | 半年 |
| 组织架构 | 部门设置、岗位职责、汇报关系 | 季度 |
| 发展历程 | 大事记、里程碑事件 | 年度 |
| 联系方式 | 内外联系方式、通讯录 | 按需 |
### 2.2 产品技术
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 产品手册 | 各产品线的产品说明书、操作指南 | 随产品更新 |
| 技术规范 | 行业标准、企业标准、检测依据 | 按需 |
| 技术方案 | 项目技术方案、可行性分析 | 按需 |
| 研发文档 | 研发过程中的技术记录、设计文档 | 持续 |
| 技术 FAQ | 产品使用中的技术问题及解答 | 持续 |
### 2.3 质量管理
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 质量管理体系 | ISO 体系文件、质量手册、程序文件 | 年度审核 |
| 检测标准 | 各类检测方法标准、判定依据 | 按标准更新 |
| 计量规程 | 设备计量校准规程、管理要求 | 年度 |
| 不合格品处理 | 不合格品处理流程、评审记录模板 | 按需 |
| 质量案例库 | 典型质量问题案例、改进措施 | 持续 |
### 2.4 制度流程
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 行政管理 | 考勤、出差、办公用品、车辆管理 | 年度 |
| 财务管理 | 报销流程、费用标准、审批权限 | 年度 |
| 人力资源 | 招聘、绩效考核、薪酬福利 | 年度 |
| 采购管理 | 采购流程、供应商管理、审批流程 | 年度 |
| 项目管理 | 项目立项、执行、验收、归档流程 | 年度 |
### 2.5 培训学习
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 新员工培训 | 入职培训材料、公司文化介绍 | 年度 |
| 岗位技能 | 各岗位专业技能培训材料 | 按需 |
| 安全培训 | 安全生产、消防安全培训 | 年度 |
| 外部培训 | 外部培训资料、行业学习资源 | 按需 |
### 2.6 项目档案
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 立项文档 | 项目立项申请、可行性分析 | 按项目 |
| 验收报告 | 项目验收报告、交付文档 | 按项目 |
| 客户资料 | 客户信息、需求文档、沟通记录 | 按需 |
| 合同模板 | 各类合同标准模板 | 年度 |
### 2.7 FAQ
| 子分类 | 内容说明 | 更新频率 |
|--------|---------|---------|
| 通用 FAQ | 公司常见问题（工作地点、福利等） | 持续 |
| IT 支持 | 系统使用、软件安装、网络问题 | 持续 |
| 行政 FAQ | 报销、请假、出差等流程问题 | 持续 |
| 产品售后 | 产品使用、售后问题 | 持续 |
## 3. 文档分段策略
### 3.1 分段参数配置
| 参数 | 推荐值 | 说明 |
|------|--------|------|
| 分段长度 | 500 tokens | 约 300-400 个中文字符 |
| 重叠长度 | 50 tokens | 上下文重叠，保持语义连贯 |
| 最大分段数/文件 | 20 | 单文件最大分段数 |
| 分隔符 | `\n`、`\n\n`、`。`、`！`、`？`、`；` | 中文优先分隔符 |
### 3.2 分段优先级规则
1. **按标题分层**：一级标题 → 二级标题 → 三级标题
2. **按段落分割**：在自然段落边界处分割
3. **按句号分割**：超出长度限制时在句号处分割
4. **硬截断兜底**：超出最大长度时强制截断
### 3.3 不同文档类型的分段建议
| 文档类型 | 建议分段长度 | 特殊处理 |
|----------|-------------|---------|
| 产品手册 | 300-500 tokens | 保留产品型号、参数表格 |
| 技术规范 | 500-800 tokens | 保留规范编号、章节号 |
| 管理制度 | 400-600 tokens | 保留条款编号 |
| FAQ | 按问答对分段 | 每对为一个分段 |
| 培训材料 | 500-700 tokens | 保留课程结构 |
| 合同模板 | 按条款分段 | 保留条款编号和标题 |
### 3.4 元数据标签建议
每个知识库文档建议添加以下元数据标签，便于精准检索：
```
- department: 所属部门（产品部/质量部/行政部...）
- doc_type: 文档类型（手册/规范/制度/FAQ...）
- product: 关联产品（如适用）
- version: 文档版本号
- status: 状态（有效/废止/草稿）
- last_updated: 最后更新时间
```
## 4. 知识库导入流程
### 4.1 批量导入步骤
1. **文件整理**：按上述分类结构整理文件目录
2. **格式检查**：确保文件为支持的格式（PDF、Word、Markdown、TXT、Excel）
3. **元数据标注**：为每个文件添加元数据标签
4. **创建知识库**：在 Dify 中按分类创建独立知识库
5. **上传文档**：按分类批量上传，应用对应分段策略
6. **索引验证**：检查分段结果，确认无明显截断错误
7. **测试检索**：使用典型问题测试检索效果
### 4.2 知识库命名规范
```
KB-{分类英文缩写}-{名称}
示例：
KB-COMP-公司概况
KB-PROD-产品技术
KB-QUAL-质量管理
KB-RULE-制度流程
KB-TRAIN-培训学习
KB-PROJ-项目档案
KB-FAQ-常见问题
```
## 5. 维护策略
| 维护类型 | 频率 | 负责人 | 说明 |
|----------|------|--------|------|
| 内容更新 | 按需 | 各部门 | 文档有更新时同步上传 |
| 索引重建 | 月度 | IT 部 | 检查分段质量，优化检索 |
| 过期清理 | 季度 | 管理部 | 标记/移除过期文档 |
| 效果评估 | 月度 | IT 部 | 检索准确率、用户满意度 |
| 备份 | 每日 | IT 部 | 数据库、向量库自动备份 |
---
_最后更新: 2026-06-06_
docs/performance-baseline.md
+128
View File
@@ -0,0 +1,128 @@
# 性能基线指标
> 西安云美电子科技有限公司 - 企业知识库
> 版本：v1.0 | 创建时间：2026-06-06
---
## 1. 测试环境
| 项目 | 规格 |
|------|------|
| 服务器 | 8 核 CPU / 16 GB RAM / 100 GB SSD |
| 部署方式 | Docker Compose |
| Dify 版本 | 最新社区版（v1.x） |
| 模型 | DeepSeek-Chat |
| 知识库文档数 | 100-500 篇（初期） |
| 知识库分段方式 | 自动分段，500 tokens/段 |
---
## 2. 响应时间基线
| 场景 | 指标 | 目标值 | 可接受值 |
|------|------|:------:|:--------:|
| 首次响应（首 token） | TTFB | ≤ 3s | ≤ 5s |
| 简单问题完整回答 | 总耗时 | ≤ 8s | ≤ 15s |
| 复杂问题（跨分类检索） | 总耗时 | ≤ 12s | ≤ 20s |
| 多轮对话第 N 轮（N≤10） | 总耗时 | ≤ 10s | ≤ 15s |
| 流式输出首字延迟 | TTFB | ≤ 2s | ≤ 4s |
| 知识库索引构建（单文档） | 索引耗时 | ≤ 10s | ≤ 30s |
| 知识库索引构建（批量100篇） | 索引耗时 | ≤ 5min | ≤ 10min |
---
## 3. 准确率基线
| 场景 | 指标 | 目标值 | 可接受值 |
|------|------|:------:|:--------:|
| P0 核心问题回答准确率 | Top-1 准确率 | ≥ 95% | ≥ 85% |
| 制度流程类问题 | 回答准确率 | ≥ 98% | ≥ 90% |
| 产品技术类问题 | 回答准确率 | ≥ 95% | ≥ 85% |
| FAQ 类问题 | 回答准确率 | ≥ 98% | ≥ 90% |
| 不相关问题拒绝率 | 拒绝准确率 | ≥ 95% | ≥ 85% |
| 来源标注准确率 | 标注准确率 | ≥ 90% | ≥ 80% |
| 多轮对话上下文保持率 | 一致性 | ≥ 90% | ≥ 80% |
---
## 4. 并发与容量基线
| 场景 | 指标 | 目标值 | 可接受值 |
|------|------|:------:|:--------:|
| 并发用户数 | 最大并发 | ≥ 20 | ≥ 10 |
| 并发响应时间（10用户） | P95 延迟 | ≤ 10s | ≤ 20s |
| 并发响应时间（20用户） | P95 延迟 | ≤ 15s | ≤ 30s |
| 单知识库文档上限 | 最大文档数 | 1000 篇 | 500 篇 |
| 单知识库分段上限 | 最大分段数 | 50000 段 | 20000 段 |
| 单次检索返回 | Top-K 相关文档 | 3-5 段 | 3-10 段 |
---
## 5. 可用性基线
| 场景 | 指标 | 目标值 |
|------|------|:------:|
| 服务可用性 | Uptime | ≥ 99% |
| 计划外停机 | 月均 | ≤ 1 次 |
| 故障恢复时间 | MTTR | ≤ 30 min |
| 数据库备份频率 | RPO | 每日 |
| 数据恢复测试 | 频率 | 季度 |
---
## 6. 模型资源消耗基线
| 场景 | 指标 | 估算值 |
|------|------|--------|
| 单次问答（简单） | DeepSeek Token 消耗 | ~500-1000 tokens |
| 单次问答（复杂） | DeepSeek Token 消耗 | ~1500-3000 tokens |
| 每日 50 次问答 | 日 Token 消耗 | ~50K-100K tokens |
| 每月预估 | 月 Token 消耗 | ~1.5M-3M tokens |
---
## 7. 基线测量方法
### 7.1 响应时间测量
```bash
# 使用 curl 测量 TTFB
curl -o /dev/null -s -w "TTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
-X POST http://<dify-host>/v1/chat-messages \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{"query":"差旅报销标准是什么？","inputs":{},"response_mode":"blocking","user":"test-user"}'
```
### 7.2 准确率测量
使用 `tests/test-cases.md` 中的 37 个测试用例，逐条执行并记录结果。
计算公式：
- Top-1 准确率 = 正确回答数 / 总测试问题数 × 100%
- 拒绝准确率 = 正确拒绝无关问题数 / 总无关问题数 × 100%
### 7.3 并发测量
```bash
# 使用 ab（Apache Benchmark）模拟并发
ab -n 20 -c 10 -p request.json -T application/json \
-H "Authorization: Bearer <api-key>" \
http://<dify-host>/v1/chat-messages
```
---
## 8. 性能调优建议
| 问题方向 | 调优手段 |
|----------|---------|
| 响应慢 | 优化知识库分段大小、调整 Top-K 参数、升级服务器 |
| 准确率低 | 优化分段策略、增加元数据标签、调整检索权重 |
| 并发不足 | 扩展 Worker 实例数、增加 Redis 内存、升级 CPU |
| Token 消耗高 | 优化 System Prompt 长度、调整上下文窗口、启用缓存 |
---
_最后更新: 2026-06-06_