MantisAI 完整部署手册（Python3.11+Tesseract OCR全依赖）

项目简介 & 源码仓库

MantisAI 本地私有化RAG知识库对话系统，完全本地运行不上传第三方云端。技术栈：前端HTML+JS + PHP业务接口 + Python3.11向量后端 + llama.cpp GGUF本地嵌入 + Tesseract图文OCR识别。

开源GitCode源码地址：https://gitcode.com/nick_xu_i/MantisAI

本地私有化 GitCode开源 Apache+PHP Python3.11 llama.cpp GGUF Tesseract OCR图文识别

一、硬件与软件前置要求

硬件配置推荐

最低内存

16GB

推荐内存

32GB

硬盘空间

50GB+

推荐显卡

8G+ N卡显存

必备软件清单

Git 工具（拉取项目源码）
Apache HTTP Server 2.4
PHP 8.1~8.3 线程安全TS版
Python 3.11（项目指定稳定版，禁止3.10/3.12）
Tesseract-OCR 5.3.0（Windows图文识别，含中文语言包）
llama.cpp 编译包（llama-server嵌入推理服务）

整套系统需要4个常驻服务同时运行：Apache、PHP、Python3.11后端、llama-server；缺少任意一项功能失效。

二、GitCode 拉取完整项目源码

安装Git并配置系统环境变量，打开CMD/终端执行克隆

# Windows 拉取至D盘网站根目录
cd D:\
git clone https://gitcode.com/nick_xu_i/MantisAI mantisai

# Linux 拉取服务目录
cd /data
git clone https://gitcode.com/nick_xu_i/MantisAI mantisai

进入项目目录查看核心文件

cd mantisai
# Windows查看文件
dir
# Linux查看文件
ls

核心文件说明
- index.html：前端主页面
- api.php：PHP用户/配置/文件接口
- main.py：Python3.11向量检索后端
- requirements.txt：完整Python依赖清单
- GUI.css：全局统一UI样式（本手册共用）
- session/：会话、用户、向量持久化目录

Apache网站根目录直接指向mantis文件夹，无需复制文件。

三、Apache 2.4 安装与站点配置

Windows

Linux

下载Apache Lounge 2.4压缩包，解压 D:/Apache24

管理员CMD注册系统服务

cd D:\Apache24\bin
httpd.exe -k install -n "Apache24"

前置操作：手动创建日志文件夹
```
mkdir d:\ai-chat\logs
mkdir d:\mdpdf\logs
```

修改 D:\Apache24\conf/httpd.conf 核心基础配置

ServerRoot "D:/Apache24"
# 必须开启反向代理、WebSocket、重写模块
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
LoadModule headers_module modules/mod_headers.so
LoadModule php8_module "D:/php8/php8apache2_4.dll"
# PHP解析配置
PHPIniDir "D:/php8"
AddHandler application/x-httpd-php .php
DirectoryIndex index.html index.php

在httpd.conf末尾追加虚拟主机（8888主AI）端口根据自己的端口配置

# 监听端口声明，必须添加
Listen 8888
Listen 8889

# 8888 主AI会话页面
<VirtualHost *:8888>
    ServerName localhost-test
    ServerAlias 127.0.0.8888
    DocumentRoot "d:/ai-chat"
    <Directory "d:/ai-chat">
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>
    DirectoryIndex index.html

    RewriteEngine On
    # WebSocket反向代理适配PDF生成长连接
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/ws/(.*)$ ws://127.0.0.1:8000/ws/$1 [P,L]

    # API接口反向代理
    ProxyPass /api http://127.0.0.1:8000/api
    ProxyPassReverse /api http://127.0.0.1:8000/api
    # PDF静态文件代理
    ProxyPass /pdf http://127.0.0.1:8000/pdf
    ProxyPassReverse /pdf http://127.0.0.1:8000/pdf

    ProxyPreserveHost On
    ProxyTimeout 3600
    RequestHeader set X-Forwarded-Proto "http"

    ErrorLog "d:/ai-chat/logs/error.log"
    CustomLog "d:/ai-chat/logs/access.log" combined
</VirtualHost>

配置语法校验（管理员CMD执行，无报错再启动服务）
```
cd D:\Apache24\bin
httpd -t
```

启停命令

net start Apache24
# 重启服务
httpd.exe -k restart -n "Apache24"

1. 两个虚拟主机ServerAlias不能同为127.0.0.1，会端口分发冲突启动失败； 2. 必须提前创建logs日志文件夹，否则Apache启动直接崩溃； 3. proxy_wstunnel_module模块缺失会导致WebSocket长连接（PDF生成）502报错； 4. Python后端main.py必须先启动监听8000，否则/api /pdf /ws全部网关错误。

Ubuntu安装

sudo apt update
sudo apt install apache2

新建站点配置 /etc/apache2/sites-available/mantis.conf

