RAG on KnightLi的博客

PageIndex 是什么？不用向量库的推理式 RAG 文档索引解析

Wed, 20 May 2026 23:51:37 +0800

VectifyAI/PageIndex 是一个很有意思的 RAG 项目。它不从“再建一个向量库”开始，而是把长文档先整理成类似目录的树状结构，再让 LLM 沿着这棵树做推理式检索。

截至本文整理时，GitHub 页面显示项目约有 31.8k stars、2.7k forks，许可证为 MIT。README 给它的定位是：Vectorless, Reasoning-based RAG，也就是无向量库、基于推理的 RAG。

它想解决什么问题

传统 RAG 的常见路径是：切块、向量化、写入向量数据库，再用相似度搜索召回片段。这套方法简单、通用，也很成熟，但在长篇专业文档里容易遇到几个问题：

相似度不等于真正相关。
文档结构被切块打散，章节关系丢失。
召回结果可解释性弱，很难说明为什么命中这一段。
对财报、监管文件、法律文书、技术手册这类材料，问题往往需要跨章节推理。

PageIndex 的思路是反过来：先把文档组织成语义树，再让模型像人类读目录、翻章节、逐层定位一样查找相关内容。

PageIndex 的基本工作流

README 里把 PageIndex 的检索分成两步：

为文档生成类似 Table-of-Contents 的树状结构索引。
通过树搜索做 reasoning-based retrieval。

这棵树不是简单的文件目录，而是面向 LLM 使用的文档结构。节点里会有标题、页码范围、摘要、子节点等信息。这样模型在回答问题时，不必一开始就面对大量零散 chunk，而是可以先判断应该进入哪个章节，再继续向下搜索。

这种方式更适合结构清晰但内容很长的文档，例如：

金融报告和 SEC filings。
监管材料和合规文档。
学术教材和论文。
法律文件。
技术手册和产品文档。
超过模型上下文窗口的大型 PDF。

和传统向量 RAG 的差异

PageIndex 的核心卖点可以概括成五点。

第一，不需要 Vector DB。它依赖文档结构和 LLM 推理来定位内容，而不是只做向量相似度搜索。

第二，不做传统 chunking。文档会按自然章节组织，而不是被切成固定长度片段。

第三，可解释性更强。检索路径可以对应到页码、章节和树节点，比“向量相似度命中某段文本”更容易追踪。

第四，检索是上下文感知的。问题、对话历史、领域背景都可以影响树搜索路径。

第五，更接近人类专家读文档的方式。人通常不是把整本文档切成小块再算相似度，而是先看目录，再定位章节，最后读细节。

这并不意味着向量库没有价值。更准确的说法是：PageIndex 适合那些“语义相似不够，需要结构和推理参与”的长文档场景。

本地怎么跑

README 提供了本地自托管方式。先安装依赖：

`1`	`pip3 install --upgrade -r requirements.txt`

然后在项目根目录创建 .env，写入 LLM API key。项目通过 LiteLLM 支持多模型：

`1`	`OPENAI_API_KEY=your_openai_key_here`

对 PDF 生成 PageIndex 结构：

`1`	`python3 run_pageindex.py --pdf_path /path/to/your/document.pdf`

也可以处理 Markdown：

`1`	`python3 run_pageindex.py --md_path /path/to/your/document.md`

常见可选参数包括：

--model
--toc-check-pages
--max-pages-per-node
--max-tokens-per-node
--if-add-node-id
--if-add-node-summary
--if-add-doc-description

README 里也提醒，本地开源版本使用标准 PDF 解析。如果是复杂 PDF，项目方的云服务会提供增强 OCR、树构建和检索流程。

Agentic Vectorless RAG 示例

项目还提供了一个 agentic vectorless RAG 示例，使用自托管 PageIndex 和 OpenAI Agents SDK。安装可选依赖后运行：

1
2

pip3 install openai-agents
python3 examples/agentic_vectorless_rag_demo.py

这个示例的价值在于，它把 PageIndex 从“生成文档树”推进到“让 Agent 使用文档树检索”。如果你正在做企业知识库、财报问答、法规问答或技术文档 Agent，这个示例比单纯看 README 更值得跑一遍。

云服务、MCP 和 API

PageIndex 不只是一个 GitHub repo。项目页面还给了几类入口：

自托管：用开源代码本地运行，适合试验和可控部署。
Chat Platform：类似 ChatGPT 的文档分析平台。
MCP / API：方便接入现有 Agent 或自动化流程。
Enterprise：面向私有化或本地部署。

这说明它的定位不是单纯的 demo，而是想把“推理式文档检索”做成一套可集成的文档智能基础设施。

适合哪些场景

PageIndex 比较适合这些任务：

长 PDF 问答。
财报、年报、招股书、监管文件分析。
法律和合规文档检索。
技术手册问答。
多章节教材或论文检索。
需要可解释检索路径的企业知识库。
给 Agent 提供结构化文档上下文。

如果你的材料本身很短、结构不明显，或者只是普通 FAQ，传统 embedding + vector DB 可能已经够用。PageIndex 的优势更容易出现在长文档、强结构、专业领域和需要推理的问题里。

需要注意什么

第一，PageIndex 仍然依赖 LLM。树构建、摘要和检索质量会受模型能力、提示词、文档解析质量影响。

第二，本地版本使用标准 PDF 解析，复杂扫描件、图表密集型 PDF、版式混乱材料可能需要 OCR 和更强的预处理。

第三，无向量库不等于零成本。树构建本身也会消耗模型调用和时间，尤其是大规模文档库。

第四，它更像是文档结构索引和推理检索框架，不是直接替代所有 RAG 技术栈。实际生产里，也可能和向量检索、关键词检索、权限控制、缓存、审计系统一起使用。

小结

PageIndex 的有趣之处在于，它把 RAG 的重点从“文本相似度召回”转向“文档结构 + LLM 推理”。对于长文档和专业文档，这个方向很值得关注。

如果你正在做企业文档问答、金融报告分析、法规检索或技术手册 Agent，可以把 PageIndex 当成一个新的 RAG 架构参考：先让文档有结构，再让模型沿着结构推理，而不是一开始就把所有内容切碎丢进向量库。

参考来源：

GitHub：VectifyAI/PageIndex

OpenKB：把文档编译成可持续更新的 LLM 知识库

Sun, 17 May 2026 17:15:08 +0800

OpenKB 是 VectifyAI 开源的 LLM 知识库工具。

它不是传统意义上“把文档切块、向量化、查询时再拼上下文”的 RAG 系统，而是把原始文档先编译成一个结构化 wiki：有文档摘要、有概念页、有交叉引用，也有后续查询和 lint 检查。换句话说，它更像是一个会持续整理资料的知识库 CLI。

项目地址：https://github.com/VectifyAI/OpenKB

先说结论

