在 macOS 上从源码部署 RAGFlow-0.14.1：详细指南

一、引言

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 依赖项
安装 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 

安装依赖项：执行以下命令安装 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，直至依赖安装成功。
4. 启动第三方服务：使用 Docker Compose 启动 “基本” 服务，其中包括 MinIO、Elasticsearch、Redis 和 MySQL，在终端输入以下命令：

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

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

5. 更新第三方服务的主机和端口设置：首先，在/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 。修改后的内容大致如下：

yamlragflow:
  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 后端服务
注释 nginx 行：使用文本编辑器打开docker/entrypoint.sh文件，找到/usr/sbin/nginx这一行，在其开头添加#符号，将其注释掉，修改后的内容如下：

# /usr/sbin/nginx

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

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

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

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

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

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 前端服务
安装前端依赖项：在终端进入web目录，执行以下命令安装前端依赖项：

cd web
npm install --force

更新代理配置：使用文本编辑器打开.umirc.ts文件，将proxy.target更新为http://127.0.0.1:9380 。
启动前端服务：在终端执行以下命令启动前端服务：

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，开启人工智能应用开发之旅。