企业官网建设流程全解析

1. 项目定位与整体拆分思路

1.1 为什么是from-scratch

我最初看到这个标题时，第一反应是"又一份AI资源清单"，但真正深入进去才发现，ai-engineering-from-scratch想表达的东西完全不一样。它不是在罗列"推荐你学这个、用那个"的收藏夹，而是试图回答一个更原始的问题：如果一个人完全从零开始，不依赖任何现成的低代码平台、不套用别人的成熟模板，能不能靠自己的双手把一个AI产品从数据到上线完整地搭出来？

这个问题的答案直接决定了学习路径的走向。过去几年AI领域的最大幻觉是"会调API就等于会AI"，实际上真的上手做项目时你会发现，模型调用只是最后一公里。前面还有数据清洗、索引构建、检索调优、评估迭代、部署监控这一整条链路，每一环都可能成为项目炸掉的导火索。from-scratch这个思路把重心从"消费模型能力"拉回到"构建系统能力"，这才是AI工程和AI调包侠之间的本质分水岭。

我自己的体会是，这个项目适合三类人：第一类是后端或全栈工程师，想搞清楚AI应用在现场到底是怎么跑起来的；第二类是算法工程师，觉得自己模型功底不错但一搞工程就手足无措；第三类是真正零基础的转行者，想找一条能看到全貌、能动手、能积累作品的学习主线。无论哪类人，都应该带着一个实打实的问题来学，比如"我要做一个公司内部的知识库问答机器人"，而不是漫无目的地刷教程。

1.2 四条关键主线：数据、模型、评估、工程

如果把AI工程拆到最简，我会把它分成四条主线，每条主线都是一整套独立的能力域，而且互相之间是有先后依赖关系的。

数据主线是第一位的，也是最容易被忽略的。很多人拿着一个开箱即用的RAG框架跑demo，感觉一切都很顺，但一到自己的业务数据上就翻车，原因几乎都出在数据这层：格式乱七八糟、编码不一致、表格和PDF混在一起、专有名词满天飞。没有一条干净、稳定、可重复的数据处理流水线，模型再强也发挥不出来。

模型主线是大家最熟悉的部分，但工程视角下的模型能力和算法视角完全不同。工程侧更关心的是：不同模型在不同任务上的性价比、单次请求延迟能不能接受、上下文窗口怎么利用最划算、模型输出需要什么约束。这些问题的答案往往不是靠论文，而是靠benchmark和压测得出来的。

评估主线是AI工程里最像"良心活"的部分，因为它又难又不可省。传统软件的评估是确定性测试，AI应用则充满不确定性：同样的输入，模型今天答得好明天答得稀碎，你怎么知道改动到底是变好了还是变坏了？没有一套系统的评估机制，后期迭代就是在打地鼠。

工程主线负责把前面三条串成一个可交付的系统，涉及服务化部署、接口设计、性能优化、监控告警、成本控制。from-scratch项目的魅力就在这里：每条线你都得亲手摸一遍，而不是装个框架就当完事了。下面我会按实际动手顺序把每条线拆开来讲。

2. 核心技术栈与学习路径规划

2.1 基础设施与数据能力：从Python到数据处理流水线

不管项目最终用什么模型、什么框架，Python都是绕不开的第一道门槛。这里说的"会Python"不是能跑通教程那种程度，而是你真正能用它处理脏数据、写工程代码的水平。我自己见过太多人卡在NumPy和Pandas上，明明思路有了，数据一复杂就不知从何下手。

建议的基础设施学习路径是：Python基础语法与类型注解，到Pandas做表格数据的清洗与聚合，再到正则表达式处理杂乱文本。这个阶段不要碰任何AI库，先把数据操作练熟。你可以找一份真实的业务数据来练手，比如网上公开的电商评论、客服工单、招聘信息，练习目标是能独立完成"读取-清洗-转换-导出"的完整闭环。