OpenKB 值得关注的地方有三点：

它把知识库输出成普通 Markdown 文件，而不是锁在某个专用数据库里。
它用 PageIndex 处理长 PDF，主打无向量数据库的长文档检索。
它强调“知识编译”，让 LLM 生成摘要、概念页和交叉链接，而不是每次提问都从零检索。

这让 OpenKB 更适合长期积累资料的场景，比如论文阅读、项目文档、公司内部资料、技术规范、产品调研和个人知识库。

它也不是万能替代品。如果你需要高并发线上问答、复杂权限管理、Web 管理后台、企业级审计和大规模多租户能力，OpenKB 现在更像一个开发者工具和知识库原型，而不是完整企业知识平台。

OpenKB 是什么

OpenKB 的全名是 Open Knowledge Base。

它以 CLI 形式工作，把放进知识库的原始文档转换、整理、总结，并生成一套 wiki 文件。官方 README 里的描述很直接：OpenKB 会用 LLM 把原始文档编译成结构化、互相链接的 wiki 风格知识库，并通过 PageIndex 支持无向量数据库的长文档检索。

支持的输入格式包括：

PDF
Word
Markdown
PowerPoint
HTML
Excel
纯文本
其他可由 markitdown 转换的格式

生成后的知识库位于 wiki/ 目录，主要包括：

index.md：知识库总览
log.md：操作时间线
AGENTS.md：知识库结构和维护说明
sources/：转换后的原文
summaries/：每份文档的摘要
concepts/：跨文档概念页
explorations/：保存的查询结果
reports/：lint 检查报告

这个设计最大的好处是透明。你可以直接打开 Markdown 文件查看知识库，而不是只能通过一个黑盒检索接口拿答案。

它和传统 RAG 有什么不同

传统 RAG 常见流程是：

把文档切块。
生成 embedding。
存进向量数据库。
查询时召回相关片段。
把片段塞给 LLM 生成答案。

这个流程很成熟，也很适合问答系统。但它有一个问题：知识本身没有真正沉淀。每次提问都在重新找片段、重新拼上下文、重新生成答案。

OpenKB 的思路更偏“先整理，再问答”：

文档进入 raw/。
短文档通过 markitdown 转成 Markdown。
长 PDF 通过 PageIndex 生成树状索引和摘要。
LLM 生成文档摘要。
LLM 读取已有概念页，创建或更新跨文档概念。
知识库索引、日志和交叉链接同步更新。

这样做的结果是，新增一份文档不只是多了一个可检索文件，而是可能更新十几个 wiki 页面。知识会被写进概念页里，并和已有资料发生连接。

这更像人类维护知识库的方式：新资料进来后，不只是存档，还要更新主题页、总结差异、补充引用。

PageIndex 解决什么问题

长文档一直是 RAG 和 LLM 知识库里的难点。

如果直接把长 PDF 切成很多 chunk，容易遇到几个问题：

章节关系丢失。
表格、图片和脚注难处理。
检索片段过碎，答案缺少全局结构。
上下文窗口再大，也不适合把整本文档塞进去。
摘要链路过长时，细节容易被压掉。

OpenKB 使用 PageIndex 来处理长 PDF。按项目说明，PageIndex 会为长文档建立树状索引和摘要，让 LLM 在文档树上推理，而不是直接读取整篇长文档。

这条路线的重点不是“向量相似度最高的几段文本”，而是让模型利用文档层级结构找到相关内容。对于研究报告、论文、说明书、招股书、合规文档这类长材料，这个思路很有意义。

OpenKB 默认可以使用开源版 PageIndex 本地运行；如果需要 OCR、复杂 PDF 处理或更快结构生成，也可以配置 PAGEINDEX_API_KEY 使用 PageIndex Cloud。

安装和快速开始

OpenKB 可以直接通过 pip 安装：

`1`	`pip install openkb`

也可以安装 GitHub 最新版本：

`1`	`pip install git+https://github.com/VectifyAI/OpenKB.git`

从源码开发安装：

1
2
3

git clone https://github.com/VectifyAI/OpenKB.git
cd OpenKB
pip install -e .

创建一个知识库目录：

1
2

mkdir my-kb && cd my-kb
openkb init

添加文档：

1
2

openkb add paper.pdf
openkb add ~/papers/

提问：

`1`	`openkb query "What are the main findings?"`

进入交互聊天：

`1`	`openkb chat`

如果你想让知识库自动处理新文件，可以使用 watch 模式：

`1`	`openkb watch`

之后把文件放进 raw/，OpenKB 会自动更新 wiki。

LLM 配置

OpenKB 通过 LiteLLM 支持多种模型供应商，包括 OpenAI、Claude、Gemini 等。

初始化时可以设置模型，也可以在 .openkb/config.yaml 里配置：

1
2
3

model: gpt-5.4
language: en
pageindex_threshold: 20

模型名称遵循 LiteLLM 的 provider/model 格式。OpenAI 模型可以省略 provider 前缀，例如：

`1`	`model: gpt-5.4`

Anthropic、Gemini 这类模型通常写成：

`1`	`model: anthropic/claude-sonnet-4-6`

`1`	`model: gemini/gemini-3.1-pro-preview`

API key 放在 .env：

`1`	`LLM_API_KEY=your_llm_api_key`

如果启用 PageIndex Cloud，再补充：

`1`	`PAGEINDEX_API_KEY=your_pageindex_api_key`

常用命令

OpenKB 的命令很适合开发者使用：

openkb init：初始化知识库。
openkb add <file_or_dir>：添加文件或目录。
openkb remove <doc>：移除文档，并清理相关 wiki 页面、图片、注册表和 PageIndex 状态。
openkb query "question"：对知识库进行一次性提问。
openkb chat：进入多轮对话。
openkb watch：监听 raw/ 目录并自动更新。
openkb lint：检查知识库结构和内容健康状态。
openkb list：列出已索引文档和概念。
openkb status：查看知识库统计信息。

其中 openkb chat 比 openkb query 更适合连续探索。它支持会话恢复、会话列表和删除，也支持在聊天中使用 slash commands，比如 /status、/list、/add <path>、/save、/lint。

为什么 Markdown wiki 很重要

很多知识库工具的麻烦在于迁移成本。

一旦资料进入专有数据库、专有索引或专有格式，你就很难直接审查、修改、备份和迁移。OpenKB 把结果写成普通 Markdown，这让它天然适合和现有工具配合。

最直接的用法是用 Obsidian 打开 wiki/ 目录：

摘要页可以直接阅读。
概念页可以用 [[wikilinks]] 互相连接。
图谱视图可以看到知识之间的关系。
查询结果可以保存到 explorations/。
AGENTS.md 可以定义知识库维护方式。

这让 OpenKB 不只是一个问答工具，也可以变成个人或团队的知识整理流水线。

