企业官网建设流程全解析

我做的这个项目，内部代号叫 REA。名字没什么深意，就是从 R（Retrieval）、E（Extraction）、A（Agent）三个核心词里各取了一个字母，用来表示"检索—抽取—执行"这条完整链路。做它的初衷也很朴素：去年我在整理一批历史项目文档和散落在十几个文件夹里的技术笔记时，发现真正花时间的不是写代码，而是"找到东西、看懂东西、把东西从上下文里捞出来"这个过程。REA 就是针对这个痛点做的一个自动化检索与摘要抽取工具，目标用户是我自己这类需要频繁翻旧资料、从长文本里提炼关键信息、再把提炼结果丢给下游流程去用的开发者。

它可以做什么？简单说，输入一段种子关键词或者问题，REA 会在你指定的目录、代码仓库或者本地知识库里做语义检索，把命中的文档段落提取出来，再通过一个可配置的抽取模型生成结构化摘要，最后把结果以统一格式输出，供后续脚本、流程或其他工具直接调用。不是搜索引擎的替代品，而是更偏"定向抽取"和"流程编排"的那一类工具。

这篇我会把整个项目的思路、核心实现、踩过的坑和调优经验完整记录下来，包括一些常规文档里不会写的东西：比如为什么选某种切片策略而不是另一种、为什么抽取模型换了三版才稳定、以及实测下来哪些环节最容易被低估。适合正在做本地知识库工具、文档处理流水线，或者准备自己造轮子做信息抽取的同学参考。

1. 项目要解决的真实痛点：我以为缺的是搜索，实际缺的是"定向抽取"

先说结论：如果你只是嫌本地文件搜不到东西，那用一个全文索引工具就够了，REA 这套东西对你来说属于过度设计。它的价值在于"从检索结果里进一步提炼结构化信息"，比如状态、责任人、结论、参数、版本号这类可复用字段。这是普通搜索给不了的东西。

我最早的需求场景是这样的：某天下午要写一份季度复盘，需要从几十份周报里找出每个阶段提到的"风险项"和"应对措施"。用系统自带搜索把相关周报一篇篇翻出来，眼睛扫一遍提取信息，然后手动贴进表格。这个过程耗费了大概大半天。我当时就想，如果有一个工具能自动完成"检索—切片—提取—汇总"这四步，把几十篇文章变成一个结构化的风险清单表格，那该多省事。REA 就是顺着这条路子走下来的。

为了把这个需求讲得更清楚，我拆成了三个层次：

第一层是"能不能找到"。传统的关键词匹配在遇到同义表述、口语化描述或者跨文档信息时基本失效。比如你搜"网络超时"，命中不了写的是"连接经常断"的文档。这需要语义检索，也就是把文本转成向量，通过空间距离找相似内容。

第二层是"找到了能不能看懂"。文档里的关键信息往往藏在冗长段落中间。比如某篇周报里有句话："本周中段出现了支付接口偶发超时的现象，经排查是上游回调延迟导致的，后续接入了重试机制，目前未再复现。"这里面"风险项"是支付接口偶发超时，"应对措施"是加重试机制，"状态"是已解决。人眼能秒读，但机器要稳定地从这类句子里抽取出来，就得靠实体识别加关系判断那一套。

第三层是"抽取出来能不能直接用"。如果只是打印在控制台里，那跟人眼读一遍没有本质区别。REA 的定位是"给流程用的工具"，所以输出必须结构化、可二次消费，比如 JSON 格式、字段固定、附带原文出处。这样才能衔接后面的自动化报告生成、定时巡检、异常预警这些下游环节。

这个三层拆解基本决定了 REA 的模块划分：检索器负责第一层，切片器配合抽取模型负责第二层，输出格式化器负责第三层。整体链路清晰，每个模块都能独立替换，这也是后面迭代时最受益的设计决策。

2. 整体架构与关键选型：不是所有组件都需要"最新最强"

架构上我走了一条非常朴素的管道式路线，没有上任何繁琐的框架。整个 REA 由五个模块串联：输入解析器、语义检索器、文档切片器、信息抽取器、结构化输出器。每个模块之间只通过标准数据格式通信，这意味着你可以在任意环节换成自己的实现。

数据流大概是这样的：种子问题进来，解析器把它转成检索条件并生成向量，检索器从向量库里召回候选文档片段，切片器把这些片段按语义边界切成若干 chunk，抽取器逐 chunk 扫描并抽取目标字段，输出器汇总去重后按统一 schema 返回。整个过程可以批量跑，也可以按需执行。

选型上我坚持三个原则：

原则一，模型要能本地跑。因为处理的文档里有一部分是内部开会纪要、未公开的技术方案，不适合送外部接口。所以语义检索模型和抽取模型都选了可以在本地 CPU/GPU 上运行的开源模型，数据不出内网。代价是效果上跟商业大模型有差距，但通过提示词优化和结构化约束可以弥补大部分。

