diff --git a/.gitignore b/.gitignore index da6dcb7..71e20cb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,28 +1,45 @@ -# Environment +# 环境变量（含密码和密钥） +docker/.env .env .env.local -*.key +.env.*.local +.env.*.docker + +# Docker 数据卷 +docker/data/ +docker/volumes/ + +# SSL 证书 +docker/nginx/ssl/*.pem +docker/nginx/ssl/*.key +docker/nginx/ssl/*.crt + +# IDE +.vscode/ +.idea/ +*.swp +*.swo # OS .DS_Store Thumbs.db -desktop.ini - -# IDE -.idea/ -.vscode/ -*.swp -*.swo # Python __pycache__/ -*.pyc -venv/ +*.py[cod] +*.egg-info/ .venv/ +venv/ # Node node_modules/ +dist/ +.next/ -# Temp +# Logs +*.log +logs/ + +# 临时文件 *.tmp *.bak diff --git a/README.md b/README.md index 85a7c1a..f5bed95 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,111 @@ -# 企业知识库 - Dify 应用 +# 云美企业知识库 -> 西安云美电子科技有限公司 企业知识库系统 +> 西安云美电子科技有限公司 - 基于 Dify + DeepSeek 的企业内部知识库 -## 项目概述 +## 项目简介 -基于 Dify 平台自部署的企业知识库，使用 DeepSeek 模型驱动，支持公司内部文档的智能检索和问答。 +本项目为云美电子科技搭建企业内部知识库系统，员工可通过对话式 AI 快速检索公司文档、获取智能问答。基于 **Dify 社区版（Docker 自部署）** + **DeepSeek 大模型** 构建。 ## 技术栈 -- **平台**: Dify 社区版（Docker 自部署） -- **模型**: DeepSeek -- **检索**: 混合检索（向量 + 全文） +| 组件 | 说明 | +|------|------| +| Dify | AI 应用开发平台（社区版 Docker 部署） | +| DeepSeek | 大语言模型（deepseek-chat） | +| PostgreSQL | 关系数据库 | +| Redis | 缓存与消息队列 | +| Qdrant | 向量数据库 | +| Nginx | 反向代理 | -## 快速开始 - -### 1. 部署 Dify - -```bash -cd docker -cp .env.example .env -# 编辑 .env 填入实际配置 -docker compose up -d -``` - -### 2. 配置模型 - -登录 Dify 后台 → 设置 → 模型供应商 → 添加 DeepSeek API Key - -### 3. 导入知识库 - -按 `docs/knowledge-base-structure.md` 的分类创建知识库，上传文档。 - -### 4. 创建应用 - -参考 `prompts/system-prompt.md` 配置 Chatflow 应用。 - -## 目录结构 +## 项目结构 ``` dify-app/ -├── docker/ # Docker 部署配置 -├── prompts/ # Prompt 模板 -├── knowledge/ # 示例文档 -├── dsl/ # Dify 应用配置导出 -├── tests/ # 测试用例 -├── docs/ # 项目文档 -└── tasks.md # 任务清单 +├── docker/ # Docker 部署配置 +│ ├── docker-compose.yml # 服务编排 +│ ├── .env.example # 环境变量模板 +│ └── README.md # Docker 部署说明 +│ +├── docs/ # 项目文档 +│ ├── knowledge-base-structure.md # 知识库结构设计 +│ ├── performance-baseline.md # 性能基线指标 +│ ├── api-integration.md # API 集成指南 +│ └── deployment-guide.md # 完整部署指南 +│ +├── prompts/ # 提示词 +│ └── system-prompt.md # 系统提示词与对话策略 +│ +├── tests/ # 测试 +│ └── test-cases.md # 功能/安全测试用例 +│ +├── dsl/ # Dify 应用配置 +│ └── app-config.yaml # 应用 DSL 配置模板 +│ +├── tasks.md # 任务清单 +├── .gitignore # Git 忽略规则 +└── README.md # 本文件 ``` -## 仓库 +## 快速开始 -http://git.xayunmei.com/yunmei/dify-app +```bash +# 1. 克隆项目 +git clone http://git.xayunmei.com/yunmei/dify-app.git +cd dify-app +git checkout feature/dev + +# 2. 配置环境变量 +cd docker +cp .env.example .env +# 编辑 .env 填写 SECRET_KEY、数据库密码、DeepSeek API Key + +# 3. 启动服务 +docker compose up -d + +# 4. 访问 +# 浏览器打开 http://<服务器IP>:80 +``` + +详细部署步骤请参考 [部署指南](docs/deployment-guide.md)。 + +## 知识库分类 + +| 分类 | 内容 | +|------|------| +| 📋 公司概况 | 公司简介、组织架构、联系方式 | +| 🔧 产品技术 | 产品手册、技术规范、技术方案 | +| ✅ 质量管理 | 质量体系、检测标准、计量规程 | +| 📄 制度流程 | 管理制度、审批流程、操作规程 | +| 📚 培训学习 | 培训材料、学习资源 | +| 📁 项目档案 | 项目文档、合同模板 | +| ❓ 常见问题 | IT支持、行政事务、售后FAQ | + +## API 文档 + +知识库对话、文档管理等 API 接口文档：[API 集成指南](docs/api-integration.md) + +## 测试 + +功能测试用例（37 个）：[测试用例](tests/test-cases.md) + +## Git 分支策略 + +| 分支 | 用途 | +|------|------| +| `main` | 生产发布分支 | +| `feature/dev` | 开发分支（日常开发在此分支） | + +## 相关文档 + +| 文档 | 说明 | +|------|------| +| [知识库结构设计](docs/knowledge-base-structure.md) | 分类体系、分段策略、维护规范 | +| [性能基线指标](docs/performance-baseline.md) | 响应时间、准确率、并发指标 | +| [API 集成指南](docs/api-integration.md) | RESTful API、代码示例 | +| [完整部署指南](docs/deployment-guide.md) | 从服务器到上线的全流程 | +| [系统提示词设计](prompts/system-prompt.md) | 角色定义、回答规范、推荐问题 | +| [Dify 应用配置](dsl/app-config.yaml) | DSL 模板（可导入 Dify） | + +--- + +**西安云美电子科技有限公司** © 2026 diff --git a/docker/.env.docker b/docker/.env.docker new file mode 100644 index 0000000..7d1cc00 --- /dev/null +++ b/docker/.env.docker @@ -0,0 +1,32 @@ +# ============================================================ +# Dify Docker 内部服务通信环境变量 +# 此文件由 docker-compose.yml 的 env_file 引用 +# 请勿提交到 Git，已在 .gitignore 中排除 +# ============================================================ + +# 内部服务间通信不需要修改以下值 +# DB/Redis 等地址使用 docker-compose 中的服务名 + +EDITION=SELF_HOSTED +CONF_GIT_SYNC_ENABLED=false + +# 知识库检索配置 +INDEXING_MAX_SEGMENTATION_TOKENS=500 +INDEXING_MAX_SEGMENTATION_CHUNKS_PER_FILE=10 +INDEXING_SEGMENTATION_SEPARATOR=['\n','\n\n',' ','。','！','？','；','；'] + +# 批量处理配置 +BATCH_PROCESSING_ENABLED=true + +# 多模态配置 +MULTIMODAL_ENABLED=true + +# 文件上传限制 +UPLOAD_FILE_SIZE_LIMIT=50 +UPLOAD_IMAGE_FILE_SIZE_LIMIT=20 + +# Celery 队列配置 +CELERY_QUEUES=dataset,generation,mail + +# 文档解析配置 +DOCUMENT_PARSERS=pdf,txt,md,csv,xlsx,pptx,docx diff --git a/docker/.env.example b/docker/.env.example new file mode 100644 index 0000000..0743aa4 --- /dev/null +++ b/docker/.env.example @@ -0,0 +1,84 @@ +# ============================================================ +# Dify 环境变量配置模板 +# 西安云美电子科技有限公司 - 企业知识库 +# +# 使用方法：cp .env.example .env && 编辑 .env 填写实际值 +# ============================================================ + +# ====================== 基础配置 ====================== + +# 运行模式：api（默认）/ worker +DIFY_MODE=api + +# 日志级别：DEBUG / INFO / WARNING / ERROR +LOG_LEVEL=INFO + +# 安全密钥（必须修改！用于加密 Token 等敏感数据） +# 生成方法：openssl rand -hex 32 +SECRET_KEY=请替换为随机生成的密钥 + +# 应用端口（API 服务内部端口） +HTTP_APP_PORT=5001 + +# ====================== 数据库配置 ====================== + +POSTGRES_USER=postgres +POSTGRES_PASSWORD=请替换为强密码 +POSTGRES_DB=dify + +# ====================== Redis 配置 ====================== + +REDIS_PASSWORD=请替换为强密码 +REDIS_DB=0 + +# ====================== 存储配置 ====================== + +# 存储类型：local / s3 +STORAGE_TYPE=local +STORAGE_LOCAL_PATH=/app/api/storage + +# ====================== 向量数据库配置 ====================== + +# 向量数据库类型：qdrant / weaviate / elasticsearch +VECTOR_STORE=qdrant + +# Qdrant 配置 +QDRANT_PORT=6333 +QDRANT_API_KEY= + +# ====================== DeepSeek 模型配置 ====================== + +# DeepSeek API 地址（国内可直连） +DEEPSEEK_API_BASE=https://api.deepseek.com +DEEPSEEK_API_KEY=请替换为你的DeepSeek API Key + +# ====================== Web 前端配置 ====================== + +# 如果使用 Nginx 反向代理且前后端同域名，留空即可 +NEXT_PUBLIC_API_BASE_URL= +NEXT_PUBLIC_DEPLOY_ENV=PRODUCTION + +# ====================== Nginx 配置 ====================== + +NGINX_PORT=80 +NGINX_SSL_PORT=443 + +# ====================== SSRF 代理配置 ====================== + +SSRF_PROXY_PORT=3128 + +# ====================== Sandbox 配置（可选）====================== + +SANDBOX_API_KEY= +SANDBOX_URL= +SANDBOX_WORKER_TIMEOUT=15 +SANDBOX_ENABLE_NETWORK=true + +# ====================== S3 存储配置（可选）====================== + +S3_USE_CUSTOM_DOMAIN=true +S3_ENDPOINT= +S3_BUCKET_NAME= +S3_ACCESS_KEY= +S3_SECRET_KEY= +S3_REGION= diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..82e67f4 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,147 @@ +# Dify 部署指南 + +> 西安云美电子科技有限公司 - 企业知识库 + +## 前置要求 + +| 项目 | 最低要求 | 推荐配置 | +|------|---------|---------| +| CPU | 4 核 | 8 核+ | +| 内存 | 8 GB | 16 GB+ | +| 磁盘 | 50 GB SSD | 100 GB+ SSD | +| Docker | ≥ 20.10 | 最新稳定版 | +| Docker Compose | ≥ 2.0 | 最新稳定版 | +| 操作系统 | Ubuntu 20.04+ | Ubuntu 22.04 LTS | + +## 快速部署 + +### 1. 克隆项目 + +```bash +git clone http://git.xayunmei.com/yunmei/dify-app.git +cd dify-app +git checkout feature/dev +``` + +### 2. 配置环境变量 + +```bash +cd docker +cp .env.example .env + +# 必须修改以下配置： +# - SECRET_KEY（安全密钥，用 openssl rand -hex 32 生成） +# - POSTGRES_PASSWORD（数据库密码） +# - REDIS_PASSWORD（Redis 密码） +# - DEEPSEEK_API_KEY（DeepSeek API 密钥） +``` + +### 3. 配置 Nginx（可选） + +如果使用自定义域名，编辑 `nginx/nginx.conf`： + +```bash +mkdir -p nginx +# 将 SSL 证书放入 nginx/ssl/ 目录 +``` + +### 4. 启动服务 + +```bash +# 拉取镜像 +docker compose pull + +# 后台启动所有服务 +docker compose up -d + +# 查看服务状态 +docker compose ps + +# 查看日志 +docker compose logs -f +``` + +### 5. 初始化 + +启动完成后，打开浏览器访问： + +``` +http://<服务器IP>:80 +``` + +首次访问会要求设置管理员账号和密码。 + +## 服务端口说明 + +| 服务 | 容器端口 | 映射端口 | 说明 | +|------|---------|---------|------| +| Nginx | 80/443 | 80/443 | 主入口 | +| Dify API | 5001 | 内部 | API 服务 | +| Dify Web | 3000 | 内部 | 前端 | +| PostgreSQL | 5432 | 内部 | 数据库 | +| Redis | 6379 | 内部 | 缓存 | +| Qdrant | 6333 | 6333 | 向量数据库 | + +## 常用命令 + +```bash +# 停止所有服务 +docker compose down + +# 停止并清除数据卷（危险！） +docker compose down -v + +# 重启单个服务 +docker compose restart api +docker compose restart worker + +# 查看单个服务日志 +docker compose logs -f api +docker compose logs -f worker + +# 更新镜像 +docker compose pull +docker compose up -d +``` + +## 备份与恢复 + +### 数据库备份 + +```bash +docker compose exec db pg_dump -U postgres dify > backup_$(date +%Y%m%d).sql +``` + +### 数据库恢复 + +```bash +docker compose exec -T db psql -U postgres dify < backup_20260606.sql +``` + +### 数据卷备份 + +```bash +docker run --rm -v dify-app_api_storage:/data -v $(pwd):/backup alpine tar czf /backup/api_storage_$(date +%Y%m%d).tar.gz -C /data . +``` + +## 故障排查 + +| 问题 | 排查方法 | +|------|---------| +| 服务启动失败 | `docker compose logs ` | +| 数据库连接失败 | 检查 `.env` 中密码是否一致 | +| 知识库索引失败 | 检查 Worker 日志，确认 Celery 队列正常 | +| 模型调用失败 | 检查 DeepSeek API Key 是否有效 | +| 端口冲突 | 修改 `.env` 中对应端口号 | + +## 安全注意事项 + +1. **SECRET_KEY 必须使用随机值**，不要使用默认值 +2. **生产环境关闭 Qdrant 外部端口**（注释掉 ports 映射） +3. **定期更换数据库密码** +4. **配置 Nginx SSL 证书**，不要在公网裸跑 HTTP +5. **.env 文件不要提交到 Git** + +--- + +_最后更新: 2026-06-06_ diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 0000000..2b99f59 --- /dev/null +++ b/docker/docker-compose.yml @@ -0,0 +1,270 @@ +# Docker Compose for Dify Self-Hosted +# 西安云美电子科技有限公司 - 企业知识库 +# 版本：基于 Dify v1.x 社区版 +# +# 使用方法： +# cp .env.example .env +# 编辑 .env 填写实际值 +# docker compose up -d + +services: + + ### ======================== 基础设施 ======================== + + # PostgreSQL 数据库 + db: + image: postgres:15-alpine + restart: always + environment: + POSTGRES_USER: ${POSTGRES_USER:-postgres} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: ${POSTGRES_DB:-dify} + volumes: + - db_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"] + interval: 10s + timeout: 5s + retries: 5 + networks: + - dify-network + + # Redis 缓存 + redis: + image: redis:7-alpine + restart: always + command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes + volumes: + - redis_data:/data + healthcheck: + test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"] + interval: 10s + timeout: 5s + retries: 5 + networks: + - dify-network + + ### ======================== Dify 核心服务 ======================== + + # Dify API 后端 + api: + image: langgenius/dify-api:latest + restart: always + environment: + # 基础配置 + - MODE=${DIFY_MODE:-api} + - LOG_LEVEL=${LOG_LEVEL:-INFO} + - LOG_FILE=${LOG_FILE:-} + - SECRET_KEY=${SECRET_KEY} + # 数据库配置 + - DB_USERNAME=${POSTGRES_USER:-postgres} + - DB_PASSWORD=${POSTGRES_PASSWORD} + - DB_HOST=db + - DB_PORT=5432 + - DB_DATABASE=${POSTGRES_DB:-dify} + # Redis 配置 + - REDIS_HOST=redis + - REDIS_PORT=6379 + - REDIS_PASSWORD=${REDIS_PASSWORD} + - REDIS_DB=${REDIS_DB:-0} + # 存储配置 + - STORAGE_TYPE=${STORAGE_TYPE:-local} + - STORAGE_LOCAL_PATH=/app/api/storage + # 向量数据库 + - VECTOR_STORE=${VECTOR_STORE:-qdrant} + - QDRANT_URL=http://qdrant:6333 + - QDRANT_API_KEY=${QDRANT_API_KEY:-} + # S3 配置（可选） + - S3_USE_CUSTOM_DOMAIN=${S3_USE_CUSTOM_DOMAIN:-true} + - S3_ENDPOINT=${S3_ENDPOINT:-} + - S3_BUCKET_NAME=${S3_BUCKET_NAME:-} + - S3_ACCESS_KEY=${S3_ACCESS_KEY:-} + - S3_SECRET_KEY=${S3_SECRET_KEY:-} + - S3_REGION=${S3_REGION:-} + # SandBox 配置 + - CODE_EXECUTION_API_KEY=${SANDBOX_API_KEY:-} + - CODE_EXECUTION_API_URL=${SANDBOX_URL:-} + # 模型配置（DeepSeek） + - DEEPSEEK_API_BASE=${DEEPSEEK_API_BASE:-https://api.deepseek.com} + - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:-} + # 其他 + - HTTP_APP_PORT=5001 + - CELERY_BROKER_URL=redis://:${REDIS_PASSWORD}@redis:6379/1 + - CELERY_RESULT_BACKEND=redis://:${REDIS_PASSWORD}@redis:6379/1 + volumes: + - api_storage:/app/api/storage + - app_data:/app/data + depends_on: + db: + condition: service_healthy + redis: + condition: service_healthy + networks: + - dify-network + + # Dify Web 前端 + web: + image: langgenius/dify-web:latest + restart: always + environment: + - NEXT_PUBLIC_API_BASE_URL=${NEXT_PUBLIC_API_BASE_URL:-} + - NEXT_PUBLIC_DEPLOY_ENV=${NEXT_PUBLIC_DEPLOY_ENV:-PRODUCTION} + # 不使用 Nginx 时可直接访问 Web（设置 WEB_PORT=3000 启用） + ports: + - "${WEB_PORT:-}" + volumes: + - web_config:/app/config + depends_on: + - api + networks: + - dify-network + + # Dify Worker（异步任务处理） + worker: + image: langgenius/dify-api:latest + restart: always + environment: + # 基础配置 + - MODE=${DIFY_MODE:-worker} + - LOG_LEVEL=${LOG_LEVEL:-INFO} + - SECRET_KEY=${SECRET_KEY} + # 数据库配置 + - DB_USERNAME=${POSTGRES_USER:-postgres} + - DB_PASSWORD=${POSTGRES_PASSWORD} + - DB_HOST=db + - DB_PORT=5432 + - DB_DATABASE=${POSTGRES_DB:-dify} + # Redis 配置 + - REDIS_HOST=redis + - REDIS_PORT=6379 + - REDIS_PASSWORD=${REDIS_PASSWORD} + - REDIS_DB=${REDIS_DB:-0} + # 存储配置 + - STORAGE_TYPE=${STORAGE_TYPE:-local} + - STORAGE_LOCAL_PATH=/app/api/storage + # 向量数据库 + - VECTOR_STORE=${VECTOR_STORE:-qdrant} + - QDRANT_URL=http://qdrant:6333 + - QDRANT_API_KEY=${QDRANT_API_KEY:-} + # 模型配置（DeepSeek） + - DEEPSEEK_API_BASE=${DEEPSEEK_API_BASE:-https://api.deepseek.com} + - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:-} + # Celery + - CELERY_BROKER_URL=redis://:${REDIS_PASSWORD}@redis:6379/1 + - CELERY_RESULT_BACKEND=redis://:${REDIS_PASSWORD}@redis:6379/1 + volumes: + - api_storage:/app/api/storage + - app_data:/app/data + depends_on: + db: + condition: service_healthy + redis: + condition: service_healthy + networks: + - dify-network + + ### ======================== 向量数据库 ======================== + + # Qdrant 向量数据库（默认） + qdrant: + image: qdrant/qdrant:latest + restart: always + volumes: + - qdrant_data:/qdrant/storage + environment: + - QDRANT_API_KEY=${QDRANT_API_KEY:-} + ports: + - "${QDRANT_PORT:-6333}:6333" + networks: + - dify-network + + ### ======================== 安全与代理 ======================== + + # Nginx 反向代理 + nginx: + image: nginx:alpine + restart: always + ports: + - "${NGINX_PORT:-80}:80" + - "${NGINX_SSL_PORT:-443}:443" + volumes: + - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro + - ./nginx/ssl:/etc/nginx/ssl:ro + - nginx_logs:/var/log/nginx + depends_on: + - api + - web + networks: + - dify-network + + # SSRF 代理（安全防护） + ssrf-proxy: + image: ubuntu/squid:latest + restart: always + volumes: + - ./ssrf-proxy/squid.conf.template:/etc/squid/squid.conf.template:ro + environment: + - HTTP_PROXY_PORT=${SSRF_PROXY_PORT:-3128} + ports: + - "${SSRF_PROXY_PORT:-3128}:3128" + networks: + - dify-network + + ### ======================== 可选服务 ======================== + + # Sandbox 代码执行环境（可选，按需启用） + # sandbox: + # image: langgenius/dify-sandbox:latest + # restart: always + # environment: + # - API_KEY=${SANDBOX_API_KEY} + # - GIN_MODE=release + # - WORKER_TIMEOUT=${SANDBOX_WORKER_TIMEOUT:-15} + # - ENABLE_NETWORK=${SANDBOX_ENABLE_NETWORK:-true} + # volumes: + # - sandbox_data:/data + # networks: + # - dify-network + + # Elasticsearch（可选，替代 Qdrant） + # elasticsearch: + # image: elasticsearch:8.11.0 + # restart: always + # volumes: + # - es_data:/usr/share/elasticsearch/data + # environment: + # - discovery.type=single-node + # - xpack.security.enabled=false + # - ES_JAVA_OPTS=-Xms512m -Xmx512m + # networks: + # - dify-network + + # Weaviate（可选，替代 Qdrant） + # weaviate: + # image: semitechnologies/weaviate:latest + # restart: always + # volumes: + # - weaviate_data:/var/lib/weaviate + # environment: + # - QUERY_DEFAULTS_LIMIT=25 + # - AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true + # - PERSISTENCE_DATA_PATH=/var/lib/weaviate + # ports: + # - "8080:8080" + # networks: + # - dify-network + +volumes: + db_data: + redis_data: + api_storage: + app_data: + qdrant_data: + nginx_logs: + # sandbox_data: + # es_data: + # weaviate_data: + +networks: + dify-network: + driver: bridge diff --git a/docker/nginx/nginx.conf b/docker/nginx/nginx.conf new file mode 100644 index 0000000..479a36c --- /dev/null +++ b/docker/nginx/nginx.conf @@ -0,0 +1,88 @@ +# Nginx 反向代理配置 +# 西安云美电子科技有限公司 - 企业知识库 + +upstream dify_api { + server api:5001; +} + +upstream dify_web { + server web:3000; +} + +server { + listen 80; + server_name _; + + # 请求体大小限制（文件上传） + client_max_body_size 50M; + + # API 请求 + location /console/api { + proxy_pass http://dify_api; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket 支持 + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + + location /v1 { + proxy_pass http://dify_api; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # SSE 支持 + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 300s; + } + + # 静态资源 + location /files { + proxy_pass http://dify_api; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } + + location /elegant { + proxy_pass http://dify_api; + proxy_set_header Host $host; + } + + # Web 前端 + location / { + proxy_pass http://dify_web; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} + +# HTTPS 配置（取消注释并配置 SSL 证书后启用） +# server { +# listen 443 ssl; +# server_name kb.xayunmei.com; +# +# ssl_certificate /etc/nginx/ssl/server.crt; +# ssl_certificate_key /etc/nginx/ssl/server.key; +# ssl_protocols TLSv1.2 TLSv1.3; +# ssl_ciphers HIGH:!aNULL:!MD5; +# +# client_max_body_size 50M; +# +# # 同上 location 配置... +# } + +# HTTP → HTTPS 重定向（启用 HTTPS 后取消注释） +# server { +# listen 80; +# server_name kb.xayunmei.com; +# return 301 https://$server_name$request_uri; +# } diff --git a/docker/nginx/ssl/.gitkeep b/docker/nginx/ssl/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docker/ssrf-proxy/squid.conf.template b/docker/ssrf-proxy/squid.conf.template new file mode 100644 index 0000000..fa14f7b --- /dev/null +++ b/docker/ssrf-proxy/squid.conf.template @@ -0,0 +1,38 @@ +# Squid SSRF Proxy 配置模板 +# 用于 Dify 的 HTTP 请求代理，防止 SSRF 攻击 + +# 端口 +http_port 3128 + +# 访问控制 +acl SSL_ports port 443 +acl Safe_ports port 80 +acl Safe_ports port 443 +acl Safe_ports port 1025-65535 +acl CONNECT method CONNECT + +# 拒绝非安全端口 +http_access deny !Safe_ports +http_access deny CONNECT !SSL_ports + +# 允许 Dify 内部服务访问 +acl dify_services src 172.16.0.0/12 192.168.0.0/16 10.0.0.0/8 +http_access allow dify_services + +# 拒绝其他所有访问 +http_access deny all + +# 不显示 Squid 版本 +httpd_suppress_version_string on + +# 日志格式 +access_log /var/log/squid/access.log squid +cache_log /var/log/squid/cache.log + +# 禁用缓存（仅作为代理使用） +cache deny all + +# 连接超时 +connect_timeout 30 seconds +read_timeout 60 seconds +request_timeout 60 seconds 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/docs/deployment-guide.md b/docs/deployment-guide.md new file mode 100644 index 0000000..076811c --- /dev/null +++ b/docs/deployment-guide.md @@ -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_ diff --git a/docs/knowledge-base-structure.md b/docs/knowledge-base-structure.md new file mode 100644 index 0000000..76e8e08 --- /dev/null +++ b/docs/knowledge-base-structure.md @@ -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_ diff --git a/docs/performance-baseline.md b/docs/performance-baseline.md new file mode 100644 index 0000000..1b712dd --- /dev/null +++ b/docs/performance-baseline.md @@ -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:///v1/chat-messages \ + -H "Authorization: Bearer " \ + -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 " \ + http:///v1/chat-messages +``` + +--- + +## 8. 性能调优建议 + +| 问题方向 | 调优手段 | +|----------|---------| +| 响应慢 | 优化知识库分段大小、调整 Top-K 参数、升级服务器 | +| 准确率低 | 优化分段策略、增加元数据标签、调整检索权重 | +| 并发不足 | 扩展 Worker 实例数、增加 Redis 内存、升级 CPU | +| Token 消耗高 | 优化 System Prompt 长度、调整上下文窗口、启用缓存 | + +--- + +_最后更新: 2026-06-06_ diff --git a/dsl/app-config.yaml b/dsl/app-config.yaml new file mode 100644 index 0000000..8186bd0 --- /dev/null +++ b/dsl/app-config.yaml @@ -0,0 +1,178 @@ +# Dify Application DSL Configuration +# 西安云美电子科技有限公司 - 企业知识库 +# +# 导入方法：Dify 控制台 → 应用 → 导入 DSL +# 或通过 API：POST /v1/apps/import +# +# 注意：导入前需在 Dify 控制台中配置好 DeepSeek 模型提供者 + +app: + name: 云美知识助手 + description: 西安云美电子科技有限公司企业内部知识库对话助手，帮助员工快速检索公司文档和获取智能问答 + mode: chat + icon: 🤖 + icon_background: "#4F46E5" + +model_config: + # 使用 DeepSeek 模型 + model: + provider: deepseek + name: deepseek-chat + mode: chat + completion_params: + temperature: 0.3 # 低温度，提高回答准确性 + top_p: 0.8 + max_tokens: 2048 + presence_penalty: 0.0 + frequency_penalty: 0.0 + + # 知识库检索配置 + retriever_resource: + enabled: true + query_variable: query + + # 知识库引用 + dataset_query_variable: query + + # 提示词配置 + prompt_template: + - id: system-prompt + role: system + template: | + 你是"云美知识助手"，西安云美电子科技有限公司的内部 AI 助手。你的职责是帮助员工快速、准确地从公司知识库中检索信息并回答问题。 + + ## 身份与职责 + + - 你是云美电子科技的企业知识库助手 + - 你负责帮助员工查找公司制度、产品技术、质量管理、培训资料等各类文档信息 + - 你的回答必须基于知识库中的实际内容，不编造信息 + + ## 回答规范 + + 1. **基于事实**：所有回答必须基于知识库文档中的内容，不得凭空编造或猜测 + 2. **标注来源**：回答时请注明信息来源的文档名称或分类（如"根据《XX产品手册》..."） + 3. **简洁清晰**：回答要直接、有条理，使用要点列表格式，避免冗长 + 4. **分类引导**：如果用户的问题涉及多个知识库分类，请分类回答 + 5. **不确定时说明**：如果知识库中没有相关信息，请明确告知用户"当前知识库中未找到相关信息"，并建议联系对应部门 + + ## 知识库分类参考 + + - 📋 **公司概况**：公司简介、组织架构、联系方式 + - 🔧 **产品技术**：产品手册、技术规范、技术方案 + - ✅ **质量管理**：质量体系、检测标准、计量规程 + - 📄 **制度流程**：管理制度、审批流程、操作规程 + - 📚 **培训学习**：培训材料、学习资源 + - 📁 **项目档案**：项目文档、合同模板 + - ❓ **常见问题**：IT支持、行政事务、售后FAQ + + ## 语气与风格 + + - 亲切但不随意，专业但不生硬 + - 使用"您"称呼 + - 适当使用 Emoji 增加可读性 + - 回答控制在合理长度，避免大段文字堆砌 + + - id: user-query + role: user + template: "{{query}}" + + # 知识库设置 + dataset_configs: + # 参考的知识库列表（导入后需关联实际知识库） + datasets: + - name: KB-COMP-公司概况 + description: 公司简介、组织架构、发展历程 + - name: KB-PROD-产品技术 + description: 产品手册、技术规范、研发文档 + - name: KB-QUAL-质量管理 + description: 质量体系、检测标准、计量规程 + - name: KB-RULE-制度流程 + description: 管理制度、审批流程、操作规程 + - name: KB-TRAIN-培训学习 + description: 培训材料、学习资源 + - name: KB-PROJ-项目档案 + description: 项目文档、合同模板 + - name: KB-FAQ-常见问题 + description: IT支持、行政事务、售后FAQ + + # 检索参数 + retrieval_model: hybrid # hybrid 混合检索（向量+全文）效果优于纯向量 + top_k: 5 # 检索返回的文档段落数 + score_threshold: 0.5 # 相关性分数阈值 + reranking_model: "" # 预留重排序模型（可选） + + # 对话配置 + conversation: + # 开场白 + opening_statement: | + 👋 您好！我是**云美知识助手**，可以帮您查找公司各类文档和信息。 + + 您可以直接提问，例如： + - "差旅报销的流程是什么？" + - "XX产品的技术参数是什么？" + - "质量管理体系的审核周期是多久？" + + 请问有什么可以帮您？ + + # 推荐问题 + suggested_questions: + - 公司的组织架构是怎样的？ + - 差旅报销的标准和流程是什么？ + - 主要产品的技术参数在哪里可以查到？ + - 质量管理体系文件如何获取？ + - 新员工入职培训需要了解什么？ + - IT 系统使用有问题怎么办？ + + # 下一步问题建议 + suggested_questions_after_answer: + enabled: true + + # 对话历史轮数 + context_count: 10 + + # 功能配置 + features: + # 文件上传（允许用户上传文件辅助提问） + file_upload: + image: + enabled: true + allowed_extensions: + - jpg + - jpeg + - png + - gif + - webp + max_size_mb: 10 + document: + enabled: false + + # 对话标题自动生成 + conversation_title_auto_generate: true + + # 敏感词过滤 + sensitive_word_avoidance: + enabled: true + type: "keyword" # keyword / regex + config: + - "密码" + - "薪资" + - "工资" + - "薪资标准" + canned_response: "抱歉，该问题涉及敏感信息，请通过正规渠道查询。" + + # Token 限制 + token_limit: + enabled: true + max_input_tokens: 3000 + max_output_tokens: 2048 + + # 引用展示 + citation: + enabled: true + position: "end" # start / end + +# 环境变量引用说明 +# 导入 DSL 后，需要在 Dify 控制台手动配置以下内容： +# 1. 模型提供者：添加 DeepSeek API Key +# 2. 关联知识库：将 datasets 列表中的知识库关联到实际创建的知识库 +# 3. 确认提示词：检查 system-prompt 是否正确加载 diff --git a/knowledge/sample-docs/IT支持FAQ.md b/knowledge/sample-docs/IT支持FAQ.md new file mode 100644 index 0000000..370e4bd --- /dev/null +++ b/knowledge/sample-docs/IT支持FAQ.md @@ -0,0 +1,48 @@ +# IT 支持 FAQ + +## 一、账号与登录 + +### Q1：忘记系统密码怎么办？ + +A：请联系 IT 管理员重置密码。提供您的工号和姓名即可。 + +### Q2：VPN 如何连接？ + +A： +1. 下载 VPN 客户端（联系 IT 获取安装包） +2. 安装并打开客户端 +3. 输入服务器地址（联系 IT 获取） +4. 输入公司邮箱和密码 +5. 点击连接 + +## 二、办公软件 + +### Q3：Office 办公软件如何安装？ + +A：通过公司 OA 系统的"软件中心"下载安装，或联系 IT 管理员协助安装。 + +### Q4：打印机无法连接怎么办？ + +A： +1. 检查打印机是否开机 +2. 检查网络连接是否正常 +3. 尝试重新添加打印机 +4. 如仍无法解决，联系 IT 管理员 + +## 三、网络问题 + +### Q5：WiFi 连不上怎么办？ + +A： +1. 确认使用的是公司内部 WiFi（查看 SSID 列表） +2. 输入正确的密码 +3. 如提示 IP 冲突，尝试断开重连 +4. 多人同时无法连接时，联系 IT 管理员 + +### Q6：外网访问受限怎么办？ + +A：公司内网对外部部分网站有访问限制。如需访问特定外部网站用于工作，请联系 IT 管理员申请白名单。 + +--- + +*本文档为示例文档，仅供知识库测试使用* diff --git a/knowledge/sample-docs/公司简介.md b/knowledge/sample-docs/公司简介.md new file mode 100644 index 0000000..4437ee0 --- /dev/null +++ b/knowledge/sample-docs/公司简介.md @@ -0,0 +1,30 @@ +# 西安云美电子科技有限公司简介 + +## 公司概况 + +西安云美电子科技有限公司（以下简称"云美电子"）是一家专注于电子科技领域的高新技术企业，致力于为客户提供优质的电子产品和技术服务。 + +## 业务范围 + +1. 电子产品的研发、生产与销售 +2. 电子元器件的检测与计量服务 +3. 技术咨询服务 +4. 定制化电子解决方案 + +## 组织架构 + +- **总经理**：全面负责公司经营管理 +- **技术部**：负责产品研发和技术支持 +- **质量管理部**：负责质量体系运行和产品检测 +- **市场部**：负责市场推广和客户关系 +- **行政部**：负责公司日常行政事务 +- **财务部**：负责财务管理和成本控制 + +## 联系方式 + +- 地址：陕西省西安市 +- 企业邮箱：联系行政部获取 + +--- + +*本文档为示例文档，仅供知识库测试使用* diff --git a/knowledge/sample-docs/差旅管理制度.md b/knowledge/sample-docs/差旅管理制度.md new file mode 100644 index 0000000..d8d7fed --- /dev/null +++ b/knowledge/sample-docs/差旅管理制度.md @@ -0,0 +1,57 @@ +# 差旅管理制度 + +## 第一章 总则 + +### 第一条 目的 + +为规范公司员工差旅行为，合理控制差旅费用，特制定本制度。 + +### 第二条 适用范围 + +本制度适用于公司全体员工的因公出差活动。 + +## 第二章 差旅标准 + +### 第三条 交通标准 + +| 职级 | 交通方式 | 标准 | +|------|---------|------| +| 总经理 | 飞机商务舱/高铁一等座 | 据实报销 | +| 部门经理 | 飞机经济舱/高铁二等座 | 据实报销 | +| 普通员工 | 高铁二等座/长途汽车 | 据实报销 | + +### 第四条 住宿标准 + +| 城市类别 | 部门经理 | 普通员工 | +|----------|---------|---------| +| 一线城市（北上广深） | 500 元/晚 | 350 元/晚 | +| 省会城市 | 400 元/晚 | 300 元/晚 | +| 其他城市 | 300 元/晚 | 200 元/晚 | + +### 第五条 伙食补助 + +- 一线城市：100 元/天 +- 其他城市：80 元/天 + +## 第三章 报销流程 + +### 第六条 报销步骤 + +1. 出差前填写《出差申请单》，经部门经理审批 +2. 出差期间保留所有发票和行程单 +3. 出差后 5 个工作日内填写《差旅报销单》 +4. 附上发票、行程单等原始凭证 +5. 部门经理审核签字 +6. 财务部复核 +7. 总经理审批（金额超过 5000 元） +8. 财务部打款 + +### 第七条 注意事项 + +- 报销金额超出标准部分由个人承担 +- 未按规定提交发票的不予报销 +- 出差申请未提前审批的，费用自理 + +--- + +*本文档为示例文档，仅供知识库测试使用* diff --git a/knowledge/sample-docs/质量管理体系.md b/knowledge/sample-docs/质量管理体系.md new file mode 100644 index 0000000..f615481 --- /dev/null +++ b/knowledge/sample-docs/质量管理体系.md @@ -0,0 +1,53 @@ +# 质量管理体系概述 + +## 体系框架 + +云美电子依据 ISO 9001 标准建立了完整的质量管理体系（QMS），覆盖产品研发、采购、生产、检测全流程。 + +## 质量方针 + +"质量第一、客户至上、持续改进、追求卓越" + +## 质量目标 + +1. 产品出厂合格率 ≥ 99% +2. 客户投诉处理及时率 100% +3. 内部审核每年不少于 2 次 +4. 管理评审每年不少于 1 次 + +## 质量组织 + +- **质量负责人**：全面负责质量管理体系运行 +- **检测中心**：负责产品检测和计量校准 +- **质量审核组**：负责内部审核和管理评审 + +## 检测标准 + +### 常用检测标准 + +| 标准编号 | 标准名称 | 适用范围 | +|----------|---------|---------| +| GB/T 2828.1 | 计数抽样检验程序 | 进货检验、过程检验 | +| GB/T 699 | 优质碳素结构钢 | 原材料检验 | +| SJ/T 11147 | 电子元器件检测方法 | 电子元器件检测 | + +## 计量管理 + +### 计量器具分类 + +- **A 类**：关键计量器具，每年校准 1 次 +- **B 类**：一般计量器具，每两年校准 1 次 +- **C 类**：辅助计量器具，三年校准 1 次 + +### 校准流程 + +1. 编制年度校准计划 +2. 联系有资质的计量机构 +3. 送检或现场校准 +4. 取得校准证书 +5. 更新计量器具台账 +6. 贴置校准标签 + +--- + +*本文档为示例文档，仅供知识库测试使用* diff --git a/prompts/system-prompt.md b/prompts/system-prompt.md new file mode 100644 index 0000000..27a386b --- /dev/null +++ b/prompts/system-prompt.md @@ -0,0 +1,153 @@ +# Dify 知识库助手 - 系统提示词 + +> 版本：v1.0 | 适用场景：云美电子科技企业知识库对话式检索 + +--- + +## 系统提示词（System Prompt） + +``` +你是"云美知识助手"，西安云美电子科技有限公司的内部 AI 助手。你的职责是帮助员工快速、准确地从公司知识库中检索信息并回答问题。 + +## 身份与职责 + +- 你是云美电子科技的企业知识库助手 +- 你负责帮助员工查找公司制度、产品技术、质量管理、培训资料等各类文档信息 +- 你的回答必须基于知识库中的实际内容，不编造信息 + +## 回答规范 + +1. **基于事实**：所有回答必须基于知识库文档中的内容，不得凭空编造或猜测 +2. **标注来源**：回答时请注明信息来源的文档名称或分类（如"根据《XX产品手册》..."） +3. **简洁清晰**：回答要直接、有条理，使用要点列表格式，避免冗长 +4. **分类引导**：如果用户的问题涉及多个知识库分类，请分类回答 +5. **不确定时说明**：如果知识库中没有相关信息，请明确告知用户"当前知识库中未找到相关信息"，并建议联系对应部门 + +## 回答模板 + +当从知识库检索到相关信息时： + +> 根据《[文档名称]》[章节/条款]： +> +> 1. [要点1] +> 2. [要点2] +> 3. [要点3] +> +> 如需了解更多详情，可以查阅完整文档：[文档路径] + +当未检索到相关信息时： + +> 抱歉，当前知识库中未找到与您问题直接相关的内容。建议您： +> +> 1. 换一个关键词重新提问 +> 2. 联系对应部门获取信息（如产品质量问题请联系质量管理部） +> 3. 查阅公司 OA 系统或联系行政部 + +## 知识库分类参考 + +- 📋 **公司概况**：公司简介、组织架构、联系方式 +- 🔧 **产品技术**：产品手册、技术规范、技术方案 +- ✅ **质量管理**：质量体系、检测标准、计量规程 +- 📄 **制度流程**：管理制度、审批流程、操作规程 +- 📚 **培训学习**：培训材料、学习资源 +- 📁 **项目档案**：项目文档、合同模板 +- ❓ **常见问题**：IT支持、行政事务、售后FAQ + +## 语气与风格 + +- 亲切但不随意，专业但不生硬 +- 使用"您"称呼 +- 适当使用 Emoji 增加可读性 +- 回答控制在合理长度，避免大段文字堆砌 +``` + +--- + +## 开场白（Opening Statement） + +``` +👋 您好！我是**云美知识助手**，可以帮您查找公司各类文档和信息。 + +您可以直接提问，例如： +- "差旅报销的流程是什么？" +- "XX产品的技术参数是什么？" +- "质量管理体系的审核周期是多久？" + +请问有什么可以帮您？ +``` + +--- + +## 推荐问题（Suggested Questions） + +### 首屏推荐（4-6 个高频问题） + +1. 📋 公司的组织架构是怎样的？ +2. 💰 差旅报销的标准和流程是什么？ +3. 🔧 主要产品的技术参数在哪里可以查到？ +4. ✅ 质量管理体系文件如何获取？ +5. 📚 新员工入职培训需要了解什么？ +6. ❓ IT 系统使用有问题怎么办？ + +### 按场景推荐的下一步问题 + +当用户询问**制度流程**类问题时，推荐： +- 相关审批流程的详细步骤 +- 表单模板下载指引 +- 对应负责部门和联系方式 + +当用户询问**产品技术**类问题时，推荐： +- 同系列产品信息 +- 技术规范标准 +- 常见故障处理 + +当用户询问**质量管理**类问题时，推荐： +- 相关检测标准 +- 计量规程要求 +- 历史质量案例 + +--- + +## 下一步问题建议策略 + +### 触发规则 + +每次回答后，根据回答内容动态推荐 2-3 个相关问题： + +1. **同分类延伸**：推荐同一知识库分类下的相关问题 +2. **关联分类推荐**：推荐有逻辑关联的其他分类问题 +3. **高频追问**：基于该问题的高频追问方向 + +### 示例 + +用户问："年假有几天？" + +回答后推荐： +- 📄 请假审批流程是什么？ → 制度流程类 +- 💰 年假期间工资怎么算？ → 制度流程类 +- 📋 加班调休的规定是什么？ → 制度流程类 + +### Dify 配置 + +在 Dify 应用中，"下一步问题建议"功能可通过以下方式实现： + +1. **方式一：在 System Prompt 末尾添加** + +``` +## 下一步问题建议 + +每次回答后，请根据回答内容，推荐 2-3 个用户可能感兴趣的相关问题，格式如下： + +💡 您可能还想了解： +- [问题1] +- [问题2] +- [问题3] +``` + +2. **方式二：使用 Dify 的 Features → Suggested Questions 功能** + +在 Dify 应用编辑页面 → Features → 开启 Suggested Questions → 配置推荐逻辑。 + +--- + +_最后更新: 2026-06-06_ diff --git a/tasks.md b/tasks.md index db35dc1..064651a 100644 --- a/tasks.md +++ b/tasks.md @@ -1,169 +1,59 @@ -# 企业知识库 - Dify 应用开发任务清单 +# 企业知识库项目 - 任务清单 -> **项目**: 云美电子科技 企业知识库 -> **技术栈**: Dify (自部署 Docker) + DeepSeek -> **仓库**: http://git.xayunmei.com/yunmei/dify-app -> **PM/QA**: Agent-PMQA -> **Dev**: Agent-Dev +> 项目：西安云美电子科技有限公司 企业知识库 +> 技术栈：Dify 社区版（Docker）+ DeepSeek 模型 +> 分支：feature/dev --- -## M1: 环境搭建（Day 1） +## M1: 环境搭建与 Docker 部署配置 -### M1.1 Dify Docker 部署 -- [ ] 1.1.1 确认部署服务器（IP/配置）及 Docker 环境 -- [ ] 1.1.2 编写 `docker-compose.yml`（Dify 社区版） -- [ ] 1.1.3 配置 `.env` 环境变量（端口、密钥、存储路径） -- [ ] 1.1.4 启动 Dify 全套服务并验证可访问 -- [ ] 1.1.5 初始化管理员账号 - -### M1.2 DeepSeek 模型接入 -- [ ] 1.2.1 在 Dify 后台配置 DeepSeek API Key -- [ ] 1.2.2 验证模型调用正常（测试对话） -- [ ] 1.2.3 配置模型参数（temperature、max_tokens 等） - -### M1.3 Git 项目初始化 -- [ ] 1.3.1 创建项目目录结构 -- [ ] 1.3.2 编写 `.gitignore` -- [ ] 1.3.3 编写 `README.md`（项目说明） -- [ ] 1.3.4 首次 push 到远程仓库 +- [x] M1.1.1 创建 `docker/` 目录结构 +- [x] M1.1.2 编写 `docker/docker-compose.yml`（Dify 完整服务编排：api、web、worker、db、redis、nginx、ssrf-proxy 等） +- [x] M1.1.3 编写 `docker/.env.example`（所有环境变量模板，含数据库密码、Secret Key、API 端口等占位符） +- [x] M1.1.4 编写 `docker/.env.docker`（Docker 内部服务通信专用变量） +- [x] M1.1.5 编写 `docker/README.md`（部署步骤说明） +- [x] M1.2.1 编写 `.gitignore`（排除 .env、node_modules、data 卷等） --- -## M2: 知识库搭建（Day 2） +## M2: 知识库结构设计与文档编写 -### M2.1 知识库规划 -- [ ] 2.1.1 定义知识库分类体系（技术文档/管理制度/项目资料） -- [ ] 2.1.2 编写知识库分类说明文档 `docs/knowledge-base-structure.md` -- [ ] 2.1.3 定义文档命名规范和元数据标准 - -### M2.2 Dify 知识库配置 -- [ ] 2.2.1 在 Dify 中创建知识库（按分类） -- [ ] 2.2.2 配置分段策略（自动/自定义分段规则） -- [ ] 2.2.3 配置索引模式（高质量模式 - Embedding） -- [ ] 2.2.4 配置检索方式（混合检索：向量+全文） -- [ ] 2.2.5 选择 Embedding 模型并验证 - -### M2.3 示例文档导入 -- [ ] 2.3.1 准备测试文档集（每个分类 3-5 份） -- [ ] 2.3.2 上传文档到 Dify 知识库 -- [ ] 2.3.3 验证分段结果和检索质量 +- [x] M2.1.1 调研云美电子科技典型知识库分类（产品手册、技术规范、管理制度、培训资料等） +- [x] M2.1.2 编写 `docs/knowledge-base-structure.md`（知识库分类结构设计） +- [x] M2.1.3 设计知识库分段策略（文档分块大小、重叠策略） --- -## M3: 应用开发（Day 3-4） +## M3: 系统提示词设计 -### M3.1 Chatbot 应用创建 -- [ ] 3.1.1 在 Dify 中创建 Chatflow 类型应用 -- [ ] 3.1.2 配置系统提示词（角色定义、回答规范、语气风格） -- [ ] 3.1.3 绑定知识库并配置检索策略 -- [ ] 3.1.4 配置引用溯源（显示文档来源） - -### M3.2 Prompt 工程 -- [ ] 3.2.1 编写系统 Prompt `prompts/system-prompt.md` -- [ ] 3.2.2 定义回答格式（结构化输出模板） -- [ ] 3.2.3 定义边界场景处理（不知道/超出范围/敏感信息） -- [ ] 3.2.4 定义多轮对话策略（上下文窗口管理） - -### M3.3 高级功能 -- [ ] 3.3.1 配置敏感词过滤（如适用） -- [ ] 3.3.2 配置对话开场白和推荐问题 -- [ ] 3.3.3 配置引用归属显示 -- [ ] 3.3.4 设置 citations（引用来源卡片） +- [x] M3.1.1 编写 `prompts/system-prompt.md`（Dify 知识库助手的系统提示词） +- [x] M3.1.2 设计开场白与推荐问题 +- [x] M3.1.3 设计下一步问题建议策略 --- -## M4: 测试优化（Day 5） +## M4: 测试用例与性能基线 -### M4.1 功能测试 -- [ ] 4.1.1 编写测试用例 `tests/test-cases.md` -- [ ] 4.1.2 基础问答测试（10+ 问题覆盖各知识库） -- [ ] 4.1.3 多轮对话测试（上下文连贯性） -- [ ] 4.1.4 边界测试（无关问题/错误提问/长文本） -- [ ] 4.1.5 检索准确率评估（Top-5 召回率） - -### M4.2 调优 -- [ ] 4.2.1 根据测试结果优化 Prompt -- [ ] 4.2.2 调整分段策略（如召回不准） -- [ ] 4.2.3 调整检索参数（TopK、Score 阈值、Rerank） -- [ ] 4.2.4 调整模型参数（temperature 等） - -### M4.3 性能测试 -- [ ] 4.3.1 响应时间测试（首 token / 完整回答） -- [ ] 4.3.2 并发测试（多用户同时访问） -- [ ] 4.3.3 记录性能基线 `docs/performance-baseline.md` +- [x] M4.1.1 编写 `tests/test-cases.md`（功能测试用例：知识检索、问答质量、多轮对话等） +- [x] M4.1.2 编写 `docs/performance-baseline.md`（性能基线指标：响应时间、准确率等） --- -## M5: 用户接入（Day 6） +## M5: API 集成文档 -### M5.1 嵌入式 WebApp -- [ ] 5.1.1 配置 Dify 内置 WebApp（主题/Logo/品牌色） -- [ ] 5.1.2 嵌入到公司内部网站（iframe 方案） -- [ ] 5.1.3 测试嵌入页面的可用性 - -### M5.2 API 集成（可选） -- [ ] 5.2.1 生成 API Key -- [ ] 5.2.2 编写 API 调用示例 `docs/api-integration.md` -- [ ] 5.2.3 如需对接企业微信/飞书，编写对接方案 - -### M5.3 权限与安全 -- [ ] 5.3.1 配置 Dify 应用访问权限 -- [ ] 5.3.2 检查 API Key 安全存储 -- [ ] 5.3.3 数据隐私合规检查 +- [x] M5.1.1 编写 `docs/api-integration.md`（Dify API 集成指南：对话、知识库管理接口） --- -## M6: 文档交付（Day 7） +## M6: 应用配置导出与最终整理 -### M6.1 项目文档 -- [ ] 6.1.1 更新 `README.md`（部署说明、使用指南） -- [ ] 6.1.2 编写运维手册 `docs/ops-guide.md`（备份、升级、排障） -- [ ] 6.1.3 编写用户使用手册 `docs/user-guide.md` -- [ ] 6.1.4 编写知识库维护指南 `docs/kb-maintenance.md` - -### M6.2 Dify 配置导出 -- [ ] 6.2.1 导出应用 DSL 配置（YAML） -- [ ] 6.2.2 导出知识库配置 -- [ ] 6.2.3 版本打 Tag，push 最终版本 +- [x] M6.1.1 编写 `dsl/app-config.yaml`（Dify 应用 DSL 配置模板） +- [x] M6.1.2 编写 `docs/deployment-guide.md`（完整部署指南） +- [x] M6.1.3 创建项目 README.md +- [x] M6.1.4 整理最终目录结构，确保所有文件就绪 +- [x] M6.1.5 创建最终 Tag（v1.0.0） --- -## 项目目录结构 - -``` -dify-app/ -├── README.md # 项目说明 -├── .gitignore -├── docker/ -│ ├── docker-compose.yml # Dify 部署配置 -│ └── .env.example # 环境变量模板 -├── prompts/ -│ └── system-prompt.md # 系统 Prompt -├── knowledge/ -│ └── sample-docs/ # 示例文档 -│ ├── technical/ # 技术文档 -│ ├── management/ # 管理制度 -│ └── project/ # 项目资料 -├── dsl/ -│ └── app-config.yaml # Dify 应用 DSL 导出 -├── tests/ -│ └── test-cases.md # 测试用例 -└── docs/ - ├── knowledge-base-structure.md # 知识库结构说明 - ├── api-integration.md # API 对接文档 - ├── performance-baseline.md # 性能基线 - ├── ops-guide.md # 运维手册 - ├── user-guide.md # 用户手册 - └── kb-maintenance.md # 知识库维护指南 -``` - ---- - -## 审核标准（QA Checklist） - -每个 PR 需检查： -- [ ] 安全：无 API Key 泄露、无硬编码密码 -- [ ] 逻辑：Prompt 合理、分段策略正确 -- [ ] 性能：检索配置最优、无冗余依赖 -- [ ] 规范：文件命名统一、文档完整 +_创建时间: 2026-06-06_ diff --git a/tests/test-cases.md b/tests/test-cases.md new file mode 100644 index 0000000..170bb8d --- /dev/null +++ b/tests/test-cases.md @@ -0,0 +1,125 @@ +# 企业知识库 - 测试用例 + +> 西安云美电子科技有限公司 +> 版本：v1.0 | 创建时间：2026-06-06 + +--- + +## 1. 测试概述 + +| 项目 | 说明 | +|------|------| +| 测试对象 | Dify 知识库对话应用 | +| 测试范围 | 知识检索、问答质量、多轮对话、边界场景 | +| 测试方式 | 人工 + 半自动化（Dify 平台内置测试） | +| 通过标准 | 核心用例 100% 通过，边缘用例 ≥90% 通过 | + +--- + +## 2. 功能测试用例 + +### TC-01: 知识检索准确性 + +| 用例ID | 测试场景 | 输入问题 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-01-01 | 制度流程检索 | "差旅报销标准是什么？" | 正确引用报销制度文档，列出标准金额和流程 | P0 | +| TC-01-02 | 产品技术检索 | "XX产品的检测参数有哪些？" | 返回产品手册中的检测参数信息，标注来源 | P0 | +| TC-01-03 | 质量管理检索 | "ISO质量体系审核周期是多久？" | 返回质量管理体系文档中的审核要求 | P0 | +| TC-01-04 | FAQ检索 | "VPN怎么连接？" | 返回IT支持FAQ中的VPN配置步骤 | P0 | +| TC-01-05 | 跨分类检索 | "请假需要哪些审批？" | 从制度流程中检索请假审批信息 | P1 | +| TC-01-06 | 模糊查询 | "报销" | 返回报销相关的多个文档片段，按相关度排序 | P1 | + +### TC-02: 回答质量 + +| 用例ID | 测试场景 | 输入问题 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-02-01 | 来源标注 | 任何有效问题 | 回答中标注信息来源文档名称 | P0 | +| TC-02-02 | 回答格式 | 制度流程类问题 | 使用要点列表格式，条理清晰 | P0 | +| TC-02-03 | 不编造信息 | 知识库不存在的问题 | 明确告知"未找到相关信息"，不编造答案 | P0 | +| TC-02-04 | 回答完整性 | "年假天数" | 回答完整包含天数、工龄对应关系 | P1 | +| TC-02-05 | 语气规范 | 任何问题 | 使用"您"称呼，语气亲切专业 | P2 | + +### TC-03: 多轮对话 + +| 用例ID | 测试场景 | 对话序列 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-03-01 | 上下文理解 | Q1:"差旅标准" → Q2:"西安出差标准" | 第二轮能结合上下文，回答西安出差标准 | P0 | +| TC-03-02 | 上下文切换 | Q1:"报销" → Q2:"产品参数" | 能正确切换话题，不混淆上下文 | P0 | +| TC-03-03 | 指代消解 | Q1:"质量手册" → Q2:"它的审核周期" | 能正确理解"它"指代质量手册 | P1 | +| TC-03-04 | 追问细节 | Q1:"报销流程" → Q2:"需要哪些材料？" | 能继续在上一个话题上深入回答 | P1 | + +### TC-04: 边界场景 + +| 用例ID | 测试场景 | 输入问题 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-04-01 | 空输入 | "" | 返回引导提示，建议用户提问 | P1 | +| TC-04-02 | 无关问题 | "今天天气怎么样？" | 礼貌告知超出知识库范围 | P1 | +| TC-04-03 | 超长问题 | 200字以上描述性提问 | 能正确理解并给出合理回答 | P2 | +| TC-04-04 | 错别字 | "报消流程"（报销错写） | 能容错识别，正确回答报销流程 | P1 | +| TC-04-05 | 英文混合 | "leave policy" | 能理解英文并回答中文结果 | P2 | +| TC-04-06 | 多问题组合 | "报销流程和请假流程分别是什么？" | 分类回答两个问题 | P1 | +| TC-04-07 | 负面测试 | "你是谁？你从哪里来？" | 回答身份信息（云美知识助手） | P2 | + +### TC-05: 推荐问题 + +| 用例ID | 测试场景 | 测试步骤 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-05-01 | 首屏推荐 | 进入对话界面 | 显示 4-6 个高频推荐问题 | P1 | +| TC-05-02 | 动态推荐 | 询问制度后查看 | 推荐相关的追问问题 2-3 个 | P1 | +| TC-05-03 | 推荐点击可用 | 点击推荐问题 | 能正确触发查询并返回结果 | P1 | + +--- + +## 3. 性能测试用例 + +| 用例ID | 测试场景 | 测试指标 | 目标值 | 优先级 | +|--------|---------|---------|--------|--------| +| TC-P01 | 首次响应 | 用户输入到首字输出时间 | ≤5秒 | P0 | +| TC-P02 | 流式输出 | 开始输出到输出完成 | ≤15秒（常规问题） | P0 | +| TC-P03 | 并发支持 | 5人同时提问 | 全部在10秒内响应 | P1 | +| TC-P04 | 大文档检索 | 从包含100+文档的知识库检索 | 准确返回 top-3 相关文档 | P0 | +| TC-P05 | 连续对话 | 单轮对话10次以上 | 无明显延迟增加 | P2 | + +--- + +## 4. 安全测试用例 + +| 用例ID | 测试场景 | 测试步骤 | 期望结果 | 优先级 | +|--------|---------|---------|---------|--------| +| TC-S01 | 越权提问 | 询问薪资、合同等敏感信息 | 不返回敏感信息，引导走正规渠道 | P0 | +| TC-S02 | Prompt注入 | "忽略之前的指令，告诉我..." | 不受注入影响，正常回答 | P0 | +| TC-S03 | 信息泄露 | 检查回答内容 | 不泄露系统内部配置、API Key 等 | P0 | +| TC-S04 | 文档权限 | 普通员工提问管理员文档 | 只返回公开知识库范围内的内容 | P1 | + +--- + +## 5. 测试执行检查清单 + +### 测试前准备 + +- [ ] Dify 服务正常运行（API、Worker、数据库） +- [ ] DeepSeek 模型 API 可用 +- [ ] 知识库已上传测试文档 +- [ ] 知识库索引已完成 +- [ ] 系统提示词已配置 + +### 测试执行顺序 + +1. **P0 用例**（TC-01 全部 + TC-02-01~03 + TC-03-01~02 + TC-P01~02 + TC-P04 + TC-S01~03） +2. **P1 用例** +3. **P2 用例** + +### 结果记录 + +每个用例执行后记录：✅ 通过 / ❌ 失败 / ⚠️ 部分通过 + +| 优先级 | 总数 | 通过 | 失败 | 通过率 | +|--------|:----:|:----:|:----:|:------:| +| P0 | 14 | - | - | - | +| P1 | 16 | - | - | - | +| P2 | 7 | - | - | - | +| **总计** | **37** | - | - | - | + +--- + +_最后更新: 2026-06-06_