适合哪些场景

OpenKB 特别适合这些场景：

论文和技术报告阅读。
项目文档整理。
产品调研资料库。
开源项目源码外的文档知识库。
公司内部规范、会议纪要和说明文档整理。
个人 Obsidian 知识库自动维护。
长 PDF、PPT、Word 和网页资料的结构化沉淀。

如果你经常面对一堆文档，却不只是想“问一句得到答案”，而是希望资料能逐步变成可浏览、可复用、可追踪的知识库，OpenKB 的方向就很对。

使用时要注意什么

第一，OpenKB 依赖 LLM 质量。

摘要、概念页和交叉链接都由模型生成。模型越强，知识编译质量越稳定；模型能力不足时，概念抽取、冲突识别和跨文档综合都会打折扣。

第二，成本要提前估算。

如果一次性导入大量长文档，LLM 调用成本可能不低。建议先用小规模资料集测试，确认输出结构和质量，再扩大导入范围。

第三，生成的 wiki 仍然需要人工审阅。

OpenKB 可以整理资料，但不等于自动保证事实完全正确。重要知识库仍然需要人工检查摘要、概念页和引用关系。

第四，敏感资料要谨慎。

如果使用云端 LLM 或 PageIndex Cloud，就要注意文档里的隐私、商业机密和合规要求。内部资料最好先确认模型供应商、数据保留策略和访问边界。

第五，它目前更偏 CLI 工具。

项目路线图里提到未来会有 Web UI、数据库存储、大规模集合支持和层级概念索引。但在当前阶段，如果团队成员不熟悉命令行，使用门槛仍然存在。

和 Obsidian、NotebookLM、企业 RAG 的关系

OpenKB 和 Obsidian 的关系更像“自动整理层”和“阅读编辑层”。

Obsidian 适合人来写、改、浏览和建立链接；OpenKB 适合把原始文档批量整理成可以进入 Obsidian 的 wiki。

OpenKB 和 NotebookLM 的关系则更偏“本地可控”和“开放文件形态”。

NotebookLM 使用体验更直接，适合把资料丢进去快速问答和生成摘要；OpenKB 更适合开发者把整理结果留在本地目录里，用 Markdown 继续维护。

OpenKB 和企业 RAG 的关系不是替代，而是补位。

企业 RAG 更看重权限、审计、服务化、权限隔离、监控和稳定吞吐。OpenKB 更适合构建一个可读、可改、可长期沉淀的知识层。未来如果要做线上问答，也可以把 OpenKB 生成的 wiki 作为更高质量的语料来源。

一个推荐工作流

如果你想试 OpenKB，可以按这个顺序来：

新建一个测试知识库目录。
先放 3 到 5 份同一主题的文档。
运行 openkb add。
打开 wiki/ 查看摘要和概念页。
用 openkb query 问几个具体问题。
用 openkb lint 检查知识库健康状态。
用 Obsidian 打开 wiki/，看链接图谱是否有意义。
确认质量后，再导入更大的文档集合。

不要一上来就把几百个文件全丢进去。先看它对你的资料类型是否理解得好，尤其是表格、图片、长 PDF 和多文档概念合并效果。

总结

OpenKB 的价值在于，它把 LLM 知识库从“查询时临时拼上下文”往前推了一步：先把资料整理成 wiki，再在 wiki 上问答、聊天、检查和继续维护。

这条路线不一定适合所有问答系统，但很适合需要长期沉淀的知识工作。Markdown 文件、Obsidian 兼容、PageIndex 长文档处理、多模型支持和 CLI 工作流，组合起来就是一个很适合开发者和研究型用户的知识库工具。

如果你手上有大量 PDF、报告、网页、论文和项目文档，OpenKB 值得试一下。它未必能马上替代成熟企业知识库，但可以成为一个很实用的资料整理入口：先把文档变成可读、可链接、可追踪的知识，再让 LLM 在这套知识上工作。

参考链接：

计算机术语人话版：TTS、STT、API、RAG、Agent 到底在说什么

Tue, 12 May 2026 22:15:34 +0800

计算机领域有很多词，第一次听会觉得很高级。可一旦翻译成人话，往往就是日常生活里很简单的动作。

比如 AI 能说话，叫 TTS；AI 能听你说话，叫 STT。听起来像复杂系统，拆开就是“把文字读出来”和“把声音写下来”。

参考链接：https://www.zhihu.com/question/267978646/answer/2035405228460201515

这篇就从这个角度串讲一些常见术语：保留术语本身，但把它们说成人话。

TTS 和 STT：文字和语音互转

TTS 是 Text-to-Speech，意思是“文本转语音”。你输入一段文字，系统把它变成声音。导航播报、电子书朗读、AI 客服开口说话，都属于这个方向。

STT 是 Speech-to-Text，意思是“语音转文本”。你对手机说一句话，系统先把语音识别成文字，再交给后面的程序处理。语音输入法、会议转写、自动字幕、智能音箱，都离不开它。

很多语音 AI 产品的流程其实就是：

STT：把你说的话转成文字。
LLM：根据文字生成回答。
TTS：把回答读出来。

所以它看起来像在和你自然聊天，底层往往是几个模块在接力。

OCR：从图片里抄字

OCR 是 Optical Character Recognition，中文常说“光学字符识别”。

听起来很硬核，其实就是从图片里把文字抄出来。拍一张发票、扫描一页书、识别身份证上的姓名和号码，本质都是 OCR。

以前 OCR 更像“看字形猜文字”，现在会结合深度学习，对复杂背景、倾斜文字、手写字和低清图片的容忍度更高。但它解决的核心问题仍然很直接：图片里有什么字？

NLP 和 LLM：让机器处理人话

NLP 是 Natural Language Processing，自然语言处理。它处理的是人类语言，比如分词、翻译、摘要、情感分析、问答、分类。

LLM 是 Large Language Model，大语言模型。它可以理解和生成文本，所以今天很多 NLP 任务都被 LLM 接管了。

人话版理解：

NLP：让机器处理人说的话、写的字。
LLM：一个更大的文本模型，能接住很多语言任务。

你让 AI 总结文章、写邮件、改标题、解释代码，背后都属于这个大方向。

API 和 SDK：一个是接口，一个是工具包

API 是 Application Programming Interface，应用程序编程接口。

人话就是：别人把能力开一个入口给你调用。比如天气 API，你传城市，它返回天气；支付 API，你传订单，它返回支付结果。

SDK 是 Software Development Kit，软件开发工具包。

人话就是：为了让你更方便调用 API，官方把常用代码、类型、示例和工具打包给你。API 像餐厅窗口，SDK 像点餐小程序。你可以直接去窗口说需求，也可以用小程序点得更省事。

CRUD：增删改查

CRUD 是 Create、Read、Update、Delete。

翻译成人话就是：新增、查看、修改、删除。