原则二，组件要能单独替换。向量库一开始用的内存字典，后来切到更正规的向量数据库，只用改检索器内部实现，其他模块一点没动。如果某天想换更强的抽取模型，同样只需要替换抽取器里的模型调用。

原则三，避免过度工程。项目初期没有引入消息队列、容器编排这类东西。因为在个人工作流里，并发量根本到不了那一步。REA 就是一个命令行工具加一个 Python API 接口，简单直接。

各模块选型落地如下：

这套组合的完整跑通，验证了一个观点：不追最新的模型和架构，把每个环节的边界梳理清楚，反而更容易做出可靠的工具。

3. 核心模块拆解实现：检索、切片、抽取、输出的完整链路

这章是全文最核心的部分，我会按模块顺序把实现思路和关键代码逻辑串一遍。每个模块都会讲清楚"做了什么"和"为什么这么做"。

3.1 检索模块：语义召回是怎么从"找词"变成"找意思"的

检索模块的输入是一个查询串，输出是候选文档片段列表。实现分三步：先把查询串转成向量，然后在向量库里做相似度检索，最后按相似度阈值过滤并排序返回。

向量库里的数据是怎么来的？启动时会扫描你指定的根目录，对每个文件做格式识别。支持纯文本、Markdown、Word 和 PDF 这几种常见格式。文本提取之后按文档切片器切成 chunk，每个 chunk 用 embedding 模型转成一个多维向量，连同元信息（文件路径、标题、页码、chunk 序号）一起写入向量库。

查询的时候用的是同一个 embedding 模型做向量化。这里有个非常容易踩的坑：查询端的文本规范化规则必须跟入库时完全一致。比如入库前统一把全角括号转半角，那查询时也要做同样的转换，否则同一个词在两端生成向量的细微差异会被放大，导致关联度下降。REA 里我会把文本清洗函数设定为全局共用，确保两侧行为一致。

相似度计算我用的是内积，具体来说，存储前会把向量做归一化，然后内积等价于余弦相似度。至于为什么不用 L2 距离，因为归一化之后内积在排序稳定性上表现更好，对阈值也更好调。

召回流程本身很简单：召回 topK 候选，按相似度排序，保留高于阈值的片段。

def retrieve(query_vec, top_k=20, threshold=0.42): candidates = vector_db.search(query_vec, top_k) results = [] for doc_id, chunk_id, vec, meta in candidates: score = np.dot(query_vec, vec) if score >= threshold: results.append({ "doc_id": doc_id, "chunk_id": chunk_id, "text": get_chunk_text(doc_id, chunk_id), "score": float(score), "meta": meta }) results.sort(key=lambda x: x["score"], reverse=True) return results

这里 threshold 取 0.42 是我在实测语料上调出来的经验值，稍后会在踩坑章节展开讲。现在只需要记住：阈值太低压入噪声，阈值太高漏掉相关片段，这个值跟你的语料分布和模型都有关，必须动态调。

3.2 切片模块：为什么 chunk 切得好不好，直接决定抽取效果的上限

讲切片之前先讲一个我踩过的惨痛教训。第一版 REA 用的是固定长度切片，每 500 个字符切一段，不做任何语义处理。结果是抽取模块经常从中间断开的句子里提取出残缺字段，比如把"支付接口偶发超时"切成"支付接口偶发"和"超时，经排查…"两段，后者的关键信息就丢了。

后来我把切片策略改了：先用递归字符分割器按段落拆，再对超长段落做边界检测。具体逻辑是尽量让每个 chunk 在 600 到 800 字之间，并且只允许在句号、分号、段落换行这些语义边界处切断。如果碰到底层没有边界的大文本，就回退用固定长度但不截断句子，宁可让 chunk 略微超长也不牺牲完整性。

切片模块的输出是 chunk 列表，每个 chunk 带上所在文档 ID 和全局序号。之所以强调 chunk ID 要全局唯一，是因为后续抽取结果需要追溯到原文，这个操作靠 chunk ID 做映射最稳。

实践里我发现，对高度结构化文档（比如表格型周报），按 Markdown 标题层级切比按句号切效果更好；但对没有层级的长篇散文式博客，句号切分更稳。REA 里做了一个简单策略：优先按文档本身的标题结构切，没标题结构就按段落边界切。这是性价比很高的一种做法，既不需要引入昂贵的分层模型，也能覆盖绝大多数文档类型。

3.3 抽取模块：如何让模型稳定输出指定字段，而不是自由发挥

信息抽取是 REA 里迭代最多、也最考验耐心的模块。我的目标是从候选 chunk 里抽取出用户预先定义好的字段。比如一个风险清单的 schema 可能是这样的：

