企业官网建设流程全解析

1. 从写页面到喂数据：前端转 Agent 开发最容易踩空的一步

做前端的朋友转 Agent 开发，通常会有一种错觉：不就是调几个 API、拼几段 Prompt、把大模型的返回渲染到界面上吗？我一开始也是这么想的。真正上手做第一个 Agent 项目之后才发现，卡住我的根本不是 Prompt 写得好不好，也不是模型选哪个，而是数据怎么进到 Agent 的上下文里。这个环节在 Agent 开发里有个专门的名字，叫 Document Loader，也就是文档加载器。

前端日常打交道的数据是什么？是接口返回的 JSON、是组件里的 state、是 localStorage 里的一坨字符串。这些东西结构清晰、字段明确，你闭着眼睛都能 map 出来。但 Agent 面对的数据完全不是这个画风：一份 PDF 合同、一个几百行的 CSV 报表、一堆散落的 Markdown 笔记、一个嵌套了七八层的 JSON 配置文件。这些数据要先被"读进来"，再被"切碎"，最后才能"喂给"模型。而 Document Loader 就是这条流水线的第一道工序。

这一节我想聊的就是这道工序。关键词里出现了 Document Loader、Loader、CSVLoader、JSONLoader，热搜词里还有 agent 开发、agent 框架、agent 学习路线这些。我假设你已经知道 Agent 大概是什么，也写过一两个能跑通的 demo，现在卡在了"我的数据怎么进去"这一步。这篇文章会从 Loader 到底解决什么问题讲起，把 CSV 和 JSON 这两种前端最熟悉、也最容易想当然的格式拆开讲透，最后给你几条我踩过坑之后总结出来的实操经验。看完你应该能自己判断：手上这份数据，该用哪种 Loader，该怎么配参数，以及哪些坑是提前就能避开的。

先说一个反直觉的结论：在 Agent 项目里，Loader 写得好不好，直接决定了你的 Agent 是"聪明"还是"智障"。因为模型再强，它也只能看到你喂给它的那部分内容。Loader 决定了喂什么、喂多少、按什么粒度喂。这一步做砸了，后面 Prompt 写得再花哨都是白搭。

2. Document Loader 到底在 Agent 流水线里干了什么

2.1 它不是"读文件"，而是"把异构数据翻译成统一格式"

很多人第一次看到 Loader 这个词，会下意识理解成"文件读取工具"。这个理解不算错，但太窄了。如果只是读文件，前端用fetch加FileReader也能读，为什么 Agent 框架还要专门搞一套 Loader 体系？

核心原因在于：Agent 后续的所有处理环节，都要求数据是统一的 Document 结构。不管你的原始数据是 CSV、JSON、PDF 还是网页，经过 Loader 之后，都要变成同一种东西——通常是一个包含pageContent（文本内容）和metadata（元数据）的对象。这个统一结构是整个流水线的"通用货币"。

为什么非要统一？因为下游的环节太多了：文本切分器（Text Splitter）要按统一格式切、向量化模型（Embedding）要按统一格式编码、向量数据库要按统一格式存储、检索器（Retriever）要按统一格式召回。如果每个环节都要针对不同原始格式写一套适配逻辑，这个项目根本没法维护。Loader 的价值就在于把"格式适配"这件事收敛到一个环节，让下游全部面向统一结构编程。

这跟前端里的"数据归一化"是一个思路。你在 Redux 里不会让每个组件自己去解析接口返回的原始 JSON，而是先在 action 或 selector 里把它 normalize 成统一的 state 结构。Loader 就是 Agent 世界里的 normalize 层。

2.2 一条完整的 Loader 流水线长什么样

我把一个典型 Agent 项目的数据流拆给你看，你就明白 Loader 的位置了：

1. 原始数据：CSV 文件、JSON 配置、PDF 文档、数据库导出等
2. Loader 加载：把原始数据转成 Document 对象数组
3. 切分（Splitter）：把长文档切成适合模型上下文的小块
4. 向量化（Embedding）：把每个小块转成向量
5. 存储（Vector Store）：向量存进数据库
6. 检索（Retriever）：用户提问时召回相关小块
7. 生成（LLM）：把召回内容拼进 Prompt，让模型回答

Loader 是第 2 步。它看起来最简单，但它是唯一一个直接接触原始脏数据的环节。后面的步骤都假设数据已经是干净的 Document 了。所以脏活累活全在 Loader 这里。

