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 的位置了原始数据CSV 文件、JSON 配置、PDF 文档、数据库导出等Loader 加载把原始数据转成 Document 对象数组切分Splitter把长文档切成适合模型上下文的小块向量化Embedding把每个小块转成向量存储Vector Store向量存进数据库检索Retriever用户提问时召回相关小块生成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 里如果某个字段本身包含逗号标准做法是用引号包起来比如北京, 朝阳区。但如果引号处理不当这个逗号会被误认为字段分隔符导致列错位。更麻烦的是字段里本身有引号的情况需要转义。这类问题在地址、描述类字段里特别常见。坑点典型表现处理方式编码中文变乱码统一转 UTF-8或显式指定编码分隔符整行挤成一列加载前确认实际分隔符引号列错位、字段被截断用标准 CSV 库解析别手写 split3.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 文件当成一个 DocumentpageContent是格式化后的 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、时间戳、类型标记、状态、来源路径。比如一个订单 JSONpageContent里放商品名、描述、价格这些内容性字段而订单 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、网页、数据库。但处理思路是相通的先搞清楚数据的语义结构再决定用什么粒度加载最后用元数据补上结构化信息。这套思路吃透了换什么格式都不慌。