OpenWebU-RAG 文档功能配置

3.4. RAG 文档功能配置

RAG（检索增强生成）是 Open WebUI 的核心功能之一，允许用户基于自己的文档进行问答。本节将从上到下逐一解析 Admin Panel → Settings → Documents 页面的每个配置项，帮助你根据实际场景做出最优选择。

配置入口：管理员面板 → 设置 → Documents

内容提取引擎（Content Extraction Engine）

内容提取引擎决定了 Open WebUI 如何从上传的文件中提取文本。通过环境变量 CONTENT_EXTRACTION_ENGINE 选择，共支持 8 种引擎。

引擎横向对比

引擎部署方式费用支持格式OCR 能力表格/公式适用场景
默认（Default）本地，零依赖免费PDF、TXT、CSV、DOCX、代码文件❌ 不支持❌ 弱简单文档，纯文本 PDF
Apache Tika需部署 Java 服务免费（开源）1400+ 种格式❌ 弱❌ 弱格式种类多的企业环境
Docling（IBM）需部署服务或用 API免费（开源）PDF、DOCX、PPTX、HTML✅ 支持✅ 优秀复杂排版、表格、公式
Datalab Marker云 API 或自部署~$6/千页（高精度）PDF、图片✅ LLM 增强 OCR✅ 优秀复杂排版 PDF，可自部署
Mistral OCR云 API$1-2/千页PDF、图片✅ 99%+ 准确率✅ 优秀扫描件、多语言（25+ 语言）
Document IntelligenceAzure 云服务~$10/千页PDF、图片、表单✅ 支持✅ 支持Azure 生态企业用户
MinerU自部署或云 API免费（开源）PDF、图片✅ 支持✅ 最佳学术论文、金融报告、公式密集
External自定义 HTTP 服务取决于实现自定义取决于实现取决于实现对接私有解析服务

各引擎详细说明

使用 Python 原生加载器（PyPDFLoader、Docx2txtLoader、CSVLoader、TextLoader），零依赖开箱即用。但不支持 OCR，无法处理扫描件，对复杂表格和公式无能为力。

适合：纯文本 PDF 和简单文档，快速上手无需任何额外配置。

老牌 Java 文档解析框架，格式覆盖最广（1400+），但对 PDF 排版理解较弱，不擅长表格结构保留和公式识别。适合已有 Tika 基础设施的组织。

1
2
3
environment:
  - CONTENT_EXTRACTION_ENGINE=tika
  - TIKA_SERVER_URL=http://tika:9998

Python 原生，对 PDF 排版理解好，表格提取准确，支持公式，输出干净的 Markdown/JSON。在多个评测中与 MinerU 并列 top 2。

1
2
3
4
environment:
  - CONTENT_EXTRACTION_ENGINE=docling
  - DOCLING_SERVER_URL=http://docling:5000
  - DOCLING_API_KEY=your-api-key  # 如需认证

基于开源 Marker 和 Surya 模型，LLM 增强 OCR。其 Chandra OCR 模型在 olmOCR benchmark 上得分 83.1%，超过 GPT-4o。支持云 API 和自部署两种方式。

1
2
3
environment:
  - CONTENT_EXTRACTION_ENGINE=datalab_marker
  - DATALAB_MARKER_API_KEY=your-api-key

号称 99%+ 准确率，支持表格/公式/图表转表格/签名检测，覆盖 25+ 语言。性价比高（$1/千页起），但只能通过 API 调用，无法自部署。

1
2
3
environment:
  - CONTENT_EXTRACTION_ENGINE=mistral_ocr
  - MISTRAL_OCR_API_KEY=your-api-key

微软企业级服务，预置发票/收据/身份证等模型，支持自定义模型训练。价格较高但有企业合规保障。

1
2
3
environment:
  - CONTENT_EXTRACTION_ENGINE=document_intelligence
  - DOCUMENT_INTELLIGENCE_ENDPOINT=https://your-resource.cognitiveservices.azure.com/

基于 PDF-Extract-Kit 微调模型，在复杂文档（学术论文、教材、金融报告）上表现最佳，表格/公式/图片提取精度高。推荐 GPU 环境运行。

1
2
3
4
environment:
  - CONTENT_EXTRACTION_ENGINE=mineru
  - MINERU_API_URL=http://mineru:8000
  - MINERU_API_MODE=local  # cloud 或 local

万能逃生舱，指向任意 HTTP 服务，适合对接企业内部的私有文档解析服务。

1
2
3
environment:
  - CONTENT_EXTRACTION_ENGINE=external
  - EXTERNAL_DOCUMENT_LOADER_URL=http://your-service:8080/extract