我见过太多项目，前面 Loader 随便写写，把整个 CSV 当成一个大字符串塞进去，结果切分的时候按字符数硬切，把一行记录从中间劈开，模型拿到半截数据，回答得驴唇不对马嘴。问题不在模型，在 Loader 没有把"一行就是一条完整记录"这个语义信息传递下去。

2.3 前端视角下，Loader 和"解析接口数据"的本质区别

前端解析接口数据，目标是渲染。你关心的是字段能不能对上、类型对不对、要不要做空值兜底。数据是给人看的。

Loader 处理数据，目标是给模型理解。你关心的是：这段文本的语义边界在哪里、元数据能不能帮模型定位、切分之后每一块是否自洽。数据是给模型"读"的。

这个区别带来一个很实际的后果：前端习惯的"扁平化"处理，在 Loader 里往往是错的。前端喜欢把嵌套 JSON 拍平成一个对象，方便取值。但 Loader 处理嵌套 JSON 时，如果无脑拍平，会丢掉层级之间的语义关系。比如一个{"订单": {"商品": {"名称": "..."}}}，拍平之后"订单-商品-名称"这个路径信息如果丢了，模型就不知道这个"名称"到底是订单的名称还是商品的名称。

所以做 Loader 的时候，脑子里要装的不是"怎么方便取值"，而是"怎么保留语义"。

3. CSVLoader：看起来最简单，坑却最多的一种

3.1 CSV 的"一行一记录"语义，是 Loader 必须守住的东西

CSV 是前端最熟悉的格式之一，导出报表、批量导入用户，都用它。但正因为熟悉，大家反而容易轻视它。在 Agent 场景里，CSV 有一个非常关键的语义特征：一行就是一条完整的、自洽的记录。

这个特征决定了 CSVLoader 的正确用法。理想情况下，每一行应该被加载成一个独立的 Document，这一行的所有列拼成pageContent，行号、来源文件等信息放进metadata。这样切分的时候，即使后续还要再切，也是在一行内部切，不会把两条记录混在一起。

我见过有人把整个 CSV 读成一个大字符串，然后交给通用文本切分器。结果就是：切分器按固定字符数切，正好切在两条记录中间，第一条记录的后半截和第二条记录的前半截被拼成一块。模型看到这块内容，完全无法理解，因为它既不是完整的 A 记录，也不是完整的 B 记录。

提示：CSVLoader 的核心配置项通常包括"用哪一列作为内容"（比如column或content_columns）和"哪些列进元数据"。默认行为往往是把所有列拼起来，但如果你只关心其中几列，明确指定会更干净。

3.2 列的选择：不是所有列都该喂给模型

一个真实的 CSV 往往有十几列，但真正对 Agent 有用的可能只有三四列。比如一份用户反馈表，可能有 ID、提交时间、用户设备、操作系统版本、反馈内容、处理状态、处理人……对"回答用户关于反馈内容的问题"这个 Agent 来说，真正有用的是"反馈内容"，可能再加个"提交时间"做时间过滤。

如果你把所有列都塞进pageContent，会发生什么？模型每次都要读一堆无意义的 ID 和状态字段，浪费上下文窗口不说，还会干扰它的判断。更糟的是，某些列的值可能看起来像内容（比如"处理人"叫"张三"，而反馈内容里也提到"张三"），模型会混淆。

我的做法是：明确指定内容列，其余列按需放进 metadata。metadata 不占主要上下文，但在检索和过滤时非常有用。比如你可以用 metadata 里的"提交时间"做时间范围过滤，用"处理状态"过滤掉已关闭的反馈。这样既省上下文，又保留了结构化查询能力。

3.3 编码、分隔符、引号：三个让 CSVLoader 翻车的细节

CSV 格式看起来标准，实际上是个"方言"重灾区。我踩过的坑里，这三个最常见：

编码问题。中文 CSV 从 Excel 导出，经常是 GBK 或 GB18030 编码，而 Loader 默认按 UTF-8 读，结果全是乱码。乱码数据喂给模型，模型只能瞎猜。解决办法是显式指定编码，或者在加载前用工具转成 UTF-8。我一般建议在数据准备阶段就统一转成 UTF-8，别指望 Loader 帮你猜。

分隔符问题。标准 CSV 用逗号，但很多系统导出用分号、制表符，甚至竖线。如果 Loader 按逗号切，而实际是分号，那整行会被当成一列，所有字段挤在一起。加载前先看一眼文件头几行，确认分隔符。