<VirtualHost *:80>
    ServerName 127.0.0.1
    DocumentRoot /data/mantisai
    <Directory /data/mantis>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    DirectoryIndex index.html index.php
</VirtualHost>

启用站点并重启

sudo a2ensite mantis.conf
sudo systemctl restart apache2

四、PHP 8.x 环境部署

下载 TS线程安全版 PHP8.1/8.3，解压 D:/php8
复制 php.ini-development 重命名 php.ini

开启必备扩展（删除行首;注释）

extension=curl
extension=json
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_sqlite
extension=gd

目录与上传限制配置

extension_dir = "D:/php8/ext"
upload_max_filesize = 50M
post_max_size = 100M
memory_limit = 512M

重启Apache，新建info.php访问 http://127.0.0.1/info.php 验证PHP正常解析

必须使用TS线程安全版本，NTS无法加载Apache模块；curl是PHP调用Python后端核心依赖，不可关闭。

五、Python3.11 安装 & 完整依赖安装

Windows 安装流程

Linux Ubuntu安装流程

1. 安装Python3.11 64位安装包

官网下载离线安装包，安装时勾选 Add Python to PATH 自动配置环境变量

2. 验证安装（新开CMD）

python --version
# 输出 Python 3.11.x 即为正常

3. 进入项目创建虚拟环境（隔离依赖，版本不冲突）

cd D:\mantisai
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
venv\Scripts\activate
# 激活成功命令行前缀出现 (venv)

4. 一键完整依赖安装（国内清华镜像加速，含PDF生成模块）

# 全套整合安装命令，一次性安装RAG+文档导出+PDF生成所有依赖
pip install chromadb flask flask-cors asgiref rank-bm25 sentence-transformers fpdf2 python-docx python-doc-template openpyxl xlrd python-pptx matplotlib pandas langchain langchain-community langchain-text-splitters langchain-core langchain-chroma langchain-ollama pypdf docx2txt pytesseract pillow requests fastapi uvicorn playwright -i https://pypi.tuna.tsinghua.edu.cn
# 安装PDF生成所需Chrome浏览器内核
playwright install chromium

向量库：chromadb、langchain、rank-bm25、sentence-transformers
Web主服务：flask、flask-cors、asgiref
PDF生成后端：fastapi、uvicorn、playwright、chromium内核
文档解析导出：fpdf2、python-docx、openpyxl、python-pptx
OCR识别：pytesseract、pillow
网络请求：requests

5. 启动Python后端服务

python main.py

监听127.0.0.1:5000，CMD窗口保持后台常驻

1. Ubuntu安装Python3.11

sudo apt update
sudo apt install python3.11 python3.11-dev python3-pip python3.11-venv
sudo ln -s /usr/bin/python3.11 /usr/bin/python3

2. 验证版本

python3 --version

3. 项目虚拟环境

cd /data/mantisai
python3 -m venv venv
source venv/bin/activate

4. 全套依赖安装

pip3 install chromadb flask flask-cors asgiref rank-bm25 sentence-transformers fpdf2 python-docx python-docx-template openpyxl xlrd python-pptx matplotlib pandas langchain langchain-community langchain-text-splitters langchain-core langchain-chroma langchain-ollama pypdf docx2txt pytesseract pillow requests -i https://pypi.tuna.tsinghua.edu.cn/simple

5. 启动后端

python3 main.py

项目强制Python3.11，3.10/3.12存在库兼容BUG；必须激活venv虚拟环境再执行pip安装，避免全局包冲突。

六、Windows Tesseract OCR 完整部署（解决tesseract is not installed报错）

报错信息：tesseract is not installed or it's not in your PATH 上传图片向量化触发该异常，缺少OCR程序/中文语言包

方案1：Anaconda一键安装（推荐，无需手动配置系统环境变量）

打开Anaconda PowerShell Prompt执行

# 安装tesseract二进制程序
conda install -c conda-forge tesseract -y
# 安装python OCR依赖
pip install pytesseract pillow

下载中文/英文语言包：https://github.com/tesseract-ocr/tessdata
必需文件：chi_sim.traineddata（简体中文）、eng.traineddata（英文）

放入conda tessdata目录

C:\Users\你的用户名\anaconda3\envs\你的虚拟环境名\Library\tessdata
# base默认环境路径
C:\Users\你的用户名\anaconda3\Library\tessdata

main.py头部添加固定路径配置（复制到代码最上方）

import os
import pytesseract
# tessdata语言包目录
os.environ['TESSDATA_PREFIX'] = r'C:\Users\你的用户名\anaconda3\Library\tessdata'
# tesseract执行程序路径
pytesseract.tesseract_cmd = r"C:\Users\你的用户名\anaconda3\Library\bin\tesseract.exe"

验证：Anaconda终端输入 tesseract --version 输出版本即正常

方案2：独立安装包（无Anaconda用户）

