macOS 上部署 RAGFlow：详细指南

macOS 上部署 RAGFlow：详细指南

RAGFlow 是一款在人工智能领域应用广泛的强大工具。本文将详细介绍如何在 macOS 系统上从源码部署 RAGFlow 0.14.1 版本，无论是开发人员进行项目实践，还是技术爱好者探索新工具，都能从这篇指南中获取清晰、实用的部署步骤。

一、部署前准备

系统配置检查

本次部署以配备 Apple M3 Pro 芯片、18GB 内存且运行 Sonoma 14.6.1 系统的 MacBook Pro 为例。在部署前，需确认你的设备配置与之相当或更优，以确保部署过程顺利及后续使用体验。

安装 Docker 和 Docker Compose

版本要求：RAGFlow 官方明确规定，部署所需的 Docker 版本需大于等于 24.0.0，Docker Compose 版本需大于等于 v2.26.1。

安装与检查：若尚未安装，前往 Docker 官方网站下载并安装对应版本。安装完成后，在终端分别输入以下命令检查版本：

docker -v
docker-compose --version

若已安装但版本不满足要求，需及时更新到指定版本。若显示的版本符合要求，则可继续后续步骤。

二、安装和配置 RAGFlow 的前后端

下载项目

打开终端，进入你期望安装 RAGFlow 的目录，执行以下命令克隆项目仓库：

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/

这一步将把 RAGFlow 项目的源代码下载到本地指定目录，并进入该项目目录，为后续安装和配置做准备。

安装 Python 依赖项

1. 安装 Poetry：Poetry 是 Python 项目依赖管理的重要工具，在终端执行以下命令进行安装：

curl -sSL https://install.python-poetry.org | python3 -

安装完成后，使用 poetry --version 检查版本。若出现 zsh: command not found: poetry 错误，这是因为 Poetry 的安装目录未被添加到系统环境变量 PATH 中。此时，需编辑 ~/.zshrc 文件，在文件末尾添加（注意将 kuangfh 替换为你的用户名）：

export PATH="/Users/kuangfh/.local/bin:$PATH"

添加完成后，运行 source ~/.zshrc 使更改生效，确保系统能够识别 Poetry 命令。

2. 配置 Poetry：在终端中设置 Poetry 的相关环境变量，以确保虚拟环境能按预期创建和使用：

export POETRY_VIRTUALENVS_CREATE=true

3. 安装依赖项：执行以下命令安装 Python 依赖项，这会创建一个名为 .venv 的虚拟环境，并将项目所需的所有 Python 依赖项安装到该环境中：

~/.local/bin/poetry install --sync --no-root

在安装过程中，若出现错误提示与 xgboost 包有关，这是因为 xgboost 1.5.0 版本不支持 PEP 517 构建标准，而 Poetry 默认使用该标准处理依赖包安装。此时，使用 VS Code（或其他文本编辑器）打开 pyproject.toml 文件，在 [tool.poetry.dependencies] 部分，将 xgboost 的版本范围修改为 xgboost = "^1.6.0"。保存修改后，在终端执行以下命令重新生成 poetry.lock 文件：

~/.local/bin/poetry lock

该命令会根据 pyproject.toml 文件的依赖定义，更新或重新生成 poetry.lock 文件。之后，再次执行 ~/.local/bin/poetry install --sync --no-root，直至依赖安装成功。

启动第三方服务

1. 使用 Docker Compose 启动 "基本" 服务，其中包括 MinIO、Elasticsearch、Redis 和 MySQL，在终端输入以下命令：

docker compose -f docker/docker-compose-base.yml up -d

这将在后台启动这些服务，为 RAGFlow 的运行提供必要的支持。

2. 更新第三方服务的主机和端口设置：

• 首先，在 /etc/hosts 文件中添加以下内容，将 docker/service_conf.yaml.template 中指定的所有主机解析为 127.0.0.1：

  127.0.0.1    es01 infinity mysql minio redis
  

