Ragflow-Plus 快速入门指南 #

1. 目的与范围 #

本文档为 Ragflow-Plus 的快速入门指南，帮助新用户快速部署、配置和使用系统。本文档涵盖系统要求、快速部署、初始配置、基本工作流和 API 使用示例。

有关详细部署说明，请参阅 部署与配置。有关开发指南，请参阅 开发指南。

2. 前置条件与系统要求 #

2.1 硬件要求 #

2.1.1 CPU 模式（最低配置） #

• CPU：4 核以上
• 内存：8GB 以上
• 存储：50GB 以上可用空间
• 网络：稳定的互联网连接

2.1.2 GPU 模式（推荐配置） #

• CPU：8 核以上
• 内存：16GB 以上
• GPU：NVIDIA GPU，显存 8GB 以上
• 存储：100GB 以上可用空间（SSD 推荐）

2.2 软件要求 #

• 操作系统：Linux (Ubuntu 20.04+)、macOS、Windows (WSL2)
• Docker：20.10+
• Docker Compose：2.0+
• Git：2.0+

2.3 可选依赖 #

• NVIDIA Docker：GPU 模式需要（nvidia-docker2）
• Python：3.10+（本地开发需要）
• Node.js：18+（前端开发需要）

3. 快速部署 #

3.1 使用 Docker Compose 部署（推荐） #

3.1.1 克隆仓库 #

git clone https://github.com/zstar1003/ragflow-plus.git
cd ragflow-plus

3.1.2 配置环境变量 #

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量（可选，默认值通常可用）
nano .env

3.1.3 启动服务 #

# CPU 模式
docker-compose up -d

# GPU 模式（需要 NVIDIA GPU）
docker-compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

3.1.4 验证部署 #

# 检查服务状态
docker-compose ps

# 查看日志
docker-compose logs -f ragflowplus-server

# 健康检查
curl http://localhost:9380/health

3.2 访问服务 #

部署成功后，可以通过以下地址访问：

• 用户前端：http://localhost:80
• 管理前端：http://localhost:8888
• API 服务：http://localhost:9380
• API 文档：http://localhost:9380/api-docs

3.3 停止服务 #

# 停止服务
docker-compose down

# 停止并删除数据卷（谨慎使用）
docker-compose down -v

4. 初始配置 #

4.1 创建管理员账户 #

1. 访问管理前端：http://localhost:8888
2. 使用默认管理员账户登录（首次部署需要创建）
3. 或通过 API 创建：

curl -X POST http://localhost:5000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "管理员",
    "email": "admin@example.com",
    "password": "admin123"
  }'

4.2 配置 LLM 模型 #

4.2.1 通过管理界面配置 #

1. 登录管理前端
2. 进入"配置管理"
3. 配置 LLM API 密钥和端点

4.2.2 通过环境变量配置 #

# .env
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=bge-m3
CHAT_MODEL=gpt-4

4.3 创建租户和团队 #

1. 登录管理前端
2. 进入"团队管理"
3. 创建新团队
4. 添加团队成员

5. 基本工作流 #

5.1 创建知识库 #

5.1.1 通过用户界面 #

1. 登录用户前端：http://localhost:80
2. 点击"知识库管理"
3. 点击"新建知识库"
4. 输入知识库名称
5. 选择嵌入模型（默认：bge-m3）
6. 点击"创建"

5.1.2 通过 API #

curl -X POST http://localhost:9380/api/v1/knowledgebases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "我的知识库",
    "tenant_id": "tenant_123",
    "embedding_model": "bge-m3"
  }'

5.2 上传文档 #

5.2.1 通过用户界面 #

1. 进入知识库详情页
2. 点击"上传文档"
3. 选择文件（支持 PDF、DOCX、TXT、MD 等）
4. 等待文档处理完成

5.2.2 通过 API #

curl -X POST http://localhost:9380/api/v1/document/upload_and_parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "kb_id=kb_123" \
  -F "file=@document.pdf"

5.3 开始对话 #

5.3.1 通过用户界面 #

1. 进入知识库
2. 点击"开始对话"
3. 输入问题
4. 查看 AI 回答和引用来源

5.3.2 通过 API #

curl -X GET "http://localhost:9380/api/v1/completion?kb_id=kb_123&question=什么是RAG?" \
  -H "Authorization: Bearer YOUR_TOKEN"

6. API 使用示例 #

6.1 认证 #

import requests