很多后台系统、管理系统、数据库操作，本质都在围绕 CRUD 打转。用户管理、文章管理、订单管理、库存管理，看起来业务不同，底层经常都是一组表单加一组增删改查。

这也是为什么程序员会说“又写了一个 CRUD”。不是看不起这个工作，而是它确实太常见。

Cache：先放一份，省得每次重算

Cache 是缓存。

人话就是：常用的东西先放在手边，下次直接拿，不要每次都重新找、重新算、重新请求。

网页加载慢，可以把图片和脚本缓存起来；数据库查询慢，可以把热门结果放进 Redis；模型推理贵，可以缓存重复问题的答案。

缓存的难点不在“放一份”，而在“什么时候更新”。数据变了，缓存没变，就会出现旧数据。这就是很多缓存问题的根源。

Queue：排队慢慢处理

Queue 是队列。

人话就是：事情太多，先排队，一个一个处理。

比如用户上传视频后，不一定马上转码完成。系统可以先把任务放进队列，后台服务慢慢处理。发短信、发邮件、生成报表、处理订单回调，也经常用队列。

队列解决的是“不要所有事情都卡在当前请求里”。用户先得到响应，耗时任务放到后面做。

Index：给数据库做目录

Index 是索引。

数据库里的索引，可以理解成书的目录。没有目录，你要从第一页翻到最后一页；有目录，你可以更快定位到目标内容。

但索引不是越多越好。查询会变快，写入和更新可能变慢，因为数据改了，索引也要跟着维护。

所以数据库优化里常见的一句话是：慢查询先看索引。但真正做索引时，还要看查询条件、排序字段、数据量和写入频率。

RPC、REST 和 Webhook：系统之间怎么说话

RPC 是 Remote Procedure Call，远程过程调用。

人话就是：我像调用本地函数一样，去调用另一台机器上的函数。

REST 常见于 Web API。它更像用 URL 和 HTTP 方法来表达资源操作，比如 GET /users 查用户，POST /orders 创建订单。

Webhook 则是反过来通知你。你不用一直问“好了没”，对方处理完后主动回调你的地址。

简单记：

RPC：像远程调用函数。
REST：用 HTTP 管理资源。
Webhook：事情发生后主动通知你。

CDN 和 Load Balancing：离你近一点，分担一点

CDN 是 Content Delivery Network，内容分发网络。

人话就是：把静态资源放到离用户更近的节点。用户访问图片、视频、CSS、JS 时，不必每次都跑到源站。

Load Balancing 是负载均衡。

人话就是：访问量太大，不要让一台服务器硬扛，把请求分给多台机器。

一个偏“离用户近”，一个偏“别让机器累死”。大型网站通常两个都会用。

Docker、Container 和 Kubernetes：打包、运行、调度

Docker 是常见的容器工具，Container 是容器。

人话就是：把程序和它依赖的环境打包在一起，换一台机器也尽量能一样运行。这样可以减少“我电脑上能跑，服务器上不能跑”的问题。

Kubernetes，常写作 K8s，是容器编排系统。

人话就是：当容器很多时，帮你安排它们运行在哪里、挂了怎么重启、流量怎么分、版本怎么更新。

如果只有一个小服务，Docker 就够了；如果有很多服务、很多机器、很多副本，才会更需要 K8s。

CI/CD：自动构建、自动发布

CI 是 Continuous Integration，持续集成。

人话就是：代码一提交，系统自动拉代码、跑测试、构建，尽早发现问题。

CD 可以指 Continuous Delivery 或 Continuous Deployment，持续交付或持续部署。

人话就是：构建通过后，把代码更稳定、更自动地送到测试环境或生产环境。

它解决的不是“写代码”，而是“写完代码之后，怎么少出错地上线”。

Serialization：把对象打包成可传输格式

Serialization 是序列化。

人话就是：把程序里的对象变成能保存、能传输的格式，比如 JSON、XML、Protobuf。

反过来，Deserialization 是反序列化：把这些格式再还原成程序能用的对象。

你在前后端之间传 JSON，在服务之间传 Protobuf，本质都离不开序列化。

Token、Embedding、Vector DB：把文字变成模型能处理的形式

Token 在大模型里通常指文本切分后的基本单位。它不一定等于一个汉字或一个英文单词，更像模型内部处理文本时的颗粒。

Embedding 是嵌入向量。

人话就是：把文字、图片或其他内容变成一串数字，让模型可以比较它们之间的相似度。

Vector DB 是向量数据库。

人话就是：专门存这些向量，并且能快速找出“意思相近”的内容。

比如你问“怎么重置路由器”，系统可能去向量库里找“恢复出厂设置”“忘记 Wi-Fi 密码”“后台登录失败”等相近内容，再拿回来给模型参考。

RAG：先查资料，再回答

RAG 是 Retrieval-Augmented Generation，检索增强生成。

人话就是：模型回答前，先去资料库查相关内容，再带着资料回答。

它解决的是大模型容易“凭记忆瞎说”的问题。把企业文档、知识库、产品手册、代码片段接进来，模型就不只是靠训练时的记忆，而是能参考你给它的最新资料。

典型流程是：

用户提问。
系统把问题转成 Embedding。
去 Vector DB 里找相关文档。
把文档片段和问题一起交给 LLM。
模型生成回答。

所以 RAG 听起来高级，本质是“先翻资料，再组织语言”。

Agent：会自己拆任务的自动化流程

Agent 在 AI 语境里经常被翻译成智能体。

人话就是：它不只是回答一句话，而是能根据目标拆步骤、调用工具、观察结果，再决定下一步。

比如你让它“帮我分析这个仓库为什么测试失败”，普通聊天模型可能只给建议；Agent 则可能会读文件、运行测试、看报错、改代码、再跑测试。

当然，Agent 不等于一定可靠。它只是把“模型 + 工具调用 + 状态循环”串起来。真正好不好用，还要看工具权限、任务边界、错误处理和人工确认机制。

小结

很多计算机术语之所以显得高级，是因为它们被英文缩写、架构图和产品文案包了一层壳。拆开之后，大多是在描述很朴素的动作：

TTS：把文字读出来。
STT：把声音写下来。
OCR：从图片里抄字。
API：开放一个调用入口。
SDK：把调用工具打包好。
CRUD：增删改查。
Cache：常用结果先存一份。
Queue：任务排队慢慢处理。
Index：给数据做目录。
CDN：把内容放近一点。
Load Balancing：把请求分散一点。
Docker：把运行环境打包。
CI/CD：让测试和发布自动化。
Embedding：把内容变成数字向量。
RAG：先查资料，再回答。
Agent：让模型带着工具分步做事。

术语要保留，因为它们方便搜索、沟通和查文档。但理解时不用被它们吓住。先翻译成人话，再回到技术细节里看，很多概念会清楚得多。