下载安装包：tesseract-ocr-w64-setup-v5.3.0.20221222.exe（UB-Mannheim官方）
安装时勾选 Additional language data → Chinese (Simplified) 简体中文包
安装路径记录：C:\Program Files\Tesseract-OCR
配置系统环境变量：此电脑→高级系统设置→环境变量→系统PATH新增
```
C:\Program Files\Tesseract-OCR
```

main.py硬编码兜底路径

import pytesseract
pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'
os.environ['TESSDATA_PREFIX'] = r'C:\Program Files\Tesseract-OCR\tessdata'

重启CMD/IDE生效，测试图片上传OCR识别

缺少chi_sim.traineddata中文包会导致图片中文全部识别乱码；语言包必须放入tessdata文件夹。

七、llama.cpp 嵌入向量服务部署

推荐GGUF模型：Qwen3-Embedding-4B.Q4_K_M.gguf（32768超长上下文，中文最优）

Windows启动命令

D:\llama.cpp\llama-server.exe -m Qwen3-Embedding-4B.Q4_K_M.gguf --embeddings -c 32768 --port 8082

Linux启动命令

./llama-server -m Qwen3-Embedding-4B.Q4_K_M.gguf --embeddings -c 32768 --port 8082

前端设置页面新增嵌入配置
- 平台：llamacpp
- URL：http://127.0.0.1:8082/v1/embeddings
- 模型：Qwen3-Embedding-4B.Q4_K_M.gguf
- 勾选【当前启用】保存配置

若使用bge-base-zh-v1.5，模型仅支持512token，main.py中分块参数base_chunk_len必须改为42，否则文本过长token超限报错。

八、系统完整操作使用教程

1.登录注册

2.向量嵌入配置

3.文档/图片上传入库

4.知识库对话

5.高级功能

浏览器访问 http://127.0.0.1/index.html
左上角👤头像按钮打开登录弹窗
新用户填写手机号、昵称、密码自动注册；老用户直接登录

所有用户数据存储项目session/users文件夹，本地文件存储，不上传外网。

左下角齿轮⚙️下拉菜单 → 向量嵌入配置
新增llamacpp配置，填写8082接口地址与模型名称，设为启用保存

不激活嵌入服务，所有文档/图片上传向量化直接失败。

侧边栏【+新建会话】创建独立知识库会话
底部附件按钮支持格式：PDF/DOCX/TXT/JPG/PNG图片
图片自动执行Tesseract OCR提取文字；文档直接文本清洗、语义分块
统一调用llama-server生成向量存入Chroma向量库
Python控制台无异常日志即入库完成

底部输入框输入业务问题
检索范围可选：仅当前会话 / 全局全部文档
混合BM25关键词检索+向量相似度检索，拼接参考资料生成回答
对话记录自动持久化，刷新页面不丢失

1. 文件业务属性模板

自定义元数据字段（姓名/部门/年份），上传文件绑定，检索可按字段过滤

2. 知识库元属性分类

全局文档标签，多维度筛选知识库内容

3. 行业同义词库

工单、合同、专业词汇自动扩展，提升召回准确率

4. 问答导出

支持PDF/Word/PPT/Excel导出完整对话记录

5. 用户管理

管理员新增/删除用户、配置知识库访问权限

九、嵌入模型选型与分块参数

GGUF模型	上下文token	推荐base_chunk_len	硬件需求
Qwen3-Embedding-4B Q4_K_M	32768	2200	16G内存，首选
bge-large-zh-v1.5 Q4	1024	900	10G内存
bge-base-zh-v1.5 Q4	512	420	低配8G，易token超限

十、常见故障排查

1. tesseract is not installed or it's not in your PATH
根源：未安装Tesseract、未配置程序路径、缺少chi_sim中文语言包；修复：参考第六章节完整安装OCR并在main.py硬编码路径。

2. Failed to connect to Ollama
根源：/api/vector接口文档分支硬编码Ollama，未手动生成embeddings传入coll.add；修复循环调用get_embedding_local预计算向量。

3. input xxx tokens too large
bge-base模型仅512上下文，缩小base_chunk_len至420或更换Qwen长上下文嵌入模型。

4. 登录/设置弹窗点击无响应
HTML #ocr-setting-modal标签未闭合、JS点击事件缺少e.stopPropagation阻止冒泡。

5. api.php 500服务器错误
PHP未开启curl扩展、session文件夹无读写权限，修改文件夹权限777/取消只读。

6. pip安装依赖失败
确认激活venv虚拟环境，使用清华镜像-i参数加速，Python版本严格3.11。

7 Apache启动失败 / 访问/api返回502 Bad Gateway 原因1：未创建d:\ai-chat\logs、d:\mdpdf\logs日志文件夹；原因2：httpd.conf未加载proxy_wstunnel、proxy_http代理模块；原因3：两个VirtualHost共用127.0.0.1域名分发冲突；原因4：Python main.py后端8000端口未启动；修复：按第三章Windows步骤补全配置、创建日志目录、校验语法后重启Apache。