# 登录获取 token
response = requests.post('http://localhost:9380/api/v1/login', json={
    'email': 'user@example.com',
    'password': 'password123'
})

token = response.json()['data']['token']

# 使用 token 访问 API
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

6.2 创建知识库 #

import requests

response = requests.post(
    'http://localhost:9380/api/v1/knowledgebases',
    headers=headers,
    json={
        'name': '技术文档库',
        'tenant_id': 'tenant_123',
        'embedding_model': 'bge-m3'
    }
)

kb_id = response.json()['data']['id']
print(f"知识库ID: {kb_id}")

6.3 上传文档 #

import requests

with open('document.pdf', 'rb') as f:
    response = requests.post(
        'http://localhost:9380/api/v1/document/upload_and_parse',
        headers={'Authorization': headers['Authorization']},
        files={'file': f},
        data={'kb_id': kb_id}
    )

doc_id = response.json()['data']['id']
print(f"文档ID: {doc_id}")

6.4 流式对话 #

import requests
import json

def stream_chat(kb_id: str, question: str):
    """流式对话"""
    url = f'http://localhost:9380/api/v1/completion'
    params = {
        'kb_id': kb_id,
        'question': question
    }

    response = requests.get(
        url,
        params=params,
        headers=headers,
        stream=True
    )

    for line in response.iter_lines():
        if line:
            data = line.decode('utf-8')
            if data.startswith('data: '):
                event_data = json.loads(data[6:])
                if event_data['type'] == 'content':
                    print(event_data['content'], end='', flush=True)
                elif event_data['type'] == 'done':
                    print('\n对话完成')

# 使用
stream_chat(kb_id, '什么是RAG?')

7. 交互式聊天与文档编写 #

7.1 使用聊天功能 #

1. 访问聊天界面

   • 登录用户前端
   • 选择知识库
   • 点击"开始对话"

2. 发送消息

   • 在输入框输入问题
   • 按 Enter 或点击"发送"
   • 查看 AI 回答和引用来源

3. 查看对话历史

   • 左侧显示对话列表
   • 点击对话查看历史消息
   • 可以继续之前的对话

7.2 使用文档编写功能 #

1. 创建新文档

   • 点击"文档编写"
   • 开始编写内容

2. 使用 AI 助手

   • 选中文本
   • 点击"AI 助手"
   • 输入指令（如"总结这段内容"）
   • 查看 AI 生成的内容

3. 导出文档

   • 点击"导出"
   • 选择格式（Word、PDF、Markdown）
   • 下载文件

8. 常见问题 #

8.1 服务无法启动 #

问题：Docker 容器无法启动

解决方案：

1. 检查 Docker 服务是否运行：docker ps
2. 查看容器日志：docker-compose logs
3. 检查端口是否被占用：netstat -tulpn | grep 9380
4. 检查环境变量配置是否正确

8.2 文档处理失败 #

问题：上传的文档处理失败

解决方案：

1. 检查文档格式是否支持
2. 查看文档处理日志
3. 检查 MinerU 服务是否正常运行
4. 确认 Elasticsearch 连接正常

8.3 对话无响应 #

问题：发送消息后无响应

解决方案：

1. 检查知识库是否有文档
2. 确认 LLM 配置正确
3. 查看 API 日志
4. 检查网络连接

8.4 性能问题 #

问题：系统响应缓慢

解决方案：

1. 检查服务器资源使用情况
2. 优化 Elasticsearch 配置
3. 使用 GPU 模式加速
4. 增加服务器资源

9. 下一步 #

9.1 深入学习 #

• 阅读 系统架构 了解系统设计
• 阅读 API 参考 了解 API 详情
• 阅读 开发指南 参与开发

9.2 高级功能 #

• 自定义模型：配置自己的 LLM 模型
• 批量导入：批量上传和处理文档
• API 集成：将系统集成到现有应用
• 性能优化：优化系统性能

9.3 社区支持 #

• GitHub Issues：报告问题和建议
• 文档贡献：改进文档
• 代码贡献：提交 Pull Request

10. 总结 #

本文档提供了 Ragflow-Plus 的快速入门指南，包括：

• 系统要求：硬件和软件要求
• 快速部署：Docker Compose 一键部署
• 初始配置：管理员账户和 LLM 配置
• 基本工作流：创建知识库、上传文档、开始对话
• API 示例：Python 代码示例
• 常见问题：故障排除指南

通过遵循本文档的步骤，您可以快速开始使用 Ragflow-Plus 系统。