参考

知乎回答：https://www.zhihu.com/question/267978646/answer/2035405228460201515

Gemini Embedding 2：把文本、图像、视频和音频放进同一个向量空间

Mon, 04 May 2026 06:01:10 +0800

Google Developers Blog 介绍了 Gemini Embedding 2 的开发用法。这个模型已经通过 Gemini API 和 Gemini Enterprise Agent Platform 进入 GA，重点不只是“新的 embedding 模型”，而是把文本、图像、视频、音频和文档映射到同一个语义空间。

这会让检索系统的边界变宽：过去很多 RAG 流程需要先把图片、视频、音频拆成文字或元数据，再单独建索引；Gemini Embedding 2 则可以直接处理多模态输入，让代理、搜索和分类系统更容易围绕真实业务材料工作。

原文链接：Building with Gemini Embedding 2: Agentic multimodal RAG and beyond

模型能力

Gemini Embedding 2 支持 100 多种语言。单次请求可以处理：

最多 8,192 个文本 token
最多 6 张图片
最多 120 秒视频
最多 180 秒音频
最多 6 页 PDF

它的关键点是“统一语义空间”。开发者可以把不同模态的内容放在同一套向量表示里，用同一种检索、聚类或重排序逻辑处理。

例如，文本描述和图片可以放在同一次 embedding 请求里：

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()
result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        "An image of a dog",
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

print(result.embeddings)

如果你希望每个输入分别得到 embedding，而不是聚合成一个向量，可以使用 Batch API。原文也提到，Agent Platform 对这类批量支持还在跟进中。

对 RAG 的意义

多模态 embedding 对代理式 RAG 很有用。一个 AI agent 可能需要同时检查代码仓库、PDF、截图、图表、音频会议记录和产品图片。如果所有资料都能进入同一个语义空间，检索链路就不必为每种材料单独设计一套入口。

Google 建议根据任务使用 task prefix，让 embedding 更贴近检索目标。例如问答、事实核查、代码检索和搜索结果，可以使用不同前缀：

# Generate embedding for your task's query:
def prepare_query(query):
    return f"task: question answering | query: {content}"
    # return f"task: fact checking | query: {content}"
    # return f"task: code retrieval | query: {content}"
    # return f"task: search result | query: {content}"
# Generate embedding for document of an asymmetric retrieval task:
def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

这种前缀适合非对称检索：用户查询往往很短，文档内容往往很长。把 query 和 document 分别按任务格式整理，可以改善短查询到长文档之间的匹配。

原文给了两个落地反馈：

Harvey 在法律检索基准上，Recall@20 precision 相比上一代 embedding 提升 3%。
Supermemory 在 Recall@1 搜索准确率上提升 40%，并把它用于记忆、索引、搜索和问答管线。

这些数字不代表所有场景都会同幅度提升，但说明多模态 embedding 已经不只是演示能力，而是在真实检索产品中产生效果。

视觉搜索

Gemini Embedding 2 也适合做以图搜图、图文混合搜索和商品识别。原文提到服装租赁公司 Nuuly 用它匹配仓库中未打标签的服装照片，使 Match@20 从 60% 提升到接近 87%，总体成功识别率从 74% 提升到 90% 以上。

这类场景的关键不是生成内容，而是理解“这张图片和哪个库存、文档或商品记录最接近”。如果你的业务里有大量图片、视频片段或扫描件，多模态 embedding 会比纯文本索引更自然。

检索重排序

Embedding 还可以用于 rerank。常见做法是先用基础检索拿到一批候选结果，再计算候选结果和用户查询之间的相似度，把更相关的内容排到前面：

# 1. Define a function to calculate the dot product (cosine similarity)
def dot_product(a: np.ndarray, b: np.ndarray):
  return (np.array(a) @ np.array(b).T)
# 2. Retrieve your embeddings
# (Assuming 'summaries' is your list of search results)
search_res = get_embeddings(summaries)
embedded_query = get_embeddings([query])

# 3. Calculate similarity scores
sim_value = dot_product(search_res, embedded_query)

# 4. Select the most relevant result
best_match_index = np.argmax(sim_value)

原文还提到一种思路：先让模型根据内部知识生成一个假设答案，再把这个假设答案做 embedding，与候选内容比较相似度，用来挑出语义更贴近的结果。这对问答型 RAG 尤其有用。

聚类、分类和异常检测

除了检索，embedding 也适合聚类、分类和异常检测。和前面的问答检索不同，这些属于对称任务，query 和 document 可以使用同一种任务前缀：

# Generate embedding for query & document of your task.
def prepare_query_and_document(content):
    # return f'task: clustering | query: {content}'
    # return f'task: sentence similarity | query: {content}'
    # return f'task: classification | query: {content}'

这类任务可以用于舆情分类、内容审核、相似资产归类、异常样本发现，也可以帮助 agent 对大量上下文材料先做整理，再进入后续推理。

存储和成本

Gemini Embedding 2 默认输出 3,072 维向量。它使用 Matryoshka Representation Learning，因此可以通过 output_dimensionality 把向量截断到更小维度。Google 推荐在效率优先时使用 1,536 或 768 维：

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config={"output_dimensionality": 768}
)

向量可以存到 Agent Platform Vector Search、Pinecone、Weaviate、Qdrant、ChromaDB 等系统里。成本方面，原文提到 Batch API 可提供更高吞吐，并达到默认 embedding 价格的 50%。

开发者该怎么用

如果你已有文本 RAG，可以先从两类增量改造开始：

把 PDF、截图、图片说明和文本文档放入同一个索引，测试查询召回是否更稳定。
给不同任务加 task prefix，例如问答、事实核查、代码检索、商品搜索，不要把所有内容都按同一种 embedding 方式处理。

如果你在做新产品，可以优先考虑这些方向：

企业知识库：同时检索文档、图表、演示稿截图和会议材料。
视觉搜索：用图片、文本或混合输入查找商品、资产、设计稿和档案。
Agent 工具链：让 coding agent、研究 agent 或客服 agent 检索多种格式的业务材料。
内容治理：对文本、图片、视频片段做统一分类、聚类和异常检测。

Gemini Embedding 2 的价值在于把多模态材料变成同一套可检索资产。对开发者来说，这会减少“先转文字再检索”的中间层，也让 RAG 系统更接近真实世界的数据形态。

常见向量模型怎么选：OpenAI、BGE、E5、GTE、Jina 对比

Thu, 23 Apr 2026 15:23:47 +0800

做 RAG、语义搜索、知识库召回时，很多人一开始会纠结同一个问题：向量模型这么多，到底该选哪一个。

常见模型大致可以分成两组。一组是通用文本向量，覆盖中英文和多语言任务；另一组更适合中文场景，重点看中文检索、中文问答和中文知识库效果。

如果先给一个很短的结论，可以这样看：