{ "risk_item": "风险项描述", "impact": "影响范围", "solution": "应对措施", "status": "状态: 解决中/已解决/未解决" }

问题在于，抽取模型如果不受约束，输出格式会五花八门。有时候字段名变成了"风险"而不是"risk_item"，有时候凭空多出一段解释文字。为了稳定格式，我做了两件事：

第一件事，把 schema 描述直接写进提示词，几轮测试调整后，把期望输出格式固化成了模板，要求模型只输出 JSON，不要解释。

第二件事，对输出结果做后处理校验，用 schema 里的字段清单比对模型输出，如果缺失或类型不对，就做一次带修正提示的重抽取。这个机制把格式错误率从最初的 30% 降到了 5% 以下。

关键提示词模板大致是这样的：

"文本片段：\n{text}\n\n请从上述文本中抽取以下字段：\n- risk_item: 风险项描述\n- impact: 影响范围\n- solution: 应对措施\n- status: 风险状态\n\n只输出 JSON，不要输出任何解释。"

这套组合的代价是多了一次后处理调用的开销，但在批量场景下完全可以接受。我更在意的是下游流程能稳定吃到结构化数据，为此多花一点算力是值得的。

3.4 输出模块：带溯源的结构化结果，才是"给流程用"的结果

输出模块解决的是兼容性。目前我用的是 JSON Lines 格式，每行一个抽取结果。每条结果包含四个固定字段：chunk_id，对应原文内容，抽取的字段字典，以及相似度得分。

带 chunk_id 的主要目的是溯源。如果下游发现某条抽取结果有问题，可以瞬间定位到原文位置，省去了大海捞针的排查时间。这在使用 REA 生成周报数据时特别重要，至少提升了数据校对的效率。

除了 JSON Lines，REA 还内置了一个简单的汇总器，可以把同一文档里多条抽取结果合并成一个条目。比如一个季度几十份周报都提到"支付接口超时"，汇总器会把它们的处理状态、出现时段归并成表格行，这就是我最初想要的"自动风险清单"效果。

{"chunk_id": "doc17-chunk03", "text": "本周中段出现了支付接口偶发超时的现象...", "extracted": {"risk_item": "支付接口偶发超时", "impact": "支付链路可用性下降", "solution": "接入重试机制", "status": "已解决"}, "score": 0.67}

输出模块还有一个细节：为了避免下游被空字段打扰，我会在输出前过滤掉"字段值为空"的 chunk。这个过滤策略看似很简单，但在实际使用里可以避免大量无效后处理。

4. 实测效果与调优过程：从"能跑通"到"好用"之间隔着一个调参地狱

项目第一版跑通后，我用历史周报做了一批测试，结论是"能跑通，但你不会想在日常里用"。主要问题有三类：召回精度不稳、抽取格式错乱、重复信息过多。这一节记录我是怎么一步步把这些坑填平的。

4.1 召回精度对比：阈值不是越大越好，也不是越小越好

我最早把相似度阈值设成 0.30，召回的结果里混入了大量主题沾边但实质无关的 chunk。比如搜"支付网关超时"，会召回不少讲"网络架构演进"的内容，因为都涉及网络。后来我把阈值往上调到 0.42，情况明显改善。但这不代表阈值越高越好。调到 0.55 之后，相关内容的召回率明显下降，有些只在不同词面下讲同一件事的 chunk 就被筛掉了。

调阈值时一个实用的思路是：先跑一批带标注的样本，画出召回率和精度的权衡曲线，找拐点。如果没有标注样本，一个粗糙的经验法则是把阈值设在最大相关命中分数和最大无关命中分数之间，REA 初版就是这样调的。

实践中我还会在检索模块里输出每个 chunk 的得分分布，辅助判断阈值是否合理。如果几乎所有得分都集中在 0.3 到 0.5 之间，那就要考虑是 embedding 模型不匹配语料，而不是阈值的问题。

4.2 抽取模型的三次换血：从通用到领域适配的演进

第一版抽取模块用的是通用生成模型。效果怎么说呢，摘要味很重，抽出来的"风险项"经常是原文的重述，而不是精准字段。比如原文"上游 DNS 解析偶尔失败，导致部分用户访问异常"，它会抽成"存在用户访问异常的风险"，丢失了"上游 DNS 解析失败"这个真正有价值的实体。

第二版换了抽取能力更强的模型，但仍然没有很好地约束输出。这在处理几百个 chunk 时特别明显，结果里混进大量解释性文本，把 schema 变得稀碎。

第三次迭代我决定上"结构化提示词 + 后处理校验"的双保险，把字段描述写死在提示词里，同时在后处理阶段校验字段存在性。这次改动带来的提升很直观：格式正确率到了 95% 上下，字段信息也基本能对位原文。由此得到一个经验：模型能力不是唯一决定因素，"提示词怎么约束"和"结果怎么校验"同样关键。