数据清理其实是整个项目中性价比最高的投资。你在数据上省下的每一个小时，都会在后面检索效果和模型输出质量上加倍回报。举个最简单的例子：正文里包含大量HTML标签的网页抓取数据，如果你不做清洗就直接切chunk，不仅浪费token，检索命中率还会被噪声干扰。清洗这一步做好了，后面很多问题都能在源头杜绝。

数据能力这一层还需要掌握的最重要技能是文本切分。这听起来简单，但实际非常讲究。我通常把切分策略分成固定长度切分、结构感知切分、语义切分三个层级。固定的字符数切分最基础也最粗暴，按500个字符切一刀，可能把一个完整段落拦腰斩断，导致检索到半个段落语义残缺；结构感知切分是按Markdown标题、HTML标签、段落边界、代码块来切，保住了语义完整性；语义切分则是用embedding的相似度自动找切分点，效果好但计算成本高。from-scratch项目要求的是按场景选对策略，而不是无脑用一个库。

2.2 模型能力与RAG核心组件

模型层是AI工程的心脏。这一层的核心不是"背几个模型名字"，而是建立一套选型思路。以中文场景为例，embedding模型方面国内常用的有bge系列，它的中文语义理解能力比OpenAI的text-embedding-3在部分垂直领域表现更稳；生成模型方面，兼顾效果与成本时可以考虑Qwen系列的开源权重模型，追求零部署成本时则可以直接调用各家API。

RAG（检索增强生成）是当前AI工程最主流的应用范式，我把它拆成三个你必须亲自实现一遍的组件。第一个组件是向量化：把文本切块后用embedding模型映射成向量，这个过程的参数选择直接决定后续检索质量。第二个组件是向量存储：可以用FAISS做本地轻量方案，也可以上Milvus、pgvector这样的生产级方案。第三个组件是检索融合：不止向量检索一种方式，关键词检索（比如BM25）在很多场景下表现反而更好，把两者结果做融合排序，往往能带来明显的效果提升。

我强烈建议你至少手动实现一次简化版的RAG流程，不要一上来就上LlamaIndex或者LangChain。这不是否定框架的价值，而是你如果不亲手写一遍数据加载、切分、向量化、检索、拼接上下文、调模型这几个步骤，后面用框架时你根本不知道它替你做了什么、在哪个环节可能出错。很多线上事故排查到最后，都是"框架默认行为不符合你的数据特征"这种问题，没亲手写过一遍的人很难定位到根因。

关键参数这块也得做到心里有数。常见的文本切分参数是chunk_size 300到500字符、overlap 50到80字符，但这个值并非通用，需要根据你的文档结构和模型上下文长度调整。召回参数top_k通常取3到5，取决于问题复杂度；温度参数temeperature在事实问答场景调到0.1到0.3左右，在创意写作场景再放开。这些参数都不是理论推出来的，是你反复刷测试集刷出来的，评估这一步咱们后面单独讲。

2.3 Agent与工具调用的工程视角

聊完RAG，再来看Agent。这是AI工程里话题度最高也最容易产生误解的部分。工程视角下的Agent，核心不是"智能体突然涌现了智能"，而是"把模型能力拆解成多个可控的子任务组合"。

一个典型的Agent工作流包含规划、工具调用、结果整合这几个环节。规划环节让模型决定下一步做哪个动作，工具调用环节让模型对接外部系统，结果整合环节把多轮信息汇总成最终答复。这里最大的工程难点是控制：你给Agent的自由度越大，出错的可能性越高，尤其在生产环境里，工具调用链一旦失控，可能造成不可逆的操作。

from-scratch的学习路径上，我会建议从最简单的ReAct范式入手，让模型按"思考-行动-观察"的循环来完成任务。先手动实现一个能调用搜索引擎或者计算器的单工具Agent，再去理解多工具路由、工具编排这些复杂机制。工程上有一个特别实用的原则：能用RAG解决的场景，就不要为了炫技加Agent；能用一个工具调用完成的，就不要设计三步链。系统越复杂，越难评估、越难排查，训练和运营成本也越高。