想省事、直接用 API：text-embedding-3-small 或 text-embedding-3-large
想做中文检索，且希望开源可自部署：bge-base-zh-v1.5、bge-m3、gte-large-zh
想兼顾多语言：multilingual-e5-base、multilingual-e5-large、jina-embeddings-v3
想在中文场景里压成本：bge-small-zh-v1.5、gte-base-zh

一、先按类型看这些模型

1. OpenAI 系列

text-embedding-3-small
text-embedding-3-large

这类模型的特点是调用简单、稳定，适合直接接 API 做检索、RAG、分类和相似度匹配。它们的优势不在“某一个中文榜单分数特别高”，而在整体体验完整：接入门槛低、效果稳定、工程成本也低。

如果团队不想自己托管模型、不想维护推理服务，OpenAI 这类方案通常最省时间。

2. BGE 系列

BAAI/bge-small-zh-v1.5
BAAI/bge-base-zh-v1.5
bge-m3

BGE 是中文检索里很常见的一条线。bge-small-zh-v1.5 和 bge-base-zh-v1.5 更偏中文单语任务，适合中文语义搜索、知识库召回、FAQ 匹配。bge-m3 则更通用，能覆盖多语言、多粒度和更复杂的检索场景。

如果你的数据主要是中文文本，BGE 往往是最容易进入候选名单的一组。

3. E5 系列

intfloat/multilingual-e5-base
multilingual-e5-large

E5 系列的特点是多语言能力比较均衡，适合中英混合、跨语种检索、国际化内容库。它不是只盯中文，而是更强调“不同语言都能放到一个统一检索体系里”。

如果你的语料不是纯中文，而是中文、英文、日文甚至更多语言混在一起，E5 通常比中文专用模型更稳。

4. GTE 系列

Alibaba-NLP/gte-base-zh
gte-large-zh

GTE 在中文任务里也很常见，定位和 BGE 有点接近，都是中文检索的实用型选手。它的特点通常是比较平衡，没有特别复杂的使用门槛，适合做中文知识库、站内搜索和企业内部文档召回。

如果你想在中文开源模型里多做一组对照，GTE 很值得一起评测。

5. Jina Embeddings

jina-embeddings-v3

Jina 这一类更偏通用和现代工程场景，常见于多语言检索、长文本、网页内容处理等任务。它经常出现在“一个模型覆盖更多任务形态”的讨论里，适合希望统一 embedding 层的团队。

如果你的内容来源比较杂，既有网页、文档，也有多语言文本，Jina 往往是一个值得测试的备选。

二、中文场景里，哪些模型更常用

如果把范围收窄到中文场景，常见候选基本就是这些：

bge-small-zh-v1.5
bge-base-zh-v1.5
bge-m3
gte-base-zh
gte-large-zh
multilingual-e5-base
multilingual-e5-large

这几类里，最典型的分法其实不是“谁绝对更强”，而是下面这三个问题：

你的数据是不是以中文为主
你是不是需要多语言
你更在意效果、成本，还是部署方便

三、把这些模型放在一起看

1. 如果只看中文效果

纯中文知识库、中文问答、中文文档召回，一般优先看 BGE 和 GTE。

bge-small-zh-v1.5：更轻，适合成本敏感场景
bge-base-zh-v1.5：通常是中文场景里更均衡的一档
gte-base-zh：和轻量 BGE 类似，适合先做基线
gte-large-zh：更适合追求召回质量的场景
bge-m3：适合希望把中文检索和更复杂能力放到一起考虑的团队

如果语料几乎全是中文，E5 虽然也能用，但很多时候不会是第一优先。

2. 如果需要多语言

这时优先级会明显变化。

multilingual-e5-base 和 multilingual-e5-large 更适合多语言统一检索
jina-embeddings-v3 也适合多语言和通用文本任务
bge-m3 比传统中文专用模型更适合扩展到多语言
text-embedding-3-small 和 text-embedding-3-large 适合想直接上 API 的场景

如果你的库里同时有中文、英文、产品文档、网页文案和用户问题，多语言模型会比中文专用模型省掉很多后续改造成本。

3. 如果要控制推理和存储成本

轻量模型更有优势。

bge-small-zh-v1.5
gte-base-zh
multilingual-e5-base
text-embedding-3-small

这类模型通常更适合：

文档量大
更新频繁
需要批量向量化
对延迟和成本比较敏感

如果数据规模很大，embedding 维度、推理速度、索引占用都会直接影响总成本，所以“先上小模型做基线”通常是更稳的做法。

4. 如果优先追求上限

更大的模型通常更适合复杂检索或高质量召回，例如：

text-embedding-3-large
multilingual-e5-large
gte-large-zh
bge-base-zh-v1.5
bge-m3

但这里要注意，模型越大不代表线上体验一定越好。很多项目最后的瓶颈不是模型本身，而是切分策略、召回条数、重排、数据清洗和评测方式。

四、每个模型更适合什么任务

模型	更适合的场景	简单判断
`text-embedding-3-small`	通用检索、RAG、快速接入	API 省事，成本友好
`text-embedding-3-large`	更重视质量的通用检索	效果优先，工程最省心
`bge-small-zh-v1.5`	中文轻量检索	中文常用入门款
`bge-base-zh-v1.5`	中文知识库、FAQ、语义搜索	中文场景很均衡
`bge-m3`	中文为主但希望兼顾更复杂检索	扩展性更强
`multilingual-e5-base`	多语言基础检索	国际化项目常用
`multilingual-e5-large`	多语言高质量召回	更偏效果导向
`gte-base-zh`	中文轻量召回	适合先做基线
`gte-large-zh`	中文质量优先场景	可作为 BGE 对照组
`jina-embeddings-v3`	多语言、网页、通用文本任务	统一 embedding 层时值得测

五、实际选型时可以怎么决策

如果你只是要落地，而不是写论文，选型顺序可以简单一点：

场景一：中文知识库

优先测试这几组：

bge-base-zh-v1.5
gte-large-zh
bge-small-zh-v1.5

如果预算紧，先从小模型开始；如果更重视召回质量，再往更大的模型试。

场景二：中英混合知识库

优先测试：

multilingual-e5-base
multilingual-e5-large
text-embedding-3-small
text-embedding-3-large

如果不想自部署，OpenAI 会更直接；如果要自己托管，E5 更常见。

场景三：中文为主，但未来可能扩到多语言

优先测试：

bge-m3
multilingual-e5-base
jina-embeddings-v3

这类场景最怕的是一开始只看中文，后面又要重做整个向量库。

六、最后怎么选，关键不是“榜单第一”

向量模型选型里，最容易踩的坑就是只看公开分数，然后直接上线。

更靠谱的方式通常是：

先挑 2 到 4 个候选模型
用自己的真实数据做 embedding
跑一轮召回评测
再结合成本、延迟、部署方式做决定