引擎选择建议

场景推荐引擎理由
简单文档、快速上手默认零配置，开箱即用
扫描件、多语言文档Mistral OCR性价比最高，准确率高
学术论文、公式密集MinerU 或 Docling表格/公式提取精度最佳
企业 Azure 环境Document Intelligence合规保障，预置模型丰富
想自部署 + 高精度Datalab Marker 或 MinerU开源可控，精度优秀
格式种类极多Apache Tika1400+ 格式覆盖

PDF 提取图片（PDF Extract Images）

配置项环境变量默认值说明
PDF Extract ImagesPDF_EXTRACT_IMAGESfalse是否从 PDF 中提取嵌入的图片

启用后会增加处理时间和存储空间，仅在文档中的图片内容对问答有价值时开启。

PDF 加载模式

Open WebUI 提供两种 PDF 处理模式，决定了文档在进入切分器之前的预处理方式：

模式行为优点缺点适用场景
Page（页模式）每页作为独立文档单元，保留页边界检索时能精确定位到具体页码跨页内容会被截断PPT 转 PDF、每页独立主题
Single Document（单文档模式）整个 PDF 合并为一个文本块，再统一切分跨页内容不会丢失，语义连贯失去页码定位能力论文、书籍、报告等连续叙述型文档

最佳实践：大多数 RAG 场景推荐 Single Document 模式，因为语义连贯性比页码定位更重要。如果文档每页内容相对独立（如幻灯片），则用 Page 模式。

文本切分（Text Splitting）

文本切分决定了文档被拆分成多大的片段（chunk）存入向量数据库。切分质量直接影响检索精度。

切分器类型

切分器计量方式特点适用场景
默认（Character）按字符数使用递归分隔符（\n\n → \n → 空格 → 字符）逐级切分，简单高效，无依赖英文文档、通用场景
Token按 token 数按模型 tokenizer 计算，切分大小与模型上下文窗口精确对齐中文文档（1 个汉字 ≈ 2-3 个 token）、需要精确控制 token 用量

核心参数

配置项环境变量默认值推荐值说明
Chunk SizeCHUNK_SIZE15001000-2000每个 chunk 的最大大小。太小丢失上下文，太大降低检索精度
Chunk OverlapCHUNK_OVERLAP100Chunk Size 的 5%-15%相邻 chunk 的重叠量，保证边界处语义连贯

参数调优指南：

  • Chunk Size 太小（<500）：上下文不完整，模型难以理解片段含义
  • Chunk Size 太大（>2000）：包含过多无关信息，检索精度下降
  • Chunk Overlap 太小：重要信息可能被切断在两个 chunk 之间
  • Chunk Overlap 太大：存储冗余增加，检索效率降低

Markdown 标题文本分割器

配置项默认值说明
Markdown Header Text Splitter关闭按 Markdown 标题（H1-H6）进行结构化预切分
Chunk Min Size Target—合并过小片段的阈值，建议设为 Chunk Size 的 50%

启用后，文档会先按 Markdown 标题进行结构化预切分，然后再交给标准切分器处理。好处：

  • 保留文档的逻辑结构，每个 chunk 属于明确的章节
  • 避免跨章节切分导致语义混乱
  • 配合 Chunk Min Size Target 参数，可以将过小的片段向前合并（单向合并算法，不跨文档），官方测试显示阈值设为 1000（chunk size 2000 时）可减少 90%+ 的碎片 chunk

最佳实践：如果文档是 Markdown 格式，或提取引擎输出 Markdown（Docling、MinerU、Marker 都输出 Markdown），强烈建议开启此选项。

嵌入模型（Embedding Model）

嵌入模型将文本转换为向量表示，是 RAG 检索的基础。模型质量直接决定检索准确性。

引擎横向对比

引擎配置值费用延迟隐私推荐模型
SentenceTransformers（默认）""免费，本地运行中等（取决于硬件）完全本地all-MiniLM-L6-v2（轻量）、BAAI/bge-m3（多语言）
Ollamaollama免费，本地运行快（已有 Ollama 实例）完全本地nomic-embed-text（推荐首选）、mxbai-embed-large
OpenAIopenai按 token 计费低（云端）数据发送到云端text-embedding-3-small（性价比）、text-embedding-3-large（高精度）
Azure OpenAIazure按 token 计费低（云端）Azure 合规保障同 OpenAI 模型，通过 Azure 部署

各引擎详细说明