3. 从零落地一个知识库问答项目

3.1 需求拆解与数据准备：把目标翻译成工程任务

理论知识讲再多也不如动手做一个完整项目，我建议从零搭一个公司内部知识库问答助手，比如把产品文档、技术规范、FAQ整理成系统，让同事用自然语言提问，系统给出带依据的回答。这个项目麻雀虽小五脏俱全，能覆盖AI工程的主要环节。

第一步是需求拆解，你要把模糊的业务诉求翻译成可实施的工程指标。用户说"回答要准确"，你就要把它拆成能测量的指标，比如检索命中率、答案忠实度、引用可追溯性。用户说"响应要快"，你就要定义P95延迟目标是多少秒。这个翻译过程本身就是AI工程和纯算法工作的最大区别。

数据准备阶段最有挑战性的是处理混合格式的文档。一套真实的知识库里可能同时有Markdown文档、PDF、Excel表格甚至扫描件。我的实操方案是分类型走通道：结构化数据走CSV导入加字典构建，半结构化文档走格式解析加结构切分，非结构化文本走纯文本抽取加清洗。对PDF这种格式，纯文本抽取往往效果不好，我一般先用工具把PDF转成Markdown再做后续处理，这样能保留标题层级和表格结构，为后续做结构感知切分打基础。

清洗环节有几个细节值得单独提一下。第一，要把全角半角统一、编码统一成UTF-8、多余空白符压缩掉；第二，要处理敏感信息和隐私数据，比如把身份证号、手机号做脱敏，避免进入知识库；第三，要去除版权信息、页眉页脚、水印内容。这些看似琐碎的操作，直接影响向量检索的效果和合规安全。

3.2 索引构建与检索实现：亲手写一遍才懂的原理

数据准备好后，进入索引构建环节。我的建议是先用一个2000段左右的测试集来做实验，不要一上来就全量构建，这样迭代成本低、调试快。

切分参数我通常会跑一组对比实验。比如固定文本分别按300、400、500字符切，再配合不同的overlap，然后人工抽查一批问题的检索命中质量，选表现最稳的一组参数。这个"稳"字很关键，它代表的不只是平均指标好，而是各种刁钻问题都能找到相关内容，没有明显的偏科。

向量化阶段要记录好三样东西：embedding模型的维度、归一化方式、批量推理的吞吐量。这些信息在后续选型、扩容、成本估算时都要用。向量存储方面，本地实验用FAISS最省事，但要正式上线的话还是建议用Milvus或者pgvector，原因是一旦数据量超过数百万量级，纯内存方案在持久化和动态更新上会非常吃力。

检索实现的正确姿势是构建混合检索。我实际项目里最常用的方案是向量检索和BM25关键词检索双路召回，再用RRF（Reciprocal Rank Fusion）算法做结果融合。这个方案的好处是实现简单、效果稳定，尤其适合专业名词多、代码片段多、拼写不规范的文档场景。纯向量检索的问题在于：如果用户的提问用词和文档用词差异大，embedding可能拉不回相关内容，而关键词检索恰好能补上这一环。

检索到的内容建议返回top_k个chunk，默认给5个左右，同时要求把每个chunk的来源（文档名、章节、页码）一并返回。这一步非常关键，因为后续评估要考察"是不是引用了正确的文档"，如果你不记录来源，发现问题时很难定位到底哪一环出了错。

3.3 生成、评估与上线：让系统真正可用

检索链路打通后，生成环节相对直接，但有两个容易被忽视的细节。一个是上下文压缩，当检索到的内容过长超过模型上下文窗口时，盲目截断不如做摘要压缩，保住关键信息的同时省token。另一个是prompt的系统设计，你要明确告诉模型：只能基于给定上下文回答、不能编造、如果上下文无关就明确说不知道、回答时列出引用来源。这套系统prompt的质量，决定了整个产品体验的天花板。