因为真正决定结果的，往往不是模型名本身，而是模型和你的语料、分块策略、查询形式到底合不合。

总结

如果只想记住一版实用结论，可以这样：

中文优先：先看 bge-base-zh-v1.5、gte-large-zh
成本优先：先看 bge-small-zh-v1.5、gte-base-zh、text-embedding-3-small
多语言优先：先看 multilingual-e5-base、multilingual-e5-large、jina-embeddings-v3
直接上 API：先看 text-embedding-3-small、text-embedding-3-large
想兼顾中文和后续扩展：先看 bge-m3

没有一个模型适合所有项目，但大多数项目都可以先从这几组里很快筛出第一批候选。

AI 名词解释：用大白话讲清楚 Agent、MCP、RAG 和 Token

Thu, 23 Apr 2026 13:13:40 +0800

刚开始接触 AI，最容易劝退人的通常不是模型本身，而是讨论里那些一串串名词。Agent、MCP、RAG、AIGC、Token 看起来都很常见，但如果没人先用人话讲一遍，很多人其实只是在“眼熟”，并没有真正听懂。

这篇就顺着一组常见入门解释的思路，把 10 个高频 AI 名词压缩成一套更容易记住的解释。目标不是讲得多学术，而是先帮你建立一个能跟上日常讨论的基础框架。

10 个常见 AI 名词，分别是什么意思

1. Agent：不只会聊天的执行型 AI

Agent 可以先理解成“会干活的 AI 助手”。

普通聊天机器人更像是你问一句、它答一句；Agent 则更进一步，它会把任务拆开、安排步骤、调用工具，再把结果交回来。比如你让它帮你整理资料、查信息、生成文档，它不只是给建议，而是可能直接把这些动作串起来做完。

所以 Agent 的关键，不在“会不会说”，而在“能不能做”。

2. OpenClaw：驻留在电脑里的 AI 助手

视频里把 OpenClaw 形容成一种“住在电脑里的 AI 管家”。

你可以把这类工具理解成更贴近桌面操作的 AI 助手：它不只是接收文字，还可能直接观察界面、调用本地工具、按流程执行任务。和普通网页聊天相比，这类工具更强调实际操作能力。

如果说 Agent 是抽象层面的“执行型 AI”，那这类桌面型助手更像是它在个人电脑上的一种具体落地形式。

3. Skills：给 Agent 装上的能力包

Skills 可以理解成 Agent 的功能模块或操作说明。

同一个 Agent，装上不同的 Skills，就能表现出不同的专长。比如有的偏文案生成，有的偏数据整理，有的偏代码处理。它们有点像手机里的 App，也有点像一套套可复用的工作流程。

所以很多时候，不是模型突然“变聪明”了，而是它背后多了一组明确的规则、工具和步骤。

4. MCP：AI 连接外部工具的统一接口

MCP 全称是 Model Context Protocol。

如果用生活里的比喻，它有点像 AI 世界里的 Type-C 接口。以前模型想接不同工具，往往要一套一套单独对接；有了统一协议之后，接入方式会更标准，也更容易复用。

对普通用户来说，最值得记住的一点是：MCP 解决的不是“模型会不会回答”，而是“模型怎么安全、稳定地连上外部工具和资源”。

5. 抽卡：AI 生成结果带有随机性

“抽卡”这个说法常见于 AI 绘图、视频生成和内容创作场景。

意思很简单：同样的提示词、同样的大方向，每次生成出来的结果也可能不一样。有时候效果惊艳，有时候明显翻车，所以很多人会把反复尝试生成结果这件事，形容成像游戏里抽卡。

它提醒我们的其实是同一件事：AI 生成不是固定公式，而是带概率和波动的过程。

6. API：应用和模型之间的连接方式

API 全称是 Application Programming Interface，也就是应用程序接口。

它可以理解成程序之间沟通的标准入口。你在自己的应用、脚本或编辑器里调用模型服务，本质上就是通过 API 发请求、拿结果。

如果把模型服务比作一家餐厅，那么：

菜单像 API 文档
点菜像发起 API 请求
后厨出餐像模型返回结果

所以很多工具表面上看起来不一样，底层其实都是在调用某种 API。

7. 多模态：AI 不只处理文字

“多模态”说的是 AI 不再只会读写文本，而是可以同时处理多种信息形态。

比如它可以看图、听语音、理解视频、生成图片，甚至做实时语音和视频交互。和早期只会处理文字的模型相比，多模态模型更像是在同时拥有“看、听、说、写”的能力。

这也是为什么现在很多 AI 产品的交互方式，已经不再局限于一个输入框。

8. RAG：先检索资料，再组织答案

RAG 是 Retrieval-Augmented Generation，通常译作检索增强生成。

它适合解决一个很现实的问题：模型本身的训练数据有时间边界，也不知道你企业内部的新文档、客服记录和业务规则。RAG 的思路就是，先从指定资料里把相关内容找出来，再结合这些资料生成回答。

它的价值通常体现在三点：

答案更容易贴近真实资料
可以追溯回答依据来自哪里
新文档加入后，知识可随时更新

所以很多企业知识库、智能客服和内部问答系统，底层都会用到 RAG。

9. AIGC：AI 生成内容的总称

AIGC 是 AI Generated Content 的缩写。

它不是某一个单独工具，而是一个总称，泛指 AI 生成出来的内容，包括文本、图片、音频、视频等各种形式。你看到的 AI 写稿、AI 制图、AI 做短视频、AI 配音，都可以放进 AIGC 这个大框里理解。

这个词真正重要的地方在于，它描述的是一种内容生产方式，而不是某个具体模型。

10. Token：模型处理内容时的计量单位

Token 可以理解成模型处理文本时使用的基础计量单位。

它不完全等于“一个字”或者“一个单词”，但在使用层面上，你可以先把它当成模型计算和计费时的通用单位。你的输入会消耗 Token，模型的输出会消耗 Token，上下文里保留的历史内容同样会占用 Token。

所以为什么很多模型服务都在强调上下文长度、成本控制和压缩提示词，本质上都和 Token 有关。

RAGFlow 项目整理：开源 RAG 引擎的功能与使用方法

Wed, 15 Apr 2026 22:09:25 +0800

RAGFlow 是 infiniflow 开源的 RAG（Retrieval-Augmented Generation，检索增强生成）引擎。它的目标不是只做一个“上传文件然后问答”的知识库外壳，而是把文档解析、切分、检索、重排、引用溯源、模型配置、Agent 能力和 API 集成放进一套完整工作流里。

如果你正在做企业知识库、文档问答、客服助手、内部资料检索，或者想给 LLM 加一层更可靠的上下文来源，RAGFlow 属于值得重点看的开源方案。

01 RAGFlow 解决什么问题