使用 Python sentence-transformers 库在本地运行，模型自动从 HuggingFace 下载缓存。零成本、完全隐私，但首次加载模型较慢，且占用服务器内存/显存。默认模型 all-MiniLM-L6-v2 较轻量但精度一般。

⚠️ 网络提示：如果服务器无法访问 huggingface.co，启动时会出现 SSL 重连错误，RAG 功能将不可用。可添加镜像站环境变量解决：

1
2
environment:
  - HF_ENDPOINT=https://hf-mirror.com

如果你已经在用 Ollama 跑 LLM，这是最方便的选择。nomic-embed-text 是社区最推荐的模型：8192 token 上下文、完全开源、在 MTEB 和 LoCo 基准上表现优异。

先下载模型：

1
2
3
ollama pull nomic-embed-text
# 或中文场景
ollama pull bge-m3

然后配置环境变量：

1
2
3
4
environment:
  - RAG_EMBEDDING_ENGINE=ollama
  - RAG_EMBEDDING_MODEL=nomic-embed-text
  - RAG_OLLAMA_BASE_URL=http://ollama:11434

支持任何 OpenAI 兼容端点（包括第三方）。text-embedding-3-small（1536 维）性价比高，text-embedding-3-large（3072 维）精度更好。缺点是有 API 费用、网络延迟、数据隐私风险。

1
2
3
4
5
environment:
  - RAG_EMBEDDING_ENGINE=openai
  - RAG_EMBEDDING_MODEL=text-embedding-3-small
  - RAG_OPENAI_API_BASE_URL=https://api.openai.com/v1
  - RAG_OPENAI_API_KEY=sk-...

本质上是 OpenAI 模型通过 Azure 托管，适合有 Azure 合规要求的企业。

1
2
3
environment:
  - RAG_EMBEDDING_ENGINE=azure
  - RAG_AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com/

嵌入模型选择建议

场景推荐方案理由
本地优先、已有 OllamaOllama + nomic-embed-text最佳平衡，免费、快速、质量好
资源受限、轻量部署SentenceTransformers + all-MiniLM-L6-v2零依赖，内存占用小
中文文档为主Ollama + bge-m3 或 SentenceTransformers + BAAI/bge-m3多语言支持优秀
追求精度且不介意费用OpenAI + text-embedding-3-large精度最高
企业合规要求Azure OpenAI合规保障

其他嵌入参数

配置项环境变量默认值说明
Embedding Batch SizeRAG_EMBEDDING_BATCH_SIZE100批量嵌入大小，显存不足时调小

⚠️ 重要：更换嵌入模型后，所有已有文档必须重新嵌入（re-embed），因为不同模型的向量空间不兼容。确定模型后不要轻易更换。

检索与排序（Retrieval & Ranking）

检索参数决定了从向量数据库中召回多少结果、如何过滤和排序。这是影响 RAG 最终效果的关键环节。

核心检索参数

配置项环境变量默认值推荐值说明
Top KTOP_K55-10返回的最相关 chunk 数量。太少可能遗漏信息，太多会稀释上下文
Relevance ThresholdRELEVANCE_THRESHOLD0.00.2-0.5最低相关性分数阈值，低于此分数的 chunk 被过滤。设为 0 表示不过滤

参数调优指南：

  • Top K 太少（❤️）：可能遗漏重要信息，回答不完整
  • Top K 太多（>10）：包含过多噪音，模型可能被无关内容干扰
  • Relevance Threshold 太低（0）：不过滤，噪音多
  • Relevance Threshold 太高（>0.7）：过滤过严，可能丢失有用信息

混合搜索（Hybrid Search）

配置项环境变量默认值推荐说明
Hybrid SearchENABLE_RAG_HYBRID_SEARCHfalse开启结合向量搜索 + BM25 关键词匹配

混合搜索使用 EnsembleRetriever，同时执行：

  • 向量搜索：基于语义相似度，擅长理解同义词和语义关联
  • BM25 关键词匹配：基于词频统计，擅长精确匹配专有名词、代码、ID 等

两者互补，显著提升召回率，推荐开启。

重排序（Reranking）

配置项环境变量默认值说明
Reranking ModelRAG_RERANKING_MODEL—使用 CrossEncoder/ColBERT 对检索结果重排序
Top K RerankerTOP_K_RERANKER—重排序后保留的结果数

重排序的工作流程：

  1. 先通过向量搜索（+ BM25）召回较多候选结果
  2. 再用 CrossEncoder 模型对每个候选结果与查询进行精细打分
  3. 按新分数重新排序，保留 Top K Reranker 个最相关结果

推荐配合 Hybrid Search 使用，这是提升 RAG 质量最有效的组合。