评估环节是我踩过最多坑的地方。早期我都是靠人工看几十条问答结果觉得"还行"就上线，结果发现改一个检索参数，几个经典问题变好了，另外冷门问题全崩了，没有数据根本定位不了。后来我梳理出一套适合自己的评估体系，分三个维度：检索效果指标（命中率、召回率、MRR）、生成质量指标（忠实度、相关性、完整性）、工程指标（延迟、成本、失败率）。

具体做法是准备一份50到100条的评测集，每条包含一个真实问题和对应的理想文档范围。每次改动后跑一遍评测集，对比三维度的量化打分，而不是靠感觉。评估集的价值会随着项目迭代越来越大，它相当于AI系统的回归测试，没有它，你永远不敢放心地调整任何东西。

上线部署我的建议是服务化拆分。检索服务单独跑一个API，生成服务单独跑一个API，中间用消息或HTTP调用串联。这样做的最大好处是你可以独立扩容检索集群或生成集群，不会一方抖动拖垮全局。部署时用Docker做容器化，用FastAPI暴露接口，前面再挂一层Nginx做负载均衡，这套技术栈虽然朴素但非常实用。可观测性上必须把三段链路都做埋点：检索耗时、模型首字耗时、完整响应耗时，以及每一跳的失败率和token消耗。缺少可观测性的AI应用就像没有仪表盘的飞机，起飞容易，降落全凭运气。

4. 实操中的常见问题与排查技巧实录

4.1 检索效果差：从数据清洗到索引重建的排查顺序

我做知识库项目时遇到最多的问题就是"用户问了一个问题，系统回答'不知道'，但文档里明明有答案"。这类问题90%以上不是模型笨，而是检索环节没召回相关内容。排查时按顺序来：先确认问题里的关键术语是否和文档用词一致；再验证embedding检索的top_k结果里是否真的没有相关内容；如果没有，就用同样的关键词做BM25检索，对比两路结果差异。

这个排查过程能很快定位到问题归属，是切分粒度问题、embedding模型问题，还是查询改写问题。切分粒度问题通常表现为："问题的答案是跨段落组合而成的，单看chunk都不完整"，解决办法是增大chunk_size或改用结构感知切分，让相关文本尽量落在一个chunk内。embedding模型问题表现为："语义相近但关键词完全不同的句子，向量相似度却不高"，解决办法通常是换更强或更符合领域特征的embedding模型。查询改写问题则表现为："原问题本身表述模糊，比如只写'网络连接失败'"，解决办法是增加一个query改写环节，把用户原问题拆成多个更具体的子查询分别检索，再汇总结果。

一个非常实用的排查技巧是把检索的中间结果打印成可视化的调试报告，包括原始问题、改写后问题、每路召回的前5个chunk、每个chunk的文本和得分、最后融合的排序结果。这样一眼就能看到问题出在哪一层。我见过太多人在系统表现不好的时候直接调prompt或者换模型，其实那样既不精准又浪费时间，先把检索结果可视化看一遍，很多问题是不言自明的。

4.2 幻觉与上下文管理：别让模型自由发挥

模型答得一板一眼但内容完全是编的，这类问题在知识库问答场景非常致命。幻觉的根源在生成环节，但化解手段分布在整个链路。我总结了一组亲测有效的组合拳：系统prompt限定回答范围只基于提供上下文；请求参数温度调到0.1以下；对模型输出做引用校验，要求输出必须带有来源标记；对"不确定"场景做兜底话术，让模型明确说"根据提供资料暂未找到相关信息"。

引用校验是治理幻觉非常有效的一招。具体做法是在prompt里要求模型回答时，在每个核心结论后用上标标注来源chunk编号，程序在拿到模型输出后解析这些编号，检查它引用的chunk确实在本次检索top_k结果里。如果模型引用了不存在的chunk，说明它编了依据，系统就直接拦截替换成安全回答。这套机制听起来简单，但对幻觉问题的压制效果非常明显，属于投入产出比非常高的工程手段。