普通 RAG 系统最容易遇到的问题有三个：

文档解析质量不稳定，尤其是 PDF、扫描件、表格、图片、复杂排版文档。
切分策略不透明，命中结果看起来像“搜到了”，但上下文并不完整。
回答缺少可靠引用，用户很难判断答案来自哪里。

RAGFlow 的重点正好放在这些地方。项目 README 里强调了 Deep document understanding、模板化切分、可视化 chunk、引用溯源和多路召回加重排。换句话说，它更关注“高质量数据进入，高质量答案出来”，而不是只把向量数据库和聊天框接起来。

02 核心功能

1. 深度文档理解

RAGFlow 支持从复杂格式的非结构化数据中抽取知识。README 中列出的数据类型包括 Word、PPT、Excel、TXT、图片、扫描件、结构化数据、网页等。

这对企业知识库很关键。真实资料通常不是干净的 Markdown，而是合同、报告、表格、扫描 PDF、产品手册、截图和网页混在一起。如果解析质量不够，后面的向量检索和 LLM 回答都会被拖垮。

2. 模板化切分

RAGFlow 提供模板化 chunking。它的价值在于：切分策略不是黑盒，可以根据文档类型选择更合适的方式。

例如普通文章、论文、表格、问答文档、图片说明、合同条款，对 chunk 的粒度和边界要求都不一样。模板化切分可以减少“句子被切碎”“表格上下文丢失”“标题和正文分离”这类问题。

3. 可追溯引用

RAGFlow 强调 grounded citations，也就是回答要能追溯到来源片段。它还提供 chunk 可视化，方便人工干预解析和切分结果。

这点对生产环境尤其重要。企业内部问答不是只要“看起来像答案”，还要能查证来源。对于政策、合规、财务、技术文档、客户支持资料来说，引用和溯源几乎是刚需。

4. 自动化 RAG 工作流

RAGFlow 把 RAG 流程做成相对完整的链路：

创建知识库
上传或同步数据
解析文档
查看和干预 chunk
配置 LLM 与 embedding 模型
执行多路召回与重排
构建聊天助手
通过 API 集成到业务系统

这让它更像一个 RAG 平台，而不是一个单点库。对于团队来说，UI、可视化和 API 都有价值：非研发人员可以维护知识库，研发人员可以把能力接入已有系统。

5. Agent、MCP 与工作流能力

RAGFlow 的近期更新里已经包含 Agentic workflow、MCP、Agent Memory、代码执行组件等内容。这说明它不只想做传统知识库问答，也在向 Agent 场景延伸。

典型方向是：Agent 在执行任务时，可以把 RAGFlow 作为可靠的企业知识上下文层；需要查资料时从知识库召回，生成回答时保留引用，必要时再组合工具调用或工作流。

03 基本使用流程

按照官方快速开始文档，RAGFlow 的常见使用路径可以概括为下面几步。

1. 准备运行环境

官方 README 给出的基础要求是：

CPU >= 4 cores
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0
Docker Compose >= v2.26.1

如果要使用代码执行器的沙箱功能，还需要 gVisor。另外要注意，官方 Docker 镜像主要面向 x86 平台；如果是 ARM64，需要按官方说明自行构建镜像。

2. 拉取项目

1
2

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

3. 检查 `vm.max_map_count`

RAGFlow 部署会依赖 Elasticsearch / OpenSearch 这类组件，因此 Linux 上通常需要确认：

`1`	`sysctl vm.max_map_count`

如果数值低于 262144，可以临时设置：

`1`	`sudo sysctl -w vm.max_map_count=262144`

如果希望重启后仍然生效，需要写入 /etc/sysctl.conf。

4. 使用 Docker Compose 启动

CPU 模式可以直接启动：

`1`	`docker compose -f docker-compose.yml up -d`

如果要用 GPU 加速 DeepDoc 任务，README 中给出的方式是在 .env 中启用 DEVICE=gpu 后再启动：

1
2

sed -i '1i DEVICE=gpu' .env
docker compose -f docker-compose.yml up -d

启动后查看日志：

`1`	`docker logs -f docker-ragflow-cpu-1`

看到服务启动完成后，再通过浏览器访问服务器地址。默认配置下，通常可以直接访问：

`1`	`http://IP_OF_YOUR_MACHINE`

5. 配置模型 API Key

RAGFlow 需要配置 LLM 和 embedding 模型。README 提到可以在 service_conf.yaml.template 中选择默认 LLM factory，并更新对应的 API_KEY。

实际使用时，你需要根据自己的模型供应商配置：

聊天模型
embedding 模型
rerank 模型
多模态模型（如果要理解 PDF / DOCX 中的图片）

6. 创建知识库并上传文档

服务启动后，典型操作是：

登录 Web UI。
创建 dataset / knowledge base。
上传文档或配置数据源同步。
等待解析完成。
查看 chunk 结果，必要时人工调整。
创建聊天助手，选择知识库。
测试问答效果和引用来源。

如果要接入业务系统，可以继续使用 RAGFlow 的 API 或 SDK，把知识库检索和聊天能力接到自己的应用里。

04 适合哪些场景

RAGFlow 适合这些需求：

企业内部知识库问答
产品手册、技术文档、FAQ 检索
客服助手和售前支持助手
合同、报告、制度文件的可追溯问答
多格式资料统一整理
需要 UI 维护知识库，同时又要 API 集成的团队
想把 RAG 能力作为 Agent 上下文层的系统

它尤其适合文档格式复杂、需要引用溯源、希望人工干预解析结果的场景。

05 使用时要注意什么

第一，RAGFlow 不是轻量脚本。它对机器资源有要求，官方建议至少 4 核 CPU、16GB 内存和 50GB 磁盘。如果只是给少量 Markdown 做问答，可能没必要上这么完整的平台。

第二，文档质量仍然重要。RAGFlow 能改善解析和切分，但不能让低质量、过期、互相矛盾的资料自动变得可靠。真正上线前，知识库治理仍然要做。

第三，模型配置会直接影响效果。embedding、rerank、聊天模型、多模态模型的选择，都会影响召回和回答质量。RAGFlow 提供了工作流，但效果仍然要靠数据、模型和参数一起调。

第四，生产环境要关注权限和数据安全。企业知识库里往往有内部资料，部署方式、访问控制、日志、API Key、模型供应商数据策略都要提前设计。

06 简短判断

RAGFlow 的优势在于把 RAG 里最麻烦的部分做成了平台化能力：复杂文档解析、可解释切分、引用溯源、多路召回、重排、模型配置、Web UI、API 和 Agent 扩展。

如果你要做的是可验证、可维护、可接入业务系统的企业知识库，RAGFlow 比“向量库 + 简单聊天 UI”的方案更完整。反过来，如果只是个人小规模资料问答，或者数据格式非常简单，轻量 RAG 框架可能更省资源。