在实际项目中将大语言模型LLM与个人或企业的私有数据结合构建一个能精准回答特定领域问题的智能助手是许多开发者和技术团队的核心需求。单纯依赖通用大模型的“通识”能力往往无法满足对准确性、时效性和数据安全性的要求。RAG检索增强生成技术通过“检索相关文档片段 基于片段生成答案”的模式为解决这一问题提供了成熟路径。然而从概念到落地中间隔着环境配置、服务部署、流程串联和问题排查等诸多环节。本文将聚焦于使用 DeepSeek 和 RAGFlow 这两个开源工具在本地环境搭建一个功能完整的个人知识库系统。DeepSeek 作为性能优异的开源大模型提供了本地部署的可能RAGFlow 则是一个基于 Docker 的开源 RAG 引擎它简化了文档解析、向量化检索和问答流水线的构建。整个流程涉及 Docker 环境准备、DeepSeek 模型服务部署、RAGFlow 服务部署、知识库创建与文档上传以及最终的问答测试。即使没有深厚的大模型或 Docker 背景按照本文的步骤也能在本地机器上构建起一个可运行、可查询的私有知识库原型为后续更复杂的生产级应用打下基础。1. 理解 RAG 工作流与核心组件选型在开始动手部署之前需要先厘清整个系统的工作原理以及为什么选择 DeepSeek 和 RAGFlow 这两个组件。这有助于在后续配置和排错时能够清晰地知道每个环节在做什么。1.1 RAG 的基本工作流程RAG 并非一个单一的模型而是一个系统架构。其核心思想是在生成答案前先从外部知识库中检索出与问题最相关的文档片段然后将这些片段和问题一起提交给大模型指令模型“基于给定的上下文回答问题”。一个典型的 RAG 系统包含以下步骤文档处理与索引将原始文档如 PDF、Word、TXT进行解析、分块然后通过嵌入模型Embedding Model转换为向量并存入向量数据库Vector Database建立索引。问题检索当用户提出问题时同样使用嵌入模型将问题转换为向量然后在向量数据库中搜索与之最相似的文档片段即向量相似度计算。提示词构建与答案生成将检索到的相关片段作为“上下文”与用户问题一起构造成一个详细的提示词Prompt发送给大语言模型LLM由 LLM 生成最终答案。这样做的好处是答案来源于提供的文档准确性更高无需重新训练模型成本低可以随时通过更新文档库来更新知识。1.2 为什么选择 DeepSeek 和 RAGFlow在本地部署场景下组件选型需要综合考虑性能、资源消耗、易用性和开源许可。DeepSeek是一个系列的开源大语言模型由深度求索公司发布。选择它的原因包括开源免费模型权重可下载允许商业使用没有调用次数和费用限制。性能强劲在多项公开基准测试中其最新版本如 DeepSeek-V2表现接近或超越部分闭源模型。适合本地部署提供了不同规模的模型如 7B、16B、67B 等用户可以根据自身硬件条件主要是 GPU 显存选择。对于个人知识库7B 或 16B 的量化版本通常能在消费级显卡上流畅运行。API 兼容性其提供的推理服务通常兼容 OpenAI API 格式这极大方便了与上游应用如 RAGFlow的集成。RAGFlow是一个开源的 RAG 引擎其核心优势在于“开箱即用”和“深度可定制”文档解析能力强内置 OCR 和文档解析能力能较好地处理扫描件、表格、图表等复杂格式的文档。可视化配置提供了 Web 界面可以直观地创建知识库、上传文档、配置检索策略和测试问答降低了使用门槛。流水线清晰将文档解析、文本分块、向量化、检索、重排序、提示词构建等环节模块化流程清晰。支持多种后端支持连接多种向量数据库如 Milvus, DashVector和 LLM兼容 OpenAI API 的模型服务架构灵活。将两者结合即用 RAGFlow 作为 RAG 流程的“大脑”和“调度中心”用 DeepSeek 作为本地部署的“答案生成器”可以构建一个完全自主可控的私有知识库系统。2. 部署环境准备与依赖检查本地部署的成功与否很大程度上取决于前期环境是否准备妥当。本节将详细说明所需的软硬件环境并提供详细的检查清单。2.1 硬件与操作系统要求CPU建议四核以上。文档解析和向量计算对 CPU 有一定要求。内存至少 16GB。运行 Docker 容器、向量数据库和大模型服务需要较多内存。存储至少 50GB 可用空间。用于存放 Docker 镜像、模型文件、向量索引和文档。GPU非必需但强烈推荐如果希望获得流畅的问答体验建议配备 NVIDIA GPU。显存要求取决于部署的 DeepSeek 模型大小DeepSeek-Coder-V2-Lite 7B 量化版约 6GB 显存。DeepSeek-V2-Lite 16B 量化版约 12GB 显存。若无 GPU也可使用 CPU 推理但速度会慢很多。操作系统Linux (Ubuntu 20.04/22.04, CentOS 7/8) 或 macOS。Windows 用户建议使用 WSL2 (Windows Subsystem for Linux)。本文后续命令以 Linux/WSL2 环境为例。2.2 核心软件依赖安装2.2.1 Docker 与 Docker ComposeRAGFlow 官方推荐使用 Docker Compose 进行一键部署因此必须先安装 Docker 和 Docker Compose。安装 Docker# 以 Ubuntu 为例使用官方脚本安装 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入 docker 组避免每次使用 sudo sudo usermod -aG docker $USER # 退出当前终端并重新登录使组权限生效安装完成后运行以下命令验证docker --version应输出类似Docker version 24.0.7, build afdd53b的信息。安装 Docker Compose Docker Compose 现在通常作为 Docker Desktop 的一部分或可通过插件形式安装。对于 Linux可以单独安装# 下载 Docker Compose 二进制文件 (请检查 GitHub 发布页获取最新版本) sudo curl -L https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker-compose --version应输出类似Docker Compose version v2.24.0的信息。2.2.2 NVIDIA 容器工具包仅限 GPU 用户如果系统有 NVIDIA GPU 并打算用于模型推理需要安装 NVIDIA Container Toolkit使 Docker 容器能够调用 GPU。# 添加 NVIDIA 容器仓库 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker安装后运行docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi测试。如果能看到 GPU 信息则配置成功。2.2.3 模型下载工具可选但推荐DeepSeek 模型文件较大数 GB 到数十 GB建议使用git-lfs或huggingface-cli进行下载。# 安装 git-lfs sudo apt-get install git-lfs git lfs install # 或者安装 huggingface-cli pip install huggingface-hub2.3 环境检查清单在进入下一步之前请对照下表检查你的环境检查项命令预期结果Docker 服务状态sudo systemctl is-active dockeractiveDocker 命令权限docker ps(不加 sudo)列出容器或为空不报权限错误Docker Compose 版本docker-compose --version显示版本号 (v2.x)GPU 可用性 (如有)docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi显示 GPU 详细信息磁盘空间df -h /可用空间 50GB内存free -h可用内存 8GB3. 部署 DeepSeek 模型推理服务我们将使用一个兼容 OpenAI API 的推理框架来部署 DeepSeek 模型这样 RAGFlow 就可以像调用 OpenAI 一样调用我们本地的模型。这里以vLLM和Ollama两种常见方案为例。3.1 方案一使用 vLLM 部署高性能推荐vLLM 是一个高性能的 LLM 推理和服务库尤其擅长注意力键值缓存的内存管理吞吐量高。拉取 Docker 镜像docker pull vllm/vllm-openai:latest下载 DeepSeek 模型权重 前往 Hugging Face 模型库例如deepseek-ai/DeepSeek-V2-Lite-Chat选择你需要的模型。使用git-lfs克隆或直接下载。# 示例下载 DeepSeek-V2-Lite 16B 模型 (确保磁盘空间足够) git lfs install git clone https://huggingface.co/deepseek-ai/DeepSeek-V2-Lite-Chat ./models/DeepSeek-V2-Lite-Chat注意模型文件很大下载可能需要很长时间。也可以先下载量化版本如-awq后缀以减少显存占用。启动 vLLM OpenAI API 服务 假设模型权重路径为/path/to/your/models/DeepSeek-V2-Lite-Chat。docker run --runtime nvidia --gpus all \ -v /path/to/your/models:/models \ -p 8000:8000 \ --name deepseek-vllm \ vllm/vllm-openai:latest \ --model /models/DeepSeek-V2-Lite-Chat \ --served-model-name deepseek-chat \ --api-key token-abc123 \ --max-model-len 8192参数解释--runtime nvidia --gpus all指定使用 NVIDIA GPU。-v ...将主机上的模型目录挂载到容器内的/models。-p 8000:8000将容器的 8000 端口映射到主机的 8000 端口。--model指定容器内的模型路径。--served-model-name服务发布的模型名称调用时会用到。--api-key设置一个 API 密钥RAGFlow 连接时需要。--max-model-len模型支持的最大上下文长度根据模型实际情况设置。验证服务 服务启动后使用curl测试curl http://localhost:8000/v1/models应该返回包含deepseek-chat模型信息的 JSON。也可以测试聊天接口curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer token-abc123 \ -d { model: deepseek-chat, messages: [{role: user, content: Hello, who are you?}], temperature: 0.7 }如果收到包含模型自我介绍的回答说明服务运行正常。3.2 方案二使用 Ollama 部署更简易Ollama 提供了更简单的模型管理和运行方式适合快速入门。安装并启动 Ollama# 下载安装脚本并执行 curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 服务 ollama serve 拉取并运行 DeepSeek 模型 Ollama 官方可能提供了 DeepSeek 模型也可以从社区获取。例如# 拉取模型 (例如 deepseek-coder:6.7b) ollama pull deepseek-coder:6.7b # 以 OpenAI API 兼容模式运行 OLLAMA_HOST0.0.0.0 ollama run deepseek-coder:6.7bOllama 默认的 OpenAI 兼容 API 端口是 11434。启动后可以通过http://localhost:11434/v1/chat/completions进行访问。3.3 模型服务配置要点无论使用哪种方案最终都是提供一个兼容 OpenAI API 的 HTTP 端点。你需要记录以下信息用于后续配置 RAGFlowAPI Base URL如http://你的服务器IP:8000/v1或http://localhost:11434/v1。API Key如果服务端设置了密钥如 vLLM 的--api-key则需要记录。Model Name服务发布的模型名称如deepseek-chat。4. 部署与配置 RAGFlowRAGFlow 提供了官方的 Docker Compose 文件可以一键启动所有依赖服务包括 MySQL、Redis、向量数据库等。4.1 获取 RAGFlow 部署文件克隆仓库或下载 Compose 文件git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker或者直接下载docker-compose.yml文件。检查并修改环境变量配置 在docker目录下通常有一个.env或config文件用于配置。关键配置项包括HTTP_PORTRAGFlow Web 界面的访问端口默认为 9380。数据库、Redis、向量数据库的连接信息通常使用默认值即可因为它们在 Docker 网络内互通。最重要的LLM 的配置。需要找到配置 LLM 的地方将其指向我们刚刚部署的 DeepSeek 服务。以常见的配置为例你可能需要编辑docker-compose.yml或同级目录下的一个配置文件。查找LLM_API_KEY,LLM_API_BASE,LLM_MODEL等环境变量。如果没有则需要在 RAGFlow 启动后通过其 Web 界面进行配置。4.2 启动 RAGFlow 服务在包含docker-compose.yml的目录下执行docker-compose up -d-d参数表示在后台运行。首次运行会拉取多个镜像RAGFlow server, MySQL, Redis, Milvus 等需要一定时间。可以使用docker-compose logs -f查看启动日志。当看到所有容器状态均为Up时表示启动成功docker-compose ps4.3 通过 Web 界面配置 LLM打开浏览器访问http://你的服务器IP:9380。首次访问会进入初始化页面可能需要设置管理员账号密码。登录后进入系统设置或模型管理页面。这里需要添加一个“自定义模型”或“本地模型”。填写配置信息模型名称自定义如My-DeepSeek。模型类型选择OpenAI或OpenAI-Compatible。API Base URL填写你的 DeepSeek 服务地址如http://host.docker.internal:8000/v1。注意如果 RAGFlow 运行在 Docker 容器内而 DeepSeek 服务运行在宿主机不能直接用localhost。在 Linux/macOS 的 Docker 桌面版或使用特定网络模式下可以使用host.docker.internal指向宿主机。在纯 Linux 环境下可能需要使用宿主机的实际 IP 地址并确保防火墙开放了相应端口。API Key填写在启动 vLLM 时设置的--api-key如token-abc123。如果没设置或使用 Ollama 默认无密钥可以留空或填dummy。模型名称填写 DeepSeek 服务发布的模型名如deepseek-chat。上下文长度根据模型能力填写如8192。保存配置并测试连接。如果配置正确RAGFlow 会提示连接成功。4.4 常见部署问题排查问题现象可能原因检查与解决RAGFlow 容器启动失败端口冲突、镜像拉取失败、权限不足1.docker-compose logs 服务名查看具体错误。2. 检查 9380、3306MySQL、6379Redis、19530Milvus端口是否被占用。3. 确认 Docker 有足够权限和资源。Web 界面无法访问防火墙未开放端口、容器未成功启动1.docker-compose ps确认所有服务状态为Up。2. 在服务器本机用curl http://localhost:9380测试。3. 检查服务器安全组/防火墙规则放行 9380 端口。LLM 连接测试失败API Base URL 或网络不通1. 在 RAGFlow 容器内执行curl 你的 DeepSeek API URL/models看是否能通。2. 确保 DeepSeek 服务正在运行 (docker ps或ollama list)。3. 正确使用host.docker.internal或宿主机 IP。上传文档后处理失败解析器依赖缺失、内存不足1. 查看 RAGFlow 服务日志看是否有 OCR 或解析错误。2. 确保 Docker 容器分配了足够内存可在docker-compose.yml中配置mem_limit。3. 尝试上传一个简单的纯文本文件测试。5. 构建与测试你的第一个知识库当 DeepSeek 服务和 RAGFlow 都正常运行并成功连接后就可以开始构建知识库了。5.1 创建知识库在 RAGFlow Web 界面点击“知识库” - “新建知识库”。填写知识库名称、描述并选择嵌入模型。RAGFlow 内置了bge-large-zh等模型对于中文文档效果较好保持默认即可。也可以选择其他兼容的嵌入模型。配置文本分块Chunking策略分块大小通常设置在 256-1024 个字符或 token之间。太小会丢失上下文太大会降低检索精度。对于普通文档512 是一个不错的起点。重叠大小相邻文本块之间重叠的字符数通常为分块大小的 10%-20%。这有助于避免一个答案被切分到两个块边界。配置检索策略检索器类型通常选择“向量检索”。Top K每次检索返回的最相关片段数量通常设为 3-5。重排序Rerank这是一个可选但能提升精度的步骤。如果启用检索到的 Top K 个片段会经过一个更精细的排序模型再次排序将最相关的放在前面。如果硬件资源允许建议开启。5.2 上传与处理文档在创建好的知识库中点击“上传文档”。支持多种格式PDF、Word、PPT、TXT、Markdown甚至图片需 OCR。上传后RAGFlow 会自动进行以下流水线处理解析提取文档中的文本、表格、图片文字。分块按照之前设定的策略将文本切割成片段。向量化使用嵌入模型将每个文本片段转换为向量。入库将向量和元数据存入向量数据库如 Milvus。你可以在“文档”列表中查看处理状态。状态变为“已索引”后文档就可供检索了。5.3 进行问答测试进入知识库的“对话”或“测试”页面。在输入框中提问。问题应基于你上传的文档内容。观察回答。一个运行良好的 RAG 系统其回答应该准确答案内容来源于上传的文档。可追溯回答下方通常会附上“参考来源”点击可以定位到原文片段。这是 RAG 区别于普通聊天模型的关键特征。自然语言流畅像是基于文档内容组织的答案而不是生硬地拼接片段。示例测试上传文档一份关于“项目管理办法”的 PDF。提问“项目评审会议需要哪些人参加”期望回答应列出文档中规定的参会人员角色并附上对应的原文出处。5.4 优化检索效果如果发现回答不准确或未找到相关信息可以从以下几个方面优化调整分块策略对于结构严谨的文档如 API 文档可以适当增大分块大小对于内容松散的文档可以减小分块大小。优化提问方式尝试使用更接近文档原文表述的关键词进行提问。检查文档解析质量在文档详情页查看解析出的原始文本是否正确特别是表格和图片中的文字。启用重排序如果之前未启用可以开启重排序功能它能有效提升答案相关性。调整 Top K 值适当增加 Top K 值让模型看到更多候选片段但可能会引入噪声。6. 生产环境考量与最佳实践将本地知识库用于个人学习或 demo 验证是一回事若要用于团队协作或轻度生产环境则需要考虑更多因素。6.1 安全性加固访问控制RAGFlow 自带用户角色管理。务必为不同使用者创建账号并分配适当的权限如只读、可上传、可管理。API 密钥管理DeepSeek 服务如果设置了 API Key应妥善保管。不要在代码或配置文件中硬编码可以考虑使用环境变量或密钥管理服务。网络隔离将 DeepSeek 和 RAGFlow 服务部署在内网仅通过反向代理如 Nginx暴露必要的 Web 界面端口并配置 HTTPS。文档审核建立文档上传前的审核机制避免错误或敏感信息进入知识库。6.2 性能与稳定性资源监控使用docker stats或nvidia-smi监控容器和 GPU 的资源使用情况CPU、内存、显存。为关键容器如 DeepSeek 服务设置资源限制防止其耗尽主机资源。# 在 docker run 命令中限制资源 --memory 16g --memory-swap 20g --cpus 4模型量化如果 GPU 显存紧张务必使用量化版本的 DeepSeek 模型如 AWQ, GPTQ 量化这可以大幅降低显存占用仅轻微损失精度。服务高可用对于重要服务可以考虑使用 Docker Swarm 或 Kubernetes 进行容器编排实现故障自动恢复和水平扩展。至少应为数据库MySQL, Milvus配置持久化存储卷防止数据丢失。# 在 docker-compose.yml 中为 Milvus 配置卷 volumes: - milvus_data:/var/lib/milvus日志与告警配置 Docker 容器的日志驱动将日志集中收集到 ELK 或 Loki 等系统。对服务健康状态如 HTTP 端口探活设置告警。6.3 知识库维护版本管理知识库文档会更新。RAGFlow 支持文档更新后重新索引。建议建立文档版本管理制度并在上传新版本后触发对旧文档的删除和重新索引操作。定期评估定期用一组标准问题测试知识库评估回答的准确率和相关性。根据结果调整分块、检索策略或考虑更新嵌入模型。冷门知识处理对于极少被查询的冷门知识可以考虑将其存入传统数据库进行关键词检索与 RAG 形成互补。6.4 扩展方向多模态RAGFlow 支持图片 OCR。可以探索上传带有图表、示意图的文档构建能回答“根据某张图说明...”问题的知识库。联网搜索结合 Tavily、Serper 等工具在本地知识库无法回答时自动进行网络搜索并将结果补充到上下文中。Agent 集成将本地知识库作为工具接入到 LangChain、AutoGen 等智能体框架中让 Agent 在规划任务时能够主动查询知识库。更复杂的流水线RAGFlow 支持自定义推理流程。可以尝试在检索后加入更复杂的处理如调用多个模型进行验证、总结等。搭建本地知识库的过程本质上是将数据、算法和工程进行有机结合。从环境准备、服务部署、配置对接到效果调优每一步都可能遇到问题。关键是要理解每个组件的职责和它们之间的交互协议如 OpenAI API。当问答不准确时要有清晰的排查思路是文档没解析好分块不合理检索策略不对还是大模型本身的理解或生成有问题通过日志、中间结果如检索到的片段一步步定位才能让这个系统真正为你所用。 基于DeepSeek与RAGFlow的本地私有知识库搭建实战
在实际项目中将大语言模型LLM与个人或企业的私有数据结合构建一个能精准回答特定领域问题的智能助手是许多开发者和技术团队的核心需求。单纯依赖通用大模型的“通识”能力往往无法满足对准确性、时效性和数据安全性的要求。RAG检索增强生成技术通过“检索相关文档片段 基于片段生成答案”的模式为解决这一问题提供了成熟路径。然而从概念到落地中间隔着环境配置、服务部署、流程串联和问题排查等诸多环节。本文将聚焦于使用 DeepSeek 和 RAGFlow 这两个开源工具在本地环境搭建一个功能完整的个人知识库系统。DeepSeek 作为性能优异的开源大模型提供了本地部署的可能RAGFlow 则是一个基于 Docker 的开源 RAG 引擎它简化了文档解析、向量化检索和问答流水线的构建。整个流程涉及 Docker 环境准备、DeepSeek 模型服务部署、RAGFlow 服务部署、知识库创建与文档上传以及最终的问答测试。即使没有深厚的大模型或 Docker 背景按照本文的步骤也能在本地机器上构建起一个可运行、可查询的私有知识库原型为后续更复杂的生产级应用打下基础。1. 理解 RAG 工作流与核心组件选型在开始动手部署之前需要先厘清整个系统的工作原理以及为什么选择 DeepSeek 和 RAGFlow 这两个组件。这有助于在后续配置和排错时能够清晰地知道每个环节在做什么。1.1 RAG 的基本工作流程RAG 并非一个单一的模型而是一个系统架构。其核心思想是在生成答案前先从外部知识库中检索出与问题最相关的文档片段然后将这些片段和问题一起提交给大模型指令模型“基于给定的上下文回答问题”。一个典型的 RAG 系统包含以下步骤文档处理与索引将原始文档如 PDF、Word、TXT进行解析、分块然后通过嵌入模型Embedding Model转换为向量并存入向量数据库Vector Database建立索引。问题检索当用户提出问题时同样使用嵌入模型将问题转换为向量然后在向量数据库中搜索与之最相似的文档片段即向量相似度计算。提示词构建与答案生成将检索到的相关片段作为“上下文”与用户问题一起构造成一个详细的提示词Prompt发送给大语言模型LLM由 LLM 生成最终答案。这样做的好处是答案来源于提供的文档准确性更高无需重新训练模型成本低可以随时通过更新文档库来更新知识。1.2 为什么选择 DeepSeek 和 RAGFlow在本地部署场景下组件选型需要综合考虑性能、资源消耗、易用性和开源许可。DeepSeek是一个系列的开源大语言模型由深度求索公司发布。选择它的原因包括开源免费模型权重可下载允许商业使用没有调用次数和费用限制。性能强劲在多项公开基准测试中其最新版本如 DeepSeek-V2表现接近或超越部分闭源模型。适合本地部署提供了不同规模的模型如 7B、16B、67B 等用户可以根据自身硬件条件主要是 GPU 显存选择。对于个人知识库7B 或 16B 的量化版本通常能在消费级显卡上流畅运行。API 兼容性其提供的推理服务通常兼容 OpenAI API 格式这极大方便了与上游应用如 RAGFlow的集成。RAGFlow是一个开源的 RAG 引擎其核心优势在于“开箱即用”和“深度可定制”文档解析能力强内置 OCR 和文档解析能力能较好地处理扫描件、表格、图表等复杂格式的文档。可视化配置提供了 Web 界面可以直观地创建知识库、上传文档、配置检索策略和测试问答降低了使用门槛。流水线清晰将文档解析、文本分块、向量化、检索、重排序、提示词构建等环节模块化流程清晰。支持多种后端支持连接多种向量数据库如 Milvus, DashVector和 LLM兼容 OpenAI API 的模型服务架构灵活。将两者结合即用 RAGFlow 作为 RAG 流程的“大脑”和“调度中心”用 DeepSeek 作为本地部署的“答案生成器”可以构建一个完全自主可控的私有知识库系统。2. 部署环境准备与依赖检查本地部署的成功与否很大程度上取决于前期环境是否准备妥当。本节将详细说明所需的软硬件环境并提供详细的检查清单。2.1 硬件与操作系统要求CPU建议四核以上。文档解析和向量计算对 CPU 有一定要求。内存至少 16GB。运行 Docker 容器、向量数据库和大模型服务需要较多内存。存储至少 50GB 可用空间。用于存放 Docker 镜像、模型文件、向量索引和文档。GPU非必需但强烈推荐如果希望获得流畅的问答体验建议配备 NVIDIA GPU。显存要求取决于部署的 DeepSeek 模型大小DeepSeek-Coder-V2-Lite 7B 量化版约 6GB 显存。DeepSeek-V2-Lite 16B 量化版约 12GB 显存。若无 GPU也可使用 CPU 推理但速度会慢很多。操作系统Linux (Ubuntu 20.04/22.04, CentOS 7/8) 或 macOS。Windows 用户建议使用 WSL2 (Windows Subsystem for Linux)。本文后续命令以 Linux/WSL2 环境为例。2.2 核心软件依赖安装2.2.1 Docker 与 Docker ComposeRAGFlow 官方推荐使用 Docker Compose 进行一键部署因此必须先安装 Docker 和 Docker Compose。安装 Docker# 以 Ubuntu 为例使用官方脚本安装 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入 docker 组避免每次使用 sudo sudo usermod -aG docker $USER # 退出当前终端并重新登录使组权限生效安装完成后运行以下命令验证docker --version应输出类似Docker version 24.0.7, build afdd53b的信息。安装 Docker Compose Docker Compose 现在通常作为 Docker Desktop 的一部分或可通过插件形式安装。对于 Linux可以单独安装# 下载 Docker Compose 二进制文件 (请检查 GitHub 发布页获取最新版本) sudo curl -L https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker-compose --version应输出类似Docker Compose version v2.24.0的信息。2.2.2 NVIDIA 容器工具包仅限 GPU 用户如果系统有 NVIDIA GPU 并打算用于模型推理需要安装 NVIDIA Container Toolkit使 Docker 容器能够调用 GPU。# 添加 NVIDIA 容器仓库 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker安装后运行docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi测试。如果能看到 GPU 信息则配置成功。2.2.3 模型下载工具可选但推荐DeepSeek 模型文件较大数 GB 到数十 GB建议使用git-lfs或huggingface-cli进行下载。# 安装 git-lfs sudo apt-get install git-lfs git lfs install # 或者安装 huggingface-cli pip install huggingface-hub2.3 环境检查清单在进入下一步之前请对照下表检查你的环境检查项命令预期结果Docker 服务状态sudo systemctl is-active dockeractiveDocker 命令权限docker ps(不加 sudo)列出容器或为空不报权限错误Docker Compose 版本docker-compose --version显示版本号 (v2.x)GPU 可用性 (如有)docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi显示 GPU 详细信息磁盘空间df -h /可用空间 50GB内存free -h可用内存 8GB3. 部署 DeepSeek 模型推理服务我们将使用一个兼容 OpenAI API 的推理框架来部署 DeepSeek 模型这样 RAGFlow 就可以像调用 OpenAI 一样调用我们本地的模型。这里以vLLM和Ollama两种常见方案为例。3.1 方案一使用 vLLM 部署高性能推荐vLLM 是一个高性能的 LLM 推理和服务库尤其擅长注意力键值缓存的内存管理吞吐量高。拉取 Docker 镜像docker pull vllm/vllm-openai:latest下载 DeepSeek 模型权重 前往 Hugging Face 模型库例如deepseek-ai/DeepSeek-V2-Lite-Chat选择你需要的模型。使用git-lfs克隆或直接下载。# 示例下载 DeepSeek-V2-Lite 16B 模型 (确保磁盘空间足够) git lfs install git clone https://huggingface.co/deepseek-ai/DeepSeek-V2-Lite-Chat ./models/DeepSeek-V2-Lite-Chat注意模型文件很大下载可能需要很长时间。也可以先下载量化版本如-awq后缀以减少显存占用。启动 vLLM OpenAI API 服务 假设模型权重路径为/path/to/your/models/DeepSeek-V2-Lite-Chat。docker run --runtime nvidia --gpus all \ -v /path/to/your/models:/models \ -p 8000:8000 \ --name deepseek-vllm \ vllm/vllm-openai:latest \ --model /models/DeepSeek-V2-Lite-Chat \ --served-model-name deepseek-chat \ --api-key token-abc123 \ --max-model-len 8192参数解释--runtime nvidia --gpus all指定使用 NVIDIA GPU。-v ...将主机上的模型目录挂载到容器内的/models。-p 8000:8000将容器的 8000 端口映射到主机的 8000 端口。--model指定容器内的模型路径。--served-model-name服务发布的模型名称调用时会用到。--api-key设置一个 API 密钥RAGFlow 连接时需要。--max-model-len模型支持的最大上下文长度根据模型实际情况设置。验证服务 服务启动后使用curl测试curl http://localhost:8000/v1/models应该返回包含deepseek-chat模型信息的 JSON。也可以测试聊天接口curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer token-abc123 \ -d { model: deepseek-chat, messages: [{role: user, content: Hello, who are you?}], temperature: 0.7 }如果收到包含模型自我介绍的回答说明服务运行正常。3.2 方案二使用 Ollama 部署更简易Ollama 提供了更简单的模型管理和运行方式适合快速入门。安装并启动 Ollama# 下载安装脚本并执行 curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 服务 ollama serve 拉取并运行 DeepSeek 模型 Ollama 官方可能提供了 DeepSeek 模型也可以从社区获取。例如# 拉取模型 (例如 deepseek-coder:6.7b) ollama pull deepseek-coder:6.7b # 以 OpenAI API 兼容模式运行 OLLAMA_HOST0.0.0.0 ollama run deepseek-coder:6.7bOllama 默认的 OpenAI 兼容 API 端口是 11434。启动后可以通过http://localhost:11434/v1/chat/completions进行访问。3.3 模型服务配置要点无论使用哪种方案最终都是提供一个兼容 OpenAI API 的 HTTP 端点。你需要记录以下信息用于后续配置 RAGFlowAPI Base URL如http://你的服务器IP:8000/v1或http://localhost:11434/v1。API Key如果服务端设置了密钥如 vLLM 的--api-key则需要记录。Model Name服务发布的模型名称如deepseek-chat。4. 部署与配置 RAGFlowRAGFlow 提供了官方的 Docker Compose 文件可以一键启动所有依赖服务包括 MySQL、Redis、向量数据库等。4.1 获取 RAGFlow 部署文件克隆仓库或下载 Compose 文件git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker或者直接下载docker-compose.yml文件。检查并修改环境变量配置 在docker目录下通常有一个.env或config文件用于配置。关键配置项包括HTTP_PORTRAGFlow Web 界面的访问端口默认为 9380。数据库、Redis、向量数据库的连接信息通常使用默认值即可因为它们在 Docker 网络内互通。最重要的LLM 的配置。需要找到配置 LLM 的地方将其指向我们刚刚部署的 DeepSeek 服务。以常见的配置为例你可能需要编辑docker-compose.yml或同级目录下的一个配置文件。查找LLM_API_KEY,LLM_API_BASE,LLM_MODEL等环境变量。如果没有则需要在 RAGFlow 启动后通过其 Web 界面进行配置。4.2 启动 RAGFlow 服务在包含docker-compose.yml的目录下执行docker-compose up -d-d参数表示在后台运行。首次运行会拉取多个镜像RAGFlow server, MySQL, Redis, Milvus 等需要一定时间。可以使用docker-compose logs -f查看启动日志。当看到所有容器状态均为Up时表示启动成功docker-compose ps4.3 通过 Web 界面配置 LLM打开浏览器访问http://你的服务器IP:9380。首次访问会进入初始化页面可能需要设置管理员账号密码。登录后进入系统设置或模型管理页面。这里需要添加一个“自定义模型”或“本地模型”。填写配置信息模型名称自定义如My-DeepSeek。模型类型选择OpenAI或OpenAI-Compatible。API Base URL填写你的 DeepSeek 服务地址如http://host.docker.internal:8000/v1。注意如果 RAGFlow 运行在 Docker 容器内而 DeepSeek 服务运行在宿主机不能直接用localhost。在 Linux/macOS 的 Docker 桌面版或使用特定网络模式下可以使用host.docker.internal指向宿主机。在纯 Linux 环境下可能需要使用宿主机的实际 IP 地址并确保防火墙开放了相应端口。API Key填写在启动 vLLM 时设置的--api-key如token-abc123。如果没设置或使用 Ollama 默认无密钥可以留空或填dummy。模型名称填写 DeepSeek 服务发布的模型名如deepseek-chat。上下文长度根据模型能力填写如8192。保存配置并测试连接。如果配置正确RAGFlow 会提示连接成功。4.4 常见部署问题排查问题现象可能原因检查与解决RAGFlow 容器启动失败端口冲突、镜像拉取失败、权限不足1.docker-compose logs 服务名查看具体错误。2. 检查 9380、3306MySQL、6379Redis、19530Milvus端口是否被占用。3. 确认 Docker 有足够权限和资源。Web 界面无法访问防火墙未开放端口、容器未成功启动1.docker-compose ps确认所有服务状态为Up。2. 在服务器本机用curl http://localhost:9380测试。3. 检查服务器安全组/防火墙规则放行 9380 端口。LLM 连接测试失败API Base URL 或网络不通1. 在 RAGFlow 容器内执行curl 你的 DeepSeek API URL/models看是否能通。2. 确保 DeepSeek 服务正在运行 (docker ps或ollama list)。3. 正确使用host.docker.internal或宿主机 IP。上传文档后处理失败解析器依赖缺失、内存不足1. 查看 RAGFlow 服务日志看是否有 OCR 或解析错误。2. 确保 Docker 容器分配了足够内存可在docker-compose.yml中配置mem_limit。3. 尝试上传一个简单的纯文本文件测试。5. 构建与测试你的第一个知识库当 DeepSeek 服务和 RAGFlow 都正常运行并成功连接后就可以开始构建知识库了。5.1 创建知识库在 RAGFlow Web 界面点击“知识库” - “新建知识库”。填写知识库名称、描述并选择嵌入模型。RAGFlow 内置了bge-large-zh等模型对于中文文档效果较好保持默认即可。也可以选择其他兼容的嵌入模型。配置文本分块Chunking策略分块大小通常设置在 256-1024 个字符或 token之间。太小会丢失上下文太大会降低检索精度。对于普通文档512 是一个不错的起点。重叠大小相邻文本块之间重叠的字符数通常为分块大小的 10%-20%。这有助于避免一个答案被切分到两个块边界。配置检索策略检索器类型通常选择“向量检索”。Top K每次检索返回的最相关片段数量通常设为 3-5。重排序Rerank这是一个可选但能提升精度的步骤。如果启用检索到的 Top K 个片段会经过一个更精细的排序模型再次排序将最相关的放在前面。如果硬件资源允许建议开启。5.2 上传与处理文档在创建好的知识库中点击“上传文档”。支持多种格式PDF、Word、PPT、TXT、Markdown甚至图片需 OCR。上传后RAGFlow 会自动进行以下流水线处理解析提取文档中的文本、表格、图片文字。分块按照之前设定的策略将文本切割成片段。向量化使用嵌入模型将每个文本片段转换为向量。入库将向量和元数据存入向量数据库如 Milvus。你可以在“文档”列表中查看处理状态。状态变为“已索引”后文档就可供检索了。5.3 进行问答测试进入知识库的“对话”或“测试”页面。在输入框中提问。问题应基于你上传的文档内容。观察回答。一个运行良好的 RAG 系统其回答应该准确答案内容来源于上传的文档。可追溯回答下方通常会附上“参考来源”点击可以定位到原文片段。这是 RAG 区别于普通聊天模型的关键特征。自然语言流畅像是基于文档内容组织的答案而不是生硬地拼接片段。示例测试上传文档一份关于“项目管理办法”的 PDF。提问“项目评审会议需要哪些人参加”期望回答应列出文档中规定的参会人员角色并附上对应的原文出处。5.4 优化检索效果如果发现回答不准确或未找到相关信息可以从以下几个方面优化调整分块策略对于结构严谨的文档如 API 文档可以适当增大分块大小对于内容松散的文档可以减小分块大小。优化提问方式尝试使用更接近文档原文表述的关键词进行提问。检查文档解析质量在文档详情页查看解析出的原始文本是否正确特别是表格和图片中的文字。启用重排序如果之前未启用可以开启重排序功能它能有效提升答案相关性。调整 Top K 值适当增加 Top K 值让模型看到更多候选片段但可能会引入噪声。6. 生产环境考量与最佳实践将本地知识库用于个人学习或 demo 验证是一回事若要用于团队协作或轻度生产环境则需要考虑更多因素。6.1 安全性加固访问控制RAGFlow 自带用户角色管理。务必为不同使用者创建账号并分配适当的权限如只读、可上传、可管理。API 密钥管理DeepSeek 服务如果设置了 API Key应妥善保管。不要在代码或配置文件中硬编码可以考虑使用环境变量或密钥管理服务。网络隔离将 DeepSeek 和 RAGFlow 服务部署在内网仅通过反向代理如 Nginx暴露必要的 Web 界面端口并配置 HTTPS。文档审核建立文档上传前的审核机制避免错误或敏感信息进入知识库。6.2 性能与稳定性资源监控使用docker stats或nvidia-smi监控容器和 GPU 的资源使用情况CPU、内存、显存。为关键容器如 DeepSeek 服务设置资源限制防止其耗尽主机资源。# 在 docker run 命令中限制资源 --memory 16g --memory-swap 20g --cpus 4模型量化如果 GPU 显存紧张务必使用量化版本的 DeepSeek 模型如 AWQ, GPTQ 量化这可以大幅降低显存占用仅轻微损失精度。服务高可用对于重要服务可以考虑使用 Docker Swarm 或 Kubernetes 进行容器编排实现故障自动恢复和水平扩展。至少应为数据库MySQL, Milvus配置持久化存储卷防止数据丢失。# 在 docker-compose.yml 中为 Milvus 配置卷 volumes: - milvus_data:/var/lib/milvus日志与告警配置 Docker 容器的日志驱动将日志集中收集到 ELK 或 Loki 等系统。对服务健康状态如 HTTP 端口探活设置告警。6.3 知识库维护版本管理知识库文档会更新。RAGFlow 支持文档更新后重新索引。建议建立文档版本管理制度并在上传新版本后触发对旧文档的删除和重新索引操作。定期评估定期用一组标准问题测试知识库评估回答的准确率和相关性。根据结果调整分块、检索策略或考虑更新嵌入模型。冷门知识处理对于极少被查询的冷门知识可以考虑将其存入传统数据库进行关键词检索与 RAG 形成互补。6.4 扩展方向多模态RAGFlow 支持图片 OCR。可以探索上传带有图表、示意图的文档构建能回答“根据某张图说明...”问题的知识库。联网搜索结合 Tavily、Serper 等工具在本地知识库无法回答时自动进行网络搜索并将结果补充到上下文中。Agent 集成将本地知识库作为工具接入到 LangChain、AutoGen 等智能体框架中让 Agent 在规划任务时能够主动查询知识库。更复杂的流水线RAGFlow 支持自定义推理流程。可以尝试在检索后加入更复杂的处理如调用多个模型进行验证、总结等。搭建本地知识库的过程本质上是将数据、算法和工程进行有机结合。从环境准备、服务部署、配置对接到效果调优每一步都可能遇到问题。关键是要理解每个组件的职责和它们之间的交互协议如 OpenAI API。当问答不准确时要有清晰的排查思路是文档没解析好分块不合理检索策略不对还是大模型本身的理解或生成有问题通过日志、中间结果如检索到的片段一步步定位才能让这个系统真正为你所用。