做 RAG 与 Agent 项目的人平时聊得最多的是向量、路由、工具调用、记忆、上下文工程但真到动手写代码那一步所有人都会撞上同一个东西JSON。第二周第6讲放在这里表面上看是“基础使用”但它实际上决定了后面所有实战环节能不能顺利跑通——无论是 RAG 的文档切块与元数据管理还是 Agent 的工具参数与状态记录底层都是 JSON 在充当数据交换的协议。这篇内容我会用做项目的口吻带你过一遍 JSON语法、Python 实操、JSON Schema、JSONPath最后落到两个具体场景用 JSON 做知识库元数据以及用 JSON 支撑 Agent 的工具调用闭环。适合刚入门的同学也适合写了挺久代码但从来没系统性梳理过 JSON 处理的人。建议自己开一个 Jupyter 跟着敲基础这道关过了后面几周才会顺。1. 为什么 RAG 与 Agent 开发绕不开 JSON1.1 第二周做“基础篇”的用意很多同学看到“基础使用”四个字脑子里第一反应是跳过JSON 不就是键值对吗看两眼就会了。但等真正开始做 Agent 工具调用十个里有八个会在同一个地方卡住模型返回了一个字符串里面嵌套着转义字符外层结构是多层的数组套对象不解析完根本拿不到工具的入参。你说它是“基础”也好说它是“地基”也好反正绕不开。把 JSON 放在第二周第6讲有两个原因。第一RAG 和 Agent 的应用场景天然是“结构化交互”模型无论多聪明最终在工程层面对接的都是固定格式的数据而 JSON 就是那个被普遍接受的固定格式标准第二这一周讲基础后面讲知识库构建、Agent 编排、并发难点的时候我都默认你会熟练处理 JSON所以现在花一次课的时间补上后面不需要回头再讲一遍。所以我建议这一节不要跳过。有过基础的可以快速过哪怕只是扫一眼后面的代码惯例完全没接触过的请务必动手敲完所有代码块尤其是第 3、7 节那是生产环境最高频的使用方式。1.2 RAG 管线里的三处 JSON先说 RAG。一个典型的 RAG 流程从数据进来到答案返回有三处必须和 JSON 打交道。第一处是知识库的原始格式。你收集到的资料可能是 PDF、Markdown、网页抓取但很多工程化的知识库在落地的时候会统一转成 JSON 或 JSONL方便做版本管理、字段扩展和增量更新。像{id:doc_001,title:...,content:...,tags:[...],published_at:...}这样的结构几乎是知识库项目的标配。你会发现只要后面要接 Elasticsearch、MongoDB 这类存储导出和导入天然就是 JSON 视角。第二处是切块后的元数据。文档拆分成 chunk 之后每个 chunk 都会携带一个 JSON 元数据对象来源页码、章节标题、更新时间、权限位、标签等。这堆元数据会跟着向量一起存进向量库检索时作为过滤条件使用。元数据设计得不好检索命中率很多人叫 rag hit rate会很难看。比如同样一个标签字段有人用tags: [入门, 教程]有人塞成tags: 入门,教程后者在过滤时大概率会踩坑。第三处是检索结果回传给模型的那一刻。向量库返回的 top-k 结果最终要拼成一段上下文交给 LLM。如果手动拼“片段1xxx 片段2xxx”模型也能读但当你需要同时返回来源、页码、置信度分数时没有结构化的 JSON上下文会变得混乱且不可控。用 JSON 结构化回传模型的稳定性和可解释性都会好很多。1.3 Agent 里的三处 JSON再看 AgentJSON 的使用密度比 RAG 更高。第一处是工具调用的参数协议。Agent 的核心机制是让模型输出“这次该调用哪个工具、参数是什么”的描述而不是直接让它执行代码。比如用户问“上海明天适合跑步吗”模型输出{name:get_weather,arguments:{\city\:\上海\,\date\:\2026-04-12\}}。你拿到这串 JSON解析出工具名和参数然后去调天气服务。参数如果解析失败整个 Agent 执行链路直接中断。网上总能看到 “agent execution terminated due to error.” 这类报错十次里有七次是这里出了问题。第二处是 Agent 的记忆与状态。多轮对话里对话历史、缓存结果、待执行的操作都需要序列化之后才能存下来。JSONL 是最常见的一种持久化格式每条记录一行 JSON方便追加也方便重放调试。很多轻量级 Agent demo 就是用一个.jsonl文件模拟整个记忆层。第三处是 Agent 与外部系统的对接。无论是 HTTP API、数据库还是消息队列传输层定义的数据格式绝大多数是 JSON。你写的 Agent 就像一个总调度员而它所调度的系统只认 JSON 包裹的数据。学会解析和生成 JSON其实就是在和整个后端生态对话。2. JSON 语法一个“看着简单”但又容易犯迷糊的知识点2.1 六种数据类型与嵌套结构JSON 支持的数据类型不多连日期、时间戳这些都没有原生类型仔细看就是六种对象、数组、字符串、数字、布尔值、null。理解这个“少”很重要——很多新手以为 JSON 里可以直接写undefined、写函数、写注释这些都是把 JavaScript 对象的规则混进来了。对象用大括号包裹是无序的键值对集合数组用中括号包裹是有序的值列表。它们可以无限嵌套整体结构是一棵树。你可以这样建立心智模型对象像字典键是字符串值可以是任意类型数组像列表元素可以是任意类型。只要记住“值可以是六种类型中的任意一种”嵌套关系就不会搞混。下面这个例子包含了全部数据类型你可以当成“语法模版”反复对照{ title: RAG入门, view_count: 12800, avg_score: 4.7, is_public: true, tags: [基础, 检索增强], author: { name: 老周, active: false, last_login: null } }这里的对象、数组、字符串、数字、布尔值、null 都出现了。实际项目里嵌套三层四层很正常不要慌从外到内一层层拆就行。2.2 手写 JSON 的常见错误引号、转义、尾逗号手写 JSON 最容易翻车的三个点我挨个说。第一字符串必须用双引号。JSON 规范里没有单引号字符串很多人在 Python 里写习惯单引号结果生成出来的{name: Alice}直接抛JSONDecodeError。反过来说Python 的字典如果要转成 JSON字符串键最后也会变成双引号这是正常现象。第二转义。JSON 字符串里的双引号必须用反斜杠转义比如他说\你好\。如果这个 JSON 字符串本身又要放进另一个 JSON 字符串里反斜杠还要再转一层就会出现\叠\\\的情况。很多 Agent 工具调用之所以解析失败就是模型把嵌套引号处理错了。第三尾逗号。JSON 不允许对象或数组最后一个元素的后面再跟逗号像{a:1,b:2,}是非法结构。Python 的 dict 写尾逗号没事但json.dumps不会产出尾逗号手写 JSON 字符串时千万别图省事。我建议你从现在开始养成习惯任何 JSON 只要是人工编写都要经过一次工具校验。VSCode 装个 JSON 插件或者直接用 Python 跑一行json.loads检查都比肉眼强。2.3 JSON 与 YAML/TOML 的选择很多同学会问现在配置文件不都推荐 YAML 和 TOML 吗为什么这里还要强调 JSON我的判断很简单。YAML 的优点是易读、支持注释适合人工维护配置文件TOML 适合依赖强类型键值对的场景。但在 Agent 和 RAG 的场景里你打交道最多的是“模型输出结构”和“接口返回协议”这两者 JSON 有天然优势它足够严格限制也少几乎所有语言都有原生或一等公民的解析库模型在预训练阶段见到的 JSON 语料也远多于 YAML。所以我的原则是给 LLM 的工具参数格式和上下文协议一律用 JSON自己项目里的人工配置可以用 YAML跨语言传输必须 JSON。不要为了炫技把模型输出定义成 YAML虽然有些模型也支持 YAML但出错的概率明显更高。3. Python 实战JSON 读写与转换保姆级3.1 json.loads 与 json.dumps参数才是重点Python 内置的json模块已经足够日常使用我先把两个核心函数的应用场景说清楚。json.loads(text)是把 JSON 字符串解析成 Python 对象JSON 对象变 dict数组变 list字符串变 str数字变 int/float布尔变 boolnull 变 None。json.dumps(obj)是反过来把 Python 对象序列化成 JSON 字符串。文件读写对应的是json.load(fp)和json.dump(obj, fp)。但是真正拉开差距的是dumps的参数。我直接给一套常用配置import json data { title: RAG实战, author: 老周, tags: [基于知识库, Agent] } output json.dumps( data, ensure_asciiFalse, # 不要把所有中文转成 \uXXXX indent2, # 格式化方便阅读 sort_keysFalse, # 保持插入顺序 defaultstr, # 超出常规类型的转字符串兜底 ) print(output)ensure_asciiFalse几乎是我每个项目的固定参数。否则你会得到\u57fa\u4e8e...调试起来想死。indent2适合给人看的输出如果是要给后端接口用的数据建议不要 indent体积更小。另有一个常见的坑用 f-string 手拼 JSON。比如f{{name:{user}}}一旦user里带了双引号或反斜杠就会直接破坏整个 JSON 结构。正确做法永远是先把数据放到字典里然后json.dumps生成。3.2 日期、中文、特殊字符处理JSON 没有日期类型所以日期在 JSON 里只是一个字符串。Python 的datetime.datetime、date默认是不能被dumps序列化的直接跑会报TypeError: Object of type datetime is not JSON serializable。最简单的处理方式有两个from datetime import datetime payload {name: 知识库, created_at: datetime.now()} # 方式一统一转字符串 payload[created_at] payload[created_at].isoformat() # 方式二dumps 时用 defaultstr json.dumps(payload, defaultstr)方式一更推荐因为isoformat()输出的是标准 ISO 8601 格式跨语言、跨系统都不会有歧义。方式二只适合临时调试遇到某些对象时转出来的字符串可能不是你想要的。这里还牵扯到一个高频报错尤其是 Java 服务端对接时常见的 “json parse error: cannot deserialize value of typejava.util.datefrom str”。问题不在 JSON 本身而在于两端的日期格式约定不一致。比如 Python 端传了2026-04-12Java 端用 Jackson 反序列化到java.util.Date时没有指定 pattern严格模式下就会失败。解决方法永远是事先约定统一格式比如一律用yyyy-MM-ddTHH:mm:ssZ并且统一存 UTC 时间而不是在出问题时临时猜。中文和特殊字符也有两个常见坑。一是读取 JSON 文件时文件编码必须是 UTF-8否则会出现乱码或读取失败建议永远写open(file, encodingutf-8)二是输出到控制台时因为终端编码问题中文可能显示不出来这不代表数据坏了换个环境或者写文件验证即可。3.3 从文件、HTTP、数据库读取 JSON 的常规做法实际项目里JSON 不会只出现在代码里的字符串变量中最常见的三个来源是文件、HTTP 响应和数据库。文件读取的固定写法import json with open(knowledge_base.json, encodingutf-8) as f: data json.load(f)HTTP 响应如果用的是requests直接.json()方法最方便但如果响应体不是 JSON 会抛异常所以稳妥一点可以在调用前判断Content-Type。如果你是写 Agent 的工具函数要注意外部 API 可能返回超大 JSON建议先把文本拿到手再决定是一次性解析还是流式处理。数据库这边差异比较大。MongoDB 本身就是文档型存储返回的基本就是类 JSON 对象直接用就可以PostgreSQL 的 JSONB 字段在 SQLAlchemy 里拿到的一般是 Python dict存入时用json.dumps读取时用json.loads。大数据场景下如果离线任务用 Spark 读取 JSON 文件直接用spark.read.json(path)即可内置支持嵌套结构推断。4. JSON Schema给 Agent 的工具加上“类型安全”4.1 工具调用中的 JSON Schema 示例Agent 开发中你通常会给模型声明工具支持哪些参数、参数是什么类型。这个声明的载体就是 JSON Schema。很多主流的 Agent 框架里函数定义都长这个样子{ name: get_weather, description: 查询指定城市某天的天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称如 上海 }, date: { type: string, format: date, description: 日期格式为 yyyy-MM-dd } }, required: [city] } }这一小段 JSON 不是给人看的是给模型看的。它告诉模型工具叫get_weather只需要字符串类型的城市和日期其中城市必填。模型看到这样的定义后才会在回答问题时输出匹配的工具调用参数。正因为模型是按照 schema 来生成的所以你后端的参数校验也需要基于 schema 来做而不是自己写一堆 if-else 去判断字段类型那样既麻烦又容易漏。4.2 用 jsonschema 校验返回结果光有 schema 不校验等于形同虚设。Python 有现成的jsonschema库用起来非常简单import json import jsonschema tool_schema { type: object, properties: { city: {type: string}, date: {type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$} }, required: [city] } # 模型返回的参数确保是 dict try: jsonschema.validate(args, tool_schema) print(参数合法) except jsonschema.ValidationError as e: print(参数不合法, e.message)为什么强调这一步因为模型输出偶尔会有幻觉明明字段定义是字符串它可能输出数字required 字段可能缺失日期格式可能写成了2026年4月12日。如果你不做 schema 校验这些脏参数会一路传到真实工具里然后工具内部再报错排查链路很长。先校验、再执行问题就能定位到“模型输出不合法”这一层。另外校验通过后最好再走一层业务约束校验比如日期不能晚于今天、城市必须在支持列表内。Schema 管格式业务逻辑管范围两层缺一不可。4.3 给 RAG 元数据也立一个 schema在 RAG 项目里JSON Schema 同样适用。我的习惯是给知识库的 chunk 元数据也建一个 schema哪怕只是简单的几个字段。比如{ type: object, properties: { id: {type: string}, source: {type: string}, page: {type: integer}, tags: {type: array, items: {type: string}}, updated_at: {type: string, format: date-time} }, required: [id, source, updated_at] }有了这个 schema每个 chunk 入库前都可以先过一遍校验。否则等检索阶段做过滤时突然发现某条 chunk 的page字段是字符串12另一条是整数12过滤条件就会漏数据。元数据脏是 RAG 命中率上不去的隐形杀手之一这是我自己踩过不少次坑之后才形成的习惯。5. JSONPath像查数据库一样查 JSON5.1 最常用的 JSONPath 写法如果你写代码时经常遇到这种需求一个很深的嵌套 JSON你想快速拿出某个字段或者筛选出符合条件的所有记录。用 Python 一层层 for 循环也能做但代码会很难看。JSONPath 就是解决这个问题的它相当于 SQL 之于数据库专门查 JSON。我列一份最常用的语法表表达式含义$根节点$.store.book根节点下的 store 下的 book$.store.book[0]book 数组的第一个元素$.store.book[*].titlebook 数组里每个元素的 title$..author递归查找所有 author 字段$.store.book[?(.price 10)]筛选 price 小于 10 的记录$.store.book[?(.category tech)]筛选 category 为 tech 的记录Python 里要用这个能力可以装jsonpath-ng库from jsonpath_ng import parse json_data { store: { book: [ {title: RAG实战, category: tech, price: 10}, {title: Agent入门, category: tech, price: 8}, {title: 小说集, category: fiction, price: 5} ] } } expr parse($.store.book[?(.category tech)]) matches expr.find(json_data) for match in matches: print(match.value[title])输出会是RAG实战和Agent入门。这种写法可读性高运维人员和研发同事也能一眼看懂过滤逻辑。5.2 RAG 元数据过滤的实战RAG 项目里的 JSONPath 通常不是直接用而是藏在各个检索组件的过滤语法里。比如 Elasticsearch 查询 DSL、OpenSearch 的 filter 部分写起来就是一个大的 JSON 对象{ query: { bool: { filter: [ {term: {tags: 入门}}, {range: {published_at: {gte: 2025-01-01}}} ] } } }不少同学第一次看到这段第一反应是“这么复杂”但如果你已经习惯了 JSONPath就会发现里面的逻辑几乎是相通的指定字段、指定操作符、指定值。term就是等于range就是区间过滤。我自己在项目里更常用的方式是先把所有知识库元数据读成 Python dict 的列表然后直接用 JSONPath 或列表推导式快速筛选出候选数据再决定要调用哪个检索通道。元数据量不大时这个做法比每次都连数据库还高效。5.3 什么时候不用 JSONPathJSONPath 不是万能钥匙。如果 JSON 结构的层级非常深而且你的业务逻辑需要肉眼逐层判断用普通 Python 循环反而更清晰。另外涉及多字段联合判断、需要聚合统计的场景JSONPath 也不擅长这时候把数据导入 SQLite 或直接用 pandas 处理会更顺手。性能上也要注意无脑递归扫描$..在大数组上会反复遍历整棵树。如果你要在一个几百 MB 的 JSON 里高频查找别指望 JSONPath 能做复杂优化该预处理就预处理该转数据库就转数据库。6. RAG 实战用 JSON 组织一份可检索的知识库6.1 一个自包含的小型知识库长什么样回到 RAG 场景。假设我们要做一个小型教程知识库内容不多但想完整走通 JSON 加载、切块、检索、回传的链路。我会先把知识库设计成一个 JSON 文件而不是一上来就上向量数据库。设计如下{ title: 第二周知识库, version: 1.0, chapters: [ { id: ch01, title: RAG是什么, tags: [入门], sections: [ {id: s01, heading: 定义, content: RAG 是检索增强生成先检索再生成。}, {id: s02, heading: 流程图, content: 用户问题先转向量再匹配知识库最后拼上下文。} ] }, { id: ch02, title: JSON基础, tags: [基础, 数据格式], sections: [ {id: s03, heading: 对象, content: JSON 对象用大括号包裹。}, {id: s04, heading: 数组, content: JSON 数组用中括号包裹。} ] } ] }每个 section 其实就可以看作一个 chunkid 唯一带上标题和标签作为元数据。这样设计的好处是后面切块、按标签过滤、按章节聚合都不需要额外处理。6.2 加载、切块、检索的代码示例下面这个示例我刻意没有引入重型的向量库用纯 Python 做“简易版检索”帮你理解 JSON 在整个流程里的位置。import json import math with open(knowledge_base.json, encodingutf-8) as f: kb json.load(f) # 拉平所有 section形成 chunk 列表 chunks [] for chapter in kb[chapters]: for section in chapter[sections]: chunks.append({ id: section[id], text: section[heading] section[content], tags: chapter[tags], chapter: chapter[title], }) # 简易打分计算重叠词作为相似度 def simple_score(query, text): words set(query) set(text) return len(words) query_text 什么是RAG query_chars list(query_text) scored [] for chunk in chunks: base_score simple_score(query_chars, list(chunk[text])) # 标签匹配额外加分 if 入门 in chunk[tags]: base_score 0.5 scored.append((base_score, chunk)) scored.sort(keylambda x: x[0], reverseTrue) top3 scored[:3] # 把检索结果序列化成给 LLM 的上下文 context json.dumps( [{id: c[id], text: c[text], score: s} for s, c in top3], ensure_asciiFalse, indent2, ) print(context)在这个简化版本里分数计算非常粗糙但链条是完整的JSON 文件 - Python 对象 - 切块 - 打分 - JSON 字符串回传给模型。你后面无论换词向量还是换向量库前面 JSON 加载和 chunks 的元数据形态都不用大改。很多新手会问为什么不直接用 LangChain 或者 LlamaIndex 的文档加载器因为在这个阶段手写一遍能让你看清“文档结构 - chunk 元数据 - 检索结果”这一路的 JSON 流动用了框架反而变成黑盒。6.3 进阶本体、GraphRAG 也在用 JSON如果你往后走会接触到一个叫“本体Ontology”的东西常见于企业级知识库。本体的定义文件很多就走 JSON-LD 或类似格式节点、边、属性都用 JSON 表示。GraphRAG 也类似图的节点和关系最终也要序列化通常逃不开 JSON 或 JSONL。这其实也解释了为什么热搜榜上总能看到“ontology rag”“graphrag llm wiki 本体 rag”这类词。它们看上去很高深但只要你 JSON 基础扎实读这些项目的配置文件、导入导出格式会明显更快进入状态。知识组织得越结构化检索的命中率通常也越稳定。7. Agent 实战JSON 完成工具调用闭环7.1 从用户输入到结构化参数的解析Agent 工具调用的核心闭环是用户输入 - 模型输出工具调用 JSON - 解析参数 - 执行工具 - 结果回填。先说前两步。假设你已经定义好get_weather工具你给模型发消息后有些框架返回的内容是这样的llm_output {name: get_weather, arguments: {\\city\\: \\上海\\, \\date\\: \\2026-04-12\\}}注意arguments的值本身也是一个 JSON 字符串所以你必须做两层解析import json tool_call json.loads(llm_output) # 第一次解析外层 args_text tool_call[arguments] # 取出内层字符串 args json.loads(args_text) # 第二次解析内层 print(args[city], args[date])很多线上报错都出在第二次解析上因为args_text里的转义符稍微出一个问题json.loads就直接炸了。所以我的习惯是所有从模型拿到的 JSON 文本解析时都包一层 try-except并用日志记录原始文本否则排错过程非常痛苦。7.2 工具执行结果回填给模型工具执行完之后不能直接把结果怼回对话里就完事要按模型 API 的约定格式回传。以 OpenAI 风格的协议为例工具结果通常是这样一条消息{ role: tool, tool_call_id: call_abc123, content: {\weather\:\晴\,\temperature\:24} }这个content也可以是普通字符串但我推荐只要工具返回的是结构化数据就继续用 JSON 字符串保留字段名和类型信息。模型第二次生成回答时能从这串 JSON 里拿到完整上下文。回填时你要重点小心一个场景工具执行本身抛异常。举例天气接口超时你直接返回System error给模型模型可能会顺着这句话编一个结果。更好的做法是把异常也序列化成 JSON 回传{ role: tool, tool_call_id: call_abc123, content: {\error\: \timeout\, \message\: \天气服务超时请稍后重试\} }然后让模型基于这个错误信息向用户解释。这样既不会中断对话也保留了纠错的余地。7.3 多轮记忆与 JSONL 日志Agent 的上下文不是每个请求都从零开始你需要把历史对话和工具结果串起来。轻量级项目里我习惯直接写 JSONL 文件{turn: 1, role: user, content: 上海明天适合跑步吗} {turn: 2, role: assistant, tool_calls: [{id: call_1, name: get_weather, arguments: {\city\:\上海\,\date\:\2026-04-12\}}]} {turn: 3, role: tool, tool_call_id: call_1, content: {\weather\:\晴\,\temperature\:24}} {turn: 4, role: assistant, content: 明天上海晴温度24度适合跑步。}每行一条 JSON按 turn 排序。调试时把文件回放一遍就能看出是哪一步出现了 JSON 解析错误、哪一步上下文被截断非常直观。写这个文件时注意两点一是追加写入用a模式别每次覆盖二是每条消息都要能独立解析不要因为中间某行脏数据影响整份日志加载。7.4 并发与状态写入的注意点有人问过“AI Agent 怎么扛并发”我的答案很简单先别急着加线程先把 JSON 层面的并发安全做好。如果你的 Agent 状态是写本地 JSON 文件多个进程同时json.dump同一个文件大概率会互相覆盖出现数据丢失。推荐做法是原子写先写入临时文件再os.replace覆盖原文件这样单次写入要么完全成功要么不落盘。import os import json def atomic_write(path, data): tmp_path path .tmp with open(tmp_path, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse) os.replace(tmp_path, path) # 原子替换真实线上环境优先把 Agent 状态放进 Redis 或数据库而不是本地文件。但如果你做的是教学 demo 或内部工具上面的原子写就够了。另外工具调用本身的并发问题更关键同一个工具重复执行会不会产生副作用比如扣款、发送消息这类操作在上游必须有幂等控制否则并发请求一多钱多扣了都不知道。8. 常见问题与排查经验实录8.1 一张表对照常见 JSON 报错我把 RAG 和 Agent 开发里高频出现的 JSON 报错整理成一张速查表报错现象常见原因建议处理JSONDecodeError: Expecting property name enclosed in double quotes字符串中了单引号或键没有引号确认字符串是双引号包裹JSONDecodeError: Expecting , delimiter手写时漏逗号或多了尾逗号用格式化工具检查JSONDecodeError: Extra data一个文件里塞了多个 JSON 对象改用逐行解析或先合并成数组TypeError: Object of type datetime is not JSON serializablePython 日期类型默认不能被序列化转 ISO 字符串或defaultstrcannot deserialize value of type java.util.date from str跨语言日期格式不匹配两端统一 ISO 8601并在 Java 端声明JsonFormatAgent execution terminated due to error.工具参数 JSON 解析失败或工具异常未捕获外层加 try-except记录原始模型输出中文显示成\uXXXXdumps没设ensure_asciiFalse序列化时显式指定这张表不能解决所有问题但能帮你把大部分问题定位到具体环节。尤其是“Extra data”很多人以为json.load能读多行 JSON实际不能JSONL 要用逐行读取。8.2 日期反序列化跨语言噩梦前面提到过 Java 端的日期反序列化报错我再展开讲一个我实际遇到过的案例。Python 侧脚本生成 JSONimport json from datetime import datetime data {user: admin, expired_at: datetime(2026, 12, 1, 10, 30, 0)} print(json.dumps(data, defaultstr)) # 输出 {user: admin, expired_at: 2026-12-01 10:30:00}Java 侧用 Jackson 反序列化到java.util.Date直接报cannot deserialize value of type java.util.Date from str。原因就是2026-12-01 10:30:00不是 ISO 8601 标准格式缺少T也没有时区信息Jackson 还能尝试解析但失败。这个问题可以这样彻底解决Python 端一律用datetime.now(timezone.utc).isoformat()输出类似2026-12-01T10:30:0000:00Java 端字段加JsonFormat(pattern yyyy-MM-ddTHH:mm:ssXXX)。两端格式对齐后这类问题基本绝迹。另外提醒一句JSON 本身不限定日期格式所以跨团队协作时接口文档里必须写明日期格式不要指望“默认能解析”。8.3 超大 JSON 与性能建议RAG 知识库动辄几百 MB如果全部一次性json.load()进内存机器很容易直接内存告警。我的三个建议第一用流式解析。Python 的ijson库支持迭代式解析大文件边读边处理不必把全部内容载入内存。虽然项目起步用不上但你迟早会遇到。第二离线预处理。大文件不要每次请求都解析提前把需要的字段抽出来缓存或者转成更高效的格式存库。线上 RAG 服务追求的是低延迟不是每次启动时重新解析一遍巨型 JSON。第三压缩传输。JSON 文本冗余度高用 gzip 压缩能减少大量网络消耗。如果是在 HTTP 接口间传大对象记得开启压缩。结尾很多人把 JSON 当“会了但没用”的基础实际上它才是 RAG 和 Agent 项目里承上启下的那根线。数据加载、切块元数据、检索上下文、工具调用参数、记忆持久化哪一环断掉整个系统都会停在原地。我个人体会是不要急着背一堆框架 API先把 JSON 读写和排错练熟遇到任何报错先看原始文本长什么样再想解法这个习惯比记住任何库都重要。最后分享一个实战细节我在每次 Agent 调试时都会把模型返回的原始 JSON 完整打日志并且打印之前不做截断。很多看起来莫名其妙、像“agent execution terminated due to error.”这样的错误真正原因往往就藏在原始 JSON 里某一个多余的反斜杠上。多看原始文本JSON 就会从“头疼”变成“顺手的工具”。