检索策略建议

文档规模推荐配置
小文档集（<100 个文档）Top K=5，不需要混合搜索和重排序
中等文档集（100-1000）Top K=5-8，开启 Hybrid Search
大文档集（>1000）Top K=8-10，开启 Hybrid Search + Reranking，Relevance Threshold=0.2+

高级设置

RAG 模板与上下文

配置项环境变量默认值说明
RAG TemplateRAG_TEMPLATE内置模板自定义 RAG 提示词模板，控制检索内容如何注入到 LLM prompt
RAG System ContextRAG_SYSTEM_CONTEXTfalse设为 true 将 RAG 上下文放入 system message 而非 user message

RAG System Context 的作用：将检索到的文档内容放入 system message，而非 user message。好处是在多轮对话中可以优化 KV cache 复用（因为 system message 不变），推荐 Ollama/llama.cpp 用户开启。

异步与性能

配置项环境变量默认值说明
Async EmbeddingENABLE_ASYNC_EMBEDDINGfalse后台线程池处理嵌入，上传大量文档时建议开启

文件与工具

配置项默认值说明
File Context启用控制是否对附件执行 RAG 并预注入内容
Builtin Tools启用给模型提供 query_knowledge_bases、search_chats 等函数调用工具

网页加载

配置项环境变量默认值说明
Web Loader SSL VerificationENABLE_WEB_LOADER_SSL_VERIFICATIONtrue网页加载时是否验证 SSL 证书
Google Drive IntegrationGOOGLE_DRIVE_API_KEY 等—Google Drive 文件直接导入

向量数据库（Vector Database）

向量数据库用于存储文档的向量表示，是 RAG 检索的底层存储。

配置项环境变量默认值说明
Vector DBVECTOR_DBchromadb向量数据库类型
Vector DB URLVECTOR_DB_URL—外部向量数据库连接地址

支持的向量数据库

数据库部署方式适用场景特点
ChromaDB内置，无需额外配置个人使用、小团队默认选择，开箱即用
Qdrant需部署独立服务大规模部署高性能，支持过滤
Milvus需部署独立服务企业环境分布式，支持十亿级向量
Weaviate需部署独立服务需要混合搜索内置向量+关键词搜索
OpenSearch需部署独立服务已有 OpenSearch 集群Elasticsearch 开源替代
PGVectorPostgreSQL 扩展已有 PostgreSQL 环境复用现有数据库
Pinecone云端托管云端部署，免运维全托管，按用量计费
S3 VectorAWS S3AWS 生态低成本存储

内置数据库，无需任何额外配置，开箱即用。适合个人和小团队。

1
2
3
environment:
  - VECTOR_DB=qdrant
  - QDRANT_URL=http://qdrant:6333
1
2
3
environment:
  - VECTOR_DB=milvus
  - MILVUS_URI=http://milvus:19530
1
2
3
environment:
  - VECTOR_DB=pgvector
  - PGVECTOR_DB_URL=postgresql://user:pass@postgres:5432/vectors
1
2
3
4
environment:
  - VECTOR_DB=pinecone
  - PINECONE_API_KEY=your-api-key
  - PINECONE_ENVIRONMENT=us-east-1

对于大多数用户，ChromaDB 已经足够使用，无需额外配置。

整体最佳实践总结

根据以上所有配置项的分析，以下是推荐的最佳实践组合：

配置项推荐值理由
提取引擎根据文档类型选择（见引擎选择建议表）复杂 PDF 用 Docling/MinerU/Mistral OCR，简单文档用默认
PDF 加载模式Single Document语义连贯性优先
文本切分器中文用 Token，英文用 Character中文字符数 ≠ token 数
Chunk Size1000-2000平衡上下文完整性和检索精度
Chunk OverlapChunk Size 的 10%保证边界语义连贯
Markdown 标题切分开启（如果文档是 Markdown）保留文档结构，减少碎片
嵌入模型本地：Ollama + nomic-embed-text免费、快速、质量好
Hybrid Search开启向量 + 关键词互补，显著提升召回率
Reranking配合 Hybrid Search 开启提升精度最有效的组合
Top K5-10平衡召回和噪音
Relevance Threshold0.2-0.5过滤低质量结果
RAG System Contexttrue（Ollama 用户）优化多轮对话 KV cache
向量数据库ChromaDB（默认）小团队足够，零配置

💡 核心原则：先确定嵌入模型（确定后不要轻易更换），再开启 Hybrid Search + Reranking，最后根据文档类型选择提取引擎。这三步是提升 RAG 质量投入产出比最高的操作。