4.3 chunk 大小对抽取效果的直接影响

我用同一批周报跑了三组对比，分别用 300 字、700 字、1200 字作为目标 chunk 大小。300 字档召回效果好，但抽取字段经常因为上下文不足而缺信息，比如只知道"支付接口超时"却不知道"已解决"这个状态。1200 字档上下文充足，但抽取模型面对大段文本时容易漏字段，也更容易被无关信息干扰。

最后取了个折中值：700 字左右。这个体量既能保留关键上下文，又不至于让模型注意力被稀释。不同文档类型可能各有最优值，比如会议纪要短段落多，400 字更合适；技术方案长段落多，1000 字也不嫌大。所以我把 chunk 大小做成了可配置项，默认 700，按场景覆盖。

4.4 一个完整实例：从十篇周报到结构化风险清单

贴近实际跑一遍 REA，大家会更直观地看它到底干了多少活。

我把 10 篇历史周报丢进测试目录，配置目标字段为 risk_item、impact、solution、status，然后执行检索和抽取。整个过程大概耗时 40 秒，输出了一共 47 条有效抽取结果，覆盖了 6 个不同的风险主题：支付接口超时、数据库慢查询、告警通道延迟、需求排期冲突、部署脚本权限问题、第三方回调节流。

其中"支付接口超时"这一主题下，分散在 4 篇周报里的信息被汇总成一行：

• risk_item：支付接口偶发超时
• impact：支付链路可用性下降，部分用户支付失败
• solution：接入重试机制，排查上游回调延迟
• status：已解决（第 3 周起未再复现）

我看了下，这个结果跟人工整理的高度一致，而且标注了哪些 chunk 支撑的结论。从输入到输出，手写实现整个过程大概需要半个工作日，REA 跑一次是 40 秒。这就是这个东西的价值所在。

5. 踩坑记录与避坑指南：那些文档里不会写但你迟早会遇到的问题

每次复盘这类项目，真正值钱的其实不是架构多漂亮，而是那些让你耗掉一整个下午的问题。下面这几个坑我都有切肤之痛，写出来希望你能提前避开。

第一个坑：向量匹配与字符清洗不一致

这是检索效果差的第一大来源。入库时做了全角转半角、大小写统一、去多余空格，查询时没做同样处理，导致同一句话的两个版本算出来相似度偏低。解决办法前面提过：把清洗函数做成公共函数，入库和查询强制调用同一套逻辑。我用这个办法解决了大量"为什么我觉得相关却召不回"的疑惑。

第二个坑：切片切断句子，直接废掉候选

固定长度切片导致实体在切割处被拆开，抽取模块就抽不到完整字段。这是抽取效果差的元凶之一。解决办法是切片时优先找句号、分号、换行符这类边界，宁可多留一点上下文也不切半个句子。REA 里还加了一个二次检查：如果 chunk 末尾不是终止标点，就把末尾不完整句子挪到下一个 chunk 开头。

第三个坑：抽取结果里混入"解释性废话"

生成模型默认会附带解释，比如"根据您提供的文本，我提取到以下字段"。你可以用提示词约束"只输出 JSON"，更可靠的办法是后处理阶段剥除多余文本。我的做法是：先检查输出能否被 json.loads 解析，失败则用正则提取大括号区域做二次解析，再失败才触发重抽取。这套兜底逻辑让很多偶发格式错误无声无息地消失了。

第四个坑：向量库更新后相关性反而下降

我给一批文档重新建了索引，发现同类查询的召回质量下降。排查后发现旧索引里混着一批已被覆盖的旧 chunk，导致检索结果里新旧内容混杂。解决办法是每次重建索引前先清理全部旧向量，再执行增量写入。经验的归纳就是：索引管理要像数据库迁移一样谨慎，别图省事执行全量写入。

第五个坑：批量处理时内存失控

处理大批量文档时，如果一次性把所有文档读入内存再切片再向量化，中等体量语料就可能撑爆内存。REA 后来改成流式处理：扫描队列里逐个文档读取、切片、向量化、写库，然后释放内存。这个改动让批量处理能力和稳定性都上了一个台阶。

第六个坑：调参之后效果没法复现

REA 的 threshold、chunk_size 等参数分散在代码各处，改了一次之后回不去。后来我把所有超参数集中到一个 dataclass 配置类里，并且每次跑批都会把配置快照打到结果文件的头部。这样效果好坏都可以复现、可以对比，排查问题时少走很多弯路。

从第一版能跑通，到后来真正变成我每周都在用的工具，中间最大的感悟就是：这类工具的价值不在于"用最新最强模型"，而在于把每个环节的边界、格式、异常处理都做扎实。如果你也在做类似的东西，希望这份记录能帮你省下一些本该花在调试上的时间。