引号问题。CSV 里如果某个字段本身包含逗号，标准做法是用引号包起来，比如"北京, 朝阳区"。但如果引号处理不当，这个逗号会被误认为字段分隔符，导致列错位。更麻烦的是字段里本身有引号的情况，需要转义。这类问题在地址、描述类字段里特别常见。

3.4 大 CSV 的内存问题：别一次性全读进来

前端处理大文件有个天然优势：可以流式读、可以分页。但很多 Loader 的默认行为是一次性把整个文件读进内存。一个几十万行的 CSV，读进来就是几百 MB，再加上转成 Document 对象、切分、向量化，内存直接爆掉。

我的经验是：如果 CSV 超过几万行，就要考虑分批加载。具体做法是先按行数或文件大小切分原始文件，分批加载、分批向量化、分批入库。这样内存占用可控，而且中途失败可以断点续传，不用从头再来。

另一个思路是：先想清楚这个 Agent 到底需不需要全量数据。很多时候，你只需要最近三个月的数据，或者某个状态的数据。在加载前就用命令行工具（比如awk、csvkit）过滤一遍，能省掉大量无用功。我见过有人把三年的历史数据全加载进去，结果 Agent 回答问题时召回的全是过期信息。

4. JSONLoader：嵌套结构才是真正的考验

4.1 为什么 JSON 比 CSV 难处理

CSV 是二维的：行和列。JSON 是任意维度的：对象套对象、数组套对象、对象里又有数组。这种灵活性对前端是好事，对 Loader 却是噩梦。

核心矛盾在于：模型需要的是线性文本，而 JSON 是树形结构。Loader 要做的，就是把树"压平"成文本，同时尽量不丢失结构信息。这个"尽量"就是难点所在。

举个前端很熟悉的例子。一个接口返回：

{ "user": { "name": "李雷", "orders": [ {"id": 1, "item": "键盘", "price": 299}, {"id": 2, "item": "鼠标", "price": 99} ] } }