• 然后，使用文本编辑器打开 docker/service_conf.yaml.template 文件，按照 docker/.env 中的指定，将 mysql 端口更新为 5455，将 es 端口更新为 1200。修改后的内容大致如下：

  ragflow:
    host: ${RAGFLOW_HOST:-0.0.0.0}
    http_port: 9380
  mysql:
    name: '${MYSQL_DBNAME:-rag_flow}'
    user: '${MYSQL_USER:-root}'
    password: '${MYSQL_PASSWORD:-infini_rag_flow}'
    host: '${MYSQL_HOST:-mysql}'
    port: 5455
    max_connections: 100
    stale_timeout: 30m
  minio:
    user: '${MINIO_USER:-rag_flow}'
    password: '${MINIO_PASSWORD:-infini_rag_flow}'
    host: '${MINIO_HOST:-minio}:9000'
  es:
    hosts: 'http://${ES_HOST:-es01}:1200'
    username: '${ES_USER:-elastic}'
    password: '${ELASTIC_PASSWORD:-infini_rag_flow}'
  

三、启动 RAGFlow 后端服务

1. 注释 nginx 行：使用文本编辑器打开 docker/entrypoint.sh 文件，找到 /usr/sbin/nginx 这一行，在其开头添加 # 符号，将其注释掉，修改后的内容如下：

   # /usr/sbin/nginx
   

2. 激活虚拟环境：在终端执行以下命令，激活之前创建的 Python 虚拟环境，并设置 PYTHONPATH 环境变量：

   source .venv/bin/activate
   export PYTHONPATH=$(pwd)
   

3. 设置 HuggingFace 镜像站点（可选）：若在部署过程中无法访问 HuggingFace，可在终端设置 HF_ENDPOINT 环境变量为镜像站点地址，例如：

   export HF_ENDPOINT=https://hf-mirror.com
   

4. 启动后端服务：在终端执行以下命令启动后端服务：

   bash docker/entrypoint.sh
   

   若启动过程中遇到 NLTK 库相关报错，提示找不到 punkt_tab 资源或 wordnet 资源，分别运行以下命令进行下载：

   python
   import nltk
   nltk.download('punkt_tab')
   nltk.download('wordnet')
   

   若出现 docker/entrypoint.sh: line 8: /ragflow/docker/service_conf.yaml.template: No such file or directory 错误，需将 entrypoint.sh 中的路径修改为相对路径。修改后的内容如下：

   # replace env variables in the service_conf.yaml file
   rm -rf ./conf/service_conf.yaml  # 使用相对路径
   while IFS= read -r line || [[ -n "$line" ]]; do
       # Use eval to interpret the variable with default values
       eval "echo \"$line\"" >> ./conf/service_conf.yaml  # 使用相对路径
   done < ./docker/service_conf.yaml.template  # 使用相对路径
   

   修改完成后，重新执行 bash docker/entrypoint.sh 启动后端服务。

四、启动 RAGFlow 前端服务

1. 安装前端依赖项：在终端进入 web 目录，执行以下命令安装前端依赖项：

   cd web
   npm install --force
   

2. 更新代理配置：使用文本编辑器打开 .umirc.ts 文件，将 proxy.target 更新为 http://127.0.0.1:9380。

3. 启动前端服务：在终端执行以下命令启动前端服务：

   npm run dev
   

   启动成功后，终端会显示前端服务的 IP 地址和端口号，根据提示信息可在浏览器中访问 RAGFlow 服务。

五、访问 RAGFlow 服务

打开 Web 浏览器，在地址栏输入前端服务显示的 IP 地址和端口号（例如 http://127.0.0.1:9222，注意确保端口号与实际显示一致），即可访问 RAGFlow 服务。

若在解析文档时出现 ModuleNotFoundError: No module named 'FlagEmbedding' 错误，在终端使用 pip 命令安装该模块：

pip install FlagEmbedding==1.2.10
pip show FlagEmbedding

六、关闭前后端服务

当不再需要使用 RAGFlow 服务时，可在终端执行以下命令关闭前后端服务：

pkill npm
pkill -f "docker/entrypoint.sh"

七、总结

通过以上详细的步骤，我们完成了在 macOS 上从源码部署 RAGFlow 0.14.1 的全过程。在部署过程中，每一步都至关重要，需仔细操作，尤其是环境变量的设置、依赖项的安装以及路径的配置等环节。若在部署过程中遇到问题，可参考文中的解决方案或进一步查阅相关资料。希望本文能帮助大家顺利部署 RAGFlow，开启人工智能应用开发之旅。