当前位置：首页 > news >正文

【大模型实战篇】Mac本地部署RAGFlow的踩坑史

news 2025/12/22 13:07:10

1. 题外话

最近一篇文章还是在11月30日写的，好长时间没有打卡了。最近工作上的事情特别多，主要聚焦在大模型的预训练、微调和RAG两个方面。主要用到的框架是Megatron-DeepSpeed，后续会带来一些分享。今天的文章主要聚焦在RAG。

近期调研了一系列开源的RAG框架（约20多个开源项目），相对来说，RAGFlow【1】更贴合我的需求，因此就花了一些时间去研究，本文分享下在Mac系统本地化部署的实践。通过本地化部署和使用，能够更好的帮助你分析其中的一些能力以及理解代码。不过话说回来，虽然RAGFlow的demo使用还是挺可以的，但开源项目的代码质量和文档质量不得不令人吐槽，希望该项目的作者能够重视起来。

2. Mac系统部署

我们采用从源码部署的模式【2】。由于0.15.1似乎对mac的支持不够，因此回退到0.14.1版本。后续的安装是基于0.14.1版本进行，这个需要说明一下。

这里说一下我本地的mac系统信息：

芯片：Apple M2 Pro

内存：16G

macOS： Ventura 13.4

2.1 资源要求

CPU ≥ 4 cores
RAM ≥ 16 GB
Disk ≥ 50 GB
Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1

Mac查看cpu信息

> sysctl -a | grep machdep.cpu

machdep.cpu.cores_per_package: 10

machdep.cpu.core_count: 10

machdep.cpu.logical_per_package: 10

machdep.cpu.thread_count: 10

machdep.cpu.brand_string: Apple M2 Pro

2.2 安装pipx

> python -m pip install --user pipx

配置启动：

> python -m site --user-base

> nano ~/.zshrc

添加以下指令到.zshrc：

export PATH="/path/to/user_base/bin:$PATH"

生效：

> source ~/.zshrc

接下来可以使用pipx：

> pipx

usage: pipx [-h] [--quiet] [--verbose] [--global] [--version]

{install,install-all,uninject,inject,pin,unpin,upgrade,upgrade-all,upgrade-shared,uninstall,uninstall-all,reinstall,reinstall-all,list,interpreter,run,runpip,ensurepath,environment,completions}

...

Install and execute apps from Python packages.

Binaries can either be installed globally into isolated Virtual Environments

or run directly in a temporary Virtual Environment.

2.3 安装poetry

pipx install poetry

配置：

export POETRY_VIRTUALENVS_CREATE=true POETRY_VIRTUALENVS_IN_PROJECT=true

2.4 安装依赖包

瘦身版:

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

完整版:

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

注意：此时安装会报xgboost的安装错误，原因是xgboost 包的版本 1.5.0 不支持 PEP 517 构建标准，而 Poetry 默认使用 PEP 517 来处理依赖包的安装【3】。

解决方案为编辑 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

安装依赖顺利完成。

2.5 启动第三方服务

使用 Docker Compose 启动 ‘base’ 服务（MinIO、Elasticsearch、Redis 和 MySQL）

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

这里也遇到docker compose的问题，可能需要涉及到重新安装，看你的版本，如果是高版本，则需要安装一个docker-compose的extension包，否则安装docker-compose。确保你的docker-compose版本在v2.26.1及以上。

另外，可以添加docker的国内加速镜像，能够顺利一些。

2.6 启动 RAGFlow 后端服务

在 docker/entrypoint.sh 文件中注释掉 nginx 这一行。

# /usr/sbin/nginx

回退路径到ragflow目录，激活 Python 虚拟环境：

> source .venv/bin/activate

> export PYTHONPATH=$(pwd)

如果无法访问 HuggingFace，可以设置 HF_ENDPOINT 环境变量以使用镜像站点：

推荐一个 huggingface 的镜像站：https://hf-mirror.com/

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

在ragflow路径下运行 entrypoint.sh 脚本来启动后端服务：

bash docker/entrypoint.sh

这里直接使用源码，可能会报错路径问题， /ragflow/docker/service_conf.yaml.template: No such file or directory。需要调整一下路径【3】。具体如下：

#!/bin/bash# 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 valueseval "echo \"$line\"" >> ./conf/service_conf.yaml
done < ./docker/service_conf.yaml.template# unset http proxy which maybe set by docker daemon
export http_proxy=""; export https_proxy=""; export no_proxy=""; export HTTP_PROXY=""; export HTTPS_PROXY=""; export NO_PROXY=""#/usr/sbin/nginxexport LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/PY=python3
if [[ -z "$WS" || $WS -lt 1 ]]; thenWS=1
fifunction task_exe(){while [ 1 -eq 1 ];do$PY rag/svr/task_executor.py $1;done
}for ((i=0;i<WS;i++))
dotask_exe  $i &
donewhile [ 1 -eq 1 ];do$PY api/ragflow_server.py
donewait;

另外启动过程中，可能会报一些module not found的错误，python依赖包罗列如下：

beartype, pycryptodomex, pdfplumber, polars, datrie, hanziconv, roman_numbers, cn2an strenum, tiktoken, xxhash, elasticsearch_dsl, valkey, flask_login, word2number, infinity

如果启动成功，可以看待下述的信息：

2.6 启动 RAGFlow 前端服务

安装前端依赖项：

注：需要安装node

> cd web

> npm install --force

安装依赖的过程又有点麻烦，出现很多次timeout

配置一下镜像：

npm config set registry https://registry.npmmirror.com/

在 .umirc.ts 中将 proxy.target 更新为 http://127.0.0.1:9380

vim .umirc.ts

启动 RAGFlow 前端服务:

npm run dev

3. 系统界面展示

4. 服务关闭

开发完成后停止 RAGFlow 服务

停止 RAGFlow 前端服务：

pkill npm

停止 RAGFlow 后端服务：

pkill -f “docker/entrypoint.sh”

5. 参考材料

【1】https://github.com/infiniflow/ragflow

【2】Launch the RAGFlow Service from Source

【3】源码部署RAGFlow-0.14.1