大家好,我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。
最近在做一个图纸文档审查 Agent 时,遇到一个很具体的问题:复杂图纸经过 Python 脚本切割、取数和校审之后,结果默认保存成 JSON。程序处理很方便,但文件一交给大模型,上下文很快就变大,Agent 需要反复召回和解释。
这个校审结果文件本身并不复杂,就是一个 JSON 数组,里面有 50 条记录、14 个字段。每条记录对应一张图纸的判断结果,包含图名、图号、页码、判断结论、判断规则、闭合方式、闭合说明、布尔判断、边界最小距离和净距等信息。
结构本身没有问题,问题出在重复。每条记录都要重新出现一遍中文字段名,判断规则、闭合方式 和 判断说明 这些内容也会反复出现。程序不会在意这些重复,但模型每读一遍,都要消耗上下文。
后面我没有一上来重写规则,而是顺着这份数据的使用方式,慢慢走了三步:
JSON -> CSV -> Markdown(字典说明 + CSV 数据)
第一步是 JSON。它适合 Python 脚本输出,也方便程序保留完整字段和继续处理。但当几十个对象都重复相同字段名和长文本时,它就不适合直接作为模型上下文。
第二步是标准 CSV。把 14 个字段只在表头声明一次,每个 JSON 对象变成一行,原来的结构没有丢失,重复字段名却被去掉了。对于这种字段固定、每条记录结构一致的校审结果,CSV 已经能明显减少上下文,而且人可以直接打开比较,程序也容易解析。
但继续看下去,我发现 CSV 里还有一层重复:合格/不合格、几种固定的闭合方式,以及两类反复出现的判断说明。于是有了第三步,把重复枚举抽成字典:布尔值用 1/0,结论用 P/F,闭合方式用 MBB、IR、BBB、BBF、DG,判断说明用 J1/J2。主表只保存编码,完整含义在文件开头声明一次。
最后的内容已经不再是纯 CSV,而是“格式说明 + 字典 + CSV 数据”:
1 | FORMAT:v1 |
这时再把文件保存成 .csv 就有点勉强了,因为除了表格,它还包含格式协议和字段字典;保存成 .md 更自然。人打开能直接读,模型能先理解字典再读取数据,代码也可以从代码块里提取真正的数据区。
所以这次优化并不是简单地说 JSON 不好,而是在区分两件事:程序内部如何可靠存储,模型上下文如何高效表达。JSON 继续承担完整结果和程序交换,CSV 负责批量记录,Markdown 负责把格式说明、字典和数据组织成模型容易理解的输入。
这个过程让我重新思考一个看起来很小的问题:
到底应该用什么格式,把数据交给大模型和 Agent?
我的当前判断是:给程序严格校验的数据用 JSON,给模型批量比较的数据用 CSV,给人和模型共同理解的内容用 Markdown;HTML 只在确实需要保留页面结构时使用。
问题不是格式偏好,而是上下文成本
JSON、CSV、Markdown 和 HTML 都有成熟的使用场景。真正的问题不是哪种格式更高级,而是这份数据主要给谁使用。
如果数据主要给程序消费,需要字段校验、类型约束和自动执行,JSON 很合适。
如果数据主要给模型阅读、比较、归纳和生成,就要考虑上下文成本。大量重复字段、嵌套层级和转义符虽然对程序有意义,却不一定能帮助模型理解业务内容。
Agent 项目里很贵的一项资源就是上下文窗口。格式噪音多一点,真正能放进去的图纸信息、业务规则和判断依据就少一点。一次调用可能感觉不明显,但在检索、工具调用和多轮执行中,这些成本会不断累积。
所以在选择格式前,我现在会先问一句:
这份数据是给程序执行,给模型分析,还是给人复核?
JSON 适合什么:接口、校验和程序中间态
JSON 的优势很明确:结构清晰、生态成熟、容易解析,也方便做字段和类型校验。
在这类流程里,Python 脚本刚生成完整校审结果时,用 JSON 保存是合理的。程序可以明确读取每个字段,后续做过滤、转换、校验或写入数据库也比较稳定。
我会在这些场景继续使用 JSON:
- 工具调用参数和接口返回值;
- 需要严格字段校验的数据;
- Agent 的任务状态和程序中间态;
- 后续需要自动执行的结构化结果。
JSON 的问题不在于不能给模型读,而在于不应该成为所有模型输入的默认外壳。这个结果文件只有 50 条记录,但图名、图号、判断结论、判断规则、闭合方式、判断说明等字段名仍然会重复 50 次,长文本内容也会一起重复。
所以我的边界是:JSON 面向程序、校验和自动执行,不负责承载所有需要模型大量阅读的内容。
CSV 适合什么:清单、表格和批量记录
这类图纸校审数据从 JSON 转成 CSV 后,最直观的变化是表头只需要出现一次。
一行代表一条图纸校审结果,一列代表一个字段。Agent 要比较哪些图纸合格、采用了哪种闭合方式、边界最小距离和净距是多少时,可以沿着表格直接阅读,不需要在重复字段和对象结构里来回查找。
在 Agent 项目里,我会优先用 CSV 表达这些内容:
- 图元、设备、物料、订单和工单等批量记录;
- 测试用例、任务清单和文件索引;
- 需要排序、筛选、分类和统计的数据;
- 字段固定、结构接近二维表的数据。
CSV 的价值是用较少的格式成本保留足够清楚的结构。但它也有边界:复杂层级、长文本和字段解释都不适合硬塞进 CSV。
判断方法很简单:数据像表,就优先用 CSV。
Markdown 适合什么:字段字典、知识页和任务说明
CSV 解决了批量数据的问题,但它没有回答另一个问题:字段是什么意思,为什么要这样判断?
所以第三步,我增加了 Markdown 字典格式,用来解释编码和数据。例如:
P/F分别表示合格和不合格;MBB、IR、BBB、BBF、DG表示不同闭合方式;J1/J2指向两类完整的判断说明;1/0统一表示布尔值;FORMAT、DICT、DATA分别声明版本、字典和数据区。
这些内容如果继续放进每一条 JSON 或 CSV 记录里,会造成重复;单独整理成 Markdown 后,Agent 可以先理解字段字典和审核规则,再读取 CSV 中的批量数据,人也可以直接复核和修改。
Markdown 适合这些场景:
- 字段字典、业务规则和审核说明;
- 技术文章、方案、会议纪要和知识页;
- Agent 的任务说明、执行计划和分析报告;
- 需要人和模型一起维护的中间成果。
它既保留标题、列表、代码块和表格等轻量结构,又不会像 HTML 那样带入大量页面标签。
知识库正在从简单的“上传文件后问答”,变成文档、任务和 Agent 共同协作的工作台。在这种场景里,Markdown 的价值不只是模型容易读,更重要的是它能让 Agent 的中间结果变成人可以继续接手的工作产品。
判断方法同样简单:数据像文章、说明或知识,就优先用 Markdown。
HTML 适合什么:网页采集、页面还原和 UI 分析
HTML 不是不能用,但它主要描述的是页面结构。
导航栏、按钮、样式类名、脚本、推荐列表和隐藏内容,对浏览器渲染有用,对模型总结正文却可能只是噪音。如果把完整 HTML 直接放进知识库,切分和召回时也容易把正文与页面外壳混在一起。
我会在这些场景保留 HTML:
- 网页采集和浏览器自动化;
- 页面结构分析和 UI 还原;
- 确实需要保留 DOM 层级和渲染语义的任务。
如果任务只是总结文章、提取观点、生成知识页或建立 RAG 索引,我更愿意先抽取正文,再转换成干净的 Markdown。
放进 Agent 和 RAG 工作流里怎么选
格式选择会影响 Agent 每一步看到什么。
工具调用后,如果下一步由程序继续处理,可以返回 JSON;如果下一步由模型比较一批记录,可以返回 CSV;如果结果需要模型理解并让人复核,可以返回 Markdown。
在 RAG 场景里也一样:
- 文章、报告、方案、会议纪要:Markdown;
- 清单、指标、图元和业务记录:CSV;
- 接口对象、工具参数和程序状态:JSON;
- 网页原始材料:HTML,但进入检索前尽量清洗。
这不是为了追求格式统一,而是为了让每一步都拿到最适合自己的数据。格式选对了,模型少做一次猜测,人工少做一次解释,下游也少补一层解析逻辑。
我的实际取舍:让数据像它本来的样子
回到这次图纸校审数据的优化,最后形成的是一个很朴素的流程:
第一步,用 JSON 承接程序刚提取出来的完整结果,保证字段明确、结果可校验。
第二步,把需要 Agent 批量比较和分析的记录整理成 CSV,减少重复字段和上下文占用。
第三步,用 Markdown 字典补充字段含义、业务规则和审核要求,让模型和人都能看懂。
这不是说后一种格式全面替代前一种格式,而是随着使用对象变化,让数据进入更合适的形态:程序处理 JSON,模型分析 CSV,人和模型共同理解 Markdown。
如果你的 Agent 项目也准备调整数据格式,可以先做三个小检查:
- 找出真正进入模型上下文的数据,而不是只看数据库里存了什么。
- 判断它本质上是文章、表格、接口对象,还是网页。
- 观察调整后上下文是否更省、模型是否更稳定、人工是否更容易复核。
结尾:格式越合适,Agent 越容易稳定做事
Agent 项目里,数据格式看起来是小事,但它会影响上下文成本、模型理解、工具调用、RAG 质量和后续维护。
我的当前建议是:
- 长文本、知识页和任务说明,优先用 Markdown。
- 清单、表格和批量记录,优先用 CSV。
- 工具调用、接口参数和程序状态,继续用 JSON。
- HTML 保留在需要页面结构的场景,进入模型前尽量清洗。
- 每次选择格式时,都先问清楚它是给程序执行、给模型分析,还是给人复核。
Agent 工程化不只是模型和框架,也包括这些朴素的输入输出判断。数据交得越清楚,模型越容易稳定做事,人也越容易复核和迭代。
我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。