上下文管理还有一个容易被忽视的方向：多轮对话中的上下文继承。很多RAG系统只在单轮问题里表现好，一旦用户连续追问"那怎么配置呢""能举个例子吗"，系统就不知道"那"指代什么。我建议在每轮对话里把上一轮检索到的chunk摘要和上一轮回答的摘要，作为本轮prompt的前置上下文，而不是把全部历史对话一股脑塞进去。这样既保留了"指向当前话题"的关键信息，又不会因为历史过长挤占检索结果的token空间。

4.3 性能瓶颈与成本优化：上线后才是真正的战场

项目上线后，真正考验人的是性能和成本问题。我经历过的典型场景是：内部几百人同时用，单轮问答的完整链路要花8到15秒，用户反馈太慢；同时每天token消耗量远超预期，一个月下来成本报表让人头皮发麻。

性能瓶颈的排查顺序通常是：先看哪一段耗时长。用链路埋点数据，把检索耗时、模型首字耗时、完整响应生成耗时分开看。检索耗时高多半是向量检索规模大但没做聚类或索引优化，或者是混合检索的两路返回都太慢；模型首字耗时高多半是模型输入序列太长，需要压缩上下文或换更快的参数；完整生成耗时高则要结合用户场景判断，如果只是要一个简短答案，强制模型输出太长的内容本身就是浪费。

成本优化的手段里，缓存的效果立竿见影。对高频重复的问题做embedding级缓存和回答级缓存，能省掉大量重复计算和重复token调用。我的实测经验是，加上缓存后，30%到50%的重复咨询流量直接被吞掉了，成本和延迟同时下降。其次是用模型分级策略：简单的检索摘要、关键词提取任务用便宜的小模型，复杂推理、长答案生成才用大模型，不要一把梭全走最强模型。再往下就是token压缩，检索回来的top_k文档对最终答案的贡献分布往往不均匀，能用摘要或者重排序把最核心的3000字符挑出来，就别把1万字符全塞给大模型。

还要特别注意一点，在评估集基础上做性能调优和成本优化，每次改动后都要重新跑评测集，防止优化手段损害了回答质量。省钱省到质量崩盘是最不划算的买卖。

5. 动手实践中的几个关键习惯与个人反思

做这个from-scratch项目的过程，本身就是一个不断推翻重建的过程。我最大的收获不是学会了某个具体框架，而是形成了一套对待AI工程问题的习惯。第一个习惯是永远带着指标做改动，任何改动都记录在案：改了什么、预期改善什么、实测结果如何、是否回滚。没有这套记录，你会在各种参数组合里迷失方向。

第二个习惯是最小可行再加迭代。不要一开始就追求全功能系统，先做一条最简链路跑通，再逐步加上混合检索、重排序、query改写、引用校验这些增强模块。每加一个模块都做A/B对比，确认有效再保留，无效就撤掉。这样既能控制复杂度，也能让系统始终处于"知道为什么会这样"的状态。

第三个习惯是珍惜自己的评测集。我见过很多人做AI项目，花了大量时间调模型和prompt，却连一份像样的评测集都没有。等你需要做决策时，比如换模型还是调参数、扩大chunk还是缩小chunk，没有评测集就全靠赌。花两三个小时搭评测集，是AI工程里回报率最高的时间投资。

最后分享一个我在迭代过程中的小经验：项目上线一段时间后，要把用户真实提问累积起来，定期补充进评测集。你会发现真实提问的分布和你在开发阶段设计的问题分布差异非常大，新增的场景往往暴露原系统最脆弱的环节。持续用真实数据喂养评测集，这个系统的能力边界才会越扩越实，而不是停留在demo阶段的自娱自乐。ai-engineering-from-scratch这个名字的真正分量，其实就藏在这条没有捷径、每一步都要亲手踩过的路上。