如果无脑JSON.stringify成一行，模型看到的是{"user":{"name":"李雷","orders":[{"id":1,...，它得自己在脑子里解析这个结构。模型不是不能做，但很费劲，而且容易出错。更好的做法是把它转成带层级标记的文本，比如：

user.name: 李雷 user.orders[0].id: 1 user.orders[0].item: 键盘 user.orders[0].price: 299 user.orders[1].id: 2 ...

这样每一行都是自解释的，模型一眼就能看懂"这是李雷的第一个订单的商品名"。

4.2 JSONLoader 的两种典型策略：整块加载 vs 按路径拆分

JSONLoader 通常支持两种模式，选哪种取决于你的数据形态和查询需求。

整块加载：把整个 JSON 文件当成一个 Document，pageContent是格式化后的 JSON 文本。适合小文件、配置类数据，或者你希望模型看到全局结构的情况。缺点是文件一大就超上下文，而且切分的时候容易破坏结构。

按路径拆分：用 JSONPath 或类似语法指定"在哪个节点上拆成独立 Document"。比如指定$.user.orders[*]，就会把每个订单拆成一个 Document。适合数组型数据，每个元素是独立实体的情况。

我一般的原则是：如果 JSON 里有一个明显的"记录数组"，就按数组元素拆。比如日志文件、订单列表、消息记录，这些都是天然的"一条一条"。如果 JSON 是一个整体配置或一个复杂对象，没有明显的记录边界，就整块加载，但要做好切分策略。

4.3 用 JSONPath 精准控制"拆在哪一层"

JSONPath 是 JSONLoader 里最值得花时间学的部分。它决定了你的数据被拆成什么粒度。几个常用的写法：

• $表示根节点，整块加载
• $.items[*]表示 items 数组的每个元素各成一个 Document
• $.data.records[*]表示深层嵌套里的 records 数组
• $..name表示递归查找所有 name 字段（这个要慎用，容易拆得太碎）

选拆分层级的时候，问自己一个问题：用户会针对什么粒度提问？如果用户会问"第 3 个订单的商品是什么"，那订单就是拆分粒度。如果用户会问"这个用户的整体消费情况"，那可能整个 user 对象作为一个 Document 更合适。

拆得太细，会丢失上下文。比如你把每个订单的每个字段都拆成一个 Document，那模型看到"价格 299"的时候，根本不知道这是哪个订单的。拆得太粗，检索精度又不够。这个平衡点需要根据实际查询场景反复调。

4.4 元数据：JSON 里那些"不该进正文但很有用"的字段

JSON 里往往有一些字段，不适合放进pageContent（会干扰模型），但放进metadata却非常有用。典型的有：ID、时间戳、类型标记、状态、来源路径。

比如一个订单 JSON，pageContent里放商品名、描述、价格这些"内容性"字段，而订单 ID、下单时间、订单状态放进metadata。这样检索的时候，你可以先用 metadata 过滤（比如只看"已完成"的订单），再在过滤结果里做语义检索。这种"结构化过滤 + 语义检索"的组合，效果比纯语义检索好得多。

注意：metadata 里的值最好是简单类型（字符串、数字、布尔），别塞复杂对象。很多向量数据库对 metadata 的类型有限制，塞复杂对象会导致入库失败。

5. 从"能加载"到"加载得好"：几个决定成败的实操细节

5.1 切分粒度要和 Loader 的拆分粒度对齐

这是我最想强调的一点。Loader 和 Splitter 是两个环节，但它们必须协同工作。如果 Loader 已经把数据拆成了"一行一记录"，那 Splitter 就应该尽量保持这个边界，不要跨记录切。如果 Loader 加载的是一个大文档，那 Splitter 才需要按语义或字符数去切。

我见过最常见的错误是：Loader 把整个 CSV 加载成一个 Document，然后 Splitter 按 1000 字符硬切。结果就是前面说的，记录被劈开。正确的做法是让 Loader 就按行拆，Splitter 对每一行做"如果太长再切"的二次处理。

判断标准很简单：切分后的每一块，单独拿出来读，是不是一个完整的意思？如果读起来像半句话，那就是切错了。

5.2 别忽略"加载失败"的处理

生产环境里，Loader 一定会遇到加载失败的情况：文件损坏、编码错误、格式不符合预期、权限问题。如果 Loader 遇到一个坏文件就整个流程崩掉，那这个 Agent 根本没法上线。

我的做法是：每个文件的加载都包一层错误处理，失败的记录到日志里，跳过继续。最后统计一下成功多少、失败多少。失败的单独排查，不影响整体流程。这跟前端批量请求时用Promise.allSettled而不是Promise.all是一个道理——不能因为一个失败就全军覆没。

5.3 加载完先"验货"，别急着往下走

数据加载完，别急着切分和向量化。先抽样看几条 Document，确认：pageContent是不是你想要的文本、metadata字段对不对、有没有乱码、有没有空内容、拆分粒度合不合理。

这一步花五分钟，能省掉后面几小时的排查。因为一旦向量化入库，再发现问题，就得清库重来。我一般会写个小脚本，加载完打印前 3 条和后 3 条 Document，肉眼过一遍。这个习惯帮我拦下过无数次"编码错了""拆错层了""字段名对不上"的问题。

5.4 增量更新：别每次都全量重来

数据是会变的。今天加载的 CSV，明天可能新增了几百行。如果每次都全量重新加载、重新向量化，成本高得离谱。

合理的做法是给每条 Document 一个稳定的唯一标识（比如用文件路径加行号，或者用记录里的业务 ID），入库时做 upsert。新增的插入，修改的更新，删除的标记失效。这样每次只需要处理变化的部分。这个机制在项目初期可能觉得没必要，但数据量一上来，就是救命的设计。

6. 转岗路上关于 Loader 的几点个人体会

我从写页面转到做 Agent，最大的认知转变就是：前端的"数据"是给人看的，Agent 的"数据"是给模型读的。这两个目标看起来接近，实际上对数据的要求完全不同。给人看的数据可以容错、可以兜底、可以靠 UI 弥补；给模型读的数据，脏一点、乱一点、结构丢一点，模型就直接给你脸色看。

Document Loader 这个环节，技术含量看起来不高，但它是最考验"数据 sense"的地方。你得理解你的数据长什么样、语义边界在哪里、用户会怎么问、模型需要看到什么。这些东西没有标准答案，只能靠一个个项目磨出来。

如果你正在做第一个 Agent 项目，我的建议是：在 Loader 上多花点时间，别急着往下跑。把数据加载对了、拆对了、元数据配对了，后面的切分、检索、生成都会顺很多。反过来，Loader 糊弄过去，后面每个环节都在给前面的错误擦屁股，越擦越乱。

CSV 和 JSON 只是开始。真实项目里你还会遇到 PDF、Word、网页、数据库。但处理思路是相通的：先搞清楚数据的语义结构，再决定用什么粒度加载，最后用元数据补上结构化信息。这套思路吃透了，换什么格式都不慌。